@metaobjectsdev/cli 0.24.4 → 0.25.0

package/src/commands/docs.ts

@@ -22,6 +22,7 @@ import {
   makeRenderContext,
   buildPkMap,
   buildRelationMap,
+  buildProjectionViews,
   resolveDocsConfig,
   apiLabel,
 } from "@metaobjectsdev/codegen-ts";
@@ -30,11 +31,28 @@ import type {
   EmittedFile,
   ResolvedDocsConfig,
   DocsSurface,
+  Dialect,
+  ColumnNamingStrategy,
 } from "@metaobjectsdev/codegen-ts";
-import { docsFile, apiDocsFile, requirementsFile } from "@metaobjectsdev/codegen-ts/generators";
-import { composeRegistry, coreProviders, renderCoreMetamodelDocs } from "@metaobjectsdev/metadata";
-import type { MetaDataTypeProvider } from "@metaobjectsdev/metadata";
+import { docsFile, apiDocsFile, requirementsFile, agentDocsFile } from "@metaobjectsdev/codegen-ts/generators";
+import {
+  composeRegistry,
+  coreProviders,
+  DEFAULT_COLUMN_NAMING_STRATEGY,
+  renderCoreMetamodelDocs,
+} from "@metaobjectsdev/metadata";
+import { dbEmittingObjects, DEFAULT_DIALECT, missingDialectMessage } from "@metaobjectsdev/codegen-ts";
+import type { MetaDataTypeProvider, MetaRoot } from "@metaobjectsdev/metadata";
 import { generateSite, SITE_TEMPLATE_NAMES, SITE_ASSET_NAMES, readSiteFile } from "@metaobjectsdev/docs-site";
+// The `agent` schema surface takes the physical schema as an ARGUMENT with its resolvers
+// injected — codegen-ts deliberately owns none of it (see agent-schema-input.ts). THIS is
+// where the two packages meet: `meta docs` already depends on both.
+import {
+  buildExpectedSchemaWithProvenance,
+  columnTypeSql,
+  qualifiedDbName,
+} from "@metaobjectsdev/migrate-ts";
+import type { AgentSchemaInput, SchemaColumnLike } from "@metaobjectsdev/codegen-ts";
 
 type DocsLayout = "flat" | "package";
 
@@ -106,6 +124,7 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   let wantModel = false;
   let wantApi = false;
   let wantRequirements = false;
+  let wantAgent = false;
   let wantMetamodel = false;
   let wantSite = false;
   let wantScaffoldSite = false;
@@ -133,6 +152,8 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
       wantApi = true;
     } else if (a === "--requirements") {
       wantRequirements = true;
+    } else if (a === "--agent") {
+      wantAgent = true;
     } else if (a === "--metamodel") {
       wantMetamodel = true;
     } else if (a === "--site") {
@@ -175,6 +196,7 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   if (wantModel) surfaces.push("model");
   if (wantApi) surfaces.push("api");
   if (wantRequirements) surfaces.push("requirements");
+  if (wantAgent) surfaces.push("agent");
   return {
     // `<project-root>` is the project root that CONTAINS the metadata; default
     // cwd (mirrors how migrate/gen treat the working directory as the root).
@@ -197,7 +219,99 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   };
 }
 
-export async function docsCommand(args: string[], cwd: string): Promise<number> {
+/**
+ * How a caller other than the CLI wants `meta docs` to behave.
+ *
+ * `verify --docs` runs this exact command into a temp directory and diffs the result, so
+ * that the gate and the door can never be two implementations of "what the docs are". The
+ * only thing it needs differently is silence: a verify run announcing "meta docs — wrote 8
+ * entity pages" in the middle of its own report describes work the user is not getting.
+ */
+export interface DocsCommandOptions {
+  /** Suppress the informational output. Warnings and errors still print — a docs run that
+   *  degraded is something a verify caller must see, not something to swallow. */
+  silent?: boolean;
+}
+
+/**
+ * The physical schema `agent/schema.md` renders from, built by the package that OWNS it
+ * (`migrate-ts`) with its own resolvers handed across — see codegen-ts's
+ * agent-schema-input.ts for why the docs generator refuses to compute any of this itself.
+ *
+ * Returns undefined, after warning, when the page is to be SKIPPED — and a skipped page is
+ * not a silent pass: `verify --docs` convicts a committed `agent/<page>.md` that a fresh
+ * run no longer emits (see lib/docs-drift.ts), so a page describing the previous schema
+ * fails the gate rather than surviving it on exactly the change it most needs to flag.
+ */
+function buildAgentSchemaInput(
+  root: MetaRoot,
+  configured: Dialect | undefined,
+  strategy: ColumnNamingStrategy,
+): AgentSchemaInput | undefined {
+  // THE RUNNER'S OWN GUARD DECIDES THIS, not a default applied here.
+  //
+  // `DEFAULT_DIALECT` is INERT: `runGen` throws when a model emits database code and the
+  // config declares no dialect, and it throws BEFORE `normalizeConfig` fills that default
+  // in, precisely so a DB project that forgot one gets a named error instead of
+  // "a Postgres project quietly emitting sqlite". So a persisted model with no dialect is
+  // not a sqlite project — it is a project `meta gen` REFUSES. Documenting it as sqlite
+  // would state an answer the toolchain never gave, about a schema it will not build.
+  //
+  // Two wrong answers were tried here before this one, and both were ASSERTIONS. First a
+  // hardcoded `?? "sqlite"`; then a skip whenever `dialect` was absent, on the theory that
+  // an undeclared dialect is an unknown one. The compute answer is to ask the predicate
+  // `runGen` asks — `dbEmittingObjects` — and skip only when that guard would fire. A model
+  // with no persisted object needs no dialect and renders an empty schema page anyway, so
+  // the inert default is correct for exactly the projects the guard lets through.
+  const dbEmitting = dbEmittingObjects(root.objects());
+  if (dbEmitting.length > 0 && configured === undefined) {
+    log.warn(
+      `docs: agent/schema.md skipped — ${missingDialectMessage(dbEmitting)} ` +
+        `('meta gen' refuses this model for the same reason.)`,
+    );
+    return undefined;
+  }
+  const dialect = configured ?? DEFAULT_DIALECT;
+  try {
+    const built = buildExpectedSchemaWithProvenance(root, {
+      dialect,
+      columnNamingStrategy: strategy,
+      // Views come from codegen-ts (migrate-ts never generates view DDL), exactly as
+      // `verify --db` threads them.
+      views: buildProjectionViews(root, { dialect, columnNamingStrategy: strategy }),
+    });
+    return {
+      dialect,
+      tables: built.snapshot.tables,
+      views: built.snapshot.views,
+      provenance: built.provenance,
+      // The structural `SchemaColumnLike` is migrate-ts's own ColumnDescriptor,
+      // narrowed to what the page reads; the cast hands the full descriptor back to
+      // the renderer that produced it.
+      columnType: (c: SchemaColumnLike) => columnTypeSql(c as never, dialect),
+      qualify: qualifiedDbName,
+    };
+  } catch (err) {
+    // A model the schema builder refuses is a real condition (a primary-key move, a
+    // duplicate physical name) that `meta migrate` will report properly. Docs must not
+    // be the command that fails on it, so the schema page is skipped and the other two
+    // agent pages still emit.
+    log.warn(
+      `docs: agent/schema.md skipped — the expected schema could not be built ` +
+        `(${(err as Error).message}). Run 'meta migrate' for the full diagnosis.`,
+    );
+    return undefined;
+  }
+}
+
+export async function docsCommand(
+  args: string[],
+  cwd: string,
+  opts?: DocsCommandOptions,
+): Promise<number> {
+  // Informational output only. `log.warn` / `log.error` are deliberately NOT routed
+  // through this: a skipped surface or a failed render is a finding either way.
+  const info = opts?.silent === true ? (_m: string): void => {} : log.info;
   let flags: DocsFlags;
   try {
     flags = parseDocsArgs(args, cwd);
@@ -211,6 +325,33 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // NEITHER a user's metadata NOR a config — there is nothing to load. It writes
   // the renderer's files under <out>/metamodel/ (default ./docs/metamodel).
   if (flags.metamodel) {
+    // `--site` builds HTML from a MODEL — docs-site's own loader and templates over the
+    // user's metadata. The metamodel surface is a different renderer entirely, over the
+    // registry, and it emits markdown; there is no renderer here to bridge them. The flag
+    // used to be parsed, accepted and then dropped by this very return: the command wrote
+    // sixteen markdown files, printed a success line and exited 0, so asking for a site
+    // produced no site and no complaint.
+    //
+    // It refuses rather than growing an HTML renderer, which would put a markdown-
+    // rendering dependency into a published package for one surface. The website renders
+    // it instead, keeping that dependency dev-only and giving the pages the metaobjects.dev
+    // look rather than the docs-site adopter theme.
+    // `--scaffold-site` is here for the same reason and was missed the first time: it is
+    // the OTHER flag that asks for files to be written, and this same early return dropped
+    // it identically — `--metamodel --scaffold-site` wrote 16 markdown pages, scaffolded no
+    // theme anywhere, and exited 0. Fixing one of a matched pair leaves the defect wearing
+    // a different flag name.
+    const dropped = [
+      ...(flags.site ? ["--site"] : []),
+      ...(flags.scaffoldSite ? ["--scaffold-site"] : []),
+    ];
+    if (dropped.length > 0) {
+      log.error(
+        `docs: ${dropped.join(" and ")} ${dropped.length > 1 ? "are" : "is"} not supported ` +
+        "with --metamodel. The metamodel reference is markdown; the rendered form is " +
+        "published at https://metaobjects.dev/reference");
+      return 2;
+    }
     return metamodelDocsCommand(cwd, flags.out);
   }
 
@@ -376,6 +517,13 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     loadedRoot: root,
     outDir,
     dbImport: "",
+    // The project's own prefix, not the "" default. `agent/ui.md` documents an ENDPOINT,
+    // and the routes generator mounts every one of them inside
+    // `fastify.register(…, { prefix: apiPrefix })` — so a project configuring "/api" is
+    // served at /api/authors and was being told, by the page whose whole job is to be
+    // right about addresses, that it was /authors. `meta gen` threads this (runner.ts);
+    // `meta docs` is the OTHER door onto the same page and did not.
+    apiPrefix: loadedConfig?.apiPrefix ?? "",
     pkMap: buildPkMap(root),
     relationMap: buildRelationMap(root),
   });
@@ -498,16 +646,46 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
       // Surfaces owned by other ports: link only, with a pointer to where they
       // get produced.
       for (const s of labeled.filter((s) => s.lang !== "ts")) {
-        log.info(
+        info(
           `meta docs: api surface '${s.lang}' (${s.subDir}) is produced by that port's docs command — run it to populate those pages.`,
         );
       }
     } else if (hasConfig) {
       // Config present but failed to load — already warned above; don't claim an
       // api surface we couldn't build.
-      log.info("meta docs: api surface skipped — metaobjects.config.ts failed to load.");
+      info("meta docs: api surface skipped — metaobjects.config.ts failed to load.");
+    } else {
+      info("meta docs: api surface skipped — no metaobjects.config.ts (nothing generated to document).");
+    }
+  }
+
+  // AGENT surface — three pages an agent reads BEFORE touching a tier (`agent/schema.md`
+  // before persistence, `agent/ui.md` before a form or grid, `agent/requirements.md`
+  // before adding a capability). The fourth file the always-on pointer names,
+  // `api/AGENT-API.md`, belongs to the api surface above.
+  //
+  // Gated on a loadable gen config exactly as `api` is, and for a stronger reason: the
+  // physical schema depends on the project's DIALECT and column-naming strategy, and the
+  // neutral model surface above runs on a placeholder because it documents no SQL at all.
+  // The dialect here is the project's own, resolved by the same default `meta gen` and
+  // `meta migrate` apply — see `buildAgentSchemaInput`.
+  if (docsCfg.surfaces.includes("agent")) {
+    if (loadedConfig !== undefined) {
+      const strategy = loadedConfig.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY;
+      const schema = buildAgentSchemaInput(root, loadedConfig.dialect, strategy);
+      emit.push(
+        ...(await agentDocsFile({
+          ...(schema !== undefined && { schema }),
+          columnNamingStrategy: strategy,
+        }).generate(ctx)),
+      );
+    } else if (hasConfig) {
+      info("meta docs: agent surface skipped — metaobjects.config.ts failed to load.");
     } else {
-      log.info("meta docs: api surface skipped — no metaobjects.config.ts (nothing generated to document).");
+      info(
+        "meta docs: agent surface skipped — no metaobjects.config.ts (the physical schema " +
+          "and the generated UI are what it describes).",
+      );
     }
   }
 
@@ -548,7 +726,15 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // did not run — the opposite of the silence the empty-ledger guard exists to produce.
   const requirementFiles = emit.filter((f) => f.path.startsWith("requirements.")).length;
   const reqSummary = requirementFiles > 0 ? `; ${requirementFiles} requirement file(s)` : "";
-  log.info(`meta docs — wrote ${modelSummary}; ${apiSummary}${reqSummary} → ${outDir}`);
+  // Same rule as the requirements line: NAMED rather than counted, and only when written.
+  // Each agent page is skipped when its tier has nothing to describe, so "3 agent pages"
+  // would leave a reader unable to tell which three — and the pages are the thing the
+  // always-on agent context points at by name.
+  const agentPages = emit
+    .filter((f) => f.path.startsWith("agent/"))
+    .map((f) => basename(f.path));
+  const agentSummary = agentPages.length > 0 ? `; agent/${agentPages.sort().join(" + agent/")}` : "";
+  info(`meta docs — wrote ${modelSummary}; ${apiSummary}${reqSummary}${agentSummary} → ${outDir}`);
   return 0;
 }
 

package/src/commands/eject.ts

@@ -0,0 +1,282 @@
+// FR-040 §4.2(a) — `meta eject <generator>` takes ownership of any reference-template
+// generator, in any package, at any time after `meta init`. ADR-0034 scaffold-and-own
+// has `init` copy five of them eagerly (entity, queries, routes, barrel, names); this is the
+// SAME copy operation, generalised to every ejectable name and callable on demand — for
+// a generator you skipped at init time, or one a package gained since.
+import { mkdir, writeFile, stat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cliVersion } from "../lib/version.js";
+import * as coreTpl from "@metaobjectsdev/codegen-ts";
+import * as reactTpl from "@metaobjectsdev/codegen-ts-react";
+import * as tanstackTpl from "@metaobjectsdev/codegen-ts-tanstack";
+import { parseEjectArgs } from "../lib/args.js";
+import { log } from "../lib/log.js";
+import { declaredDependencyNames, readPackageManifest } from "../lib/package-manifest.js";
+
+// Mirrors `OWNED_GENERATORS_DIR` in init.ts's `writeOwnedGenerators` — same directory,
+// same never-clobber-without-consent contract. Kept as its own local constant rather
+// than shared: eject is a standalone operation on ANY name, not a byproduct of init,
+// and the two call sites have no other state in common worth coupling over one string.
+const OWNED_GENERATORS_DIR = "codegen/generators";
+
+interface TemplateSource {
+  packageName: string;
+  names: readonly string[];
+  /** That package's own `src/reference/` directory. */
+  root: () => string;
+}
+
+// One registry, three packages — a package that gains templates later registers itself
+// here and `meta eject` picks it up with no other change.
+//
+// Each entry exposes its reference ROOT rather than a read function. The packages' own
+// `readReferenceTemplate` narrows its parameter to a literal union, so calling it with
+// a CLI-supplied `string` used to need a generic `asserts name is N` helper — ~20 lines
+// to re-establish, for the compiler, a fact `resolveSource` has ALREADY established at
+// runtime by selecting this entry via `names.includes(name)`. Reading from the root
+// deletes that machinery without weakening anything: membership is still checked, once,
+// where the untrusted value enters.
+const SOURCES: TemplateSource[] = [
+  {
+    packageName: "@metaobjectsdev/codegen-ts",
+    names: coreTpl.REFERENCE_GENERATOR_NAMES,
+    root: coreTpl.resolveReferenceRoot,
+  },
+  {
+    packageName: "@metaobjectsdev/codegen-ts-react",
+    names: reactTpl.REFERENCE_GENERATOR_NAMES,
+    root: reactTpl.resolveReferenceRoot,
+  },
+  {
+    packageName: "@metaobjectsdev/codegen-ts-tanstack",
+    names: tanstackTpl.REFERENCE_GENERATOR_NAMES,
+    root: tanstackTpl.resolveReferenceRoot,
+  },
+];
+
+function resolveSource(name: string): TemplateSource | undefined {
+  return SOURCES.find((s) => s.names.includes(name));
+}
+
+/** Every ejectable name, in registry order (stable — matches `meta eject --list`). */
+export function ejectableNames(): string[] {
+  return SOURCES.flatMap((s) => s.names);
+}
+
+// Every reference template's header documents its own paste-ready import line, e.g.
+// codegen-ts/src/reference/entity.ts:
+//   // Then import it LOCALLY in metaobjects.config.ts:
+//   //   import { entityFile } from "./codegen/generators/entity.js";
+// Extracting it here — rather than re-deriving an export symbol from the file name —
+// means eject can never drift from what the template itself already tells a human to
+// paste, and needs no per-name export-symbol map: a generator's exported symbol does
+// NOT follow its file name (`hooks.ts` exports `tanstackQuery`, `routes-hono.ts`
+// exports `routesFileHono`, `grid.ts` exports `tanstackGrid`).
+const HEADER_IMPORT_RE = /^\/\/\s+(import \{ \w+ \} from "\.\/codegen\/generators\/[\w.-]+\.js";)\s*$/m;
+
+/** The bound symbol out of the already-validated import line — same single source of
+ *  truth as the line itself, so the "replace this binding" message can never name a
+ *  symbol the template does not actually export. */
+function extractExportName(importLine: string, name: string): string {
+  const match = /^import \{ (\w+) \}/.exec(importLine);
+  if (!match?.[1]) {
+    throw new Error(`reference template "${name}" has an unparseable import line: ${importLine}`);
+  }
+  return match[1];
+}
+
+function extractImportLine(templateSource: string, name: string): string {
+  const match = HEADER_IMPORT_RE.exec(templateSource);
+  if (!match?.[1]) {
+    throw new Error(
+      `reference template "${name}" has no documented "// import { ... }" header line — ` +
+        "cannot report the import line to paste.",
+    );
+  }
+  return match[1];
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export interface EjectOptions {
+  cwd: string;
+  name: string;
+  /** Overwrite an already-ejected file. Without it, eject NEVER clobbers — matching
+   *  `writeOwnedGenerators`'s unconditional preserve-if-present rule in init.ts. */
+  force?: boolean;
+}
+
+export interface EjectResult {
+  path: string;
+  importLine: string;
+  /** The symbol the template exports — the binding to REPLACE in the config. */
+  exportName: string;
+  /** The package the generator currently comes from, i.e. the import to remove. */
+  packageName: string;
+  /** Advisory lines about packages the ejected file imports but the project lacks. */
+  dependencyNotes: string[];
+  status: "created" | "preserved";
+}
+
+/** The `@metaobjectsdev/*` packages an ejected template imports, read from the file
+ *  itself rather than from a per-name table — the template is the only thing that
+ *  knows, and a table would drift from it the moment a template gains an import. */
+function requiredPackages(templateSource: string): string[] {
+  const found = new Set<string>();
+  // The optional trailing group matches a SUBPATH and is deliberately not captured: what
+  // has to be installed is the package, and `@metaobjectsdev/metadata/constants` is a
+  // real, documented subpath this codebase already uses (the browser-safe pure-constants
+  // entry). Requiring the closing quote straight after the package name — as this did —
+  // made any such import match nothing at all, so a template gaining one would get no
+  // note. That is the drift this function exists to prevent, reappearing inside the
+  // function itself.
+  for (const m of templateSource.matchAll(/from\s+"(@metaobjectsdev\/[\w-]+)(?:\/[\w./-]+)?"/g)) {
+    if (m[1] !== undefined) found.add(m[1]);
+  }
+  return [...found].sort();
+}
+
+/**
+ * An ejected file is ordinary source in the adopter's repo, so its imports must be
+ * declared dependencies or their `tsc` reports TS2307 on the file we just told them
+ * they own — and under a strict (pnpm/npm) node_modules layout `meta gen` cannot
+ * resolve it either. `meta init` already calls this out by ADDING the two packages its
+ * five scaffolded generators need; the on-demand templates import two more
+ * (codegen-ts-react, codegen-ts-tanstack) that nothing declares.
+ *
+ * This REPORTS rather than edits: init is a scaffolder writing a whole project and has
+ * a manifest in hand, while eject copies one file into a repo whose dependency policy
+ * (workspace protocol, catalog, pinned ranges) is the adopter's. Naming the exact
+ * missing package and the version to match is the useful half; silently rewriting
+ * someone's manifest is not.
+ */
+export async function dependencyNotesForTemplate(cwd: string, templateSource: string): Promise<string[]> {
+  const required = requiredPackages(templateSource);
+  if (required.length === 0) return [];
+
+  const pkg = readPackageManifest(cwd);
+  if (pkg === undefined) {
+    // No readable manifest — say what the file needs and let the adopter place it.
+    return [`This file imports: ${required.join(", ")}. Make sure each is installed.`];
+  }
+  const declared = declaredDependencyNames(pkg);
+
+  const missing = required.filter((p) => !declared.has(p));
+  if (missing.length === 0) return [];
+  return [
+    `The ejected file imports ${missing.join(", ")}, which your package.json does not ` +
+    "declare — your typecheck will report TS2307 until it does. Install with:",
+    `  npm i -D ${missing.map((p) => `${p}@^${cliVersion()}`).join(" ")}`,
+  ];
+}
+
+export async function ejectGenerator(opts: EjectOptions): Promise<EjectResult> {
+  const source = resolveSource(opts.name);
+  if (source === undefined) {
+    throw new Error(
+      `unknown generator "${opts.name}". Ejectable generators: ${ejectableNames().join(", ")}. ` +
+        "Run `meta eject --list` to see them grouped by package.",
+    );
+  }
+
+  const templateSource = await readFile(join(source.root(), `${opts.name}.ts`), "utf8");
+  const importLine = extractImportLine(templateSource, opts.name);
+  const exportName = extractExportName(importLine, opts.name);
+  const rel = `${OWNED_GENERATORS_DIR}/${opts.name}.ts`;
+  const abs = join(opts.cwd, rel);
+  const notes = await dependencyNotesForTemplate(opts.cwd, templateSource);
+  const common = {
+    path: rel,
+    importLine,
+    exportName,
+    packageName: source.packageName,
+    dependencyNotes: notes,
+  };
+
+  if (!opts.force && (await fileExists(abs))) {
+    return { ...common, status: "preserved" };
+  }
+
+  await mkdir(join(opts.cwd, OWNED_GENERATORS_DIR), { recursive: true });
+  await writeFile(abs, templateSource, "utf8");
+  return { ...common, status: "created" };
+}
+
+function listOutput(): string {
+  const lines: string[] = [];
+  lines.push("Ejectable generators (copy any of these into codegen/generators/ and own it):");
+  lines.push("");
+  for (const source of SOURCES) {
+    lines.push(`${source.packageName}:`);
+    lines.push(`  ${source.names.join(", ")}`);
+    lines.push("");
+  }
+  lines.push("Run: meta eject <name>");
+  return lines.join("\n");
+}
+
+export async function ejectCommand(args: string[], cwd: string): Promise<number> {
+  let flags;
+  try {
+    flags = parseEjectArgs(args);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  if (flags.list) {
+    log.info(listOutput());
+    return 0;
+  }
+
+  if (flags.name === undefined) {
+    log.error("meta eject requires a generator name, or --list to see what's ejectable.");
+    return 2;
+  }
+
+  try {
+    const result = await ejectGenerator({ cwd, name: flags.name, force: flags.force });
+    if (result.status === "preserved") {
+      log.info(`${result.path} already exists — left untouched (pass --force to overwrite).`);
+    } else {
+      log.info(`Ejected "${flags.name}" -> ${result.path}. You own it now (ADR-0034 scaffold-and-own).`);
+    }
+    // REPLACE, never "paste". A generator reaches `generators: [...]` under ONE binding,
+    // so a reader told to "paste" gets a duplicate identifier at best — and at worst
+    // deletes nothing, keeps `formFile()` in the array bound to the PACKAGE import, and
+    // silently runs the packaged generator while editing the ejected file. That failure
+    // is invisible and is the exact one ejecting exists to prevent.
+    //
+    // But eject reads no config, so it cannot know WHICH of the three states this project
+    // is in, and stating one of them as fact is wrong in the other two — including for the
+    // five `meta init` scaffolds, whose config already imports from ./codegen/generators/,
+    // which is precisely the `meta eject <name> --force` re-sync case. Name the goal, then
+    // the three branches; the reader knows which one they are looking at.
+    log.info(`In metaobjects.config.ts, "${result.exportName}" must resolve to this file:`);
+    log.info(`  ${result.importLine}`);
+    log.info(
+      `  - If it is imported from "${result.packageName}", REPLACE that import with the ` +
+      "line above. Adding a second one leaves `generators` bound to the PACKAGED " +
+      "generator, and your edits to this file do nothing.",
+    );
+    log.info(
+      "  - If it is already imported from ./codegen/generators/ (what `meta init` " +
+      "scaffolds), it points here already — nothing to change.",
+    );
+    log.info(
+      `  - If ${result.exportName}() is not in \`generators\` yet, add the import above ` +
+      "AND the entry.",
+    );
+    for (const line of result.dependencyNotes) log.info(line);
+    return 0;
+  } catch (err) {
+    log.error((err as Error).message);
+    return 1;
+  }
+}

package/src/commands/gen.ts

@@ -9,6 +9,10 @@ import { log } from "../lib/log.js";
 import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
+import {
+  antiPatternRows, ranSection, skippedSection, warnCapped,
+  type AdvisoryFindingRow, type AdvisorySection,
+} from "../lib/advisory.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { runGen, listGenerators } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
@@ -149,12 +153,23 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     (forgeConfig.targets ? Object.values(forgeConfig.targets).map((t) => t.outDir) : [])
       .concat([forgeConfig.outDir]),
   ));
+
+  // The advisory verify-as-teacher pass now runs BEFORE the result is rendered,
+  // because its findings ride IN the result. It used to run after the payload was
+  // printed and write only to stderr as text, so `meta gen --format json` on a run
+  // with hundreds of findings emitted a document that mentioned none of them — the
+  // structured output being the documented default for an agent on a pipe.
+  // Warnings ONLY — nothing here reaches the exit code (bias to under-flagging).
+  const antiPatterns = runAntiPatternScan(
+    projectRoot, cliConfig.dryRun, flags.noAntipatterns, forgeConfig.verify?.antiPatternIgnore);
+
   const genResult = {
     files,
     outDir: targetDirs.length > 1 ? targetDirs.join(", ") : forgeConfig.outDir,
     dialect: forgeConfig.dialect,
     dryRun: cliConfig.dryRun,
     warnings: [],
+    antiPatterns,
   };
   const output =
     fmt === "toon" ? formatGenResultToon(genResult)
@@ -175,31 +190,51 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     );
   }
 
-  // Advisory verify-as-teacher pass (same as `meta verify`): on a real write run,
-  // surface authored source that hand-rolls what the metadata could model. `gen`
-  // is the command an agent always runs, so this is where the teaching actually
-  // reaches it. Warnings ONLY — never affects the exit code. Suppress with
-  // --no-antipatterns or META_NO_ANTIPATTERNS=1 (both opt-outs work on `meta gen`
-  // and `meta verify`).
-  if (!cliConfig.dryRun && !flags.noAntipatterns && process.env.META_NO_ANTIPATTERNS !== "1") {
-    try {
-      const findings = scanSourceForAntiPatterns(projectRoot);
-      if (findings.length > 0) {
-        const CAP = 10;
-        log.warn(
-          `\nmeta gen — ${findings.length} place(s) hand-roll what MetaObjects can model ` +
-            `(advisory — declaring the construct lets codegen own it):`,
-        );
-        for (const f of findings.slice(0, CAP)) log.warn(`  ${f.message}`);
-        if (findings.length > CAP) log.warn(`  …and ${findings.length - CAP} more.`);
-      }
-    } catch { /* never let an advisory scan break gen */ }
+  // The human-readable half of the advisory pass, printed after the file listing
+  // where a reader expects it. Capped for a terminal; the structured payload above
+  // already carried every finding, and the tail line says so.
+  if (antiPatterns.total > 0) {
+    log.warn(
+      `\nmeta gen — ${antiPatterns.total} place(s) hand-roll what MetaObjects can model ` +
+        `(advisory — declaring the construct lets codegen own it):`,
+    );
+    warnCapped(antiPatterns.rows.map((r) => `  ${r.message}`), flags.limit, { structured: fmt !== "text" });
   }
 
   const hasFailure = files.some((f) => f.status === "conflict" || f.status === "refused");
   return hasFailure ? 1 : 0;
 }
 
+/**
+ * Run the advisory verify-as-teacher scan (same pass `meta verify` runs): surface
+ * authored source that hand-rolls what the metadata could model. `gen` is the
+ * command an agent always runs, so this is where the teaching actually reaches it.
+ *
+ * Returns the section EITHER WAY — a skip is reported with its reason rather than
+ * dropped, so a reader can tell "found nothing" from "never looked". Warnings only;
+ * it can never affect the exit code. Suppress with --no-antipatterns or
+ * META_NO_ANTIPATTERNS=1 (both opt-outs work on `meta gen` and `meta verify`).
+ */
+function runAntiPatternScan(
+  projectRoot: string,
+  dryRun: boolean,
+  noAntipatterns: boolean,
+  ignore: readonly string[] | undefined,
+): AdvisorySection<AdvisoryFindingRow> {
+  // A --dry-run writes nothing, so it teaches nothing; the scan is skipped, as it
+  // always has been. The payload now says that instead of looking clean.
+  if (dryRun) return skippedSection("skipped on --dry-run (the advisory pass runs on a real write run)");
+  if (noAntipatterns) return skippedSection("suppressed by --no-antipatterns");
+  if (process.env.META_NO_ANTIPATTERNS === "1") return skippedSection("suppressed by META_NO_ANTIPATTERNS=1");
+  try {
+    return ranSection(antiPatternRows(scanSourceForAntiPatterns(
+      projectRoot, ignore !== undefined ? { ignore } : undefined)));
+  } catch (err) {
+    // Never let an advisory scan break gen — but never claim it found nothing either.
+    return skippedSection(`the scan failed: ${(err as Error).message}`);
+  }
+}
+
 /**
  * `meta gen --list` — print the stable-name generator registry (ADR-0021 D3).
  *