@ogygie/cli 0.1.0

package/templates/project/ci/ogygie-gates.yml

@@ -0,0 +1,42 @@
+# Governed by Ogygie (spec ogygie-standalone-repo B2): overwritten as-is by
+# `ogygie upgrade`, never merged. Product-specific CI lives in OTHER workflow
+# files, never in this one.
+name: ogygie-gates
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least-privilege token: gitleaks-action reads the PR's commit list on
+# pull_request events; PR comments stay disabled so no write scope is needed.
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  verifier:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      # Deliberate order: Ogygie gates BEFORE the tests —
+      # a lying manifest must break faster than a red test.
+      - run: pnpm exec ogygie check        # lockstep versions + governed-file checksums (B5)
+      - run: pnpm ogygie:verify-manifest   # manifest ↔ actual code (routes, folders, tables)
+      - run: pnpm ogygie:verify-specs      # frontmatter + sections + spec lifecycle + decision refs
+      - run: pnpm ogygie:verify-contracts  # transitive purity of every schemas.ts
+      - run: pnpm typecheck
+      - run: pnpm lint                     # any, ts-ignore, raw-db, dangerouslySetInnerHTML
+      - run: pnpm test
+      # Security
+      - uses: gitleaks/gitleaks-action@v2  # committed secrets
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          GITLEAKS_ENABLE_COMMENTS: "false"
+      - uses: semgrep/semgrep-action@v1    # dangerous patterns (SAST)
+        with: { config: "p/typescript p/owasp-top-ten" }
+      - run: pnpm audit --audit-level=high # dependency CVEs

package/templates/project/design/patterns.md

@@ -0,0 +1,28 @@
+# Catalogue des patterns UI
+
+> 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.
+>
+> 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).
+
+## 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.
+
+## 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.
+
+## 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é.
+
+## 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).
+
+## 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.

package/templates/project/design/tokens.json

@@ -0,0 +1,50 @@
+{
+  "$intent": "Placeholder design tokens of the starter. A product REWRITES these values when it opens (AGENTS.product.md); the structure stays. The design tool composes ONLY from these tokens — a missing color or spacing is an amendment of this file (explicit decision), never a hardcoded value (AGENTS.md §Front).",
+  "color": {
+    "surface": "#f6f6f4",
+    "surface-raised": "#ffffff",
+    "border": "#e2e1dc",
+    "text": "#22241f",
+    "text-muted": "#5f6259",
+    "accent": "#3b5b92",
+    "accent-contrast": "#ffffff",
+    "positive": "#2f6b4f",
+    "warning": "#a96a1f",
+    "danger": "#b3423a",
+    "focus": "#7aa2ff"
+  },
+  "typography": {
+    "font-sans": "system-ui, -apple-system, 'Segoe UI', sans-serif",
+    "font-mono": "ui-monospace, 'SF Mono', 'Cascadia Mono', monospace",
+    "size": {
+      "xs": "0.75rem",
+      "sm": "0.875rem",
+      "base": "1rem",
+      "lg": "1.125rem",
+      "xl": "1.375rem",
+      "2xl": "1.75rem"
+    },
+    "leading": {
+      "tight": "1.25",
+      "normal": "1.5"
+    }
+  },
+  "spacing": {
+    "1": "0.25rem",
+    "2": "0.5rem",
+    "3": "0.75rem",
+    "4": "1rem",
+    "6": "1.5rem",
+    "8": "2rem",
+    "12": "3rem"
+  },
+  "radius": {
+    "sm": "0.25rem",
+    "md": "0.5rem",
+    "lg": "0.75rem",
+    "full": "9999px"
+  },
+  "shadow": {
+    "raised": "0 1px 2px rgb(0 0 0 / 0.06), 0 2px 8px rgb(0 0 0 / 0.04)"
+  }
+}

package/templates/project/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store

package/templates/project/ogygie.manifest.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "product": {
+    "name": "__PRODUCT_NAME__",
+    "description": "Produit Ogygie __PRODUCT_NAME__ — décrire le job-to-be-done ici (checklist de démarrage)."
+  },
+  "ogygieVersion": "__OGYGIE_VERSION__",
+  "apps": [],
+  "features": [],
+  "conventions": {
+    "agentsMd": "AGENTS.md",
+    "failuresMd": "FAILURES.md",
+    "specsFolder": "specs/"
+  }
+}

package/templates/project/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "__PRODUCT_NAME__",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.3.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json && pnpm -r --if-present run typecheck",
+    "lint": "tsx scripts/lint-interdits.ts",
+    "ogygie:verify-manifest": "tsx scripts/verify-manifest.ts",
+    "ogygie:verify-specs": "tsx scripts/verify-specs.ts",
+    "ogygie:verify-contracts": "tsx scripts/verify-contracts.ts",
+    "ogygie:impact": "tsx scripts/ogygie-impact.ts",
+    "ogygie:design-brief": "tsx scripts/ogygie-design-brief.ts",
+    "verify": "pnpm ogygie:verify-manifest && pnpm ogygie:verify-specs && pnpm ogygie:verify-contracts && pnpm typecheck && pnpm lint && pnpm test"
+  },
+  "dependencies": {
+    "@ogygie/core": "__OGYGIE_VERSION__"
+  },
+  "devDependencies": {
+    "@ogygie/cli": "__OGYGIE_VERSION__",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0",
+    "zod": "^4.0.0"
+  }
+}

package/templates/project/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+packages:
+  - "apps/*"
+  - "packages/*"
+
+# Build scripts are opt-in with pnpm 11; esbuild postinstall fetches its binary
+# (needed by tsx and vitest).
+allowBuilds:
+  esbuild: true

package/templates/project/scripts/lint-interdits.ts

@@ -0,0 +1,119 @@
+/**
+ * @intent CI gate `pnpm lint`: greps the source for the absolute bans of
+ * AGENTS.md §Interdits. Deliberately dependency-free — a real ESLint setup
+ * (incl. the `ogygie/no-raw-db` rule) is tracked as a follow-up. Type-level
+ * bans are only checked on code (comments stripped); the ts-ignore ban is
+ * checked everywhere since it lives in comments by nature.
+ *
+ * The raw-db ban is no longer a hand-kept list: it is DERIVED from
+ * ogygie.manifest.json through @ogygie/core/shared-tables (mayUseRawDb), so a
+ * feature earns the right to touch the database directly only by declaring, in
+ * the manifest, that every table it owns is shared (AGENTS.md §Multi-tenant
+ * rule 4). The policy itself is unit-tested with its mutations (D22) — this
+ * script only reports.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { OgygieManifestSchema } from "@ogygie/core/manifest";
+import { mayUseRawDb } from "@ogygie/core/shared-tables";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const SELF = fileURLToPath(import.meta.url);
+const SCANNED_DIRS = ["apps", "packages", "scripts"];
+const IGNORED_DIRS = new Set(["node_modules", "dist", ".git"]);
+const EXTENSIONS = [".ts", ".tsx", ".mts", ".mjs"];
+
+const TS_IGNORE_BAN = {
+  pattern: new RegExp(`@ts-${"ignore"}`),
+  rule: "ts-ignore interdit — @ts-expect-error avec justification si inévitable",
+};
+
+// Closed-list socle exception (AGENTS.md §Multi-tenant): the tenancy feature
+// BUILDS the contexts, so it predates them. Every other feature goes through
+// tenantDb — unless the manifest declares that every table it owns is SHARED,
+// which have no tenant column to filter on. Interim guard until the real
+// ESLint `ogygie/no-raw-db` rule lands.
+const FEATURES_PREFIX = "apps/api/src/features/";
+// TODO(product): the ONE tenancy socle feature allowed to touch the raw
+// database (it BUILDS the tenant contexts) — declare it in AGENTS.product.md
+// and here. Empty until the socle exists.
+const RAW_DB_SOCLE_ALLOWLIST = new Set<string>([]);
+const RAW_DB_BAN = {
+  pattern: /\bctx\.db\b/,
+  rule: "ctx.db interdit hors du socle et des features à tables partagées — passer par tenantDb (AGENTS.md §Multi-tenant)",
+};
+const CODE_BANS = [
+  { pattern: /as unknown as/, rule: "as unknown as interdit" },
+  { pattern: /(:\s*any\b)|(<any[,>])|(\bas any\b)|(\bany\[\])/, rule: "type any interdit" },
+  { pattern: /dangerouslySetInnerHTML/, rule: "dangerouslySetInnerHTML interdit" },
+];
+
+const manifest = OgygieManifestSchema.parse(
+  JSON.parse(readFileSync(join(ROOT, "ogygie.manifest.json"), "utf8")),
+);
+/** Feature folder names allowed to touch the raw database, derived — not held. */
+const rawDbAllowedFolders = new Set(
+  manifest.features
+    .filter((feature) => mayUseRawDb(feature, RAW_DB_SOCLE_ALLOWLIST))
+    .map((feature) => feature.folder.split("/").at(-1) ?? feature.name),
+);
+
+const violations: string[] = [];
+
+function stripComments(line: string): string {
+  const trimmed = line.trim();
+  if (trimmed.startsWith("*") || trimmed.startsWith("/*") || trimmed.startsWith("//")) {
+    return "";
+  }
+  return line.replace(/\/\/.*$/, "");
+}
+
+function scan(dir: string): void {
+  for (const entry of readdirSync(dir)) {
+    if (IGNORED_DIRS.has(entry)) continue;
+    const entryPath = join(dir, entry);
+    const stats = statSync(entryPath);
+    if (stats.isDirectory()) {
+      scan(entryPath);
+      continue;
+    }
+    if (entryPath === SELF) continue;
+    if (!EXTENSIONS.some((extension) => entry.endsWith(extension))) continue;
+    const lines = readFileSync(entryPath, "utf8").split("\n");
+    lines.forEach((line, index) => {
+      const location = `${relative(ROOT, entryPath)}:${index + 1}`;
+      if (TS_IGNORE_BAN.pattern.test(line)) {
+        violations.push(`${location} — ${TS_IGNORE_BAN.rule}`);
+      }
+      const code = stripComments(line);
+      for (const { pattern, rule } of CODE_BANS) {
+        if (pattern.test(code)) {
+          violations.push(`${location} — ${rule}`);
+        }
+      }
+      const relPath = relative(ROOT, entryPath);
+      if (relPath.startsWith(FEATURES_PREFIX)) {
+        const featureFolder = relPath.slice(FEATURES_PREFIX.length).split("/")[0] ?? "";
+        if (!rawDbAllowedFolders.has(featureFolder) && RAW_DB_BAN.pattern.test(code)) {
+          violations.push(`${location} — ${RAW_DB_BAN.rule}`);
+        }
+      }
+    });
+  }
+}
+
+for (const dir of SCANNED_DIRS) {
+  try {
+    scan(join(ROOT, dir));
+  } catch {
+    // folder may not exist yet in a fresh checkout — nothing to scan
+  }
+}
+
+if (violations.length > 0) {
+  for (const violation of violations) console.error(violation);
+  console.error(`\nlint — ${violations.length} violation(s) des interdits AGENTS.md.`);
+  process.exit(1);
+}
+console.log("lint — OK, aucun interdit détecté.");

package/templates/project/scripts/ogygie-design-brief.ts

@@ -0,0 +1,192 @@
+/**
+ * @intent Session tool `pnpm ogygie:design-brief <feature> [--stdout]`
+ * (specs/ogygie-design-brief.spec.md): writes the feature's design brief to
+ * design/briefs/<feature>.md, DERIVED from the repo's sources of truth —
+ * manifest routes, Zod contracts (via z.toJSONSchema), the feature spec,
+ * design/tokens.json, design/patterns.md, the front apps' pattern modules,
+ * and test-fixtures/ counts. Same family as ogygie-impact and verify-*:
+ * fs + manifest in, findings as OgygieError, no new dependency.
+ *
+ * This file only GATHERS: every decision (formats, warnings, empty-section
+ * signaling, rendering) lives in @ogygie/core/design-brief with its spec
+ * tests. Missing sources are passed as null — signaled downstream, never
+ * guessed here.
+ *
+ * Output contract (spec §États UI): Markdown file + console summary; --stdout
+ * additionally prints the document. Exit 0, or 1 when the feature is unknown.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import {
+  buildDesignBrief,
+  renderDesignBriefMarkdown,
+  type DesignBriefSources,
+  type JsonSchemaNode,
+} from "@ogygie/core/design-brief";
+import { OgygieManifestSchema } from "@ogygie/core/manifest";
+import { dbTableNamesOf } from "@ogygie/core/shared-tables";
+import { ogygieError } from "@ogygie/core/errors";
+
+const ROOT = new URL("..", import.meta.url).pathname;
+const MANIFEST_PATH = "ogygie.manifest.json";
+const BRIEFS_FOLDER = join("design", "briefs");
+
+// ---------------------------------------------------------------- helpers
+function readTextIfExists(relativePath: string): string | null {
+  const fullPath = join(ROOT, relativePath);
+  return existsSync(fullPath) ? readFileSync(fullPath, "utf8") : null;
+}
+
+/** First `@intent` line of a module, the pattern's one-line contract. */
+function intentLineOf(content: string): string | null {
+  const match = /@intent\s+(.+)/.exec(content);
+  return match?.[1] === undefined ? null : match[1].trim();
+}
+
+/** Production .ts/.tsx files of a folder, tests excluded, stable order. */
+function productionSourcesOf(folder: string): Array<{ file: string; content: string }> {
+  const fullFolder = join(ROOT, folder);
+  if (!existsSync(fullFolder)) return [];
+  const sources: Array<{ file: string; content: string }> = [];
+  for (const entry of readdirSync(fullFolder, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name, "en"),
+  )) {
+    const relativePath = join(folder, entry.name);
+    if (entry.isDirectory()) {
+      sources.push(...productionSourcesOf(relativePath));
+      continue;
+    }
+    if (!/\.(ts|tsx)$/.test(entry.name) || /\.test\.(ts|tsx)$/.test(entry.name)) continue;
+    sources.push({ file: relativePath, content: readFileSync(join(ROOT, relativePath), "utf8") });
+  }
+  return sources;
+}
+
+/** Rows of test-fixtures/<table>.json — null when absent or not an array. */
+function fixtureRowCountOf(table: string): number | null {
+  const raw = readTextIfExists(join("test-fixtures", `${table}.json`));
+  if (raw === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.length : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A named export of schemas.ts turned into JSON Schema — null, never a guess. */
+function jsonSchemaOfExport(
+  schemasModule: Record<string, unknown> | null,
+  exportName: string,
+): JsonSchemaNode | null {
+  const candidate = schemasModule?.[exportName];
+  if (candidate === undefined || candidate === null) return null;
+  try {
+    return z.toJSONSchema(candidate as z.ZodType) as JsonSchemaNode;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------- CLI args
+const cliArguments = process.argv.slice(2);
+const printToStdout = cliArguments.includes("--stdout");
+const featureArgument = cliArguments.find((argument) => !argument.startsWith("--"));
+
+if (featureArgument === undefined) {
+  const failure = ogygieError({
+    code: "DESIGN_BRIEF_UNKNOWN_FEATURE",
+    message: "No feature name given. Usage: pnpm ogygie:design-brief <feature> [--stdout].",
+    file: null,
+    cause: "process.argv carries no non-flag argument",
+    suggestedFix:
+      "Pass a feature name from ogygie.manifest.json, e.g. `pnpm ogygie:design-brief notes`.",
+  });
+  console.error(JSON.stringify(failure, null, 2));
+  process.exit(1);
+}
+const featureName = featureArgument;
+
+// ---------------------------------------------------------------- gathering
+const manifest = OgygieManifestSchema.parse(
+  JSON.parse(readFileSync(join(ROOT, MANIFEST_PATH), "utf8")),
+);
+const apiApp = manifest.apps.find((app) => app.type === "api");
+const feature = manifest.features.find((candidate) => candidate.name === featureName);
+const owningApp =
+  feature?.app === undefined
+    ? apiApp
+    : manifest.apps.find((app) => app.name === feature.app) ?? apiApp;
+
+const patternModules: DesignBriefSources["patternModules"] = [];
+for (const app of manifest.apps.filter((candidate) => candidate.type === "front")) {
+  const patternsFolder = join(app.path, "src", "patterns");
+  for (const source of productionSourcesOf(patternsFolder)) {
+    const name = source.file.split("/").pop()?.replace(/\.(ts|tsx)$/, "");
+    if (name !== undefined) patternModules.push({ name, intent: intentLineOf(source.content) });
+  }
+}
+
+let sources: DesignBriefSources = {
+  featureName,
+  validFeatureNames: manifest.features.map((candidate) => candidate.name),
+  visualTokensJson: readTextIfExists(join("design", "tokens.json")),
+  patternsCatalogDoc: readTextIfExists(join("design", "patterns.md")),
+  patternModules,
+  routes: [],
+  specContent: null,
+  featureSources: [],
+  fixtureCounts: [],
+};
+
+if (feature !== undefined && owningApp !== undefined) {
+  const featureFolder = join(owningApp.path, feature.folder);
+  const schemasPath = join(ROOT, featureFolder, "schemas.ts");
+  let schemasModule: Record<string, unknown> | null = null;
+  if (existsSync(schemasPath)) {
+    schemasModule = (await import(pathToFileURL(schemasPath).href)) as Record<string, unknown>;
+  }
+  sources = {
+    ...sources,
+    routes: feature.routes.map((route) => ({
+      method: route.method,
+      path: route.path,
+      description: route.description,
+      inputSchemaName: route.schemaInput,
+      outputSchemaName: route.schemaOutput,
+      inputJsonSchema: jsonSchemaOfExport(schemasModule, route.schemaInput),
+      outputJsonSchema: jsonSchemaOfExport(schemasModule, route.schemaOutput),
+    })),
+    specContent: feature.spec == null ? null : readTextIfExists(feature.spec),
+    featureSources: productionSourcesOf(featureFolder),
+    fixtureCounts: dbTableNamesOf(feature).map((table) => ({
+      table,
+      count: fixtureRowCountOf(table),
+    })),
+  };
+}
+
+// ---------------------------------------------------------------- build
+const result = buildDesignBrief(sources);
+if (result.failure !== null) {
+  console.error(JSON.stringify(result.failure, null, 2));
+  console.error("\nogygie:design-brief — feature inconnue.");
+  process.exit(1);
+}
+
+const markdown = renderDesignBriefMarkdown(result.brief);
+mkdirSync(join(ROOT, BRIEFS_FOLDER), { recursive: true });
+const briefPath = join(BRIEFS_FOLDER, `${featureName}.md`);
+writeFileSync(join(ROOT, briefPath), markdown);
+
+if (printToStdout) console.log(markdown);
+console.log(`── ogygie:design-brief ${featureName} ──`);
+console.log(`Brief écrit : ${briefPath} (${markdown.split("\n").length - 1} lignes)`);
+console.log(
+  result.brief.warnings.length === 0
+    ? "Avertissements : aucun."
+    : `Avertissements : ${result.brief.warnings.length}\n${result.brief.warnings.map((warning) => `  ⚠ ${warning}`).join("\n")}`,
+);
+process.exit(0);