@ogygie/studio 0.8.0 → 0.10.0

package/dist/server.js

@@ -39,17 +39,182 @@ function throwOgygieError(input, httpStatus = 500) {
 }
 
 // src/server/storage/local-adapter.ts
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, normalize } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute as isAbsolute2, resolve as resolve2, sep as sep2 } from "node:path";
+
+// ../ogygie-core/src/repo-adapter.ts
+import { readFile as readFileFromDisk, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { z as z2 } from "zod";
+var RepoFileEntrySchema = z2.object({
+  /** Path relative to the LISTED directory, "/" separated, never absolute. */
+  path: z2.string(),
+  sizeBytes: z2.number().int().nonnegative()
+});
+var NEVER_LISTED = /* @__PURE__ */ new Set(["node_modules"]);
+function isSkippedDirectory(name) {
+  return name.startsWith(".") || NEVER_LISTED.has(name);
+}
+function refusePathOutsideRepo(relativePath, cause) {
+  return throwOgygieError(
+    {
+      code: "PATH_OUTSIDE_REPO",
+      message: "The requested path resolves outside the repo root.",
+      file: relativePath,
+      cause,
+      suggestedFix: "Address a path INSIDE the repo, written relative to its root and without `..`."
+    },
+    400
+  );
+}
 function resolveInsideRoot(rootDir, relativePath) {
-  const absolute = normalize(join(rootDir, relativePath));
-  if (!absolute.startsWith(normalize(rootDir))) {
+  if (isAbsolute(relativePath)) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" is an absolute path`);
+  }
+  const root = resolve(rootDir);
+  const absolute = resolve(root, relativePath);
+  if (absolute !== root && !absolute.startsWith(root + sep)) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" resolves to "${absolute}", outside "${root}"`);
+  }
+  return absolute;
+}
+async function assertRealPathInsideRoot(rootDir, absolute, relativePath) {
+  let realRoot;
+  let realTarget;
+  try {
+    realRoot = await realpath(rootDir);
+    realTarget = await realpath(absolute);
+  } catch {
+    return;
+  }
+  if (realTarget !== realRoot && !realTarget.startsWith(realRoot + sep)) {
+    refusePathOutsideRepo(
+      relativePath,
+      `"${relativePath}" is a symbolic link leading to "${realTarget}", outside "${realRoot}"`
+    );
+  }
+}
+async function listFilesRecursively(absoluteDir, prefix) {
+  let entries;
+  try {
+    entries = await readdir(absoluteDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      if (isSkippedDirectory(entry.name)) continue;
+      files.push(...await listFilesRecursively(join(absoluteDir, entry.name), relativePath));
+    } else if (entry.isFile()) {
+      const stats = await stat(join(absoluteDir, entry.name));
+      files.push({ path: relativePath, sizeBytes: stats.size });
+    }
+  }
+  return files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+async function resolveGitDirs(rootDir) {
+  const dotGit = join(rootDir, ".git");
+  let gitDir;
+  try {
+    const stats = await stat(dotGit);
+    if (stats.isDirectory()) {
+      gitDir = dotGit;
+    } else {
+      const pointer = (await readFileFromDisk(dotGit, "utf8")).trim();
+      const target = pointer.startsWith("gitdir:") ? pointer.slice("gitdir:".length).trim() : "";
+      if (target === "") return null;
+      gitDir = isAbsolute(target) ? target : resolve(rootDir, target);
+    }
+  } catch {
+    return null;
+  }
+  try {
+    const commonPointer = (await readFileFromDisk(join(gitDir, "commondir"), "utf8")).trim();
+    return { gitDir, commonDir: isAbsolute(commonPointer) ? commonPointer : resolve(gitDir, commonPointer) };
+  } catch {
+    return { gitDir, commonDir: gitDir };
+  }
+}
+async function readRefSha(dirs, refName) {
+  for (const base of [dirs.gitDir, dirs.commonDir]) {
+    try {
+      const sha = (await readFileFromDisk(join(base, refName), "utf8")).trim();
+      if (sha !== "") return sha;
+    } catch {
+    }
+  }
+  try {
+    const packed = await readFileFromDisk(join(dirs.commonDir, "packed-refs"), "utf8");
+    for (const line of packed.split("\n")) {
+      if (line.startsWith("#") || line.startsWith("^")) continue;
+      const [sha, name] = line.trim().split(" ");
+      if (name === refName && sha !== void 0 && sha !== "") return sha;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function createFilesystemRepoAdapter(rootDir) {
+  return {
+    async readFile(relativePath) {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      try {
+        return await readFileFromDisk(absolute, "utf8");
+      } catch (thrown) {
+        return throwOgygieError({
+          code: "REPO_FILE_NOT_FOUND",
+          message: "The requested file cannot be read from the repo.",
+          file: relativePath,
+          cause: `reading "${absolute}" failed: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+          suggestedFix: "Check the path against what the map declares \u2014 the manifest is the only chart of a repo."
+        });
+      }
+    },
+    async listDirectory(relativePath) {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      return listFilesRecursively(absolute, "");
+    },
+    async exists(relativePath) {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      try {
+        await stat(absolute);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async currentRef() {
+      const dirs = await resolveGitDirs(rootDir);
+      if (dirs === null) return null;
+      let head;
+      try {
+        head = (await readFileFromDisk(join(dirs.gitDir, "HEAD"), "utf8")).trim();
+      } catch {
+        return null;
+      }
+      if (!head.startsWith("ref:")) return head === "" ? null : head;
+      return readRefSha(dirs, head.slice("ref:".length).trim());
+    }
+  };
+}
+
+// src/server/storage/local-adapter.ts
+function resolveInsideRoot2(rootDir, relativePath) {
+  const root = resolve2(rootDir);
+  const absolute = resolve2(root, relativePath);
+  if (isAbsolute2(relativePath) || absolute !== root && !absolute.startsWith(root + sep2)) {
     throwOgygieError(
       {
-        code: "STORAGE_PATH_OUTSIDE_ROOT",
+        code: "PATH_OUTSIDE_REPO",
         message: "The requested path escapes the repo root.",
-        file: null,
-        cause: `relative path "${relativePath}" resolves outside "${rootDir}"`,
+        file: relativePath,
+        cause: `relative path "${relativePath}" resolves to "${absolute}", outside "${root}"`,
         suggestedFix: "Only address files inside the repo (specs/, ogygie.manifest.json)."
       },
       400
@@ -58,32 +223,11 @@ function resolveInsideRoot(rootDir, relativePath) {
   return absolute;
 }
 function createLocalSpecStorage(rootDir) {
+  const reader = createFilesystemRepoAdapter(rootDir);
   return {
-    async list(dir) {
-      const absolute = resolveInsideRoot(rootDir, dir);
-      try {
-        const entries = await readdir(absolute, { withFileTypes: true });
-        return entries.filter((entry) => entry.isFile()).map((entry) => ({ name: entry.name }));
-      } catch {
-        return [];
-      }
-    },
-    async read(path) {
-      const absolute = resolveInsideRoot(rootDir, path);
-      try {
-        return await readFile(absolute, "utf8");
-      } catch {
-        return throwOgygieError({
-          code: "STORAGE_FILE_NOT_FOUND",
-          message: "The requested file cannot be read from the repo.",
-          file: path,
-          cause: `readFile failed for "${absolute}"`,
-          suggestedFix: "Check that the studio was launched from an Ogygie repo root (specs/ + ogygie.manifest.json)."
-        });
-      }
-    },
+    ...reader,
     async write(path, content, _message) {
-      const absolute = resolveInsideRoot(rootDir, path);
+      const absolute = resolveInsideRoot2(rootDir, path);
       await mkdir(dirname(absolute), { recursive: true });
       await writeFile(absolute, content, "utf8");
     }
@@ -99,99 +243,113 @@ import {
 } from "fastify-type-provider-zod";
 
 // ../ogygie-core/src/spec.schema.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // ../ogygie-core/src/manifest.schema.ts
-import { z as z2 } from "zod";
-var FeatureNameSchema = z2.string().regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "kebab-case required");
-var PackageDependencySchema = z2.string().regex(/^package:[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "expected package:<kebab-case-name>");
-var HttpRouteSchema = z2.object({
-  method: z2.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
-  path: z2.string().startsWith("/api/"),
-  description: z2.string().min(10),
-  schemaInput: z2.string().describe("Exported name of the input Zod schema, e.g. CreateOrderInputSchema"),
-  schemaOutput: z2.string().describe("Exported name of the output Zod schema"),
-  invalidates: z2.array(z2.string()).optional().describe(
+import { z as z3 } from "zod";
+var FeatureNameSchema = z3.string().regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "kebab-case required");
+var PackageDependencySchema = z3.string().regex(/^package:[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "expected package:<kebab-case-name>");
+var HttpRouteSchema = z3.object({
+  method: z3.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  path: z3.string().startsWith("/api/"),
+  description: z3.string().min(10),
+  schemaInput: z3.string().describe("Exported name of the input Zod schema, e.g. CreateOrderInputSchema"),
+  schemaOutput: z3.string().describe("Exported name of the output Zod schema"),
+  invalidates: z3.array(z3.string()).optional().describe(
     "Cache roots this mutation stales BEYOND its own path root (cross-feature dependency, read by the manifest-derived client \u2014 never guessed in a screen). Each value must be an existing feature name or route root"
   )
 });
-var SharedTableKindSchema = z2.enum(["reference", "ownerless"]);
-var DbTableDeclarationSchema = z2.union([
-  z2.string(),
-  z2.object({
-    name: z2.string(),
-    shared: z2.literal(true),
+var SharedTableKindSchema = z3.enum(["reference", "ownerless"]);
+var DbTableDeclarationSchema = z3.union([
+  z3.string(),
+  z3.object({
+    name: z3.string(),
+    shared: z3.literal(true),
     sharedKind: SharedTableKindSchema.optional()
   })
 ]);
-var FeatureManifestSchema = z2.object({
+var FeatureManifestSchema = z3.object({
   name: FeatureNameSchema,
-  intent: z2.string().min(20).max(300).describe("The feature's 'why' in 1-3 sentences"),
-  app: z2.string().optional().describe("Name of the owning app (apps[].name); defaults to the api app"),
-  folder: z2.string().describe("Path relative to the app root, e.g. src/features/orders"),
-  spec: z2.string().nullable().describe("Path to the spec, e.g. specs/orders.spec.md, null for technical features"),
-  routes: z2.array(HttpRouteSchema),
-  dbTables: z2.array(DbTableDeclarationSchema).describe(
+  intent: z3.string().min(20).max(300).describe("The feature's 'why' in 1-3 sentences"),
+  app: z3.string().optional().describe("Name of the owning app (apps[].name); defaults to the api app"),
+  folder: z3.string().describe("Path relative to the app root, e.g. src/features/orders"),
+  spec: z3.string().nullable().describe("Path to the spec, e.g. specs/orders.spec.md, null for technical features"),
+  routes: z3.array(HttpRouteSchema),
+  dbTables: z3.array(DbTableDeclarationSchema).describe(
     "Drizzle tables owned by this feature (one table = one owner). String = tenant-scoped; { name, shared: true } = shared referential"
   ),
-  dependsOn: z2.array(z2.union([FeatureNameSchema, PackageDependencySchema])).describe(
+  dependsOn: z3.array(z3.union([FeatureNameSchema, PackageDependencySchema])).describe(
     "Features imported through their index.ts, and product packages as package:<name> \u2014 nothing else"
   ),
-  status: z2.enum(["skeleton", "in-progress", "delivered"])
+  status: z3.enum(["skeleton", "in-progress", "delivered"])
 });
-var OgygieVersionSchema = z2.string().regex(/^\d+\.\d+\.\d+$/, "expected a plain x.y.z version");
-var FrameworkManifestSchema = z2.object({
-  packages: z2.array(
-    z2.object({
-      name: z2.string().describe("Published npm name, e.g. @ogygie/core"),
-      path: z2.string().describe("Folder relative to the repo root"),
-      intent: z2.string().min(20)
+var OgygieVersionSchema = z3.string().regex(/^\d+\.\d+\.\d+$/, "expected a plain x.y.z version");
+var FrameworkManifestSchema = z3.object({
+  packages: z3.array(
+    z3.object({
+      name: z3.string().describe("Published npm name, e.g. @ogygie/core"),
+      path: z3.string().describe("Folder relative to the repo root"),
+      intent: z3.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: z3.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: z3.enum(["skeleton", "in-progress", "delivered"])
     })
   ),
-  templates: z2.object({
-    project: z2.string().describe("Folder copied by `ogygie init`"),
-    feature: z2.string().describe("Reserved for `ogygie generate feature` (not wired yet)")
+  templates: z3.object({
+    project: z3.string().describe("Folder copied by `ogygie init`"),
+    feature: z3.string().describe("Reserved for `ogygie generate feature` (not wired yet)")
   }),
-  governedFiles: z2.string().describe("Module declaring the exhaustive list of files `upgrade` may overwrite (D3)")
+  governedFiles: z3.string().describe("Module declaring the exhaustive list of files `upgrade` may overwrite (D3)")
 });
-var VocabularyEntrySchema = z2.object({
-  canonical: z2.string().regex(/^[a-z][a-zA-Z0-9]*$/, "camelCase English term required").describe("The one machine term for this concept, e.g. gadget"),
-  forbiddenAliases: z2.array(
-    z2.string().min(2).regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "lowercase root (kebab-case allowed) required")
+var VocabularyEntrySchema = z3.object({
+  canonical: z3.string().regex(/^[a-z][a-zA-Z0-9]*$/, "camelCase English term required").describe("The one machine term for this concept, e.g. gadget"),
+  forbiddenAliases: z3.array(
+    z3.string().min(2).regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "lowercase root (kebab-case allowed) required")
   ).min(1).describe("Roots the code may never carry for this concept, e.g. widget"),
-  reference: z2.string().optional().describe("Anchor into AGENTS.product.md where the concept is explained")
+  reference: z3.string().optional().describe("Anchor into AGENTS.product.md where the concept is explained")
 });
-var ProductVocabularySchema = z2.object({
-  entries: z2.array(VocabularyEntrySchema)
+var ProductVocabularySchema = z3.object({
+  entries: z3.array(VocabularyEntrySchema)
 });
-var PackageManifestSchema = z2.object({
+var PackageManifestSchema = z3.object({
   name: FeatureNameSchema,
-  path: z2.string().describe("Folder relative to the repo root, e.g. packages/solver"),
-  intent: z2.string().min(20).max(300).describe("The package's 'why' in 1-3 sentences"),
-  spec: z2.string().nullable(),
-  dependsOn: z2.array(PackageDependencySchema).describe("Other PRODUCT packages, as package:<name> \u2014 never a feature: a package that depended on one would live under an app, and would be a feature"),
-  status: z2.enum(["skeleton", "in-progress", "delivered"])
+  path: z3.string().describe("Folder relative to the repo root, e.g. packages/solver"),
+  intent: z3.string().min(20).max(300).describe("The package's 'why' in 1-3 sentences"),
+  spec: z3.string().nullable(),
+  dependsOn: z3.array(PackageDependencySchema).describe("Other PRODUCT packages, as package:<name> \u2014 never a feature: a package that depended on one would live under an app, and would be a feature"),
+  status: z3.enum(["skeleton", "in-progress", "delivered"])
 });
-var TenancyManifestSchema = z2.object({
-  column: z2.string().min(1).describe("SQL name of the tenant column, e.g. workspace_id \u2014 the one AGENTS.product.md announces"),
-  rawDbAllowed: z2.array(FeatureNameSchema).default([]).describe(
+var TenancyManifestSchema = z3.object({
+  column: z3.string().min(1).describe("SQL name of the tenant column, e.g. workspace_id \u2014 the one AGENTS.product.md announces"),
+  rawDbAllowed: z3.array(FeatureNameSchema).default([]).describe(
     "Features allowed to reach the raw database: the tenancy socle, which BUILDS the contexts and therefore predates them. Every other feature goes through tenantDb"
   )
 });
-var OgygieManifestSchema = z2.object({
-  version: z2.literal(1),
-  product: z2.object({
-    name: z2.string(),
-    description: z2.string().min(20)
+var OgygieManifestSchema = z3.object({
+  version: z3.literal(1),
+  product: z3.object({
+    name: z3.string(),
+    description: z3.string().min(20)
   }),
   ogygieVersion: OgygieVersionSchema.optional(),
   framework: FrameworkManifestSchema.optional(),
-  apps: z2.array(
-    z2.object({
-      name: z2.string(),
-      path: z2.string(),
-      type: z2.enum(["api", "front", "gateway"]),
-      entryPoint: z2.string(),
+  apps: z3.array(
+    z3.object({
+      name: z3.string(),
+      path: z3.string(),
+      type: z3.enum(["api", "front", "gateway"]),
+      entryPoint: z3.string(),
       /**
        * Code the product HOSTS without maintaining it — imported as-is from
        * elsewhere, the framework's own dev tooling being the typical case.
@@ -204,21 +362,21 @@ var OgygieManifestSchema = z2.object({
        * ANNOUNCES it on every run — one that stops being visible is one that
        * gets forgotten.
        */
-      vendored: z2.literal(true).optional()
+      vendored: z3.literal(true).optional()
     })
   ),
-  features: z2.array(FeatureManifestSchema),
+  features: z3.array(FeatureManifestSchema),
   tenancy: TenancyManifestSchema.optional().describe(
     "Product values the framework gates need \u2014 absent, the tenancy checks do not run"
   ),
-  packages: z2.array(PackageManifestSchema).optional().describe("Product code living outside every app \u2014 libraries, engines. Absent = the project has none"),
+  packages: z3.array(PackageManifestSchema).optional().describe("Product code living outside every app \u2014 libraries, engines. Absent = the project has none"),
   vocabulary: ProductVocabularySchema.optional().describe(
     "The product's closed vocabulary \u2014 declared here, enforced by `ogygie verify-vocabulary`. Absent = gate silent"
   ),
-  conventions: z2.object({
-    agentsMd: z2.literal("AGENTS.md"),
-    failuresMd: z2.literal("FAILURES.md"),
-    specsFolder: z2.literal("specs/")
+  conventions: z3.object({
+    agentsMd: z3.literal("AGENTS.md"),
+    failuresMd: z3.literal("FAILURES.md"),
+    specsFolder: z3.literal("specs/")
   })
 }).superRefine((manifest, context) => {
   const featureNames = new Set(manifest.features.map((feature) => feature.name));
@@ -240,6 +398,22 @@ var OgygieManifestSchema = z2.object({
     }
     packageNames.add(packageEntry.name);
   });
+  const specIdOf = (specPath) => (specPath.split("/").pop() ?? specPath).replace(/\.spec\.md$/, "");
+  const ownedSpecIds = /* @__PURE__ */ new Set([
+    ...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 \u2014 one spec, one owner`
+      });
+    }
+  });
   const checkPackageDependencies = (dependsOn, path) => {
     dependsOn.forEach((dependency, dependencyIndex) => {
       if (!dependency.startsWith("package:")) return;
@@ -352,17 +526,17 @@ var OgygieManifestSchema = z2.object({
 });
 
 // ../ogygie-core/src/spec.schema.ts
-var DeferredBehaviorSchema = z3.string().regex(
+var DeferredBehaviorSchema = z4.string().regex(
   /^.+ blockedBy:[a-z][a-z0-9]*(-[a-z0-9]+)*$/,
   'Expected "<behavior> blockedBy:<feature-name>" (feature name in kebab-case)'
 );
-var SpecFrontmatterSchema = z3.object({
+var SpecFrontmatterSchema = z4.object({
   id: FeatureNameSchema.describe("Identical to the feature name in the manifest"),
-  status: z3.enum(["draft", "validated", "implemented"]),
-  depends_on: z3.array(FeatureNameSchema),
-  priority: z3.enum(["P0", "P1", "P2"]),
-  refs: z3.array(z3.string()).default([]).describe("References to the domain model, e.g. 'modele-gally \xA74.2'"),
-  deferred: z3.array(DeferredBehaviorSchema).default([]).describe("Behaviors deferred to a later feature (DECISIONS.md D13)")
+  status: z4.enum(["draft", "validated", "implemented"]),
+  depends_on: z4.array(FeatureNameSchema),
+  priority: z4.enum(["P0", "P1", "P2"]),
+  refs: z4.array(z4.string()).default([]).describe("References to the domain model, e.g. 'modele-gally \xA74.2'"),
+  deferred: z4.array(DeferredBehaviorSchema).default([]).describe("Behaviors deferred to a later feature (DECISIONS.md D13)")
 });
 var SECTIONS_SPEC_OBLIGATOIRES = [
   "# @intent",
@@ -578,15 +752,15 @@ function toReadableSummary(filePath, spec) {
   };
 }
 async function listSpecFileNames(deps) {
-  const entries = await deps.storage.list(SPECS_DIR);
-  return entries.map((entry) => entry.name).filter((name) => name.endsWith(".spec.md") && !name.startsWith("_")).sort();
+  const entries = await deps.storage.listDirectory(SPECS_DIR);
+  return entries.map((entry) => entry.path).filter((path) => !path.includes("/")).filter((name) => name.endsWith(".spec.md") && !name.startsWith("_")).sort();
 }
 async function listSpecSummaries(deps) {
   const fileNames = await listSpecFileNames(deps);
   const summaries = [];
   for (const fileName of fileNames) {
     const filePath = `${SPECS_DIR}/${fileName}`;
-    const content = await deps.storage.read(filePath);
+    const content = await deps.storage.readFile(filePath);
     const parsed = parseSpec(filePath, fileName, content);
     const id = fileName.replace(/\.spec\.md$/, "");
     summaries.push(
@@ -611,7 +785,7 @@ async function readParsedSpec(deps, specId) {
     );
   }
   const filePath = specPathOf(specId);
-  const content = await deps.storage.read(filePath);
+  const content = await deps.storage.readFile(filePath);
   const parsed = parseSpec(filePath, fileName, content);
   if (!parsed.ok) {
     throw new OgygieFailure(parsed.error, 422);
@@ -714,7 +888,7 @@ async function createSpec(deps, specId) {
   }
   let template;
   try {
-    template = await deps.storage.read(TEMPLATE_PATH);
+    template = await deps.storage.readFile(TEMPLATE_PATH);
   } catch {
     return throwOgygieError({
       code: "SPEC_TEMPLATE_NOT_FOUND",
@@ -740,7 +914,7 @@ async function createSpec(deps, specId) {
   return toReadableSummary(filePath, parsed.spec);
 }
 async function getManifest(deps) {
-  const content = await deps.storage.read(MANIFEST_PATH);
+  const content = await deps.storage.readFile(MANIFEST_PATH);
   let raw;
   try {
     raw = JSON.parse(content);
@@ -773,52 +947,52 @@ async function getManifest(deps) {
 }
 
 // src/server/schemas.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var SpecStatusSchema = SpecFrontmatterSchema.shape.status;
-var ReadableSpecSummarySchema = z4.object({
+var ReadableSpecSummarySchema = z5.object({
   id: FeatureNameSchema,
   status: SpecStatusSchema,
   priority: SpecFrontmatterSchema.shape.priority,
-  depends_on: z4.array(FeatureNameSchema),
-  filePath: z4.string(),
-  presentSections: z4.array(z4.string())
+  depends_on: z5.array(FeatureNameSchema),
+  filePath: z5.string(),
+  presentSections: z5.array(z5.string())
 });
-var UnreadableSpecSummarySchema = z4.object({
-  id: z4.string(),
-  filePath: z4.string(),
+var UnreadableSpecSummarySchema = z5.object({
+  id: z5.string(),
+  filePath: z5.string(),
   error: OgygieErrorSchema
 });
-var SpecSummarySchema = z4.union([
+var SpecSummarySchema = z5.union([
   ReadableSpecSummarySchema,
   UnreadableSpecSummarySchema
 ]);
-var ListSpecsOutputSchema = z4.object({
-  specs: z4.array(SpecSummarySchema)
+var ListSpecsOutputSchema = z5.object({
+  specs: z5.array(SpecSummarySchema)
 });
-var SpecParamsSchema = z4.object({
+var SpecParamsSchema = z5.object({
   specId: FeatureNameSchema
 });
-var GetSpecOutputSchema = z4.object({
+var GetSpecOutputSchema = z5.object({
   frontmatter: SpecFrontmatterSchema,
   /** Markdown body after the frontmatter block, byte-exact. */
-  body: z4.string(),
-  presentSections: z4.array(z4.string())
+  body: z5.string(),
+  presentSections: z5.array(z5.string())
 });
-var UpdateSpecInputSchema = z4.object({
+var UpdateSpecInputSchema = z5.object({
   frontmatter: SpecFrontmatterSchema,
   /** Omitted ⇒ the existing markdown body is preserved byte-exact. */
-  body: z4.string().max(2e5).optional()
+  body: z5.string().max(2e5).optional()
 });
-var UpdateSpecOutputSchema = z4.object({
+var UpdateSpecOutputSchema = z5.object({
   spec: ReadableSpecSummarySchema
 });
-var CreateSpecInputSchema = z4.object({
+var CreateSpecInputSchema = z5.object({
   id: FeatureNameSchema.max(80)
 });
-var CreateSpecOutputSchema = z4.object({
+var CreateSpecOutputSchema = z5.object({
   spec: ReadableSpecSummarySchema
 });
-var GetManifestOutputSchema = z4.object({
+var GetManifestOutputSchema = z5.object({
   manifest: OgygieManifestSchema
 });