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.

0.0.3 est la stable du chemin Git générique complet en lecture et écriture contrôlée : lecture/snapshot, création d'un commit candidat isolé, mutations confinées, identité explicite puis push compare-and-exchange protégé par --force-with-lease contre l'état distant attendu. Une branche peut être créée uniquement lorsque son absence est attendue ; toute divergence devient un conflit récupérable sans écrasement silencieux. Cette stable reste provider-neutral et n'introduit ni forge obligatoire, ni PostgreSQL, ni rebase/merge automatique, ni workflow produit complet de proposition/publication.

0.0.4-alpha.1 ouvre la fondation PostgreSQL partagée sans code de persistance prématuré. L'étude de démarrage retient tokio-postgres comme driver PostgreSQL async natif, deadpool-postgres pour le pool et Refinery pour les migrations versionnées, sans ORM ni nouvelle crate -api. L'owner retenu pour l'implémentation est knowledge-store-postgres-lib, à matérialiser à partir d'alpha.2; le premier schéma est borné à la configuration logique des sources et à leur dernière révision synchronisée. Git reste autoritaire pour tout contenu publié.

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. La création locale du candidat d'alpha.3 reste séparée de cette sémantique de lecture. 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. 0.0.4-alpha.1 sélectionne tokio-postgres, deadpool-postgres, Refinery et une base logique partagée ; la bibliothèque de stockage recevra sa configuration de connexion depuis la composition et ne lira ni ne journalisera elle-même des secrets d'environnement. PostgreSQL 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.

La revue d'horizon de 0.0.3-beta.1 sépare désormais explicitement la construction produit des trois façades : fondation PostgreSQL partagée, modèles/projections de contenu, templates publics (dont pages de garde) pour PGR/HOWTOs/snippets, templates d'administration, intégration Actix Web et adaptation Maud des templates validés, puis workflow de gestion/proposition/revue/publication. Les templates restent d'abord développés et validés dans le laboratoire Web avant adaptation runtime en Maud ; cette trajectoire n'implémente encore aucune de ces phases pendant 0.0.3.

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/studies/006-V0_0_3_GIT_WRITE_STUDY.md — choix de la mission, stratégie de worktree d'écriture et invariants de push gardé ;
• docs/studies/007-V0_0_3_GIT_WRITE_RECONCILIATION.md — réconciliation beta du chemin Git d'écriture et revue d'horizon produit PGR/HOWTOs/snippets ;
• docs/studies/008-V0_0_4_POSTGRES_FOUNDATION_STUDY.md — étude de démarrage PostgreSQL, comparaison des clients/ORM, ownership, premier schéma, migrations et tests ;
• 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/plans/003-V0_0_3_GIT_WRITE_PLAN.md — plan historique de la stable 0.0.3, écriture Git contrôlée et push gardé ;
• docs/plans/004-V0_0_4_POSTGRES_FOUNDATION_PLAN.md — plan actif de la fondation PostgreSQL partagée ;
• 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.
• prompts/003-V0_0_3_START_PROMPT.md — prompt local de reprise de 0.0.3 depuis la stable v0.0.2 publiée et vérifiée.
• prompts/004-V0_0_4_START_PROMPT.md — handoff préparé pendant la stabilisation de 0.0.3 pour ouvrir la fondation PostgreSQL partagée après publication réelle de v0.0.3.

Langue et nomenclature

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