sasedev-knowledge/README.md

SaseDev Knowledge

SaseDev Knowledge est le workspace applicatif destiné à publier et administrer plusieurs familles de connaissance SaseDev sans transformer PGR en encyclopédie technique.

Le dépôt applicatif retenu est sasedev-knowledge. Le nom court du projet et le préfixe de crates sont knowledge.

Statut

La version courante est définie par VERSION.

0.0.1 est la première stable de fondation de SaseDev Knowledge. 0.0.2 est la stable du chemin Git générique de lecture, de l'autonomie normative locale et du cas d'usage partagé de synchronisation Changed / Unchanged. La release conserve les intégrations forge, PostgreSQL, écriture Git, auth/admin complète et formats éditoriaux finaux hors scope tant qu'une mission ultérieure ne les engage pas explicitement.

knowledge-git-lib implémente knowledge-git-api::GitRepository pour des sources physiques enregistrées : mirror contrôlé, refresh avec pruning, résolution d'une référence vers un commit et snapshot/worktree détaché adressé par révision. alpha.4 ne change pas cette sémantique. Les règles nécessaires au développement courant sont désormais possédées localement sous docs/rules/, et les futurs prompts Knowledge ne chargent pas PGR sauf réévaluation explicitement engagée. knowledge-app-lib compose maintenant refresh, résolution, comparaison avec la révision précédente et préparation de snapshot en un résultat explicite Changed / Unchanged, sans persister la dernière révision ni matérialiser de scheduler.

Topologie produit de fondation

Le workspace héberge trois applications Web Actix distinctes, correspondant aux trois façades publiques prévues :

knowledge-pgr-server       -> pgr.sasedev.com
knowledge-howtos-server    -> howtos.sasedev.com
knowledge-snippets-server  -> snippets.sasedev.com

Ces trois launchers restent minces et réutilisent les mêmes crates communes lorsqu'une responsabilité est réellement partagée. Leur séparation de processus ne transforme pas le domaine en microservices et n'autorise pas la duplication de logique métier.

Chaque famille possède au minimum sa propre source Git autoritaire : dépôt pgr, dépôt howtos et dépôt snippets. La configuration doit permettre d'ajouter d'autres sources sans figer le système à exactement trois repositories.

PostgreSQL est mutualisable et constitue la baseline retenue pour l'état transversal de la plateforme : comptes, sessions, propositions, synchronisation, index et relations entre familles. Il ne remplace jamais les sources Git comme vérité du contenu publié.

Chaque application Web doit pouvoir exposer sa propre surface d'administration protégée pour son domaine. Les chemins HTTP exacts ne sont pas encore figés. Une éventuelle quatrième application d'administration pourra agréger des fonctions transversales, mais elle ne remplacera pas les contrôles d'autorisation propres aux trois serveurs.

Le workspace Rust matérialise neuf packages : les trois frontières de fondation knowledge-domain-lib, knowledge-git-api et knowledge-sync-api, le backend knowledge-git-lib, la couche application partagée knowledge-app-lib, la composition Web knowledge-web-lib, puis les trois launchers knowledge-pgr-server, knowledge-howtos-server et knowledge-snippets-server. Les deux crates -api restent passives et indépendantes d'Actix, Gitea et PostgreSQL.

Frontend de référence et rendu Maud

Knowledge adopte le profil Web PGR comme partie obligatoire de la fondation. La stable 0.0.1 matérialise un package partagé de laboratoire sous Web/knowledge-template-lab/ avec npm, TypeScript strict, Vite, Sass et Bootstrap.

Ce package sert à développer, prévisualiser et valider les assets et templates statiques de référence indépendamment des serveurs Actix. Il n'est pas une quatrième application produit ni une UI de production.

Les templates statiques sont un harness de conception/validation, pas le moteur de rendu de production. Le markup runtime des trois applications est adapté en Maud par knowledge-web-lib. Le build Vite active un manifest et possède une entrée stable src/main.ts; knowledge-web-lib résout cette entrée vers les assets hashés en production et utilise le dev server configuré en développement. Les URL publiques finales et routes admin/login restent différées.

Le mécanisme observé dans actix-auth-app est documenté comme corpus technique à adapter, pas comme code autoritaire à copier.

La stable 0.0.1 matérialise knowledge-web-lib et les trois launchers knowledge-*-server. La bibliothèque commune possède le rendu Maud, la sélection dev-server/manifest Vite et le service des assets de production ; les trois main.rs ne contiennent que la sélection de façade et du nom de variable d'environnement de bind.

Le runtime exige un bind configuré par launcher et l'une des deux sources d'assets suivantes : KNOWLEDGE_VITE_DEV_ORIGIN en développement ou KNOWLEDGE_VITE_MANIFEST_PATH en production. KNOWLEDGE_ASSET_BASE_PATH peut remplacer le préfixe / de production. Aucune route admin/login n'est matérialisée à ce stade.

Invariants de fondation

• Git est la source autoritaire du contenu versionné.
• Une forge est une intégration optionnelle et ne constitue pas une dépendance du domaine.
• Les trois applications publiques sont déployables séparément mais composent des bibliothèques communes.
• PostgreSQL conserve l'état applicatif partagé et les projections ; il ne remplace pas Git comme vérité du contenu publié.
• Chaque serveur Web conserve une frontière d'administration protégée propre à son domaine, indépendamment d'une éventuelle façade d'administration transversale.
• La lecture publique doit pouvoir fonctionner depuis des copies Git locales et un index/cache applicatif sans appel à une forge pour chaque requête.
• PGR, HOWTOs, snippets et décisions project-local conservent des forces et responsabilités documentaires distinctes.
• Une proposition externe ne publie jamais directement du contenu et conserve la révision Git de base utilisée pour sa création.

Entrées principales

• RULES.md — point d'entrée normatif local ;
• ROADMAP.md — trajectoire macro engagée ;
• CHANGELOG.md — changements utiles par release ;
• docs/000-README.md — index documentaire ;
• docs/objectives/001-PROJECT_OBJECTIVES.md — objectifs et non-objectifs ;
• docs/architecture/001-PROJECT_PROFILE.md — baseline PGR, profils/skeletons et matrice de décisions ;
• docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md — architecture de fondation multi-app Git/forge/PostgreSQL et frontières de contenu ;
• docs/architecture/003-PGR_ADOPTION_MAP.md — mapping final de l'adoption PGR v0.1.3 vers les owners locaux Knowledge ;
• docs/rules/000-README.md — index des règles normatives locales autonomes ;
• docs/templates/001-NEW_SESSION_PROMPT.md — pattern de reprise d'une future session sans consultation PGR automatique ;
• docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md — étude des deux corpus historiques auth/admin et décisions de réutilisation conceptuelle ;
• docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md — étude ciblée du pattern Vite manifest / Actix / Maud à adapter pour Knowledge ;
• docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md — réconciliation beta.1, état matérialisé, DEFER conservés et revue d'horizon ;
• docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md — comparaison processus Git / gix / git2 et décision d'implémentation de lecture ;
• docs/plans/001-V0_0_1_FOUNDATION_PLAN.md — plan historique de la fondation stable 0.0.1 ;
• docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md — plan historique de la stable 0.0.2, gates et décisions de fermeture ;
• docs/validation/001-VALIDATION_MATRIX.md — matrice de validation ;
• prompts/001-V0_0_1_START_PROMPT.md — prompt de démarrage autoritaire de la release.
• prompts/002-V0_0_2_START_PROMPT.md — handoff historique exécuté pour ouvrir 0.0.2 depuis la stable v0.0.1 vérifiée.

Langue et nomenclature

Les noms de fichiers, crates, identifiants et code sont en anglais. La documentation normative et explicative principale est en français.