@metaobjectsdev/cli 1.0.2 → 1.0.4-rc.1

package/src/index.ts

@@ -17,7 +17,7 @@ const VERSION = cliVersion();
  * human text. It is named ONCE and used by both the warning below and the help
  * text above, so the two cannot drift apart.
  */
-const FORMAT_AWARE_COMMANDS: readonly string[] = ["gen", "verify", "migrate", "types"];
+const FORMAT_AWARE_COMMANDS: readonly string[] = ["gen", "verify", "migrate", "types", "deps", "eject"];
 
 const HELP_TEXT = `meta — MetaObjects CLI (v${VERSION})
 
@@ -32,10 +32,13 @@ COMMANDS:
   gen [<entity>...]     Codegen TS targets from your declared metadata
   eject <generator>     Copy a reference generator into codegen/generators/ to own it (any time after init)
   eject --list          List every ejectable generator name, grouped by package
+  deps sync [<name>...] Resolve declared dependencies (path transport): sync the committed
+                        snapshot + sha256 lock (.metaobjects/deps/, .metaobjects/deps.lock.json)
+  deps list             One line per locked dependency: name, version, hash, node/package summary
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
   docs [<project-root>] --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
-  verify                Drift gate — subverbs: --templates / --db / --codegen / --docs (bare = --templates)
+  verify                Drift gate — subverbs: --templates / --db / --codegen / --docs / --deps (bare = --templates)
   upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
@@ -55,8 +58,14 @@ GLOBAL OPTIONS:
 
 GEN FLAGS:
   --dry-run             Compute and print, don't write
-  --list                Print the generator registry (name, tier, options) and exit —
-                        no config or metadata required
+  --list                Print the generator CATALOG (name, layer, tier, what it emits,
+                        what to install) and exit. Codegen is opt-in: nothing runs until
+                        you wire it, and this is where you choose. No config or metadata
+                        required — add --format json for the same catalog, machine-readable.
+  --probe               With --list: construct every catalog generator and dry-run it
+                        against YOUR model, reporting how many files each would emit.
+                        A count per generator beats any category label — and it
+                        cannot go stale, because it runs the generators. Needs a project.
   --baseline <default|adopt|fresh>
                         First-time-on-existing-file behavior. Default: refuse a file that
                         cannot be proved to be generated output. "adopt" records the files
@@ -94,6 +103,10 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
                         run would emit; never reports an extra file, because docs.outDir
                         holds hand-written documentation MetaObjects did not write.
                         Needs metaobjects.config.ts; exit 2 if absent.
+  --deps                Dependency drift — re-resolve each declared dependency and compare
+                        its installed artifact's hash against .metaobjects/deps.lock.json
+                        (the same check 'meta deps check' runs). Never part of the bare-verify
+                        default — it needs the publisher reachable, which CI may not have.
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:. Omit to skip.
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
@@ -108,6 +121,8 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
   --no-antipatterns     Suppress the advisory "you hand-rolled what MetaObjects can
                         model" pass (aggregate/currency/enum hints; warnings only)
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint
+                        (never a gate — this lint can't fail the build)
   --limit <n|all>       How many advisory lines TEXT output prints per section before
                         it truncates (default 20). Never applies to --format
                         toon/json, which carry every finding and every diagnostic.
@@ -147,8 +162,14 @@ USAGE:
 
 FLAGS:
   --dry-run             Compute and print, don't write
-  --list                Print the generator registry (name, tier, options) and exit —
-                        no config or metadata required
+  --list                Print the generator CATALOG (name, layer, tier, what it emits,
+                        what to install) and exit. Codegen is opt-in: nothing runs until
+                        you wire it, and this is where you choose. No config or metadata
+                        required — add --format json for the same catalog, machine-readable.
+  --probe               With --list: construct every catalog generator and dry-run it
+                        against YOUR model, reporting how many files each would emit.
+                        A count per generator beats any category label — and it cannot go
+                        stale, because it runs the generators. Needs a project.
   --baseline <default|adopt|fresh>
                         First-time-on-existing-file behavior. Default: refuse a file that
                         cannot be proved to be generated output. "adopt" records the files
@@ -174,23 +195,65 @@ limit on the machine-readable result.
 
 NOTE: outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts
 `,
-  eject: `meta eject — copy a reference generator into your repo so you own it
+  eject: `meta eject — copy reference generators into your repo so you own them
 
 USAGE:
-  meta eject <name>      Copy generator <name> into codegen/generators/<name>.ts
+  meta eject <name>...   Copy each generator into codegen/generators/<name>.ts
   meta eject --list      List every ejectable generator name, grouped by package
 
+Codegen is opt-in — \`meta init\` wires nothing — so this is the door every generator
+you run comes through. Take several at once: the install set is CONSOLIDATED, so
+\`meta eject form hooks grid\` prints one install line, not three. An unknown name
+refuses the whole call and copies nothing.
+
 FLAGS:
   --list                 List ejectable generators instead of copying one
   --force                Overwrite an already-ejected file (default: never clobber)
+  --format <toon|json|text>   Output format (global flag). The structured form carries
+                         each file's wire lines, the consolidated install set and the
+                         config keys the ejected generators read.
   --help, -h             Print this help
 
-\`meta init\` copies five generators (entity, queries, routes, barrel, names) into
-codegen/generators/ automatically (ADR-0034 scaffold-and-own). \`meta eject\` is
-the same operation for ANY generator — one you skipped at init time, a UI-tier
-generator like form/hooks/grid, or one a package gains later. It prints the
-import line to paste into metaobjects.config.ts, and it never overwrites a
-file you already own unless you pass --force.
+\`meta init\` copies NO generators — codegen is opt-in, and codegen/generators/
+starts empty on purpose. Everything you run comes through here (ADR-0034
+scaffold-and-own): the file is YOURS to edit, and \`meta gen\` runs your copy, not
+the package's. It prints the import line and the entry to add in
+metaobjects.config.ts, and never overwrites a file you already own without --force.
+
+Find names with \`meta gen --list\` — add --probe to see how many files each would
+emit for your model.
+`,
+  deps: `meta deps — sync a declared metadata dependency's committed snapshot
+
+USAGE:
+  meta deps sync [<name>...]   Resolve each declared dependency (path transport only in
+                                this release — npm/python refuse by name), validate its
+                                manifest + artifact, copy it into .metaobjects/deps/<name>/,
+                                and pin it in .metaobjects/deps.lock.json. Naming one or more
+                                <name>s syncs only those; bare 'sync' syncs everything
+                                declared. A dependency removed from config is PRUNED from
+                                the lock and its snapshot dir deleted, every run.
+  meta deps list                One line per locked dependency: name, version, hash8,
+                                node count, packages.
+  meta deps check                Re-resolve each declared dependency (path transport, same
+                                as sync steps 1-2) and compare its INSTALLED artifact's hash
+                                against .metaobjects/deps.lock.json. Read-only — never
+                                touches the lock or the snapshot. Exits 1 if any dependency
+                                has drifted or cannot be resolved (ERR_DEPENDENCY_UPSTREAM_DRIFT).
+
+FLAGS:
+  --dry-run              Plan and report; write nothing (sync only)
+  --format <toon|json|text>   Output format (global flag; default toon off-TTY)
+  --help, -h              Print this help
+
+Only the "path" transport resolves in this release — a "npm"/"python" dependency spec is
+valid config (reserved for a future toolchain) but 'meta deps sync' refuses it by name:
+"transport \`npm\` is not supported by this toolchain yet; use \`path\`".
+
+The lock is the ONLY thing 'meta deps sync' writes to besides the snapshot directory —
+sync never touches your own metadata files. 'meta deps check' compares the lock against
+what is installed right now (the same check 'meta verify --deps' runs); 'meta deps sync'
+only ever compares against what config DECLARES.
 `,
   verify: `meta verify — drift gate (templates / DB schema / codegen / migration replay)
 
@@ -210,6 +273,12 @@ FLAGS:
                         a namespace MetaObjects owns); the count of exempt pages is
                         reported either way, and a run where every page is ignored is
                         refused rather than reported clean.
+  --deps                Dependency drift — re-resolve each declared dependency exactly as
+                        'meta deps check' does and compare its installed artifact's hash
+                        against .metaobjects/deps.lock.json. Exits 1 if any dependency has
+                        drifted or cannot be resolved (ERR_DEPENDENCY_UPSTREAM_DRIFT). NEVER
+                        part of the bare-verify default — it needs the publisher reachable,
+                        which CI may not have.
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
@@ -237,6 +306,8 @@ FLAGS:
                         migrating a model onto a registered provider.
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint —
+                        never a gate; this lint can't fail the build
   --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
                         (default 20; per-section so the authoring lint can never push
                         the gate's own warnings off the end)
@@ -258,6 +329,13 @@ lint in its own section: names that are not addressable, prose slots holding one
 sentence twice, content written where no surface reads it. Warnings only — it can
 never fail the build. Opt out with --no-requirement-lint or META_NO_REQUIREMENT_LINT=1.
 The requirements GATE itself (dangling refs, link floor, levels) always runs.
+
+verify also prints an ADVISORY overlay authoring lint, in its own section: a
+top-level declaration redeclared in two or more files where more than one
+redeclaration lacks 'overlay: true' — today's default merge rule reuses it
+silently, but the same unflagged redeclaration silently becomes a NEW object
+the day the target is renamed or removed upstream. Warnings only — it can
+never fail the build. Opt out with --no-overlay-lint or META_NO_OVERLAY_LINT=1.
 `,
   export: `meta export — flatten loaded metadata to one canonical JSON artifact
 
@@ -528,7 +606,11 @@ export async function run(argv: string[]): Promise<number> {
     }
     case "eject": {
       const { ejectCommand } = await import("./commands/eject.js");
-      return ejectCommand(rest, cwd);
+      return ejectCommand(rest, cwd, fmt);
+    }
+    case "deps": {
+      const { depsCommand } = await import("./commands/deps.js");
+      return depsCommand(rest, cwd, fmt);
     }
     case "export": {
       const { exportCommand } = await import("./commands/export.js");

package/src/lib/advisory.ts

@@ -150,6 +150,19 @@ export function removedPropRows(findings: readonly RemovedPropFinding[]): Adviso
   }));
 }
 
+/** FR-043 §3.5 findings in the same row shape. */
+export function libraryPrefixRows(
+  findings: readonly { file: string; fqn: string; message: string }[],
+): AdvisoryFindingRow[] {
+  return findings.map((f) => ({
+    file: f.file,
+    line: 0,
+    rule: "library-prefix-unprovenanced",
+    construct: f.fqn,
+    message: f.message,
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // text output
 // ---------------------------------------------------------------------------

package/src/lib/agent-context-staleness.ts

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, type Manifest } from "@metaobjectsdev/sdk";
+// The agent-context subpath, not the root barrel: `@metaobjectsdev/sdk` exports TWO
+// types named `Manifest` — this one (the scaffolded agent context) via `export *`,
+// and FR-023's `metaobjects.pkg.json` explicitly. An explicit export shadows a
+// star one, so the root barrel now hands out the dependency manifest under this
+// name. `init.ts` already imports these from the subpath; this was the last site
+// reading them from the root.
+import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, type Manifest } from "@metaobjectsdev/sdk/agent-context";
 import { cliVersion } from "./version.js";
 import { log } from "./log.js";
 

package/src/lib/args.ts

@@ -107,6 +107,12 @@ export interface GenFlags {
   /** ADR-0021 D3 — print the stable-name generator registry and exit without
    *  running codegen. */
   list: boolean;
+  /**
+   * `--list` only: construct every catalog generator and dry-run it against THIS
+   * project's model, reporting a real file count per generator. Needs a project;
+   * plain `--list` deliberately does not (it describes the installed engine).
+   */
+  probe: boolean;
   /** Suppress the advisory anti-pattern (verify-as-teacher) pass. */
   noAntipatterns: boolean;
   /**
@@ -122,6 +128,7 @@ export const GEN_OPTIONS = {
   "dry-run": { type: "boolean", default: false },
   "baseline": { type: "string" },
   "list": { type: "boolean", default: false },
+  "probe": { type: "boolean", default: false },
   "no-antipatterns": { type: "boolean", default: false },
   "limit": { type: "string" },
 } as const;
@@ -149,6 +156,7 @@ export function parseGenArgs(argv: string[]): GenFlags {
     entities: positionals,
     baseline: (baselineRaw as "default" | "fresh" | "adopt" | undefined) ?? "default",
     list: !!values.list,
+    probe: !!values.probe,
     noAntipatterns: !!values["no-antipatterns"],
     // Throws on a bad value; the command layer reports it and exits 2, exactly as
     // it does for --baseline above.
@@ -296,7 +304,17 @@ export interface VerifyFlags {
    * read as that flag's opposite rather than as a replay depth.
    */
   replaySnapshot: boolean;
-  /** Whether ANY explicit subverb flag (--templates/--db/--codegen/--docs/--replay*) was passed. */
+  /**
+   * Dependency drift (Task 15, FR-023) — re-resolve each declared dependency and
+   * compare its installed artifact's hash against `.metaobjects/deps.lock.json`
+   * (the same comparison `meta deps check` runs). Deliberately NEVER part of the
+   * bare-verify default, unlike --templates: it needs the publisher reachable,
+   * which CI may not have. It is still counted in `anyExplicit`, same as
+   * --codegen/--docs, so a lone `verify --deps` does not ALSO run the template
+   * gate.
+   */
+  deps: boolean;
+  /** Whether ANY explicit subverb flag (--templates/--db/--codegen/--docs/--deps/--replay*) was passed. */
   anyExplicit: boolean;
   /** Suppress the advisory anti-pattern (verify-as-teacher) pass. */
   noAntipatterns: boolean;
@@ -308,6 +326,16 @@ export interface VerifyFlags {
    * the half that CAN fail a build switched on. Same shape as --no-antipatterns.
    */
   noRequirementLint: boolean;
+  /**
+   * Suppress the advisory overlay AUTHORING lint (FR-023 §11.1 item 4) — the
+   * finding that an unflagged cross-file redeclaration works today only
+   * because the parser's default merge rule reuses the existing node by
+   * (type, resolutionKey); it silently becomes a NEW object the day the
+   * target is renamed or removed upstream. Same shape as
+   * --no-requirement-lint: mutes the advisory half only, never a gate (this
+   * lint has no gate half at all — it can never fail the build).
+   */
+  noOverlayLint: boolean;
   /**
    * ADR-0023 strict-attr load opt-OUT (#96). `verify` is strict-by-default — an
    * undeclared/typo'd own `@attr` fails verify (ERR_UNKNOWN_ATTR). `--lax`
@@ -342,10 +370,12 @@ export const VERIFY_OPTIONS = {
   templates: { type: "boolean", default: false },
   codegen: { type: "boolean", default: false },
   docs: { type: "boolean", default: false },
+  deps: { type: "boolean", default: false },
   replay: { type: "boolean", default: false },
   "replay-snapshot": { type: "boolean", default: false },
   "no-antipatterns": { type: "boolean", default: false },
   "no-requirement-lint": { type: "boolean", default: false },
+  "no-overlay-lint": { type: "boolean", default: false },
   lax: { type: "boolean", default: false },
   "d1": { type: "string" },
   "remote": { type: "boolean", default: false },
@@ -397,15 +427,17 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
   const templates = !!values.templates;
   const codegen = !!values.codegen;
   const docs = !!values.docs;
+  const deps = !!values.deps;
   const replay = !!values.replay;
   const replaySnapshot = !!values["replay-snapshot"];
   // --db is itself an explicit subverb selector: passing a connection URL means
   // "run the schema-drift mode". So is `--dialect d1` (D1 has no --db connection
   // URL — see the `d1` field doc above). The replay flags are subverbs too, and
   // must be listed here or `meta verify --replay` would ALSO run the template gate
-  // as the bare-verify default.
+  // as the bare-verify default. --deps joins the same list for the same reason —
+  // it must NOT also be part of that default (see the VerifyFlags doc on `deps`).
   const anyExplicit =
-    templates || codegen || docs || values.db !== undefined || dialect === "d1" || replay || replaySnapshot;
+    templates || codegen || docs || deps || values.db !== undefined || dialect === "d1" || replay || replaySnapshot;
 
   return {
     prompts: values.prompts,
@@ -416,11 +448,13 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     templates,
     codegen,
     docs,
+    deps,
     replay,
     replaySnapshot,
     anyExplicit,
     noAntipatterns: !!values["no-antipatterns"],
     noRequirementLint: !!values["no-requirement-lint"],
+    noOverlayLint: !!values["no-overlay-lint"],
     lax: !!values.lax,
     d1: values.d1 as string | undefined,
     remote: !!values.remote,
@@ -576,8 +610,14 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
 // ---------------------------------------------------------------------------
 
 export interface EjectFlags {
-  /** The generator name to eject; undefined when only --list was given. */
-  name: string | undefined;
+  /**
+   * The generator names to eject, in the order given. Empty when only --list was given.
+   *
+   * MANY, not one: choosing a client tier means `form hooks grid`, and three separate
+   * invocations produce three separate install lines for the same package. The
+   * consolidated install set is the point of taking them together.
+   */
+  names: string[];
   list: boolean;
   /** Overwrite an already-ejected file; default false — eject never clobbers. */
   force: boolean;
@@ -597,13 +637,83 @@ export function parseEjectArgs(argv: string[]): EjectFlags {
     allowPositionals: true,
   });
 
-  if (positionals.length > 1) {
-    throw new Error(`meta eject takes at most one generator name; got: ${positionals.join(", ")}`);
+  // `Set.add` returns the SET, which is always truthy — so the tempting
+  // `positionals.filter((n) => !seen.add(n))` never reports anything.
+  const seen = new Set<string>();
+  const duplicates: string[] = [];
+  for (const n of positionals) {
+    if (seen.has(n)) duplicates.push(n);
+    else seen.add(n);
+  }
+  if (duplicates.length > 0) {
+    throw new Error(
+      `meta eject: repeated generator name(s): ${[...new Set(duplicates)].join(", ")}`,
+    );
   }
 
   return {
-    name: positionals[0],
+    names: positionals,
     list: !!values.list,
     force: !!values.force,
   };
 }
+
+// ---------------------------------------------------------------------------
+// deps flags — FR-023 Phase 1a Task 14
+// ---------------------------------------------------------------------------
+
+/** `meta deps`'s subcommand. `sync` and `list` are this task's; `check` is
+ *  parsed (so the grammar and its usage errors are stable now) but not yet
+ *  implemented — Task 15 wires its behavior. */
+export type DepsSubverb = "sync" | "check" | "list";
+
+const DEPS_SUBVERBS: readonly DepsSubverb[] = ["sync", "check", "list"];
+
+export interface DepsFlags {
+  subverb: DepsSubverb;
+  /** Dependency names to narrow to — `sync`'s `[<name>…]`. Empty means "all
+   *  declared dependencies." Accepted (and ignored) by every subverb rather
+   *  than rejected outright: the positional grammar is one shape for all
+   *  three, and only `sync` gives the list meaning today. */
+  names: string[];
+  /** `sync` only: plan and report, write nothing. */
+  dryRun: boolean;
+}
+
+/** The flag table `parseDepsArgs` parses. Exported so the help text can be
+ *  gated against it. Deliberately carries no "format" key: `--format` is a
+ *  GLOBAL flag `index.ts` strips from argv before any command's parser ever
+ *  runs (see `MIGRATE_OPTIONS`'s "--migration-format, not --format" note
+ *  above) — `meta deps` becomes format-aware by index.ts adding "deps" to
+ *  `FORMAT_AWARE_COMMANDS` and passing the resolved `fmt` through, exactly as
+ *  gen/verify/migrate do, not by re-declaring the flag here. */
+export const DEPS_OPTIONS = {
+  "dry-run": { type: "boolean", default: false },
+} as const;
+
+export function parseDepsArgs(argv: string[]): DepsFlags {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: DEPS_OPTIONS,
+    strict: true,
+    allowPositionals: true,
+  });
+
+  const [subverbRaw, ...names] = positionals;
+  if (subverbRaw === undefined) {
+    throw new Error(
+      "meta deps requires a subcommand: sync | check | list. Try `meta deps sync`.",
+    );
+  }
+  if (!DEPS_SUBVERBS.includes(subverbRaw as DepsSubverb)) {
+    throw new Error(
+      `meta deps: unknown subcommand "${subverbRaw}"; expected one of: ${DEPS_SUBVERBS.join(", ")}.`,
+    );
+  }
+
+  return {
+    subverb: subverbRaw as DepsSubverb,
+    names,
+    dryRun: !!values["dry-run"],
+  };
+}