feat(cli): meta docs — standalone neutral metadata-docs command

dmealing · claude · dmealing · commit 5fc844bfdc62 · 2026-06-02T06:59:10.000-04:00
Add a standalone `meta docs &lt;metadata&gt; --out &lt;dir&gt;` command that emits
neutral metadata documentation (one `&lt;Entity&gt;.md` per entity + one
`&lt;Template&gt;.md` per template.output) from metadata ALONE — no gen config.

It loads metadata via the same loadMemory path as migrate/gen, builds the
same GenContext the codegen runner builds for the docsFile() generator, and
writes the generator's output — so the pages are byte-for-byte the same
(neutral) artifact the gen pipeline produces (DRY: no re-walk of
objects/templates).

Framework templates resolve from an on-disk templates/ dir (source/install
layout), matching the codegen docs path. In the compiled standalone binary
the framework templates are unresolvable (the bun virtual fs has no on-disk
templates/), so docs surfaces a clear actionable error rather than crashing
— same scope as gen's docs path (the binary targets schema ops).

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/server/typescript/packages/cli/src/commands/docs.ts b/server/typescript/packages/cli/src/commands/docs.ts
@@ -0,0 +1,168 @@
+// `meta docs <metadata> --out <dir>` — STANDALONE neutral metadata docs.
+//
+// Emits one neutral page per entity (`<Entity>.md`) and one per
+// `template.output` (`<Template>.md`) from metadata ALONE — no gen config, no
+// codegen pipeline. It is the Tier-2 delivery (like `migrate`): runnable from
+// the compiled `meta` binary.
+//
+// DRY: this command does NOT re-walk objects/templates. It builds the same
+// GenContext the codegen runner builds for the `docsFile()` generator and
+// calls that generator, then writes the returned files. The neutrality of the
+// output is therefore guaranteed — it is byte-for-byte the same generator the
+// `meta gen` pipeline runs (gated by the docs conformance fixture).
+
+import { resolve as resolvePath } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { log } from "../lib/log.js";
+import { loadMemory, DEFAULT_METADATA_DIR } from "@metaobjectsdev/sdk";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  makeRenderContext,
+  buildPkMap,
+  buildRelationMap,
+} from "@metaobjectsdev/codegen-ts";
+import type { GenContext } from "@metaobjectsdev/codegen-ts";
+import { docsFile } from "@metaobjectsdev/codegen-ts/generators";
+
+interface DocsFlags {
+  /** Project root holding `metaobjects/` (the metadata to document). */
+  metadata: string;
+  /** Output directory for the rendered pages. */
+  out: string;
+  /** Optional override for the project root used to resolve adopter
+   *  `templates/` overrides. Defaults to the metadata root. */
+  templates?: string;
+}
+
+function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
+  let metadata: string | undefined;
+  let out: string | undefined;
+  let templates: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--out" || a === "-o") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} requires a directory argument`);
+      out = v;
+    } else if (a.startsWith("--out=")) {
+      out = a.slice("--out=".length);
+    } else if (a === "--templates") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} requires a directory argument`);
+      templates = v;
+    } else if (a.startsWith("--templates=")) {
+      templates = a.slice("--templates=".length);
+    } else if (a.startsWith("-")) {
+      throw new Error(`unknown flag: ${a}`);
+    } else if (metadata === undefined) {
+      metadata = a;
+    } else {
+      throw new Error(`unexpected argument: ${a}`);
+    }
+  }
+  return {
+    // `<metadata>` is the project root that contains metaobjects/; default cwd
+    // (mirrors how migrate/gen treat the working directory as the root).
+    metadata: metadata ?? cwd,
+    // Default out dir, resolved against the metadata root below.
+    out: out ?? "./docs",
+    ...(templates !== undefined ? { templates } : {}),
+  };
+}
+
+export async function docsCommand(args: string[], cwd: string): Promise<number> {
+  let flags: DocsFlags;
+  try {
+    flags = parseDocsArgs(args, cwd);
+  } catch (err) {
+    log.error(`docs: ${(err as Error).message}`);
+    return 2;
+  }
+
+  const metaRoot = resolvePath(cwd, flags.metadata);
+  // The project root used to resolve adopter `templates/` overrides; the
+  // framework defaults sit underneath via projectProvider's chain.
+  const projectRoot = flags.templates !== undefined
+    ? resolvePath(cwd, flags.templates)
+    : metaRoot;
+  const outDir = resolvePath(metaRoot, flags.out);
+
+  // Load metadata standalone — same loader path as migrate/gen, NO gen config.
+  let root;
+  try {
+    root = await loadMemory(metaRoot);
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (!existsSync(join(metaRoot, DEFAULT_METADATA_DIR))) {
+      log.error(`docs: no metaobjects/ found in ${metaRoot}; run 'meta init' to scaffold`);
+    } else {
+      log.error(`docs: failed to load metadata: ${msg}`);
+    }
+    return 2;
+  }
+
+  // Build the same GenContext the codegen runner builds for docsFile(). The
+  // dialect only affects column-type hints on the entity page; "sqlite" is the
+  // neutral default (migrate's offline path uses the same fallback chain).
+  const renderContext = makeRenderContext({
+    dialect: "sqlite",
+    loadedRoot: root,
+    outDir,
+    dbImport: "",
+    pkMap: buildPkMap(root),
+    relationMap: buildRelationMap(root),
+  });
+  const ctx: GenContext = {
+    entities: root.objects(),
+    loadedRoot: root,
+    matches: () => true,
+    config: { outDir, extStyle: "none", dbImport: "", dialect: "sqlite" } as never,
+    renderContext,
+    projectRoot,
+    warn: (msg) => log.warn(`docs: ${msg}`),
+  };
+
+  let files;
+  try {
+    files = await docsFile().generate(ctx);
+  } catch (err) {
+    const msg = (err as Error).message;
+    // The framework templates resolve from disk; inside the compiled `meta`
+    // binary they live on a virtual fs the provider cannot read. Surface that
+    // as an actionable message rather than a cryptic render failure.
+    if (/entity-page|template-page|failed rendering|ENOENT|not found/i.test(msg)) {
+      log.error(
+        `docs: failed to render — templates not found. ` +
+        `Run 'meta docs' from an installed package layout (with on-disk ` +
+        `templates/), not the standalone binary, OR drop your own ` +
+        `templates/docs/entity-page.md.mustache + template-page.md.mustache. (${msg})`,
+      );
+    } else {
+      log.error(`docs: ${msg}`);
+    }
+    return 1;
+  }
+
+  try {
+    await mkdir(outDir, { recursive: true });
+    for (const f of files) {
+      const path = resolvePath(outDir, f.path);
+      await mkdir(resolvePath(path, ".."), { recursive: true });
+      await writeFile(path, f.content, "utf8");
+    }
+  } catch (err) {
+    log.error(`docs: failed to write pages: ${(err as Error).message}`);
+    return 1;
+  }
+
+  // Summary: docsFile() emits one page per entity first, then one per
+  // template.output. The entity count is the matched object count; the rest
+  // are template pages.
+  const entityCount = root.objects().filter(ctx.matches).length;
+  const templateCount = files.length - entityCount;
+  log.info(
+    `meta docs — wrote ${entityCount} entity page(s) + ${templateCount} template page(s) → ${outDir}`,
+  );
+  return 0;
+}
diff --git a/server/typescript/packages/cli/src/index.ts b/server/typescript/packages/cli/src/index.ts
@@ -39,6 +39,7 @@ COMMANDS:
   init --refresh-docs   Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
   gen [<entity>...]     Codegen TS targets from metaobjects/ entities
   export                Flatten loaded metadata to one canonical JSON artifact
+  docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages)
   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
@@ -56,6 +57,11 @@ GEN FLAGS:
 EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
+DOCS FLAGS:
+  <metadata>            Project root holding metaobjects/ (default: current directory)
+  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+
 VERIFY FLAGS:
   --prompts <dir>       Directory of provider-resolved template text (default: prompts)
   --db <url>            Live DB URL — enables the schema-drift gate (exit 1 on drift).
@@ -140,6 +146,10 @@ export async function run(argv: string[]): Promise<number> {
       const { exportCommand } = await import("./commands/export.js");
       return exportCommand(rest, cwd);
     }
+    case "docs": {
+      const { docsCommand } = await import("./commands/docs.js");
+      return docsCommand(rest, cwd);
+    }
     case "verify": {
       const { verifyCommand } = await import("./commands/verify.js");
       return verifyCommand(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
@@ -11,6 +11,7 @@ COMMANDS:
   init --refresh-docs   Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
   gen [<entity>...]     Codegen TS targets from metaobjects/ entities
   export                Flatten loaded metadata to one canonical JSON artifact
+  docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages)
   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
@@ -28,6 +29,11 @@ GEN FLAGS:
 EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
+DOCS FLAGS:
+  <metadata>            Project root holding metaobjects/ (default: current directory)
+  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+
 VERIFY FLAGS:
   --prompts <dir>       Directory of provider-resolved template text (default: prompts)
   --db <url>            Live DB URL — enables the schema-drift gate (exit 1 on drift).
diff --git a/server/typescript/packages/cli/test/docs-command.test.ts b/server/typescript/packages/cli/test/docs-command.test.ts
@@ -0,0 +1,146 @@
+import { describe, test, expect, afterAll, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, rm, mkdir, writeFile, readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { docsCommand } from "../src/commands/docs.js";
+import { run } from "../src/index.js";
+
+// Metadata with ONE entity (object.value Welcome) + ONE template.output
+// (WelcomePage). Mirrors fixtures/conformance/template-doc-document so the
+// emitted pages exercise both the entity-page and the template-page paths.
+const META = {
+  "metadata.root": {
+    package: "acme::site",
+    children: [
+      {
+        "object.value": {
+          name: "Welcome",
+          children: [
+            { "field.string": { name: "name" } },
+            { "field.string": { name: "headline" } },
+          ],
+        },
+      },
+      {
+        "template.output": {
+          name: "WelcomePage",
+          "@kind": "document",
+          "@payloadRef": "Welcome",
+          "@textRef": "site/welcome",
+          "@format": "html",
+          "@maxChars": 5000,
+          "@requiredTags": ["section"],
+        },
+      },
+    ],
+  },
+};
+
+const dirs: string[] = [];
+
+/** Build a standalone project root holding metaobjects/ — NO gen config. */
+async function project(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "meta-docs-"));
+  dirs.push(root);
+  await mkdir(join(root, "metaobjects"), { recursive: true });
+  await writeFile(
+    join(root, "metaobjects", "meta.json"),
+    JSON.stringify(META),
+    "utf8",
+  );
+  return root;
+}
+
+afterAll(async () => {
+  for (const d of dirs) await rm(d, { recursive: true, force: true });
+});
+
+// Capture stdout so we can assert the summary line.
+let logged: string[];
+let origLog: typeof console.log;
+beforeEach(() => {
+  logged = [];
+  origLog = console.log;
+  console.log = (...args: unknown[]) => {
+    logged.push(args.map(String).join(" "));
+  };
+});
+afterEach(() => {
+  console.log = origLog;
+});
+
+describe("meta docs — standalone neutral metadata docs", () => {
+  test("emits an entity page AND a template page from metadata alone", async () => {
+    const root = await project();
+    const out = join(root, "out-docs");
+
+    // No gen config present anywhere — proves this is metadata-only.
+    expect(existsSync(join(root, "metaobjects.config.ts"))).toBe(false);
+    expect(existsSync(join(root, ".metaobjects", "config.json"))).toBe(false);
+
+    const code = await docsCommand([root, "--out", out], root);
+    expect(code).toBe(0);
+
+    const files = (await readdir(out)).sort();
+    expect(files).toContain("Welcome.md");
+    expect(files).toContain("WelcomePage.md");
+  });
+
+  test("entity + template pages are NEUTRAL (no codegen leakage)", async () => {
+    const root = await project();
+    const out = join(root, "out-neutral");
+    expect(await docsCommand([root, "--out", out], root)).toBe(0);
+
+    const entity = await readFile(join(out, "Welcome.md"), "utf8");
+    const template = await readFile(join(out, "WelcomePage.md"), "utf8");
+
+    // Entity page is the neutral metadata contract.
+    expect(entity).toContain("## Constraints");
+    // Template page declares its render contract.
+    expect(template).toContain("**Kind:**");
+
+    // Neutral: no language/toolchain leakage in either page.
+    for (const page of [entity, template]) {
+      expect(page).not.toContain("Zod");
+      expect(page).not.toContain(".ts");
+      expect(page).not.toContain("## Generated code");
+    }
+  });
+
+  test("prints a summary of pages written to --out", async () => {
+    const root = await project();
+    const out = join(root, "out-summary");
+    expect(await docsCommand([root, "--out", out], root)).toBe(0);
+
+    const summary = logged.join("\n");
+    // Mentions counts + destination.
+    expect(summary).toMatch(/1 entity/);
+    expect(summary).toMatch(/1 template/);
+    expect(summary).toContain(out);
+  });
+
+  test("exits non-zero with a clear message when metadata is missing", async () => {
+    const empty = await mkdtemp(join(tmpdir(), "meta-docs-empty-"));
+    dirs.push(empty);
+    const out = join(empty, "out");
+    const code = await docsCommand([empty, "--out", out], empty);
+    expect(code).not.toBe(0);
+  });
+
+  test("docs is registered in the top-level dispatcher", async () => {
+    const root = await project();
+    const out = join(root, "out-dispatch");
+    // run() dispatches the docs command (would return 2 'Unknown command'
+    // if it were not registered).
+    const code = await run(["docs", root, "--out", out]);
+    expect(code).toBe(0);
+    expect(existsSync(join(out, "Welcome.md"))).toBe(true);
+  });
+
+  test("--help lists docs", async () => {
+    expect(await run(["--help"])).toBe(0);
+    const help = logged.join("\n");
+    expect(help).toContain("docs");
+  });
+});
