From 89b8ea88c12f2d67b1cf71da088d541323a51f3b Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sun, 27 Sep 2026 11:33:12 +0200 Subject: [PATCH] 0.1.1-alpha.4 --- VERSION | 2 +- deltas/0.1.1/alpha.4.md | 226 ++++++++++++++++++ docs/000-README.md | 3 +- ...007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md | 24 +- docs/rules/550-VITE.md | 80 ++++++- docs/templates/009-WEB_VITE.md | 174 ++++++++++++++ history/0.1.1/alpha.4.md | 90 +++++++ 7 files changed, 587 insertions(+), 12 deletions(-) create mode 100644 deltas/0.1.1/alpha.4.md create mode 100644 docs/templates/009-WEB_VITE.md create mode 100644 history/0.1.1/alpha.4.md diff --git a/VERSION b/VERSION index ae7ab7f..72748ff 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.1-alpha.3.fix.2 +0.1.1-alpha.4 diff --git a/deltas/0.1.1/alpha.4.md b/deltas/0.1.1/alpha.4.md new file mode 100644 index 0000000..e5ec362 --- /dev/null +++ b/deltas/0.1.1/alpha.4.md @@ -0,0 +1,226 @@ + + + +# Delta 0.1.1-alpha.4 — Vite, dev server et outputs + +## Baseline et version + +Baseline attendue : commit opérateur de `0.1.1-alpha.3.fix.2`, réalisé après application de `history/0.1.1/alpha.3.fix.2.md` avec statut `PASS`. + +Le hash de ce commit n'est pas anticipé. + +Version avant application : + +```text +0.1.1-alpha.3.fix.2 +``` + +Version après application : + +```text +0.1.1-alpha.4 +``` + +## Objet + +Compléter l'owner `550-VITE.md` avec un contrat générique de dev server, cache, outputs et assets, puis documenter l'adaptation d'un projet Vite sans inventer un `vite.config.ts` universel. + +La tranche conserve Vite comme recommandation `SHOULD`, pas comme obligation. + +Elle ne modifie pas : + +- la baseline TypeScript/package de `alpha.3` ; +- les règles de déclarations `@types/*` ; +- le profil CSS/Sass réservé à `alpha.5` ; +- le profil Tauri ; +- WASM, backend ou deployment/operations. + +## Décisions matérialisées + +Le contrat Vite distingue désormais explicitement : + +```text +sources versionnées +cache Vite reproductible +outputs build générés +assets sources +assets copiés/transformés +``` + +Le cache et les outputs `SHOULD` rester hors Git et `SHOULD` être externalisés hors de l'arborescence source lorsqu'un emplacement de build externe est raisonnablement disponible. + +`build.emptyOutDir = true` n'est acceptable que sur un répertoire dédié dont Vite possède entièrement le contenu généré. + +Le dev server reste local/loopback par défaut. L'exposition réseau est une décision explicite. `server.allowedHosts = true` et `server.cors = true` ne sont pas des défauts PGR. + +Lorsqu'une intégration dépend d'un port déterministe, le couple `server.port` + `server.strictPort = true` est recommandé. Les ports eux-mêmes restent locaux. + +`vite preview` est classifié comme prévisualisation/smoke local du build, jamais comme serveur de production. + +## Pas de `vite.config.ts` générique artificiel + +La tranche ajoute [`docs/templates/009-WEB_VITE.md`](../../docs/templates/009-WEB_VITE.md), mais aucun fichier copiable `templates/web-vite/vite.config.ts`. + +Cette absence est volontaire : le corpus prouve l'owner et les responsabilités, mais pas une valeur universelle pour `root`, `base`, `cacheDir`, `outDir`, ports, aliases ou plugins. + +Un template exécutable pourra être ajouté ultérieurement si une configuration minimale réellement neutre est démontrée. PGR ne crée pas un fichier vide ou rempli de placeholders uniquement pour satisfaire un catalogue. + +## Scope + +REPLACE : + +```text +VERSION +docs/000-README.md +docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +docs/rules/550-VITE.md +``` + +ADD : + +```text +docs/templates/009-WEB_VITE.md +deltas/0.1.1/alpha.4.md +``` + +DELETE : aucun. + +## Validation opérateur + +Après application du history `PASS`, commit/push de `alpha.3.fix.2`, puis application du présent delta : + +```bash +test "$(cat VERSION)" = '0.1.1-alpha.4' +git cat-file -e HEAD:history/0.1.1/alpha.3.fix.2.md +test -f history/0.1.1/alpha.3.fix.2.md +test -f deltas/0.1.1/alpha.4.md +test ! -e history/0.1.1/alpha.4.md + +grep -A2 '^## Statut$' history/0.1.1/alpha.3.fix.2.md | grep -Fx 'PASS' +grep -Fx '' docs/000-README.md +grep -Fx '' docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +grep -Fx '' docs/rules/550-VITE.md +grep -Fx '' docs/templates/009-WEB_VITE.md + +python3 -B - <<'PYGATE' +from pathlib import Path +import re + +history = Path("history/0.1.1/alpha.3.fix.2.md").read_text(encoding="utf-8") +assert re.search(r"## Statut\s+PASS\s", history) + +vite = Path("docs/rules/550-VITE.md").read_text(encoding="utf-8") +for phrase in ( + "Vite **SHOULD** être le build tool/dev server privilégié", + "PGR ne fournit pas de `vite.config.ts` universel", + "`cacheDir` **SHOULD** être externalisé", + "Le contenu de `build.outDir` est un output généré", + "`build.emptyOutDir = true`", + "`publicDir` est une capacité optionnelle", + "PGR MUST NOT imposer le nom `frontend/`", + "PGR MUST NOT imposer `./`, `/` ou un chemin de sous-répertoire universel", + "Le dev server **SHOULD** rester limité à la machine locale/loopback", + "`server.port` avec `server.strictPort = true`", + "`server.allowedHosts = true` et `server.cors = true` **SHOULD NOT**", + "Il MUST NOT être présenté comme serveur de production", + "le build de production via le package manager choisi **SHOULD** faire partie de la gate", +): + assert phrase in vite, phrase + +guide = Path("docs/templates/009-WEB_VITE.md").read_text(encoding="utf-8") +for phrase in ( + "ne fournit volontairement pas de `vite.config.ts` copiable universel", + '"dev": "vite"', + '"build": "vite build"', + '"preview": "vite preview"', + "typecheck -> tsc --noEmit", + "build -> vite build", + "Le nom `frontend/` observé dans Games est une convention locale", + "PGR ne copie donc pas automatiquement `base: \"./\"`", + "Le cache Vite est reproductible", + "`build.outDir` contient des artefacts générés", + "server.allowedHosts = true", + "server.cors = true", + "server.strictPort true", + "Il ne constitue pas un serveur de production PGR", + "PGR ne livre pas encore de `vite.config.ts` exécutable générique", +): + assert phrase in guide, phrase + +plan = Path("docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md").read_text(encoding="utf-8") +for phrase in ( + "### alpha.3.fix.2 — correction de la gate des déclarations de types", + "Statut opérateur : **PASS**.", + "### alpha.4 — Vite, dev server et outputs", + "sans créer un `vite.config.ts` universel artificiel", + "TypeScript reste validé séparément ; CSS/Sass reste réservé à `alpha.5`.", +): + assert phrase in plan, phrase + +index = Path("docs/000-README.md").read_text(encoding="utf-8") +assert "templates/009-WEB_VITE.md" in index + +assert not Path("templates/web-vite/vite.config.ts").exists() +assert Path("docs/rules/530-TYPESCRIPT.md").read_text(encoding="utf-8").splitlines()[1] == "" +assert Path("docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md").read_text(encoding="utf-8").splitlines()[1] == "" +assert Path("docs/rules/560-CSS_SASS.md").read_text(encoding="utf-8").splitlines()[1] == "" +assert Path("docs/rules/710-TAURI.md").read_text(encoding="utf-8").splitlines()[1] == "" + +print("0.1.1 alpha.4 Vite contract audit: clean (outputs/cache explicit, dev server bounded, no fake universal config, alpha.5 untouched)") +PYGATE + +python3 -B -m unittest discover -s tests -v + +python3 -B scripts/audit_markdown_headers.py \ + README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts +python3 -B scripts/audit_markdown_tables.py \ + README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts +python3 -B scripts/audit_markdown_links.py \ + README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts + +git diff --check + +git add VERSION docs/000-README.md \ + docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md \ + docs/rules/550-VITE.md docs/templates/009-WEB_VITE.md \ + deltas/0.1.1/alpha.4.md + +git diff --cached --check +git status --short +``` + +Le scope indexé attendu avant ajout du history de `alpha.4` est exactement : + +```text +M VERSION +A deltas/0.1.1/alpha.4.md +M docs/000-README.md +M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +M docs/rules/550-VITE.md +A docs/templates/009-WEB_VITE.md +``` + +## Revue opérateur complémentaire + +Confirmer que : + +- Vite reste `SHOULD`, jamais `MUST` universel ; +- aucun package manager n'est imposé ; +- aucun port, host, `base`, alias ou plugin n'est transformé en valeur universelle ; +- aucun `vite.config.ts` artificiellement générique n'est ajouté ; +- cache et outputs sont classifiés comme générés et hors Git ; +- `emptyOutDir` ne peut viser qu'un output dédié ; +- `preview` n'est pas présenté comme serveur de production ; +- TypeScript/package ne sont pas réouverts ; +- CSS/Sass reste réservé à `alpha.5` ; +- Tauri/WASM/deployment restent hors scope. + +## Transition + +### PASS + +Produire `history/0.1.1/alpha.4.md`, l'appliquer puis committer/pousser `alpha.4`. Continuer avec `0.1.1-alpha.5`, consacré à CSS/Sass et à la validation frontend indépendante du host. + +### FAIL + +Consigner le diagnostic réel dans `history/0.1.1/alpha.4.md`, puis produire `alpha.4.fix.N` ou effectuer un REPLAN si le défaut révèle une frontière d'ownership incorrecte. Ne pas absorber `alpha.5` dans un correctif Vite. diff --git a/docs/000-README.md b/docs/000-README.md index 0706f30..afac049 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation PGR @@ -25,6 +25,7 @@ Les templates techniques copiables sous `templates/` restent séparés des instr - [`plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md`](plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md) — plan actif de la fondation frontend Web contrôlée, de l'audit des corpus à la séparation TypeScript/Vite/styles/package/validation. - [`rules/530-TYPESCRIPT.md`](rules/530-TYPESCRIPT.md), [`rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md), [`rules/550-VITE.md`](rules/550-VITE.md) et [`rules/560-CSS_SASS.md`](rules/560-CSS_SASS.md) — owners frontend matérialisés par `0.1.1-alpha.2`, séparant langage typé, écosystème de package, build tool et styles. - [`templates/008-WEB_TYPESCRIPT_PACKAGE.md`](templates/008-WEB_TYPESCRIPT_PACKAGE.md) — adaptation de la baseline minimale `package.json` + `tsconfig.json` de `alpha.3`, sans package manager, versions ou bundler imposés. +- [`templates/009-WEB_VITE.md`](templates/009-WEB_VITE.md) — guide d'adaptation Vite de `alpha.4` : root, dev server, cache, outputs, assets et scripts sans imposer de layout ni de port universels. - [`studies/002-TAURI_SKELETON_DECISION.md`](studies/002-TAURI_SKELETON_DECISION.md) — décision `DEFER` dont `0.1.1` doit satisfaire les prérequis Web sans créer ni autoriser automatiquement le skeleton Tauri. - [`studies/003-V0_1_0_HORIZON_REVIEW.md`](studies/003-V0_1_0_HORIZON_REVIEW.md) — revue ayant engagé `0.1.1` à `0.1.7` et maintenu WASM, serveur Rust et deployment sans réservation prématurée. - [`../prompts/007-V0_1_1_START_PROMPT.md`](../prompts/007-V0_1_1_START_PROMPT.md) — contrat de reprise autoritaire de la release `0.1.1`. diff --git a/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md b/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md index 7448c64..9d2158e 100644 --- a/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +++ b/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md @@ -1,5 +1,5 @@ - + # Plan 0.1.1 — fondation frontend Web contrôlée @@ -385,15 +385,29 @@ La gate spécifique n'a toutefois pas atteint son message final : le littéral P ### alpha.3.fix.2 — correction de la gate des déclarations de types -Corriger uniquement la syntaxe de validation de `alpha.3.fix.1`, sans modifier les règles TypeScript/package, le guide `008-WEB_TYPESCRIPT_PACKAGE.md` ni les templates JSON. +Statut opérateur : **PASS**. -La gate corrigée doit reconfirmer le `FAIL` historique de `alpha.3.fix.1`, les règles de découverte des types externes et la séparation application/bibliothèque, puis rejouer les tests et audits documentaires. Toutes les assertions contenant des apostrophes doivent utiliser des littéraux Python syntaxiquement sûrs. +La gate corrigée atteint son message final, reconfirme le `FAIL` historique de `alpha.3.fix.1`, les règles de découverte des types externes et la séparation application/bibliothèque. Les `48/48` tests et les trois audits Markdown passent, et le scope Git reste limité à `VERSION`, au plan et au delta de correction. + +Aucune règle TypeScript/package ni aucun template n'a été modifié par le fix. La trajectoire reprend donc normalement avec Vite. ### alpha.4 — Vite, dev server et outputs -Matérialiser l'owner Vite et le contrat de séparation entre sources, cache, outputs de production et assets copiés. Les sorties de build doivent avoir un statut explicite de versionnement/ignorance et éviter de polluer l'arborescence source lorsque le projet peut raisonnablement les externaliser. +Matérialiser le contrat Vite sans créer un `vite.config.ts` universel artificiel : les chemins `root`, `cacheDir`, `build.outDir`, la valeur `base`, les ports, aliases, plugins et intégrations de host dépendent du layout réel du projet. -Les paramètres de port, host, aliases et intégrations particulières restent locaux sauf preuve générique contraire. +Le profil doit en revanche fixer les responsabilités génériques suivantes : + +- distinguer sources versionnées, cache reproductible et outputs de build générés ; +- garder cache et outputs hors Git, en les externalisant hors de l'arborescence source lorsque cela reste raisonnable ; +- considérer `publicDir` comme une source statique optionnelle et les copies présentes dans `outDir` comme générées ; +- n'utiliser `build.emptyOutDir = true` que lorsque `outDir` est un répertoire dédié et possédé sans ambiguïté par le build ; +- garder le dev server local/loopback par défaut et n'élargir l'écoute réseau que pour un besoin explicite ; +- rendre port + `strictPort` déterministes lorsqu'un host ou un smoke dépend d'une URL fixe ; +- éviter les ouvertures globales de `allowedHosts` ou CORS sans justification ; +- réserver `vite preview` à la prévisualisation locale d'un build et non à un serveur de production ; +- ajouter Vite au manifest réel comme outil de développement et exposer `dev` / `build` / `preview` seulement lorsqu'ils correspondent au workflow réel. + +Les paramètres de port, host, `base`, aliases, plugins, découpage d'assets et intégrations particulières restent locaux sauf preuve générique contraire. TypeScript reste validé séparément ; CSS/Sass reste réservé à `alpha.5`. ### alpha.5 — CSS/Sass et validation frontend diff --git a/docs/rules/550-VITE.md b/docs/rules/550-VITE.md index a1e8f40..5df1230 100644 --- a/docs/rules/550-VITE.md +++ b/docs/rules/550-VITE.md @@ -1,5 +1,5 @@ - + # Profil Vite @@ -31,15 +31,81 @@ Lorsque Vite est sélectionné, cet owner possède notamment : - la copie/transformation d'assets configurée par Vite ou ses plugins ; - les paramètres Vite nécessaires à l'intégration avec un host, sans posséder le host lui-même. -Les ports, hosts réseau, aliases, plugins et conventions de nommage d'assets restent des décisions locales tant qu'aucune règle plus générale n'est démontrée. +Le manifest et le package manager restent possédés par [`540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md). Lorsque Vite est sélectionné, le manifest réel **SHOULD** normalement déclarer Vite comme dépendance de développement avec une version décidée par le projet et MAY exposer les scripts `dev`, `build` et `preview` correspondant au workflow réel. + +Un script Vite n'absorbe pas l'ownership du type-check TypeScript, de Sass, d'une génération WASM ou du host. + +## Configuration et décisions locales + +PGR ne fournit pas de `vite.config.ts` universel à ce stade. Une configuration copiable qui figerait arbitrairement le layout source, les chemins de build, le port, le `base`, les aliases ou les plugins transformerait des décisions locales en règles génériques. + +Le projet qui sélectionne Vite doit donc décider explicitement, lorsqu'ils sont pertinents : + +```text +root +base +publicDir +cacheDir +build.outDir +build.assetsDir +build.emptyOutDir +server.host +server.port +server.strictPort +preview.host / preview.port / preview.strictPort +aliases +plugins +``` + +Le guide [`../templates/009-WEB_VITE.md`](../templates/009-WEB_VITE.md) décrit comment adapter ces choix sans imposer de valeurs universelles. ## Sources, cache et outputs Les sources frontend versionnées, le cache de développement et les outputs de production sont des catégories différentes. -Le cache et les sorties de build reproductibles SHOULD rester hors Git. Pour les projets contrôlés, ils SHOULD être placés hors de l'arborescence source lorsque cela reste simple, reproductible et compatible avec la toolchain ; sinon ils doivent au minimum être ignorés explicitement. +Le cache Vite est un artefact reproductible. Il **SHOULD** rester hors Git. Pour les projets contrôlés, `cacheDir` **SHOULD** être externalisé hors de l'arborescence source lorsque cela reste simple et compatible avec la toolchain ; sinon le chemin retenu MUST être ignoré explicitement. -Le détail du contrat `root`, `cacheDir`, `outDir`, assets et dev server est réservé à `0.1.1-alpha.4`. +Le contenu de `build.outDir` est un output généré. Il **SHOULD** rester hors Git et **SHOULD** être externalisé hors de l'arborescence source lorsque cela reste raisonnable. Un projet qui conserve `dist/` ou un autre `outDir` interne MUST l'ignorer explicitement sauf artefact publié exceptionnellement et gouverné comme tel. + +`build.emptyOutDir = true` ne doit être activé explicitement que lorsque le répertoire ciblé est dédié aux outputs Vite et que sa suppression complète avant build est sûre. Il MUST NOT pointer vers un répertoire partagé contenant des artefacts appartenant à d'autres owners. + +Le nom exact de `outDir` et de `cacheDir` reste local au projet. + +## Assets et `publicDir` + +Un asset source importé/référencé par le frontend reste un source versionné selon la politique du projet. Sa copie, transformation ou version hashée dans `build.outDir` est générée et ne doit pas être traitée comme un second source. + +`publicDir` est une capacité optionnelle. Lorsqu'elle est utilisée, son contenu source est servi/copied tel quel par Vite ; les copies produites dans `outDir` restent des outputs générés. Un projet MAY définir `publicDir: false` lorsqu'il n'a pas besoin de cette voie d'assets statiques. + +Un plugin de copie statique MAY être utilisé lorsqu'il répond à un besoin réel. Il ne change pas l'ownership du fichier source copié et ne rend pas ce plugin obligatoire pour les autres projets. + +Le découpage final des assets (`assets/`, `js/`, `css/`, `fonts/`, images ou autre) reste local tant qu'aucune contrainte commune ne le justifie. + +## `root` et `base` + +`root` désigne la racine frontend comprise par Vite. PGR MUST NOT imposer le nom `frontend/` à tous les projets uniquement parce que Games l'utilise. Si les sources ne résident pas à la racine du package, le projet **SHOULD** rendre cette frontière explicite dans sa configuration. + +`base` dépend du mode de déploiement ou d'embarquement. PGR MUST NOT imposer `./`, `/` ou un chemin de sous-répertoire universel. Un host embarqué, un site servi à la racine et un déploiement sous sous-chemin peuvent légitimement demander des valeurs différentes. + +## Dev server + +Le dev server **SHOULD** rester limité à la machine locale/loopback lorsqu'aucun accès externe n'est requis. + +L'écoute sur toutes les interfaces ou l'exposition au LAN **MAY** être activée pour un besoin explicite de test, de device ou d'intégration. Elle doit alors être traitée comme une décision réseau réelle et non comme un défaut PGR. + +Les ports sont locaux au projet. Lorsqu'aucun consommateur ne dépend d'un port fixe, Vite MAY conserver son comportement normal de sélection. Lorsqu'un host, un smoke ou une autre intégration dépend d'une URL déterministe, le projet **SHOULD** configurer explicitement `server.port` avec `server.strictPort = true` afin d'échouer plutôt que de dériver silencieusement vers un autre port. + +`server.allowedHosts = true` et `server.cors = true` **SHOULD NOT** être utilisés comme raccourcis génériques. Une ouverture réseau ou CORS large doit être justifiée et bornée selon le besoin réel. + +Les réglages HMR/WebSocket, proxy, TLS et file-system allowlists restent locaux à l'intégration qui les exige. + +## Preview + +`vite preview` MAY servir de smoke local du build de production lorsqu'il apporte une preuve utile. + +Il MUST NOT être présenté comme serveur de production. Le déploiement/serving de production appartient à l'owner de deployment/operations ou au host concerné, hors scope de `0.1.1`. + +Un port de preview fixe MAY être utilisé lorsqu'un smoke automatisé en dépend ; dans ce cas `preview.strictPort = true` est recommandé pour obtenir une failure déterministe. ## Validation @@ -51,4 +117,8 @@ Une validation Vite ciblée prouve le contrat de build/dev tool de Vite ; elle n - la validation du host Tauri ; - une génération WASM possédée par un autre owner. -`alpha.4` précisera les commandes et artefacts génériques applicables. +Pour un projet réel ayant sélectionné Vite, le build de production via le package manager choisi **SHOULD** faire partie de la gate lorsqu'un changement touche Vite, ses entrées ou ses outputs. + +Le script `typecheck` TypeScript **SHOULD** rester exécutable indépendamment. Une CI MAY exécuter `typecheck` puis `build` comme deux preuves distinctes plutôt que d'enfouir la première dans un script spécifique à un package manager. + +Le guide [`../templates/009-WEB_VITE.md`](../templates/009-WEB_VITE.md) complète ce profil. diff --git a/docs/templates/009-WEB_VITE.md b/docs/templates/009-WEB_VITE.md new file mode 100644 index 0000000..ea6fdbe --- /dev/null +++ b/docs/templates/009-WEB_VITE.md @@ -0,0 +1,174 @@ + + + +# Guide d'adaptation Vite + +## Rôle + +Ce document accompagne le profil [`550-VITE.md`](../rules/550-VITE.md) lorsqu'un projet sélectionne réellement Vite. + +Il ne fournit volontairement pas de `vite.config.ts` copiable universel. Les corpus montrent une responsabilité réutilisable claire pour Vite, mais pas des valeurs universelles pour les chemins, ports, aliases, plugins ou hosts. + +L'objectif est donc de normaliser **ce qui doit être décidé et validé**, sans figer arbitrairement **la valeur de chaque décision**. + +## Manifest + +Le manifest réel du projet doit utiliser le package manager choisi par le projet et ajouter Vite comme outil de développement avec une version explicitement décidée. + +Les scripts usuels, lorsqu'ils correspondent au workflow réel, sont conceptuellement : + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build", + "preview": "vite preview" + } +} +``` + +Ce fragment n'est pas un template complet de `package.json` et ne sélectionne aucun package manager. + +`dev` et `build` sont naturels lorsqu'un frontend Vite existe. `preview` MAY être omis si aucun smoke/prévisualisation locale ne l'utilise. + +Le type-check TypeScript reste une preuve séparée : + +```text +typecheck -> tsc --noEmit +build -> vite build +``` + +Une CI peut exécuter successivement ces deux scripts sans imposer une syntaxe npm particulière. + +## Décider `root` + +Si `index.html` et les sources se trouvent à la racine comprise par Vite, aucune valeur explicite n'est nécessaire uniquement pour respecter PGR. + +Si le package contient une racine frontend dédiée, le projet doit configurer `root` vers cette racine. Le nom `frontend/` observé dans Games est une convention locale utile mais pas une obligation générique. + +## Décider `base` + +`base` doit suivre le mode réel de service/embarquement : + +```text +site servi à la racine souvent / +site sous un sous-chemin chemin public correspondant +host embarqué valeur relative si réellement requise +``` + +PGR ne copie donc pas automatiquement `base: "./"` depuis Games dans tous les projets Vite. + +## Cache + +Le cache Vite est reproductible et ne doit pas devenir un source versionné. + +Ordre de préférence PGR : + +1. placer `cacheDir` hors de l'arborescence source lorsqu'un emplacement de build externe existe déjà et reste simple à utiliser ; +2. sinon accepter un cache interne dédié et l'ignorer explicitement ; +3. ne jamais versionner le cache uniquement pour accélérer une machine locale. + +L'effacement du cache doit rester sans conséquence fonctionnelle autre qu'un recalcul. + +## Output de production + +`build.outDir` contient des artefacts générés. + +Ordre de préférence PGR : + +1. utiliser un répertoire de build externe au source tree si l'environnement du projet le permet proprement ; +2. sinon utiliser un répertoire interne dédié, tel que `dist/`, explicitement ignoré ; +3. ne versionner un output que si un autre contrat de distribution l'exige réellement et documente cet artefact comme livrable. + +Si `build.emptyOutDir` est activé, `outDir` doit être dédié à Vite. Le build ne doit pas pouvoir vider un répertoire partagé avec du WASM, des artefacts Rust, Android ou d'autres owners. + +## Assets + +Trois catégories doivent rester distinguées : + +```text +asset source importé/référencé source versionné +asset source dans publicDir source statique versionné +asset copié/transformé dans outDir output généré +``` + +`publicDir` MAY rester au défaut Vite, être déplacé ou être désactivé avec `false` selon le besoin du projet. + +Une copie réalisée par plugin n'autorise pas à supprimer la source de son owner ni à versionner la copie de build comme second source. + +## Dev server et exposition réseau + +Pour un développement local simple, rester sur une écoute locale/loopback est préférable. + +N'élargir `server.host` au LAN/toutes interfaces que lorsqu'un besoin réel l'impose, par exemple un test sur device ou un host externe. Dans ce cas, revoir aussi les contraintes de hosts autorisés, CORS, TLS, proxy et HMR selon l'intégration réelle. + +PGR déconseille les raccourcis globaux : + +```text +server.allowedHosts = true +server.cors = true +``` + +Ils ne doivent pas devenir des valeurs de template universelles. + +## Ports déterministes + +Un port fixe n'est pas une règle PGR universelle. + +Si rien ne consomme une URL déterministe, laisser Vite gérer son port peut être suffisant. + +Si un host ou un smoke attend un port connu, utiliser ensemble : + +```text +server.port valeur locale choisie +server.strictPort true +``` + +Ainsi, un conflit de port échoue explicitement au lieu de déplacer silencieusement le dev server. + +La même logique peut s'appliquer à `preview.port` + `preview.strictPort` lorsqu'un smoke de preview exige une URL stable. + +## Preview + +`vite preview` sert à vérifier localement le build produit. Il ne constitue pas un serveur de production PGR. + +Un smoke MAY lancer `preview` après un build lorsque cette observation apporte une preuve nécessaire. Le deployment/serving réel reste hors du présent owner. + +## Ce qui reste local + +La configuration suivante n'est pas normalisée par ce guide sans preuve supplémentaire : + +```text +ports exacts +host exact +base exact +aliases +plugins +noms de chunks/assets +minification +sourcemaps +proxy +TLS +HMR / WebSocket +filesystem allowlists +intégration WASM +intégration Tauri +``` + +Games fournit des exemples utiles pour plusieurs de ces points, mais PGR ne transforme pas ces valeurs en défauts génériques. + +## Validation dans PGR et dans un projet destinataire + +PGR ne livre pas encore de `vite.config.ts` exécutable générique dans cette tranche ; il n'installe donc pas Vite uniquement pour valider un fichier fictif. + +Dans un projet réel qui adopte ce profil, la gate applicable doit sélectionner l'outil réel et peut comprendre : + +```text +typecheck séparé +build Vite de production +inspection du outDir attendu +preview/smoke seulement si nécessaire +validation du host séparée +``` + +Les commandes concrètes passent par le package manager sélectionné par le projet. Un exemple npm dans une documentation tierce ne devient pas une obligation PGR. diff --git a/history/0.1.1/alpha.4.md b/history/0.1.1/alpha.4.md new file mode 100644 index 0000000..21fd304 --- /dev/null +++ b/history/0.1.1/alpha.4.md @@ -0,0 +1,90 @@ + + + +# History 0.1.1-alpha.4 — Vite, dev server et outputs + +## Statut + +PASS + +La gate opérateur de `0.1.1-alpha.4` exécutée le `2026-09-27` est `PASS`. + +La tranche précédente `0.1.1-alpha.3.fix.2` avait été clôturée, committée sous `56e3d37` puis poussée sur `origin/master` avant application du delta `alpha.4`. + +## Contrôles structurels + +Les préconditions et versions documentaires attendues ont été confirmées : + +```text +VERSION 0.1.1-alpha.4 +history/0.1.1/alpha.3.fix.2.md présent dans HEAD et PASS +deltas/0.1.1/alpha.4.md présent +history/0.1.1/alpha.4.md absent pendant la gate +docs/000-README.md version 27 +docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md version 7 +docs/rules/550-VITE.md version 2 +docs/templates/009-WEB_VITE.md version 1 +``` + +La gate spécifique Vite a atteint son message final : + +```text +0.1.1 alpha.4 Vite contract audit: clean (outputs/cache explicit, dev server bounded, no fake universal config, alpha.5 untouched) +``` + +Elle a notamment reconfirmé : + +- Vite comme recommandation `SHOULD`, non obligation universelle ; +- l'absence volontaire de `templates/web-vite/vite.config.ts` générique ; +- la séparation sources / cache / outputs ; +- `cacheDir` et `build.outDir` comme artefacts générés hors Git ; +- l'usage borné de `build.emptyOutDir = true` ; +- `publicDir` comme capacité optionnelle ; +- l'absence de layout, `base`, port, alias ou plugin universel ; +- le dev server limité à loopback par défaut ; +- `server.port` + `server.strictPort = true` lorsqu'une URL déterministe est réellement requise ; +- l'absence d'ouverture globale `allowedHosts` / CORS par défaut ; +- `vite preview` comme prévisualisation locale et non serveur de production ; +- le maintien de TypeScript/package hors du scope de la tranche ; +- le maintien de CSS/Sass pour `alpha.5`. + +## Tests et audits + +La suite Python globale a exécuté `48` tests : + +```text +Ran 48 tests in 0.720s + +OK +``` + +Les audits Markdown ont affiché : + +```text +Markdown header audit: clean (218 file(s)) +Markdown table audit: clean (9 table(s), 218 file(s)) +Markdown link audit: clean (234 local link(s), 218 file(s)) +``` + +`git diff --check` et `git diff --cached --check` n'ont produit aucune erreur. + +## Scope observé + +Le scope indexé final était exactement : + +```text +M VERSION +A deltas/0.1.1/alpha.4.md +M docs/000-README.md +M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +M docs/rules/550-VITE.md +A docs/templates/009-WEB_VITE.md +``` + +Aucun fichier TypeScript/package, CSS/Sass, Tauri ou WASM n'a été absorbé dans la tranche. + +## Conclusion + +`0.1.1-alpha.4` est validée `PASS`. + +La transition autorisée est `0.1.1-alpha.5`, consacrée à CSS/Sass et à la validation frontend indépendante du host. La création d'un skeleton frontend n'est autorisée que si les owners `530/540/550/560` et la validation réutilisable permettent une composition sans ownership caché.