@metaobjectsdev/cli 0.9.0-rc.1 → 0.10.0

package/src/commands/docs.ts

@@ -0,0 +1,438 @@
+// `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 { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
+import { loadMemory, DEFAULT_METADATA_DIR } from "@metaobjectsdev/sdk";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  makeRenderContext,
+  buildPkMap,
+  buildRelationMap,
+  resolveDocsConfig,
+  apiLabel,
+} from "@metaobjectsdev/codegen-ts";
+import type {
+  GenContext,
+  EmittedFile,
+  ResolvedDocsConfig,
+  DocsSurface,
+} from "@metaobjectsdev/codegen-ts";
+import { docsFile, apiDocsFile } from "@metaobjectsdev/codegen-ts/generators";
+import { composeRegistry, coreProviders, renderCoreMetamodelDocs } from "@metaobjectsdev/metadata";
+
+type DocsLayout = "flat" | "package";
+
+interface DocsFlags {
+  /** Project root holding `metaobjects/` (the metadata to document). */
+  metadata: string;
+  /** Output directory for the rendered pages. */
+  out: string;
+  /** Page-placement layout. `flat` (default) writes `<Name>.md` at the out
+   *  root; `package` folds pages under package-path subdirs (collision-proof
+   *  for multi-package models with repeated short names). */
+  layout: DocsLayout;
+  /** Optional override for the project root used to resolve adopter
+   *  `templates/` overrides. Defaults to the metadata root. */
+  templates?: string;
+  /** Which doc surfaces to emit, when overridden on the CLI. `--model` ⇒
+   *  ["model"], `--api` ⇒ ["api"], both ⇒ ["model","api"]. Unset ⇒ defer to the
+   *  resolved `docs:` config (default both). */
+  surfaces?: DocsSurface[];
+  /** Optional base URL override for cross-surface links (resolveDocsConfig). */
+  baseUrl?: string;
+  /** Whether `--out` was explicitly passed (so the resolver knows to override
+   *  the config's `docs.outDir` rather than fall back to the parse default). */
+  outProvided: boolean;
+  /** Whether `--layout` was explicitly passed (same override semantics). */
+  layoutProvided: boolean;
+  /** FR-033 S3 — document the METAMODEL ITSELF (the built-in type/subtype/attr
+   *  vocabulary) instead of a user's entities. Needs NO metadata + NO config. */
+  metamodel: boolean;
+}
+
+function parseLayout(v: string | undefined, flag: string): DocsLayout {
+  if (v === undefined) throw new Error(`${flag} requires flat|package`);
+  if (v !== "flat" && v !== "package") {
+    throw new Error(`${flag} must be "flat" or "package" (got "${v}")`);
+  }
+  return v;
+}
+
+function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
+  let metadata: string | undefined;
+  let out: string | undefined;
+  let templates: string | undefined;
+  let layout: DocsLayout | undefined;
+  let baseUrl: string | undefined;
+  let wantModel = false;
+  let wantApi = false;
+  let wantMetamodel = false;
+  let outProvided = false;
+  let layoutProvided = false;
+  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;
+      outProvided = true;
+    } else if (a.startsWith("--out=")) {
+      out = a.slice("--out=".length);
+      outProvided = true;
+    } else if (a === "--layout") {
+      layout = parseLayout(argv[++i], a);
+      layoutProvided = true;
+    } else if (a.startsWith("--layout=")) {
+      layout = parseLayout(a.slice("--layout=".length), "--layout");
+      layoutProvided = true;
+    } else if (a === "--model") {
+      wantModel = true;
+    } else if (a === "--api") {
+      wantApi = true;
+    } else if (a === "--metamodel") {
+      wantMetamodel = true;
+    } else if (a === "--base-url") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} requires a URL argument`);
+      baseUrl = v;
+    } else if (a.startsWith("--base-url=")) {
+      baseUrl = a.slice("--base-url=".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}`);
+    }
+  }
+  // --model and/or --api narrow the surfaces; both flags (or neither) leave the
+  // surfaces unset so the resolved `docs:` config decides (default both).
+  const surfaces: DocsSurface[] = [];
+  if (wantModel) surfaces.push("model");
+  if (wantApi) surfaces.push("api");
+  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. In --metamodel
+    // mode the renderer writes under <out>/metamodel/, default ./docs/metamodel.
+    out: out ?? (wantMetamodel ? "./docs/metamodel" : "./docs"),
+    // Default flat preserves today's single-package output (+ existing goldens).
+    layout: layout ?? "flat",
+    metamodel: wantMetamodel,
+    outProvided,
+    layoutProvided,
+    ...(surfaces.length > 0 ? { surfaces } : {}),
+    ...(baseUrl !== undefined ? { baseUrl } : {}),
+    ...(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;
+  }
+
+  // FR-033 S3 — `--metamodel`: document the BUILT-IN metamodel (type/subtype/
+  // attr vocabulary) from the strict registry. Unlike --model/--api this needs
+  // NEITHER a user's metadata NOR a config — there is nothing to load. It writes
+  // the renderer's files under <out>/metamodel/ (default ./docs/metamodel).
+  if (flags.metamodel) {
+    return metamodelDocsCommand(cwd, flags.out);
+  }
+
+  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;
+
+  // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
+  // providers (e.g. a project's custom field/object subtypes). Unlike `gen`,
+  // docs does NOT require a config — the Tier-2 "metadata alone" promise must
+  // hold for config-less projects. If the config is absent or invalid, fall
+  // back to defaults; the loader still surfaces a stable unknown-subtype error
+  // if the metadata genuinely uses an unregistered type.
+  let loadedConfig: Awaited<ReturnType<typeof loadMetaobjectsConfig>> | undefined;
+  let configProviders: NonNullable<Awaited<ReturnType<typeof loadMetaobjectsConfig>>["providers"]> | undefined;
+  // hasConfig gates the api surface: api docs describe the GENERATED REST
+  // surface, which only exists when there is a (loadable) gen config. A config
+  // that EXISTS but fails to load degrades to model-only with a warning.
+  const hasConfig = existsSync(join(metaRoot, "metaobjects.config.ts"));
+  // The config lives alongside metaobjects/ at the metadata root (metaRoot);
+  // projectRoot only diverges when --templates overrides the template lookup.
+  // Only attempt the load when the file is actually present: absence is the
+  // expected config-less case (stay silent), but a config that EXISTS yet fails
+  // to load is surfaced as a warning rather than silently degrading to
+  // provider-less docs — otherwise a custom-type project would later fail with a
+  // cryptic unknown-subtype error instead of the real config error.
+  if (hasConfig) {
+    try {
+      loadedConfig = await loadMetaobjectsConfig(metaRoot);
+      configProviders = loadedConfig.providers;
+    } catch (err) {
+      log.warn(
+        `docs: metaobjects.config.ts failed to load (${(err as Error).message}); ` +
+          `generating docs without its providers`,
+      );
+      loadedConfig = undefined;
+      configProviders = undefined;
+    }
+  }
+
+  // Merge the config `docs:` block with CLI overrides over documented defaults.
+  // CLI --out/--layout only override when explicitly passed; surfaces/baseUrl
+  // override whenever present. The resolver supplies defaults (outDir ./docs,
+  // layout = fallback, surfaces = both) so config-less + flag-less runs are
+  // unchanged.
+  const cliOverrides: Partial<ResolvedDocsConfig> = {
+    ...(flags.outProvided ? { outDir: flags.out } : {}),
+    ...(flags.layoutProvided ? { layout: flags.layout } : {}),
+    ...(flags.surfaces ? { surfaces: flags.surfaces } : {}),
+    ...(flags.baseUrl !== undefined ? { baseUrl: flags.baseUrl } : {}),
+  };
+  // Layout fallback chain: --layout (override, gated above) → docs.layout block →
+  // the project's top-level outputLayout → flat. So docs default to the SAME page
+  // placement as codegen when neither the docs block nor the CLI sets it.
+  const docsCfg = resolveDocsConfig(
+    loadedConfig?.docs,
+    cliOverrides,
+    loadedConfig?.outputLayout ?? "flat",
+  );
+  const outDir = resolvePath(metaRoot, docsCfg.outDir);
+
+  // Load metadata standalone — same loader path as migrate/gen. Threads any
+  // consumer providers from the config so custom types resolve.
+  let root;
+  try {
+    root = await loadMemory(metaRoot, {
+      ...(configProviders !== undefined ? { providers: configProviders } : {}),
+    });
+  } 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",
+      outputLayout: docsCfg.layout,
+      // api-docs reads this to decide whether to document the opt-in Hono CRUD
+      // surface. Aggregate it from the generator set exactly as the gen runner
+      // does (a generator opts in via emitsHonoRoutes), so `meta docs` auto-detects
+      // routesFileHono() rather than relying on a field users don't normally set.
+      includeHonoRoutes:
+        loadedConfig?.includeHonoRoutes ??
+        (loadedConfig?.generators?.some(
+          (g) => typeof g !== "string" && g.emitsHonoRoutes === true,
+        ) ??
+          false),
+    } as never,
+    renderContext,
+    projectRoot,
+    warn: (msg) => log.warn(`docs: ${msg}`),
+  };
+
+  const emit: EmittedFile[] = [];
+  let modelFiles: EmittedFile[] = [];
+
+  // The declared api surfaces, each tagged with its human label (apiLabel maps
+  // the language key → label; never hardcode labels). The model page links one
+  // reference per declared surface — across ALL ports, not just the surfaces
+  // THIS command emits — so a polyglot model page points at every port's docs.
+  const labeled = docsCfg.apiSurfaces.map((s) => ({ ...s, label: apiLabel(s.lang) }));
+
+  // The api surface only materializes with a loadable gen config (there is
+  // nothing generated to document otherwise), so gate api emit + cross-linking
+  // on that. When false, the model surface emits its historical standalone form.
+  const apiSelected = docsCfg.surfaces.includes("api") && loadedConfig !== undefined;
+
+  // MODEL surface — the neutral metadata pages (<Entity>.md / <Template>.md +
+  // README.md). Keep the render-error handling tight around docsFile() only.
+  if (docsCfg.surfaces.includes("model")) {
+    // When api is selected, link EVERY declared surface from the model page (so a
+    // polyglot model page references each port's api docs). `labeled` already
+    // carries {label, subDir, baseUrl?} (docsFile ignores the extra `lang`), so
+    // pass it straight through. Otherwise no api refs.
+    const modelOpts = apiSelected ? { apiSurfaces: labeled } : {};
+    try {
+      modelFiles = await docsFile(modelOpts).generate(ctx);
+    } catch (err) {
+      const msg = (err as Error).message;
+      // Duplicate output path (silent-overwrite backstop): the generator already
+      // names both colliding FQNs + the path and starts with "docs:". Surface it
+      // verbatim as a clean non-zero exit (no double prefix, no stack trace).
+      if (msg.startsWith("docs: duplicate output path")) {
+        log.error(msg);
+        return 1;
+      }
+      // 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;
+    }
+    emit.push(...modelFiles);
+  }
+
+  // API surface — the SDK reference for the GENERATED REST surface, side by side
+  // under each surface's subDir. THIS command only OWNS the surfaces it can
+  // generate — i.e. its own port (lang "ts"). Surfaces owned by other ports are
+  // linked (above) but produced by running that port's docs command; we just log
+  // a pointer. Only meaningful with a loadable gen config, so skip when absent.
+  let apiFiles: EmittedFile[] = [];
+  if (docsCfg.surfaces.includes("api")) {
+    if (loadedConfig !== undefined) {
+      try {
+        // Emit every surface THIS port owns (loop so it generalizes beyond the
+        // single ts surface owned today).
+        for (const s of labeled.filter((s) => s.lang === "ts")) {
+          apiFiles.push(
+            ...(await apiDocsFile({
+              subDir: s.subDir,
+              modelSurface: docsCfg.surfaces.includes("model"),
+            }).generate(ctx)),
+          );
+        }
+      } catch (err) {
+        const msg = (err as Error).message;
+        if (msg.startsWith("docs: duplicate output path")) {
+          log.error(msg);
+          return 1;
+        }
+        log.error(`docs: ${msg}`);
+        return 1;
+      }
+      emit.push(...apiFiles);
+      // Surfaces owned by other ports: link only, with a pointer to where they
+      // get produced.
+      for (const s of labeled.filter((s) => s.lang !== "ts")) {
+        log.info(
+          `meta docs: api surface '${s.lang}' (${s.subDir}) is produced by that port's docs command — run it to populate those pages.`,
+        );
+      }
+    } else if (hasConfig) {
+      // Config present but failed to load — already warned above; don't claim an
+      // api surface we couldn't build.
+      log.info("meta docs: api surface skipped — metaobjects.config.ts failed to load.");
+    } else {
+      log.info("meta docs: api surface skipped — no metaobjects.config.ts (nothing generated to document).");
+    }
+  }
+
+  try {
+    await mkdir(outDir, { recursive: true });
+    for (const f of emit) {
+      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 overview/index page (README.md) plus one page
+  // per entity and one per template.output. The entity count is the matched
+  // object count; the remaining non-overview model pages are template pages.
+  const entityCount = root.objects().filter(ctx.matches).length;
+  const modelOverview = modelFiles.filter((f) => f.path === "README.md").length;
+  const modelTemplates = modelFiles.length > 0
+    ? modelFiles.length - entityCount - modelOverview
+    : 0;
+  const modelSummary = docsCfg.surfaces.includes("model")
+    ? `${modelOverview} overview + ${entityCount} entity page(s) + ${modelTemplates} template page(s)`
+    : "model surface skipped";
+  const apiSummary = apiFiles.length > 0
+    ? `${apiFiles.length} api page(s)`
+    : "no api pages";
+  log.info(`meta docs — wrote ${modelSummary}; ${apiSummary} → ${outDir}`);
+  return 0;
+}
+
+/**
+ * FR-033 S3 — emit the metamodel reference docs (INDEX.md + per-type pages +
+ * providers.md) from the BUILT-IN strict registry. No metadata, no config:
+ * `composeRegistry(coreProviders)` IS the source. Files land under
+ * `<out>` (which defaults to `./docs/metamodel`), preserving the renderer's
+ * `types/<family>.md` subtree.
+ */
+async function metamodelDocsCommand(cwd: string, out: string): Promise<number> {
+  const outDir = resolvePath(cwd, out);
+  let docs: Map<string, string>;
+  try {
+    docs = renderCoreMetamodelDocs(composeRegistry(coreProviders));
+  } catch (err) {
+    log.error(`docs: failed to render metamodel docs: ${(err as Error).message}`);
+    return 1;
+  }
+  try {
+    await mkdir(outDir, { recursive: true });
+    for (const [rel, content] of docs) {
+      const path = resolvePath(outDir, rel);
+      await mkdir(resolvePath(path, ".."), { recursive: true });
+      await writeFile(path, content, "utf8");
+    }
+  } catch (err) {
+    log.error(`docs: failed to write metamodel pages: ${(err as Error).message}`);
+    return 1;
+  }
+  log.info(`meta docs --metamodel — wrote ${docs.size} page(s) → ${outDir}`);
+  return 0;
+}

package/src/commands/gen.ts

@@ -5,8 +5,9 @@ import { resolveGenConfig } from "../lib/config.js";
 import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
 import { formatGenResult, type GenFileEntry, type GenFileStatus } from "../lib/output.js";
 import { log } from "../lib/log.js";
+import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { loadMemory, DEFAULT_METADATA_DIR } from "@metaobjectsdev/sdk";
-import { runGen } from "@metaobjectsdev/codegen-ts";
+import { runGen, listGenerators } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
 
 function mapStatus(s: WriteStatus): GenFileStatus {
@@ -26,6 +27,15 @@ export async function genCommand(args: string[], cwd: string): Promise<number> {
   try { flags = parseGenArgs(args); }
   catch (err) { log.error((err as Error).message); return 2; }
 
+  // ADR-0021 D3 — `meta gen --list`: print the stable-name generator registry
+  // and exit 0 WITHOUT running codegen (no config/metadata required).
+  if (flags.list) {
+    return listGeneratorsCommand();
+  }
+
+  // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
+  warnIfAgentContextStale(cwd);
+
   const projectRoot = cwd;
   const cliConfig = resolveGenConfig(flags);
 
@@ -112,3 +122,36 @@ export async function genCommand(args: string[], cwd: string): Promise<number> {
   const hasFailure = files.some((f) => f.status === "conflict" || f.status === "refused");
   return hasFailure ? 1 : 0;
 }
+
+/**
+ * `meta gen --list` — print the stable-name generator registry (ADR-0021 D3).
+ *
+ * Generators are grouped by tier: the recommended native `meta gen` suite
+ * first, then neutral artifacts (owned by `meta docs` per D1). Each line is
+ * `<stable-name>  —  <description>` plus an options summary and, for neutral
+ * entries, a note pointing at the canonical door. Exits 0; no codegen runs.
+ */
+function listGeneratorsCommand(): number {
+  const entries = listGenerators();
+  const native = entries.filter((e) => e.tier === "native");
+  const neutral = entries.filter((e) => e.tier === "neutral");
+  const width = Math.max(...entries.map((e) => e.name.length));
+
+  const lines: string[] = [];
+  lines.push("Available generators (select by stable name):");
+  lines.push("");
+  lines.push("Native (recommended `meta gen` suite):");
+  for (const e of native) {
+    lines.push(`  ${e.name.padEnd(width)}  —  ${e.description}`);
+    if (e.options) lines.push(`  ${" ".repeat(width)}     options: ${e.options}`);
+  }
+  lines.push("");
+  lines.push("Neutral (owned by `meta docs`; not part of the native suite):");
+  for (const e of neutral) {
+    lines.push(`  ${e.name.padEnd(width)}  —  ${e.description}`);
+    if (e.note) lines.push(`  ${" ".repeat(width)}     ${e.note}`);
+  }
+
+  log.info(lines.join("\n"));
+  return 0;
+}