diff --git a/CHANGELOG.md b/CHANGELOG.md index 6622cc1..14e2785 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,5 @@ - + # Changelog SaseDev Knowledge @@ -18,7 +18,6 @@ Ce fichier décrit les changements utiles des releases publiées. Les détails d - introduit les premiers contrats provider-neutral de source, Git et synchronisation sans dépendance à une forge ni à PostgreSQL ; - active les audits Rust PGR de structure et de façade au moment où des API publiques réelles apparaissent ; - sélectionne localement `unit_tests/` hors de `src/` pour tous les tests unitaires Rust, avec `tests/` réservé aux tests d'intégration Cargo ; -- clôture la migration du layout de tests après normalisation rustfmt des deux `lib.rs` ayant fait échouer le premier `git diff --check` du fix précédent ; - fixe le frontend Web PGR comme laboratoire de validation des templates statiques et des assets avant adaptation du markup runtime en Maud ; - matérialise ce laboratoire sous `Web/knowledge-template-lab/` avec npm, TypeScript strict, Vite, Sass, Bootstrap et manifest Vite ; - retient l’intégration production Actix/Maud via le manifest Vite comme contrat d’asset mapping à réimplémenter proprement, sans copier mécaniquement le corpus historique ; diff --git a/Cargo.lock b/Cargo.lock index 8055ee9..540649e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -475,46 +475,46 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" [[package]] name = "knowledge-domain-lib" -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" [[package]] name = "knowledge-git-api" -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" dependencies = [ "knowledge-domain-lib", ] [[package]] name = "knowledge-howtos-server" -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" dependencies = [ "knowledge-web-lib", ] [[package]] name = "knowledge-pgr-server" -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" dependencies = [ "knowledge-web-lib", ] [[package]] name = "knowledge-snippets-server" -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" dependencies = [ "knowledge-web-lib", ] [[package]] name = "knowledge-sync-api" -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" dependencies = [ "knowledge-domain-lib", ] [[package]] name = "knowledge-web-lib" -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" dependencies = [ "actix-files", "actix-web", diff --git a/Cargo.toml b/Cargo.toml index 126c1a6..ca2a501 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ # file: Cargo.toml -# version: 11 +# version: 12 [workspace] resolver = "3" @@ -14,7 +14,7 @@ members = [ ] [workspace.package] -version = "0.0.1-alpha.5.fix.2" +version = "0.0.1-beta.1" edition = "2024" publish = false repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge" diff --git a/README.md b/README.md index 06ba4e9..280a03e 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # SaseDev Knowledge @@ -31,7 +31,7 @@ PostgreSQL est mutualisable et constitue la baseline retenue pour l'état transv 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 les trois frontières passives de fondation : `knowledge-domain-lib` pour les identités de famille/source, `knowledge-git-api` pour le contrat Git générique et `knowledge-sync-api` pour les signaux de synchronisation. Ces deux crates `-api` sont justifiées par des implémentations remplaçables ou multiples ; elles ne dépendent ni d'Actix, ni de Gitea, ni de PostgreSQL. +Le workspace Rust matérialise sept packages : les trois frontières de fondation `knowledge-domain-lib`, `knowledge-git-api` et `knowledge-sync-api`, la composition partagée `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 @@ -39,7 +39,7 @@ Knowledge adopte le profil Web PGR comme partie obligatoire de la fondation. `al 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 sera adapté en Maud. Le build Vite active un manifest et possède une entrée stable `src/main.ts` dont les assets hashés seront résolus plus tard par l'intégration Maud. Les URL publiques finales, routes admin/login et API Rust du loader restent différées jusqu'aux tranches serveur. +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. @@ -69,9 +69,11 @@ Le runtime exige un bind configuré par launcher et l'une des deux sources d'ass - [`docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md`](docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md) — architecture de fondation multi-app Git/forge/PostgreSQL et frontières de contenu ; - [`docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](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`](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`](docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md) — réconciliation `beta.1`, état matérialisé, DEFER conservés et revue d'horizon ; - [`docs/plans/001-V0_0_1_FOUNDATION_PLAN.md`](docs/plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan vivant de `0.0.1` ; - [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation ; - [`prompts/001-V0_0_1_START_PROMPT.md`](prompts/001-V0_0_1_START_PROMPT.md) — prompt de démarrage autoritaire de la release. +- [`prompts/002-V0_0_2_START_PROMPT.md`](prompts/002-V0_0_2_START_PROMPT.md) — handoff préparé pour `0.0.2`, exécutable uniquement après publication vérifiée de `0.0.1`. ## Langue et nomenclature diff --git a/ROADMAP.md b/ROADMAP.md index 4b1573c..3124eee 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap SaseDev Knowledge @@ -9,13 +9,17 @@ Statuts : `( )` planifié, `(x)` terminé, `(d)` différé, `(c)` annulé. ## Fondation -- `( ) 0.0.1` — fondation Knowledge : gouvernance PGR, workspace à trois applications Actix Web, architecture Git/forge/PostgreSQL partagé, frontières PGR/HOWTO/snippet, surfaces d'administration locales protégées, workspace Rust minimal, premiers contrats et baseline Web reproductible servant à valider templates/assets statiques avant adaptation Maud et intégration des assets via manifest Vite, sans implémentation fonctionnelle disproportionnée. +- `( ) 0.0.1` — fondation Knowledge : gouvernance PGR, workspace à trois applications Actix Web, architecture Git/forge/PostgreSQL partagé, frontières PGR/HOWTO/snippet, contrat d'administration locale protégée sans UI/auth complète, workspace Rust, premiers contrats, baseline Web reproductible, rendu Maud et intégration réelle du manifest Vite, sans implémentation métier disproportionnée. + +## Horizon engagé + +- `( ) 0.0.2` — implémentation Git générique et synchronisation de lecture : backend provider-neutral derrière `knowledge-git-api`, configuration de sources locales/remotes, matérialisation locale reproductible, refresh/résolution de révision, snapshot/worktree de lecture et convergence des déclencheurs explicite/périodique vers un même cas d'usage, sans API de forge obligatoire, écriture/publication Git, PostgreSQL ni format final HOWTO/snippet. ## Domaines futurs non numérotés Les thèmes suivants sont candidats à des releases ultérieures mais ne reçoivent pas encore de numéro : -- implémentation Git générique et synchronisation réelle multi-source ; +- écriture Git contrôlée, branches/propositions/rebase/push et workflow de publication ; - état PostgreSQL partagé et migrations applicatives ; - contribution/revue et administration ; - publication/rendu des trois façades ; @@ -24,4 +28,4 @@ Les thèmes suivants sont candidats à des releases ultérieures mais ne reçoiv - authentification/autorisation complète ; - déploiement et opérations multi-domaines. -Une revue d'horizon pendant `0.0.1` décidera si une prochaine version doit être engagée. Aucun numéro n'est inventé uniquement pour prolonger la roadmap. +La revue d'horizon `0.0.1-beta.1` engage uniquement `0.0.2`. Les autres thèmes restent volontairement non numérotés jusqu'à ce qu'un scope et un ordre réellement utiles soient décidés. diff --git a/VERSION b/VERSION index f207228..7390193 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.1-alpha.5.fix.2 +0.0.1-beta.1 diff --git a/deltas/0.0.1/beta.1.md b/deltas/0.0.1/beta.1.md new file mode 100644 index 0000000..b27f47c --- /dev/null +++ b/deltas/0.0.1/beta.1.md @@ -0,0 +1,100 @@ + + + +# Delta 0.0.1-beta.1 — réconciliation de fondation et revue d'horizon + +## Base requise + +État `0.0.1-alpha.5.fix.2` committé et poussé après application du history : + +```text +history/0.0.1/alpha.5.fix.2.md = PASS +``` + +La version devient : + +```text +0.0.1-beta.1 +``` + +## Nature de la tranche + +`beta.1` est une tranche de stabilisation et de réconciliation. + +Elle n'ajoute aucune grande fonctionnalité. + +Aucune crate, dépendance, route, migration, implémentation Git ou fonctionnalité admin n'est introduite. + +## Réconciliation + +La tranche corrige les formulations durables devenues obsolètes après les alphas : + +- owners Web désormais associés aux tranches effectivement matérialisées ; +- launchers documentés comme existants depuis `alpha.5` ; +- `knowledge-web-lib` retirée des crates candidates ; +- intégration manifest Vite/Maud documentée comme implémentée ; +- README aligné sur les sept packages réels ; +- changelog débarrassé d'un détail interne de fix rustfmt. + +L'étude : + +```text +docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md +``` + +possède l'état réconcilié et la revue d'horizon. + +## Revue d'horizon + +Une seule prochaine release est engagée : + +```text +0.0.2 — Git générique et synchronisation de lecture +``` + +Aucun numéro après `0.0.2` n'est réservé. + +Le prompt : + +```text +prompts/002-V0_0_2_START_PROMPT.md +``` + +est préparé comme handoff, mais il est explicitement non exécutable avant la stable `0.0.1`, son tag et son rapport post-tag `PASS`. + +## Fichiers remplacés + +```text +VERSION +Cargo.toml +README.md +CHANGELOG.md +ROADMAP.md +docs/000-README.md +docs/architecture/001-PROJECT_PROFILE.md +docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +docs/plans/001-V0_0_1_FOUNDATION_PLAN.md +docs/validation/001-VALIDATION_MATRIX.md +``` + +## Fichiers ajoutés + +```text +docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md +prompts/002-V0_0_2_START_PROMPT.md +deltas/0.0.1/beta.1.md +``` + +Aucun fichier n'est supprimé. + +## Lockfiles + +Le delta ne préfabrique ni `Cargo.lock` ni `package-lock.json`. + +Le bump de version Cargo peut modifier `Cargo.lock` dans le workspace opérateur. `package-lock.json` ne devrait pas changer puisque le graphe npm reste identique. + +## Gate + +La gate beta doit réconcilier documentation, structure, Rust, Web, manifest et smokes HTTP. + +Ne pas committe `beta.1` avant production de son history à partir des résultats opérateur. diff --git a/docs/000-README.md b/docs/000-README.md index cf706bf..78993bd 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation SaseDev Knowledge @@ -16,6 +16,7 @@ - [`studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](studies/001-AUTH_ADMIN_CORPUS_STUDY.md) — analyse des fonctionnalités auth/admin présentes ou seulement préparées dans deux archives historiques inachevées. - [`studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md`](studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md) — analyse du pattern Vite manifest / Actix / Maud de `actix-auth-app` et contrat de reprise ciblée pour Knowledge. +- [`studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md`](studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md) — réconciliation beta de la fondation, DEFER conservés et revue d'horizon engageant uniquement `0.0.2`. ## Plans @@ -26,3 +27,7 @@ - [`validation/001-VALIDATION_MATRIX.md`](validation/001-VALIDATION_MATRIX.md) — preuves proportionnées par scope. Les deltas et histories sont des artefacts de workflow, pas des substituts à cette documentation durable. + +## Handoff + +- [`../prompts/002-V0_0_2_START_PROMPT.md`](../prompts/002-V0_0_2_START_PROMPT.md) — prompt de reprise préparé pour `0.0.2`, non exécutable avant publication et vérification post-tag de `0.0.1`. diff --git a/docs/architecture/001-PROJECT_PROFILE.md b/docs/architecture/001-PROJECT_PROFILE.md index 3f7d50c..69589f7 100644 --- a/docs/architecture/001-PROJECT_PROFILE.md +++ b/docs/architecture/001-PROJECT_PROFILE.md @@ -1,5 +1,5 @@ - + # Profil du projet Knowledge @@ -39,16 +39,16 @@ Le prompt de démarrage exige néanmoins une matrice `ADOPT / KEEP-LOCAL / OVERR | `300-DOCUMENTATION` | `ADOPT` | `alpha.1` | rôles documentaires et taxonomie utile | | `400-VALIDATION` | `ADOPT` | `alpha.1` | preuves proportionnées et autorité opérateur | | `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | `alpha.2+` | backend Rust/workspace Cargo contrôlé | -| `530-TYPESCRIPT` | `ADOPT` | tranche Web | frontend durable TypeScript | -| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | tranche Web | package manager/lockfile/scripts explicites | -| `550-VITE` | `ADOPT` puisque Vite est retenu | tranche Web | dev server/build/cache/outputs | -| `560-CSS_SASS` | `ADOPT` | tranche Web | CSS/Sass et outputs | -| `700-FRAMEWORKS` | `ADOPT` | avec Actix/Maud | cadre générique des frameworks | +| `530-TYPESCRIPT` | `ADOPT` | `alpha.4` | frontend durable TypeScript | +| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | `alpha.4` | package manager/lockfile/scripts explicites | +| `550-VITE` | `ADOPT` puisque Vite est retenu | `alpha.4` | dev server/build/cache/outputs | +| `560-CSS_SASS` | `ADOPT` | `alpha.4` | CSS/Sass et outputs | +| `700-FRAMEWORKS` | `ADOPT` | `alpha.5` | cadre générique des frameworks | | `710-TAURI` | `DEFER` / non applicable | hors `0.0.1` | aucun host desktop/mobile Tauri | | skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` | `alpha.1` | fondation locale PGR | | skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` | `alpha.2` | workspace Rust contrôlé | -| skeleton `003-WEB_FRONTEND` | `ADOPT` | tranche Web | frontend indépendant du host | -| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | tranche Web | restore/typecheck/build/smoke proportionnés | +| skeleton `003-WEB_FRONTEND` | `ADOPT` | `alpha.4` | frontend indépendant du host | +| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | `alpha.4+` | restore/typecheck/build/smoke proportionnés | Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont pas sélectionnés. @@ -79,7 +79,7 @@ Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont p | Bootstrap | `KEEP-LOCAL` | framework CSS retenu pour les templates de référence et le rendu Maud ; jamais règle PGR universelle | | Racine(s) frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` pour les références statiques et assets communs | | Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; le markup runtime est adapté et servi par Maud | -| Intégration manifest Vite / Maud | `KEEP-LOCAL` | mapping d’assets hashés requis en production ; API Rust exacte différée jusqu’à la composition serveur | +| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` en `alpha.5`, avec dev-origin/manifest/base-path configurables | | Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle | | Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel | | Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré | @@ -94,7 +94,7 @@ Aucun `OVERRIDE` n'est requis à ce stade. La sélection Web `alpha.4` conserve une seule baseline partagée tant qu'aucune divergence réelle entre les trois façades ne justifie plusieurs packages. Les entrées spécifiques pourront être ajoutées dans ce package avant toute duplication de toolchain. -## Nomenclature de crates candidate +## Nomenclature de crates Les trois packages exécutables sont des boundaries produit retenus : @@ -104,7 +104,7 @@ knowledge-howtos-server launcher Actix Web de la façade HOWTOs knowledge-snippets-server launcher Actix Web de la façade snippets ``` -Ils ne sont pas encore matérialisés en `alpha.3`. Lorsqu'ils le seront, leurs `main.rs` resteront minces et composeront les bibliothèques réutilisables. Chacun doit pouvoir protéger sa propre surface d'administration métier. +Ils sont matérialisés depuis `alpha.5`. Leurs `main.rs` restent minces et délèguent à `knowledge-web-lib`. Chacun conserve le contrat de pouvoir protéger sa propre surface d'administration métier lorsque cette surface sera implémentée. Les responsabilités matérialisées sont : @@ -112,6 +112,10 @@ Les responsabilités matérialisées sont : knowledge-domain-lib types métier stables de famille/source ; aucune dépendance Actix/Git-provider/forge/PostgreSQL knowledge-git-api contrat passif GitRepository ; implémentations génériques remplaçables derrière cette frontière knowledge-sync-api contrat passif RepositoryEventSource et signaux de réconciliation ; plusieurs mécanismes producteurs prévus +knowledge-web-lib composition Actix/Maud partagée, résolution Vite dev/manifest et service des assets +knowledge-pgr-server launcher PGR mince +knowledge-howtos-server launcher HOWTOs mince +knowledge-snippets-server launcher snippets mince ``` Les responsabilités suivantes restent candidates et ne deviennent des packages que lorsqu'elles possèdent un ownership réel : @@ -121,7 +125,6 @@ knowledge-app-lib orchestration des use cases transversaux, si la s knowledge-git-lib implémentation Git générique de knowledge-git-api knowledge-store-postgres-lib état applicatif PostgreSQL partagé knowledge-forge-gitea-lib adapter Gitea optionnel -knowledge-web-lib composition Web réellement partagée, seulement si les trois serveurs dupliqueraient sinon du code knowledge-logging-lib diagnostics partagés, seulement lorsque plusieurs runtimes en ont effectivement besoin ``` @@ -148,4 +151,8 @@ Elles ne justifient pas encore de créer une crate auth, de figer `/admin` ou `/ ## Décisions à rouvrir -Les `DEFER` sont réexaminés dans la tranche qui consomme réellement la décision. Un changement de scope produit, l'ajout d'un host natif ou une contrainte externe peut déclencher un REPLAN ; il ne justifie pas un choix anticipé dans `alpha.1.fix.1`. +La réconciliation `beta.1` confirme que les `DEFER` suivants restent légitimes : adapter Gitea, driver/migrations PostgreSQL, moteur de recherche, fournisseur d'identité externe, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet et noms de crates non encore possédés par une responsabilité réelle. + +La prochaine release engagée `0.0.2` rouvre uniquement l'implémentation Git générique et la synchronisation réelle de lecture. Elle ne lève aucun des `DEFER` ci-dessus par elle-même. + +Un changement de scope produit, l'ajout d'un host natif ou une contrainte externe peut déclencher un REPLAN ; il ne justifie pas un choix anticipé. diff --git a/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md b/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md index 230dbc3..fe6348d 100644 --- a/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +++ b/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md @@ -1,5 +1,5 @@ - + # Architecture de fondation Knowledge @@ -23,8 +23,19 @@ knowledge-git-api GitRepository provider-neutral knowledge-sync-api RepositoryEventSource et signal de réconciliation ``` +`alpha.5` complète la fondation avec : + +```text +knowledge-web-lib composition Actix/Maud et assets Vite +knowledge-pgr-server launcher PGR +knowledge-howtos-server launcher HOWTOs +knowledge-snippets-server launcher snippets +``` + Les deux crates `-api` sont justifiées par des implémentations réellement remplaçables ou multiples. Elles restent sans runtime, sans logging propre et sans dépendance à Actix, Gitea ou PostgreSQL. +Les tests unitaires Rust sont désormais placés hors de `src/` sous `unit_tests/`, conformément à la convention locale Knowledge sélectionnée sur l'option permise par PGR. + Le workspace est une application déployable à train de release unique ; `Cargo.lock` est donc versionné pour conserver la résolution effectivement vérifiée. Les artefacts Cargo sont dirigés hors du dépôt vers `../builds/sasedev-knowledge/target/`. ## Vue de responsabilités @@ -270,6 +281,18 @@ En particulier, Knowledge ne doit pas hériter mécaniquement : Les trois packages `knowledge-pgr-server`, `knowledge-howtos-server` et `knowledge-snippets-server` sont des launchers minces : chacun sélectionne `ServerSite` et le nom de sa variable de bind, puis délègue au runtime commun. Ils ne possèdent aucune logique de rendu ou de manifest dupliquée. +## Réconciliation `0.0.1-beta.1` + +La fondation matérialisée est cohérente avec les objectifs `0.0.1` : + +- trois launchers séparés, sans duplication de runtime ; +- Git encore contractuel et provider-neutral, sans adapter de forge ; +- synchronisation encore contractuelle, sans worker artificiel ; +- frontend de référence indépendant et rendu runtime Maud effectivement relié au manifest Vite ; +- aucune persistance PostgreSQL, auth complète, UI admin complète, forge spécifique ou format final HOWTO/snippet introduit par anticipation. + +Les prochaines capacités sont donc reprises par releases séparées. `0.0.2` engage uniquement le chemin Git générique de lecture et la synchronisation réelle ; les autres axes restent différés. + ## 10. Administration L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité. diff --git a/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md b/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md index fd45a95..3a0919c 100644 --- a/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md +++ b/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md @@ -1,5 +1,5 @@ - + # Plan 0.0.1 — fondation SaseDev Knowledge @@ -221,9 +221,31 @@ Le snapshot `alpha.5.fix.1` committé après history contient donc déjà la nor ### beta.1 — réconciliation de fondation -Rejouer les gates pertinentes, réconcilier docs/architecture avec ce qui existe réellement, traiter les décisions devenues nécessaires et effectuer la revue d'horizon. +Réconcilier la fondation réellement matérialisée sans expansion fonctionnelle. -Aucune nouvelle grande fonctionnalité ne doit être introduite en beta par défaut. +La tranche doit : + +- confirmer les sept packages Rust et le package Web de référence ; +- corriger les formulations documentaires devenues obsolètes après `alpha.4`/`alpha.5` ; +- confirmer que `knowledge-git-api` et `knowledge-sync-api` restent passifs ; +- confirmer le layout `unit_tests/` comme convention locale ; +- confirmer que PostgreSQL, forge, auth/admin complète, formats finaux et workflow d'écriture restent différés ; +- réaliser la revue d'horizon ; +- préparer un handoff uniquement si une prochaine mission est suffisamment décidée. + +La revue d'horizon engage uniquement : + +```text +0.0.2 — Git générique et synchronisation de lecture +``` + +Aucun numéro ultérieur n'est réservé. + +La mission et ses non-objectifs sont possédés par `../studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md`. + +Le prompt `../../prompts/002-V0_0_2_START_PROMPT.md` est préparé mais reste bloqué jusqu'à publication stable et rapport post-tag `PASS` de `0.0.1`. + +Aucun nouveau crate runtime, contrat métier, dépendance, route, schéma SQL ou comportement Git n'entre dans `beta.1`. ### rc.1 — candidate stable @@ -259,7 +281,13 @@ REPLAN obligatoire si : ## Revue d'horizon -- état : requise en `beta.1` ; -- raison : aucune version après `0.0.1` n'est suffisamment cadrée pour être réservée aujourd'hui ; -- sorties autorisées : engager une prochaine version avec mission réelle, laisser l'horizon ouvert ou différer la suite ; -- interdiction : fabriquer un numéro uniquement pour satisfaire une cadence documentaire. +État à l'entrée de `beta.1` : **instruite par la tranche, en attente de gate opérateur**. + +Décision matérialisée : + +- engager `0.0.2` pour l'implémentation Git générique et la synchronisation réelle de lecture ; +- ne réserver aucun numéro après `0.0.2` ; +- conserver PostgreSQL, parsing/index, propositions/admin/auth, forge et publication en domaines futurs non numérotés ; +- préparer le prompt `002-V0_0_2_START_PROMPT.md`, exécutable seulement après publication vérifiée de `0.0.1`. + +La revue complète et les critères de reprise sont possédés par `../studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md`. diff --git a/docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md b/docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md new file mode 100644 index 0000000..224d82e --- /dev/null +++ b/docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md @@ -0,0 +1,177 @@ + + + +# Réconciliation de fondation et revue d'horizon 0.0.1 + +## Objet + +Cette étude appartient à `0.0.1-beta.1`. + +Elle réconcilie les objectifs de fondation, l'architecture réellement matérialisée après les tranches alpha, les décisions différées et l'horizon de roadmap. + +Elle ne crée aucune fonctionnalité runtime. + +## Baseline de gouvernance + +La fondation reste gouvernée par PGR stable `v0.1.1`, vérifiée au démarrage de `0.0.1`. + +Aucun `OVERRIDE` PGR n'a été nécessaire. + +Knowledge a sélectionné localement une convention plus stricte pour les tests unitaires Rust : `unit_tests/` séparé de `src/`, avec `tests/` réservé aux tests d'intégration Cargo. Cette sélection reste compatible avec le `MAY` générique de PGR `0.1.1`. + +## État matérialisé + +### Workspace Rust + +Sept packages existent : + +```text +knowledge-domain-lib +knowledge-git-api +knowledge-sync-api +knowledge-web-lib +knowledge-pgr-server +knowledge-howtos-server +knowledge-snippets-server +``` + +Les trois launchers sont des unités de déploiement distinctes. + +`knowledge-web-lib` possède la composition Actix/Maud réellement partagée. + +`knowledge-git-api` et `knowledge-sync-api` restent des frontières passives, sans implémentation provider/forge/persistence. + +### Web + +Le package : + +```text +Web/knowledge-template-lab/ +``` + +possède npm, lockfile versionné, TypeScript strict, Vite, Sass et Bootstrap. + +Le build produit un manifest avec l'entrée stable : + +```text +src/main.ts +``` + +`knowledge-web-lib` consomme réellement ce contrat : + +- dev : `KNOWLEDGE_VITE_DEV_ORIGIN` ; +- production : `KNOWLEDGE_VITE_MANIFEST_PATH` ; +- préfixe : `KNOWLEDGE_ASSET_BASE_PATH`. + +Les trois launchers reçoivent leur bind via configuration. + +### Tests + +Les tests unitaires sont hors de `src/` sous `unit_tests/`. + +L'audit `audit_rust_test_layout.py` empêche le retour du layout historique. + +Les tests d'intégration Cargo futurs restent propriétaires de `tests/`. + +## Décisions de fondation confirmées + +| Domaine | Décision beta | +|-----------------------------------------------|-----------------------------------------| +| Git autoritaire pour le contenu publié | `CONFIRM` | +| forge optionnelle | `CONFIRM` | +| plusieurs sources Git possibles par famille | `CONFIRM` | +| trois launchers Web séparés | `CONFIRM` | +| logique Web partagée dans `knowledge-web-lib` | `CONFIRM` | +| PostgreSQL logique partagé pour l'état futur | `CONFIRM`, non matérialisé | +| templates statiques comme laboratoire | `CONFIRM` | +| Maud comme rendu runtime actuel | `CONFIRM` | +| manifest Vite comme mapping production | `CONFIRM` | +| surfaces admin protégées localement | `CONFIRM` comme contrat, non implémenté | +| quatrième admin app | `DEFER` | +| Gitea | `DEFER` | +| formats finaux HOWTO/snippet | `DEFER` | + +## DEFER conservés + +Les choix suivants ne sont pas devenus nécessaires pendant `0.0.1` : + +- adapter Gitea ou autre forge ; +- driver/ORM PostgreSQL ; +- migrations PostgreSQL ; +- moteur de recherche externe ; +- fournisseur d'identité externe ; +- modèle final de rôles/capabilities ; +- routes admin/login ; +- quatrième application d'administration ; +- formats finaux HOWTO/snippet ; +- workflow complet de propositions ; +- écriture Git, branches de proposition, rebase/merge/push ; +- déploiement multi-domaines de production. + +Les maintenir différés réduit le couplage et ne bloque aucune preuve de fondation. + +## Incohérences documentaires corrigées en beta + +La réconciliation corrige les formulations historiques devenues obsolètes : + +- owners Web encore indiqués comme « tranche Web » alors qu'ils ont été matérialisés en `alpha.4` ; +- launchers décrits comme non matérialisés alors qu'ils existent depuis `alpha.5` ; +- `knowledge-web-lib` encore listée comme crate candidate ; +- API du loader Vite encore décrite comme différée alors qu'elle est maintenant possédée par `knowledge-web-lib`. + +Les références aux tranches alpha restent autorisées lorsqu'elles expliquent l'historique réel, mais ne doivent plus contredire l'état courant. + +## Revue d'horizon + +La fondation possède maintenant assez de contrats pour engager une seule prochaine release sans inventer le reste de la trajectoire. + +### Release engagée + +```text +0.0.2 — Git générique et synchronisation de lecture +``` + +Mission : + +- matérialiser une implémentation provider-neutral derrière `knowledge-git-api` ; +- gérer des sources Git locales et remotes génériques ; +- maintenir une matérialisation locale contrôlée ; +- rafraîchir/fetcher lorsque nécessaire ; +- résoudre une référence vers une révision autoritaire ; +- exposer un snapshot/worktree de lecture déterministe aux futurs parseurs ; +- faire converger déclenchement explicite et périodique vers un même cas d'usage de synchronisation ; +- détecter le changement de révision sans dépendre d'une forge. + +Non-objectifs de `0.0.2` : + +- pull/merge requests ou webhooks forge-specific ; +- publication Git en écriture ; +- workflow complet de propositions ; +- PostgreSQL ; +- parsing final HOWTO/snippet ; +- recherche ; +- auth/admin ; +- déploiement production. + +Le choix technique d'implémentation Git — processus `git`, `gix`, autre crate ou combinaison justifiée — reste à étudier au démarrage de `0.0.2`. La mission est décidée, pas la bibliothèque. + +### Horizon laissé ouvert + +Aucun numéro n'est réservé après `0.0.2`. + +Les thèmes PostgreSQL, parsing/index, propositions/admin/auth, forge et publication seront ordonnés après retour réel du chemin Git/synchronisation. + +## Handoff + +`prompts/002-V0_0_2_START_PROMPT.md` prépare la reprise. + +Il ne devient exécutable qu'après : + +```text +0.0.1 rel.N PASS +commit produit 0.0.1 +tag v0.0.1 publié +rapport post-tag Knowledge PASS +``` + +Si la publication stable révèle un défaut, le handoff `0.0.2` reste bloqué jusqu'à résolution. diff --git a/docs/validation/001-VALIDATION_MATRIX.md b/docs/validation/001-VALIDATION_MATRIX.md index 604e8d7..328a0d1 100644 --- a/docs/validation/001-VALIDATION_MATRIX.md +++ b/docs/validation/001-VALIDATION_MATRIX.md @@ -1,5 +1,5 @@ - + # Matrice de validation Knowledge @@ -381,3 +381,27 @@ Le second fix de clôture doit prouver : - smoke HTTP de `knowledge-pgr-server`, `knowledge-howtos-server` et `knowledge-snippets-server` `PASS` ; - aucune modification fonctionnelle du runtime Actix/Maud/Vite ; - `git diff --cached --check` propre. + +## Gate de `0.0.1-beta.1` + +La réconciliation beta doit prouver : + +- `VERSION = 0.0.1-beta.1` et version workspace identique ; +- history `alpha.5.fix.2` `PASS` committé avant application de beta ; +- aucun nouveau package Cargo, package npm ou comportement runtime introduit ; +- workspace Cargo toujours composé exactement de sept packages ; +- `knowledge-web-lib` et les trois launchers documentés comme matérialisés ; +- aucune formulation durable ne décrit encore `knowledge-web-lib` comme candidate ou les launchers comme non matérialisés ; +- owners Web PGR réconciliés avec `alpha.4`/`alpha.5` ; +- `unit_tests/` confirmé comme convention locale et audit associé toujours propre ; +- étude `003-V0_0_1_FOUNDATION_RECONCILIATION.md` présente ; +- roadmap engage uniquement `0.0.2` et ne réserve aucun numéro supplémentaire ; +- prompt `002-V0_0_2_START_PROMPT.md` présent et explicitement bloqué jusqu'au post-tag `0.0.1 PASS` ; +- DEFER PostgreSQL/forge/auth/admin/formats finaux conservés ; +- `CHANGELOG.md` ne contient plus le détail interne du fix rustfmt comme changement utilisateur ; +- audits Markdown headers/tables/links propres ; +- `cargo fmt --check`, audits Rust, `cargo check`, Clippy strict et tests workspace propres ; +- baseline Web `npm ci`, typecheck et build propre ; +- manifest Vite parsable ; +- smoke HTTP des trois launchers propre ; +- `git diff --cached --check` propre. diff --git a/history/0.0.1/beta.1.md b/history/0.0.1/beta.1.md new file mode 100644 index 0000000..401c291 --- /dev/null +++ b/history/0.0.1/beta.1.md @@ -0,0 +1,184 @@ + + + +# History 0.0.1-beta.1 — réconciliation de fondation et revue d'horizon + +## Statut + +PASS + +La gate opérateur de `0.0.1-beta.1` exécutée le `2026-09-28` est propre. + +## Baseline opérateur + +`alpha.5.fix.2` `PASS` a été historisé, committé et poussé avant application de `beta.1` : + +```text +history/0.0.1/alpha.5.fix.2.md = PASS +commit 515f815 +message 0.0.1-alpha.5.fix.2 +branch master +push origin/master PASS +status clean après push +``` + +Une première tentative de push a reçu une saisie parasite dans le prompt d'authentification. La commande a été rejouée immédiatement et le push réel a avancé `origin/master` de `a1b56af` à `515f815`. Cet incident de saisie n'affecte pas la baseline. + +## Contrôles initiaux + +Les preuves suivantes passent immédiatement après application du delta : + +```text +VERSION = 0.0.1-beta.1 +git diff --check PASS +cargo fmt --all -- --check PASS +aucun diff sous crates/ ou Web/ PASS +``` + +La tranche reste donc documentaire et de réconciliation comme annoncé. + +## Réconciliation structurelle + +La gate affiche : + +```text +Knowledge 0.0.1-beta.1 reconciliation audit: clean +``` + +Elle confirme : + +- exactement sept packages Cargo ; +- présence de `docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md` ; +- présence de `prompts/002-V0_0_2_START_PROMPT.md` ; +- roadmap engageant `0.0.2` sans réserver `0.0.3` ; +- suppression des formulations durables devenues obsolètes ; +- absence de crates Git/PostgreSQL/Gitea ou migrations anticipées ; +- handoff `0.0.2` explicitement bloqué jusqu'au rapport post-tag `0.0.1 PASS`. + +## Audits Markdown PGR + +Les audits propriétaires du checkout PGR voisin passent : + +```text +Markdown header audit: clean (29 file(s)) +Markdown table audit: clean (4 table(s), 29 file(s)) +Markdown link audit: clean (28 local link(s), 29 file(s)) +``` + +## Audits Rust + +Les audits sélectionnés passent : + +```text +Rust test-layout audit: clean (7 crate(s)) +Rust blank-line audit: clean (18 file(s)) +Rust item-spacing audit: clean (18 file(s)) +Rust module-order audit: clean (18 file(s)) +Rust trait-import-block audit: clean (18 file(s)) +Rust re-export-block audit: clean (18 file(s)) +Rust export completeness audit: 0 candidate(s) across 7 package(s) +``` + +## Cargo, Clippy et tests + +Les sept packages compilent en version `0.0.1-beta.1`. + +```text +cargo check --workspace PASS +cargo clippy --workspace --all-targets --all-features + -- -D warnings PASS +cargo test --workspace --all-targets --all-features PASS +``` + +Tests observés : + +```text +knowledge-domain-lib : 3 PASS +knowledge-git-api : 1 PASS +knowledge-sync-api : 1 PASS +knowledge-web-lib : 4 PASS +launchers : 0 test chacun +``` + +## Baseline Web + +Les commandes suivantes passent : + +```text +npm ci +npm run typecheck +npm run build +``` + +npm observe toujours `@parcel/watcher@2.6.0` comme package avec script d'installation non approuvé. Cette observation reste non bloquante et aucune approbation automatique n'est effectuée. + +Les warnings Sass proviennent de Bootstrap et restent non bloquants. + +## Manifest Vite + +L'audit passe : + +```text +Knowledge 0.0.1-beta.1 Vite manifest audit: clean +``` + +avec : + +```text +JS assets/assets/main-BMHcm6u9.js +CSS assets/main-V0IwlRbh.css +``` + +## Smokes HTTP + +Les trois launchers passent : + +```text +knowledge-pgr-server smoke PASS +knowledge-howtos-server smoke PASS +knowledge-snippets-server smoke PASS +Knowledge 0.0.1-beta.1 HTTP smoke: clean +``` + +## Hygiène Git + +Le contrôle final passe : + +```text +git diff --cached --check = PASS +``` + +Le staging observé avant ajout du présent history est : + +```text +M CHANGELOG.md +M Cargo.lock +M Cargo.toml +M README.md +M ROADMAP.md +M VERSION +A deltas/0.0.1/beta.1.md +M docs/000-README.md +M docs/architecture/001-PROJECT_PROFILE.md +M docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +M docs/plans/001-V0_0_1_FOUNDATION_PLAN.md +A docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md +M docs/validation/001-VALIDATION_MATRIX.md +A prompts/002-V0_0_2_START_PROMPT.md +``` + +Un caractère Unicode parasite a ensuite été soumis comme commande shell et rejeté par Bash. Il survient après le contrôle d'hygiène et le statut attendu ; il ne modifie pas le workspace et n'affecte pas la gate. + +## Décision + +`0.0.1-beta.1` est `PASS`. + +La fondation est réconciliée et l'horizon est décidé sans expansion prématurée. + +La transition autorisée est : + +```text +0.0.1-rc.1 +``` + +La RC doit geler le scope, vérifier l'intégrité de tous les histories `0.0.1`, conserver le changelog candidat et le handoff `0.0.2`, puis rejouer la gate complète avant toute promotion stable. diff --git a/prompts/002-V0_0_2_START_PROMPT.md b/prompts/002-V0_0_2_START_PROMPT.md new file mode 100644 index 0000000..e983f51 --- /dev/null +++ b/prompts/002-V0_0_2_START_PROMPT.md @@ -0,0 +1,172 @@ + + + +# Knowledge 0.0.2 — prompt de démarrage + +## Condition d'utilisation + +Ce prompt est préparé pendant `0.0.1-beta.1`. + +Il ne doit être exécuté qu'après publication complète de `0.0.1` : + +```text +history rel.N réellement PASS +commit produit 0.0.1 +tag stable v0.0.1 publié +rapport post-tag sasedev-knowledge-0.0.1-publish.001-report.md = PASS +``` + +Si l'une de ces preuves manque, rester sur la fermeture de `0.0.1`. + +## Baseline autoritaire + +Partir de l'archive téléchargée depuis le tag stable Knowledge `v0.0.1` et du rapport post-tag correspondant. + +Ne pas reconstruire la baseline depuis un workspace local non vérifié ou une conversation précédente. + +La fondation `0.0.1` a été construite avec PGR stable `v0.1.1`. Au démarrage de `0.0.2`, vérifier la stable PGR courante. Si une stable PGR plus récente existe et doit être adoptée, établir explicitement le mapping d'adoption avant l'implémentation ; ne pas modifier silencieusement les règles locales. + +## Mission + +`0.0.2` matérialise le premier chemin Git générique réel et la synchronisation de lecture. + +La release doit implémenter, derrière les contrats existants, la capacité de partir d'une source Git locale ou d'un remote Git générique, maintenir une copie locale contrôlée, rafraîchir la source, résoudre une référence vers une révision et fournir un snapshot/worktree déterministe utilisable par les futurs parseurs. + +La forge reste optionnelle. + +## Contrats existants à préserver + +Réutiliser les owners de `0.0.1` : + +```text +knowledge-domain-lib +knowledge-git-api +knowledge-sync-api +``` + +Ne pas remplacer `GitRepository` ou `RepositoryEventSource` par des types Gitea/GitHub/GitLab. + +Étendre un contrat seulement lorsqu'un besoin de l'implémentation réelle le démontre. + +## Étude obligatoire avant `alpha.1` + +Comparer les options réalistes d'implémentation Git, au minimum : + +- processus `git` contrôlé ; +- `gix` ou crate Git native pertinente ; +- combinaison éventuelle avec justification. + +Évaluer : + +- fidélité au comportement Git réel ; +- support local/remote ; +- clone/mirror/fetch/worktree ; +- contrôle des chemins et répertoires ; +- erreurs structurées ; +- sécurité des arguments/processus ; +- portabilité ; +- dépendances natives ; +- async/blocking et stratégie d'isolation ; +- testabilité avec repositories temporaires locaux ; +- coût de maintenance. + +Ne pas choisir une bibliothèque sur réputation seule. + +## Scope cible + +La release doit viser : + +- une configuration explicite de source Git locale ou remote ; +- une implémentation provider-neutral derrière `knowledge-git-api` ; +- matérialisation locale hors des sources du dépôt applicatif ; +- refresh/fetch idempotent ; +- résolution d'une référence vers une révision Git ; +- préparation d'un snapshot/worktree de lecture ; +- comparaison de la révision observée avec la précédente ; +- synchronisation explicite ; +- déclenchement périodique si la responsabilité runtime est suffisamment claire ; +- tests locaux reproductibles ne nécessitant aucune forge publique. + +## Non-objectifs + +Ne pas absorber par anticipation : + +- Gitea/GitHub/GitLab API ; +- webhook forge ; +- pull/merge requests ; +- commit/push de publication ; +- workflow complet de proposition ; +- PostgreSQL/migrations ; +- moteur de recherche ; +- format final HOWTO/snippet ; +- auth/admin ; +- worker réseau séparé sans ownership démontré. + +Un hook/webhook futur doit pouvoir produire le même signal interne que les mécanismes génériques sans devenir autoritaire. + +## Contraintes de lecture + +Une requête publique ne doit pas faire un fetch distant pour servir une page. + +Le chemin cible est : + +```text +remote/local Git + -> matérialisation locale contrôlée + -> révision autoritaire résolue + -> snapshot/worktree de lecture + -> futurs parseurs/projections +``` + +Les données dérivées doivent pouvoir être reconstruites à partir de Git. + +## Layout Rust + +Conserver la convention locale `0.0.1` : + +```text +src/ code +unit_tests/ tests unitaires rattachés par #[path] +tests/ tests d'intégration Cargo via API publique +``` + +La nouvelle implémentation Git doit avoir des tests unitaires ciblés et des tests d'intégration avec repositories Git temporaires lorsque la preuve exige de traverser la frontière publique. + +## Web + +La baseline Web/Actix/Maud/Vite de `0.0.1` reste une non-régression. + +`0.0.2` ne doit pas modifier l'UI ou le rendu sauf besoin direct démontré par la mission Git/synchronisation. + +## Première tranche + +Avant de produire `0.0.2-alpha.1` : + +1. vérifier intégralement l'archive stable `v0.0.1` et le rapport post-tag ; +2. vérifier la stable PGR applicable ; +3. relire `docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md` ; +4. inventorier exactement les contrats Git/sync existants ; +5. réaliser l'étude comparative de l'implémentation Git ; +6. décider l'owner de la configuration de sources ; +7. décider où résident les copies Git générées, hors dépôt source ; +8. établir le plan versionné `0.0.2` ; +9. préparer seulement ensuite `0.0.2-alpha.1`. + +## Workflow + +Conserver le workflow PGR : + +```text +delta +-> application opérateur +-> gates réelles +-> history PASS/FAIL +-> commit/push du snapshot observé +-> tranche suivante ou fix +``` + +Ne jamais produire un history `PASS` sans preuves opérateur. + +## Sortie attendue + +La release `0.0.2` doit fournir un chemin Git/synchronisation de lecture réellement utilisable, indépendant d'une forge, suffisamment stable pour que les releases ultérieures puissent construire parsing, projections, PostgreSQL, publication et administration sans refaire la frontière Git.