@metaobjectsdev/cli 0.11.6 → 0.12.0

package/src/index.ts

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { log } from "./lib/log.js";
 import { cliVersion } from "./lib/version.js";
+import { resolveFormat, isValidFormat, VALID_FORMATS } from "./lib/format.js";
 export { defineConfig } from "@metaobjectsdev/codegen-ts";
 export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
@@ -14,6 +15,7 @@ USAGE:
 COMMANDS:
   init                  Scaffold metaobjects/ + .metaobjects/ in the current repo
   init --refresh-docs   Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
+  agent-docs            Scaffold only the agent-context (.metaobjects/ + .claude/skills/) — canonical redirect target for all language ports
   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)
@@ -25,6 +27,7 @@ COMMANDS:
 
 GLOBAL OPTIONS:
   --cwd <path>, -C <path>   Run as if launched from <path> (default: current directory)
+  --format <toon|json|text> Output format (default: toon on non-TTY, text on TTY)
 
 GEN FLAGS:
   --dry-run             Compute and print, don't write
@@ -74,10 +77,104 @@ Other commands (ingest, mcp, serve, install-hooks, audit, capture, promote)
 ship in later sub-projects. See https://metaobjects.com for docs.
 `;
 
+/** Focused per-subcommand usage slices shown by `<cmd> --help`. */
+const COMMAND_HELP: Record<string, string> = {
+  gen: `meta gen — codegen TS targets from metaobjects/ entities
+
+USAGE:
+  meta gen [<entity>...] [flags]
+
+FLAGS:
+  --dry-run             Compute and print, don't write
+  <entity> [<entity>]   Positional filter on entity names
+  --help, -h            Print this help
+
+NOTE: outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts
+`,
+  verify: `meta verify — drift gate (templates / DB schema / codegen)
+
+USAGE:
+  meta verify [flags]
+
+FLAGS:
+  --templates           Template/prompt {{field}}↔payload drift (default when bare)
+  --codegen             Codegen drift — regenerate to temp dir and diff committed output
+                        Needs metaobjects.config.ts; exit 2 if absent.
+  --db <url>            Schema drift — live DB URL enables the schema-drift gate.
+                        Supports: file:, libsql:, postgres:, postgresql:
+  --prompts <dir>       Directory of provider-resolved template text (default: prompts)
+  --dialect sqlite|postgres   Optional override (auto-detected from --db URL scheme)
+  --allow <csv>         Accepted for parity with 'migrate'; does NOT affect the drift gate
+  --skip-schema         Skip the schema-drift gate even when --db is present
+  --help, -h            Print this help
+`,
+  export: `meta export — flatten loaded metadata to one canonical JSON artifact
+
+USAGE:
+  meta export [flags]
+
+FLAGS:
+  --out <file>          Write output to a file (default: stdout)
+  --help, -h            Print this help
+`,
+  docs: `meta docs — generate neutral metadata documentation (entity + template pages)
+
+USAGE:
+  meta docs [<metadata>] [flags]
+
+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>)
+  --help, -h            Print this help
+`,
+  init: `meta init — scaffold metaobjects/ + .metaobjects/ in the current repo
+
+USAGE:
+  meta init [flags]
+
+FLAGS:
+  --refresh-docs        Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
+  --force               Overwrite existing files
+  --quiet               Suppress output
+  --print-only          Print what would be written, don't write
+  --d1                  Include D1 (Cloudflare) migration config
+  --no-wire-root        Skip wiring root metaobjects.config.ts
+  --help, -h            Print this help
+`,
+  "agent-docs": `meta agent-docs — scaffold the agent-context (.metaobjects/ always-on files + .claude/skills/)
+
+USAGE:
+  meta agent-docs [--server <lang>]... [--client <fw>]... [--out <dir>] [flags]
+
+FLAGS:
+  --server <lang>       Server language (repeatable; e.g. csharp, kotlin, python, node)
+  --client <fw>         Client framework (repeatable; e.g. react, vue)
+  --out <dir>           Output directory (default: current directory)
+  --no-skills           Skip .claude/skills/ scaffold
+  --no-wire-root        Skip wiring root CLAUDE.md @import
+  --help, -h            Print this help
+
+NOTE: This is the canonical scaffolder for all language ports. Non-Node CLIs redirect here.
+`,
+  "prompt-snapshot": `meta prompt-snapshot — snapshot rendered template.* output
+
+USAGE:
+  meta prompt-snapshot [flags]
+
+FLAGS:
+  --check               Compare against committed snapshots; exit 1 on drift (CI gate)
+  --prompts <dir>       Directory of provider-resolved template text (default: prompts)
+  --help, -h            Print this help
+`,
+};
+
 export async function run(argv: string[]): Promise<number> {
-  // Extract the global --cwd / -C flag (anywhere in argv). A relative path
-  // resolves against the real process.cwd(). Absent → process.cwd().
+  // Extract the global --cwd / -C and --format flags (anywhere in argv).
+  // A relative --cwd path resolves against the real process.cwd().
+  // Absent --cwd → process.cwd(). Absent --format → TTY-aware default.
   let cwd = process.cwd();
+  let formatFlag: string | undefined;
   const cleaned: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
@@ -100,12 +197,63 @@ export async function run(argv: string[]): Promise<number> {
       cwd = resolve(process.cwd(), val);
       continue;
     }
+    if (a === "--format") {
+      formatFlag = argv[i + 1];
+      i++; // consume the value
+      continue;
+    }
+    if (a.startsWith("--format=")) {
+      formatFlag = a.slice("--format=".length);
+      continue;
+    }
     cleaned.push(a);
   }
 
+  // An explicit but unrecognized --format is a usage error (exit 2) — mirrors the
+  // --cwd missing-value handling above. Absent --format keeps the TTY-aware default.
+  if (formatFlag !== undefined && !isValidFormat(formatFlag)) {
+    log.error(`--format must be one of: ${VALID_FORMATS.join(", ")} (got '${formatFlag}')`);
+    return 2;
+  }
+  const fmt = resolveFormat(formatFlag, process.stdout.isTTY ?? false);
+
   const [cmd, ...rest] = cleaned;
+
+  // Intercept per-subcommand --help / -h before dispatching (mirrors migrate's own pattern).
+  if (cmd !== undefined && cmd !== "--help" && cmd !== "-h" && cmd !== "--version" && cmd !== "-v") {
+    if (rest.includes("--help") || rest.includes("-h")) {
+      const helpText = COMMAND_HELP[cmd];
+      if (helpText !== undefined) {
+        log.info(helpText);
+        return 0;
+      }
+      // Unknown command with --help → fall through to the default: branch below.
+    }
+  }
+
   switch (cmd) {
-    case undefined:
+    case undefined: {
+      // Content-first no-args view: concise status + next-step help[] rather than
+      // dumping the full manual (full manual is still available via `meta --help`).
+      const metaobjectsExists = await import("node:fs/promises")
+        .then(({ stat }) => stat(resolve(cwd, "metaobjects")).then(() => true).catch(() => false));
+      const statusLine = metaobjectsExists
+        ? `meta — MetaObjects CLI (v${VERSION})  ·  metaobjects/ found`
+        : `meta — MetaObjects CLI (v${VERSION})  ·  no metaobjects/ here`;
+      const nextSteps = metaobjectsExists
+        ? [
+            "  meta gen              Run codegen",
+            "  meta verify           Check for drift",
+            "  meta migrate          Diff vs DB and emit SQL",
+            "  meta --help           Full command reference",
+          ]
+        : [
+            "  meta init             Scaffold metaobjects/ in this directory",
+            "  meta --help           Full command reference",
+          ];
+      log.info(`${statusLine}\n\n${nextSteps.join("\n")}\n`);
+      return 0;
+    }
     case "--help":
     case "-h":
       log.info(HELP_TEXT);
@@ -118,9 +266,38 @@ export async function run(argv: string[]): Promise<number> {
       const { initCommand } = await import("./commands/init.js");
       return initCommand(rest, cwd);
     }
+    case "agent-docs": {
+      const { parseAgentDocsArgs } = await import("./lib/args.js");
+      const { init } = await import("./commands/init.js");
+      let flags;
+      try {
+        flags = parseAgentDocsArgs(rest);
+      } catch (err) {
+        log.error((err as Error).message);
+        return 2;
+      }
+      const targetCwd = flags.out !== undefined ? resolve(cwd, flags.out) : cwd;
+      try {
+        const result = await init({
+          cwd: targetCwd,
+          servers: flags.servers,
+          clients: flags.clients,
+          noSkills: flags.noSkills,
+          wireRoot: flags.wireRoot,
+          docsOnly: true,
+        });
+        log.info(`Scaffolded the MetaObjects agent context (${result.created.length} files): .metaobjects/AGENTS.md + .claude/skills/metaobjects-*.`);
+        for (const w of result.warnings) log.info(`  ${w}`);
+        log.info("Re-run agent-docs to update; --no-wire-root to skip the root CLAUDE.md @import.");
+        return 0;
+      } catch (err) {
+        log.error((err as Error).message);
+        return 1;
+      }
+    }
     case "gen": {
       const { genCommand } = await import("./commands/gen.js");
-      return genCommand(rest, cwd);
+      return genCommand(rest, cwd, fmt);
     }
     case "export": {
       const { exportCommand } = await import("./commands/export.js");
@@ -140,11 +317,10 @@ export async function run(argv: string[]): Promise<number> {
     }
     case "migrate": {
       const { migrateCommand } = await import("./commands/migrate.js");
-      return migrateCommand(rest, cwd);
+      return migrateCommand(rest, cwd, undefined, fmt);
     }
     default:
-      log.error(`Unknown command: ${cmd}`);
-      log.info(HELP_TEXT);
+      log.error(`Unknown command: ${cmd}. Run \`meta --help\` for available commands.`);
       return 2;
   }
 }

package/src/lib/args.ts

@@ -49,6 +49,40 @@ export function parseInitArgs(argv: string[]): InitFlags {
   };
 }
 
+// ---------------------------------------------------------------------------
+// agent-docs flags — docs-only scaffold (always-on + skills), no metaobjects/ project
+// ---------------------------------------------------------------------------
+
+export interface AgentDocsFlags {
+  servers: string[];
+  clients: string[];
+  out: string | undefined;
+  noSkills: boolean;
+  wireRoot: boolean;
+}
+
+export function parseAgentDocsArgs(argv: string[]): AgentDocsFlags {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      server: { type: "string", multiple: true },
+      client: { type: "string", multiple: true },
+      out: { type: "string" },
+      "no-skills": { type: "boolean", default: false },
+      "no-wire-root": { type: "boolean", default: false },
+    },
+    strict: true,
+    allowPositionals: false,
+  });
+  return {
+    servers: (values.server as string[] | undefined) ?? [],
+    clients: (values.client as string[] | undefined) ?? [],
+    out: values.out as string | undefined,
+    noSkills: !!values["no-skills"],
+    wireRoot: !values["no-wire-root"],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // gen flags — minimal: metaobjects.config.ts holds outDir/dialect/dbImport/extStyle
 // ---------------------------------------------------------------------------

package/src/lib/format.ts

@@ -0,0 +1,23 @@
+import { encode } from "@toon-format/toon";
+
+export type OutputFormat = "toon" | "json" | "text";
+
+const VALID = new Set<OutputFormat>(["toon", "json", "text"]);
+
+/** Valid --format values, for usage messages. */
+export const VALID_FORMATS: readonly OutputFormat[] = ["toon", "json", "text"];
+
+/** True iff `flag` is one of the recognized output formats. */
+export function isValidFormat(flag: string): flag is OutputFormat {
+  return VALID.has(flag as OutputFormat);
+}
+
+export function resolveFormat(flag: string | undefined, isTTY: boolean): OutputFormat {
+  if (flag && VALID.has(flag as OutputFormat)) return flag as OutputFormat;
+  // TTY-aware default: humans at a terminal get text; pipes/agents get TOON.
+  return isTTY ? "text" : "toon";
+}
+
+export function toonEncode(value: unknown): string {
+  return encode(value);
+}

package/src/lib/kysely.ts

@@ -1,5 +1,6 @@
 import { Kysely } from "kysely";
 import { BunSqliteDialect, isBun } from "./bun-sqlite-dialect.js";
+import { installCommand } from "./pm-detect.js";
 
 export type Dialect = "sqlite" | "postgres" | "d1";
 
@@ -80,8 +81,9 @@ export async function buildKyselyFromUrl(
         const mod = await import("@libsql/kysely-libsql");
         LibsqlDialect = mod.LibsqlDialect as unknown as LibsqlDialectCtor;
       } catch {
+        const cmd = await installCommand("@libsql/kysely-libsql", process.cwd());
         throw new Error(
-          `dialect 'sqlite' requires '@libsql/kysely-libsql'; install it: 'bun add @libsql/kysely-libsql'`,
+          `dialect 'sqlite' requires '@libsql/kysely-libsql'; install it: '${cmd}'`,
         );
       }
       sqliteDialect = new LibsqlDialect({ url });
@@ -108,8 +110,9 @@ export async function buildKyselyFromUrl(
     pg = await import("pg") as unknown as PgPoolModule;
     ({ PostgresDialect } = await import("kysely"));
   } catch {
+    const cmd = await installCommand("pg", process.cwd());
     throw new Error(
-      `dialect 'postgres' requires 'pg'; install it: 'bun add pg'`,
+      `dialect 'postgres' requires 'pg'; install it: '${cmd}'`,
     );
   }
   const PoolCtor = pg.Pool ?? pg.default?.Pool;

package/src/lib/output-json.ts

@@ -0,0 +1,10 @@
+import type { GenResultShape, MigrateResultShape } from "./output.js";
+import { genResultToData, migrateResultToData } from "./output.js";
+
+export function formatGenResultJson(result: GenResultShape): string {
+  return JSON.stringify(genResultToData(result), null, 2);
+}
+
+export function formatMigrateResultJson(result: MigrateResultShape): string {
+  return JSON.stringify(migrateResultToData(result), null, 2);
+}

package/src/lib/output.ts

@@ -4,6 +4,7 @@
 // (NEW MERGED CONFLICT UNCHANGED REFUSED) otherwise. Per SP5 §5.1.
 
 import type { Dialect } from "./kysely.js";
+import { toonEncode } from "./format.js";
 
 export interface FormatOptions {
   isTTY: boolean;
@@ -112,6 +113,10 @@ export interface MigrateResultShape {
   ambiguous: AmbiguousEntry[];
   writtenPaths: string[];
   dryRun: boolean;
+  /** Names of migrations actually applied to the DB this run (empty unless --apply ran and succeeded). */
+  applied?: string[];
+  /** True when --apply was attempted but failed (exit 1). */
+  applyFailed?: boolean;
 }
 
 export function formatMigrateResult(result: MigrateResultShape, _opts: FormatOptions): string {
@@ -156,3 +161,98 @@ export function formatMigrateResult(result: MigrateResultShape, _opts: FormatOpt
 
   return lines.join("\n");
 }
+
+// ---------------------------------------------------------------------------
+// gen TOON/JSON formatters (axi)
+// ---------------------------------------------------------------------------
+
+export function genResultToData(result: GenResultShape): {
+  gen: { file: string; status: GenFileStatus }[]; summary: string; help: string[];
+} {
+  const counts = result.files.reduce<Record<GenFileStatus, number>>(
+    (a, f) => ((a[f.status] = (a[f.status] ?? 0) + 1), a),
+    { new: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0 },
+  );
+  const parts: string[] = [];
+  if (counts.new) parts.push(`${counts.new} written`);
+  if (counts.merged) parts.push(`${counts.merged} merged`);
+  if (counts.conflict) parts.push(`${counts.conflict} conflict`);
+  if (counts.unchanged) parts.push(`${counts.unchanged} unchanged`);
+  if (counts.refused) parts.push(`${counts.refused} refused`);
+  const summary = result.files.length === 0
+    ? `no entities to generate in ${result.outDir}`
+    : parts.join(", ");
+  const help = result.files.length === 0
+    ? ["author entities under metaobjects/ then re-run `meta gen`"]
+    : ["typecheck the generated code with `npx tsc`", "run schema with `meta migrate --db <url> --slug <name>`"];
+  return { gen: result.files.map((f) => ({ file: f.path, status: f.status })), summary, help };
+}
+
+export function formatGenResultToon(result: GenResultShape): string {
+  return toonEncode(genResultToData(result));
+}
+
+// ---------------------------------------------------------------------------
+// migrate TOON/JSON formatters (axi)
+// ---------------------------------------------------------------------------
+
+export function migrateResultToData(result: MigrateResultShape): {
+  changes: { kind: string; count: number }[];
+  written: string[];
+  summary: string;
+  help: string[];
+} {
+  const changeEntries = Object.entries(result.changeCounts).filter(([, v]) => v > 0);
+  const changes = changeEntries.map(([kind, count]) => ({ kind, count }));
+
+  const isBlocked = result.blocked.length > 0 || result.ambiguous.length > 0;
+  const changeSummary = changeEntries.map(([k, v]) => `${v} ${k}`).join(", ");
+  const applied = result.applied ?? [];
+  const applyFailed = result.applyFailed ?? false;
+  // `--apply` also applies previously-written-but-unapplied ledger files, so
+  // `applied` can be non-empty even when there is no fresh metadata diff.
+  const hasChanges = changeEntries.length > 0 || isBlocked;
+  const prefix = changeSummary.length > 0 ? `${changeSummary}; ` : "";
+
+  // Summary + help reflect what ACTUALLY happened, computed from the real signals
+  // (dry-run, blocked/ambiguous, files written, files applied) rather than
+  // short-circuiting on the presence of a fresh diff: a dry-run wrote nothing, a
+  // generate-only run wrote files but applied nothing, and `--apply` can apply a
+  // pending ledger file even with no new diff. The `--rollback` hint appears only
+  // when something was actually applied.
+  let summary: string;
+  let help: string[];
+  if (isBlocked) {
+    summary = `${changeSummary}; not applied`;
+    help = [
+      ...result.blocked.map((b) => `re-run with --allow ${b.allowFlag} to apply: ${b.description}`),
+      ...result.ambiguous.map((a) => `re-run with --on-ambiguous to resolve: ${a.hint}`),
+    ];
+  } else if (result.dryRun) {
+    summary = hasChanges ? `${changeSummary}; preview only (nothing written)` : "no schema changes";
+    help = hasChanges
+      ? ["re-run without --dry-run to write the migration"]
+      : ["metadata and schema are in sync — nothing to do"];
+  } else if (applyFailed) {
+    summary = `${prefix}apply failed`;
+    help = ["resolve the apply error above, then re-run `meta migrate --apply`"];
+  } else if (applied.length > 0) {
+    summary = `${prefix}applied ${applied.length} migration(s)`;
+    help = ["roll back with `meta migrate --rollback <target>`"];
+  } else if (result.writtenPaths.length > 0) {
+    summary = `${prefix}wrote ${result.writtenPaths.length} migration file(s)`;
+    help = ["apply with `meta migrate --db <url> --apply`"];
+  } else if (!hasChanges) {
+    summary = "no schema changes";
+    help = ["metadata and schema are in sync — nothing to do"];
+  } else {
+    summary = `${changeSummary}; not written`;
+    help = ["re-run with --slug <name> to write the migration"];
+  }
+
+  return { changes, written: result.writtenPaths, summary, help };
+}
+
+export function formatMigrateResultToon(result: MigrateResultShape): string {
+  return toonEncode(migrateResultToData(result));
+}

package/src/lib/pm-detect.ts

@@ -0,0 +1,53 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+/**
+ * Detect the package manager in use by looking for the lockfile closest to
+ * `dir`. Walks up to the root. Returns "bun" as the default when no lockfile
+ * is found.
+ */
+export async function detectPackageManager(dir: string): Promise<PackageManager> {
+  // Check in the given dir first, then parent dirs up to the FS root.
+  let current = dir;
+  while (true) {
+    const candidates: [string, PackageManager][] = [
+      [join(current, "package-lock.json"), "npm"],
+      [join(current, "pnpm-lock.yaml"), "pnpm"],
+      [join(current, "yarn.lock"), "yarn"],
+      [join(current, "bun.lockb"), "bun"],
+      [join(current, "bun.lock"), "bun"],
+    ];
+    for (const [path, pm] of candidates) {
+      try {
+        await access(path);
+        return pm;
+      } catch {
+        // not found, try next
+      }
+    }
+    const parent = join(current, "..");
+    if (parent === current) break; // reached root
+    current = parent;
+  }
+  // Default: bun (most common for this toolchain)
+  return "bun";
+}
+
+/**
+ * Returns the install command for a missing package, using the detected PM.
+ */
+export async function installCommand(pkg: string, dir: string): Promise<string> {
+  const pm = await detectPackageManager(dir);
+  switch (pm) {
+    case "npm":
+      return `npm install ${pkg}`;
+    case "pnpm":
+      return `pnpm add ${pkg}`;
+    case "yarn":
+      return `yarn add ${pkg}`;
+    case "bun":
+      return `bun add ${pkg}`;
+  }
+}