From fd3d363bff19cdf366c22103ceebf3b0fb87d10c Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sun, 27 Sep 2026 23:00:24 +0200 Subject: [PATCH] 0.0.1-alpha.3.fix.1 --- CHANGELOG.md | 4 +- Cargo.lock | 6 +- Cargo.toml | 4 +- README.md | 11 +- ROADMAP.md | 4 +- RULES.md | 12 +- VERSION | 2 +- crates/knowledge-domain-lib/src/source.rs | 4 +- crates/knowledge-domain-lib/src/unit_tests.rs | 9 +- deltas/0.0.1/alpha.3.fix.1.md | 246 ++++++++++++++++++ docs/000-README.md | 3 +- docs/architecture/001-PROJECT_PROFILE.md | 12 +- .../002-KNOWLEDGE_ARCHITECTURE.md | 30 ++- docs/plans/001-V0_0_1_FOUNDATION_PLAN.md | 26 +- .../002-ACTIX_MAUD_VITE_CORPUS_STUDY.md | 119 +++++++++ docs/validation/001-VALIDATION_MATRIX.md | 20 +- history/0.0.1/alpha.3.fix.1.md | 143 ++++++++++ 17 files changed, 625 insertions(+), 30 deletions(-) create mode 100644 deltas/0.0.1/alpha.3.fix.1.md create mode 100644 docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md create mode 100644 history/0.0.1/alpha.3.fix.1.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f1e7960..f0e93c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,5 @@ - + # Changelog SaseDev Knowledge @@ -17,5 +17,7 @@ Ce fichier décrit les changements utiles des releases publiées. Les détails d - instancie le workspace Rust/Cargo strict avec une première crate de domaine et une politique explicite de `Cargo.lock` versionné ; - introduit les premiers contrats provider-neutral de source, Git et synchronisation sans dépendance à une forge ni à PostgreSQL ; - active les audits Rust PGR de structure et de façade au moment où des API publiques réelles apparaissent ; +- fixe le frontend Web PGR comme laboratoire de validation des templates statiques et des assets avant adaptation du markup runtime en Maud ; +- retient l’intégration production Actix/Maud via le manifest Vite comme contrat d’asset mapping à réimplémenter proprement, sans copier mécaniquement le corpus historique ; - conserve comme corpus d'inspiration séparé les archives historiques `actix-auth-app` et `amahil-project`, sans importer leurs fonctionnalités inachevées comme exigences ; - prépare un workspace Rust et une baseline Web composables sans construire prématurément la plateforme complète. diff --git a/Cargo.lock b/Cargo.lock index 068c24e..44941b0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,18 +4,18 @@ version = 4 [[package]] name = "knowledge-domain-lib" -version = "0.0.1-alpha.3" +version = "0.0.1-alpha.3.fix.1" [[package]] name = "knowledge-git-api" -version = "0.0.1-alpha.3" +version = "0.0.1-alpha.3.fix.1" dependencies = [ "knowledge-domain-lib", ] [[package]] name = "knowledge-sync-api" -version = "0.0.1-alpha.3" +version = "0.0.1-alpha.3.fix.1" dependencies = [ "knowledge-domain-lib", ] diff --git a/Cargo.toml b/Cargo.toml index a5fc25e..5c5b6b6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ # file: Cargo.toml -# version: 2 +# version: 3 [workspace] resolver = "3" @@ -10,7 +10,7 @@ members = [ ] [workspace.package] -version = "0.0.1-alpha.3" +version = "0.0.1-alpha.3.fix.1" edition = "2024" publish = false repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge" diff --git a/README.md b/README.md index ef66d86..413b506 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # SaseDev Knowledge @@ -33,6 +33,14 @@ Chaque application Web doit pouvoir exposer sa propre surface d'administration p Le workspace Rust matérialise désormais trois frontières passives avant toute implémentation technique : `knowledge-domain-lib` pour les identités de famille/source, `knowledge-git-api` pour le contrat Git générique et `knowledge-sync-api` pour les signaux de synchronisation. Ces deux crates `-api` sont justifiées par des implémentations remplaçables ou multiples ; elles ne dépendent ni d'Actix, ni de Gitea, ni de PostgreSQL. +## Frontend de référence et rendu Maud + +Knowledge adopte le profil Web PGR comme partie obligatoire de la fondation : Vite, TypeScript, Sass et Bootstrap servent à développer, prévisualiser et valider les assets et templates statiques de référence indépendamment des serveurs Actix. + +Ces templates statiques sont un **harness de conception/validation**, pas le moteur de rendu de production. Le markup runtime des trois applications sera adapté en Maud. Les assets produits par Vite restent consommables par les pages Maud. En production, l’intégration devra résoudre les sorties hashées depuis le manifest Vite ; en développement, un dev server Vite peut fournir les entrées directement. Les URL, ports, chemins de ressources et API Rust exacts restent différés jusqu’aux tranches Web/serveur. + +Le mécanisme observé dans `actix-auth-app` est documenté comme corpus technique à adapter, pas comme code autoritaire à copier. + ## Invariants de fondation - Git est la source autoritaire du contenu versionné. @@ -54,6 +62,7 @@ Le workspace Rust matérialise désormais trois frontières passives avant toute - [`docs/architecture/001-PROJECT_PROFILE.md`](docs/architecture/001-PROJECT_PROFILE.md) — baseline PGR, profils/skeletons et matrice de décisions ; - [`docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md`](docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md) — architecture de fondation multi-app Git/forge/PostgreSQL et frontières de contenu ; - [`docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md) — étude des deux corpus historiques auth/admin et décisions de réutilisation conceptuelle ; +- [`docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md`](docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md) — étude ciblée du pattern Vite manifest / Actix / Maud à adapter pour Knowledge ; - [`docs/plans/001-V0_0_1_FOUNDATION_PLAN.md`](docs/plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan vivant de `0.0.1` ; - [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation ; - [`prompts/001-V0_0_1_START_PROMPT.md`](prompts/001-V0_0_1_START_PROMPT.md) — prompt de démarrage autoritaire de la release. diff --git a/ROADMAP.md b/ROADMAP.md index 890f022..4b1573c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap SaseDev Knowledge @@ -9,7 +9,7 @@ Statuts : `( )` planifié, `(x)` terminé, `(d)` différé, `(c)` annulé. ## Fondation -- `( ) 0.0.1` — fondation Knowledge : gouvernance PGR, workspace à trois applications Actix Web, architecture Git/forge/PostgreSQL partagé, frontières PGR/HOWTO/snippet, surfaces d'administration locales protégées, workspace Rust minimal, premiers contrats et baseline Web reproductible sans implémentation fonctionnelle disproportionnée. +- `( ) 0.0.1` — fondation Knowledge : gouvernance PGR, workspace à trois applications Actix Web, architecture Git/forge/PostgreSQL partagé, frontières PGR/HOWTO/snippet, surfaces d'administration locales protégées, workspace Rust minimal, premiers contrats et baseline Web reproductible servant à valider templates/assets statiques avant adaptation Maud et intégration des assets via manifest Vite, sans implémentation fonctionnelle disproportionnée. ## Domaines futurs non numérotés diff --git a/RULES.md b/RULES.md index 327842b..0f938e4 100644 --- a/RULES.md +++ b/RULES.md @@ -1,5 +1,5 @@ - + # Règles SaseDev Knowledge @@ -157,6 +157,16 @@ Sous réserve des décisions différées et de la matérialisation par tranche, Ces choix ne sont pas présentés comme des règles PGR universelles. +## Contrat frontend statique / Maud + +Le skeleton Web PGR `003-WEB_FRONTEND` et sa validation associée sont obligatoires pour `0.0.1`. Le frontend contrôlé doit utiliser la chaîne réellement sélectionnée TypeScript + Vite + Sass + Bootstrap pour valider indépendamment du backend les assets, comportements client et templates statiques de référence. + +Les templates statiques servent de support de conception, prévisualisation et validation navigateur. Ils MUST NOT devenir silencieusement une seconde implémentation runtime divergente : le HTML servi en production par les applications Actix est rendu avec Maud, et toute adaptation depuis le template de référence doit préserver explicitement les contrats utiles de structure, classes, attributs et assets. + +Le build Vite de production MUST produire un mapping machine-readable des entrées hashées, typiquement le manifest Vite. L’intégration Actix/Maud MUST résoudre ses URLs d’assets depuis ce mapping plutôt que coder les noms hashés. En mode développement, un dev server Vite MAY fournir les entrées directement. Les origins, ports, préfixes de ressources et chemins de manifest MUST être configurables ou possédés explicitement par la configuration réelle ; ils ne doivent pas être copiés comme constantes depuis un corpus historique. + +Le pattern de loader observé dans `actix-auth-app` est un corpus d’inspiration. Sa reprise doit être réévaluée selon les règles Rust Knowledge : pas de `panic!`/`unwrap`/`expect`, erreurs récupérables, API minimale, tests ciblés et séparation claire entre debug/dev et production. + ## Rust et crates Le préfixe de crate retenu est `knowledge-`. diff --git a/VERSION b/VERSION index 4450b18..85e44d7 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.1-alpha.3 +0.0.1-alpha.3.fix.1 diff --git a/crates/knowledge-domain-lib/src/source.rs b/crates/knowledge-domain-lib/src/source.rs index ba8879f..df4fe4c 100644 --- a/crates/knowledge-domain-lib/src/source.rs +++ b/crates/knowledge-domain-lib/src/source.rs @@ -1,5 +1,5 @@ // file: crates/knowledge-domain-lib/src/source.rs -// version: 1 +// version: 2 //! Source identities independent of repository and forge providers. @@ -30,7 +30,7 @@ impl crate::SourceId { if value.trim().is_empty() { return Err(crate::SourceIdError::Empty); } - return Ok(crate::SourceId(value.to_owned())); + return Ok(Self(value.to_owned())); } /// Return the identifier as text. diff --git a/crates/knowledge-domain-lib/src/unit_tests.rs b/crates/knowledge-domain-lib/src/unit_tests.rs index e4e9d10..a61b160 100644 --- a/crates/knowledge-domain-lib/src/unit_tests.rs +++ b/crates/knowledge-domain-lib/src/unit_tests.rs @@ -1,5 +1,5 @@ // file: crates/knowledge-domain-lib/src/unit_tests.rs -// version: 1 +// version: 2 #[test] fn source_id_rejects_empty_values() { @@ -7,6 +7,13 @@ fn source_id_rejects_empty_values() { return; } +#[test] +fn source_id_constructs_and_exposes_valid_values() { + let source_id = crate::SourceId::new("pgr"); + assert_eq!(source_id.as_ref().map(crate::SourceId::as_str), Ok("pgr")); + return; +} + #[test] fn content_sources_are_not_limited_to_three_repositories() { let sources = [ diff --git a/deltas/0.0.1/alpha.3.fix.1.md b/deltas/0.0.1/alpha.3.fix.1.md new file mode 100644 index 0000000..d3a5370 --- /dev/null +++ b/deltas/0.0.1/alpha.3.fix.1.md @@ -0,0 +1,246 @@ + + + +# Delta 0.0.1-alpha.3.fix.1 — correction `SourceId` et précision Web/Maud + +## Base requise + +État `0.0.1-alpha.3` committé et poussé après application du history : + +```text +history/0.0.1/alpha.3.md = FAIL +``` + +La version devient : + +```text +0.0.1-alpha.3.fix.1 +``` + +## Cause du fix + +La gate `alpha.3` échoue avec `E0423` parce que `SourceId::new` construit le tuple struct privé via son re-export crate-root : + +```text +crate::SourceId(value.to_owned()) +``` + +Le type est public via re-export, mais son champ privé reste possédé par le module `source`. Le fix construit donc la valeur depuis le scope de l'implémentation avec : + +```text +Self(value.to_owned()) +``` + +Aucune visibilité de champ n'est élargie et aucune nouvelle API publique n'est ajoutée. + +## Régression ajoutée + +`knowledge-domain-lib` reçoit un test direct qui prouve qu'un identifiant valide : + +```text +SourceId::new("pgr") +``` + +est construit et expose ensuite `pgr` via `as_str()`. + +Les tests précédents restent inchangés dans leur intention : rejet de l'identifiant vide et absence de limite codée à trois sources. + +## Précision Web/Maud + +Une précision de trajectoire fournie avant clôture de `alpha.3` est intégrée au plan vivant sans démarrer le frontend : + +- le skeleton PGR `003-WEB_FRONTEND` est obligatoire pour `0.0.1` ; +- Vite + TypeScript + Sass + Bootstrap servent notamment de laboratoire indépendant pour les templates statiques de référence et les assets ; +- le markup runtime est ensuite adapté et rendu en Maud par les serveurs Actix ; +- le build de production Vite doit produire un manifest d'entrées hashées ; +- l'intégration Actix/Maud consommera ce mapping au lieu de coder des noms hashés ; +- le pattern de `actix-auth-app` est étudié comme corpus, pas copié mécaniquement. + +La séparation de scope reste : + +```text +alpha.4 -> frontend indépendant, templates statiques, assets, manifest Vite +alpha.5 -> Actix Web, Maud, résolution du manifest et intégration runtime +``` + +Aucun `package.json`, frontend, serveur Actix, loader Rust Vite ou dépendance Web n'est ajouté par le présent fix. + +## Corpus Vite étudié + +Le nouveau document : + +```text +docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md +``` + +consigne le pattern réellement observé dans : + +```text +actix-auth-app-master.zip +SHA-256 bcdf4c568c827b77c70ee476218c2b07ea0fca408ab87d2f044333309d19ab71 +``` + +Il distingue le contrat réutilisable des détails à ne pas importer tels quels, notamment : origin `localhost:5173`, préfixe `/res`, `panic!` sur manifest invalide, arborescence d'assets et dépendances TypeScript non justifiées. + +## Fichier Rust corrigé + +```text +crates/knowledge-domain-lib/src/source.rs +crates/knowledge-domain-lib/src/unit_tests.rs +``` + +## Documentation remplacée + +```text +CHANGELOG.md +Cargo.toml +README.md +ROADMAP.md +RULES.md +VERSION +docs/000-README.md +docs/architecture/001-PROJECT_PROFILE.md +docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +docs/plans/001-V0_0_1_FOUNDATION_PLAN.md +docs/validation/001-VALIDATION_MATRIX.md +``` + +## Documentation ajoutée + +```text +docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md +deltas/0.0.1/alpha.3.fix.1.md +``` + +Aucun fichier n'est supprimé. + +## `Cargo.lock` + +Le delta ne livre pas de `Cargo.lock` préfabriqué. Les trois packages héritent de la nouvelle version workspace `0.0.1-alpha.3.fix.1`; la toolchain opérateur doit donc régénérer le lockfile réel et sa modification doit être incluse au staging du fix si Cargo l'actualise. + +## Validation attendue + +Après application du history `alpha.3 FAIL`, commit/push de `alpha.3`, puis extraction du présent delta : + +```bash +test "$(cat VERSION)" = "0.0.1-alpha.3.fix.1" + +git diff --check + +python3 - <<'PY' +from pathlib import Path +import tomllib + +with Path("Cargo.toml").open("rb") as handle: + root_manifest = tomllib.load(handle) + +assert root_manifest["workspace"]["package"]["version"] == "0.0.1-alpha.3.fix.1" +assert set(root_manifest["workspace"]["members"]) == { + "crates/knowledge-domain-lib", + "crates/knowledge-git-api", + "crates/knowledge-sync-api", +} + +source = Path("crates/knowledge-domain-lib/src/source.rs").read_text(encoding="utf-8") +tests = Path("crates/knowledge-domain-lib/src/unit_tests.rs").read_text(encoding="utf-8") +study = Path("docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md").read_text(encoding="utf-8") +plan = Path("docs/plans/001-V0_0_1_FOUNDATION_PLAN.md").read_text(encoding="utf-8") +rules = Path("RULES.md").read_text(encoding="utf-8") + +assert "return Ok(Self(value.to_owned()));" in source +assert "return Ok(crate::SourceId(value.to_owned()));" not in source +assert "source_id_constructs_and_exposes_valid_values" in tests +assert 'SourceId::new("pgr")' in tests + +for phrase in ( + "build.manifest = true", + "src/app/vite.rs", + "dev -> URL d’entrée Vite directe", + "release -> entrée stable -> manifest Vite -> URL d’asset hashé", + "http://localhost:5173", +): + assert phrase in study, phrase + +for phrase in ( + "### alpha.4 — baseline Web indépendante et templates de référence", + "### alpha.5 — composition Actix/Maud et manifest Vite", +): + assert phrase in plan, phrase + +for phrase in ( + "Le skeleton Web PGR `003-WEB_FRONTEND`", + "Le build Vite de production MUST produire", + "le HTML servi en production par les applications Actix est rendu avec Maud", +): + assert phrase in rules, phrase + +for forbidden in ( + "package.json", + "vite.config.ts", + "crates/knowledge-pgr-server", + "crates/knowledge-howtos-server", + "crates/knowledge-snippets-server", + "crates/knowledge-web-lib", + "migrations", +): + assert not Path(forbidden).exists(), forbidden + +print("Knowledge 0.0.1-alpha.3.fix.1 structural audit: clean") +PY + +cargo metadata --format-version 1 --no-deps \ + > /tmp/sasedev-knowledge-alpha3-fix1-metadata.json + +cargo fmt --all +cargo fmt --all -- --check + +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 . + +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings + +cargo test -p knowledge-domain-lib --all-targets --all-features +cargo test -p knowledge-git-api --all-targets --all-features +cargo test -p knowledge-sync-api --all-targets --all-features + +test -f Cargo.lock +if git check-ignore -q Cargo.lock; then + echo 'Cargo.lock must remain versioned' >&2 + exit 1 +fi + +python3 - <<'PY' +import json +from pathlib import Path + +metadata = json.loads( + Path("/tmp/sasedev-knowledge-alpha3-fix1-metadata.json").read_text(encoding="utf-8") +) + +packages = {package["name"] for package in metadata["packages"]} +assert packages == { + "knowledge-domain-lib", + "knowledge-git-api", + "knowledge-sync-api", +}, packages + +for package in metadata["packages"]: + assert package["version"] == "0.0.1-alpha.3.fix.1", ( + package["name"], + package["version"], + ) + +print("Knowledge 0.0.1-alpha.3.fix.1 Cargo metadata audit: clean") +PY + +git add -A +git diff --cached --check +git status --short +``` + +Ne pas committe `alpha.3.fix.1` avant production de son history à partir des résultats opérateur. diff --git a/docs/000-README.md b/docs/000-README.md index 22dfbea..cf706bf 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation SaseDev Knowledge @@ -15,6 +15,7 @@ ## Études - [`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. ## Plans diff --git a/docs/architecture/001-PROJECT_PROFILE.md b/docs/architecture/001-PROJECT_PROFILE.md index e31e93b..11149e9 100644 --- a/docs/architecture/001-PROJECT_PROFILE.md +++ b/docs/architecture/001-PROJECT_PROFILE.md @@ -1,5 +1,5 @@ - + # Profil du projet Knowledge @@ -74,10 +74,12 @@ Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont p | Maud | `KEEP-LOCAL` | rendu SSR initial lorsque pertinent | | TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale | | Package manager frontend | `DEFER` | choisir dans la tranche Web avant création du manifest/lockfile | -| Vite | `KEEP-LOCAL` + owner `550` adopté | choix local cohérent avec la recommandation PGR ; configuration à décider dans la tranche Web | -| Sass | `KEEP-LOCAL` + owner `560` adopté | choix local ; compilation intégrée à la chaîne Web si elle apporte la valeur attendue | -| Bootstrap | `KEEP-LOCAL` | framework CSS local, jamais règle PGR/Tauri/Web universelle | -| Racine(s) frontend | `DEFER` | décider dans la tranche Web selon le partage réel entre les trois applications | +| 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 | +| 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 | +| Bootstrap | `KEEP-LOCAL` | framework CSS retenu pour les templates de référence et le rendu Maud ; jamais règle PGR universelle | +| Racine(s) frontend | `DEFER` | décider en `alpha.4` selon le partage réel entre les trois applications et leurs templates de référence | +| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; le markup runtime est adapté et servi par Maud | +| Intégration manifest Vite / Maud | `KEEP-LOCAL` | mapping d’assets hashés requis en production ; API Rust exacte différée jusqu’à la composition serveur | | Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle | | Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel | | Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré | diff --git a/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md b/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md index 05c45a2..b8e693e 100644 --- a/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +++ b/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md @@ -1,5 +1,5 @@ - + # Architecture de fondation Knowledge @@ -238,6 +238,34 @@ Actix Web et Maud sont des choix de composition/rendu locaux. Vite gère les ass La stratégie exacte de partage des assets/frontend entre les trois applications reste `DEFER` jusqu'à la tranche Web : un package commun n'est créé que si du code/assets sont réellement communs. +### Pipeline Web de référence et rendu runtime + +Le frontend Web n’est pas une SPA concurrente du SSR Maud. Il possède deux responsabilités distinctes : + +```text +Vite + TypeScript + Sass + Bootstrap + -> assets construits et templates statiques de référence + -> typecheck/build/preview/smoke indépendants du backend + +Actix Web + Maud + -> markup runtime des trois applications + -> consommation des mêmes contrats d’assets +``` + +Les templates statiques de référence permettent de travailler rapidement sur le HTML, le responsive, les classes Bootstrap, les comportements TypeScript et les styles Sass sans démarrer les serveurs Rust. Ils sont ensuite adaptés en composants/templates Maud pour le rendu runtime. Cette adaptation ne doit pas créer deux produits UI indépendants : la tranche Web devra définir les invariants vérifiables qui empêchent la dérive entre référence statique et rendu Maud. + +Le build production Vite doit exposer un manifest permettant au backend de convertir une clé d’entrée stable en URL d’asset hashé. Le corpus `actix-auth-app` montre un pattern utile : manifest Vite activé, entrées TypeScript/Sass explicites, loader Rust et sélection dev-server versus manifest en fonction du mode. Knowledge retient le **contrat d’intégration**, pas l’implémentation historique telle quelle. + +En particulier, Knowledge ne doit pas hériter mécaniquement : + +- d’un origin Vite `localhost:5173` codé en dur ; +- d’un préfixe `/res` universel ; +- d’un `panic!` lorsque le manifest est absent ou invalide ; +- d’une arborescence d’assets spécifique au corpus ; +- de dépendances TypeScript `@types/*` non justifiées par les packages réellement consommés. + +`alpha.4` possède le frontend indépendant et la production du manifest. `alpha.5` possède l’intégration Actix/Maud et doit décider si le loader d’assets devient une crate/lib partagée entre les trois serveurs. + ## 10. Administration L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité. diff --git a/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md b/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md index 66f7b9a..a03b354 100644 --- a/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md +++ b/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md @@ -1,5 +1,5 @@ - + # Plan 0.0.1 — fondation SaseDev Knowledge @@ -126,7 +126,13 @@ Le skeleton `002-RUST_CARGO_WORKSPACE` est matérialisé avec `knowledge-domain- ### alpha.3 — contrats domaine/Git/synchronisation -Introduire uniquement les premiers contrats/types nécessaires aux frontières `GitRepository`, source/famille de contenu et synchronisation, avec tests ciblés. Le modèle doit supporter au moins les trois sources initiales sans coder une limite à trois. +Statut opérateur initial : **FAIL**. + +La gate valide la structure et les audits puis échoue dans `knowledge-domain-lib` : `SourceId::new` tente de construire le tuple struct privé via le re-export crate-root depuis son sous-module. Le même défaut bloque `cargo check`, Clippy et les trois suites ciblées. + +`alpha.3.fix.1` corrige ce défaut Rust, ajoute une régression directe de construction `SourceId` et précise la trajectoire Web/Maud fournie avant clôture de la tranche ; il ne démarre aucune implémentation frontend ou serveur. + +Le scope fonctionnel de `alpha.3` reste : introduire uniquement les premiers contrats/types nécessaires aux frontières `GitRepository`, source/famille de contenu et synchronisation, avec tests ciblés. Le modèle doit supporter au moins les trois sources initiales sans coder une limite à trois. Matérialiser `knowledge-git-api` et `knowledge-sync-api` parce que ces frontières ont des implémentations réellement remplaçables/multiples. Garder ces crates passives ; ne pas créer `knowledge-git-lib`, worker, Gitea ou persistence par anticipation. @@ -134,15 +140,19 @@ Adopter les audits Rust PGR de structure/façade désormais utiles avec les prem Ne pas ajouter d'API Gitea ni de persistance PostgreSQL par anticipation. -### alpha.4 — baseline Web indépendante +### alpha.4 — baseline Web indépendante et templates de référence -Instancier le skeleton `003-WEB_FRONTEND` : choisir package manager et lockfile, TypeScript strict, Vite, Sass et Bootstrap réellement nécessaires, avec typecheck/build indépendants du backend. +Instancier obligatoirement le skeleton `003-WEB_FRONTEND` : choisir package manager et lockfile, TypeScript strict, Vite, Sass et Bootstrap, avec typecheck/build indépendants du backend. -Décider à cette tranche si les trois applications partagent un package d'assets/frontend ou possèdent des entrées séparées. Ne pas dupliquer par défaut, ne pas imposer non plus un frontend unique sans preuve de réutilisation. +Le frontend sert d’abord de laboratoire de templates statiques : développer et valider indépendamment le markup de référence, les comportements TypeScript, le responsive Bootstrap et les styles Sass avant adaptation du markup runtime en Maud. Les pages statiques ne deviennent pas une seconde UI de production. -### alpha.5 — composition des trois serveurs minimale +Activer le manifest de build Vite et définir des clés d’entrée stables pour les assets réellement destinés aux pages Maud. Les outputs restent générés/hors Git conformément à PGR. -Matérialiser le minimum Actix Web/Maud nécessaire pour prouver trois launchers minces : +Décider à cette tranche si les trois applications partagent un package d'assets/frontend ou possèdent des entrées séparées. Ne pas dupliquer par défaut, ne pas imposer non plus un frontend unique sans preuve de réutilisation. Définir également une preuve minimale contre la dérive entre templates statiques de référence et future adaptation Maud. + +### alpha.5 — composition Actix/Maud et manifest Vite + +Matérialiser le minimum Actix Web/Maud nécessaire pour prouver trois launchers minces et intégrer les assets produits par `alpha.4` : ```text knowledge-pgr-server @@ -152,6 +162,8 @@ knowledge-snippets-server Ils doivent composer les mêmes contrats/bibliothèques lorsque la responsabilité est partagée et rester capables de recevoir des configurations de sources Git distinctes. +Le HTML runtime est rendu avec Maud. En développement, la composition MAY cibler le dev server Vite configuré ; en production, elle MUST résoudre les assets hashés via le manifest Vite ou un mapping équivalent produit par la chaîne Web. Le pattern de `actix-auth-app` est à adapter sous les règles Knowledge, notamment sans `panic!` et sans origin/port codé en dur. + La tranche ne doit pas introduire admin complète, auth complète, persistance métier complète ni forge obligatoire. ### beta.1 — réconciliation de fondation diff --git a/docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md b/docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md new file mode 100644 index 0000000..1866999 --- /dev/null +++ b/docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md @@ -0,0 +1,119 @@ + + + +# Étude Actix/Maud/Vite — corpus `actix-auth-app` + +## Objet + +Cette étude extrait uniquement le pattern d’intégration frontend/backend observé dans l’archive historique inachevée : + +```text +actix-auth-app-master.zip +SHA-256 bcdf4c568c827b77c70ee476218c2b07ea0fca408ab87d2f044333309d19ab71 +``` + +Le corpus n’est pas une baseline autoritaire et son code n’est pas copié tel quel. L’objectif est de cadrer la future composition Knowledge entre : + +- templates statiques et assets validés par le profil Web PGR ; +- rendu SSR Maud ; +- serveur Actix Web ; +- assets Vite hashés en production. + +## Pattern effectivement observé + +### Build Vite + +Le fichier `frontend/vite.config.ts` observé : + +- utilise `frontend/` comme root ; +- configure un dev server sur le port `5173` ; +- utilise une base de production `/res` ; +- produit dans `../public/res` ; +- active `build.manifest = true` ; +- déclare des entrées TypeScript et Sass explicites ; +- produit des noms JS/CSS hashés ; +- copie plusieurs familles d’assets statiques avec `vite-plugin-static-copy` ; +- utilise `sass-embedded`. + +Ces choix prouvent qu’un build Vite peut servir de pipeline d’assets pour un backend SSR. Ils ne rendent ni `/res`, ni le port `5173`, ni cette arborescence normatifs pour Knowledge. + +### Loader Rust + +Le module `src/app/vite.rs` observé charge `.vite/manifest.json` en release et expose un `Loader::entry_url(entry_key, fallback)`. Une entrée stable du type `ts/main.ts` ou `sass/main.scss` est ainsi convertie vers un fichier hashé du build. + +Le loader existe aussi en debug, mais son manifest reste absent et `entry_url` renvoie alors un fallback. Les handlers choisissent de leur côté des URLs directes du dev server Vite en debug et la résolution par manifest en release. + +### Composition Maud + +Les handlers Actix construisent le markup avec Maud puis injectent les URLs CSS/JS selon le mode : + +```text +dev -> URL d’entrée Vite directe +release -> entrée stable -> manifest Vite -> URL d’asset hashé +``` + +Le pattern démontre que Vite et Maud ne sont pas concurrents : Vite possède la chaîne d’assets/client, tandis que Maud possède le markup runtime. + +## Éléments à reprendre conceptuellement + +Knowledge retient pour ses futures tranches Web/serveur : + +1. un frontend validable indépendamment des serveurs Rust ; +2. des templates statiques de référence pour travailler le markup et les assets ; +3. TypeScript, Sass et Bootstrap consommés par la chaîne Vite sélectionnée ; +4. un build de production avec manifest ; +5. des clés d’entrée stables indépendantes des noms hashés ; +6. un composant Rust commun capable de résoudre ces clés pour les pages Maud ; +7. une voie de développement utilisant le dev server Vite lorsqu’elle est utile ; +8. une gate d’intégration distincte prouvant que le backend résout réellement les sorties du build. + +## Éléments à ne pas copier mécaniquement + +Le corpus contient plusieurs décisions locales ou incompatibles avec les règles Knowledge : + +- `http://localhost:5173` est codé directement dans plusieurs fichiers ; +- `/res` est traité comme convention locale ; +- le loader panique en release lorsqu’un manifest est absent/invalide ; +- l’arborescence et les copies d’assets sont spécifiques à l’application ; +- `@types/node` et `@types/bootstrap` existent dans le package mais doivent être réévalués selon les usages TypeScript réels ; +- le package utilise un alias npm `rolldown-vite`, choix qui n’est pas adopté automatiquement par Knowledge ; +- la présence de plusieurs fallbacks statiques peut masquer une divergence si elle n’est pas testée explicitement. + +Knowledge devra donc adapter le pattern avec erreurs récupérables et observables, configuration explicite, tests et dépendances justifiées. + +## Contrat retenu pour `0.0.1` + +### `alpha.4` + +La tranche Web possède : + +- choix explicite du package manager et du lockfile ; +- TypeScript strict et script `typecheck` ; +- Vite ; +- Sass ; +- Bootstrap ; +- templates statiques de référence ; +- build de production ; +- manifest Vite ; +- preview/smoke navigateur seulement lorsqu’une propriété runtime le justifie. + +Elle ne possède pas encore le rendu Maud ni la lecture Rust du manifest. + +### `alpha.5` + +La tranche de composition serveur possède : + +- trois launchers Actix Web minces ; +- rendu Maud ; +- intégration avec les assets construits par `alpha.4` ; +- résolution production par manifest ; +- configuration de la voie dev Vite si conservée ; +- tests/smokes ciblés de l’intégration. + +La décision de créer ou non un `knowledge-web-lib` commun dépendra du code réellement partagé entre les trois serveurs. + +## Source de vérité UI + +Les templates statiques sont des artefacts de **référence et validation**, pas une deuxième application à servir en production. Le markup runtime est Maud. + +La tranche Web devra définir une méthode proportionnée pour limiter la dérive entre les deux représentations : par exemple contrats de classes/attributs critiques, snapshots ciblés ou smokes navigateur. La méthode exacte reste `DEFER` jusqu’à `alpha.4`; PGR n’impose pas une duplication exhaustive ni un framework de test particulier. diff --git a/docs/validation/001-VALIDATION_MATRIX.md b/docs/validation/001-VALIDATION_MATRIX.md index 257934f..a786bcb 100644 --- a/docs/validation/001-VALIDATION_MATRIX.md +++ b/docs/validation/001-VALIDATION_MATRIX.md @@ -1,5 +1,5 @@ - + # Matrice de validation Knowledge @@ -89,7 +89,9 @@ STYLES preuve séparée uniquement si le build ne prouve pas déjà la compilati SMOKE navigateur seulement lorsqu'une propriété runtime le justifie ``` -La gate frontend reste exécutable indépendamment du backend autant que la topologie réelle le permet. +La gate frontend reste exécutable indépendamment du backend autant que la topologie réelle le permet. Les templates statiques de référence appartiennent à cette gate : leur rôle est de prouver le design/markup/assets côté Web avant adaptation Maud, pas de prouver le rendu Actix. + +Lorsque Vite est sélectionné pour les assets réellement servis par Maud, la gate de production doit également prouver l’émission d’un manifest parsable et la présence des clés d’entrée attendues. Une gate d’intégration Actix/Maud distincte prouve ensuite que ces clés sont résolues sans coder les noms hashés. Si plusieurs entrées/frontend existent pour PGR, HOWTOs et snippets, la gate doit couvrir chacune des entrées modifiées sans forcer trois builds identiques lorsqu'un package commun possède réellement les assets partagés. @@ -180,3 +182,17 @@ La tranche doit prouver : - hygiène Git et headers documentaires/code applicables. L'audit `audit_rust_const_blocks.py` n'appartient pas à la gate globale de cette tranche. + +## Gate de `0.0.1-alpha.3.fix.1` + +Le fix doit prouver : + +- `VERSION = 0.0.1-alpha.3.fix.1` et version workspace identique ; +- history `alpha.3` `FAIL` committé avant application du fix ; +- construction valide de `SourceId` depuis son module sans contourner la visibilité du tuple struct ; +- test de régression direct `SourceId::new("pgr")` + tests précédents ; +- audits Rust PGR sélectionnés propres ; +- `cargo check`, Clippy strict et les trois suites ciblées `PASS` ; +- aucune dépendance ou crate fonctionnelle Web/Actix/PostgreSQL/Gitea ajoutée ; +- trajectoire Web documentée : skeleton Web PGR obligatoire en `alpha.4`, templates statiques de référence, rendu runtime Maud, manifest Vite produit côté frontend et intégration Actix/Maud seulement en `alpha.5` ; +- hygiène Git et documentation propres. diff --git a/history/0.0.1/alpha.3.fix.1.md b/history/0.0.1/alpha.3.fix.1.md new file mode 100644 index 0000000..c3f148e --- /dev/null +++ b/history/0.0.1/alpha.3.fix.1.md @@ -0,0 +1,143 @@ + + + +# History 0.0.1-alpha.3.fix.1 — correction `SourceId` et précision Web/Maud + +## Statut + +FAIL + +La gate opérateur de `0.0.1-alpha.3.fix.1` exécutée le `2026-09-27` confirme la correction de `SourceId` et le passage des tests ciblés, mais Clippy strict échoue sur la documentation manquante des variantes publiques de `ContentFamily`. + +## Baseline opérateur + +La tranche `alpha.3` `FAIL` a été historisée, committée et poussée avant application du fix : + +```text +history/0.0.1/alpha.3.md = FAIL +commit 6b6bdcf +message 0.0.1-alpha.3 +branch master +push origin/master PASS +status clean après push +``` + +Le push observé a avancé `origin/master` de `8cd187b` à `6b6bdcf`. + +## Correction `SourceId` + +La vérification ciblée confirme que le fix attendu est présent : + +```text +return Ok(Self(value.to_owned())); +``` + +L'erreur de compilation `E0423` observée sur `alpha.3` n'est plus reproduite. + +## Structure et audits + +Les contrôles suivants sont propres : + +```text +VERSION = 0.0.1-alpha.3.fix.1 +git diff --check = clean +cargo fmt --all -- --check = PASS +Rust blank-line audit: clean (8 file(s)) +Rust item-spacing audit: clean (8 file(s)) +Rust module-order audit: clean (8 file(s)) +Rust trait-import-block audit: clean (8 file(s)) +Rust re-export-block audit: clean (8 file(s)) +Rust export completeness audit: 0 candidate(s) across 3 package(s) +``` + +## `cargo check` + +`cargo check --workspace` termine avec succès pour les trois crates. + +Il émet cependant quatre warnings `missing_docs` dans : + +```text +crates/knowledge-domain-lib/src/content_family.rs +``` + +sur les variantes publiques : + +```text +Pgr +Howto +Snippet +ProjectLocal +``` + +La politique workspace déclare `missing_docs = "warn"`, donc ces diagnostics restent des warnings sous `cargo check`. + +## Échec Clippy strict + +La commande : + +```text +cargo clippy --workspace --all-targets --all-features -- -D warnings +``` + +transforme les warnings `missing_docs` en erreurs, comme attendu par la gate stricte. + +Les quatre variantes publiques non documentées empêchent donc le `PASS` de tranche. + +Le défaut ne doit pas être contourné par un `allow(missing_docs)` ni par une réduction de la politique de lint ; les items publics doivent être documentés. + +## Tests ciblés + +Les tests passent malgré les warnings documentaires : + +```text +knowledge-domain-lib : 3 passed; 0 failed +knowledge-git-api : 1 passed; 0 failed +knowledge-sync-api : 1 passed; 0 failed +``` + +Les preuves confirment notamment : + +- construction valide de `SourceId` ; +- rejet d'un identifiant vide ; +- absence de limite codée à trois repositories ; +- indépendance du contrat Git vis-à-vis d'une forge ; +- caractère non autoritaire de `ExternalSignal`. + +## Scope Git observé + +`git diff --cached --check` est propre. + +Le staging transmis avant ajout du présent history contient : + +```text +M CHANGELOG.md +M Cargo.lock +M Cargo.toml +M README.md +M ROADMAP.md +M RULES.md +M VERSION +M crates/knowledge-domain-lib/src/source.rs +M crates/knowledge-domain-lib/src/unit_tests.rs +A deltas/0.0.1/alpha.3.fix.1.md +M docs/000-README.md +M docs/architecture/001-PROJECT_PROFILE.md +M docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +M docs/plans/001-V0_0_1_FOUNDATION_PLAN.md +A docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md +M docs/validation/001-VALIDATION_MATRIX.md +``` + +Ce scope est cohérent avec le fix annoncé et le `Cargo.lock` régénéré par Cargo. + +## Décision + +`0.0.1-alpha.3.fix.1` est `FAIL`. + +La transition autorisée est : + +```text +0.0.1-alpha.3.fix.2 +``` + +Le second fix doit rester minimal : documenter les quatre variantes publiques de `ContentFamily`, conserver la politique `missing_docs`, puis rejouer `cargo check`, Clippy strict et les trois suites ciblées. Aucun élargissement fonctionnel n'est autorisé.