@ogygie/cli 0.15.0 → 0.17.0

package/dist/cli.js

@@ -15200,6 +15200,50 @@ function checkProject(deps) {
   return problems;
 }
 
+// src/commands/generate.ts
+import { createRequire } from "node:module";
+import { join as join5 } from "node:path";
+import { pathToFileURL } from "node:url";
+var GENERATE_CLI_ENTRY = "@ogygie/generate/cli";
+var GenerateNotResolved = class extends Error {
+};
+async function loadGenerateFrom(projectRoot) {
+  const resolveFromProject = createRequire(join5(projectRoot, "package.json"));
+  let entryPoint;
+  try {
+    entryPoint = resolveFromProject.resolve(GENERATE_CLI_ENTRY);
+  } catch (thrown) {
+    throw new GenerateNotResolved(thrown instanceof Error ? thrown.message : String(thrown));
+  }
+  return await import(pathToFileURL(entryPoint).href);
+}
+async function runGenerate(deps) {
+  const importGenerate = deps.importGenerate ?? (() => loadGenerateFrom(deps.projectRoot));
+  let generator;
+  try {
+    generator = await importGenerate();
+  } catch (thrown) {
+    const reason = thrown instanceof Error ? thrown.message : String(thrown);
+    if (thrown instanceof GenerateNotResolved) {
+      throwOgygieError({
+        code: "GENERATE_NOT_INSTALLED",
+        message: "The Ogygie generator is not installed in this project.",
+        file: "package.json",
+        cause: `${GENERATE_CLI_ENTRY} cannot be resolved: ${reason}`,
+        suggestedFix: `The generator is experimental (spec ogygie-generate): until its promotion it lives in the framework repo as packages/ogygie-generate \u2014 add it to the workspace as @ogygie/generate (workspace:*) there, or wait for the published package at the framework's version (${deps.cliVersion}, lockstep D2).`
+      });
+    }
+    throwOgygieError({
+      code: "GENERATE_LOAD_FAILED",
+      message: "The Ogygie generator is installed but could not be loaded.",
+      file: "package.json",
+      cause: reason,
+      suggestedFix: "Reinstalling will not help. The package ships as TypeScript source until its promotion: run the command through a TypeScript host (`pnpm ogygie:generate`, `pnpm ogygie:verify-generation`, or `pnpm exec tsx` on the CLI entry), and check that @ogygie/generate matches @ogygie/cli (lockstep D2)."
+    });
+  }
+  return generator.runGenerateCommand({ projectRoot: deps.projectRoot, argv: deps.argv, log: deps.log, error: deps.error });
+}
+
 // src/commands/init.ts
 import {
   existsSync as existsSync5,
@@ -15209,16 +15253,16 @@ import {
   statSync,
   writeFileSync as writeFileSync3
 } from "node:fs";
-import { dirname as dirname2, join as join5 } from "node:path";
+import { dirname as dirname2, join as join6 } from "node:path";
 var PRODUCT_NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 var RENAMED_TEMPLATE_FILES = {
   gitignore: ".gitignore"
 };
 function listTemplateFiles(root, folder = "") {
   const files = [];
-  for (const entry of readdirSync(join5(root, folder)).sort()) {
+  for (const entry of readdirSync(join6(root, folder)).sort()) {
     const relativePath = folder === "" ? entry : `${folder}/${entry}`;
-    if (statSync(join5(root, relativePath)).isDirectory()) {
+    if (statSync(join6(root, relativePath)).isDirectory()) {
       files.push(...listTemplateFiles(root, relativePath));
     } else {
       files.push(relativePath);
@@ -15243,12 +15287,12 @@ function initProject(deps, productName2) {
       suggestedFix: "Pick a kebab-case name, e.g. `ogygie init order-desk`."
     });
   }
-  if (existsSync5(join5(deps.targetDir, MANIFEST_FILE_NAME))) {
+  if (existsSync5(join6(deps.targetDir, MANIFEST_FILE_NAME))) {
     throwOgygieError({
       code: "OGYGIE_INIT_TARGET_NOT_EMPTY",
       message: `The target directory already hosts an Ogygie project (${MANIFEST_FILE_NAME} found).`,
       file: MANIFEST_FILE_NAME,
-      cause: `${join5(deps.targetDir, MANIFEST_FILE_NAME)} exists`,
+      cause: `${join6(deps.targetDir, MANIFEST_FILE_NAME)} exists`,
       suggestedFix: "Run `pnpm ogygie upgrade` in that project instead of init."
     });
   }
@@ -15262,12 +15306,12 @@ function initProject(deps, productName2) {
       suggestedFix: "Start from an empty directory (only a .git folder is tolerated)."
     });
   }
-  const projectTemplates = join5(deps.templatesDir, "project");
+  const projectTemplates = join6(deps.templatesDir, "project");
   const writtenFiles = [];
   for (const templateRelativePath of listTemplateFiles(projectTemplates)) {
-    const content = readFileSync5(join5(projectTemplates, templateRelativePath), "utf8").replaceAll("__PRODUCT_NAME__", productName2).replaceAll("__OGYGIE_VERSION__", deps.cliVersion);
+    const content = readFileSync5(join6(projectTemplates, templateRelativePath), "utf8").replaceAll("__PRODUCT_NAME__", productName2).replaceAll("__OGYGIE_VERSION__", deps.cliVersion);
     const targetRelativePath = targetPathOf(templateRelativePath);
-    const absoluteTarget = join5(deps.targetDir, targetRelativePath);
+    const absoluteTarget = join6(deps.targetDir, targetRelativePath);
     mkdirSync2(dirname2(absoluteTarget), { recursive: true });
     writeFileSync3(absoluteTarget, content);
     writtenFiles.push(targetRelativePath);
@@ -15284,14 +15328,14 @@ function initProject(deps, productName2) {
 }
 
 // src/commands/studio.ts
-import { createRequire } from "node:module";
-import { join as join6 } from "node:path";
-import { pathToFileURL } from "node:url";
+import { createRequire as createRequire2 } from "node:module";
+import { join as join7 } from "node:path";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
 var PUBLISHED_STUDIO_SERVER = "@ogygie/studio/server";
 async function loadStudioFrom(projectRoot) {
-  const resolveFromProject = createRequire(join6(projectRoot, "package.json"));
+  const resolveFromProject = createRequire2(join7(projectRoot, "package.json"));
   const entryPoint = resolveFromProject.resolve(PUBLISHED_STUDIO_SERVER);
-  return await import(pathToFileURL(entryPoint).href);
+  return await import(pathToFileURL2(entryPoint).href);
 }
 function isModuleNotFound(thrown) {
   const code = thrown?.code;
@@ -15329,14 +15373,14 @@ async function runStudio(deps) {
 
 // src/commands/mcp.ts
 import { readFileSync as readFileSync6 } from "node:fs";
-import { createRequire as createRequire2 } from "node:module";
-import { join as join7 } from "node:path";
-import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { createRequire as createRequire3 } from "node:module";
+import { join as join8 } from "node:path";
+import { pathToFileURL as pathToFileURL3 } from "node:url";
 var PUBLISHED_MCP_SERVER = "@ogygie/mcp/server";
 async function loadMcpFrom(projectRoot) {
-  const resolveFromProject = createRequire2(join7(projectRoot, "package.json"));
+  const resolveFromProject = createRequire3(join8(projectRoot, "package.json"));
   const entryPoint = resolveFromProject.resolve(PUBLISHED_MCP_SERVER);
-  return await import(pathToFileURL2(entryPoint).href);
+  return await import(pathToFileURL3(entryPoint).href);
 }
 function isModuleNotFound2(thrown) {
   const code = thrown?.code;
@@ -15377,7 +15421,7 @@ async function runMcp(deps) {
 
 // src/commands/upgrade.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname3, join as join8 } from "node:path";
+import { dirname as dirname3, join as join9 } from "node:path";
 
 // src/version.ts
 function compareVersions(a, b) {
@@ -15425,7 +15469,7 @@ async function upgradeProject(deps) {
   for (const governed of governedFiles) {
     const expected = installedChecksums[governed.targetPath];
     if (expected === void 0) continue;
-    const absolutePath = join8(deps.projectRoot, governed.targetPath);
+    const absolutePath = join9(deps.projectRoot, governed.targetPath);
     const actual = existsSync6(absolutePath) ? sha256Hex(readFileSync7(absolutePath, "utf8")) : "<absent>";
     if (actual !== expected) {
       throwOgygieError({
@@ -15441,10 +15485,10 @@ async function upgradeProject(deps) {
   const diffBlocks = [];
   for (const governed of governedFiles) {
     const content = readFileSync7(
-      join8(deps.templatesDir, governed.templatePath),
+      join9(deps.templatesDir, governed.templatePath),
       "utf8"
     );
-    const absolutePath = join8(deps.projectRoot, governed.targetPath);
+    const absolutePath = join9(deps.projectRoot, governed.targetPath);
     const current = existsSync6(absolutePath) ? readFileSync7(absolutePath, "utf8") : "";
     const diff = diffLines(current, content);
     if (diff !== "") {
@@ -15465,7 +15509,7 @@ ${diff}`);
       };
     }
     for (const write of plannedWrites) {
-      const absolutePath = join8(deps.projectRoot, write.targetPath);
+      const absolutePath = join9(deps.projectRoot, write.targetPath);
       mkdirSync3(dirname3(absolutePath), { recursive: true });
       writeFileSync4(absolutePath, write.content);
     }
@@ -15487,7 +15531,7 @@ ${diff}`);
 
 // src/commands/verify-vocabulary.ts
 import { existsSync as existsSync7, readFileSync as readFileSync8, readdirSync as readdirSync2, statSync as statSync2 } from "node:fs";
-import { join as join9, relative, sep } from "node:path";
+import { join as join10, relative, sep } from "node:path";
 
 // ../ogygie-core/src/vocabulary.ts
 var TOKEN_PATTERN = new RegExp("\\p{L}[\\p{L}\\p{N}]*(?:[-_$][\\p{L}\\p{N}]+)*", "gu");
@@ -15632,7 +15676,7 @@ function isScannableDirectory(name) {
 // src/commands/verify-vocabulary.ts
 var CODE_EXTENSIONS = [".ts", ".tsx", ".mts", ".mjs", ".js", ".jsx"];
 function readManifest(projectRoot) {
-  const manifestPath = join9(projectRoot, MANIFEST_FILE_NAME);
+  const manifestPath = join10(projectRoot, MANIFEST_FILE_NAME);
   if (!existsSync7(manifestPath)) {
     throwOgygieError({
       code: "OGYGIE_CLI_USAGE",
@@ -15657,13 +15701,13 @@ function readManifest(projectRoot) {
   return parsed.data;
 }
 function collectCodeFiles(projectRoot, folder) {
-  const absoluteFolder = join9(projectRoot, folder);
+  const absoluteFolder = join10(projectRoot, folder);
   if (!existsSync7(absoluteFolder)) return [];
   const files = [];
   const walk = (directory) => {
     for (const entry of readdirSync2(directory)) {
       if (!isScannableDirectory(entry)) continue;
-      const entryPath = join9(directory, entry);
+      const entryPath = join10(directory, entry);
       if (statSync2(entryPath).isDirectory()) {
         walk(entryPath);
         continue;
@@ -15706,9 +15750,9 @@ function verifyVocabulary(deps) {
   const sourceFiles = productCodeFoldersOf(manifest).flatMap(
     (folder) => collectCodeFiles(deps.projectRoot, folder)
   );
-  const governed = governedFiles.filter((file2) => existsSync7(join9(deps.projectRoot, file2.targetPath))).map((file2) => ({
+  const governed = governedFiles.filter((file2) => existsSync7(join10(deps.projectRoot, file2.targetPath))).map((file2) => ({
     path: file2.targetPath,
-    content: readFileSync8(join9(deps.projectRoot, file2.targetPath), "utf8")
+    content: readFileSync8(join10(deps.projectRoot, file2.targetPath), "utf8")
   }));
   return auditProductVocabulary({
     vocabulary: manifest.vocabulary,
@@ -15884,6 +15928,30 @@ var governedChecksumsByVersion = {
     "scripts/verify-specs.ts": "03d58baa11822ad7ae67080f990f7a82f4f94d223b12777728b8b9ddd7ebd843",
     "tsconfig.base.json": "0f8919e9ed8bbc88e0308fa2fa91471dabb18d1df721bd78c04076597eba89a2"
   },
+  "0.16.0": {
+    ".github/workflows/ogygie-gates.yml": "48c40efe9fe66dd0f9c3b94287026d80eae9afd6782b5833fdf8846d8662babf",
+    "AGENTS.md": "74725a71e531502d4d4898518bad68e610a370bd410058b58e11220532dc327f",
+    "CLAUDE.md": "785ee8d90e368806d8cf0b4d84a15f29d1dc961168bda86cf1a6c60a923c8c9b",
+    "scripts/lint-interdits.ts": "4644e1aaabc1d19ed42a0bdf8e2e55b9451f789d87d59754bce3432de7c357e7",
+    "scripts/ogygie-design-brief.ts": "aba1585717b30808dd0bc8930a37a1ad2d83ee6869f969dbd06ca595e37a4a89",
+    "scripts/ogygie-impact.ts": "f06cc8b4a46ddfbcfb32ba747c2454548ca49918123d04ab13d210b4a89c1fb9",
+    "scripts/verify-contracts.ts": "9cd64c88dcc3b54b65bf1e1b7a68eb00353ee16f2a9ce8bca3c49ba063c2a08b",
+    "scripts/verify-manifest.ts": "6c448fa3a19b87666f686ca57c6ca834d9e169b1380e4fe6e4c19b995bf94f3c",
+    "scripts/verify-specs.ts": "03d58baa11822ad7ae67080f990f7a82f4f94d223b12777728b8b9ddd7ebd843",
+    "tsconfig.base.json": "0f8919e9ed8bbc88e0308fa2fa91471dabb18d1df721bd78c04076597eba89a2"
+  },
+  "0.17.0": {
+    ".github/workflows/ogygie-gates.yml": "48c40efe9fe66dd0f9c3b94287026d80eae9afd6782b5833fdf8846d8662babf",
+    "AGENTS.md": "e058a54ff4750abf19f7c4b026e8be661d8ce25419596d22c20de2c387469370",
+    "CLAUDE.md": "785ee8d90e368806d8cf0b4d84a15f29d1dc961168bda86cf1a6c60a923c8c9b",
+    "scripts/lint-interdits.ts": "4644e1aaabc1d19ed42a0bdf8e2e55b9451f789d87d59754bce3432de7c357e7",
+    "scripts/ogygie-design-brief.ts": "aba1585717b30808dd0bc8930a37a1ad2d83ee6869f969dbd06ca595e37a4a89",
+    "scripts/ogygie-impact.ts": "f06cc8b4a46ddfbcfb32ba747c2454548ca49918123d04ab13d210b4a89c1fb9",
+    "scripts/verify-contracts.ts": "9cd64c88dcc3b54b65bf1e1b7a68eb00353ee16f2a9ce8bca3c49ba063c2a08b",
+    "scripts/verify-manifest.ts": "6c448fa3a19b87666f686ca57c6ca834d9e169b1380e4fe6e4c19b995bf94f3c",
+    "scripts/verify-specs.ts": "03d58baa11822ad7ae67080f990f7a82f4f94d223b12777728b8b9ddd7ebd843",
+    "tsconfig.base.json": "0f8919e9ed8bbc88e0308fa2fa91471dabb18d1df721bd78c04076597eba89a2"
+  },
   "0.2.0": {
     ".github/workflows/ogygie-gates.yml": "48c40efe9fe66dd0f9c3b94287026d80eae9afd6782b5833fdf8846d8662babf",
     "AGENTS.md": "ca73ab619d8c55fac11858d815bf5fbab6537ecebe7ae4123cbdeb3e3e36bf1a",
@@ -15978,22 +16046,22 @@ var governedChecksumsByVersion = {
 
 // src/paths.ts
 import { existsSync as existsSync8, readFileSync as readFileSync9 } from "node:fs";
-import { dirname as dirname4, join as join10 } from "node:path";
+import { dirname as dirname4, join as join11 } from "node:path";
 import { fileURLToPath } from "node:url";
-var PACKAGE_ROOT = join10(dirname4(fileURLToPath(import.meta.url)), "..");
+var PACKAGE_ROOT = join11(dirname4(fileURLToPath(import.meta.url)), "..");
 var PackageVersionSchema2 = external_exports.object({ version: external_exports.string() });
 function cliVersion() {
   return PackageVersionSchema2.parse(
-    JSON.parse(readFileSync9(join10(PACKAGE_ROOT, "package.json"), "utf8"))
+    JSON.parse(readFileSync9(join11(PACKAGE_ROOT, "package.json"), "utf8"))
   ).version;
 }
 function templatesDir() {
-  const embedded = join10(PACKAGE_ROOT, "templates");
+  const embedded = join11(PACKAGE_ROOT, "templates");
   if (existsSync8(embedded)) return embedded;
   return repoTemplatesDir();
 }
 function repoTemplatesDir() {
-  return join10(PACKAGE_ROOT, "..", "..", "templates");
+  return join11(PACKAGE_ROOT, "..", "..", "templates");
 }
 
 // src/cli.ts
@@ -16086,14 +16154,23 @@ ogygie verify-vocabulary \u2014 ${problems.length} probl\xE8me(s).`);
       cliVersion: cliVersion(),
       argv: process.argv.slice(3)
     });
+  } else if (command === "generate") {
+    const exitCode = await runGenerate({
+      projectRoot: process.cwd(),
+      cliVersion: cliVersion(),
+      argv: process.argv.slice(3),
+      log: (line) => console.log(line),
+      error: (line) => console.error(line)
+    });
+    if (exitCode !== 0) process.exit(exitCode);
   } else {
     printError(
       ogygieError({
         code: "OGYGIE_CLI_USAGE",
         message: `Unknown command ${JSON.stringify(command ?? "")}.`,
         file: null,
-        cause: `expected one of: init <product-name>, adopt, upgrade, check, verify-vocabulary, studio, mcp (flags: --json, --yes)`,
-        suggestedFix: "Run `ogygie init <product-name>`, `ogygie adopt`, `ogygie upgrade`, `ogygie check`, `ogygie verify-vocabulary`, `ogygie studio` or `ogygie mcp`."
+        cause: `expected one of: init <product-name>, adopt, upgrade, check, verify-vocabulary, studio, mcp, generate <check|generate|verify> (flags: --json, --yes)`,
+        suggestedFix: "Run `ogygie init <product-name>`, `ogygie adopt`, `ogygie upgrade`, `ogygie check`, `ogygie verify-vocabulary`, `ogygie studio`, `ogygie mcp` or `ogygie generate <check|generate|verify>`."
       })
     );
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Ogygie framework CLI: deterministic scaffolding (init), governed-file upgrades (upgrade) and lockstep verification (check) for Ogygie products.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@ogygie/core": "0.15.0",
+    "@ogygie/core": "0.17.0",
     "@types/node": "^24.0.0",
     "esbuild": "^0.28.0",
     "tsx": "^4.20.0",

package/templates/project/AGENTS.md

@@ -295,12 +295,19 @@ dérogation qui s'oublie. Elle ne couvre JAMAIS le code du produit lui-même.
 ### Stack imposée (toute autre lib = amendement DECISIONS.md d'abord)
 Vite + React 19 + TanStack Router (routing EN CODE) + TanStack Query (état serveur) ;
 PAS de lib d'état client (useState suffit) ; Tailwind v4 thémé depuis `design/tokens.json`
-(valeurs arbitraires `p-[13px]` interdites par lint) ; primitives UI copiées dans
-`apps/web/src/patterns/` (jamais consommées directement depuis node_modules par une
-feature) ; react-hook-form UNIQUEMENT via le pattern `ContractForm` ; TanStack
-Table UNIQUEMENT via `DataTable` ; Recharts UNIQUEMENT via `VarianceChart` ;
+(valeurs arbitraires `p-[13px]` interdites par lint) ; le socle de patterns vient du
+paquet `@ogygie/ui` — `ScreenState`, `EmptyState`, `ErrorBanner`, `EditableText`,
+`fetchContract`, et derrière leur propre point d'entrée `DataTable`
+(`@ogygie/ui/data-table`), `ContractForm` (`@ogygie/ui/contract-form`),
+`VarianceChart` (`@ogygie/ui/variance-chart`) — IMPORTÉ, jamais recopié ; les
+patterns PRODUIT vivent dans `apps/web/src/patterns/` (jamais consommés directement
+depuis node_modules par une feature) ; react-hook-form UNIQUEMENT via `ContractForm` ;
+TanStack Table UNIQUEMENT via `DataTable` ; Recharts UNIQUEMENT via `VarianceChart` ;
 date-fns via les helpers `@ogygie/core` (jamais de `new Date()` nu) ; i18n Lingui
-(ICU, extraction vérifiée en CI). Noms de patterns en anglais.
+(ICU, extraction vérifiée en CI) — `@ogygie/ui` ne porte AUCUNE chaîne : tout texte
+lui arrive en prop, traduit par la feature. Noms de patterns en anglais. La feuille
+Tailwind du produit déclare le paquet comme source
+(`@source "../node_modules/@ogygie/ui/src";`), sinon ses classes ne sont pas générées.
 
 ### Structure d'une feature front (miroir de l'API)
 ```
@@ -319,7 +326,7 @@ apps/web/features/orders/
 /** @intent Data access of the orders feature. Re-validates contracts in dev. */
 import { useQuery } from "@tanstack/react-query";
 import { ListOrdersOutputSchema } from "@product/api/features/orders/schemas";
-import { fetchContract } from "../../lib/fetchContract"; // Zod parse in dev, OgygieError on broken contract
+import { fetchContract } from "@ogygie/ui"; // Zod parse of the answer; an OgygieFailure on a refused call or a broken contract
 
 export function useOrders() {
   return useQuery({
@@ -334,18 +341,25 @@ export function useOrders() {
 // apps/web/features/orders/OrdersList.tsx
 /** @intent Orders list screen: composition of patterns, zero business logic. */
 import { Trans } from "@lingui/react/macro";
-import { DataTable } from "../../patterns/DataTable";
-import { EmptyState } from "../../patterns/EmptyState";
-import { ErrorBanner } from "../../patterns/ErrorBanner";
+import { ScreenState } from "@ogygie/ui";
+import { DataTable } from "@ogygie/ui/data-table";
 import { useOrders } from "./queries";
 
 export function OrdersList() {
-  const { data, isPending, error } = useOrders();
-  if (error) return <ErrorBanner error={error} />;
-  if (isPending) return <DataTable.Skeleton />;
-  if (data.orders.length === 0)
-    return <EmptyState title={<Trans>Ajoutez votre première commande</Trans>} />;
-  return <DataTable rows={data.orders} columns={orderColumns} />;
+  return (
+    <ScreenState
+      query={useOrders()}
+      errorTitle={<Trans>Cette vue n'a pas pu être chargée</Trans>}
+      loading={<DataTable.Skeleton />}
+      isEmpty={(data) => data.orders.length === 0}
+      emptyState={{
+        title: <Trans>Ajoutez votre première commande</Trans>,
+        explanation: <Trans>Les commandes enregistrées apparaissent ici.</Trans>,
+      }}
+    >
+      {(data) => <DataTable rows={data.orders} columns={orderColumns} rowKey={(order) => order.id} />}
+    </ScreenState>
+  );
 }
 ```
 
@@ -353,6 +367,9 @@ export function OrdersList() {
 - Un écran est une COMPOSITION de patterns : jamais de `<table>`, `<form>` ou fetch nus
   dans une feature. Si un pattern manque, on le crée dans `patterns/` (et on met à jour
   `design/patterns.md`), on ne bricole pas dans la feature.
+- Les états d'un écran — accès refusé, erreur, chargement, vide — passent par
+  `ScreenState`, jamais par une cascade de `if` propre à l'écran : le corps ne reçoit
+  que des données servies.
 - Chaque état UI listé dans la spec (vide/chargement/nominal/erreur) a son test.
 - Toute chaîne visible passe par Lingui (`<Trans>`/`t`) — la CI casse sinon.
 - Chiffres financiers : `tabular-nums`, alignés à droite, unité explicite.

package/templates/project/design/patterns.md

@@ -2,27 +2,35 @@
 
 > Les patterns sont les SEULES briques d'écran autorisées (AGENTS.md §Front) :
 > un écran est une COMPOSITION de patterns, jamais de `<table>`, `<form>` ni
-> fetch nus. Le starter n'a pas encore d'app front produit : à l'ouverture du
-> premier front, chaque pattern retenu est COPIÉ dans `apps/web/src/patterns/`
-> et sa fiche ci-dessous devient son contrat. Un pattern manquant se crée ICI
-> d'abord (fiche + décision), jamais en one-off dans un écran.
+> fetch nus. Les patterns GÉNÉRIQUES ci-dessous sont LIVRÉS par le paquet
+> `@ogygie/ui` : un produit les importe, il ne les recopie pas, et leur fiche
+> ci-dessous est leur contrat. Un pattern PRODUIT — propre au domaine — naît
+> dans `apps/web/src/patterns/` avec sa fiche ICI d'abord, jamais en one-off
+> dans un écran. Tout texte lu par un humain arrive à un pattern générique en
+> prop, traduit par la feature (Lingui) : le paquet ne porte aucune chaîne.
 >
 > Ce catalogue est une source de vérité du brief de design
 > (`pnpm ogygie:design-brief <feature>`) : chaque fiche `## <Name>` devient
 > une entrée du vocabulaire de composition. Noms en anglais (machine-lisible),
 > fiches en français (document humain).
 
+## ScreenState
+Le composant d'état UNIQUE d'un écran (`@ogygie/ui`). Reçoit la lecture (`QueryLike`, sous-ensemble d'un résultat TanStack Query) et le corps en fonction de rendu, et décide dans cet ordre : accès refusé (`denied` de l'appelant, ou une réponse 401/403 quand une copie `accessDenied` est donnée), erreur (`ErrorBanner`, titré par `errorTitle`), chargement (`loading`, à défaut `Skeleton`), vide (`isEmpty` + `emptyState`, un `EmptyState` avec son action), puis le corps avec des données servies. Un corps ne branche jamais sur `undefined`.
+
 ## DataTable
-Tableau de données (TanStack Table, seul usage autorisé). États : squelette de chargement (`DataTable.Skeleton`), vide (déléguer à EmptyState), nominal trié/paginé, erreur (déléguer à ErrorBanner). Chiffres en `tabular-nums` alignés à droite, unité explicite.
+Tableau de données (`@ogygie/ui/data-table`, TanStack Table — seul usage autorisé). Colonnes typées `{ id, header, cell, sortValue?, align? }` ; tri par clic d'en-tête (`aria-sort`), chiffres `align: "end"` en `tabular-nums` alignés à droite, unité explicite dans la cellule. États : squelette de chargement (`DataTable.Skeleton`), vide DÉLÉGUÉ (`emptyState` : un `EmptyState` qui dit pourquoi), nominal trié ; l'erreur appartient à `ScreenState`. La liste de colonnes reste stable (module ou `useMemo`).
 
 ## EmptyState
-État vide intentionnel : un titre, une explication courte, UNE action de création. Jamais de tableau ou de liste vides nus — l'écran vide est le premier écran que voit chaque nouvel utilisateur.
+État vide intentionnel (`@ogygie/ui`) : un titre qui nomme la CAUSE, une explication qui dit ce qui le remplirait, UNE action de création au plus. Jamais de tableau ou de liste vides nus — l'écran vide est le premier écran que voit chaque nouvel utilisateur. Deux causes, deux formulations : rien d'enregistré, ou un filtre qui ne trouve rien.
 
 ## ErrorBanner
-Bandeau d'erreur qui affiche une OgygieError : message traduit via `userMessageKey` (clé ICU), code stable et `suggestedFix` repliables. Tout état d'erreur d'écran passe par lui — jamais de message d'erreur improvisé.
+Bandeau d'erreur (`@ogygie/ui`) : affiche une `OgygieFailure` en entier — le titre du produit, le message, le code stable avec le statut et la cause, la correction suggérée — et dégrade toute autre erreur à son message. `kind: "save"` marque une écriture refusée (le produit titre autrement) ; `retry` ajoute le bouton que le produit libelle. Tout état d'erreur d'écran passe par lui — jamais de message improvisé.
 
 ## ContractForm
-Formulaire DÉRIVÉ d'un contrat Zod (react-hook-form, seul usage autorisé) : les contraintes du schéma (min/max/regex, obligatoire) sont les validations des champs — rien n'est redéclaré à la main. États : saisie, soumission en cours (bouton désactivé), erreurs de champ, erreur serveur (ErrorBanner).
+Formulaire DÉRIVÉ d'un contrat Zod (`@ogygie/ui/contract-form`, react-hook-form — seul usage autorisé) : les champs viennent de la forme du schéma, leurs contrôles de leur genre (texte, nombre, date, sélection d'enum, case à cocher), leurs contraintes des bornes du schéma — rien n'est redéclaré à la main — et le schéma valide chaque soumission (`safeParse`). Libellés, aides, libellés d'options, `submitLabel` et `cancel` sont des props traduites ; `renderIssue` traduit la phrase d'un refus. États : saisie, soumission en cours (bouton inactif, `pending`), erreur de champ (une phrase sous le champ), erreur de formulaire (un `refine`), erreur serveur (`error` : un `ErrorBanner` save au-dessus des actions). `onSubmit` reçoit la SORTIE parsée du contrat.
 
 ## VarianceChart
-Graphique d'écart (Recharts, seul usage autorisé) : compare une valeur constatée à une référence. États : chargement, vide, nominal, erreur. Montants en `tabular-nums`, axe et unité toujours étiquetés.
+Graphique d'écart (`@ogygie/ui/variance-chart`, Recharts — seul usage autorisé) : une valeur constatée (`measured`) contre une référence (`reference`), par libellé, en deux barres groupées ; l'écart signé se lit dans l'infobulle ; une ligne zéro quand les valeurs la traversent. Couleurs tirées des tokens du produit par variables CSS, noms de séries et unité en props traduites. États : vide DÉLÉGUÉ (`emptyState`), squelette (`VarianceChart.Skeleton`) ; chargement et erreur appartiennent à `ScreenState`. Montants en `tabular-nums`, axe et unité toujours étiquetés.
+
+## EditableText
+Texte qui s'écrit là où il se lit (`@ogygie/ui`) : un clic le transforme en champ, quitter le champ ou Entrée enregistre, Échap abandonne. Un lecteur sans droit voit le texte nu, jamais un contrôle inactif. Un brouillon blanc est refusé sans écriture (sauf `allowEmpty`) ; une borne (`maxLength`) arrête le champ et affiche le compteur ; `pending` rend le contrôle inactif le temps d'une écriture. `placeholder` et `ariaLabel` sont traduits par la feature.

package/templates/project/scripts/verify-manifest.ts

@@ -16,6 +16,12 @@
  * `url: "/api/..."` found in a feature's routes.ts and every `pgTable("...")`
  * found in a feature's db.schema.ts must be declared in the manifest
  * (MANIFEST_ROUTE_UNDECLARED / MANIFEST_TABLE_UNDECLARED).
+ *
+ * A GENERATED feature (Ogygie generator, spec ogygie-generate) carries the
+ * generator's twin of a canonical file — `routes.gen.ts` where a hand-written
+ * feature has `routes.ts` — and this gate reads whichever nature is on disk,
+ * in both directions. `index.ts` keeps its canonical name by exception and
+ * `schemas.ts` has no twin: it is the human gesture the generator starts from.
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -148,6 +154,36 @@ for (const productPackage of manifest.packages ?? []) {
 const apiApp = manifest.apps.find((app) => app.type === "api");
 const featureNames = new Set(manifest.features.map((feature) => feature.name));
 
+/**
+ * Canonical file → its generated twin (`.gen` infix, Ogygie generator). A
+ * feature carries one nature or the other, never both by hand; when both
+ * exist, both are read, so a route or a table never hides in the file the gate
+ * did not open.
+ */
+const GENERATED_TWIN: Readonly<Record<string, string>> = {
+  "routes.ts": "routes.gen.ts",
+  "service.ts": "service.gen.ts",
+  "repository.ts": "repository.gen.ts",
+  "db.schema.ts": "db.schema.gen.ts",
+};
+
+function naturesOf(fileName: string): string[] {
+  const twin = GENERATED_TWIN[fileName];
+  return twin === undefined ? [fileName] : [fileName, twin];
+}
+
+/** `routes.ts` → `routes.ts or routes.gen.ts`, for the messages. */
+function eitherNature(fileName: string): string {
+  return naturesOf(fileName).join(" or ");
+}
+
+/** The canonical file and/or its generated twin, as they exist in the folder. */
+function readNatures(dir: string, fileName: string): Array<{ name: string; content: string }> {
+  return naturesOf(fileName)
+    .filter((name) => existsSync(join(dir, name)))
+    .map((name) => ({ name, content: readFileSync(join(dir, name), "utf8") }));
+}
+
 for (const feature of manifest.features) {
   const manifestRef = `${MANIFEST_PATH}#features.${feature.name}`;
 
@@ -229,21 +265,22 @@ for (const feature of manifest.features) {
 
   const canonicalFiles = ["index.ts", "routes.ts", "schemas.ts", "service.ts", "repository.ts"];
   for (const fileName of canonicalFiles) {
-    if (!existsSync(join(featureDir, fileName))) {
+    if (!naturesOf(fileName).some((name) => existsSync(join(featureDir, name)))) {
       report({
         code: "FEATURE_CANONICAL_FILE_MISSING",
-        message: `Feature "${feature.name}" is missing canonical file ${fileName}.`,
+        message: `Feature "${feature.name}" is missing canonical file ${eitherNature(fileName)}.`,
         file: join(apiApp.path, feature.folder, fileName),
-        cause: `${fileName} absent (AGENTS.md §Structure d'une feature)`,
-        suggestedFix: "Create the file following the canonical template in AGENTS.md.",
+        cause: `${eitherNature(fileName)} absent (AGENTS.md §Structure d'une feature; the generated twin counts)`,
+        suggestedFix: "Create the file following the canonical template in AGENTS.md, or generate the feature (spec ogygie-generate).",
       });
     }
   }
 
   const schemasPath = join(featureDir, "schemas.ts");
-  const routesPath = join(featureDir, "routes.ts");
   const schemasContent = existsSync(schemasPath) ? readFileSync(schemasPath, "utf8") : "";
-  const routesContent = existsSync(routesPath) ? readFileSync(routesPath, "utf8") : "";
+  const routeNatures = readNatures(featureDir, "routes.ts");
+  const routesFile = routeNatures[0]?.name ?? "routes.ts";
+  const routesContent = routeNatures.map((nature) => nature.content).join("\n");
 
   for (const route of feature.routes) {
     for (const schemaName of [route.schemaInput, route.schemaOutput]) {
@@ -261,26 +298,27 @@ for (const feature of manifest.features) {
     if (!routesContent.includes(`"${route.path}"`)) {
       report({
         code: "MANIFEST_ROUTE_NOT_FOUND",
-        message: `Route ${route.method} ${route.path} is declared in the manifest but absent from routes.ts.`,
-        file: join(apiApp.path, feature.folder, "routes.ts"),
-        cause: `"${route.path}" not found in routes.ts`,
-        suggestedFix: "Register the route in routes.ts or remove it from the manifest.",
+        message: `Route ${route.method} ${route.path} is declared in the manifest but absent from ${routesFile}.`,
+        file: join(apiApp.path, feature.folder, routesFile),
+        cause: `"${route.path}" not found in ${eitherNature("routes.ts")}`,
+        suggestedFix: "Register the route in routes.ts (or regenerate routes.gen.ts from the spec) or remove it from the manifest.",
       });
     }
   }
 
   if (feature.dbTables.length > 0) {
-    const dbSchemaPath = join(featureDir, "db.schema.ts");
-    const dbSchemaContent = existsSync(dbSchemaPath) ? readFileSync(dbSchemaPath, "utf8") : "";
+    const dbSchemaNatures = readNatures(featureDir, "db.schema.ts");
+    const dbSchemaFile = dbSchemaNatures[0]?.name ?? "db.schema.ts";
+    const dbSchemaContent = dbSchemaNatures.map((nature) => nature.content).join("\n");
     for (const table of dbTableNamesOf(feature)) {
       const tableDefinition = new RegExp(`pgTable\\(\\s*"${table}"`);
       if (!tableDefinition.test(dbSchemaContent)) {
         report({
           code: "MANIFEST_TABLE_NOT_FOUND",
-          message: `Feature "${feature.name}" declares table "${table}" but db.schema.ts does not define it.`,
-          file: join(apiApp.path, feature.folder, "db.schema.ts"),
-          cause: `pgTable("${table}") not found`,
-          suggestedFix: "Define the table in db.schema.ts or remove it from dbTables.",
+          message: `Feature "${feature.name}" declares table "${table}" but ${dbSchemaFile} does not define it.`,
+          file: join(apiApp.path, feature.folder, dbSchemaFile),
+          cause: `pgTable("${table}") not found in ${eitherNature("db.schema.ts")}`,
+          suggestedFix: "Define the table in db.schema.ts (or regenerate db.schema.gen.ts from the spec) or remove it from dbTables.",
         });
       }
     }
@@ -297,7 +335,7 @@ for (const feature of manifest.features) {
       report({
         code: "SHARED_TABLE_WITH_TENANT_COLUMN",
         message: `Table "${finding.table}" is declared shared in the manifest but its Drizzle definition still carries "${finding.tenantColumn}".`,
-        file: join(apiApp.path, feature.folder, "db.schema.ts"),
+        file: join(apiApp.path, feature.folder, dbSchemaFile),
         cause: `pgTable("${finding.table}") declares column "${finding.tenantColumn}" while the manifest says shared: true`,
         suggestedFix:
           "Either drop the tenant column (the table is a shared referential: no tenant owns it, no RLS tenant policy), or remove `shared: true` and go back through tenantDb.",
@@ -333,16 +371,14 @@ if (apiApp !== undefined) {
         ? ` (no manifest entry has folder=${relativeFolder})`
         : "";
 
-    const routesPath = join(featuresRoot, dirName, "routes.ts");
-    if (existsSync(routesPath)) {
-      const routesContent = readFileSync(routesPath, "utf8");
-      for (const match of routesContent.matchAll(/url:\s*"(\/api\/[^"]*)"/g)) {
+    for (const nature of readNatures(join(featuresRoot, dirName), "routes.ts")) {
+      for (const match of nature.content.matchAll(/url:\s*"(\/api\/[^"]*)"/g)) {
         const routePath = match[1];
         if (routePath !== undefined && !declaredPaths.has(routePath)) {
           report({
             code: "MANIFEST_ROUTE_UNDECLARED",
-            message: `Route ${routePath} is registered in ${relativeFolder}/routes.ts but not declared in the manifest.`,
-            file: join(apiApp.path, relativeFolder, "routes.ts"),
+            message: `Route ${routePath} is registered in ${relativeFolder}/${nature.name} but not declared in the manifest.`,
+            file: join(apiApp.path, relativeFolder, nature.name),
             cause: `url: "${routePath}" found in code, absent from the manifest${missingEntryCause}`,
             suggestedFix:
               "Declare the route (method, path, schemas) in ogygie.manifest.json — the manifest must never lie by omission.",
@@ -351,16 +387,14 @@ if (apiApp !== undefined) {
       }
     }
 
-    const dbSchemaPath = join(featuresRoot, dirName, "db.schema.ts");
-    if (existsSync(dbSchemaPath)) {
-      const dbSchemaContent = readFileSync(dbSchemaPath, "utf8");
-      for (const match of dbSchemaContent.matchAll(/pgTable\(\s*"([^"]+)"/g)) {
+    for (const nature of readNatures(join(featuresRoot, dirName), "db.schema.ts")) {
+      for (const match of nature.content.matchAll(/pgTable\(\s*"([^"]+)"/g)) {
         const tableName = match[1];
         if (tableName !== undefined && !declaredTables.has(tableName)) {
           report({
             code: "MANIFEST_TABLE_UNDECLARED",
-            message: `Table "${tableName}" is defined in ${relativeFolder}/db.schema.ts but not declared in the manifest.`,
-            file: join(apiApp.path, relativeFolder, "db.schema.ts"),
+            message: `Table "${tableName}" is defined in ${relativeFolder}/${nature.name} but not declared in the manifest.`,
+            file: join(apiApp.path, relativeFolder, nature.name),
             cause: `pgTable("${tableName}") found in code, absent from dbTables${missingEntryCause}`,
             suggestedFix:
               "Add the table to the feature's dbTables in ogygie.manifest.json (one table = one owner).",