@metaobjectsdev/cli 1.0.12 → 1.1.0

package/src/commands/gen.ts

@@ -1,4 +1,4 @@
-import { relative } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { parseGenArgs } from "../lib/args.js";
 import { resolveGenConfig, resolveMigrateDefaults } from "../lib/config.js";
 import { genMigrateAdvice } from "../lib/gen-migrate-advice.js";
@@ -16,7 +16,7 @@ import {
   type AdvisoryFindingRow, type AdvisorySection,
 } from "../lib/advisory.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
-import { runGen } from "@metaobjectsdev/codegen-ts";
+import { declaredGeneratorNames, runGen, undeclaredGeneratorsMessage } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
 import { packageOfResolutionKey } from "@metaobjectsdev/metadata";
 import type { MetaRoot } from "@metaobjectsdev/metadata";
@@ -27,10 +27,13 @@ import {
   buildCatalogListing, renderCatalogText, wiredGeneratorNames, ownedGeneratorNames,
   declaredDepsOf,
 } from "../lib/catalog-listing.js";
-import { emitStructured } from "../lib/format.js";
+import { emitStructured, narrate } from "../lib/format.js";
 import { composeCatalog } from "../lib/catalog.js";
 import { describeError } from "../lib/error-text.js";
 import { findRuntimeBoundaryCrossings, runtimeBoundaryWarnings } from "../lib/runtime-boundary-advisory.js";
+import { hasLegacyDocsBlock, legacyDocsConfigMessage, NO_CONFIG_MESSAGE } from "../lib/docs-removed.js";
+import { buildAgentSchemaInput } from "../lib/agent-schema.js";
+import { existsSync } from "node:fs";
 
 /**
  * Print a load failure with everything the loader's ADR-0009 envelope carried — the stable
@@ -127,13 +130,26 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   // would find no manifest there and silently skip the nudge. `meta verify` makes
   // the same call for the same reason; the two commands describe this and the
   // anti-pattern scan below as one advisory pass, so they must scan one tree.
-  warnIfAgentContextStale(projectRoot);
+  //
+  // EVERY warning this run prints is also collected here, in the order printed, because
+  // the structured result carries them. They used to reach stderr only — and on a pipe,
+  // where the default format is the document, a reader of that document saw a clean run
+  // with every caveat missing. A new warning site adds to this list.
+  const warnings: string[] = [];
+  const advise = (line: string | undefined): void => { if (line !== undefined) warnings.push(line); };
+  advise(warnIfAgentContextStale(projectRoot));
   // Advisory: the committed hash manifest is what makes hand-edit detection work on a
   // machine that did not generate the output. Silent unless it is ignored. Keyed on
   // projectRoot, not cwd, for the same reason its neighbour is — the manifest belongs to
   // whichever directory `resolveCollection` decided the metadata lives in.
-  warnIfManifestIgnored(projectRoot);
+  advise(warnIfManifestIgnored(projectRoot));
 
+  // ADR-0034 Amendment 9: the config IS the list. With none there is nothing to generate,
+  // documentation included, and a run that wrote nothing silently would read as a pass.
+  if (!existsSync(join(projectRoot, "metaobjects.config.ts"))) {
+    log.error(NO_CONFIG_MESSAGE);
+    return 2;
+  }
   let forgeConfig;
   try {
     forgeConfig = await loadMetaobjectsConfig(projectRoot);
@@ -141,6 +157,28 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     log.error(describeError(err));
     return 2;
   }
+  // A 1.0 `docs` block configured a command that no longer exists. Nothing reads it, so the
+  // run would write no documentation; it fails before writing anything instead.
+  if (hasLegacyDocsBlock(forgeConfig)) {
+    log.error(legacyDocsConfigMessage("meta gen"));
+    return 2;
+  }
+  // `--generators` narrows to DECLARED entries, by stable name; it never adds one.
+  const catalog = composeCatalog();
+  if (flags.generators !== undefined) {
+    let declared: string[];
+    try {
+      declared = declaredGeneratorNames(forgeConfig, catalog);
+    } catch (err) {
+      log.error(describeError(err));
+      return 2;
+    }
+    const unknown = flags.generators.filter((n) => !declared.includes(n));
+    if (unknown.length > 0) {
+      log.error(`meta gen: ${undeclaredGeneratorsMessage(unknown, declared)}`);
+      return 2;
+    }
+  }
 
   let metadata;
   const loadOptions = {
@@ -151,7 +189,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     metadata = await loadMemory(genCollection.configDir, loadOptions);
   } catch (err) {
     reportLoadError(log, "failed to load metadata", err);
-    return 2;
+    return 1;
   }
 
   // ADR-0023: gen loads leniently, so an unknown attribute (`isAbstrakt: true`, a
@@ -162,7 +200,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   const unknownAttrs = unknownAttrFindings.length > 0
     ? [...unknownAttrFindings, UNKNOWN_ATTR_GEN_ADVICE]
     : [];
-  for (const w of unknownAttrs) log.warn(`warning: ${w}`);
+  for (const w of unknownAttrs) { log.warn(`warning: ${w}`); warnings.push(w); }
 
   // FR-023 §11.1 item 2 — refuse a positional that names ONLY objects imported
   // from a dependency and excluded from output by the default exclusion rule.
@@ -185,7 +223,8 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
       projectRoot,
       // The COMPOSED catalog, so the requires / api-framework gates can see the react
       // and tanstack entries too. codegen-ts only knows its own slice.
-      catalog: composeCatalog(),
+      catalog,
+      ...(flags.generators !== undefined && { generatorNames: flags.generators }),
       baseline: flags.baseline,
       // --dry-run must actually preview. This was previously passed only to the
       // display object below, so a "preview" run wrote every file.
@@ -199,6 +238,15 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
       // snapshot artifact), so sharedModelFile() defaults its `files` selection
       // to exactly what this project itself declares.
       sourceFiles: genCollection.ownFiles,
+      // The source DIRECTORIES, with each dependency artifact's, for a generator that loads
+      // the model with a loader of its own (the docs site).
+      sourceRoots: sourceRootsOf(genCollection),
+      // The physical schema `agent/schema.md` describes, built only if `agentDocsFile()` asks.
+      agentSchema: () => buildAgentSchemaInput(
+        metadata,
+        forgeConfig.dialect,
+        (m) => { const w = `[agent-docs] ${m}`; log.warn(w); warnings.push(w); },
+      ),
       // FR-043 §6 — the shipped-library selection. Always passed, including as `[]`:
       // that is what tells the post-selection audit "this project opted into none",
       // which is a different statement from a programmatic caller that never said.
@@ -210,20 +258,23 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     return 1;
   }
 
-  for (const w of result.warnings) { log.warn(w); }
+  for (const w of result.warnings) { log.warn(w); warnings.push(w); }
 
   // A first-run POINTER, not a warning: an empty selection is the designed state of a
   // fresh `meta init`, so calling it a problem would make every new project start with
   // one. It says what to do next and disappears the moment anything is wired.
   if ((forgeConfig.generators?.length ?? 0) === 0) {
-    log.info(
+    // stdout only in text format: a structured run carries the same pointer in the
+    // document's `help`, and a sentence in front of the document breaks `| jq`.
+    narrate(fmt,
       "\nNothing is generated until you choose it — `generators: []` is what `meta init` " +
         "scaffolds, by design.\n" +
-        "  meta gen --list --probe    the catalog, with how many files each generator " +
-        "would emit for YOUR model\n" +
-        "  meta eject <name>...       take the ones you want; it prints the import, the " +
-        "entry to wire, and what to install\n" +
-        "(`meta docs` needs none of this — documentation is on by default.)",
+        "  meta gen --list --probe    the catalog: the import that runs each generator as " +
+        "shipped, and how many files it would emit for YOUR model\n" +
+        "  meta eject <name>...       copy one into your repo to change what it emits; it " +
+        "prints the import to swap in, the entry to wire, and what to install\n" +
+        "Documentation is chosen the same way: docsFile(), apiDocsFile() and the rest, with a " +
+        "`docs` target.",
     );
   }
 
@@ -241,7 +292,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   if (!cliConfig.dryRun) {
     for (const w of runtimeBoundaryWarnings(
       findRuntimeBoundaryCrossings(projectRoot, result.files.map((f) => f.path)),
-    )) log.warn(`warning: ${w}`);
+    )) { log.warn(`warning: ${w}`); warnings.push(w); }
   }
 
   const targetDirs = Array.from(new Set(
@@ -263,9 +314,9 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     metadata,
     dialect: forgeConfig.dialect,
     migrateDialect: migrateDefaults.dialect,
-    columnNamingStrategy: forgeConfig.columnNamingStrategy,
     projectRoot,
     migrateOutDir: migrateDefaults.outDir,
+    migrateFormat: migrateDefaults.format,
     changedFiles: result.files.filter((f) => CHANGED_STATUSES.has(f.status)).map((f) => f.path),
   });
 
@@ -275,7 +326,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     dialect: forgeConfig.dialect,
     dryRun: cliConfig.dryRun,
     // Text mode already printed these to stderr above; the structured forms carry them.
-    warnings: fmt === "text" ? [] : unknownAttrs,
+    warnings: fmt === "text" ? [] : warnings,
     antiPatterns,
     generatorCount: forgeConfig.generators?.length ?? 0,
     ...(migrateAdvice !== undefined ? { migrateAdvice } : {}),
@@ -436,7 +487,7 @@ async function listCatalogCommand(
       });
     } catch (err) {
       reportLoadError(log, "failed to load metadata", err);
-      return 2;
+      return 1;
     }
 
     opts = {
@@ -451,9 +502,21 @@ async function listCatalogCommand(
         // codegen config it was moved out of.
         libraries: genCollection.libraries,
       },
-      // The collection's own files, exactly as `meta gen` supplies them below —
-      // `shared-model` cannot be counted without them.
-      probe: { metadata, scope: genCollection.inScope, sourceFiles: genCollection.ownFiles },
+      // The run inputs `meta gen` supplies below: `shared-model` cannot be counted without the
+      // collection's own files, `docs-site` without its source directories, and `agent-docs`
+      // leaves out its schema page without the schema. The schema's skip reasons are not
+      // printed: a count is what the probe reports.
+      probe: {
+        metadata,
+        scope: genCollection.inScope,
+        sourceFiles: genCollection.ownFiles,
+        sourceRoots: sourceRootsOf(genCollection),
+        agentSchema: () => buildAgentSchemaInput(
+          metadata,
+          forgeConfig.dialect,
+            () => {},
+        ),
+      },
     };
   } else {
     // No probe: still report `wired` / `owned` when a project happens to be here, since
@@ -483,3 +546,12 @@ async function listCatalogCommand(
   else emitStructured(rows, fmt);
   return 0;
 }
+
+/**
+ * The collection's metadata source directories, followed by the directory of each dependency's
+ * artifact: a loader that reads whole directories (the docs site's) needs both, or an
+ * `extends` onto an imported abstract would not resolve in it.
+ */
+export function sourceRootsOf(collection: Collection): string[] {
+  return [...collection.sourceRoots, ...new Set(collection.dependencies.map((d) => dirname(d.artifactPath)))];
+}

package/src/commands/generator.ts

@@ -13,9 +13,9 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { parseArgs } from "node:util";
 import { catalogEntry } from "../lib/catalog.js";
 import { log } from "../lib/log.js";
+import { parseCommandArgs } from "../lib/strict-args.js";
 import { dependencyNotesForTemplate } from "./eject.js";
 import {
   CONFIG_FILE,
@@ -333,7 +333,7 @@ export async function generatorCommand(args: string[], cwd: string): Promise<num
   let values: { scope?: string; force?: boolean; "no-wire"?: boolean };
   let positionals: string[];
   try {
-    ({ values, positionals } = parseArgs({ args, options: GENERATOR_OPTIONS, strict: true, allowPositionals: true }));
+    ({ values, positionals } = parseCommandArgs("generator", { args, options: GENERATOR_OPTIONS, strict: true, allowPositionals: true }));
   } catch (err) {
     log.error(describeError(err));
     return 2;

package/src/commands/init.ts

@@ -11,13 +11,17 @@ import { assertKnownStackValues, resolveStack } from "../lib/detect-stack.js";
 import { reportIgnoredScaffold } from "../lib/ignored-scaffold-check.js";
 import { parseInitArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
-import { cliVersion } from "../lib/version.js";
+import { cliVersion, isPrereleaseVersion } from "../lib/version.js";
+import { currentContentHash } from "../lib/agent-context-staleness.js";
 import { findWranglerConfig, parseWranglerConfig } from "@metaobjectsdev/migrate-ts";
 import { DEFAULT_DOCS_DIR } from "@metaobjectsdev/codegen-ts";
 import { describeError } from "../lib/error-text.js";
+import { SUBTYPE_ROOT, TYPE_METADATA, TYPE_SUBTYPE_SEPARATOR } from "@metaobjectsdev/metadata/constants";
+import { docsRefForVersion } from "@metaobjectsdev/metadata";
 
-// ADR-0034 scaffold-and-own — `meta init` copies the codegen reference templates into
-// the consumer's repo so they OWN them; metaobjects.config.ts imports them locally.
+// ADR-0034 scaffold-and-own — where `meta eject` and `meta generator new` put a generator
+// the consumer OWNS. `meta init` scaffolds it empty; metaobjects.config.ts imports from it
+// locally, or imports a stock generator from its package (Amendment 5).
 const OWNED_GENERATORS_DIR = "codegen/generators";
 
 
@@ -31,13 +35,10 @@ const OWNED_GENERATORS_DIR = "codegen/generators";
 // `meta gen --list` and by `meta eject routes`, to the adopter who actually chose it.
 const SCAFFOLD_OUT_DIR = "src/generated";
 
+// The canonical form of an empty root, byte-for-byte what `meta fmt` writes, so a
+// freshly scaffolded project passes `meta fmt --check` (it used to fail it at once).
 const META_COMMON_JSON = JSON.stringify(
-  {
-    metadata: {
-      package: "",
-      children: [] as unknown[],
-    },
-  },
+  { [`${TYPE_METADATA}${TYPE_SUBTYPE_SEPARATOR}${SUBTYPE_ROOT}`]: {} },
   null,
   2,
 ) + "\n";
@@ -107,33 +108,37 @@ export default defineConfig({
   // would emit, so you can see what your metadata is already asking for. Group by
   // \`layer\`: model / persistence / api / client / docs / capability.
   //
-  // Then take the ones you want:
+  // Every row carries the import line that runs its generator as shipped
+  // (\`wire.import\`). Add it at the top of this file:
+  //
+  //   import { entityFile, queriesFile, barrel } from "@metaobjectsdev/codegen-ts/generators";
+  //
+  // then call each one in the array below: entityFile(), queriesFile(), barrel(). A
+  // generator's options are in its documentation. The row also lists what to install
+  // and the config keys the generator reads (\`dbImport\`, \`apiPrefix\`, \`extStyle\`, …).
+  // Add them here as you go.
+  //
+  // Need one to emit something different? Own it:
+  //
+  //   meta eject entity
   //
-  //   meta eject entity queries routes barrel
+  // copies that generator into ./codegen/generators/ — YOURS to edit — and prints the
+  // local import to swap in for the package one. \`meta gen\` then runs your copy.
   //
-  // That copies each generator into ./codegen/generators/ — YOURS to edit, and what
-  // \`meta gen\` runs — and prints the import line to add here, the entry to add below,
-  // what to install, and any config keys those generators read (\`dbImport\`,
-  // \`apiPrefix\`, \`extStyle\`, …). Add them here as you go.
+  // Documentation is chosen the same way: the \`docs\` layer of the catalog (docsFile(),
+  // apiDocsFile(), …) writes to a \`docs\` target you declare beside \`generators\`:
+  //
+  //   targets: { docs: { outDir: "${DEFAULT_DOCS_DIR}" } },
+  //
+  // Nothing is generated that this file does not declare, documentation included.
   //
   // Need an output nothing in that catalog emits — OpenAPI, JSON Schema, a client, a
-  // service layer, docs? Write your own generator; that is the normal path:
+  // service layer? Write your own generator; that is the normal path:
   //
   //   meta generator new openapi --scope model
   //
   // writes a working, commented generator into ./codegen/generators/ and adds it here.
   generators: [],
-
-  docs: {
-    outDir: "${DEFAULT_DOCS_DIR}",  // every surface lands here (run: meta docs).
-                               // A SUB-directory on purpose: these pages are regenerated
-                               // and overwritten, and docs/ itself is usually yours.
-    layout: "flat",            // or "package" for multi-package models
-    // surfaces defaults to ["model", "api", "requirements", "agent"] — all four.
-    // Documentation is the one thing that IS on by default, because the requirements
-    // and agent surfaces emit ZERO files for a project with nothing to describe, and
-    // the always-on agent context points at the agent/ pages by name.
-  },
 });
 `;
 }
@@ -150,14 +155,16 @@ Next steps:
   1. Author entities under metaobjects/ (start from the scaffolded meta.common.json)
   2. meta gen --list --probe    # the catalog: every generator, grouped by layer, with
                                 #   how many files each would emit for YOUR model
-  3. meta eject <name>...       # take the ones you want — copies them into
+  3. Wire the ones you want in metaobjects.config.ts: each catalog row prints the
+     import that runs it as shipped.
+     meta eject <name>...       # need to change what one emits? copies it into
                                 #   codegen/generators/ (yours to edit) and prints the
-                                #   import, the entry to wire, and what to install
+                                #   import to swap in and what to install
      meta generator new <name>  # an output no reference emits? write your own — this
                                 #   scaffolds a working one and wires it
-  4. meta gen                  # generate from exactly what you wired
-  5. meta docs                  # neutral model + API docs (on by default)
-  6. Create your tables: meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
+  4. meta gen                  # generate from exactly what you wired, documentation
+                                #   included (the docs layer of the catalog)
+  5. Create your tables: meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
      A new database later (a fresh clone, CI, tests) replays the committed migrations:
        meta migrate apply-pending --db file:other.sqlite
 `;
@@ -205,6 +212,13 @@ export interface InitResult {
    * just scaffolded over your work.
    */
   refreshedDocsOnly?: boolean;
+  /**
+   * True when the project was already initialized (`metaobjects/` or `.metaobjects/`
+   * exists) and the run was neither `--force` nor `--refresh-docs`: nothing was written.
+   * A re-run asks for a state that already holds, so it is a no-op that exits 0, not
+   * the error it used to be.
+   */
+  alreadyInitialized?: boolean;
 }
 
 async function readManifest(cwd: string): Promise<Manifest | undefined> {
@@ -299,17 +313,31 @@ async function writeAgentContext(opts: InitOptions, result: InitResult): Promise
   warnIfMonorepoSubdir(opts, result);
   const prior = await readManifest(opts.cwd);
   const stack = await stackForAgentContext(opts, prior);
-  let assembled = assemble({ contentRoot: resolveAgentContextRoot(), stack });
+  let assembled = assemble({ contentRoot: resolveAgentContextRoot(), stack, docsRef: docsRefForVersion(cliVersion()) });
   if (opts.noSkills) assembled = assembled.filter((f) => !f.path.startsWith(".claude/skills/"));
 
+  const generatedBy = cliVersion();
+  const contentHash = currentContentHash().currentContentHash;
   const decision = planScaffold({
     stack, assembled, prior,
     readCurrent: (rel) => {
       const abs = join(opts.cwd, rel);
       return existsSyncWrap(abs) ? readFileSyncWrap(abs, "utf8") : undefined;
     },
-    generatedBy: cliVersion(),
+    generatedBy,
+    ...(contentHash !== undefined && { contentHash }),
   });
+  // A pre-release CLI stamps its own pre-release version into the committed
+  // .metaobjects/.agent-context.json ("generatedBy") and the skills/docs it scaffolds may
+  // differ from the eventual release's. tools/prerelease/detect-prerelease-pins.sh now
+  // flags that on the tree side; this is the other half — say so at the moment it is
+  // written, not only when someone later runs the detector.
+  if (isPrereleaseVersion(generatedBy)) {
+    result.warnings.push(
+      `agent context generated by pre-release CLI ${generatedBy} — refresh it again with ` +
+        `the release CLI before merging ('meta init --refresh-docs --docs-only').`,
+    );
+  }
 
   // --force: overwrite hand-edited docs in place rather than parking the fresh copy
   // at <path>.new (issue #163 — a forced (re)scaffold means "I mean it"; applies to
@@ -585,9 +613,10 @@ export async function init(opts: InitOptions): Promise<InitResult> {
   }
 
   if (exists && !opts.force && !opts.refreshDocs) {
-    throw new Error(
-      "metaobjects/ or .metaobjects/ already exists; use --force to overwrite scaffold files (existing records are preserved), or --refresh-docs to update only agent docs",
-    );
+    if (metaobjectsExists) result.preserved.push(DEFAULT_METADATA_DIR);
+    if (agentDirExists) result.preserved.push(DEFAULT_METAOBJECTS_DIR);
+    result.alreadyInitialized = true;
+    return result;
   }
 
   const dirs = [
@@ -603,7 +632,10 @@ export async function init(opts: InitOptions): Promise<InitResult> {
       ".metaobjects/config.json",
       ".metaobjects/.gitignore",
     );
-    result.created.push(".metaobjects/AGENTS.md", ".metaobjects/CLAUDE.md", ".claude/skills/metaobjects-*", AGENT_CONTEXT_MANIFEST_PATH);
+    // The agent context forecasts itself: writeAgentContext is dry-run aware and
+    // reports exactly the paths a real run writes — the root CLAUDE.md/AGENTS.md wiring
+    // included, which a hand-kept list here used to leave out.
+    await writeAgentContext(opts, result);
     result.created.push(OWNED_GENERATORS_DIR, CODEGEN_TSCONFIG_REL);
     result.created.push("metaobjects.config.ts", ".gitignore");
     return result;
@@ -884,9 +916,19 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
       configOnly: flags.configOnly,
     });
 
+    if (result.alreadyInitialized) {
+      log.info(
+        `meta init: already initialized (${result.preserved.join(" and ")} exist) — nothing written (no-op).\n` +
+          "  meta init --refresh-docs   update the agent docs after a CLI upgrade\n" +
+          "  meta init --force          re-scaffold the project files (your metadata is preserved)",
+      );
+      return 0;
+    }
+
     if (flags.printOnly) {
       log.info("Would create:");
       for (const path of result.created) log.info(`  ${path}`);
+      for (const w of result.warnings) log.info(`  ${w}`);
       return 0;
     }