@metaobjectsdev/cli 1.0.12 → 1.1.0

package/src/commands/eject.ts

@@ -1,8 +1,9 @@
 // FR-040 §4.2(a) — `meta eject <generator>...` takes ownership of any reference-template
 // generator, in any package, at any time after `meta init`.
 //
-// Under opt-in codegen this is THE copy door: `meta init` scaffolds the layout and an
-// empty selection, so every generator an adopter runs arrives through here. It takes
+// This is the copy door, for a generator an adopter wants to CHANGE: `meta init`
+// scaffolds the layout and an empty selection, and a generator run as shipped is
+// imported from its package without coming through here (ADR-0034 Amendment 5). It takes
 // MANY names, because a real selection is several — choosing a client tier is
 // `form hooks grid` — and three separate invocations produce three separate install
 // lines for the same package. The consolidated install set is the point.
@@ -14,6 +15,7 @@
 // config-array edit has regressed across at least four filed issues). The primary
 // consumer performs two file edits and one install trivially when told exactly what
 // they are. `meta gen` plus `tsc` is the audit.
+import { existsSync } from "node:fs";
 import { mkdir, writeFile, stat, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { cliVersion } from "../lib/version.js";
@@ -24,12 +26,16 @@ import { parseEjectArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { declaredDependencyNames, readPackageManifest } from "../lib/package-manifest.js";
 import { compareOwnedCopy, type OwnedComparison } from "../lib/owned-copy.js";
-import { composeCatalog, packageOf } from "../lib/catalog.js";
-import { installSetFor, type InstallSet, type OwnedRuntimeInstall } from "../lib/install-set.js";
+import { composeCatalog, CORE_CODEGEN_PACKAGE, factoryModuleOf, packageOf } from "../lib/catalog.js";
+import { dependencyRangesOf, installSetFor, type InstallSet, type OwnedRuntimeInstall } from "../lib/install-set.js";
 import {
   ejectRuntime, ejectsRuntime, runtimeCopyStatus, runtimeDiffCommand, runtimeInstall,
   type RuntimeEjectResult, type RuntimeFileResult,
 } from "../lib/runtime-eject.js";
+import {
+  closureOf, ejectTemplates, OWNED_TEMPLATES_DIR, packagedTemplates, predatesTemplateHandOver,
+  templateCopyStatus, templateDiffCommand, type TemplateEjectResult, type TemplateFileResult,
+} from "../lib/template-eject.js";
 import { HTTP_RUNTIME_PACKAGE, OWNED_RUNTIME_DIR } from "@metaobjectsdev/codegen-ts";
 import { emitStructured, type OutputFormat } from "../lib/format.js";
 import {
@@ -37,6 +43,7 @@ import {
   type LibraryEjectResult,
 } from "../lib/library-eject.js";
 import { describeError } from "../lib/error-text.js";
+import { DOCS_SITE_NAME, ejectDocsSite, type DocsSiteFileResult } from "../lib/docs-site-eject.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
@@ -61,8 +68,6 @@ interface TemplateSource {
 // 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 CORE_CODEGEN_PACKAGE = "@metaobjectsdev/codegen-ts";
-
 const SOURCES: TemplateSource[] = [
   {
     packageName: CORE_CODEGEN_PACKAGE,
@@ -85,6 +90,7 @@ 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);
@@ -112,6 +118,19 @@ function extractExportName(importLine: string, name: string): string {
   return match[1];
 }
 
+// The CALL a template's header documents, when it is not the bare `<export>()`. A factory
+// that cannot be called without options says so where it says how to import it
+// (`//   generators: [sharedModelFile({ name, include })]`). Read from the header for the
+// reason the import line is: the template is the one thing that knows, and the catalog
+// deliberately does not derive a call from an options summary.
+const HEADER_ENTRY_RE = /^\/\/\s+generators: \[(\w+\(.*\))\],?\s*$/m;
+
+/** The call to wire: the header's, when it documents one for this template's own export. */
+function extractEntry(templateSource: string, exportName: string): string {
+  const call = HEADER_ENTRY_RE.exec(templateSource)?.[1];
+  return call !== undefined && call.startsWith(`${exportName}(`) ? call : `${exportName}()`;
+}
+
 function extractImportLine(templateSource: string, name: string): string {
   const match = HEADER_IMPORT_RE.exec(templateSource);
   if (!match?.[1]) {
@@ -144,6 +163,9 @@ export interface EjectResult {
   importLine: string;
   /** The symbol the template exports — the binding to REPLACE in the config. */
   exportName: string;
+  /** The call to wire, with any options the factory cannot be called without
+   *  (`sharedModelFile({ name, include })`), as the template's header documents it. */
+  entry: 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. */
@@ -171,6 +193,12 @@ export interface EjectResult {
    * generator whose output imports no adapter.
    */
   runtime?: RuntimeEjectResult | undefined;
+  /**
+   * ADR-0034 Amendment 8: the template modules this generator calls to write its output,
+   * copied into `codegen/templates/` so the adopter owns those too. Absent for a generator
+   * that calls none (`barrel`).
+   */
+  templates?: TemplateEjectResult | undefined;
 }
 
 /** The `@metaobjectsdev/*` packages an ejected template imports, read from the file
@@ -205,8 +233,13 @@ function requiredPackages(templateSource: string): string[] {
  * 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);
+export async function dependencyNotesForTemplate(
+  cwd: string,
+  templateSource: string,
+  /** Packages the template modules copied beside the generator import, as well. */
+  alsoImported: readonly string[] = [],
+): Promise<string[]> {
+  const required = [...new Set([...requiredPackages(templateSource), ...alsoImported.filter((p) => p.startsWith("@metaobjectsdev/"))])].sort();
   if (required.length === 0) return [];
 
   const pkg = readPackageManifest(cwd);
@@ -234,19 +267,23 @@ export async function ejectGenerator(opts: EjectOptions): Promise<EjectResult> {
     );
   }
 
-  const templateSource = await readFile(join(source.root(), `${opts.name}.ts`), "utf8");
+  // What is written is the reference with its module specifiers pointed at the project:
+  // its template modules are copied beside it (ADR-0034 Amendment 8).
+  const closure = closureOf(opts.name);
+  const templateSource = closure.generator.content;
   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 notes = await dependencyNotesForTemplate(opts.cwd, templateSource, closure.packages);
   const common = {
     path: rel,
     importLine,
     exportName,
+    entry: extractEntry(templateSource, exportName),
     packageName: source.packageName,
     dependencyNotes: notes,
-    templatePackages: requiredPackages(templateSource),
+    templatePackages: closure.packages.filter((p) => p.startsWith("@metaobjectsdev/")),
   };
 
   const existing = (await fileExists(abs)) ? await readFile(abs, "utf8") : undefined;
@@ -265,8 +302,17 @@ export async function ejectGenerator(opts: EjectOptions): Promise<EjectResult> {
     ? await ejectRuntime(opts.cwd, [opts.name], opts.force === true)
     : undefined;
 
+  // The template modules follow the same rule, for the same reason: a kept copy that predates
+  // the hand-over still imports the emit code from the package, so copying the modules beside
+  // it would be dead code in the project.
+  const keptCopyPredatesTemplates =
+    existing !== undefined && !opts.force && predatesTemplateHandOver(existing, closure);
+  const templates = closure.templates.length > 0 && !keptCopyPredatesTemplates
+    ? await ejectTemplates(opts.cwd, [closure], opts.force === true)
+    : undefined;
+
   if (!opts.force && existing !== undefined) {
-    return { ...common, status: "preserved", comparison, runtime };
+    return { ...common, status: "preserved", comparison, runtime, templates };
   }
 
   await mkdir(join(opts.cwd, OWNED_GENERATORS_DIR), { recursive: true });
@@ -276,6 +322,7 @@ export async function ejectGenerator(opts: EjectOptions): Promise<EjectResult> {
     status: existing === undefined ? "created" : "replaced",
     comparison,
     runtime,
+    templates,
   };
 }
 
@@ -314,6 +361,47 @@ export async function runtimeCopyLines(cwd: string): Promise<string[]> {
   return lines;
 }
 
+/**
+ * The owned template modules under `codegen/templates/`, file by file, against what the
+ * installed packages would write there today. Shared by `meta eject --list` and
+ * `meta gen --list`. Empty when the project owns no template copy.
+ *
+ * Only the import lines of a copy differ from the package by design, so the comparison is
+ * the one the generator copies get: `identical` says an upgrade can be taken by re-copying
+ * (`meta eject <name> --force`); `DIFFERS` says the copy is yours in a way the package is
+ * not, and names the diff that tells whose change it is.
+ */
+export async function templateCopyLines(cwd: string): Promise<string[]> {
+  if (!existsSync(join(cwd, OWNED_TEMPLATES_DIR))) return [];
+  const rows = await templateCopyStatus(cwd, packagedTemplates());
+  if (rows.length === 0) return [];
+  const lines: string[] = [
+    `Template source this project owns (${OWNED_TEMPLATES_DIR}/), against the installed codegen packages:`,
+  ];
+  const differing: string[] = [];
+  for (const r of rows) {
+    if (r.verdict === "identical") lines.push(`  ${r.path}  [identical to the package]`);
+    else if (r.verdict === "reformatted") lines.push(`  ${r.path}  [same content as the package, your formatting]`);
+    else if (r.verdict === "not-in-package") lines.push(`  ${r.path}  [not in the package — yours, or removed upstream]`);
+    else {
+      const diff = templateDiffCommand(r);
+      if (diff !== undefined) differing.push(diff);
+      lines.push(
+        `  ${r.path}  [DIFFERS: ${r.referenceOnly} line(s) only in the package, ${r.localOnly} line(s) only in yours]`,
+      );
+    }
+  }
+  if (differing.length > 0) {
+    lines.push(
+      "  See the difference (upstream fix, or your own?) before taking an upgrade. " +
+        "Only the import lines of a copy differ from the package by design:",
+    );
+    for (const d of differing) lines.push(`    ${d}`);
+  }
+  lines.push("");
+  return lines;
+}
+
 /**
  * `--list` doubles as the staleness report for what this project ALREADY owns.
  *
@@ -323,38 +411,120 @@ export async function runtimeCopyLines(cwd: string): Promise<string[]> {
  * gate green. Marking each owned copy `identical` / `differs` makes it a one-command
  * answer instead of a diff nobody thinks to run.
  */
-async function listOutput(cwd: string): Promise<string> {
-  const lines: string[] = [];
-  lines.push("Ejectable generators (copy any of these into codegen/generators/ and own it):");
-  lines.push("");
-  let anyStale = false;
+/** One reference generator as `--list` reports it: is a copy owned, and how far it moved. */
+interface GeneratorListRow {
+  name: string;
+  package: string;
+  /** `available` = not ejected; `owned` = ejected but the reference could not be read. */
+  status: "available" | "owned" | "identical" | "reformatted" | "differs";
+  /** Lines behind / of your own in the GENERATOR file alone. */
+  behind: number;
+  own: number;
+  /**
+   * The renderers this generator owns under `codegen/templates/` (those it imports that
+   * exist in the project), each against the installed package. A generator is `identical`
+   * only when its file AND every one of these is; `status` is `differs` when any differs.
+   * Absent when the project owns none of its renderers.
+   */
+  templates?: GeneratorTemplateRow[];
+}
+
+interface GeneratorTemplateRow {
+  path: string;
+  status: "identical" | "reformatted" | "differs";
+  behind: number;
+  own: number;
+}
+
+/** One `SOURCES` entry and the rows walked for it — the grouping the text list prints. */
+interface GeneratorListGroup {
+  packageName: string;
+  rows: GeneratorListRow[];
+}
+
+async function generatorListGroups(cwd: string): Promise<GeneratorListGroup[]> {
+  const groups: GeneratorListGroup[] = [];
+  // Every renderer the project holds, against the package: attributed to a generator by what
+  // that generator imports, so a renderer another generator owns never flags this one.
+  const templateStatus = await templateCopyStatus(cwd, packagedTemplates());
   for (const source of SOURCES) {
-    lines.push(`${source.packageName}:`);
+    const rows: GeneratorListRow[] = [];
+    groups.push({ packageName: source.packageName, rows });
     for (const name of source.names) {
+      const row: GeneratorListRow = { name, package: source.packageName, status: "available", behind: 0, own: 0 };
+      rows.push(row);
       const abs = join(cwd, OWNED_GENERATORS_DIR, `${name}.ts`);
-      if (!(await fileExists(abs))) {
-        lines.push(`  ${name}`);
-        continue;
-      }
+      if (!(await fileExists(abs))) continue;
       let ref: string;
       try {
-        ref = await readFile(join(source.root(), `${name}.ts`), "utf8");
+        ref = closureOf(name).generator.content;
       } catch {
-        lines.push(`  ${name}  [owned]`);
+        row.status = "owned";
         continue;
       }
-      const owned = await readFile(abs, "utf8");
-      const cmp = await compareOwnedCopy(owned, ref);
-      if (cmp.verdict === "identical") {
-        lines.push(`  ${name}  [owned — identical to the reference]`);
-      } else if (cmp.verdict === "reformatted") {
-        lines.push(`  ${name}  [owned — same content as the reference, your formatting]`);
+      const cmp = await compareOwnedCopy(await readFile(abs, "utf8"), ref);
+      if (cmp.verdict === "identical" || cmp.verdict === "reformatted") {
+        row.status = cmp.verdict;
       } else {
-        anyStale = true;
+        row.status = "differs";
+        row.behind = cmp.referenceOnly;
+        row.own = cmp.localOnly;
+      }
+      const reached = new Set(closureOf(name).templates.map((f) => f.path));
+      const renderers: GeneratorTemplateRow[] = [];
+      for (const t of templateStatus) {
+        if (!reached.has(t.path) || t.verdict === "not-in-package") continue;
+        renderers.push({
+          path: t.path,
+          status: t.verdict === "identical" || t.verdict === "reformatted" ? t.verdict : "differs",
+          behind: t.referenceOnly,
+          own: t.localOnly,
+        });
+      }
+      if (renderers.length > 0) row.templates = renderers;
+      if (renderers.some((r) => r.status === "differs")) row.status = "differs";
+    }
+  }
+  return groups;
+}
+
+/** `--list` as one structured document: the generators and the shipped libraries. */
+async function listData(cwd: string): Promise<Record<string, unknown>> {
+  const generators = (await generatorListGroups(cwd)).flatMap((g) => g.rows);
+  return {
+    generators,
+    libraries: ejectableLibraryNames(),
+    help: [
+      "run `meta eject <name>...` to copy a generator into codegen/generators/ and own it",
+      "`meta eject --list --format text` also reports owned runtime copies and ejected-library drift",
+    ],
+  };
+}
+
+async function listOutput(cwd: string): Promise<string> {
+  const lines: string[] = [];
+  lines.push("Ejectable generators (copy any of these into codegen/generators/ and own it):");
+  lines.push("");
+  const groups = await generatorListGroups(cwd);
+  const anyStale = groups.some((g) => g.rows.some((r) => r.status === "differs"));
+  const generatorFileDiffers = (r: GeneratorListRow): boolean => r.behind > 0 || r.own > 0;
+  for (const group of groups) {
+    lines.push(`${group.packageName}:`);
+    for (const r of group.rows) {
+      if (r.status === "available") lines.push(`  ${r.name}`);
+      else if (r.status === "owned") lines.push(`  ${r.name}  [owned]`);
+      else if (r.status === "identical") lines.push(`  ${r.name}  [owned — identical to the reference]`);
+      else if (r.status === "reformatted") lines.push(`  ${r.name}  [owned — same content as the reference, your formatting]`);
+      else {
+        const differing = (r.templates ?? []).filter((t) => t.status === "differs");
         lines.push(
-          `  ${name}  [owned — DIFFERS: ${cmp.referenceOnly} line(s) behind, ` +
-            `${cmp.localOnly} line(s) of your own]`,
+          generatorFileDiffers(r)
+            ? `  ${r.name}  [owned — DIFFERS: ${r.behind} line(s) behind, ${r.own} line(s) of your own]`
+            : `  ${r.name}  [owned — DIFFERS: generator identical, ${differing.length} renderer(s) differ]`,
         );
+        for (const t of differing) {
+          lines.push(`    renderer ${t.path}  [DIFFERS: ${t.behind} line(s) behind, ${t.own} line(s) of your own]`);
+        }
       }
     }
     lines.push("");
@@ -376,6 +546,12 @@ async function listOutput(cwd: string): Promise<string> {
     lines.push("");
   }
   lines.push(...(await runtimeCopyLines(cwd)));
+  lines.push(...(await templateCopyLines(cwd)));
+  // The docs site's theme: not a generator copy (its builder stays packaged), but a name
+  // `meta eject` takes all the same.
+  lines.push("The docs site's theme (its templates and assets, into codegen/docs-site/):");
+  lines.push(`  ${DOCS_SITE_NAME}`);
+  lines.push("");
   // FR-043 — the shipped libraries, and how far this project's copies have drifted.
   lines.push("Shipped libraries (copy one into your own sources and own it):");
   for (const name of ejectableLibraryNames()) lines.push(`  ${name}`);
@@ -422,16 +598,28 @@ async function listOutput(cwd: string): Promise<string> {
 // the command
 // ---------------------------------------------------------------------------
 
+/**
+ * The entry an ejected generator is wired by. Every generator, documentation included, goes
+ * in the top-level `generators` and is run by `meta gen` (ADR-0034 Amendment 9).
+ */
+interface EjectWiring {
+  /** The call, with the options the factory cannot be called without. */
+  entry: string;
+}
+
 /** One row of the `--format json` payload. */
 interface EjectedRow {
   name: string;
   path: string;
   status: EjectResult["status"];
-  /** The two edits an adopter makes in `metaobjects.config.ts`. */
+  /** The two edits an adopter makes in `metaobjects.config.ts`: the import, and the entry in
+   *  `generators`. */
   wire: { import: string; entry: string };
   requires: readonly string[];
   /** The adapter source copied beside it (ADR-0034 Amendment 3). Absent when none. */
   runtime?: RuntimeFileResult[];
+  /** The template modules copied beside it (ADR-0034 Amendment 8). Absent when none. */
+  templates?: TemplateFileResult[];
 }
 
 interface EjectPayload {
@@ -441,6 +629,22 @@ interface EjectPayload {
   config: { keys: string[] };
   /** FR-043 — libraries ejected in this call. Absent when none were. */
   libraries?: LibraryEjectResult[];
+  /** `meta eject docs-site`: the site's templates and assets. Absent when not asked for. */
+  docsSite?: DocsSiteFileResult[];
+}
+
+/** The text report for `meta eject docs-site`. */
+function reportDocsSite(files: readonly DocsSiteFileResult[]): void {
+  const written = files.filter((f) => f.status !== "preserved").length;
+  log.info(
+    `Ejected the docs-site theme -> codegen/docs-site/: ${written} file(s) written, ` +
+      `${files.length - written} already there and kept (--force replaces them).`,
+  );
+  log.info(
+    "  docsSiteFile() reads these in place of the bundled templates and assets; edit them to own " +
+      "the site's look. The site builder stays in the package. Wire the generator, if you have " +
+      "not: `docsSiteFile()` in `generators`, with a `docs` target.",
+  );
 }
 
 /** The text report for one ejected library. */
@@ -486,20 +690,14 @@ function reportLibrary(result: LibraryEjectResult): void {
  * already-copied half as "preserved" and the adopter cannot tell what happened.
  * Returns the unknown names, or an empty array.
  */
-/** Where a package-only generator's factory is imported from. The core package serves
- *  its generator factories from the `/generators` subpath; the UI packages from the root. */
-function packageFactoryPath(name: string): string {
-  const pkg = packageOf(name) ?? "";
-  return pkg === CORE_CODEGEN_PACKAGE ? `${pkg}/generators` : pkg;
-}
 
 function unknownNames(names: readonly string[]): string[] {
-  return names.filter((n) => resolveSource(n) === undefined && !isLibraryName(n));
+  return names.filter((n) => resolveSource(n) === undefined && !isLibraryName(n) && n !== DOCS_SITE_NAME);
 }
 
 /** Print the per-name text report — every branch below predates this command taking
  *  more than one name, and each was written against a real incident. */
-function reportOne(result: EjectResult, name: string): void {
+function reportOne(result: EjectResult, name: string, wiring: EjectWiring): void {
   if (result.status === "preserved") {
     // "already exists — left untouched" was the whole message, and it answered the
     // question nobody has. What an owner needs to know is whether their copy still
@@ -534,6 +732,7 @@ function reportOne(result: EjectResult, name: string): void {
           "See which, before deciding:",
       );
       log.info(`    diff -u node_modules/${result.packageName}/src/reference/${name}.ts ${result.path}`);
+      log.info("  (A copy differs from the reference in its import lines by design: they point at your project.)");
       log.info(
         "  To take upstream changes AND keep your customization, three-way merge them — " +
           "`git merge-file --diff3 <your copy> <the reference you ejected from> <the reference above>`. " +
@@ -556,32 +755,61 @@ function reportOne(result: EjectResult, name: string): void {
     log.info(`Ejected "${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. 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/, it points here already " +
-    "— nothing to change.",
-  );
-  log.info(
-    `  - If ${result.exportName}() is not in \`generators\` yet, add the import above ` +
-    "AND the entry.",
-  );
+  {
+    // 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. 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 "${factoryModuleOf(name) ?? 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/, it points here already " +
+      "— nothing to change.",
+    );
+    log.info(
+      `  - If ${wiring.entry} is not in \`generators\` yet, add the import above ` +
+      "AND the entry.",
+    );
+  }
   for (const line of result.dependencyNotes) log.info(line);
   if (result.runtime !== undefined && result.runtime.files.length > 0) reportRuntime(result.runtime.files);
+  if (result.templates !== undefined && result.templates.files.length > 0) reportTemplates(result.templates.files);
+}
+
+/** What the template copy handed over, and how the owned generator reaches it. */
+function reportTemplates(files: readonly TemplateFileResult[]): void {
+  const written = files.filter((f) => f.status !== "preserved");
+  // A kept file that already matches the package is not news (ejecting `entity queries` copies
+  // the shared validators once, then finds them) — only a kept file that differs is.
+  const kept = files.filter((f) => f.status === "preserved" && f.comparison?.verdict !== "identical");
+  log.info(
+    `The code this generator calls to write its output is yours too: its template modules are in ` +
+      `${OWNED_TEMPLATES_DIR}/, not in the codegen package. What stays in the package is the engine ` +
+      "(the generator base, the model walks, the naming and type-mapping tables).",
+  );
+  if (written.length > 0) {
+    log.info(
+      `  Copied ${written.length} file(s) into ${OWNED_TEMPLATES_DIR}/ (from the installed package; only their import lines differ).`,
+    );
+  }
+  const keptDiffering = kept.filter((f) => f.comparison?.verdict === "differs");
+  if (kept.length > 0) {
+    log.info(
+      `  ${kept.length} file(s) were already there and were left untouched` +
+        (keptDiffering.length > 0 ? `, ${keptDiffering.length} of them differing from the package` : "") +
+        " (--force replaces them). `meta eject --list` compares each one.",
+    );
+  }
 }
 
 /** What the adapter copy handed over, and how the emitted code reaches it. */
@@ -624,7 +852,8 @@ export async function ejectCommand(
   }
 
   if (flags.list) {
-    log.info(await listOutput(cwd));
+    if (fmt === "text") log.info(await listOutput(cwd));
+    else emitStructured(await listData(cwd), fmt);
     return 0;
   }
 
@@ -645,7 +874,7 @@ export async function ejectCommand(
   const unknown = unmatched.filter((n) => packageOf(n) === undefined);
   if (packageOnly.length > 0) {
     log.error(
-      `package-only generator(s): ${packageOnly.map((n) => `${n} (${packageFactoryPath(n)})`).join(", ")}. ` +
+      `package-only generator(s): ${packageOnly.map((n) => `${n} (${factoryModuleOf(n) ?? ""})`).join(", ")}. ` +
         "No reference template ships for them, so they cannot be ejected: import the factory " +
         "from the package named beside each one and wire it in `generators: [...]`. " +
         "Nothing was ejected.",
@@ -665,11 +894,20 @@ export async function ejectCommand(
   const rows: EjectedRow[] = [];
   const libraries: LibraryEjectResult[] = [];
   const templatePackages = new Set<string>();
+  // Packages OUTSIDE @metaobjectsdev that the copied template modules import (a Markdown/TOON
+  // writer, say): read from the codegen package that ships them, never restated here.
+  const templateThirdParty = new Map<string, string | undefined>();
   // ADR-0034 Amendment 3: the generators whose adapter source was copied, and what it imports.
   const runtimeGenerators = new Set<string>();
   const runtimePackages = new Set<string>();
+  let docsSite: DocsSiteFileResult[] | undefined;
   try {
     for (const name of flags.names) {
+      if (name === DOCS_SITE_NAME) {
+        docsSite = await ejectDocsSite(cwd, flags.force);
+        if (fmt === "text") reportDocsSite(docsSite);
+        continue;
+      }
       if (isLibraryName(name)) {
         const lib = await ejectLibrary({ cwd, name, force: flags.force });
         libraries.push(lib);
@@ -678,19 +916,25 @@ export async function ejectCommand(
       }
       const result = await ejectGenerator({ cwd, name, force: flags.force });
       for (const p of result.templatePackages) templatePackages.add(p);
+      for (const p of closureOf(name).packages.filter((q) => !q.startsWith("@metaobjectsdev/"))) {
+        templateThirdParty.set(p, dependencyRangesOf(CORE_CODEGEN_PACKAGE)[p]);
+      }
       if (result.runtime !== undefined) {
         runtimeGenerators.add(name);
         for (const p of result.runtime.packages) runtimePackages.add(p);
       }
+      const catalogEntry = catalog[name];
+      const wiring: EjectWiring = { entry: result.entry };
       rows.push({
         name,
         path: result.path,
         status: result.status,
-        wire: { import: result.importLine, entry: `${result.exportName}()` },
-        requires: catalog[name]?.requires ?? [],
+        wire: { import: result.importLine, entry: wiring.entry },
+        requires: catalogEntry?.requires ?? [],
         ...(result.runtime !== undefined ? { runtime: result.runtime.files } : {}),
+        ...(result.templates !== undefined ? { templates: result.templates.files } : {}),
       });
-      if (fmt === "text") reportOne(result, name);
+      if (fmt === "text") reportOne(result, name, wiring);
     }
   } catch (err) {
     log.error(describeError(err));
@@ -705,7 +949,7 @@ export async function ejectCommand(
   // names, so a summary built from the catalog alone printed a line that omitted a
   // package each per-file note had just asked for.
   const entries = flags.names
-    .filter((n) => !isLibraryName(n))
+    .filter((n) => !isLibraryName(n) && n !== DOCS_SITE_NAME)
     .map((n) => catalog[n])
     .filter((e) => e !== undefined);
   // The copied adapter source imports its own dependencies (qs, the framework, the core
@@ -716,7 +960,7 @@ export async function ejectCommand(
     const { runtime, dev } = runtimeInstall([...runtimePackages]);
     ownedRuntime = { generators: runtimeGenerators, runtime, dev };
   }
-  const install = installSetFor(entries, [...templatePackages], ownedRuntime);
+  const install = installSetFor(entries, [...templatePackages], ownedRuntime, templateThirdParty);
   const configKeys = [...new Set(entries.flatMap((e) => e.configKeys ?? []))].sort();
 
   if (fmt === "text") {
@@ -749,6 +993,7 @@ export async function ejectCommand(
       install,
       config: { keys: configKeys },
       ...(libraries.length > 0 ? { libraries } : {}),
+      ...(docsSite !== undefined ? { docsSite } : {}),
     };
     emitStructured(payload, fmt);
   }