@ogygie/core 0.8.0 → 0.10.0

package/src/manifest-owners.ts

@@ -3,19 +3,42 @@
  * the map owns this spec, and how far along is it?
  *
  * The rule itself does not change — a spec only claims `implemented` when the
- * manifest confirms it. What changes is that the map now has two kinds of
- * entry able to confirm: a feature living under an app, and a PRODUCT PACKAGE
- * living outside every app (spec manifest-packages). Before that, a spec whose
- * code sat in `packages/` could never be marked finished, and nothing said why
- * — the gate answered `manifest status=absent` and suggested two fixes, both
- * impossible.
+ * manifest confirms it. What changes is WHICH entries are able to confirm.
+ * The map declares THREE natures, and this function knows all three:
+ * a feature living under an app, a PRODUCT PACKAGE living outside every app
+ * (spec manifest-packages), and a FRAMEWORK PACKAGE — the published packages a
+ * framework repo describes in its `framework` block.
+ *
+ * Each nature was added the day a spec of that nature could not be confirmed,
+ * and the failure mode is always the same silence: the gate answers "no entry
+ * of that name", suggests fixes that cannot be applied, and the spec stays
+ * `validated` for ever while its code ships (FAILURES.md 2026-08-25 — three
+ * framework specs were in that state, one of them for a delivered gate).
+ * Hence the standing convention: a spec verifier knows EVERY nature of owner
+ * the manifest declares, and a nature added to the map is added here in the
+ * same lot.
+ *
+ * A framework package matches by its `spec` field, not by its name: a
+ * published npm name (`@ogygie/mcp`) is not a spec id (`ogygie-mcp`). Several
+ * may point at the same spec — a framework spec often spans the core and the
+ * CLI — and the LEAST advanced one answers: a spec is delivered when all its
+ * code is, not when its first half is.
  *
  * Lives in the core, not in the gate script, so the rule travels with the
  * versioned package instead of with a copy each project keeps.
  */
 import type { OgygieManifest } from "./manifest.schema.js";
 
-export type SpecOwnerKind = "feature" | "package";
+/** Least advanced first — the order the "all its code" rule sorts on. */
+const ADVANCEMENT = ["skeleton", "in-progress", "delivered"] as const;
+
+/** `specs/ogygie-mcp.spec.md` -> `ogygie-mcp`. The manifest declares a PATH
+ * (as features do), the lifecycle rule reasons on ids. */
+function specIdOf(specPath: string): string {
+  return (specPath.split("/").pop() ?? specPath).replace(/\.spec\.md$/, "");
+}
+
+export type SpecOwnerKind = "feature" | "package" | "framework-package";
 
 export interface SpecOwner {
   kind: SpecOwnerKind;
@@ -29,44 +52,99 @@ export interface SpecOwner {
   folder: string | null;
 }
 
+/** One entry of the map, with everything a tool needs to go read its code. */
+export interface MapEntry extends SpecOwner {
+  /** The spec this entry owns, or null when it owns none. */
+  specId: string | null;
+}
+
 /**
- * The entry owning `specId`, feature first. Names are unique across the whole
- * map (the schema refuses a package named like a feature), so the order only
- * decides which lookup runs first, never which answer is right.
+ * EVERYTHING the map declares, each entry with its folder already resolved
+ * through the app that carries it.
+ *
+ * One resolution for the whole framework. The spec-lifecycle gate and the
+ * impact analyzer used to resolve folders on their own, and the analyzer got
+ * it wrong in the way that does not show: it picked ONE app —
+ * `apps.find(app => app.type === "api")` — and joined every feature's folder
+ * to that one, so a front feature was looked for under the api app and never
+ * found. It also refused to run at all when no api app existed. The map
+ * already answered per entry, through `feature.app`, which the schema REQUIRES
+ * a front or gateway feature to declare.
+ *
+ * A fourth nature of entry is therefore added HERE, once, and every tool sees
+ * it (FAILURES.md 2026-08-25: a verifier that ignores a category cannot report
+ * it).
  */
-export function findSpecOwner(
-  manifest: OgygieManifest,
-  specId: string,
-): SpecOwner | undefined {
-  const feature = manifest.features.find((candidate) => candidate.name === specId);
-  if (feature !== undefined) {
+export function declaredEntries(manifest: OgygieManifest): MapEntry[] {
+  const entries: MapEntry[] = [];
+
+  for (const feature of manifest.features) {
+    // The app that CARRIES this feature — never a globally chosen one.
     const owningApp =
       feature.app === undefined
         ? manifest.apps.find((app) => app.type === "api")
         : manifest.apps.find((app) => app.name === feature.app);
-    return {
+    entries.push({
       kind: "feature",
       name: feature.name,
       status: feature.status,
       folder: owningApp === undefined ? null : `${owningApp.path}/${feature.folder}`,
-    };
+      specId: feature.name,
+    });
   }
 
-  const productPackage = (manifest.packages ?? []).find(
-    (candidate) => candidate.name === specId,
-  );
-  if (productPackage !== undefined) {
-    return {
+  for (const productPackage of manifest.packages ?? []) {
+    entries.push({
       kind: "package",
       name: productPackage.name,
       status: productPackage.status,
       folder: productPackage.path,
-    };
+      specId: productPackage.name,
+    });
+  }
+
+  for (const frameworkPackage of manifest.framework?.packages ?? []) {
+    entries.push({
+      kind: "framework-package",
+      name: frameworkPackage.name,
+      status: frameworkPackage.status,
+      folder: frameworkPackage.path,
+      // A published npm name is not a spec id: the link is DECLARED.
+      specId: frameworkPackage.spec === null ? null : specIdOf(frameworkPackage.spec),
+    });
   }
 
-  return undefined;
+  return entries;
+}
+
+/**
+ * The entry owning `specId`, feature first. Names are unique across the whole
+ * map (the schema refuses a package named like a feature), so the order only
+ * decides which lookup runs first, never which answer is right.
+ */
+export function findSpecOwner(
+  manifest: OgygieManifest,
+  specId: string,
+): SpecOwner | undefined {
+  const owning = declaredEntries(manifest).filter((entry) => entry.specId === specId);
+  if (owning.length === 0) return undefined;
+  // Feature first: names are unique across the map (the schema refuses a
+  // package named like a feature), so the order decides which lookup runs
+  // first, never which answer is right. Among several framework packages
+  // pointing at the SAME spec — a framework spec often spans the core and the
+  // CLI — the LEAST advanced answers: a spec is delivered when all its code is.
+  const byPriority = owning.slice().sort((left, right) => {
+    if (left.kind !== right.kind) {
+      const order: SpecOwnerKind[] = ["feature", "package", "framework-package"];
+      return order.indexOf(left.kind) - order.indexOf(right.kind);
+    }
+    return ADVANCEMENT.indexOf(left.status) - ADVANCEMENT.indexOf(right.status);
+  });
+  const owner = byPriority[0];
+  if (owner === undefined) return undefined;
+  return { kind: owner.kind, name: owner.name, status: owner.status, folder: owner.folder };
 }
 
 /** What a refusal should suggest — both natures, never one that cannot exist. */
 export const SPEC_OWNER_FIX =
-  "Set the owning entry to delivered in the manifest — a feature under `features`, or a library under `packages` — or keep the spec in validated.";
+  "Set the owning entry to delivered in the manifest — a feature under `features`, a library under `packages`, or a published package under `framework.packages` (which names its spec explicitly) — or keep the spec in validated.";

package/src/manifest.schema.test.ts

@@ -220,6 +220,78 @@ describe("manifest — ogygieVersion et bloc framework (spec ogygie-standalone-r
             name: "@ogygie/core",
             path: "packages/ogygie-core",
             intent: "Schémas, erreurs et outillage génériques du framework.",
+            spec: null,
+            status: "delivered",
+          },
+        ],
+        templates: { project: "templates/project", feature: "templates/feature" },
+        governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+      },
+    };
+    expect(OgygieManifestSchema.safeParse(manifest).success).toBe(true);
+  });
+
+  // A published package is an OWNER of specs like any other entry of the map.
+  // What follows guards the day that was discovered — a spec verifier that
+  // ignores a nature answers "no owner" and lets a delivered spec look unborn
+  // (FAILURES.md 2026-08-25).
+  it("MUTATION : un package du framework sans `status` est refusé (le cycle de vie ne devine pas)", () => {
+    const manifest = {
+      ...manifestWithFeature({}),
+      framework: {
+        packages: [
+          {
+            name: "@ogygie/core",
+            path: "packages/ogygie-core",
+            intent: "Schémas, erreurs et outillage génériques du framework.",
+            spec: null,
+          },
+        ],
+        templates: { project: "templates/project", feature: "templates/feature" },
+        governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+      },
+    };
+    expect(OgygieManifestSchema.safeParse(manifest).success).toBe(false);
+  });
+
+  it("MUTATION : un package du framework qui revendique la spec d'une FEATURE est refusé", () => {
+    const manifest = {
+      ...manifestWithFeature({}),
+      framework: {
+        packages: [
+          {
+            name: "@ogygie/shell",
+            path: "packages/ogygie-shell",
+            intent: "Package revendiquant la spec déjà possédée par la feature web-shell.",
+            spec: "specs/web-shell.spec.md",
+            status: "delivered",
+          },
+        ],
+        templates: { project: "templates/project", feature: "templates/feature" },
+        governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+      },
+    };
+    expect(OgygieManifestSchema.safeParse(manifest).success).toBe(false);
+  });
+
+  it("DEUX packages du framework peuvent porter la MÊME spec : une spec du framework enjambe souvent core et cli", () => {
+    const manifest = {
+      ...manifestWithFeature({}),
+      framework: {
+        packages: [
+          {
+            name: "@ogygie/core",
+            path: "packages/ogygie-core",
+            intent: "Moitié jugement de la spec, sans aucune collecte disque.",
+            spec: "specs/outillage.spec.md",
+            status: "delivered",
+          },
+          {
+            name: "@ogygie/cli",
+            path: "packages/ogygie-cli",
+            intent: "Moitié collecte de la même spec, appelée par la CI gouvernée.",
+            spec: "specs/outillage.spec.md",
+            status: "in-progress",
           },
         ],
         templates: { project: "templates/project", feature: "templates/feature" },

package/src/manifest.schema.ts

@@ -145,6 +145,20 @@ export const FrameworkManifestSchema = z.object({
       name: z.string().describe("Published npm name, e.g. @ogygie/core"),
       path: z.string().describe("Folder relative to the repo root"),
       intent: z.string().min(20),
+      /**
+       * The spec describing this package, when one does. Named EXPLICITLY
+       * because a published npm name (`@ogygie/mcp`) is not a spec id
+       * (`ogygie-mcp`) — the other two natures of entry match by name, this
+       * one cannot. Several packages may point at the same spec: a spec of
+       * the framework often spans the core and the CLI.
+       */
+      spec: z.string().nullable(),
+      /**
+       * How far along, in the SAME words as the other natures. Required, and
+       * deliberately without default: a lifecycle gate that guesses a status
+       * confirms specs nobody delivered.
+       */
+      status: z.enum(["skeleton", "in-progress", "delivered"]),
     }),
   ),
   templates: z.object({
@@ -310,6 +324,27 @@ export const OgygieManifestSchema = z.object({
       packageNames.add(packageEntry.name);
     });
 
+    // One spec, one owner, ACROSS the three natures. A framework package
+    // pointing at a spec a feature or a product package already owns would
+    // give the lifecycle gate two answers, and it only ever reads the first.
+    const specIdOf = (specPath: string): string =>
+      (specPath.split("/").pop() ?? specPath).replace(/\.spec\.md$/, "");
+    const ownedSpecIds = new Set<string>([
+      ...manifest.features.map((feature) => feature.name),
+      ...packageNames,
+    ]);
+    (manifest.framework?.packages ?? []).forEach((packageEntry, index) => {
+      if (packageEntry.spec === null) return;
+      const specId = specIdOf(packageEntry.spec);
+      if (ownedSpecIds.has(specId)) {
+        context.addIssue({
+          code: "custom",
+          path: ["framework", "packages", index, "spec"],
+          message: `spec "${specId}" is already owned by a feature or a product package — one spec, one owner`,
+        });
+      }
+    });
+
     // Every `package:<name>` must designate a DECLARED package, wherever it is
     // written: a dangling dependency describes a map nobody can follow.
     const checkPackageDependencies = (

package/src/repo-adapter.test.ts

@@ -0,0 +1,192 @@
+/**
+ * @intent Proves the read-only repo access of DECISIONS.md D10, and guards the
+ * mutations that make such a module lie instead of fail: a traversal guard
+ * comparing prefixes without a separator, a symlink walking out of the repo, a
+ * `.git` that is a FILE (every worktree), a ref stored packed rather than
+ * loose. Each of those returns a plausible answer when it is wrong, which is
+ * why each has its test.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { OgygieFailure } from "./error.schema.js";
+import {
+  createFilesystemRepoAdapter,
+  createInMemoryRepoAdapter,
+  type RepoAdapter,
+} from "./repo-adapter.js";
+
+/** The stable code carried by a thrown OgygieFailure. */
+function codeOf(thrown: unknown): string {
+  return thrown instanceof OgygieFailure ? thrown.error.code : "<not an OgygieFailure>";
+}
+
+async function expectRefusal(action: () => Promise<unknown>, expectedCode: string): Promise<void> {
+  await expect(action()).rejects.toSatisfy(
+    (thrown: unknown) => codeOf(thrown) === expectedCode,
+    `expected an OgygieError with code ${expectedCode}`,
+  );
+}
+
+describe("repo-adapter — lecture du disque", () => {
+  let rootDir: string;
+  let outsideDir: string;
+  let adapter: RepoAdapter;
+
+  beforeAll(async () => {
+    const base = await mkdtemp(join(tmpdir(), "ogygie-repo-"));
+    rootDir = join(base, "repo");
+    outsideDir = join(base, "repo-evil");
+    await mkdir(join(rootDir, "src", "features", "orders"), { recursive: true });
+    await mkdir(outsideDir, { recursive: true });
+    await writeFile(join(rootDir, "AGENTS.md"), "règles", "utf8");
+    await writeFile(join(rootDir, "src", "features", "orders", "schemas.ts"), "export const a = 1;\n", "utf8");
+    await writeFile(join(rootDir, "src", "features", "orders", "service.ts"), "// service\n", "utf8");
+    await writeFile(join(outsideDir, "secrets.env"), "TOKEN=leaked", "utf8");
+    await mkdir(join(rootDir, "node_modules", "left-pad"), { recursive: true });
+    await writeFile(join(rootDir, "node_modules", "left-pad", "index.js"), "module.exports = 1;", "utf8");
+    await symlink(join(outsideDir, "secrets.env"), join(rootDir, "escape.env"));
+    adapter = createFilesystemRepoAdapter(rootDir);
+  });
+
+  afterAll(async () => {
+    await rm(join(rootDir, ".."), { recursive: true, force: true });
+  });
+
+  it("ÉTANT DONNÉ un fichier du repo QUAND on le lit ALORS son contenu revient tel quel", async () => {
+    expect(await adapter.readFile("AGENTS.md")).toBe("règles");
+  });
+
+  it("un listing est RÉCURSIF, trié, et porte la taille de chaque fichier", async () => {
+    const entries = await adapter.listDirectory("src/features/orders");
+    expect(entries.map((entry) => entry.path)).toEqual(["schemas.ts", "service.ts"]);
+    expect(entries[0]?.sizeBytes).toBe(20);
+  });
+
+  it("un dossier ABSENT liste vide — une feature en squelette est un état légitime", async () => {
+    expect(await adapter.listDirectory("src/features/inexistante")).toEqual([]);
+  });
+
+  it("node_modules et les dossiers cachés ne sont jamais listés", async () => {
+    const paths = (await adapter.listDirectory(".")).map((entry) => entry.path);
+    expect(paths).toContain("AGENTS.md");
+    expect(paths.some((path) => path.startsWith("node_modules/"))).toBe(false);
+  });
+
+  it("MUTATION : un chemin remontant vers un repo VOISIN est refusé, rien n'est lu", async () => {
+    // The neighbour is named "repo-evil" next to "repo" on purpose: a guard
+    // comparing prefixes without a separator lets it through, since
+    // "/…/repo-evil" does start with "/…/repo".
+    await expectRefusal(() => adapter.readFile("../repo-evil/secrets.env"), "PATH_OUTSIDE_REPO");
+  });
+
+  it("MUTATION : un chemin ABSOLU est refusé", async () => {
+    await expectRefusal(() => adapter.readFile(join(outsideDir, "secrets.env")), "PATH_OUTSIDE_REPO");
+  });
+
+  it("MUTATION : un lien symbolique sortant est refusé, bien que son chemin soit propre", async () => {
+    await expectRefusal(() => adapter.readFile("escape.env"), "PATH_OUTSIDE_REPO");
+  });
+
+  it("un fichier absent échoue avec un code stable, jamais un contenu vide", async () => {
+    await expectRefusal(() => adapter.readFile("jamais-ecrit.md"), "REPO_FILE_NOT_FOUND");
+  });
+
+  it("exists répond sans jamais lever pour un fichier absent", async () => {
+    expect(await adapter.exists("AGENTS.md")).toBe(true);
+    expect(await adapter.exists("jamais-ecrit.md")).toBe(false);
+  });
+
+  it("un dossier qui n'est PAS un clone git rend un ref null — jamais un identifiant inventé", async () => {
+    expect(await adapter.currentRef()).toBeNull();
+  });
+});
+
+describe("repo-adapter — le ref git, dans les trois formes que git donne à `.git`", () => {
+  let base: string;
+
+  const git = (cwd: string, ...args: string[]): string =>
+    execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        GIT_AUTHOR_NAME: "Fixture",
+        GIT_AUTHOR_EMAIL: "fixture@example.invalid",
+        GIT_COMMITTER_NAME: "Fixture",
+        GIT_COMMITTER_EMAIL: "fixture@example.invalid",
+      },
+    }).trim();
+
+  let clone: string;
+  let head: string;
+
+  beforeAll(async () => {
+    base = await mkdtemp(join(tmpdir(), "ogygie-git-"));
+    clone = join(base, "clone");
+    await mkdir(clone);
+    git(clone, "init", "--initial-branch=main");
+    await writeFile(join(clone, "AGENTS.md"), "règles", "utf8");
+    git(clone, "add", "AGENTS.md");
+    git(clone, "commit", "-m", "fixture");
+    head = git(clone, "rev-parse", "HEAD");
+  });
+
+  afterAll(async () => {
+    await rm(base, { recursive: true, force: true });
+  });
+
+  it("ÉTANT DONNÉ un clone ordinaire QUAND on demande le ref ALORS c'est le SHA de HEAD", async () => {
+    expect(await createFilesystemRepoAdapter(clone).currentRef()).toBe(head);
+  });
+
+  it("ÉTANT DONNÉ un WORKTREE, dont `.git` est un FICHIER, ALORS le ref est trouvé quand même", async () => {
+    // The form this repo itself works in. A reader that only knows the
+    // directory form answers null here — and null is a legitimate answer
+    // elsewhere, so nothing would ever protest.
+    const worktree = join(base, "wt");
+    git(clone, "worktree", "add", "-b", "essai", worktree);
+    const worktreeHead = git(worktree, "rev-parse", "HEAD");
+    expect(await createFilesystemRepoAdapter(worktree).currentRef()).toBe(worktreeHead);
+  });
+
+  it("ÉTANT DONNÉ des refs COMPACTÉES QUAND on demande le ref ALORS packed-refs répond", async () => {
+    git(clone, "pack-refs", "--all");
+    expect(await createFilesystemRepoAdapter(clone).currentRef()).toBe(head);
+  });
+
+  it("ÉTANT DONNÉ une HEAD DÉTACHÉE ALORS le SHA qu'elle porte est rendu directement", async () => {
+    const detached = join(base, "detached");
+    git(clone, "worktree", "add", "--detach", detached, head);
+    expect(await createFilesystemRepoAdapter(detached).currentRef()).toBe(head);
+  });
+});
+
+describe("repo-adapter — fixture en mémoire", () => {
+  const adapter = createInMemoryRepoAdapter({
+    "AGENTS.md": "règles",
+    "specs/notes.spec.md": "---\nid: notes\n---\n",
+    "src/features/notes/schemas.ts": "export const a = 1;\n",
+  });
+
+  it("lit, liste par préfixe et rend des tailles en OCTETS, pas en caractères", async () => {
+    expect(await adapter.readFile("AGENTS.md")).toBe("règles");
+    const entries = await adapter.listDirectory("specs");
+    expect(entries).toEqual([{ path: "notes.spec.md", sizeBytes: 18 }]);
+    // "règles" is 6 characters and 7 bytes: a size in characters would lie to
+    // every caller enforcing a byte budget.
+    const root = await adapter.listDirectory("");
+    expect(root.find((entry) => entry.path === "AGENTS.md")?.sizeBytes).toBe(7);
+  });
+
+  it("un fichier absent échoue du MÊME code que sur disque", async () => {
+    await expectRefusal(() => adapter.readFile("absent.md"), "REPO_FILE_NOT_FOUND");
+  });
+
+  it("le ref est fourni par la fixture, et peut modéliser un dossier sans git", async () => {
+    expect(await adapter.currentRef()).toBe("0".repeat(40));
+    expect(await createInMemoryRepoAdapter({}, { ref: null }).currentRef()).toBeNull();
+  });
+});