@metaobjectsdev/cli 1.0.13 → 1.1.1-rc.1

package/src/lib/args.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from "node:util";
+import { parseCommandArgs } from "./strict-args.js";
 import type { DeclaredRename } from "@metaobjectsdev/migrate-ts";
 import { parseAdvisoryLimit } from "./advisory.js";
 
@@ -36,7 +36,7 @@ export const INIT_OPTIONS = {
 } as const;
 
 export function parseInitArgs(argv: string[]): InitFlags {
-  const { values } = parseArgs({
+  const { values } = parseCommandArgs("init", {
     args: argv,
     options: INIT_OPTIONS,
     strict: true,
@@ -79,7 +79,7 @@ export const AGENT_DOCS_OPTIONS = {
 } as const;
 
 export function parseAgentDocsArgs(argv: string[]): AgentDocsFlags {
-  const { values } = parseArgs({
+  const { values } = parseCommandArgs("agent-docs", {
     args: argv,
     options: AGENT_DOCS_OPTIONS,
     strict: true,
@@ -122,6 +122,12 @@ export interface GenFlags {
    * a structured payload, which carries every finding.
    */
   limit: number;
+  /**
+   * `--generators <names>`: narrow the run to these declared generators, by stable name
+   * (ADR-0034 Amendment 9). Undefined runs everything the config declares. A name the
+   * config does not declare is refused; a narrowing never adds a generator.
+   */
+  generators?: string[];
 }
 
 /** The flag table `parseGenArgs` parses. Exported so the help text can be gated against it. */
@@ -132,10 +138,11 @@ export const GEN_OPTIONS = {
   "probe": { type: "boolean", default: false },
   "no-antipatterns": { type: "boolean", default: false },
   "limit": { type: "string" },
+  "generators": { type: "string" },
 } as const;
 
 export function parseGenArgs(argv: string[]): GenFlags {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseCommandArgs("gen", {
     args: argv,
     options: GEN_OPTIONS,
     strict: true,
@@ -162,9 +169,19 @@ export function parseGenArgs(argv: string[]): GenFlags {
     // Throws on a bad value; the command layer reports it and exits 2, exactly as
     // it does for --baseline above.
     limit: parseAdvisoryLimit(values.limit as string | undefined),
+    ...(values.generators !== undefined && { generators: parseGeneratorNames(values.generators as string) }),
   };
 }
 
+/** `docs,api-docs` → `["docs", "api-docs"]`; an empty list is refused, since it would run nothing. */
+function parseGeneratorNames(raw: string): string[] {
+  const names = raw.split(",").map((n) => n.trim()).filter((n) => n !== "");
+  if (names.length === 0) {
+    throw new Error("--generators needs at least one generator name, e.g. --generators docs,api-docs");
+  }
+  return names;
+}
+
 // ---------------------------------------------------------------------------
 // export flags
 // ---------------------------------------------------------------------------
@@ -179,7 +196,7 @@ export const EXPORT_OPTIONS = {
 } as const;
 
 export function parseExportArgs(argv: string[]): ExportFlags {
-  const { values } = parseArgs({
+  const { values } = parseCommandArgs("export", {
     args: argv,
     options: EXPORT_OPTIONS,
     strict: true,
@@ -207,7 +224,7 @@ export const FMT_OPTIONS = {
 } as const;
 
 export function parseFmtArgs(argv: string[]): FmtFlags {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseCommandArgs("fmt", {
     args: argv,
     options: FMT_OPTIONS,
     strict: true,
@@ -251,6 +268,20 @@ function assertSchemaDialect(dialect: string | undefined): void {
 export const MIGRATE_FORMATS = ["default", "flyway"] as const;
 export type MigrateFormat = (typeof MIGRATE_FORMATS)[number];
 
+/**
+ * A `--migration-format` value, validated. One parser for `meta migrate` and `meta verify`,
+ * so the two accept the same formats and refuse a bad one with the same message.
+ *
+ * The flag is --migration-format, not --format: `--format` is already a GLOBAL cli flag
+ * selecting output rendering (toon|json|text), consumed in index.ts.
+ */
+function parseMigrationFormat(raw: string | undefined): MigrateFormat | undefined {
+  if (raw !== undefined && !MIGRATE_FORMATS.includes(raw as MigrateFormat)) {
+    throw new Error(`invalid --migration-format '${raw}'; expected: ${MIGRATE_FORMATS.join(", ")}`);
+  }
+  return raw as MigrateFormat | undefined;
+}
+
 // Exported (not just module-local) so allow-tokens-pinned.test.ts can pin it
 // against sdk's AllowTokenEnum (config.json's static migrate.allow validator)
 // — the two lists drifted silently before that test existed: sdk's enum was
@@ -308,6 +339,12 @@ export interface VerifyFlags {
   allow: AllowToken[];
   /** Skip the schema-drift gate even when --db is present. */
   skipSchema: boolean;
+  /**
+   * The migration file layout the project uses, spelled as `meta migrate` spells it and
+   * resolved with the same precedence (flag > `.metaobjects/config.json` > default). Under
+   * `flyway` the schema-drift gate leaves Flyway's own history table out of the comparison.
+   */
+  migrationFormat: MigrateFormat | undefined;
   /**
    * #225 — D1 binding name from wrangler.toml, spelled/documented the same way
    * `meta migrate --d1 <binding>` does. Gated on `--dialect d1` (D1 has no URL
@@ -334,16 +371,9 @@ export interface VerifyFlags {
    */
   forbidHandEdits: boolean;
   /**
-   * Run the docs-drift gate: regenerate the `meta docs` surfaces into a temp dir and diff
-   * them against the committed docs tree.
-   *
-   * A SEPARATE subverb rather than part of `--codegen`, because they check different
-   * trees under different ownership rules: `--codegen` regenerates `outDir`/`targets` and
-   * must respect the hand edits `meta gen` preserves, while the docs tree has no merge,
-   * no manifest, and lives in a directory the adopter chose (`./docs/generated` by
-   * default) that may hold hand-written files it does not own. Folding them together
-   * would have to pick one of those rules
-   * for both.
+   * `--docs`, removed in 1.1.0 (ADR-0034 Amendment 9): `--codegen` checks documentation with
+   * everything else the generator list declares. Still parsed, so the command can say where
+   * it went (exit 2) rather than "unknown flag".
    */
   docs: boolean;
   /**
@@ -381,6 +411,21 @@ export interface VerifyFlags {
    * the half that CAN fail a build switched on. Same shape as --no-antipatterns.
    */
   noRequirementLint: boolean;
+  /**
+   * The requirement gate's strict switch (ADR-0057): report a live functional
+   * requirement that nothing implements (`WARN_REQUIREMENT_NOTHING_IMPLEMENTS`) at
+   * severity `error`, so it fails the build. The code is unchanged and no other
+   * diagnostic moves. Off by default because a ledger authored ahead of its links is
+   * the normal incremental state.
+   *
+   * Named for what it requires, not `--strict`: `--lax` below is a different axis
+   * (ADR-0023 attribute strictness), and a `--strict` beside it would read as that
+   * flag's opposite rather than as a requirement-gate setting — the same reason
+   * `--replay-snapshot` above is a subverb and not a `--strict` modifier. It is not
+   * an explicit subverb either: the requirement gate runs on every `verify`, so this
+   * flag modifies a gate that is already selected.
+   */
+  requireImplementers: boolean;
   /**
    * Suppress the advisory overlay AUTHORING lint (FR-023 §11.1 item 4) — the
    * finding that an unflagged cross-file redeclaration works today only
@@ -405,6 +450,13 @@ export interface VerifyFlags {
    * and can never fail the build.
    */
   noDeprecationLint: boolean;
+  /**
+   * Suppress the advisory FIELD authoring lint — a reference identity whose
+   * `@fields` names a field the object lacks, and a field name declared twice in
+   * one children list. Advisory only, like its siblings: it has no gate half and
+   * can never fail the build.
+   */
+  noFieldLint: 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`
@@ -436,18 +488,23 @@ export const VERIFY_OPTIONS = {
   dialect: { type: "string" },
   allow: { type: "string", multiple: true },
   "skip-schema": { type: "boolean", default: false },
+  "migration-format": { type: "string" },
   templates: { type: "boolean", default: false },
   codegen: { type: "boolean", default: false },
   "forbid-hand-edits": { type: "boolean", default: false },
+  // Removed in 1.1.0 (ADR-0034 Amendment 9). Still parsed, so `meta verify --docs` prints
+  // where the check went instead of an unknown-flag error.
   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 },
+  "require-implementers": { type: "boolean", default: false },
   "no-overlay-lint": { type: "boolean", default: false },
   "no-name-lint": { type: "boolean", default: false },
   "no-deprecation-lint": { type: "boolean", default: false },
+  "no-field-lint": { type: "boolean", default: false },
   lax: { type: "boolean", default: false },
   "d1": { type: "string" },
   "remote": { type: "boolean", default: false },
@@ -482,7 +539,7 @@ function parseAllowTokens(raw: string | string[] | undefined): AllowToken[] {
 }
 
 export function parseVerifyArgs(argv: string[]): VerifyFlags {
-  const { values } = parseArgs({
+  const { values } = parseCommandArgs("verify", {
     args: argv,
     options: VERIFY_OPTIONS,
     strict: true,
@@ -521,6 +578,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     dialect: dialect as Dialect | undefined,
     allow: allowTokens as AllowToken[],
     skipSchema: !!values["skip-schema"],
+    migrationFormat: parseMigrationFormat(values["migration-format"] as string | undefined),
     templates,
     codegen,
     forbidHandEdits,
@@ -531,9 +589,11 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     anyExplicit,
     noAntipatterns: !!values["no-antipatterns"],
     noRequirementLint: !!values["no-requirement-lint"],
+    requireImplementers: !!values["require-implementers"],
     noOverlayLint: !!values["no-overlay-lint"],
     noNameLint: !!values["no-name-lint"],
     noDeprecationLint: !!values["no-deprecation-lint"],
+    noFieldLint: !!values["no-field-lint"],
     lax: !!values.lax,
     d1: values.d1 as string | undefined,
     remote: !!values.remote,
@@ -561,7 +621,7 @@ export const PROMPT_SNAPSHOT_OPTIONS = {
 } as const;
 
 export function parsePromptSnapshotArgs(argv: string[]): PromptSnapshotFlags {
-  const { values } = parseArgs({
+  const { values } = parseCommandArgs("prompt-snapshot", {
     args: argv,
     options: PROMPT_SNAPSHOT_OPTIONS,
     strict: true,
@@ -632,7 +692,7 @@ export const MIGRATE_OPTIONS = {
 } as const;
 
 export function parseMigrateArgs(argv: string[]): MigrateFlags {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseCommandArgs("migrate", {
     args: argv,
     options: MIGRATE_OPTIONS,
     strict: true,
@@ -652,12 +712,7 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
   const dialect = values.dialect as string | undefined;
   assertSchemaDialect(dialect);
 
-  // NOTE: the flag is --migration-format, not --format: `--format` is already a
-  // GLOBAL cli flag selecting output rendering (toon|json|text), consumed in index.ts.
-  const format = values["migration-format"] as string | undefined;
-  if (format !== undefined && !MIGRATE_FORMATS.includes(format as MigrateFormat)) {
-    throw new Error(`invalid --migration-format '${format}'; expected: ${MIGRATE_FORMATS.join(", ")}`);
-  }
+  const format = parseMigrationFormat(values["migration-format"] as string | undefined);
 
   const onAmb = values["on-ambiguous"] as string | undefined;
   if (onAmb !== undefined && !ON_AMBIGUOUS.includes(onAmb as OnAmbiguous)) {
@@ -669,7 +724,7 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
   return {
     db: values.db as string | undefined,
     dialect: dialect as Dialect | undefined,
-    format: format as MigrateFormat | undefined,
+    format,
     outDir: values["out-dir"] as string | undefined,
     slug: values.slug as string | undefined,
     allow: allowTokens as AllowToken[],
@@ -749,7 +804,7 @@ export const EJECT_OPTIONS = {
 } as const;
 
 export function parseEjectArgs(argv: string[]): EjectFlags {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseCommandArgs("eject", {
     args: argv,
     options: EJECT_OPTIONS,
     strict: true,
@@ -811,7 +866,7 @@ export const DEPS_OPTIONS = {
 } as const;
 
 export function parseDepsArgs(argv: string[]): DepsFlags {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseCommandArgs("deps", {
     args: argv,
     options: DEPS_OPTIONS,
     strict: true,

package/src/lib/catalog-listing.ts

@@ -25,11 +25,12 @@ import {
   type GeneratorRegistryEntry,
   type Layer,
   type MetaobjectsGenConfig,
+  type RunGenOpts,
 } from "@metaobjectsdev/codegen-ts";
 import * as coreTpl from "@metaobjectsdev/codegen-ts";
 import * as reactTpl from "@metaobjectsdev/codegen-ts-react";
 import * as tanstackTpl from "@metaobjectsdev/codegen-ts-tanstack";
-import { composeCatalog, listCatalog, packageOf } from "./catalog.js";
+import { composeCatalog, listCatalog, packageOf, packagedWiring, type GeneratorWiring } from "./catalog.js";
 import {
   buildLibraryRows, renderLibraryText,
   type LibraryCatalogRow, type LibraryProjectContext,
@@ -39,7 +40,8 @@ import {
   RUNTIME_ENTRIES, resolveRuntimePackage, runtimeClosure, runtimeCopyStatus, runtimeInstall,
   type RuntimeCopyRow,
 } from "./runtime-eject.js";
-import { OWNED_RUNTIME_DIR } from "@metaobjectsdev/codegen-ts";
+import { closureOf, packagedTemplates, templateCopyStatus, type TemplateCopyRow } from "./template-eject.js";
+import { DEFAULT_DOCS_DIR, DOCS_TARGET_NAME, OWNED_RUNTIME_DIR } from "@metaobjectsdev/codegen-ts";
 import { readPackageManifest, declaredDependencyNames } from "./package-manifest.js";
 import { describeError } from "./error-text.js";
 
@@ -62,6 +64,8 @@ export interface GeneratorCatalogRow {
   tier: "native" | "neutral";
   package: string;
   description: string;
+  /** The registry's one line a reader needs before wiring this entry. Printed under the row. */
+  note?: string;
   /** From the reference template's `use-when:` header. Absent for a non-ejectable entry. */
   useWhen?: string;
   /** From the reference template's `emits:` header. Absent for a non-ejectable entry. */
@@ -69,6 +73,11 @@ export interface GeneratorCatalogRow {
   requires?: readonly string[];
   configKeys?: readonly string[];
   install: { dev: string[]; runtime: string[] };
+  /**
+   * How to run this generator AS SHIPPED: the import line for its package factory. No
+   * copy involved; `meta eject` prints the local import for an owned one.
+   */
+  wire?: GeneratorWiring;
   source: {
     kind: "reference-template" | "package-only";
     ejectable: boolean;
@@ -81,6 +90,12 @@ export interface GeneratorCatalogRow {
      * imports no adapter, or the project owns none of it.
      */
     runtimeCopy?: RuntimeCopyRow[];
+    /**
+     * ADR-0034 Amendment 8: the template modules this generator calls, as far as the project
+     * owns a copy of them under `codegen/templates/` — each file compared to what the
+     * installed packages would write there. Absent when the project owns none of them.
+     */
+    templateCopy?: TemplateCopyRow[];
   };
   project?: {
     /** Wired in this project's `generators: [...]`. */
@@ -191,6 +206,10 @@ export interface CatalogListingOpts {
      * "probe failed" on every fresh project, for a generator that would in fact run.
      */
     sourceFiles?: readonly string[];
+    /** The metadata source directories, as `meta gen` supplies them: the docs site loads them. */
+    sourceRoots?: readonly string[];
+    /** The physical schema `agent/schema.md` describes, as `meta gen` supplies it. */
+    agentSchema?: RunGenOpts["agentSchema"];
   };
 }
 
@@ -205,10 +224,9 @@ export interface CatalogListingOpts {
 async function probeOne(
   entry: GeneratorRegistryEntry,
   project: CatalogProject,
-  metadata: MetaData,
-  scope: ((fqn: string) => boolean) | undefined,
-  sourceFiles: readonly string[] | undefined,
+  probe: NonNullable<CatalogListingOpts["probe"]>,
 ): Promise<{ count: number; needsConfig?: string[] } | { error: string }> {
+  const { metadata, scope, sourceFiles, sourceRoots, agentSchema } = probe;
   const count = async (config: MetaobjectsGenConfig): Promise<number> => {
     const result = await runGen({
       config: { ...config, generators: [entry.factory()] },
@@ -217,6 +235,8 @@ async function probeOne(
       dryRun: true,
       ...(scope !== undefined ? { scope } : {}),
       ...(sourceFiles !== undefined ? { sourceFiles } : {}),
+      ...(sourceRoots !== undefined ? { sourceRoots } : {}),
+      ...(agentSchema !== undefined ? { agentSchema } : {}),
     });
     return result.files.length;
   };
@@ -230,12 +250,23 @@ async function probeOne(
     // report the key as needed rather than dropping the count: the listing used to show
     // `routes … [fastify]` beside `routes-hono … [hono, would emit 3]` with no reason.
     // Only a retry that SUCCEEDS with the key supplied attributes the failure to it.
+    //
+    // A documentation generator refuses to run while `targets.docs` is unset (ADR-0034
+    // Amendment 9) — again exactly the fresh project `--probe` is asked about — and the
+    // directory changes no file count either, so it is supplied the same way.
+    const needsConfig: string[] = [];
+    let retry: MetaobjectsGenConfig = project.config;
     if (project.config.dbImport === undefined) {
+      retry = { ...retry, dbImport: PROBE_DB_IMPORT_PLACEHOLDER };
+      needsConfig.push("dbImport");
+    }
+    if (entry.factory().target === DOCS_TARGET_NAME && project.config.targets?.[DOCS_TARGET_NAME] === undefined) {
+      retry = { ...retry, targets: { ...retry.targets, [DOCS_TARGET_NAME]: { outDir: DEFAULT_DOCS_DIR } } };
+      needsConfig.push(`targets.${DOCS_TARGET_NAME}`);
+    }
+    if (needsConfig.length > 0) {
       try {
-        return {
-          count: await count({ ...project.config, dbImport: PROBE_DB_IMPORT_PLACEHOLDER }),
-          needsConfig: ["dbImport"],
-        };
+        return { count: await count(retry), needsConfig };
       } catch {
         // Fall through: the original error is the one worth reporting.
       }
@@ -275,12 +306,40 @@ async function ownedRuntimeByGenerator(
   return out;
 }
 
+/**
+ * Per OWNED generator, the project's copies of the template modules it calls. Attributed by
+ * what each generator reaches and only for generators the project owns, as the adapter copy
+ * is: `queries` and `entity` share modules, and a project that ejected only one of them
+ * must not be told it owns the other's.
+ */
+async function ownedTemplatesByGenerator(
+  projectRoot: string,
+  ownedNames: ReadonlySet<string>,
+): Promise<Map<string, TemplateCopyRow[]>> {
+  const out = new Map<string, TemplateCopyRow[]>();
+  const status = await templateCopyStatus(projectRoot, packagedTemplates());
+  if (status.length === 0) return out;
+  for (const name of ownedNames) {
+    let reached: Set<string>;
+    try {
+      reached = new Set(closureOf(name).templates.map((f) => f.path));
+    } catch {
+      continue; // not a reference generator
+    }
+    const files = status.filter((r) => reached.has(r.path));
+    if (files.length > 0) out.set(name, files);
+  }
+  return out;
+}
+
 export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promise<CatalogRow[]> {
   const rows: CatalogRow[] = [];
   const runtimeCopies = opts.project === undefined
     ? new Map<string, { files: RuntimeCopyRow[]; packages: string[] }>()
     : await ownedRuntimeByGenerator(opts.project.projectRoot, opts.project.ownedNames);
-
+  const templateCopies = opts.project === undefined
+    ? new Map<string, TemplateCopyRow[]>()
+    : await ownedTemplatesByGenerator(opts.project.projectRoot, opts.project.ownedNames);
   for (const entry of listCatalog()) {
     const template = entry.ejectable ? readTemplate(entry.name) : undefined;
     // A project that owns this generator's adapter copy installs what the COPY imports,
@@ -290,6 +349,11 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
       ? installSetFor([entry])
       : installSetFor([entry], [], { generators: new Set([entry.name]), ...runtimeInstall(owned.packages) });
     const pkg = packageOf(entry.name) ?? "";
+    // The row keeps the stock wiring even when this project owns the copy: the JSON
+    // consumer reads `source.owned` to know what it runs today, and the package line is
+    // the fact it needs to go back to stock. `renderCatalogText` deliberately hides that
+    // line under an owned row — two imports in front of a human invite wiring both.
+    const wire = packagedWiring(entry);
 
     const row: GeneratorCatalogRow = {
       name: entry.name,
@@ -299,6 +363,7 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
       tier: entry.tier,
       package: pkg,
       description: entry.description,
+      ...(entry.note !== undefined ? { note: entry.note } : {}),
       ...(template !== undefined && headerFacet(template, "use-when") !== undefined
         ? { useWhen: headerFacet(template, "use-when")! }
         : {}),
@@ -308,11 +373,13 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
       ...(entry.requires !== undefined ? { requires: entry.requires } : {}),
       ...(entry.configKeys !== undefined ? { configKeys: entry.configKeys } : {}),
       install: { dev: install.dev, runtime: install.runtime },
+      ...(wire !== undefined ? { wire } : {}),
       source: {
         kind: entry.ejectable ? "reference-template" : "package-only",
         ejectable: entry.ejectable,
         owned: opts.project === undefined ? null : opts.project.ownedNames.has(entry.name),
         ...(owned !== undefined ? { runtimeCopy: owned.files } : {}),
+        ...(templateCopies.has(entry.name) ? { templateCopy: templateCopies.get(entry.name)! } : {}),
       },
     };
 
@@ -328,13 +395,7 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
       let probeError: string | undefined;
       let needsConfig: string[] | undefined;
       if (opts.probe !== undefined) {
-        const outcome = await probeOne(
-          entry,
-          project,
-          opts.probe.metadata,
-          opts.probe.scope,
-          opts.probe.sourceFiles,
-        );
+        const outcome = await probeOne(entry, project, opts.probe);
         if ("count" in outcome) {
           wouldEmit = outcome.count;
           needsConfig = outcome.needsConfig;
@@ -421,18 +482,20 @@ const LAYER_BLURB: Record<Layer, string> = {
   persistence: "how rows are read and written",
   api: "the HTTP surface — pick ONE framework",
   client: "the browser tier — form + hooks + grid compose, they do not conflict",
-  docs: "on by default; the canonical door is `meta docs`",
+  docs: "pages about the model and the code — listed like the rest, written to the `docs` target",
   capability: "chosen by your MODEL, not by browsing — run --probe",
 };
 
 /**
  * ADR-0034 Amendment 3: every generator is a reference helper, not a guarantee. Said at
  * the top of the catalog because this is where an adopter decides what to depend on.
+ * Amendment 5: both ways to run one are named here — import it, or own a copy.
  */
 export const REFERENCE_HELPER_NOTE: readonly string[] = [
-  "Each generator is a reference helper, not a guarantee: `meta eject <name>` copies it into",
-  "your repo and the copy is yours to change. What MetaObjects guarantees (migrate, verify,",
-  "render) is not a generator and is not listed here.",
+  "Each generator is a reference helper, not a guarantee. Import it from its package to run",
+  "it as shipped, or `meta eject <name>` to copy it into your repo and change what it emits.",
+  "What MetaObjects guarantees (migrate, verify, render) is not a generator and is not",
+  "listed here.",
   "Your database, store or framework is not listed (MongoDB, DynamoDB, Express, NestJS, Vue, …)?",
   "Model it anyway and write or retarget a generator: the metaobjects-codegen skill's",
   "references/any-stack.md has the procedure. MySQL is `dialect: \"mysql\"`.",
@@ -440,8 +503,8 @@ export const REFERENCE_HELPER_NOTE: readonly string[] = [
 
 /** The footer line explaining the `package-only` row mark. */
 export const PACKAGE_ONLY_NOTE =
-  "package-only = no reference template ships for it yet, so `meta eject` cannot copy it; " +
-  "import it from its package instead.";
+  "package-only = no reference template ships for it, so `meta eject` cannot copy it. " +
+  "Run one as shipped by importing its factory — the import sits under its row.";
 
 /** The human rendering: grouped by layer, because layer is the axis you select by. */
 export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
@@ -473,6 +536,15 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
           : `owned runtime: ${differing} file(s) DIFFER from the package — meta eject --list`,
       );
     }
+    if (r.source.templateCopy !== undefined) {
+      // The template modules this generator calls, compared to the packages.
+      const differing = r.source.templateCopy.filter((c) => c.verdict === "differs").length;
+      marks.push(
+        differing === 0
+          ? "owned templates: identical to the package"
+          : `owned templates: ${differing} file(s) DIFFER from the package — meta eject --list`,
+      );
+    }
     if (probed && r.project?.wouldEmit !== null && r.project?.wouldEmit !== undefined) {
       const needs = r.project.needsConfig;
       marks.push(
@@ -487,9 +559,16 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
     }
     const suffix = marks.length > 0 ? `  [${marks.join(", ")}]` : "";
     lines.push(`  ${r.name.padEnd(width)}  —  ${r.description}${suffix}`);
+    if (r.note !== undefined) lines.push(`  ${" ".repeat(width)}     ${r.note}`);
     if (r.requires !== undefined && r.requires.length > 0) {
       lines.push(`  ${" ".repeat(width)}     requires: ${r.requires.join(", ")}`);
     }
+    // The import that runs it as shipped. Not shown once the project owns a copy: its
+    // wiring is then the local import `meta eject` printed, and showing the package's
+    // beside an `owned` mark invites wiring both.
+    if (r.wire !== undefined && r.source.owned !== true) {
+      lines.push(`  ${" ".repeat(width)}     ${r.wire.import}`);
+    }
   }
 
   // The library section sits between the generators and the footer: the footer's
@@ -498,8 +577,9 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
   lines.push(...renderLibraryText(rows.filter((r): r is LibraryCatalogRow => r.kind === "library")));
 
   lines.push("");
-  lines.push("`meta eject <name...>` copies a generator into codegen/generators/ and prints");
-  lines.push("the import to add, the entry to wire, and what to install.");
+  lines.push("To run a generator as shipped, add the import under its row and call it in");
+  lines.push("`generators: [...]`. To change what one emits, `meta eject <name...>` copies it into");
+  lines.push("codegen/generators/ and prints the import to swap in, the entry to wire, and what to install.");
   if (generators.some((r) => !r.source.ejectable)) lines.push(PACKAGE_ONLY_NOTE);
   if (!probed) {
     lines.push("Add --probe to see how many files each would emit for YOUR model.");

package/src/lib/catalog.ts

@@ -21,11 +21,24 @@ import {
 import { reactGeneratorRegistry } from "@metaobjectsdev/codegen-ts-react";
 import { tanstackGeneratorRegistry } from "@metaobjectsdev/codegen-ts-tanstack";
 
-/** The slices, in install-boundary order: the engine, then its framework packages. */
-const SLICES: ReadonlyArray<readonly [string, Record<string, GeneratorRegistryEntry>]> = [
-  ["@metaobjectsdev/codegen-ts", generatorRegistry],
-  ["@metaobjectsdev/codegen-ts-react", reactGeneratorRegistry],
-  ["@metaobjectsdev/codegen-ts-tanstack", tanstackGeneratorRegistry],
+/**
+ * The engine package. Its factories are served from a `/generators` subpath rather than
+ * its root (the root is the engine plus the primitives an owned generator composes); the
+ * framework packages serve theirs from the root. Exported because `eject.ts`'s source
+ * table names the same package — one definition per CLI package, not two.
+ */
+export const CORE_CODEGEN_PACKAGE = "@metaobjectsdev/codegen-ts";
+
+/**
+ * The slices, in install-boundary order: the engine, then its framework packages. The
+ * third element is the module that package serves factories from — a per-package fact
+ * declared at registration, so {@link factoryModuleOf} is a lookup and a new slice
+ * carries its own fact instead of adding a case to a name-keyed branch.
+ */
+const SLICES: ReadonlyArray<readonly [string, Record<string, GeneratorRegistryEntry>, string]> = [
+  [CORE_CODEGEN_PACKAGE, generatorRegistry, `${CORE_CODEGEN_PACKAGE}/generators`],
+  ["@metaobjectsdev/codegen-ts-react", reactGeneratorRegistry, "@metaobjectsdev/codegen-ts-react"],
+  ["@metaobjectsdev/codegen-ts-tanstack", tanstackGeneratorRegistry, "@metaobjectsdev/codegen-ts-tanstack"],
 ];
 
 /**
@@ -44,6 +57,38 @@ export function catalogPackages(): string[] {
   return SLICES.map(([pkg]) => pkg);
 }
 
+/**
+ * The module a catalog entry's factory is imported from to run it as shipped — the third
+ * element of the slice that registers the name. Undefined for a name no slice registers.
+ */
+export function factoryModuleOf(name: string): string | undefined {
+  return SLICES.find(([, slice]) => name in slice)?.[2];
+}
+
+/**
+ * How one generator reaches a config as shipped: the import line for its factory. The
+ * call is not derived here — a factory's options are documented with the generator.
+ */
+export interface GeneratorWiring {
+  import: string;
+}
+
+/**
+ * How to wire a catalog entry AS SHIPPED: import its factory from the package, no copy.
+ *
+ * This is the half of "import by default, eject to customize" the catalog owns. The
+ * other half is `meta eject`, which prints the import for the owned copy — the symbol is
+ * the same in both (gated), so moving between them is one import line.
+ *
+ * Every entry has one, documentation included (ADR-0034 Amendment 9): there is one way to
+ * generate, and an entry is wired the same way whatever it writes.
+ */
+export function packagedWiring(entry: GeneratorRegistryEntry): GeneratorWiring | undefined {
+  const from = factoryModuleOf(entry.name);
+  if (from === undefined) return undefined;
+  return { import: `import { ${entry.factoryExport} } from "${from}";` };
+}
+
 /**
  * The composed catalog, keyed by stable name.
  *
@@ -54,7 +99,7 @@ export function catalogPackages(): string[] {
  * another.
  */
 export function composeCatalog(): Record<string, GeneratorRegistryEntry> {
-  return composeSlices(SLICES);
+  return composeSlices(SLICES.map(([pkg, slice]) => [pkg, slice] as const));
 }
 
 /**