@ogygie/studio 0.4.0 → 0.5.1

package/dist/server.js

@@ -0,0 +1,904 @@
+// src/server/start.ts
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../ogygie-core/src/error.schema.ts
+import { z } from "zod";
+var OgygieErrorSchema = z.object({
+  ogygie: z.literal(true).describe("Marker: lets an agent tell our errors from noise"),
+  code: z.string().regex(/^[A-Z][A-Z0-9_]+$/, "SCREAMING_SNAKE_CASE, stable over time"),
+  message: z.string().min(10).describe("Human-readable sentence (technical English)"),
+  file: z.string().nullable().describe("Relative path of the file involved, null when not localizable"),
+  cause: z.string().describe("The precise datum or condition that triggered the error"),
+  suggestedFix: z.string().describe("Concrete action to fix \u2014 never empty"),
+  details: z.record(z.string(), z.unknown()).default({}),
+  timestamp: z.iso.datetime()
+});
+function ogygieError(input) {
+  return OgygieErrorSchema.parse({
+    ogygie: true,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    details: {},
+    ...input
+  });
+}
+var OgygieFailure = class extends Error {
+  error;
+  httpStatus;
+  constructor(error, httpStatus = 500) {
+    super(error.message);
+    this.name = "OgygieFailure";
+    this.error = error;
+    this.httpStatus = httpStatus;
+  }
+};
+function throwOgygieError(input, httpStatus = 500) {
+  throw new OgygieFailure(ogygieError(input), httpStatus);
+}
+
+// src/server/storage/local-adapter.ts
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, normalize } from "node:path";
+function resolveInsideRoot(rootDir, relativePath) {
+  const absolute = normalize(join(rootDir, relativePath));
+  if (!absolute.startsWith(normalize(rootDir))) {
+    throwOgygieError(
+      {
+        code: "STORAGE_PATH_OUTSIDE_ROOT",
+        message: "The requested path escapes the repo root.",
+        file: null,
+        cause: `relative path "${relativePath}" resolves outside "${rootDir}"`,
+        suggestedFix: "Only address files inside the repo (specs/, ogygie.manifest.json)."
+      },
+      400
+    );
+  }
+  return absolute;
+}
+function createLocalSpecStorage(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)."
+        });
+      }
+    },
+    async write(path, content, _message) {
+      const absolute = resolveInsideRoot(rootDir, path);
+      await mkdir(dirname(absolute), { recursive: true });
+      await writeFile(absolute, content, "utf8");
+    }
+  };
+}
+
+// src/server/app.ts
+import Fastify from "fastify";
+import {
+  hasZodFastifySchemaValidationErrors,
+  serializerCompiler,
+  validatorCompiler
+} from "fastify-type-provider-zod";
+
+// ../ogygie-core/src/spec.schema.ts
+import { z as z3 } 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 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(
+    "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 DbTableDeclarationSchema = z2.union([
+  z2.string(),
+  z2.object({ name: z2.string(), shared: z2.literal(true) })
+]);
+var FeatureManifestSchema = z2.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(
+    "Drizzle tables owned by this feature (one table = one owner). String = tenant-scoped; { name, shared: true } = shared referential"
+  ),
+  dependsOn: z2.array(FeatureNameSchema).describe("Features imported through their index.ts \u2014 nothing else"),
+  status: z2.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)
+    })
+  ),
+  templates: z2.object({
+    project: z2.string().describe("Folder copied by `ogygie init`"),
+    feature: z2.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)")
+});
+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")
+  ).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")
+});
+var ProductVocabularySchema = z2.object({
+  entries: z2.array(VocabularyEntrySchema)
+});
+var OgygieManifestSchema = z2.object({
+  version: z2.literal(1),
+  product: z2.object({
+    name: z2.string(),
+    description: z2.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(),
+      /**
+       * Code the product HOSTS without maintaining it — imported as-is from
+       * elsewhere, the framework's own dev tooling being the typical case.
+       * A vendored app is skipped by the vocabulary gate: a product's business
+       * vocabulary has no claim over code it will never rename.
+       *
+       * A literal `true`, like `shared` on a table: an app is either vendored
+       * (and says so) or the product's own (and stays silent) — no third
+       * state. The derogation is declared here, machine-readably, and the gate
+       * ANNOUNCES it on every run — one that stops being visible is one that
+       * gets forgotten.
+       */
+      vendored: z2.literal(true).optional()
+    })
+  ),
+  features: z2.array(FeatureManifestSchema),
+  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/")
+  })
+}).superRefine((manifest, context) => {
+  const canonicalOwners = /* @__PURE__ */ new Map();
+  const aliasOwners = /* @__PURE__ */ new Map();
+  (manifest.vocabulary?.entries ?? []).forEach((entry, index) => {
+    const canonicalRoot = entry.canonical.toLowerCase();
+    const firstOwner = canonicalOwners.get(canonicalRoot);
+    if (firstOwner !== void 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["vocabulary", "entries", index, "canonical"],
+        message: `canonical "${entry.canonical}" is already declared by entry ${firstOwner}`
+      });
+    } else {
+      canonicalOwners.set(canonicalRoot, index);
+    }
+  });
+  (manifest.vocabulary?.entries ?? []).forEach((entry, index) => {
+    entry.forbiddenAliases.forEach((alias, aliasIndex) => {
+      const path = ["vocabulary", "entries", index, "forbiddenAliases", aliasIndex];
+      const canonicalOwner = canonicalOwners.get(alias);
+      if (canonicalOwner !== void 0) {
+        context.addIssue({
+          code: "custom",
+          path,
+          message: `alias "${alias}" is the canonical term of entry ${canonicalOwner} \u2014 a term cannot be both`
+        });
+        return;
+      }
+      const firstOwner = aliasOwners.get(alias);
+      if (firstOwner !== void 0) {
+        context.addIssue({
+          code: "custom",
+          path,
+          message: `alias "${alias}" is already forbidden by entry ${firstOwner} \u2014 one alias belongs to one concept`
+        });
+        return;
+      }
+      aliasOwners.set(alias, index);
+    });
+  });
+  const appsByName = new Map(manifest.apps.map((app) => [app.name, app]));
+  const knownInvalidationTargets = new Set(
+    manifest.features.map((feature) => feature.name)
+  );
+  for (const feature of manifest.features) {
+    for (const route of feature.routes) {
+      const root = route.path.split("/")[2];
+      if (root !== void 0) knownInvalidationTargets.add(root);
+    }
+  }
+  manifest.features.forEach((feature, index) => {
+    feature.routes.forEach((route, routeIndex) => {
+      for (const target of route.invalidates ?? []) {
+        if (!knownInvalidationTargets.has(target)) {
+          context.addIssue({
+            code: "custom",
+            path: ["features", index, "routes", routeIndex, "invalidates"],
+            message: `invalidates target "${target}" matches no feature name and no route root`
+          });
+        }
+      }
+    });
+  });
+  manifest.features.forEach((feature, index) => {
+    if (feature.app === void 0) return;
+    const owningApp = appsByName.get(feature.app);
+    if (owningApp === void 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["features", index, "app"],
+        message: `app "${feature.app}" is not declared in apps[]`
+      });
+      return;
+    }
+    if (owningApp.type !== "api" && (feature.routes.length > 0 || feature.dbTables.length > 0)) {
+      context.addIssue({
+        code: "custom",
+        path: ["features", index],
+        message: "a non-api feature owns no HTTP routes and no DB tables \u2014 declare them on the api feature"
+      });
+    }
+  });
+});
+
+// ../ogygie-core/src/spec.schema.ts
+var DeferredBehaviorSchema = z3.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({
+  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)")
+});
+var SECTIONS_SPEC_OBLIGATOIRES = [
+  "# @intent",
+  "# Comportements",
+  "# Contrats de donn\xE9es",
+  "# \xC9tats UI",
+  "# Non-objectifs",
+  "# Budget"
+];
+function splitInlineArrayElements(inner) {
+  const elements = [];
+  let current = "";
+  let openQuote = null;
+  for (const character of inner) {
+    if (openQuote === null && (character === '"' || character === "'")) {
+      openQuote = character;
+      current += character;
+    } else if (character === openQuote) {
+      openQuote = null;
+      current += character;
+    } else if (openQuote === null && character === ",") {
+      elements.push(current);
+      current = "";
+    } else {
+      current += character;
+    }
+  }
+  elements.push(current);
+  return { elements, unbalancedQuote: openQuote !== null };
+}
+function unquote(raw, location, problems) {
+  const trimmed = raw.trim();
+  const first = trimmed[0];
+  if (first === '"' || first === "'") {
+    if (trimmed.length < 2 || !trimmed.endsWith(first)) {
+      problems.push(`${location}: unbalanced quotes in ${JSON.stringify(trimmed)}`);
+      return null;
+    }
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function parseSpecFrontmatter(text) {
+  const value = {};
+  const problems = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const trimmed = (lines[index] ?? "").trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex === -1 || trimmed.startsWith('"') || trimmed.startsWith("'")) {
+      problems.push(
+        `unparseable line ${JSON.stringify(trimmed)}: expected \`key: value\` \u2014 a spilled array element outside any array? (scalars and arrays of scalars only, D13)`
+      );
+      continue;
+    }
+    const key = trimmed.slice(0, colonIndex).trim();
+    let rawValue = trimmed.slice(colonIndex + 1).trim();
+    if (rawValue.startsWith("[")) {
+      let closed = rawValue.endsWith("]");
+      while (!closed && index + 1 < lines.length) {
+        index += 1;
+        rawValue = `${rawValue} ${(lines[index] ?? "").trim()}`;
+        closed = rawValue.endsWith("]");
+      }
+      if (!closed) {
+        problems.push(
+          `key "${key}": array opened with "[" and never closed with "]" before the end of the frontmatter \u2014 a truncated array would be silently read as empty, hence refused (D13)`
+        );
+        continue;
+      }
+      const { elements, unbalancedQuote } = splitInlineArrayElements(
+        rawValue.slice(1, -1)
+      );
+      if (unbalancedQuote) {
+        problems.push(`key "${key}": unbalanced quotes inside the array`);
+        continue;
+      }
+      const parsedElements = [];
+      let broken = false;
+      for (const element of elements) {
+        if (element.trim() === "") continue;
+        const unquoted = unquote(element, `key "${key}"`, problems);
+        if (unquoted === null) broken = true;
+        else parsedElements.push(unquoted);
+      }
+      if (!broken) value[key] = parsedElements;
+    } else {
+      const unquoted = unquote(rawValue, `key "${key}"`, problems);
+      if (unquoted !== null) value[key] = unquoted;
+    }
+  }
+  return { value, problems };
+}
+
+// src/server/service.ts
+var SPECS_DIR = "specs";
+var TEMPLATE_PATH = "specs/_TEMPLATE.spec.md";
+var MANIFEST_PATH = "ogygie.manifest.json";
+var FRONTMATTER_BLOCK = /^---\n([\s\S]*?)\n---/;
+function splitSpecFile(content) {
+  const match = FRONTMATTER_BLOCK.exec(content);
+  if (match === null || match[1] === void 0) return null;
+  return { frontmatterText: match[1], body: content.slice(match[0].length) };
+}
+function presentSectionsOf(body) {
+  const searchable = `
+${body}`;
+  const present = [];
+  let cursor = 0;
+  for (const section of SECTIONS_SPEC_OBLIGATOIRES) {
+    const position = searchable.indexOf(`
+${section}`, cursor);
+    if (position === -1) continue;
+    present.push(section);
+    cursor = position + section.length;
+  }
+  return present;
+}
+function missingSectionsOf(body) {
+  const present = new Set(presentSectionsOf(body));
+  return SECTIONS_SPEC_OBLIGATOIRES.filter((section) => !present.has(section));
+}
+function quoteFrontmatterElement(value, specPath) {
+  if (value.includes("\n") || value.includes('"') && value.includes("'")) {
+    throwOgygieError(
+      {
+        code: "SPEC_FRONTMATTER_UNSERIALIZABLE",
+        message: "A frontmatter array element cannot be written in the restricted spec format.",
+        file: specPath,
+        cause: `element ${JSON.stringify(value)} contains a newline or both quote kinds`,
+        suggestedFix: "Rewrite the element without newlines and with at most one kind of quote character."
+      },
+      422
+    );
+  }
+  return value.includes('"') ? `'${value}'` : `"${value}"`;
+}
+function serializeSpecFrontmatter(frontmatter, specPath) {
+  const quote = (value) => quoteFrontmatterElement(value, specPath);
+  const lines = [
+    `id: ${frontmatter.id}`,
+    `status: ${frontmatter.status}`,
+    `depends_on: [${frontmatter.depends_on.join(", ")}]`,
+    `priority: ${frontmatter.priority}`,
+    `refs: [${frontmatter.refs.map(quote).join(", ")}]`
+  ];
+  if (frontmatter.deferred.length > 0) {
+    lines.push(`deferred: [${frontmatter.deferred.map(quote).join(", ")}]`);
+  }
+  return lines.join("\n");
+}
+function specPathOf(specId) {
+  return `${SPECS_DIR}/${specId}.spec.md`;
+}
+function frontmatterInvalidError(filePath, cause) {
+  return ogygieError({
+    code: "SPEC_FRONTMATTER_INVALID",
+    message: `Spec ${filePath} has an invalid frontmatter.`,
+    file: filePath,
+    cause,
+    suggestedFix: "Fix the frontmatter in your editor to match packages/ogygie-core/src/spec.schema.ts \u2014 the studio never repairs a spec silently."
+  });
+}
+function parseSpec(filePath, fileName, content) {
+  const split = splitSpecFile(content);
+  if (split === null) {
+    return {
+      ok: false,
+      error: frontmatterInvalidError(
+        filePath,
+        "file does not start with a --- ... --- frontmatter block"
+      )
+    };
+  }
+  const parsed = parseSpecFrontmatter(split.frontmatterText);
+  if (parsed.problems.length > 0) {
+    return { ok: false, error: frontmatterInvalidError(filePath, parsed.problems.join(" ; ")) };
+  }
+  const checked = SpecFrontmatterSchema.safeParse(parsed.value);
+  if (!checked.success) {
+    return {
+      ok: false,
+      error: frontmatterInvalidError(
+        filePath,
+        checked.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(" ; ")
+      )
+    };
+  }
+  const expectedId = fileName.replace(/\.spec\.md$/, "");
+  if (checked.data.id !== expectedId) {
+    return {
+      ok: false,
+      error: ogygieError({
+        code: "SPEC_ID_MISMATCH",
+        message: `Spec ${fileName} declares id "${checked.data.id}" \u2014 expected "${expectedId}".`,
+        file: filePath,
+        cause: `id=${checked.data.id} \u2260 filename ${expectedId}`,
+        suggestedFix: "Make the frontmatter id identical to the file name."
+      })
+    };
+  }
+  return { ok: true, spec: { frontmatter: checked.data, body: split.body } };
+}
+function toReadableSummary(filePath, spec) {
+  return {
+    id: spec.frontmatter.id,
+    status: spec.frontmatter.status,
+    priority: spec.frontmatter.priority,
+    depends_on: spec.frontmatter.depends_on,
+    filePath,
+    presentSections: presentSectionsOf(spec.body)
+  };
+}
+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();
+}
+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 parsed = parseSpec(filePath, fileName, content);
+    const id = fileName.replace(/\.spec\.md$/, "");
+    summaries.push(
+      parsed.ok ? toReadableSummary(filePath, parsed.spec) : { id, filePath, error: parsed.error }
+    );
+  }
+  return summaries;
+}
+async function readParsedSpec(deps, specId) {
+  const fileName = `${specId}.spec.md`;
+  const fileNames = await listSpecFileNames(deps);
+  if (!fileNames.includes(fileName)) {
+    throwOgygieError(
+      {
+        code: "SPEC_NOT_FOUND",
+        message: `No spec file exists for id "${specId}".`,
+        file: specPathOf(specId),
+        cause: `${fileName} absent from ${SPECS_DIR}/`,
+        suggestedFix: "Pick an id from GET /api/specs, or create the spec first."
+      },
+      404
+    );
+  }
+  const filePath = specPathOf(specId);
+  const content = await deps.storage.read(filePath);
+  const parsed = parseSpec(filePath, fileName, content);
+  if (!parsed.ok) {
+    throw new OgygieFailure(parsed.error, 422);
+  }
+  return parsed.spec;
+}
+async function getSpec(deps, specId) {
+  const spec = await readParsedSpec(deps, specId);
+  return {
+    frontmatter: spec.frontmatter,
+    body: spec.body,
+    presentSections: presentSectionsOf(spec.body)
+  };
+}
+async function saveSpec(deps, specId, input) {
+  const current = await readParsedSpec(deps, specId);
+  const filePath = specPathOf(specId);
+  if (input.frontmatter.id !== specId) {
+    throwOgygieError(
+      {
+        code: "SPEC_ID_MISMATCH",
+        message: `The submitted frontmatter declares id "${input.frontmatter.id}" \u2014 expected "${specId}".`,
+        file: filePath,
+        cause: `frontmatter.id=${input.frontmatter.id} \u2260 route param ${specId}`,
+        suggestedFix: "Keep the id identical to the file name \u2014 it is not editable."
+      },
+      422
+    );
+  }
+  const from = current.frontmatter.status;
+  const target = input.frontmatter.status;
+  if (target === "implemented" && from !== "implemented") {
+    throwOgygieError(
+      {
+        code: "STUDIO_TRANSITION_FORBIDDEN",
+        message: "Status `implemented` belongs to the implementation flow (manifest + CI), never to the studio UI.",
+        file: filePath,
+        cause: `attempted transition ${from} \u2192 implemented from the studio`,
+        suggestedFix: "Implement the feature, update the manifest to delivered, then flip the spec in the implementation commit."
+      },
+      409
+    );
+  }
+  const isValidation = from === "draft" && target === "validated";
+  if (from !== target && !isValidation) {
+    throwOgygieError(
+      {
+        code: "STUDIO_TRANSITION_FORBIDDEN",
+        message: "The studio only performs the draft \u2192 validated transition.",
+        file: filePath,
+        cause: `attempted transition ${from} \u2192 ${target} from the studio`,
+        suggestedFix: "Reopening or downgrading a spec happens in the implementation flow (spec amendment commit), not in the studio."
+      },
+      409
+    );
+  }
+  let body = input.body ?? current.body;
+  if (input.body !== void 0 && !body.startsWith("\n")) {
+    body = `
+${body}`;
+  }
+  if (isValidation) {
+    const missing = missingSectionsOf(body);
+    if (missing.length > 0) {
+      throwOgygieError(
+        {
+          code: "SPEC_SECTION_MISSING",
+          message: `Spec ${specId} cannot be validated: ${missing.length} mandatory section(s) missing.`,
+          file: filePath,
+          cause: `missing or out-of-order: ${missing.join(" ; ")}`,
+          suggestedFix: "Write the missing sections (in canonical order) before validating \u2014 a validated spec is an implementation contract.",
+          details: { missingSections: missing }
+        },
+        409
+      );
+    }
+  }
+  const serialized = serializeSpecFrontmatter(input.frontmatter, filePath);
+  const content = `---
+${serialized}
+---${body}`;
+  const message = isValidation ? `spec: validate ${specId}` : `spec: save ${specId}`;
+  await deps.storage.write(filePath, content, message);
+  return toReadableSummary(filePath, { frontmatter: input.frontmatter, body });
+}
+async function createSpec(deps, specId) {
+  const fileName = `${specId}.spec.md`;
+  const fileNames = await listSpecFileNames(deps);
+  if (fileNames.includes(fileName)) {
+    throwOgygieError(
+      {
+        code: "SPEC_ALREADY_EXISTS",
+        message: `A spec already exists for id "${specId}" \u2014 nothing was overwritten.`,
+        file: specPathOf(specId),
+        cause: `${fileName} already present in ${SPECS_DIR}/`,
+        suggestedFix: "Open the existing spec from the board, or pick another id."
+      },
+      409
+    );
+  }
+  let template;
+  try {
+    template = await deps.storage.read(TEMPLATE_PATH);
+  } catch {
+    return throwOgygieError({
+      code: "SPEC_TEMPLATE_NOT_FOUND",
+      message: "specs/_TEMPLATE.spec.md is missing \u2014 the studio creates specs from it.",
+      file: TEMPLATE_PATH,
+      cause: "template file unreadable",
+      suggestedFix: "Restore specs/_TEMPLATE.spec.md from the framework skeleton."
+    });
+  }
+  const content = template.replace(/^id: .*$/m, `id: ${specId}`);
+  const filePath = specPathOf(specId);
+  await deps.storage.write(filePath, content, `spec: create ${specId}`);
+  const parsed = parseSpec(filePath, fileName, content);
+  if (!parsed.ok) {
+    return throwOgygieError({
+      code: "SPEC_TEMPLATE_NOT_FOUND",
+      message: "specs/_TEMPLATE.spec.md does not produce a readable draft spec.",
+      file: TEMPLATE_PATH,
+      cause: parsed.error.cause,
+      suggestedFix: "Fix the template's frontmatter to match SpecFrontmatterSchema."
+    });
+  }
+  return toReadableSummary(filePath, parsed.spec);
+}
+async function getManifest(deps) {
+  const content = await deps.storage.read(MANIFEST_PATH);
+  let raw;
+  try {
+    raw = JSON.parse(content);
+  } catch (parseError) {
+    return throwOgygieError(
+      {
+        code: "MANIFEST_INVALID",
+        message: "ogygie.manifest.json is not valid JSON.",
+        file: MANIFEST_PATH,
+        cause: parseError instanceof Error ? parseError.message : "unparseable JSON",
+        suggestedFix: "Fix the manifest JSON \u2014 the studio only ever READS it."
+      },
+      422
+    );
+  }
+  const parsed = OgygieManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throwOgygieError(
+      {
+        code: "MANIFEST_INVALID",
+        message: "ogygie.manifest.json does not satisfy OgygieManifestSchema.",
+        file: MANIFEST_PATH,
+        cause: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(" ; "),
+        suggestedFix: "Fix the listed fields to match packages/ogygie-core/src/manifest.schema.ts."
+      },
+      422
+    );
+  }
+  return parsed.data;
+}
+
+// src/server/schemas.ts
+import { z as z4 } from "zod";
+var SpecStatusSchema = SpecFrontmatterSchema.shape.status;
+var ReadableSpecSummarySchema = z4.object({
+  id: FeatureNameSchema,
+  status: SpecStatusSchema,
+  priority: SpecFrontmatterSchema.shape.priority,
+  depends_on: z4.array(FeatureNameSchema),
+  filePath: z4.string(),
+  presentSections: z4.array(z4.string())
+});
+var UnreadableSpecSummarySchema = z4.object({
+  id: z4.string(),
+  filePath: z4.string(),
+  error: OgygieErrorSchema
+});
+var SpecSummarySchema = z4.union([
+  ReadableSpecSummarySchema,
+  UnreadableSpecSummarySchema
+]);
+var ListSpecsOutputSchema = z4.object({
+  specs: z4.array(SpecSummarySchema)
+});
+var SpecParamsSchema = z4.object({
+  specId: FeatureNameSchema
+});
+var GetSpecOutputSchema = z4.object({
+  frontmatter: SpecFrontmatterSchema,
+  /** Markdown body after the frontmatter block, byte-exact. */
+  body: z4.string(),
+  presentSections: z4.array(z4.string())
+});
+var UpdateSpecInputSchema = z4.object({
+  frontmatter: SpecFrontmatterSchema,
+  /** Omitted ⇒ the existing markdown body is preserved byte-exact. */
+  body: z4.string().max(2e5).optional()
+});
+var UpdateSpecOutputSchema = z4.object({
+  spec: ReadableSpecSummarySchema
+});
+var CreateSpecInputSchema = z4.object({
+  id: FeatureNameSchema.max(80)
+});
+var CreateSpecOutputSchema = z4.object({
+  spec: ReadableSpecSummarySchema
+});
+var GetManifestOutputSchema = z4.object({
+  manifest: OgygieManifestSchema
+});
+
+// src/server/routes.ts
+async function registerStudioRoutes(app, deps) {
+  const route = app.withTypeProvider();
+  route.route({
+    method: "GET",
+    url: "/api/specs",
+    schema: { response: { 200: ListSpecsOutputSchema } },
+    handler: async (_request, reply) => {
+      return reply.code(200).send({ specs: await listSpecSummaries(deps) });
+    }
+  });
+  route.route({
+    method: "GET",
+    url: "/api/specs/:specId",
+    schema: { params: SpecParamsSchema, response: { 200: GetSpecOutputSchema } },
+    handler: async (request, reply) => {
+      return reply.code(200).send(await getSpec(deps, request.params.specId));
+    }
+  });
+  route.route({
+    method: "PUT",
+    url: "/api/specs/:specId",
+    schema: {
+      params: SpecParamsSchema,
+      body: UpdateSpecInputSchema,
+      response: { 200: UpdateSpecOutputSchema }
+    },
+    handler: async (request, reply) => {
+      const spec = await saveSpec(deps, request.params.specId, request.body);
+      return reply.code(200).send({ spec });
+    }
+  });
+  route.route({
+    method: "POST",
+    url: "/api/specs",
+    schema: {
+      body: CreateSpecInputSchema,
+      response: { 201: CreateSpecOutputSchema }
+    },
+    handler: async (request, reply) => {
+      const spec = await createSpec(deps, request.body.id);
+      return reply.code(201).send({ spec });
+    }
+  });
+  route.route({
+    method: "GET",
+    url: "/api/manifest",
+    schema: { response: { 200: GetManifestOutputSchema } },
+    handler: async (_request, reply) => {
+      return reply.code(200).send({ manifest: await getManifest(deps) });
+    }
+  });
+}
+
+// src/server/app.ts
+async function createStudioApp(options) {
+  const app = Fastify({ logger: false });
+  app.setValidatorCompiler(validatorCompiler);
+  app.setSerializerCompiler(serializerCompiler);
+  app.setErrorHandler((error, _request, reply) => {
+    if (error instanceof OgygieFailure) {
+      return reply.status(error.httpStatus).send(error.error);
+    }
+    if (hasZodFastifySchemaValidationErrors(error)) {
+      return reply.status(400).send(
+        ogygieError({
+          code: "CONTRACT_VALIDATION_FAILED",
+          message: "The request does not satisfy the route's input contract.",
+          file: null,
+          cause: error.validation.map((issue) => `${issue.instancePath || "(root)"}: ${issue.message ?? "invalid"}`).join(" ; "),
+          suggestedFix: "Fix the listed fields to match the route's Zod input schema."
+        })
+      );
+    }
+    app.log.error(error);
+    return reply.status(500).send(
+      ogygieError({
+        code: "INTERNAL_ERROR",
+        message: "Unexpected studio error \u2014 details are in the server logs only.",
+        file: null,
+        cause: "unhandled exception",
+        suggestedFix: "Relaunch `pnpm ogygie studio`; record a FAILURES.md entry if it recurs."
+      })
+    );
+  });
+  await registerStudioRoutes(app, options);
+  if (options.uiDistDir !== void 0) {
+    const fastifyStatic = (await import("@fastify/static")).default;
+    await app.register(fastifyStatic, { root: options.uiDistDir });
+    app.setNotFoundHandler((request, reply) => {
+      if (request.method === "GET" && !request.url.startsWith("/api/")) {
+        return reply.sendFile("index.html");
+      }
+      return reply.status(404).send(
+        ogygieError({
+          code: "ROUTE_NOT_FOUND",
+          message: "No studio route matches this request.",
+          file: null,
+          cause: `${request.method} ${request.url}`,
+          suggestedFix: "Use the routes documented in specs/ogygie-studio.spec.md."
+        })
+      );
+    });
+  }
+  await app.ready();
+  return app;
+}
+
+// src/server/start.ts
+var PACKAGE_DIR = fileURLToPath(new URL("../..", import.meta.url));
+async function buildUiIfMissing(uiDistDir) {
+  if (existsSync(join2(uiDistDir, "index.html"))) return;
+  console.log("ogygie studio \u2014 UI absente, construction unique\u2026");
+  try {
+    const { build } = await import("vite");
+    await build({
+      configFile: join2(PACKAGE_DIR, "vite.config.ts"),
+      logLevel: "warn"
+    });
+  } catch (thrown) {
+    throwOgygieError({
+      code: "OGYGIE_STUDIO_UI_MISSING",
+      message: "The studio UI is missing and cannot be built here.",
+      file: "packages/ogygie-studio/dist-ui/index.html",
+      cause: thrown instanceof Error ? `dist-ui absent and vite unavailable: ${thrown.message}` : "dist-ui absent and vite unavailable",
+      suggestedFix: "A published @ogygie/studio ships its UI already built \u2014 reinstall the package. Inside the framework workspace, run `pnpm --filter @ogygie/studio build`."
+    });
+  }
+}
+function openInBrowser(url) {
+  const opener = process.platform === "darwin" ? "open" : "xdg-open";
+  try {
+    spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+  } catch {
+  }
+}
+async function startStudio(options) {
+  const port = options.port ?? 4001;
+  const uiDistDir = join2(PACKAGE_DIR, "dist-ui");
+  await buildUiIfMissing(uiDistDir);
+  const app = await createStudioApp({
+    storage: createLocalSpecStorage(options.repoRoot),
+    uiDistDir
+  });
+  await app.listen({ port, host: "127.0.0.1" });
+  const url = `http://127.0.0.1:${port}`;
+  console.log(`ogygie studio \u2014 ${url} (repo: ${options.repoRoot})`);
+  if (options.openBrowser !== false) openInBrowser(url);
+  return app;
+}
+export {
+  startStudio
+};