0.0.2-alpha.1
This commit is contained in:
@@ -1,5 +1,5 @@
|
|||||||
# file: Cargo.toml
|
# file: Cargo.toml
|
||||||
# version: 16
|
# version: 17
|
||||||
|
|
||||||
[workspace]
|
[workspace]
|
||||||
resolver = "3"
|
resolver = "3"
|
||||||
@@ -14,7 +14,7 @@ members = [
|
|||||||
]
|
]
|
||||||
|
|
||||||
[workspace.package]
|
[workspace.package]
|
||||||
version = "0.0.1"
|
version = "0.0.2-alpha.1"
|
||||||
edition = "2024"
|
edition = "2024"
|
||||||
publish = false
|
publish = false
|
||||||
repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge"
|
repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge"
|
||||||
|
|||||||
10
README.md
10
README.md
@@ -1,5 +1,5 @@
|
|||||||
<!-- file: README.md -->
|
<!-- file: README.md -->
|
||||||
<!-- version: 9 -->
|
<!-- version: 10 -->
|
||||||
|
|
||||||
# SaseDev Knowledge
|
# SaseDev Knowledge
|
||||||
|
|
||||||
@@ -11,7 +11,9 @@ Le dépôt applicatif retenu est `sasedev-knowledge`. Le nom court du projet et
|
|||||||
|
|
||||||
La version courante est définie par [`VERSION`](VERSION).
|
La version courante est définie par [`VERSION`](VERSION).
|
||||||
|
|
||||||
`0.0.1` est la première stable de fondation de SaseDev Knowledge. Elle établit la gouvernance, les frontières d'architecture, le workspace Rust/Web, les premiers contrats provider-neutral et les validations nécessaires avant les capacités fonctionnelles des releases suivantes.
|
`0.0.1` est la première stable de fondation de SaseDev Knowledge. `0.0.2-alpha.1` ouvre maintenant la release Git/synchronisation : elle adopte explicitement PGR `v0.1.3`, ferme l'étude du backend Git et fixe le plan avant toute implémentation fonctionnelle.
|
||||||
|
|
||||||
|
Cette première tranche de `0.0.2` ne modifie ni les crates Rust ni la baseline Web. L'implémentation Git réelle commencera dans une tranche ultérieure après validation opérateur de ce cadrage.
|
||||||
|
|
||||||
## Topologie produit de fondation
|
## Topologie produit de fondation
|
||||||
|
|
||||||
@@ -70,10 +72,12 @@ Le runtime exige un bind configuré par launcher et l'une des deux sources d'ass
|
|||||||
- [`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/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/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/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/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](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`](docs/plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan historique de la fondation stable `0.0.1` ;
|
- [`docs/plans/001-V0_0_1_FOUNDATION_PLAN.md`](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`](docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md) — plan actif de `0.0.2`, gates et trajectoire prévisionnelle ;
|
||||||
- [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation ;
|
- [`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/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`, à utiliser uniquement après publication du tag `v0.0.1` et vérification post-tag `PASS`.
|
- [`prompts/002-V0_0_2_START_PROMPT.md`](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
|
## Langue et nomenclature
|
||||||
|
|
||||||
|
|||||||
29
RULES.md
29
RULES.md
@@ -1,5 +1,5 @@
|
|||||||
<!-- file: RULES.md -->
|
<!-- file: RULES.md -->
|
||||||
<!-- version: 9 -->
|
<!-- version: 10 -->
|
||||||
|
|
||||||
# Règles SaseDev Knowledge
|
# Règles SaseDev Knowledge
|
||||||
|
|
||||||
@@ -11,14 +11,20 @@ Le contenu éditorial publié par PGR, HOWTOs et snippets vit dans des dépôts
|
|||||||
|
|
||||||
## Baseline PGR
|
## Baseline PGR
|
||||||
|
|
||||||
La fondation `0.0.1` est cadrée à partir de la stable PGR `v0.1.1`, vérifiée par son rapport post-tag `publish.001` `PASS`.
|
La fondation stable `0.0.1` a été cadrée à partir de PGR `v0.1.1`. Cette référence reste historique et n'est pas réécrite rétroactivement.
|
||||||
|
|
||||||
Empreinte de l'archive PGR autoritaire utilisée pour ce cadrage :
|
À partir de `0.0.2-alpha.1`, Knowledge adopte comme baseline PGR courante la stable `v0.1.3`, vérifiée par `pgr-0.1.3-publish.001-report.md = PASS`.
|
||||||
|
|
||||||
|
Identité de la baseline PGR courante :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a
|
tag v0.1.3
|
||||||
|
commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3
|
||||||
|
SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
|
||||||
```
|
```
|
||||||
|
|
||||||
|
La migration depuis `v0.1.1` suit `230-ADOPTION` : seuls les owners réellement applicables sont adoptés, les choix locaux compatibles sont conservés et l'historique `0.0.1` n'est pas réécrit pour simuler une conformité rétroactive.
|
||||||
|
|
||||||
Les contrats PGR adoptés sont instanciés localement dans ce dépôt. PGR n'est pas une dépendance runtime ou build de Knowledge.
|
Les contrats PGR adoptés sont instanciés localement dans ce dépôt. PGR n'est pas une dépendance runtime ou build de Knowledge.
|
||||||
|
|
||||||
## Owners PGR applicables
|
## Owners PGR applicables
|
||||||
@@ -29,6 +35,7 @@ La fondation retient les owners suivants dans leur scope réel :
|
|||||||
200 gouvernance et lifecycle
|
200 gouvernance et lifecycle
|
||||||
210 workflow plan/delta/history/handoff
|
210 workflow plan/delta/history/handoff
|
||||||
220 composition des skeletons pendant l'instanciation
|
220 composition des skeletons pendant l'instanciation
|
||||||
|
230 adoption d'une nouvelle baseline PGR par un projet existant
|
||||||
300 documentation
|
300 documentation
|
||||||
400 validation proportionnée
|
400 validation proportionnée
|
||||||
500 famille langage/écosystème
|
500 famille langage/écosystème
|
||||||
@@ -40,11 +47,11 @@ La fondation retient les owners suivants dans leur scope réel :
|
|||||||
700 famille framework pour les frameworks réellement utilisés
|
700 famille framework pour les frameworks réellement utilisés
|
||||||
```
|
```
|
||||||
|
|
||||||
Les skeletons `001-PROJECT_GOVERNANCE_FOUNDATION`, `002-RUST_CARGO_WORKSPACE` et `003-WEB_FRONTEND` sont les spécialisations retenues pour `0.0.1`, avec matérialisation progressive selon le plan.
|
Les skeletons `001-PROJECT_GOVERNANCE_FOUNDATION`, `002-RUST_CARGO_WORKSPACE` et `003-WEB_FRONTEND` restent les références de composition de l'état existant. L'adoption PGR `v0.1.3` ne les réapplique pas mécaniquement sur le projet déjà matérialisé.
|
||||||
|
|
||||||
Le profil `710-TAURI` n'est pas applicable au produit Web actuel. Aucun skeleton Tauri n'est adopté.
|
Le profil `710-TAURI` reste `DEFER` / non applicable au produit Web actuel. Aucun skeleton Tauri n'est adopté.
|
||||||
|
|
||||||
Les profils Java/Maven/Gradle, Android et les autres technologies absentes du projet restent hors scope.
|
Les owners Java/Maven/Gradle réorganisés en PGR `0.1.2`, le profil Android réévalué en `0.1.3` et les autres technologies absentes du projet restent hors scope.
|
||||||
|
|
||||||
## Priorité et décisions locales
|
## Priorité et décisions locales
|
||||||
|
|
||||||
@@ -52,7 +59,7 @@ Les obligations PGR réellement adoptées priment sur une préférence locale de
|
|||||||
|
|
||||||
Les choix propres au produit restent locaux lorsqu'aucun owner PGR plus spécifique ne les impose. C'est notamment le cas de l'architecture Git/forge/PostgreSQL, du choix Actix Web/Maud, de Bootstrap, de la topologie à trois applications Web et de la topologie des dépôts de contenu.
|
Les choix propres au produit restent locaux lorsqu'aucun owner PGR plus spécifique ne les impose. C'est notamment le cas de l'architecture Git/forge/PostgreSQL, du choix Actix Web/Maud, de Bootstrap, de la topologie à trois applications Web et de la topologie des dépôts de contenu.
|
||||||
|
|
||||||
Aucun `OVERRIDE` PGR n'est établi par `0.0.1-alpha.1.fix.1`.
|
Aucun `OVERRIDE` PGR n'est requis par l'adoption `v0.1.3` de `0.0.2-alpha.1`.
|
||||||
|
|
||||||
Les décisions différées sont explicites dans [`docs/architecture/001-PROJECT_PROFILE.md`](docs/architecture/001-PROJECT_PROFILE.md). Une valeur différée ne doit pas être remplacée par un choix arbitraire provenant d'un autre projet.
|
Les décisions différées sont explicites dans [`docs/architecture/001-PROJECT_PROFILE.md`](docs/architecture/001-PROJECT_PROFILE.md). Une valeur différée ne doit pas être remplacée par un choix arbitraire provenant d'un autre projet.
|
||||||
|
|
||||||
@@ -118,6 +125,12 @@ Une proposition externe MUST conserver la révision Git de base et MUST NOT écr
|
|||||||
|
|
||||||
La synchronisation générique MUST disposer d'une voie indépendante des webhooks. Les hooks et webhooks MAY accélérer une synchronisation qui converge vers le même cas d'usage interne.
|
La synchronisation générique MUST disposer d'une voie indépendante des webhooks. Les hooks et webhooks MAY accélérer une synchronisation qui converge vers le même cas d'usage interne.
|
||||||
|
|
||||||
|
Pour `0.0.2`, la première implémentation générique retenue utilise un processus `git` contrôlé derrière `knowledge-git-api`. Cette décision est locale à Knowledge et reste remplaçable derrière le contrat.
|
||||||
|
|
||||||
|
La configuration physique des sources Git et la matérialisation locale appartiennent à `knowledge-git-lib` lorsqu'elle sera créée. Les copies générées MUST résider sous une racine d'état explicitement fournie au backend, hors du dépôt applicatif et des dépôts éditoriaux. Ni une URL remote ni un `SourceId` brut ne doivent devenir directement un chemin de stockage.
|
||||||
|
|
||||||
|
La racine d'état Git n'est pas un stockage métier. En `0.0.2`, elle est possédée exclusivement par une instance de backend/processus ; un partage concurrent inter-processus reste différé tant qu'un verrouillage dédié n'est pas matérialisé.
|
||||||
|
|
||||||
## PostgreSQL
|
## PostgreSQL
|
||||||
|
|
||||||
PostgreSQL est destiné à l'état applicatif : comptes, sessions, propositions, revues, audit applicatif, index, recherche, synchronisation et jobs.
|
PostgreSQL est destiné à l'état applicatif : comptes, sessions, propositions, revues, audit applicatif, index, recherche, synchronisation et jobs.
|
||||||
|
|||||||
185
deltas/0.0.2/alpha.1.md
Normal file
185
deltas/0.0.2/alpha.1.md
Normal file
@@ -0,0 +1,185 @@
|
|||||||
|
<!-- file: deltas/0.0.2/alpha.1.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# Delta 0.0.2-alpha.1 — adoption PGR et cadrage Git/synchronisation
|
||||||
|
|
||||||
|
## Baseline requise
|
||||||
|
|
||||||
|
Partir de la stable autoritaire :
|
||||||
|
|
||||||
|
```text
|
||||||
|
tag Knowledge v0.0.1
|
||||||
|
commit Knowledge 98ec46fe73bd50dacbe6be220650d87dd2000b74
|
||||||
|
archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d
|
||||||
|
publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
Le prompt exécuté est :
|
||||||
|
|
||||||
|
```text
|
||||||
|
prompts/002-V0_0_2_START_PROMPT.md
|
||||||
|
```
|
||||||
|
|
||||||
|
La version devient :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.0.2-alpha.1
|
||||||
|
```
|
||||||
|
|
||||||
|
## Objet
|
||||||
|
|
||||||
|
Fermer les décisions obligatoires de démarrage de `0.0.2` avant toute implémentation Git fonctionnelle :
|
||||||
|
|
||||||
|
- vérifier et adopter explicitement la stable PGR courante `v0.1.3` dans son scope applicable ;
|
||||||
|
- activer `230-ADOPTION` pour la migration PGR du projet existant ;
|
||||||
|
- préserver l'historique `0.0.1` construit sous PGR `v0.1.1` ;
|
||||||
|
- documenter l'inventaire des contrats Git/sync existants ;
|
||||||
|
- sélectionner le processus `git` contrôlé après comparaison avec `gix` et `git2` ;
|
||||||
|
- attribuer à la future `knowledge-git-lib` l'ownership de la configuration physique et du backend Git ;
|
||||||
|
- fixer une racine d'état Git généré hors du dépôt source ;
|
||||||
|
- établir le plan versionné `0.0.2` et sa première gate.
|
||||||
|
|
||||||
|
Aucun runtime Git, aucune crate et aucune dépendance ne sont ajoutés dans cette tranche.
|
||||||
|
|
||||||
|
## Adoption PGR
|
||||||
|
|
||||||
|
La baseline PGR applicable devient :
|
||||||
|
|
||||||
|
```text
|
||||||
|
PGR tag v0.1.3
|
||||||
|
PGR commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3
|
||||||
|
PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
|
||||||
|
PGR publish report pgr-0.1.3-publish.001-report.md = PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
Le mapping durable est enregistré dans `docs/architecture/001-PROJECT_PROFILE.md`.
|
||||||
|
|
||||||
|
Les changements PGR `0.1.2`/`0.1.3` sur Java/Maven/Gradle/Android ne rendent pas ces profils applicables à Knowledge. Le `DEFER` Tauri reste inchangé. Aucun `OVERRIDE` n'est introduit.
|
||||||
|
|
||||||
|
## Décision Git
|
||||||
|
|
||||||
|
L'étude :
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
|
||||||
|
```
|
||||||
|
|
||||||
|
retient le client Git externe piloté via `std::process::Command`, sans shell.
|
||||||
|
|
||||||
|
Le layout retenu est conceptuellement :
|
||||||
|
|
||||||
|
```text
|
||||||
|
<git-state-root>/
|
||||||
|
hooks-disabled/
|
||||||
|
repositories/<source-key>.git/
|
||||||
|
snapshots/<source-key>/<resolved-revision>/
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun de ces chemins n'est créé par `alpha.1`.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
REPLACE :
|
||||||
|
|
||||||
|
```text
|
||||||
|
VERSION
|
||||||
|
Cargo.toml
|
||||||
|
README.md
|
||||||
|
RULES.md
|
||||||
|
docs/000-README.md
|
||||||
|
docs/architecture/001-PROJECT_PROFILE.md
|
||||||
|
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
|
||||||
|
docs/validation/001-VALIDATION_MATRIX.md
|
||||||
|
```
|
||||||
|
|
||||||
|
ADD :
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
|
||||||
|
docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
|
||||||
|
deltas/0.0.2/alpha.1.md
|
||||||
|
```
|
||||||
|
|
||||||
|
DELETE : aucun.
|
||||||
|
|
||||||
|
Aucun fichier sous `crates/` ou `Web/` n'est modifié.
|
||||||
|
|
||||||
|
Aucun history `0.0.2-alpha.1` n'est inclus : il doit refléter les preuves opérateur après application.
|
||||||
|
|
||||||
|
## Gate opérateur
|
||||||
|
|
||||||
|
Après application du delta :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
test "$(cat VERSION)" = '0.0.2-alpha.1'
|
||||||
|
grep -F 'version = "0.0.2-alpha.1"' Cargo.toml
|
||||||
|
|
||||||
|
git diff --check
|
||||||
|
|
||||||
|
python3 -B scripts/audit_rust_test_layout.py crates
|
||||||
|
python3 -B scripts/audit_rust_blank_lines.py crates
|
||||||
|
python3 -B scripts/audit_rust_item_spacing.py crates
|
||||||
|
python3 -B scripts/audit_rust_module_order.py crates
|
||||||
|
python3 -B scripts/audit_rust_trait_import_blocks.py crates
|
||||||
|
python3 -B scripts/audit_rust_reexport_blocks.py crates
|
||||||
|
python3 -B scripts/audit_rust_export_completeness.py --root . --summary-only
|
||||||
|
|
||||||
|
cargo fmt --all -- --check
|
||||||
|
cargo metadata --format-version 1 --no-deps
|
||||||
|
cargo check --workspace
|
||||||
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||||
|
cargo test --workspace --all-targets --all-features
|
||||||
|
|
||||||
|
(
|
||||||
|
cd Web/knowledge-template-lab
|
||||||
|
npm ci
|
||||||
|
npm run typecheck
|
||||||
|
npm run build
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Puis rejouer les contrôles de manifest Vite et les trois smokes HTTP selon les commandes déjà possédées par la gate stable `0.0.1`.
|
||||||
|
|
||||||
|
Contrôles spécifiques de cette tranche :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
test -f docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
|
||||||
|
test -f docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
|
||||||
|
test -f deltas/0.0.2/alpha.1.md
|
||||||
|
test ! -e history/0.0.2/alpha.1.md
|
||||||
|
|
||||||
|
grep -F 'PGR stable tag v0.1.3' docs/architecture/001-PROJECT_PROFILE.md
|
||||||
|
grep -F '`230-ADOPTION`' docs/architecture/001-PROJECT_PROFILE.md
|
||||||
|
grep -F 'processus `git` contrôlé' docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
|
||||||
|
grep -F 'repositories/<source-key>.git' docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
|
||||||
|
grep -F 'snapshots/<source-key>/<resolved-revision>' docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
|
||||||
|
|
||||||
|
git diff --name-only -- crates Web
|
||||||
|
git diff --cached --check
|
||||||
|
```
|
||||||
|
|
||||||
|
`git diff --name-only -- crates Web` doit être vide pour cette tranche.
|
||||||
|
|
||||||
|
Le `Cargo.lock` peut être généré ou modifié localement par Cargo mais reste ignoré/non suivi conformément à la stable `0.0.1`. Le `package-lock.json` reste versionné.
|
||||||
|
|
||||||
|
## Transition
|
||||||
|
|
||||||
|
### PASS
|
||||||
|
|
||||||
|
Produire séparément :
|
||||||
|
|
||||||
|
```text
|
||||||
|
history/0.0.2/alpha.1.md
|
||||||
|
```
|
||||||
|
|
||||||
|
avec les résultats réels, l'appliquer, puis commit/push `0.0.2-alpha.1` avant préparation de `alpha.2`.
|
||||||
|
|
||||||
|
### FAIL
|
||||||
|
|
||||||
|
Produire le history réel `FAIL`, le committer, puis corriger uniquement cette tranche avec :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.0.2-alpha.1.fix.1
|
||||||
|
```
|
||||||
|
|
||||||
|
Ne pas préparer `alpha.2` tant que la tranche courante n'est pas fermée conformément au workflow.
|
||||||
@@ -1,5 +1,5 @@
|
|||||||
<!-- file: docs/000-README.md -->
|
<!-- file: docs/000-README.md -->
|
||||||
<!-- version: 5 -->
|
<!-- version: 6 -->
|
||||||
|
|
||||||
# Documentation SaseDev Knowledge
|
# Documentation SaseDev Knowledge
|
||||||
|
|
||||||
@@ -17,10 +17,12 @@
|
|||||||
- [`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/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/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`.
|
- [`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`.
|
||||||
|
- [`studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md) — étude comparative Git de démarrage `0.0.2`, décision process et ownership du backend.
|
||||||
|
|
||||||
## Plans
|
## Plans
|
||||||
|
|
||||||
- [`plans/001-V0_0_1_FOUNDATION_PLAN.md`](plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan historique de la stable de fondation `0.0.1`.
|
- [`plans/001-V0_0_1_FOUNDATION_PLAN.md`](plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan historique de la stable de fondation `0.0.1`.
|
||||||
|
- [`plans/002-V0_0_2_GIT_SYNC_PLAN.md`](plans/002-V0_0_2_GIT_SYNC_PLAN.md) — plan actif de Git générique et synchronisation de lecture `0.0.2`.
|
||||||
|
|
||||||
## Validation
|
## Validation
|
||||||
|
|
||||||
@@ -30,4 +32,4 @@ Les deltas et histories sont des artefacts de workflow, pas des substituts à ce
|
|||||||
|
|
||||||
## Handoff
|
## 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`, à utiliser seulement après publication du tag `v0.0.1` et vérification post-tag `PASS`.
|
- [`../prompts/002-V0_0_2_START_PROMPT.md`](../prompts/002-V0_0_2_START_PROMPT.md) — handoff historique exécuté pour ouvrir `0.0.2` depuis `v0.0.1` publiée et vérifiée.
|
||||||
|
|||||||
@@ -1,158 +1,185 @@
|
|||||||
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
||||||
<!-- version: 9 -->
|
<!-- version: 10 -->
|
||||||
|
|
||||||
# Profil du projet Knowledge
|
# Profil du projet Knowledge
|
||||||
|
|
||||||
## Baseline autoritaire
|
## Baseline autoritaire
|
||||||
|
|
||||||
Le cadrage initial repose sur :
|
La stable produit depuis laquelle `0.0.2` est ouverte est :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
PGR stable tag v0.1.1
|
Knowledge stable tag v0.0.1
|
||||||
PGR archive SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a
|
Knowledge stable commit 98ec46fe73bd50dacbe6be220650d87dd2000b74
|
||||||
PGR publish report pgr-0.1.1-publish.001-report.md = PASS
|
Knowledge archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d
|
||||||
Knowledge prompt prompts/001-V0_0_1_START_PROMPT.md
|
Knowledge publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS
|
||||||
|
Knowledge start prompt prompts/002-V0_0_2_START_PROMPT.md
|
||||||
```
|
```
|
||||||
|
|
||||||
L'archive PGR observée possède `VERSION = 0.1.1`, `292` entrées ZIP, `256` fichiers, `36` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Les `48` tests Python et les audits Markdown headers/tables/links de la stable ont été rejoués avant préparation de cette tranche et sont propres.
|
La fondation `0.0.1` a été construite sous PGR `v0.1.1`. Cette identité reste historique dans les artefacts `0.0.1`.
|
||||||
|
|
||||||
Cette constatation de prévalidation ne remplace aucune gate opérateur Knowledge.
|
Le démarrage de `0.0.2` vérifie puis adopte la stable PGR courante :
|
||||||
|
|
||||||
## Nature de l'instanciation
|
```text
|
||||||
|
PGR stable tag v0.1.3
|
||||||
|
PGR stable commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3
|
||||||
|
PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
|
||||||
|
PGR publish report pgr-0.1.3-publish.001-report.md = PASS
|
||||||
|
```
|
||||||
|
|
||||||
Knowledge est un nouveau projet. La procédure normative d'adoption d'un dépôt existant `230-ADOPTION.md` n'est donc pas activée comme owner de migration.
|
L'archive PGR `v0.1.3` vérifiée possède `VERSION = 0.1.3`, `332` entrées ZIP, `290` fichiers, `42` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Son rapport post-tag indique `48/48` tests Python et les audits Markdown propres.
|
||||||
|
|
||||||
Le prompt de démarrage exige néanmoins une matrice `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`. Les mêmes libellés sont utilisés ci-dessous pour rendre explicite la relation entre PGR et les décisions fondatrices Knowledge :
|
Cette prévalidation ne remplace aucune gate opérateur Knowledge.
|
||||||
|
|
||||||
|
## Nature de l'adoption
|
||||||
|
|
||||||
|
Knowledge n'est plus un nouveau dépôt à instancier : `0.0.2-alpha.1` migre un projet existant de la baseline PGR `v0.1.1` vers `v0.1.3`.
|
||||||
|
|
||||||
|
L'owner PGR `230-ADOPTION` devient applicable à cette migration ; son contrat est instancié localement par les décisions suivantes :
|
||||||
|
|
||||||
|
- partir d'une baseline autoritaire observée ;
|
||||||
|
- sélectionner uniquement les owners réellement applicables ;
|
||||||
|
- classifier `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` ;
|
||||||
|
- préserver les décisions locales compatibles ;
|
||||||
|
- ne pas réécrire les commits, deltas, histories ou documents historiques pour simuler une conformité rétroactive ;
|
||||||
|
- valider proportionnellement la migration.
|
||||||
|
|
||||||
|
Les classifications locales restent :
|
||||||
|
|
||||||
- `ADOPT` — contrat PGR applicable retenu ;
|
- `ADOPT` — contrat PGR applicable retenu ;
|
||||||
- `KEEP-LOCAL` — choix propre à Knowledge, non possédé par un owner PGR plus spécifique et compatible avec les contrats adoptés ;
|
- `KEEP-LOCAL` — choix propre à Knowledge, compatible et non possédé par un owner PGR plus spécifique ;
|
||||||
- `OVERRIDE` — règle PGR applicable remplacée localement ;
|
- `OVERRIDE` — règle PGR applicable remplacée ou raffinée localement avec justification ;
|
||||||
- `DEFER` — choix volontairement reporté avec condition de reprise.
|
- `DEFER` — choix volontairement reporté avec condition de reprise.
|
||||||
|
|
||||||
## Owners et skeletons applicables
|
## Owners et skeletons applicables
|
||||||
|
|
||||||
| Élément | Décision | Matérialisation | Motif |
|
| Élément | Décision courante | État Knowledge | Motif |
|
||||||
|----------------------------------------------|---------------------------------|-----------------|----------------------------------------------|
|
|----------------------------------------------|------------------------------------|-----------------|---------------------------------------------------------------|
|
||||||
| `200-GOVERNANCE` | `ADOPT` | `alpha.1` | lifecycle/version locale |
|
| `200-GOVERNANCE` | `ADOPT` | actif | lifecycle/version locale |
|
||||||
| `210-WORKFLOW` | `ADOPT` | `alpha.1` | plan/delta/history/handoff |
|
| `210-WORKFLOW` | `ADOPT` | actif | plan/delta/history/handoff |
|
||||||
| `220-SKELETONS` | `ADOPT` pour l'instanciation | `alpha.1` | composition explicite sans copie mécanique |
|
| `220-SKELETONS` | `ADOPT` comme référence | actif | les skeletons existants ne sont pas réappliqués mécaniquement |
|
||||||
| `300-DOCUMENTATION` | `ADOPT` | `alpha.1` | rôles documentaires et taxonomie utile |
|
| `230-ADOPTION` | `ADOPT` | `0.0.2-alpha.1` | migration explicite PGR `v0.1.1 -> v0.1.3` |
|
||||||
| `400-VALIDATION` | `ADOPT` | `alpha.1` | preuves proportionnées et autorité opérateur |
|
| `300-DOCUMENTATION` | `ADOPT` | actif | rôles documentaires et taxonomie |
|
||||||
| `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | `alpha.2+` | backend Rust/workspace Cargo contrôlé |
|
| `400-VALIDATION` | `ADOPT` | actif | preuves proportionnées et autorité opérateur |
|
||||||
| `530-TYPESCRIPT` | `ADOPT` | `alpha.4` | frontend durable TypeScript |
|
| `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | actif | backend Rust/workspace Cargo strict |
|
||||||
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | `alpha.4` | package manager/lockfile/scripts explicites |
|
| `530-TYPESCRIPT` | `ADOPT` | actif | frontend durable TypeScript |
|
||||||
| `550-VITE` | `ADOPT` puisque Vite est retenu | `alpha.4` | dev server/build/cache/outputs |
|
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | actif | npm/lockfile/scripts explicites |
|
||||||
| `560-CSS_SASS` | `ADOPT` | `alpha.4` | CSS/Sass et outputs |
|
| `550-VITE` | `ADOPT` | actif | dev server/build/cache/outputs/manifest |
|
||||||
| `700-FRAMEWORKS` | `ADOPT` | `alpha.5` | cadre générique des frameworks |
|
| `560-CSS_SASS` | `ADOPT` | actif | CSS/Sass et outputs |
|
||||||
| `710-TAURI` | `DEFER` / non applicable | hors `0.0.1` | aucun host desktop/mobile Tauri |
|
| `700-FRAMEWORKS` | `ADOPT` | actif | cadre générique des frameworks |
|
||||||
| skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` | `alpha.1` | fondation locale PGR |
|
| `710-TAURI` | `DEFER` / non applicable | inchangé | aucun host desktop/mobile Tauri |
|
||||||
| skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` | `alpha.2` | workspace Rust contrôlé |
|
| skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` comme référence historique | matérialisé | fondation locale existante |
|
||||||
| skeleton `003-WEB_FRONTEND` | `ADOPT` | `alpha.4` | frontend indépendant du host |
|
| skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` comme référence historique | matérialisé | workspace Rust existant |
|
||||||
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | `alpha.4+` | restore/typecheck/build/smoke proportionnés |
|
| skeleton `003-WEB_FRONTEND` | `ADOPT` comme référence historique | matérialisé | frontend indépendant du host |
|
||||||
|
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | actif | restore/typecheck/build/smoke proportionnés |
|
||||||
|
|
||||||
Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont pas sélectionnés.
|
Les owners Java/Maven/Gradle restructurés dans PGR `0.1.2`, le profil Android réévalué en `0.1.3` et les autres technologies absentes ne sont pas sélectionnés. Leur évolution n'entraîne donc aucune migration de code Knowledge.
|
||||||
|
|
||||||
|
Aucun `OVERRIDE` n'est requis par l'adoption `v0.1.3`.
|
||||||
|
|
||||||
## Matrice des décisions importantes
|
## Matrice des décisions importantes
|
||||||
|
|
||||||
| Décision | Classification | Contrat retenu / condition de reprise |
|
| Décision | Classification | Contrat retenu / condition de reprise |
|
||||||
|----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------|
|
|----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------|
|
||||||
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
|
||||||
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
|
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
|
||||||
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
|
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
|
||||||
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
|
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
|
||||||
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
|
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
|
||||||
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
|
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
|
||||||
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
|
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
|
||||||
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
|
| Implémentation Git de `0.0.2` | `KEEP-LOCAL` | processus `git` contrôlé derrière `knowledge-git-api` ; décision réévaluable derrière le contrat |
|
||||||
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
|
| Configuration physique Git | `KEEP-LOCAL` | future `knowledge-git-lib` ; source locale/remote + racine d'état ; pas dans le domaine |
|
||||||
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/polling constituent le socle ; hooks/webhooks sont des accélérateurs |
|
| Copies Git générées | `KEEP-LOCAL` | racine d'état explicite hors dépôt source, mirrors et snapshots adressés par clé sûre/révision |
|
||||||
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée pour l'état transversal et les projections ; jamais vérité du contenu Git publié |
|
| Partage du cache Git entre processus | `DEFER` | état root exclusif à une instance backend en `0.0.2` ; reprendre avec verrouillage inter-processus réel |
|
||||||
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
|
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
|
||||||
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo ; actif depuis `alpha.2` |
|
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
|
||||||
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; les manifests Cargo restent le contrat versionné |
|
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/périodique convergent vers le même cas d'usage ; hooks/webhooks restent accélérateurs |
|
||||||
| Actix Web | `KEEP-LOCAL` | trois launchers matérialisés en `alpha.5` et composition partagée dans `knowledge-web-lib` |
|
| Scheduler périodique concret | `DEFER` | créer seulement lorsque son owner runtime/lifecycle est démontré |
|
||||||
| Maud | `KEEP-LOCAL` | rendu SSR commun matérialisé dans `knowledge-web-lib` en `alpha.5` |
|
| Dernière révision observée en `0.0.2` | `KEEP-LOCAL` | fournie par l'appelant et retournée par le cas d'usage ; pas de pseudo-persistance locale |
|
||||||
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
|
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée future pour état transversal/projections ; jamais vérité du contenu Git publié |
|
||||||
| Package manager frontend | `KEEP-LOCAL` | npm sélectionné en `alpha.4` ; `package-lock.json` versionné |
|
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
|
||||||
| Vite | `KEEP-LOCAL` + owner `550` adopté | build/preview des templates et assets de référence ; manifest de production consommé par l’intégration Maud |
|
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo déjà matérialisé |
|
||||||
| Sass | `KEEP-LOCAL` + owner `560` adopté | styles source de la chaîne de validation Web et des assets réellement servis par les pages Maud |
|
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; manifests Cargo versionnés |
|
||||||
| Bootstrap | `KEEP-LOCAL` | framework CSS retenu pour les templates de référence et le rendu Maud ; jamais règle PGR universelle |
|
| Actix Web | `KEEP-LOCAL` | trois launchers existants et composition partagée dans `knowledge-web-lib` |
|
||||||
| Racine(s) frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` pour les références statiques et assets communs |
|
| Maud | `KEEP-LOCAL` | rendu SSR commun dans `knowledge-web-lib` |
|
||||||
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; le markup runtime est adapté et servi par Maud |
|
| TypeScript | `ADOPT` | owner `530` |
|
||||||
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` en `alpha.5`, avec dev-origin/manifest/base-path configurables |
|
| Package manager frontend | `KEEP-LOCAL` | npm ; `package-lock.json` versionné |
|
||||||
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
|
| Vite | `KEEP-LOCAL` + owner `550` adopté | build/preview de références et manifest consommé par Maud |
|
||||||
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
|
| Sass | `KEEP-LOCAL` + owner `560` adopté | styles source et assets réellement servis |
|
||||||
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |
|
| Bootstrap | `KEEP-LOCAL` | framework CSS local Knowledge, jamais règle PGR universelle |
|
||||||
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
|
| Racine frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` |
|
||||||
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte encore différée |
|
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; rendu runtime Maud |
|
||||||
| Quatrième application d'administration | `DEFER` | peut agréger du transverse plus tard mais ne remplace jamais les frontières admin locales |
|
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` |
|
||||||
| Modèle rôles/capabilities | `DEFER` | séparer identité partagée et autorisations métier avant de figer enums/scopes |
|
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
|
||||||
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel ; ne pas figer un schéma sans contenu représentatif |
|
| Migrations PostgreSQL | `DEFER` | reprendre avec le premier schéma réel |
|
||||||
| Noms définitifs de toutes les crates | `DEFER` | seules les responsabilités et les trois launchers sont cadrés ; créer une crate uniquement avec ownership réel |
|
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif lorsque ce scope sera engagé |
|
||||||
|
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
|
||||||
Aucun `OVERRIDE` n'est requis à ce stade.
|
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte différée |
|
||||||
|
| Quatrième application d'administration | `DEFER` | agréger seulement si une responsabilité transverse apparaît |
|
||||||
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.
|
| Modèle rôles/capabilities | `DEFER` | reprendre avec les cas d'usage d'autorisation réels |
|
||||||
|
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel |
|
||||||
|
| Autres noms de crates | `DEFER` | créer uniquement lorsque l'ownership est démontré |
|
||||||
|
|
||||||
## Nomenclature de crates
|
## Nomenclature de crates
|
||||||
|
|
||||||
Les trois packages exécutables sont des boundaries produit retenus :
|
Les packages matérialisés dans la stable `0.0.1` sont :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
knowledge-pgr-server launcher Actix Web de la façade PGR
|
knowledge-domain-lib types métier stables de famille/source
|
||||||
knowledge-howtos-server launcher Actix Web de la façade HOWTOs
|
knowledge-git-api contrat passif GitRepository provider-neutral
|
||||||
knowledge-snippets-server launcher Actix Web de la façade snippets
|
knowledge-sync-api contrat passif RepositoryEventSource
|
||||||
|
knowledge-web-lib composition Actix/Maud/Vite partagée
|
||||||
|
knowledge-pgr-server launcher PGR mince
|
||||||
|
knowledge-howtos-server launcher HOWTOs mince
|
||||||
|
knowledge-snippets-server launcher snippets mince
|
||||||
```
|
```
|
||||||
|
|
||||||
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.
|
`0.0.2-alpha.1` ferme deux décisions d'ownership sans créer de placeholder :
|
||||||
|
|
||||||
Les responsabilités matérialisées sont :
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
knowledge-domain-lib types métier stables de famille/source ; aucune dépendance Actix/Git-provider/forge/PostgreSQL
|
knowledge-git-lib implémentation Git générique + configuration physique + état local contrôlé
|
||||||
knowledge-git-api contrat passif GitRepository ; implémentations génériques remplaçables derrière cette frontière
|
knowledge-app-lib owner candidat du cas d'usage de synchronisation partagé, à matérialiser seulement quand l'orchestration réelle le démontre
|
||||||
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 :
|
Les responsabilités suivantes restent candidates et non matérialisées :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
knowledge-app-lib orchestration des use cases transversaux, si la séparation apporte une valeur réelle
|
|
||||||
knowledge-git-lib implémentation Git générique de knowledge-git-api
|
|
||||||
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
|
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
|
||||||
knowledge-forge-gitea-lib adapter Gitea optionnel
|
knowledge-forge-gitea-lib adapter Gitea optionnel
|
||||||
knowledge-logging-lib diagnostics partagés, seulement lorsque plusieurs runtimes en ont effectivement besoin
|
knowledge-logging-lib diagnostics partagés, seulement sur besoin multi-runtime réel
|
||||||
```
|
```
|
||||||
|
|
||||||
Règles de création :
|
Règles de création :
|
||||||
|
|
||||||
- ne pas créer une crate uniquement pour refléter un diagramme ;
|
- ne pas créer une crate uniquement pour refléter un diagramme ;
|
||||||
- ne pas utiliser `-api` sans frontière de contrat indépendante réellement nécessaire ;
|
- ne pas utiliser `-api` sans frontière de contrat indépendante réellement nécessaire ;
|
||||||
- garder le domaine indépendant d'Actix, Gitea et PostgreSQL ;
|
- garder le domaine indépendant d'Actix, Gitea, Git process et PostgreSQL ;
|
||||||
- garder les adapters dépendants des contrats, jamais l'inverse ;
|
- garder les adapters/implémentations dépendants des contrats, jamais l'inverse ;
|
||||||
- ne pas dupliquer dans les trois serveurs une logique qui possède clairement un owner commun ;
|
- ne pas dupliquer dans les trois serveurs une logique qui possède clairement un owner commun ;
|
||||||
- ne pas créer un service réseau supplémentaire lorsqu'une crate partagée suffit.
|
- ne pas créer un service réseau supplémentaire lorsqu'une crate partagée suffit.
|
||||||
|
|
||||||
## Corpus auth/admin étudié en alpha.2
|
## Corpus auth/admin étudié en 0.0.1
|
||||||
|
|
||||||
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` sont des sources d'inspiration non autoritaires. Leur analyse est conservée dans [`../studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](../studies/001-AUTH_ADMIN_CORPUS_STUDY.md).
|
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` restent des sources d'inspiration non autoritaires. Leur analyse est conservée dans [`../studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](../studies/001-AUTH_ADMIN_CORPUS_STUDY.md).
|
||||||
|
|
||||||
Elles justifient de conserver séparées :
|
Elles justifient de conserver séparées l'identité/authentification partagée, l'autorisation privilégiée propre à chaque application et une éventuelle façade transverse ultérieure. Elles ne justifient toujours pas de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA pendant `0.0.2`.
|
||||||
|
|
||||||
- l'identité/authentification partagée de plateforme ;
|
## Résultat de l'adoption PGR 0.1.3
|
||||||
- l'autorisation privilégiée propre aux cas d'usage de chaque application ;
|
|
||||||
- une éventuelle façade d'administration transversale ultérieure.
|
|
||||||
|
|
||||||
Elles ne justifient pas encore de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA comme scope `0.0.1`.
|
L'adoption est bornée aux évolutions réellement applicables :
|
||||||
|
|
||||||
|
- `230-ADOPTION` devient applicable parce que Knowledge est désormais un projet existant ;
|
||||||
|
- les owners déjà adoptés restent actifs ;
|
||||||
|
- les changements PGR Java/Maven/Gradle/Android ne s'appliquent pas ;
|
||||||
|
- le `DEFER` Tauri reste inchangé ;
|
||||||
|
- les skeletons servent de références de comparaison et ne sont pas réinstanciés ;
|
||||||
|
- les anciennes gates/deltas/histories `0.0.1` conservent leur contexte historique, y compris les états `FAIL` et anciennes décisions corrigées plus tard ;
|
||||||
|
- aucune règle produit Git/process n'est promue en règle PGR générale.
|
||||||
|
|
||||||
## Décisions à rouvrir
|
## Décisions à rouvrir
|
||||||
|
|
||||||
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 release `0.0.2` rouvre uniquement l'implémentation Git générique et la synchronisation réelle de lecture.
|
||||||
|
|
||||||
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.
|
Restent différés : adapter Gitea, PostgreSQL/migrations, moteur de recherche, auth/admin complète, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet, écriture/publication Git et partage concurrent de la même racine Git entre plusieurs processus.
|
||||||
|
|
||||||
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é.
|
Un changement de scope produit, un besoin mesuré ou une contrainte d'exploitation peut déclencher un REPLAN ; il ne justifie pas un choix anticipé.
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
|
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
|
||||||
<!-- version: 9 -->
|
<!-- version: 10 -->
|
||||||
|
|
||||||
# Architecture de fondation Knowledge
|
# Architecture de fondation Knowledge
|
||||||
|
|
||||||
@@ -69,9 +69,9 @@ knowledge-pgr-server knowledge-howtos-server knowledge-snippets-server
|
|||||||
|
|
||||||
La dépendance pointe vers les contrats métier. Les détails Actix, processus Git, API Gitea ou SQL ne remontent pas dans le domaine.
|
La dépendance pointe vers les contrats métier. Les détails Actix, processus Git, API Gitea ou SQL ne remontent pas dans le domaine.
|
||||||
|
|
||||||
`GitRepository` ne porte que les opérations génériques actuellement nécessaires : rafraîchir la vue locale d'une source et résoudre une référence opaque vers une révision Git autoritaire. Le contrat ne suppose ni API de forge, ni type de remote particulier, ni format SHA figé.
|
`GitRepository` ne porte dans la stable `0.0.1` que les opérations génériques alors nécessaires : rafraîchir la vue locale d'une source et résoudre une référence opaque vers une révision Git autoritaire. `0.0.2` n'étend ce contrat que lorsqu'un besoin de snapshot réellement implémenté le démontre. Le contrat ne suppose ni API de forge, ni type de remote particulier, ni format SHA figé.
|
||||||
|
|
||||||
`RepositoryEventSource` ne produit qu'un `RepositorySyncSignal` associé à un `source_id`. La cause est volontairement grossière (`Explicit`, `Periodic`, `ExternalSignal`) afin que hook Git, webhook de forge ou watcher ne deviennent pas des concepts autoritaires du domaine.
|
`RepositoryEventSource` ne produit qu'un `RepositorySyncSignal` associé à un `source_id`. La cause reste volontairement grossière (`Explicit`, `Periodic`, `ExternalSignal`) afin que hook Git, webhook de forge ou watcher ne deviennent pas des concepts autoritaires du domaine.
|
||||||
|
|
||||||
## 1. Applications publiques
|
## 1. Applications publiques
|
||||||
|
|
||||||
@@ -105,32 +105,81 @@ Le domaine ne suppose pas qu'une famille possède exactement un repository. Il m
|
|||||||
|
|
||||||
## 3. Git générique
|
## 3. Git générique
|
||||||
|
|
||||||
Le contrat conceptuel `GitRepository` couvre uniquement les opérations Git nécessaires :
|
Le contrat `GitRepository` reste provider-neutral. `0.0.2-alpha.1` sélectionne comme première implémentation un **processus `git` contrôlé** dans la future crate :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
refs / resolve revision
|
knowledge-git-lib
|
||||||
fetch
|
|
||||||
checkout ou worktree local
|
|
||||||
status/diff
|
|
||||||
branch
|
|
||||||
commit
|
|
||||||
merge/rebase contrôlé lorsque le workflow l'exige
|
|
||||||
push lorsque autorisé
|
|
||||||
```
|
```
|
||||||
|
|
||||||
L'implémentation doit fonctionner sans connaître Gitea, GitHub ou GitLab.
|
Cette sélection est une décision locale Knowledge, pas un couplage du contrat au CLI Git. Une autre implémentation pourra remplacer le backend ultérieurement si des preuves de maintenance, performance ou portabilité le justifient.
|
||||||
|
|
||||||
Le serveur préfère des mirrors/clones et worktrees locaux. Une requête publique ne doit pas déclencher un appel réseau vers la forge.
|
### Configuration physique
|
||||||
|
|
||||||
La baseline prévoit au moins trois sources Git indépendantes :
|
`knowledge-domain-lib` continue de posséder `SourceId` et `ContentSource`. Les URLs, chemins locaux, exécutable Git et répertoires de travail ne remontent pas dans le domaine.
|
||||||
|
|
||||||
|
`knowledge-git-lib` possédera la configuration physique :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
pgr source primaire de knowledge-pgr-server
|
source_id -> local path ou remote Git générique
|
||||||
howtos source primaire de knowledge-howtos-server
|
source_id -> référence cible configurée
|
||||||
snippets source primaire de knowledge-snippets-server
|
backend -> racine d'état Git contrôlée
|
||||||
```
|
```
|
||||||
|
|
||||||
Ce mapping est configurable et extensible ; il ne devient pas un `match` codé en dur sur trois repositories.
|
La composition runtime pourra charger ces valeurs depuis la configuration de déploiement. La persistance logique future dans PostgreSQL reste différée.
|
||||||
|
|
||||||
|
### Matérialisation locale
|
||||||
|
|
||||||
|
Les données générées résident hors du dépôt applicatif et hors des dépôts éditoriaux :
|
||||||
|
|
||||||
|
```text
|
||||||
|
<git-state-root>/
|
||||||
|
hooks-disabled/
|
||||||
|
repositories/
|
||||||
|
<source-key>.git/
|
||||||
|
snapshots/
|
||||||
|
<source-key>/
|
||||||
|
<resolved-revision>/
|
||||||
|
```
|
||||||
|
|
||||||
|
Le backend reçoit explicitement `<git-state-root>` ; il n'utilise aucun défaut implicite sous le workspace. Une variable de déploiement telle que `KNOWLEDGE_GIT_STATE_ROOT` pourra alimenter la composition, mais la librairie reçoit un chemin et ne lit pas elle-même l'environnement.
|
||||||
|
|
||||||
|
`source-key` est une clé sûre dérivée par l'implémentation. Un `SourceId` ou une URL remote ne sont jamais interpolés directement comme chemin de filesystem.
|
||||||
|
|
||||||
|
Pendant `0.0.2`, une racine d'état appartient exclusivement à une instance backend/processus. Le partage simultané d'une même racine entre plusieurs processus reste `DEFER` jusqu'à matérialisation d'un verrouillage inter-processus.
|
||||||
|
|
||||||
|
### Mirror et refresh
|
||||||
|
|
||||||
|
Une source locale ou remote converge vers un mirror Git contrôlé.
|
||||||
|
|
||||||
|
L'initialisation utilise conceptuellement :
|
||||||
|
|
||||||
|
```text
|
||||||
|
git clone --mirror [--no-local pour une source locale] -- <source> <mirror>
|
||||||
|
```
|
||||||
|
|
||||||
|
Pour une source locale, `--no-local` évite de créer une dépendance par hardlinks/optimisation locale sur le repository éditorial.
|
||||||
|
|
||||||
|
Le refresh réutilise la configuration du remote du mirror et met les refs à jour avec pruning. L'opération doit être idempotente et ne dépend d'aucune API de forge.
|
||||||
|
|
||||||
|
### Résolution et snapshot
|
||||||
|
|
||||||
|
Une référence cible n'est jamais considérée comme identité autoritaire avant résolution. Le backend exige qu'elle se résolve vers un commit réel, selon la sémantique :
|
||||||
|
|
||||||
|
```text
|
||||||
|
git --git-dir=<mirror> rev-parse --verify --end-of-options <reference>^{commit}
|
||||||
|
```
|
||||||
|
|
||||||
|
La valeur obtenue devient `GitRevision`.
|
||||||
|
|
||||||
|
Le snapshot de lecture est ensuite créé comme worktree détaché adressé par cette révision. Un snapshot déjà présent n'est réutilisé qu'après vérification de son `HEAD` et d'un état propre ; une divergence produit une erreur récupérable plutôt qu'un nettoyage destructif silencieux.
|
||||||
|
|
||||||
|
Les hooks Git sont désactivés pour les opérations de checkout/worktree appartenant au backend. Les commandes sont exécutées directement sans shell, avec prompts interactifs désactivés et sans journaliser de credential.
|
||||||
|
|
||||||
|
### Scope futur du contrat Git
|
||||||
|
|
||||||
|
Les opérations génériques à plus long terme peuvent inclure `status/diff`, branch, commit, merge/rebase et push. Elles ne sont pas ajoutées en `0.0.2` : la release n'étend le contrat que pour la matérialisation de lecture réellement nécessaire.
|
||||||
|
|
||||||
|
La baseline conserve au moins trois sources indépendantes (`pgr`, `howtos`, `snippets`) mais le mapping reste configurable et extensible ; aucun `match` codé en dur n'impose exactement trois repositories.
|
||||||
|
|
||||||
## 4. Forge optionnelle
|
## 4. Forge optionnelle
|
||||||
|
|
||||||
@@ -150,9 +199,9 @@ Gitea est le premier candidat d'intégration mais n'est pas figé comme dépenda
|
|||||||
|
|
||||||
## 5. Événements et synchronisation
|
## 5. Événements et synchronisation
|
||||||
|
|
||||||
Le contrat conceptuel `RepositoryEventSource` produit un **signal de synchronisation**, pas une vérité de contenu.
|
Le contrat `RepositoryEventSource` produit un **signal de synchronisation**, pas une vérité de contenu.
|
||||||
|
|
||||||
Sources prévues :
|
Sources conceptuelles :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
sync explicite
|
sync explicite
|
||||||
@@ -162,22 +211,28 @@ webhook de forge
|
|||||||
watcher filesystem éventuel
|
watcher filesystem éventuel
|
||||||
```
|
```
|
||||||
|
|
||||||
Toutes convergent vers le même cas d'usage interne :
|
Toutes les sources doivent converger vers le même cas d'usage :
|
||||||
|
|
||||||
```text
|
```text
|
||||||
signal(source_id)
|
signal(source_id)
|
||||||
-> fetch/refresh si nécessaire
|
-> refresh du mirror si nécessaire
|
||||||
-> résolution de la révision cible Git
|
-> résolution de la révision cible Git
|
||||||
-> comparaison avec la dernière révision indexée
|
-> comparaison avec previous_revision
|
||||||
-> checkout/worktree de la révision
|
-> snapshot/worktree de cette révision si changement
|
||||||
-> parsing + validation selon la famille
|
-> futurs parsing + validation + projection
|
||||||
-> construction d'une projection/index
|
|
||||||
-> publication atomique de l'état dérivé
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Un webhook peut être perdu ou dupliqué. Le commit Git résolu reste l'identité autoritaire de la révision.
|
Un webhook peut être perdu ou dupliqué. Le commit Git résolu reste l'identité autoritaire.
|
||||||
|
|
||||||
La synchronisation peut être déclenchée par chacun des trois serveurs au début. Un worker séparé n'est créé que si un besoin d'ownership/lifecycle distinct apparaît.
|
### Ownership de `0.0.2`
|
||||||
|
|
||||||
|
La synchronisation partagée est une responsabilité de couche application, distincte du backend Git et des producteurs de signaux. La candidate existante `knowledge-app-lib` devient l'owner naturel si l'orchestration réelle confirme qu'une crate partagée est nécessaire ; elle n'est pas créée en `alpha.1` comme placeholder.
|
||||||
|
|
||||||
|
Sans PostgreSQL dans cette release, la dernière révision connue n'est pas stockée dans un fichier ad hoc caché. Le cas d'usage reçoit `previous_revision` de l'appelant et retourne explicitement la révision observée ainsi qu'un résultat `Changed` ou `Unchanged`. La future persistance pourra remplacer cet état appelant sans modifier la frontière Git.
|
||||||
|
|
||||||
|
La cause `Periodic` reste supportée par `knowledge-sync-api`, mais `0.0.2-alpha.1` ne désigne pas encore de scheduler concret. Un scheduler n'est matérialisé que si son lifecycle/runtime est démontré ; lorsqu'il existe, il appelle exactement le même cas d'usage que la voie explicite.
|
||||||
|
|
||||||
|
La synchronisation peut rester composée par chacun des trois serveurs au début. Un worker réseau séparé n'est créé que si un owner/lifecycle distinct devient nécessaire.
|
||||||
|
|
||||||
## 6. Propositions et revues
|
## 6. Propositions et revues
|
||||||
|
|
||||||
@@ -291,7 +346,7 @@ La fondation matérialisée est cohérente avec les objectifs `0.0.1` :
|
|||||||
- frontend de référence indépendant et rendu runtime Maud effectivement relié au manifest Vite ;
|
- 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.
|
- 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.
|
`0.0.2-alpha.1` conserve cette réconciliation comme baseline : la release courante ouvre uniquement le chemin Git générique de lecture et la synchronisation réelle ; les autres axes restent différés.
|
||||||
|
|
||||||
## 10. Administration
|
## 10. Administration
|
||||||
|
|
||||||
@@ -350,9 +405,9 @@ Une pratique répétée dans HOWTO/snippet peut devenir un candidat d'étude PGR
|
|||||||
- utilisateurs/sessions ;
|
- utilisateurs/sessions ;
|
||||||
- propositions et revue ;
|
- propositions et revue ;
|
||||||
- commentaires/audit applicatif ;
|
- commentaires/audit applicatif ;
|
||||||
- configuration logique des sources ;
|
- configuration logique persistante des sources lorsque PostgreSQL sera matérialisé ;
|
||||||
- mapping source/famille/application ;
|
- mapping source/famille/application ;
|
||||||
- dernière révision synchronisée/indexée par source ;
|
- dernière révision synchronisée/indexée par source lorsque la persistance sera matérialisée ;
|
||||||
- index et recherche dérivés ;
|
- index et recherche dérivés ;
|
||||||
- relations calculées entre familles ;
|
- relations calculées entre familles ;
|
||||||
- jobs de synchronisation/publication ;
|
- jobs de synchronisation/publication ;
|
||||||
@@ -372,3 +427,5 @@ snippets source Git courte/contextualisée séparée
|
|||||||
```
|
```
|
||||||
|
|
||||||
Les dépôts de contenu ne sont pas fusionnés dans PGR et ne sont pas requis comme submodules Git du dépôt applicatif. Leur localisation et leurs credentials sont de la configuration de déploiement.
|
Les dépôts de contenu ne sont pas fusionnés dans PGR et ne sont pas requis comme submodules Git du dépôt applicatif. Leur localisation et leurs credentials sont de la configuration de déploiement.
|
||||||
|
|
||||||
|
Pendant `0.0.2`, cette configuration de déploiement est adaptée en configuration physique possédée par `knowledge-git-lib`. La racine de mirrors/worktrees reste un état généré reconstructible et ne remplace pas le futur stockage logique PostgreSQL.
|
||||||
|
|||||||
212
docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
Normal file
212
docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
Normal file
@@ -0,0 +1,212 @@
|
|||||||
|
<!-- file: docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# Plan 0.0.2 — Git générique et synchronisation de lecture
|
||||||
|
|
||||||
|
## Baseline autoritaire
|
||||||
|
|
||||||
|
La release part exclusivement de :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Knowledge tag stable v0.0.1
|
||||||
|
Knowledge commit stable 98ec46fe73bd50dacbe6be220650d87dd2000b74
|
||||||
|
Knowledge archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d
|
||||||
|
Knowledge publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS
|
||||||
|
start prompt prompts/002-V0_0_2_START_PROMPT.md
|
||||||
|
```
|
||||||
|
|
||||||
|
La baseline PGR applicable est réévaluée au démarrage et devient :
|
||||||
|
|
||||||
|
```text
|
||||||
|
PGR stable tag v0.1.3
|
||||||
|
PGR stable commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3
|
||||||
|
PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
|
||||||
|
PGR publish report pgr-0.1.3-publish.001-report.md = PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
Le passage de PGR `v0.1.1` à `v0.1.3` est une adoption d'un projet existant et active l'owner `230-ADOPTION` pour cette migration. Les artifacts historiques `0.0.1` ne sont pas réécrits.
|
||||||
|
|
||||||
|
## Mission
|
||||||
|
|
||||||
|
`0.0.2` rend réellement utilisable le chemin de lecture Git générique :
|
||||||
|
|
||||||
|
```text
|
||||||
|
source locale/remote
|
||||||
|
-> mirror contrôlé
|
||||||
|
-> refresh
|
||||||
|
-> résolution vers commit
|
||||||
|
-> snapshot/worktree déterministe
|
||||||
|
-> résultat de synchronisation changed/unchanged
|
||||||
|
```
|
||||||
|
|
||||||
|
La forge reste optionnelle et absente du chemin générique.
|
||||||
|
|
||||||
|
## Décisions fermées avant `alpha.1`
|
||||||
|
|
||||||
|
L'étude [`../studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](../studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md) fixe les décisions suivantes :
|
||||||
|
|
||||||
|
- backend initial par processus `git` contrôlé, sans shell ;
|
||||||
|
- `knowledge-git-lib` comme owner de l'implémentation et de la configuration physique Git ;
|
||||||
|
- racine d'état explicite hors dépôt source ;
|
||||||
|
- mirrors sous `repositories/<source-key>.git` ;
|
||||||
|
- snapshots sous `snapshots/<source-key>/<resolved-revision>` ;
|
||||||
|
- source locale clonée avec `--mirror --no-local` ;
|
||||||
|
- résolution vers un commit réel avant création de snapshot ;
|
||||||
|
- état root exclusif au processus/backend pour cette release ;
|
||||||
|
- dernière révision précédente fournie par l'appelant tant que PostgreSQL reste hors scope ;
|
||||||
|
- scheduler périodique concret différé, mais le signal `Periodic` conserve la même voie de synchronisation ;
|
||||||
|
- aucun backend secondaire `gix`/`git2` tant qu'un besoin observé ne le justifie.
|
||||||
|
|
||||||
|
## Hors scope
|
||||||
|
|
||||||
|
Restent explicitement hors `0.0.2` :
|
||||||
|
|
||||||
|
- API Gitea/GitHub/GitLab ;
|
||||||
|
- webhooks forge ;
|
||||||
|
- pull/merge requests ;
|
||||||
|
- branch/commit/rebase/merge/push de publication ;
|
||||||
|
- PostgreSQL et migrations ;
|
||||||
|
- persistance durable de l'état de sync ;
|
||||||
|
- parsing final PGR/HOWTO/snippet ;
|
||||||
|
- moteur de recherche ;
|
||||||
|
- auth/admin ;
|
||||||
|
- worker réseau séparé ;
|
||||||
|
- cache Git partagé simultanément par plusieurs processus ;
|
||||||
|
- changement de rendu/UI Web.
|
||||||
|
|
||||||
|
## alpha.1 — adoption PGR, étude et cadrage
|
||||||
|
|
||||||
|
Objectif : fermer les prérequis du prompt de démarrage sans introduire de runtime Git incomplet.
|
||||||
|
|
||||||
|
Scope prévu :
|
||||||
|
|
||||||
|
- vérifier la stable Knowledge et son rapport post-tag ;
|
||||||
|
- adopter explicitement PGR `v0.1.3` pour le scope applicable via `230-ADOPTION` ;
|
||||||
|
- préserver comme historiques les références PGR `v0.1.1` propres à la fondation `0.0.1` ;
|
||||||
|
- inventorier les contrats `domain/git-api/sync-api` ;
|
||||||
|
- comparer processus Git, `gix` et `git2` ;
|
||||||
|
- décider `knowledge-git-lib` comme owner concret de configuration/backend ;
|
||||||
|
- décider le layout des copies Git générées ;
|
||||||
|
- établir ce plan et la gate de release.
|
||||||
|
|
||||||
|
Aucun fichier sous `crates/` ou `Web/` n'est modifié dans cette tranche.
|
||||||
|
|
||||||
|
Statut opérateur : **à valider**.
|
||||||
|
|
||||||
|
## alpha.2 — contrats minimaux et backend process
|
||||||
|
|
||||||
|
Forecast :
|
||||||
|
|
||||||
|
- matérialiser `knowledge-git-lib` ;
|
||||||
|
- ajouter uniquement les types/configurations nécessaires à une source locale ou remote et à la racine d'état ;
|
||||||
|
- encapsuler `std::process::Command` derrière un runner testable ;
|
||||||
|
- implémenter l'initialisation/inspection du mirror contrôlé ;
|
||||||
|
- étendre `knowledge-git-api` seulement si le besoin de snapshot le requiert déjà à cette tranche ;
|
||||||
|
- tests unitaires de validation de configuration, chemins, arguments, erreurs et redaction.
|
||||||
|
|
||||||
|
La tranche ne doit pas encore créer de dépendance forge ou de scheduler.
|
||||||
|
|
||||||
|
Forecast non validé ; peut être scindé si la surface devient trop large.
|
||||||
|
|
||||||
|
## alpha.3 — refresh, résolution et snapshot réel
|
||||||
|
|
||||||
|
Forecast :
|
||||||
|
|
||||||
|
- refresh idempotent du mirror ;
|
||||||
|
- résolution typée d'une référence vers un commit ;
|
||||||
|
- préparation du worktree détaché adressé par révision ;
|
||||||
|
- validation d'un snapshot existant avant réutilisation ;
|
||||||
|
- tests d'intégration Cargo avec repositories temporaires locaux ;
|
||||||
|
- preuve du changement de révision après un nouveau commit source ;
|
||||||
|
- preuve qu'aucun accès à une forge publique n'est nécessaire.
|
||||||
|
|
||||||
|
Les tests doivent exercer la frontière publique de `knowledge-git-lib` et non une imitation de commandes.
|
||||||
|
|
||||||
|
## alpha.4 — cas d'usage de synchronisation
|
||||||
|
|
||||||
|
Forecast :
|
||||||
|
|
||||||
|
- matérialiser `knowledge-app-lib` si l'orchestration partagée démontre bien cet ownership ;
|
||||||
|
- enchaîner refresh, resolve, comparaison avec `previous_revision` et snapshot ;
|
||||||
|
- retourner explicitement `Unchanged` ou `Changed` avec la révision observée ;
|
||||||
|
- synchronisation explicite réellement utilisable ;
|
||||||
|
- vérifier qu'un signal `Periodic` peut emprunter exactement le même cas d'usage sans matérialiser artificiellement un scheduler ;
|
||||||
|
- conserver la persistance de dernière révision hors scope.
|
||||||
|
|
||||||
|
Si l'orchestration peut rester plus simple sans nouvelle crate tout en évitant la duplication entre launchers, la tranche peut être replanifiée ; aucune crate n'est créée par symétrie.
|
||||||
|
|
||||||
|
## beta.1 — réconciliation
|
||||||
|
|
||||||
|
Forecast :
|
||||||
|
|
||||||
|
- réconcilier documentation, contrats et implémentation réellement obtenue ;
|
||||||
|
- vérifier tous les `DEFER` ;
|
||||||
|
- retirer les hypothèses de plan devenues fausses ;
|
||||||
|
- confirmer absence de régression Web/Actix/Maud/Vite ;
|
||||||
|
- exécuter les gates Rust complètes ;
|
||||||
|
- décider, à partir du retour réel, si une release suivante doit être engagée et laquelle ;
|
||||||
|
- ne pas réserver automatiquement un numéro futur.
|
||||||
|
|
||||||
|
Aucune grande fonctionnalité nouvelle ne doit être introduite en beta.
|
||||||
|
|
||||||
|
## rc.1 — release candidate
|
||||||
|
|
||||||
|
Forecast :
|
||||||
|
|
||||||
|
- aucune nouvelle fonctionnalité ;
|
||||||
|
- gate documentaire, Rust, Web et Git complète sur l'état final ;
|
||||||
|
- aucune dépendance forge/PostgreSQL/auth/admin ;
|
||||||
|
- candidat stable uniquement si les tests locaux Git réels sont propres et reproductibles.
|
||||||
|
|
||||||
|
Un `FAIL` produit `rc.1.fix.1`, jamais un `PASS` fictif.
|
||||||
|
|
||||||
|
## rel.1 — clôture stable
|
||||||
|
|
||||||
|
Forecast :
|
||||||
|
|
||||||
|
- promotion mécanique après history RC `PASS` ;
|
||||||
|
- version stable `0.0.2` ;
|
||||||
|
- stabilisation README/ROADMAP/CHANGELOG/index/plan ;
|
||||||
|
- création d'un prompt de reprise uniquement si la revue d'horizon a réellement engagé une prochaine release ;
|
||||||
|
- gate pré-tag complète ;
|
||||||
|
- history `rel.1` produit seulement à partir des résultats opérateur ;
|
||||||
|
- commit stable `0.0.2`, push, tag annoté `v0.0.2`, archive du tag puis rapport `publish.001` seulement après `PASS`.
|
||||||
|
|
||||||
|
## Stratégie de validation
|
||||||
|
|
||||||
|
La validation doit rester proportionnée mais la mission Git exige des preuves réelles, pas uniquement des mocks.
|
||||||
|
|
||||||
|
À partir de la première tranche fonctionnelle :
|
||||||
|
|
||||||
|
```text
|
||||||
|
cargo fmt --all -- --check
|
||||||
|
python3 -B scripts/audit_rust_test_layout.py crates
|
||||||
|
python3 -B scripts/audit_rust_blank_lines.py crates
|
||||||
|
python3 -B scripts/audit_rust_item_spacing.py crates
|
||||||
|
python3 -B scripts/audit_rust_module_order.py crates
|
||||||
|
python3 -B scripts/audit_rust_trait_import_blocks.py crates
|
||||||
|
python3 -B scripts/audit_rust_reexport_blocks.py crates
|
||||||
|
python3 -B scripts/audit_rust_export_completeness.py --root . --summary-only
|
||||||
|
cargo metadata --format-version 1 --no-deps
|
||||||
|
cargo check --workspace
|
||||||
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||||
|
cargo test --workspace --all-targets --all-features
|
||||||
|
```
|
||||||
|
|
||||||
|
Les tests Git utilisent des repositories temporaires locaux. Une preuve live vers une forge ou Internet reste une gate externe séparée et non requise par le chemin générique.
|
||||||
|
|
||||||
|
La baseline Web reste non-régression. Les gates npm/build/manifest et les smokes HTTP sont rejoués dans les tranches de stabilisation ou si une modification peut les affecter ; `alpha.1` n'altère aucun fichier Rust/Web.
|
||||||
|
|
||||||
|
## Clôture et transition
|
||||||
|
|
||||||
|
Le `CHANGELOG` ne reçoit pas de catalogue de tranches. Il est consolidé au stade de candidate/stable avec les changements utiles de la release.
|
||||||
|
|
||||||
|
`ROADMAP` ne réserve actuellement aucune version après `0.0.2`. La revue d'horizon appartient à `beta.1` et doit se baser sur le backend réellement éprouvé.
|
||||||
|
|
||||||
|
Le workflow demeure :
|
||||||
|
|
||||||
|
```text
|
||||||
|
delta -> application -> gate opérateur -> history réel -> commit/push -> tranche suivante/fix
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun history `PASS` n'est fourni avec ce plan.
|
||||||
245
docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
Normal file
245
docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
Normal file
@@ -0,0 +1,245 @@
|
|||||||
|
<!-- file: docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# Étude 0.0.2 — implémentation Git générique
|
||||||
|
|
||||||
|
## Objet
|
||||||
|
|
||||||
|
Cette étude ferme la décision technique exigée avant `0.0.2-alpha.1` : choisir le mécanisme qui implémentera le premier backend Git provider-neutral de Knowledge sans introduire de dépendance à une forge.
|
||||||
|
|
||||||
|
Le besoin réel est limité au chemin de lecture :
|
||||||
|
|
||||||
|
```text
|
||||||
|
source Git locale ou remote
|
||||||
|
-> copie locale contrôlée
|
||||||
|
-> refresh idempotent
|
||||||
|
-> résolution d'une référence vers un commit
|
||||||
|
-> snapshot/worktree de lecture déterministe
|
||||||
|
```
|
||||||
|
|
||||||
|
L'écriture Git, les pull/merge requests, les webhooks de forge, PostgreSQL, le parsing final et la publication restent hors scope.
|
||||||
|
|
||||||
|
## Contraintes déjà acquises
|
||||||
|
|
||||||
|
Les contrats de `0.0.1` restent autoritaires :
|
||||||
|
|
||||||
|
- `knowledge-domain-lib` possède l'identité logique `SourceId` et la famille de contenu ;
|
||||||
|
- `knowledge-git-api` possède le contrat provider-neutral `GitRepository` ;
|
||||||
|
- `knowledge-sync-api` possède les signaux non autoritaires `RepositorySyncSignal` ;
|
||||||
|
- le domaine ne connaît ni Gitea, ni GitHub, ni GitLab ;
|
||||||
|
- une requête publique ne déclenche jamais de fetch distant ;
|
||||||
|
- les tests de la voie générique doivent fonctionner avec des repositories temporaires locaux ;
|
||||||
|
- les erreurs doivent rester récupérables et aucune donnée sensible ne doit être journalisée.
|
||||||
|
|
||||||
|
## Sources techniques consultées
|
||||||
|
|
||||||
|
Consultation effectuée le `2026-09-28` :
|
||||||
|
|
||||||
|
- Rust `std::process::Command` : <https://doc.rust-lang.org/std/process/struct.Command.html> ;
|
||||||
|
- Git `clone` : <https://git-scm.com/docs/git-clone> ;
|
||||||
|
- Git `worktree` : <https://git-scm.com/docs/git-worktree> ;
|
||||||
|
- Git `rev-parse` : <https://git-scm.com/docs/git-rev-parse> ;
|
||||||
|
- `gix` `0.88.0` : <https://docs.rs/gix/0.88.0/gix/> et <https://docs.rs/crate/gix/0.88.0/features> ;
|
||||||
|
- `git2` `0.21.0` : <https://docs.rs/crate/git2/0.21.0>.
|
||||||
|
|
||||||
|
Ces sources éclairent le choix technique ; elles ne remplacent pas les tests réels de Knowledge.
|
||||||
|
|
||||||
|
## Option A — processus `git` contrôlé
|
||||||
|
|
||||||
|
### Capacités
|
||||||
|
|
||||||
|
Le client Git officiel couvre directement le besoin :
|
||||||
|
|
||||||
|
- `git clone --mirror` produit un repository bare qui mappe l'ensemble des refs et configure leur mise à jour depuis le remote ;
|
||||||
|
- `--no-local` permet d'éviter l'optimisation locale par hardlinks lorsqu'une source est un chemin local ;
|
||||||
|
- `git remote update --prune` rafraîchit le mirror sans créer une logique de forge ;
|
||||||
|
- `git rev-parse --verify --end-of-options <ref>^{commit}` vérifie qu'une référence fournie résout effectivement un commit et évite qu'elle soit interprétée comme une option ;
|
||||||
|
- `git worktree add --detach <path> <revision>` matérialise un arbre de lecture associé exactement à la révision résolue.
|
||||||
|
|
||||||
|
### Sécurité du processus
|
||||||
|
|
||||||
|
Rust `std::process::Command` passe les arguments directement au programme sans shell. Le backend peut donc imposer :
|
||||||
|
|
||||||
|
- `Command::new(...)` vers un exécutable Git réel, jamais `sh -c`, `bash -c`, `cmd.exe` ou un fichier `.bat` ;
|
||||||
|
- un argument par `arg`/`args`, sans concaténation de commande ;
|
||||||
|
- `--end-of-options` ou `--` lorsque la commande Git le permet ;
|
||||||
|
- `GIT_TERMINAL_PROMPT=0` pour empêcher une attente interactive d'un serveur ;
|
||||||
|
- un `current_dir` et des chemins appartenant au backend ;
|
||||||
|
- retrait des variables d'environnement qui peuvent rediriger implicitement un repository (`GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES`) ;
|
||||||
|
- désactivation des hooks via un `core.hooksPath` vide contrôlé pour les opérations pouvant déclencher un hook ;
|
||||||
|
- source locale/remote provenant uniquement de configuration de déploiement privilégiée, jamais d'un paramètre de requête publique ;
|
||||||
|
- rejet des syntaxes de remote-helper exécutables telles que `ext::` et absence de transport arbitraire découvert depuis une entrée utilisateur ;
|
||||||
|
- absence de credentials dans les logs et dans les erreurs publiques.
|
||||||
|
|
||||||
|
Les mécanismes de credentials autorisés restent une responsabilité de déploiement : SSH agent, credential helper ou autre mécanisme Git préconfiguré. Les secrets ne sont pas copiés dans la configuration versionnée de Knowledge.
|
||||||
|
|
||||||
|
### Portabilité et exploitation
|
||||||
|
|
||||||
|
Cette option ajoute un prérequis runtime explicite : un exécutable `git` compatible doit être présent. Elle évite en revanche une nouvelle pile Git native dans Cargo et utilise le comportement du client Git réellement déployé.
|
||||||
|
|
||||||
|
Le backend demeure synchrone au niveau du contrat actuel. Les appels processus sont bloquants et devront être isolés par la couche runtime lorsqu'ils sont déclenchés depuis Actix ; cette isolation ne justifie pas de rendre les crates de contrat async.
|
||||||
|
|
||||||
|
### Testabilité
|
||||||
|
|
||||||
|
Les tests d'intégration peuvent créer un repository temporaire local, y produire plusieurs commits puis exercer exactement la même implémentation que la production sans réseau ni forge publique.
|
||||||
|
|
||||||
|
Une prévalidation locale de cette étude a confirmé avec Git `2.47.3` la séquence :
|
||||||
|
|
||||||
|
```text
|
||||||
|
clone --mirror --no-local
|
||||||
|
resolve refs/heads/main^{commit}
|
||||||
|
remote update --prune
|
||||||
|
resolve nouvelle révision
|
||||||
|
worktree add --detach
|
||||||
|
HEAD du snapshot = révision résolue
|
||||||
|
worktree propre
|
||||||
|
```
|
||||||
|
|
||||||
|
Cette prévalidation assistant ne constitue pas une gate opérateur.
|
||||||
|
|
||||||
|
## Option B — `gix`
|
||||||
|
|
||||||
|
`gix` `0.88.0` fournit une abstraction Rust riche de repository Git. Sa feature matrix couvre notamment révisions, credentials, mutation de worktree et clients réseau bloquants ou async selon configuration.
|
||||||
|
|
||||||
|
Avantages :
|
||||||
|
|
||||||
|
- API Rust et erreurs typées ;
|
||||||
|
- pas de shell ni de dépendance à un exécutable Git pour les opérations couvertes ;
|
||||||
|
- contrôle fin des features ;
|
||||||
|
- bon candidat si Knowledge doit plus tard intégrer profondément des objets Git dans son processus.
|
||||||
|
|
||||||
|
Coûts pour `0.0.2` :
|
||||||
|
|
||||||
|
- surface de features et API sensiblement plus large que le besoin actuel ;
|
||||||
|
- choix supplémentaires pour le transport réseau et son modèle bloquant/async ;
|
||||||
|
- davantage de code d'adaptation à maintenir pour reproduire et tester les détails de comportement attendus du client Git ;
|
||||||
|
- aucune nécessité actuelle ne compense ce coût puisque le produit ne parse pas encore les objets Git lui-même.
|
||||||
|
|
||||||
|
`gix` reste donc une alternative future légitime, pas une option rejetée définitivement.
|
||||||
|
|
||||||
|
## Option C — `git2` / libgit2
|
||||||
|
|
||||||
|
`git2` `0.21.0` expose des bindings Rust vers libgit2. Le support réseau n'est pas activé par défaut ; HTTPS et SSH ajoutent des features et leurs dépendances associées. La crate dépend de `libgit2-sys` et peut construire ou lier libgit2 ; SSH/HTTPS peuvent également introduire libssh2/OpenSSL selon le choix de features.
|
||||||
|
|
||||||
|
Avantages :
|
||||||
|
|
||||||
|
- API Rust mature et erreurs structurées ;
|
||||||
|
- opérations locales, clone et fetch disponibles ;
|
||||||
|
- pas d'exécutable Git requis à l'exécution lorsque toute la pile nécessaire est liée.
|
||||||
|
|
||||||
|
Coûts pour Knowledge :
|
||||||
|
|
||||||
|
- dépendances natives supplémentaires et matrice de transport plus lourde ;
|
||||||
|
- comportement libgit2 à valider séparément du client Git déployé ;
|
||||||
|
- gain insuffisant pour une release qui n'a besoin que d'une matérialisation Git de lecture.
|
||||||
|
|
||||||
|
Cette option n'est pas retenue pour `0.0.2`.
|
||||||
|
|
||||||
|
## Option D — combinaison CLI + crate Git
|
||||||
|
|
||||||
|
Une combinaison pourrait utiliser le CLI pour clone/fetch et une crate pour lire les objets ou préparer les worktrees.
|
||||||
|
|
||||||
|
Elle n'apporte aujourd'hui aucune propriété nécessaire qui ne soit déjà couverte par le CLI. Elle doublerait au contraire les modèles d'erreur, les surfaces de compatibilité et les tests de cohérence.
|
||||||
|
|
||||||
|
Décision : ne pas introduire deux backends avant qu'un besoin concret le démontre.
|
||||||
|
|
||||||
|
## Comparaison
|
||||||
|
|
||||||
|
| Critère | Processus `git` contrôlé | `gix` | `git2` |
|
||||||
|
|--------------------------------|---------------------------------------|-------------------------------------|------------------------------------------|
|
||||||
|
| Fidélité au client Git déployé | directe | élevée mais à valider par opération | libgit2, comportement distinct à valider |
|
||||||
|
| Source locale | oui | oui | oui |
|
||||||
|
| Remote générique | oui | oui avec features réseau | oui avec features réseau |
|
||||||
|
| mirror/fetch | natif et direct | disponible via API/features | disponible via libgit2 |
|
||||||
|
| worktree de lecture | commande native | API/features de mutation | API libgit2 à composer |
|
||||||
|
| Erreurs structurées | wrapper Knowledge nécessaire | natives Rust | natives Rust |
|
||||||
|
| Injection shell | évitée avec `Command` direct | sans shell | sans shell |
|
||||||
|
| Dépendance runtime externe | exécutable Git | aucune pour les chemins couverts | libgit2 et pile native liée/vendored |
|
||||||
|
| Async | opérations bloquantes à isoler | modes bloquant/async selon features | principalement synchrone |
|
||||||
|
| Tests locaux reproductibles | simples avec repositories temporaires | possibles | possibles |
|
||||||
|
| Coût d'intégration `0.0.2` | faible à moyen | moyen à élevé | moyen à élevé |
|
||||||
|
|
||||||
|
## Décision
|
||||||
|
|
||||||
|
`0.0.2` retient **un processus `git` contrôlé** comme première implémentation de `knowledge-git-api`.
|
||||||
|
|
||||||
|
La décision est locale à Knowledge et ne devient pas une règle PGR générale.
|
||||||
|
|
||||||
|
Le backend sera matérialisé dans :
|
||||||
|
|
||||||
|
```text
|
||||||
|
crates/knowledge-git-lib/
|
||||||
|
```
|
||||||
|
|
||||||
|
Cette crate possédera :
|
||||||
|
|
||||||
|
- la configuration physique d'une source Git locale ou remote ;
|
||||||
|
- la racine d'état Git généré ;
|
||||||
|
- l'exécution contrôlée de Git ;
|
||||||
|
- le mirror local ;
|
||||||
|
- refresh/résolution ;
|
||||||
|
- la préparation et validation d'un snapshot de lecture.
|
||||||
|
|
||||||
|
`knowledge-domain-lib` conserve l'identité logique. `knowledge-git-api` conserve le contrat. La composition applicative associera un `SourceId` à une configuration concrète sans faire remonter les chemins ou URLs dans le domaine.
|
||||||
|
|
||||||
|
## Racine d'état et layout retenus
|
||||||
|
|
||||||
|
Les copies Git générées ne résident jamais dans le dépôt source `sasedev-knowledge` ni dans un dépôt éditorial.
|
||||||
|
|
||||||
|
Le backend reçoit une racine d'état explicite, sans défaut implicite dans le workspace :
|
||||||
|
|
||||||
|
```text
|
||||||
|
<git-state-root>/
|
||||||
|
hooks-disabled/
|
||||||
|
repositories/
|
||||||
|
<source-key>.git/
|
||||||
|
snapshots/
|
||||||
|
<source-key>/
|
||||||
|
<resolved-revision>/
|
||||||
|
```
|
||||||
|
|
||||||
|
La future composition runtime pourra alimenter cette racine via une configuration de déploiement telle que `KNOWLEDGE_GIT_STATE_ROOT`, mais `knowledge-git-lib` reçoit un `PathBuf` et ne dépend pas directement d'une variable d'environnement.
|
||||||
|
|
||||||
|
Règles :
|
||||||
|
|
||||||
|
- `source-key` est dérivé de manière sûre par l'implémentation ; ni `SourceId` brut ni URL remote ne sont interpolés comme chemin ;
|
||||||
|
- la racine d'état appartient exclusivement à une instance de backend/processus dans `0.0.2` ; le partage concurrent entre plusieurs processus reste hors contrat tant qu'un mécanisme de verrouillage inter-processus n'est pas matérialisé ;
|
||||||
|
- un snapshot est adressé par la révision réellement résolue par le backend ;
|
||||||
|
- un snapshot existant n'est réutilisé qu'après vérification que son `HEAD` correspond à cette révision et que le worktree est propre ; une divergence est une erreur, pas une suppression silencieuse ;
|
||||||
|
- les credentials ne sont jamais dérivés dans les noms de chemins.
|
||||||
|
|
||||||
|
## Politique de source locale et remote
|
||||||
|
|
||||||
|
Une source locale et une source remote convergent vers le même mirror contrôlé.
|
||||||
|
|
||||||
|
Pour une source locale, l'initialisation utilisera `clone --mirror --no-local` afin d'éviter de rendre la copie contrôlée dépendante des hardlinks/optimisations du repository source.
|
||||||
|
|
||||||
|
Après initialisation, le refresh utilise la configuration du remote du mirror et une mise à jour avec pruning. Le backend ne dépend donc pas d'une API de forge.
|
||||||
|
|
||||||
|
## Résolution de révision
|
||||||
|
|
||||||
|
Une référence configurée reste opaque dans `knowledge-git-api`, mais l'implémentation doit produire une révision qui désigne un commit réel :
|
||||||
|
|
||||||
|
```text
|
||||||
|
git --git-dir=<mirror> rev-parse --verify --end-of-options <reference>^{commit}
|
||||||
|
```
|
||||||
|
|
||||||
|
La sortie validée devient `GitRevision`. Aucun nom de branche ou tag non résolu n'est utilisé comme identité de snapshot.
|
||||||
|
|
||||||
|
## Ownership de synchronisation
|
||||||
|
|
||||||
|
`RepositoryEventSource` reste inchangé : il ne fait qu'émettre des signaux.
|
||||||
|
|
||||||
|
Le cas d'usage partagé qui enchaîne refresh, résolution, comparaison de la précédente révision et préparation du snapshot appartient à la couche application. La candidate existante `knowledge-app-lib` devient donc justifiée lorsque cette orchestration est implémentée ; elle ne sera pas créée en `alpha.1` uniquement comme placeholder.
|
||||||
|
|
||||||
|
En l'absence de PostgreSQL dans `0.0.2`, la dernière révision observée est fournie par l'appelant au cas d'usage puis retournée dans son résultat. Cette release ne crée pas de pseudo-base locale cachée.
|
||||||
|
|
||||||
|
La cause `Periodic` reste supportée par le contrat de signal, mais un scheduler concret est différé tant que son owner runtime/lifecycle n'est pas démontré. Une future source périodique devra appeler le même cas d'usage que la synchronisation explicite.
|
||||||
|
|
||||||
|
## Conséquences pour les prochaines tranches
|
||||||
|
|
||||||
|
`alpha.1` ne modifie aucun contrat Rust fonctionnel : elle ferme les décisions nécessaires et crée le plan.
|
||||||
|
|
||||||
|
La première extension de `knowledge-git-api` sera limitée au besoin démontré de matérialisation d'un snapshot de lecture. Les APIs status/diff/branch/commit/merge/push restent hors scope.
|
||||||
|
|
||||||
|
Le changement de backend reste possible ultérieurement derrière le même contrat si les mesures de maintenance, portabilité ou performance justifient `gix` ou une autre solution.
|
||||||
@@ -1,5 +1,5 @@
|
|||||||
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
|
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
|
||||||
<!-- version: 17 -->
|
<!-- version: 18 -->
|
||||||
|
|
||||||
# Matrice de validation Knowledge
|
# Matrice de validation Knowledge
|
||||||
|
|
||||||
@@ -487,3 +487,35 @@ La candidate finale doit prouver :
|
|||||||
- staging final sans `Cargo.lock` et `git diff --cached --check` propre.
|
- staging final sans `Cargo.lock` et `git diff --cached --check` propre.
|
||||||
|
|
||||||
Un `PASS` de `rc.2` autorise uniquement `0.0.1-rel.1`.
|
Un `PASS` de `rc.2` autorise uniquement `0.0.1-rel.1`.
|
||||||
|
|
||||||
|
|
||||||
|
## Gate de `0.0.2-alpha.1`
|
||||||
|
|
||||||
|
La première tranche de `0.0.2` est documentaire et de gouvernance. Elle doit prouver :
|
||||||
|
|
||||||
|
- `VERSION = 0.0.2-alpha.1` et `[workspace.package].version` identique ;
|
||||||
|
- baseline Knowledge `v0.0.1` identifiée par son commit, SHA-256 d'archive et rapport `publish.001 PASS` ;
|
||||||
|
- adoption PGR `v0.1.3` explicite avec commit, SHA-256 d'archive et rapport `publish.001 PASS` ;
|
||||||
|
- owner `230-ADOPTION` actif uniquement pour la migration du projet existant ;
|
||||||
|
- preservation des références historiques PGR `v0.1.1` dans les artefacts `0.0.1` ;
|
||||||
|
- absence d'activation Java/Maven/Gradle/Android et maintien du `DEFER` Tauri ;
|
||||||
|
- étude comparative Git présente et décision `processus git contrôlé` explicite ;
|
||||||
|
- `knowledge-git-lib` identifiée comme owner futur de la configuration physique/backend sans création prématurée de la crate ;
|
||||||
|
- racine d'état Git explicitement hors dépôt source et layout mirror/snapshot documenté ;
|
||||||
|
- `knowledge-app-lib` seulement comme owner candidat du cas d'usage partagé, sans placeholder ;
|
||||||
|
- aucun diff sous `crates/` ou `Web/` ;
|
||||||
|
- aucun history `0.0.2/alpha.1` présent avant la gate ;
|
||||||
|
- headers, liens Markdown locaux et hygiène texte propres ;
|
||||||
|
- audits Rust existants propres ;
|
||||||
|
- Cargo/Clippy/tests workspace propres malgré le bump de version ;
|
||||||
|
- baseline Web `npm ci`, typecheck et build sans régression ;
|
||||||
|
- `Cargo.lock` toujours ignoré/non suivi et `package-lock.json` toujours versionné ;
|
||||||
|
- `git diff --cached --check` propre avant commit.
|
||||||
|
|
||||||
|
La disponibilité de l'exécutable `git` et sa version sont relevées comme prérequis du backend futur :
|
||||||
|
|
||||||
|
```text
|
||||||
|
git --version
|
||||||
|
```
|
||||||
|
|
||||||
|
`alpha.1` ne prétend pas encore valider `knowledge-git-lib` puisqu'aucune implémentation fonctionnelle n'existe dans cette tranche. La séquence mirror/refresh/resolve/worktree documentée dans l'étude est une prévalidation de conception, pas une gate produit.
|
||||||
|
|||||||
146
history/0.0.2/alpha.1.md
Normal file
146
history/0.0.2/alpha.1.md
Normal file
@@ -0,0 +1,146 @@
|
|||||||
|
<!-- file: history/0.0.2/alpha.1.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# History 0.0.2-alpha.1 — adoption PGR et cadrage Git/synchronisation
|
||||||
|
|
||||||
|
## Statut
|
||||||
|
|
||||||
|
FAIL
|
||||||
|
|
||||||
|
## Baseline opérateur
|
||||||
|
|
||||||
|
La tranche évaluée est :
|
||||||
|
|
||||||
|
```text
|
||||||
|
version 0.0.2-alpha.1
|
||||||
|
delta deltas/0.0.2/alpha.1.md
|
||||||
|
date 2026-09-28
|
||||||
|
```
|
||||||
|
|
||||||
|
Le `FAIL` est documentaire. Les commandes techniques transmises par l'opérateur sont propres, mais la revue du plan actif révèle une structure de pilotage incomplète par rapport au plan historique `0.0.1`.
|
||||||
|
|
||||||
|
## Preuves opérateur observées
|
||||||
|
|
||||||
|
### Version et hygiène initiale
|
||||||
|
|
||||||
|
Les contrôles suivants passent :
|
||||||
|
|
||||||
|
```text
|
||||||
|
VERSION = 0.0.2-alpha.1
|
||||||
|
workspace.package.version = 0.0.2-alpha.1
|
||||||
|
git diff --check = PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
### Audits Rust structurels
|
||||||
|
|
||||||
|
Les sept audits exécutés sont propres :
|
||||||
|
|
||||||
|
```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)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Prérequis Git
|
||||||
|
|
||||||
|
L'exécutable observé est :
|
||||||
|
|
||||||
|
```text
|
||||||
|
git version 2.47.3
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cargo, Clippy et tests
|
||||||
|
|
||||||
|
Les commandes suivantes passent :
|
||||||
|
|
||||||
|
```text
|
||||||
|
cargo fmt --all -- --check PASS
|
||||||
|
cargo metadata --format-version 1 --no-deps PASS
|
||||||
|
cargo check --workspace PASS
|
||||||
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||||
|
PASS
|
||||||
|
cargo test --workspace --all-targets --all-features PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
Résultats de 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 PASS
|
||||||
|
npm run typecheck PASS
|
||||||
|
npm run build PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
`npm ci` ne rapporte aucune vulnérabilité. Le build Vite réussit avec des warnings de dépréciation Sass provenant de Bootstrap ; ces warnings n'empêchent pas la gate de compilation.
|
||||||
|
|
||||||
|
### Scope de la tranche
|
||||||
|
|
||||||
|
Les fichiers attendus sont présents :
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md
|
||||||
|
docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
|
||||||
|
deltas/0.0.2/alpha.1.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Le history `history/0.0.2/alpha.1.md` était absent pendant la gate, conformément au workflow.
|
||||||
|
|
||||||
|
`git diff --name-only -- crates Web` est vide. Aucun code Rust ou frontend n'a donc été modifié par `alpha.1`.
|
||||||
|
|
||||||
|
`git diff --cached --check` est propre.
|
||||||
|
|
||||||
|
Le statut transmis avant création du présent history contient uniquement les fichiers documentaires/configuration annoncés par `alpha.1`.
|
||||||
|
|
||||||
|
## Défaut documentaire observé
|
||||||
|
|
||||||
|
La revue manuelle du plan `docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md` établit que le document ne reprend pas plusieurs éléments structurants déjà présents dans `docs/plans/001-V0_0_1_FOUNDATION_PLAN.md` :
|
||||||
|
|
||||||
|
1. les tranches `alpha.*`, `beta.1`, `rc.1` et `rel.1` sont déclarées comme sections de niveau `##` au lieu d'être des sous-sections `###` de `## Trajectoire prévisionnelle` ;
|
||||||
|
2. la section globale `## Scope` manque ;
|
||||||
|
3. la section `## État acquis et questions ouvertes` manque ;
|
||||||
|
4. la section `## Déclencheurs de REPLAN` manque ;
|
||||||
|
5. la section `## Revue d'horizon` manque ;
|
||||||
|
6. l'ordre général du document ne suit pas le patron de pilotage éprouvé par le plan `0.0.1`.
|
||||||
|
|
||||||
|
Ces défauts diminuent la lisibilité du forecast et surtout la capacité à distinguer mission, scope global, trajectoire par tranche et conditions imposant une replanification.
|
||||||
|
|
||||||
|
Le contenu technique de l'étude Git et les décisions déjà prises ne sont pas invalidés par ce défaut de structure.
|
||||||
|
|
||||||
|
## Contrôles non nécessaires pour établir le FAIL
|
||||||
|
|
||||||
|
Les preuves complémentaires de manifest Vite et les smokes HTTP ne figurent pas dans le résultat opérateur transmis avec cette gate. Elles ne sont pas inventées ni déclarées exécutées.
|
||||||
|
|
||||||
|
Le défaut documentaire ci-dessus suffit à classer la tranche `FAIL` avant sa clôture.
|
||||||
|
|
||||||
|
## Diagnostic
|
||||||
|
|
||||||
|
`alpha.1` doit être corrigée sans avancer vers l'implémentation Git :
|
||||||
|
|
||||||
|
- conserver le delta `alpha.1` et le présent history comme artefacts historiques ;
|
||||||
|
- ne pas modifier les décisions techniques de l'étude `004` sans nouvelle preuve ;
|
||||||
|
- restructurer le plan `0.0.2` sur le patron de `0.0.1` ;
|
||||||
|
- ajouter une gate explicite de structure du plan pour éviter la régression ;
|
||||||
|
- rester hors de `crates/` et `Web/`.
|
||||||
|
|
||||||
|
## Transition
|
||||||
|
|
||||||
|
Après application du présent history :
|
||||||
|
|
||||||
|
1. committer et pousser l'état complet `0.0.2-alpha.1` avec son résultat `FAIL` ;
|
||||||
|
2. appliquer ensuite seulement `0.0.2-alpha.1.fix.1` ;
|
||||||
|
3. ne pas préparer `alpha.2` tant que le fix n'est pas `PASS`.
|
||||||
Reference in New Issue
Block a user