feat(cli): meta prompt-snapshot write mode + dispatcher [FR-004]

dmealing · claude · dmealing · commit a187cbeb978a · 2026-05-23T20:04:50.000-04:00
Adds `meta prompt-snapshot` command: for each template.* node with a
committed payload.json fixture, renders the @textRef text and writes the
byte-exact output to .metaobjects/snapshots/&lt;name&gt;/output.snap. Skips
templates without a payload, exits 1 on render errors, exits 2 on missing
metaobjects/. Help text and help-output snapshot updated.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/server/typescript/packages/cli/src/commands/prompt-snapshot.ts b/server/typescript/packages/cli/src/commands/prompt-snapshot.ts
@@ -0,0 +1,104 @@
+// `meta prompt-snapshot` — deterministic rendered-prompt goldens (FR-004 #4).
+//
+// For each template.* node with a committed fixture payload, render its @textRef
+// text against that payload (same engine, provider, and @format escaping prod
+// uses) and snapshot the byte-exact output under .metaobjects/snapshots/<name>/.
+// Write mode (default) overwrites output.snap; --check (a later task) diffs and
+// fails on drift. Closes the gap the template's own git history misses: a shared
+// partial or payload-shape change that silently alters the rendered prompt.
+
+import { join } from "node:path";
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { parsePromptSnapshotArgs } from "../lib/args.js";
+import { log } from "../lib/log.js";
+import { FileProvider } from "../lib/file-provider.js";
+import { snapshotPaths } from "../lib/snapshot.js";
+import { loadMemory } from "@metaobjectsdev/sdk";
+import { TYPE_TEMPLATE, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
+import { render, type RenderFormat } from "@metaobjectsdev/render";
+
+const DEFAULT_PROMPTS_DIR = "prompts";
+
+export async function promptSnapshotCommand(args: string[], cwd: string): Promise<number> {
+  let flags;
+  try {
+    flags = parsePromptSnapshotArgs(args);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  let root;
+  try {
+    root = await loadMemory(cwd);
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (msg.includes("ENOENT") || msg.includes("no such") || msg.includes("cannot read")) {
+      log.error(`no metaobjects/ found in ${cwd}; run 'meta init' to scaffold`);
+      return 2;
+    }
+    log.error(`failed to load metadata: ${msg}`);
+    return 1;
+  }
+
+  const promptsDir = join(cwd, flags.prompts ?? DEFAULT_PROMPTS_DIR);
+  const provider = new FileProvider(promptsDir);
+
+  const templates = root.ownChildren().filter((c) => c.type === TYPE_TEMPLATE);
+  if (templates.length === 0) {
+    log.info("meta prompt-snapshot — no template.* nodes found; nothing to snapshot.");
+    return 0;
+  }
+
+  let errorCount = 0;
+  let wrote = 0;
+  let skipped = 0;
+
+  for (const tmpl of templates) {
+    const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+    // Absent/typeless required attrs are a loader-schema concern, not ours.
+    if (typeof textRef !== "string") continue;
+
+    const { dir, payloadPath, snapPath } = snapshotPaths(cwd, tmpl.name);
+    if (!existsSync(payloadPath)) {
+      log.info(`[${tmpl.name}] skipped — no payload at ${payloadPath}`);
+      skipped++;
+      continue;
+    }
+
+    let payload: unknown;
+    try {
+      payload = JSON.parse(readFileSync(payloadPath, "utf8"));
+    } catch (err) {
+      log.error(`[${tmpl.name}] invalid payload.json: ${(err as Error).message}`);
+      errorCount++;
+      continue;
+    }
+
+    const fmtAttr = tmpl.ownAttr(TEMPLATE_ATTR_FORMAT);
+    const format = typeof fmtAttr === "string" ? (fmtAttr as RenderFormat) : undefined;
+
+    let rendered: string;
+    try {
+      rendered = render({ ref: textRef, payload, provider, ...(format ? { format } : {}) });
+    } catch (err) {
+      log.error(`[${tmpl.name}] render failed: ${(err as Error).message}`);
+      errorCount++;
+      continue;
+    }
+
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(snapPath, rendered, "utf8");
+    log.info(`[${tmpl.name}] wrote ${snapPath}`);
+    wrote++;
+  }
+
+  if (errorCount > 0) {
+    log.error(`meta prompt-snapshot — ${errorCount} error(s); ${wrote} snapshot(s) written.`);
+    return 1;
+  }
+  log.info(
+    `meta prompt-snapshot — ${wrote} snapshot(s) written${skipped > 0 ? `, ${skipped} skipped` : ""}.`,
+  );
+  return 0;
+}
diff --git a/server/typescript/packages/cli/src/index.ts b/server/typescript/packages/cli/src/index.ts
@@ -40,6 +40,7 @@ COMMANDS:
   gen [<entity>...]     Codegen TS targets from metaobjects/ entities
   export                Flatten loaded metadata to one canonical JSON artifact
   verify                Check template.* text against its payload (drift gate)
+  prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version
   --help, -h            Print this help
@@ -58,6 +59,10 @@ EXPORT FLAGS:
 VERIFY FLAGS:
   --prompts <dir>       Directory of provider-resolved template text (default: prompts)
 
+PROMPT-SNAPSHOT FLAGS:
+  --check               Compare against committed snapshots; exit 1 on drift (CI gate)
+  --prompts <dir>       Directory of provider-resolved template text (default: prompts)
+
 MIGRATE FLAGS:
   --db <url>            DB connection URL (required, or set DATABASE_URL or config)
                         Supports: file:, libsql:, postgres:, postgresql:
@@ -129,6 +134,10 @@ export async function run(argv: string[]): Promise<number> {
       const { verifyCommand } = await import("./commands/verify.js");
       return verifyCommand(rest, cwd);
     }
+    case "prompt-snapshot": {
+      const { promptSnapshotCommand } = await import("./commands/prompt-snapshot.js");
+      return promptSnapshotCommand(rest, cwd);
+    }
     case "migrate": {
       const { migrateCommand } = await import("./commands/migrate.js");
       return migrateCommand(rest, cwd);
diff --git a/server/typescript/packages/cli/test/__snapshots__/cli.test.ts.snap b/server/typescript/packages/cli/test/__snapshots__/cli.test.ts.snap
@@ -12,6 +12,7 @@ COMMANDS:
   gen [<entity>...]     Codegen TS targets from metaobjects/ entities
   export                Flatten loaded metadata to one canonical JSON artifact
   verify                Check template.* text against its payload (drift gate)
+  prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version
   --help, -h            Print this help
@@ -30,6 +31,10 @@ EXPORT FLAGS:
 VERIFY FLAGS:
   --prompts <dir>       Directory of provider-resolved template text (default: prompts)
 
+PROMPT-SNAPSHOT FLAGS:
+  --check               Compare against committed snapshots; exit 1 on drift (CI gate)
+  --prompts <dir>       Directory of provider-resolved template text (default: prompts)
+
 MIGRATE FLAGS:
   --db <url>            DB connection URL (required, or set DATABASE_URL or config)
                         Supports: file:, libsql:, postgres:, postgresql:
diff --git a/server/typescript/packages/cli/test/integration/prompt-snapshot.test.ts b/server/typescript/packages/cli/test/integration/prompt-snapshot.test.ts
@@ -0,0 +1,119 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "../../src/index.js";
+
+// A view-object payload (Brief) + two prompts. `greeting` includes a shared
+// partial (the load-bearing case: editing the partial drifts the rendered
+// prompt while greeting.mustache itself is unchanged).
+const META = {
+  "metadata.root": {
+    package: "acme::ai",
+    children: [
+      { "object.value": { name: "Brief", children: [{ "field.string": { name: "name" } }] } },
+      {
+        "template.prompt": {
+          name: "greeting",
+          "@payloadRef": "Brief",
+          "@textRef": "prompt/greeting",
+          "@format": "text",
+        },
+      },
+      {
+        "template.prompt": {
+          name: "farewell",
+          "@payloadRef": "Brief",
+          "@textRef": "prompt/farewell",
+          "@format": "text",
+        },
+      },
+    ],
+  },
+};
+
+function scaffold(): string {
+  const tmp = mkdtempSync(join(tmpdir(), "meta-snap-"));
+  mkdirSync(join(tmp, "metaobjects"), { recursive: true });
+  writeFileSync(join(tmp, "metaobjects", "meta.ai.json"), JSON.stringify(META), "utf8");
+  mkdirSync(join(tmp, "prompts", "shared"), { recursive: true });
+  mkdirSync(join(tmp, "prompts", "prompt"), { recursive: true });
+  writeFileSync(join(tmp, "prompts", "shared", "preamble.mustache"), "You are a helpful guide.\n", "utf8");
+  writeFileSync(join(tmp, "prompts", "prompt", "greeting.mustache"), "{{> shared/preamble}}Hi {{name}}.", "utf8");
+  writeFileSync(join(tmp, "prompts", "prompt", "farewell.mustache"), "Bye {{name}}.", "utf8");
+  return tmp;
+}
+
+function writePayload(tmp: string, templateName: string, payload: unknown): void {
+  const dir = join(tmp, ".metaobjects", "snapshots", templateName);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "payload.json"), JSON.stringify(payload), "utf8");
+}
+
+const snapPath = (tmp: string, name: string) =>
+  join(tmp, ".metaobjects", "snapshots", name, "output.snap");
+
+let out: string[];
+let err: string[];
+let origLog: typeof console.log;
+let origErr: typeof console.error;
+
+beforeEach(() => {
+  out = [];
+  err = [];
+  origLog = console.log;
+  origErr = console.error;
+  console.log = (...a: unknown[]) => { out.push(a.map(String).join(" ")); };
+  console.error = (...a: unknown[]) => { err.push(a.map(String).join(" ")); };
+});
+afterEach(() => {
+  console.log = origLog;
+  console.error = origErr;
+});
+
+describe("meta prompt-snapshot (write mode)", () => {
+  test("writes output.snap for a template that has a payload", async () => {
+    const tmp = scaffold();
+    writePayload(tmp, "greeting", { name: "Ada" });
+    try {
+      expect(await run(["prompt-snapshot", "--cwd", tmp])).toBe(0);
+      expect(existsSync(snapPath(tmp, "greeting"))).toBe(true);
+      expect(readFileSync(snapPath(tmp, "greeting"), "utf8")).toBe("You are a helpful guide.\nHi Ada.");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test("skips a template that has no payload (no golden written)", async () => {
+    const tmp = scaffold();
+    writePayload(tmp, "greeting", { name: "Ada" }); // farewell intentionally has none
+    try {
+      expect(await run(["prompt-snapshot", "--cwd", tmp])).toBe(0);
+      expect(existsSync(snapPath(tmp, "farewell"))).toBe(false);
+      expect([...out, ...err].join("\n")).toContain("farewell");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test("exit 2 when metaobjects/ is missing", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "meta-snap-none-"));
+    try {
+      expect(await run(["prompt-snapshot", "--cwd", tmp])).toBe(2);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test("exit 1 when a template's @textRef does not resolve", async () => {
+    const tmp = scaffold();
+    writePayload(tmp, "farewell", { name: "Ada" }); // not skipped — it has a payload
+    rmSync(join(tmp, "prompts", "prompt", "farewell.mustache"), { force: true }); // @textRef now unresolvable
+    try {
+      expect(await run(["prompt-snapshot", "--cwd", tmp])).toBe(1);
+      expect([...out, ...err].join("\n")).toContain("farewell");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
