@metaobjectsdev/cli 1.0.2 → 1.0.4-rc.1

package/src/lib/install-set.ts

@@ -0,0 +1,116 @@
+// What a catalog entry costs to install — the one derivation behind both
+// `meta gen --list --format json` and `meta eject --format json`.
+//
+// Two kinds of package, resolved two different ways:
+//
+//   dev      the `@metaobjectsdev/codegen-*` package the generator lives in. Its range
+//            is the CLI's own version: the engine and the CLI ship in lockstep, so a
+//            generator from a different minor is a version mismatch, not a choice.
+//   runtime  the `@metaobjectsdev` runtime the EMITTED code imports, plus the
+//            third-party packages it imports. The runtime's range is the CLI's version
+//            for the same reason; the third-party RANGES are read from that runtime
+//            package's own `peerDependencies` and are never written here.
+//
+// That last rule is the point of this module. A second copy of a peer range in the CLI
+// is a second thing to keep in step, and the failure mode of drift is an adopter
+// installing a major nothing was tested against — the ERESOLVE trap FR-040 §4.4
+// documented, closed by construction rather than by a warning. If a range cannot be
+// read, the package is reported WITHOUT one rather than guessed at.
+
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { GeneratorRegistryEntry } from "@metaobjectsdev/codegen-ts";
+import { cliVersion } from "./version.js";
+import { packageOf } from "./catalog.js";
+import type { PackageManifest } from "./package-manifest.js";
+
+/**
+ * A package's declared peer ranges, or `{}` if they cannot be read.
+ *
+ * Resolves the package's ENTRY and walks up to the nearest manifest, rather than asking
+ * for `"<pkg>/package.json"` directly. The direct form is the obvious one and it is
+ * WRONG: a package's `exports` map gates every subpath, and `@metaobjectsdev/runtime-ts`
+ * exports `.` / `./drivers` / `./fastify` / `./drizzle-fastify` / `./hono` and no
+ * `./package.json`, so under real Node it throws ERR_PACKAGE_PATH_NOT_EXPORTED. It
+ * appeared to work in-repo only because bun resolves a symlinked source tree; against
+ * the published package it failed silently on the first try. Resolving the entry is
+ * never gated — `.` is the one subpath every package exports.
+ */
+export function peerRangesOf(packageName: string): Record<string, string> {
+  try {
+    const req = createRequire(import.meta.url);
+    let dir = dirname(req.resolve(packageName));
+    // The entry sits under dist/; the manifest is at the package root above it.
+    for (let hops = 0; hops < 8; hops++) {
+      const candidate = join(dir, "package.json");
+      if (existsSync(candidate)) {
+        const manifest = JSON.parse(readFileSync(candidate, "utf8")) as PackageManifest & {
+          name?: string;
+        };
+        // Guard against stopping at a nested manifest that is not the package itself.
+        if (manifest.name === packageName) {
+          return (manifest.peerDependencies ?? {}) as Record<string, string>;
+        }
+      }
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+export interface InstallSet {
+  /** Build-time packages, `name@range`. */
+  dev: string[];
+  /** Application-runtime packages, `name@range` (or bare `name` if no range is known). */
+  runtime: string[];
+  /** A paste-ready shell line, or "" when there is nothing to install. */
+  command: string;
+}
+
+function spec(name: string, range: string | undefined): string {
+  return range === undefined ? name : `${name}@${range}`;
+}
+
+/**
+ * The consolidated install set for a group of catalog entries.
+ *
+ * Consolidated, not per-entry: ejecting `hooks` and `grid` needs
+ * `@metaobjectsdev/codegen-ts-tanstack` ONCE, and an adopter handed the same package
+ * twice reasonably wonders which one to run.
+ */
+export function installSetFor(entries: readonly GeneratorRegistryEntry[]): InstallSet {
+  const version = cliVersion();
+  const dev = new Set<string>();
+  const runtime = new Set<string>();
+
+  for (const entry of entries) {
+    const pkg = packageOf(entry.name);
+    if (pkg !== undefined) dev.add(spec(pkg, `^${version}`));
+
+    for (const rt of entry.runtimePackages ?? []) runtime.add(spec(rt, `^${version}`));
+
+    if (entry.runtimePeers !== undefined && entry.runtimePeers.length > 0) {
+      // Ranges come from whichever runtime package declares these as peers — the union
+      // over this generator's runtimes, since a generator emitting against two of them
+      // may take a peer from either. A generator with third-party peers but no runtime
+      // package of its own has none to read, so its peers are named UNPINNED: honest,
+      // and better than a made-up bound.
+      const ranges: Record<string, string> = {};
+      for (const rt of entry.runtimePackages ?? []) Object.assign(ranges, peerRangesOf(rt));
+      for (const peer of entry.runtimePeers) runtime.add(spec(peer, ranges[peer]));
+    }
+  }
+
+  const devList = [...dev].sort();
+  const runtimeList = [...runtime].sort();
+  const parts: string[] = [];
+  if (devList.length > 0) parts.push(`npm i -D ${devList.join(" ")}`);
+  if (runtimeList.length > 0) parts.push(`npm i ${runtimeList.join(" ")}`);
+
+  return { dev: devList, runtime: runtimeList, command: parts.join(" && ") };
+}

package/src/lib/library-eject.ts

@@ -0,0 +1,298 @@
+// `meta eject <library>` — FR-043 §3.4, the copy door for a shipped library's METADATA.
+//
+// ADR-0034 ruled that a reference GENERATOR is copied into the adopter's repo because
+// the adopter owns their code. §3.4 extends the same ruling to declared design, and
+// makes it the EXPECTED mode rather than the fallback: a library is first a reference —
+// something to copy, rename, and cut down. Using one in place, tracking upstream, is the
+// deliberate minority choice.
+//
+// Two things follow, and both are here rather than in the generator path:
+//
+//   The destination is `Collection.sourceRoots[0]` — the project's first DECLARED
+//   source root, resolved through `resolveCollection()`. Never `metaobjects/`: that
+//   string is the default value of `sources` and nothing else (CLAUDE.md names the five
+//   sites allowed to spell it, and this is not one of them).
+//
+//   Every file carries a provenance header. It is what makes the copy's origin legible
+//   a year later, what `--list` reads to report staleness against the shipped tree, and
+//   what carries the ONE instruction that makes the eject complete: remove the library
+//   from `libraries`, or both trees load and merge (ERR_LIBRARY_PACKAGE_COLLISION).
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { MetaDataLoader, PACKAGE_SEPARATOR, canonicalSerialize, type MetaData } from "@metaobjectsdev/metadata";
+import {
+  libraryManifests, libraryRefSource, libraryRefs, librarySources,
+  knownLibraryTokens, splitLayerToken,
+} from "@metaobjectsdev/metadata/library";
+import { resolveCollection } from "@metaobjectsdev/sdk";
+import { cliVersion } from "./version.js";
+
+/** The first line of every ejected file — the marker `--list` scans for. */
+export const EJECT_MARKER = "# meta-eject:";
+
+/** True when `name` is a shipped library rather than a generator. */
+export function isLibraryName(name: string): boolean {
+  return name in libraryManifests();
+}
+
+/** Every shipped library name, sorted. */
+export function ejectableLibraryNames(): string[] {
+  return Object.keys(libraryManifests()).sort();
+}
+
+/**
+ * Where an ejected ref lands: `meta.<library>.<file>.yaml`.
+ *
+ * Not the library's own basename. `model.yaml` / `db.yaml` / `requirements.yaml` are
+ * meaningful inside `library/iam/` and meaningless in a directory holding an
+ * application's whole model — and three libraries ejected into one root would collide
+ * outright. The `meta.<concept>.<...>` shape is the file-naming convention this project
+ * documents.
+ */
+export function ejectedFileName(library: string, ref: string): string {
+  return `meta.${library}.${basename(ref)}.yaml`;
+}
+
+function header(library: string, ref: string): string {
+  return [
+    `${EJECT_MARKER} library=${library} ref=${ref} cli=${cliVersion()}`,
+    `# Copied from the MetaObjects shipped library "${library}". YOU OWN THIS FILE: rename`,
+    `# the package, delete what you do not need, change anything. Nothing regenerates it,`,
+    `# and no gate compares it to the shipped tree except \`meta eject --list\`.`,
+    `#`,
+    `# ONE STEP REMAINS: remove "${library}" (and any "${library}/<layer>") from`,
+    `# \`libraries\` in .metaobjects/config.json. Left there, the shipped tree and this`,
+    `# copy BOTH load and merge — additions take effect and deletions do not, because the`,
+    `# library still declares what you removed. The loader refuses that outright`,
+    `# (ERR_LIBRARY_PACKAGE_COLLISION) rather than letting it run.`,
+    "",
+  ].join("\n");
+}
+
+export interface EjectedLibraryFile {
+  ref: string;
+  /** Path relative to the project root. */
+  path: string;
+  status: "created" | "preserved" | "replaced";
+}
+
+export interface LibraryEjectResult {
+  library: string;
+  /** Absolute destination directory. */
+  root: string;
+  files: EjectedLibraryFile[];
+  /** The tokens for this library the project currently declares — what to remove. */
+  stillOptedIn: readonly string[];
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export async function ejectLibrary(opts: {
+  cwd: string;
+  name: string;
+  force?: boolean;
+}): Promise<LibraryEjectResult> {
+  const manifest = libraryManifests()[opts.name];
+  if (manifest === undefined) {
+    throw new Error(
+      `unknown library "${opts.name}". Shipped libraries: ${ejectableLibraryNames().join(", ")}.`,
+    );
+  }
+  const collection = await resolveCollection(opts.cwd);
+  const root = collection.sourceRoots[0];
+  if (root === undefined) {
+    throw new Error(
+      `this project declares no metadata source root, so there is nowhere to put ` +
+        `"${opts.name}". Declare "sources" in .metaobjects/config.json, or run 'meta init'.`,
+    );
+  }
+
+  await mkdir(root, { recursive: true });
+  const files: EjectedLibraryFile[] = [];
+  for (const ref of libraryRefs(opts.name)) {
+    const text = header(opts.name, ref) + (await libraryRefSource(ref).read());
+    const name = ejectedFileName(opts.name, ref);
+    const abs = join(root, name);
+    const existed = await fileExists(abs);
+    if (existed && opts.force !== true) {
+      files.push({ ref, path: name, status: "preserved" });
+      continue;
+    }
+    await writeFile(abs, text, "utf8");
+    files.push({ ref, path: name, status: existed ? "replaced" : "created" });
+  }
+
+  return {
+    library: opts.name,
+    root,
+    files,
+    stillOptedIn: collection.libraries.filter((t) => splitLayerToken(t)[0] === opts.name),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// staleness — `meta eject --list`
+// ---------------------------------------------------------------------------
+
+export interface LibraryStaleness {
+  library: string;
+  /** Files in this project carrying the eject marker for this library. */
+  files: string[];
+  verdict: "identical" | "differs" | "unreadable";
+  /** Nodes present in both whose own-mode serialization differs. */
+  changed: number;
+  /** Nodes the SHIPPED tree has that the ejected copy does not — upstream moved. */
+  upstreamOnly: number;
+  /** Nodes the ejected copy has that the shipped tree does not — your additions. */
+  localOnly: number;
+  /** Why the comparison could not be made, when `verdict` is "unreadable". */
+  reason?: string;
+  /** Still named in `libraries` — the ejection is not finished. */
+  stillOptedIn: boolean;
+}
+
+/** The longest package prefix every node shares — the library's own root package.
+ *
+ *  Segment-wise, never by string prefix: `acme::identity` and `acme::identityhub` share
+ *  six characters and no package at all. */
+function commonPackagePrefix(packages: readonly string[]): string {
+  if (packages.length === 0) return "";
+  let common = packages[0]!.split(PACKAGE_SEPARATOR);
+  for (const pkg of packages.slice(1)) {
+    const segments = pkg.split(PACKAGE_SEPARATOR);
+    let i = 0;
+    while (i < common.length && i < segments.length && common[i] === segments[i]) i++;
+    common = common.slice(0, i);
+  }
+  return common.join(PACKAGE_SEPARATOR);
+}
+
+/** Root-level nodes keyed by their package path RELATIVE to the library's own root
+ *  package, canonically serialized in OWN mode.
+ *
+ *  Relative rather than by resolution key, because §3.4 says an adopter who ejects "may
+ *  rename the package freely" — keying on the FQN would report every node of a renamed
+ *  copy as both upstream-only and local-only, which is the least useful answer
+ *  available. Relative rather than by BARE NAME, because a library free to use two
+ *  packages is free to declare `User` in both, and one key for two declarations means
+ *  the one serialized last silently wins: a real divergence in the other is reported as
+ *  `identical`. The relative path is what survives the rename — moving the root leaves
+ *  every suffix below it exactly where it was — so it distinguishes without giving that
+ *  edit anything to catch on. A single-package library yields the bare names it always
+ *  did. Own mode, because the question is what each file DECLARES; the effective tree
+ *  would fold a shipped base's fields into a subtype and report a difference that is not
+ *  in either file. */
+export function ownNodesByName(root: MetaData): Map<string, string> {
+  const nodes = [...root.children()];
+  const packageOf = (node: MetaData) => node.package ?? node.fileDefaultPackage ?? "";
+  // The ROOT package, neutralized in every node's serialization — for the same reason
+  // the keying is relative to it. A rename reaches the `package` key AND every `extends`
+  // inside the node, so comparing the raw text would report a renamed copy as wholly
+  // changed: the loudest possible answer to the one edit §3.4 explicitly invites. The
+  // root rather than each node's own package, so that a deeper node's reference back up
+  // to the root package is neutralized in it too.
+  const rootPackage = commonPackagePrefix(nodes.map(packageOf));
+
+  const out = new Map<string, string>();
+  for (const node of nodes) {
+    const pkg = packageOf(node);
+    const suffix =
+      rootPackage === "" ? pkg
+      : pkg === rootPackage ? ""
+      : pkg.slice(rootPackage.length + PACKAGE_SEPARATOR.length);
+    const key = suffix === "" ? node.name : `${suffix}${PACKAGE_SEPARATOR}${node.name}`;
+    const text = canonicalSerialize(node);
+    out.set(key, rootPackage === "" ? text : text.replaceAll(rootPackage, "<package>"));
+  }
+  return out;
+}
+
+/** Every project file carrying an eject marker, grouped by library. */
+async function ejectedFilesByLibrary(files: readonly string[]): Promise<Map<string, string[]>> {
+  const out = new Map<string, string[]>();
+  for (const file of files) {
+    let head: string;
+    try {
+      head = (await readFile(file, "utf8")).slice(0, 400);
+    } catch {
+      continue;
+    }
+    const match = new RegExp(`^${EJECT_MARKER} library=(\\S+)`, "m").exec(head);
+    const library = match?.[1];
+    if (library === undefined) continue;
+    out.set(library, [...(out.get(library) ?? []), file]);
+  }
+  return out;
+}
+
+/**
+ * Per-library staleness for the copies THIS project owns.
+ *
+ * The same gap `--list` closes for generators, one level up: an ejected copy can sit any
+ * number of releases behind the tree it came from and nothing compares the two. The
+ * comparison is structural, through the canonical serializer, so re-indentation and key
+ * order never show up — the only thing that can be reported is a declaration that
+ * actually changed.
+ */
+export async function libraryStaleness(cwd: string): Promise<LibraryStaleness[]> {
+  let collection;
+  try {
+    collection = await resolveCollection(cwd);
+  } catch {
+    return []; // no project — nothing is ejected here
+  }
+  const byLibrary = await ejectedFilesByLibrary(collection.ownFiles);
+  const selected = new Set(collection.libraries.map((t) => splitLayerToken(t)[0]));
+
+  const rows: LibraryStaleness[] = [];
+  for (const [library, files] of [...byLibrary].sort(([a], [b]) => a.localeCompare(b))) {
+    const row: LibraryStaleness = {
+      library,
+      files: files.map((f) => f.slice(cwd.length + 1)),
+      verdict: "identical",
+      changed: 0,
+      upstreamOnly: 0,
+      localOnly: 0,
+      stillOptedIn: selected.has(library),
+    };
+    if (!(library in libraryManifests())) {
+      rows.push({ ...row, verdict: "unreadable", reason: `this build ships no library "${library}"` });
+      continue;
+    }
+
+    // Both trees WHOLE, never file by file: a db layer is nothing but `overlay: true`
+    // redeclarations, so loading one alone is ERR_OVERLAY_NO_TARGET by construction.
+    const tokens = knownLibraryTokens().filter((t) => splitLayerToken(t)[0] === library);
+    const shipped = await new MetaDataLoader({ strict: true }).load(librarySources(tokens));
+    const { FileSource } = await import("@metaobjectsdev/metadata/core");
+    const local = await new MetaDataLoader({ strict: true }).load(
+      files.map((f) => new FileSource(f)),
+    );
+    if (local.errors.length > 0) {
+      rows.push({
+        ...row,
+        verdict: "unreadable",
+        reason: `the ejected copy does not load on its own: ${local.errors[0]!.message}`,
+      });
+      continue;
+    }
+
+    const up = ownNodesByName(shipped.root);
+    const mine = ownNodesByName(local.root);
+    for (const [name, text] of up) {
+      if (!mine.has(name)) row.upstreamOnly++;
+      else if (mine.get(name) !== text) row.changed++;
+    }
+    for (const name of mine.keys()) if (!up.has(name)) row.localOnly++;
+    row.verdict =
+      row.changed + row.upstreamOnly + row.localOnly === 0 ? "identical" : "differs";
+    rows.push(row);
+  }
+  return rows;
+}

package/src/lib/library-listing.ts

@@ -0,0 +1,258 @@
+// `meta gen --list` — the LIBRARY rows (FR-043 §4).
+//
+// It is the codegen catalog, with `kind: "library"` rows in the same table rather than
+// a parallel one: one door, one namespace, one `--probe`, one skill procedure. An agent
+// about to model "users and permissions" should meet `iam` in the list it was already
+// reading, not in a second command it has to know exists.
+//
+// THE ROW DESCRIBES THE BOX; THE PROJECT BLOCK DESCRIBES YOUR SHELF. `provides` counts
+// what the library ships across ALL its layers — what you would get if you took every
+// layer — while `project.tablesAdded` counts what YOUR selection actually put into the
+// model. Those are different numbers whenever an adopter takes the core layer alone,
+// which Amendment 1 makes the common case: `libraries: ["iam"]` provides nine entities
+// and adds zero tables.
+//
+// Every fact here is COMPUTED — from the manifest, or by loading the library and
+// counting. Nothing is a second copy of a sentence written somewhere else, which is the
+// rule §4 states as "every manifest fact is resolved, not trusted".
+import {
+  MetaDataLoader,
+  TYPE_OBJECT,
+  TYPE_REQUIREMENT,
+  OBJECT_SUBTYPE_ENTITY,
+  isWritableSource,
+  type MetaData,
+} from "@metaobjectsdev/metadata";
+import {
+  libraryManifests,
+  librarySources,
+  knownLibraryTokens,
+  splitLayerToken,
+  type LibraryManifest,
+} from "@metaobjectsdev/metadata/library";
+import { SERVER_LANGS } from "@metaobjectsdev/sdk";
+
+/** One `--list` row for a shipped library. */
+export interface LibraryCatalogRow {
+  name: string;
+  kind: "library";
+  /** The manifest's own `kind` — what SORT of library this is (`feature`, `nfr`). A
+   *  second axis from the row's `kind`, which is the catalog discriminator. */
+  libraryKind: string;
+  stability: string;
+  /** The language ports this library is reachable from. Every port embeds the whole
+   *  `library/` tree from one generator script, so this is all of them — and a test
+   *  resolves that against each port's embedded module rather than trusting it. */
+  ports: readonly string[];
+  description: string;
+  useWhen?: string;
+  packages: readonly string[];
+  /** Selection tokens, core first — `["iam", "iam/db"]`. The bare name IS the core
+   *  layer, and a layer token implies it. This is the field an adopter acts on: under
+   *  Amendment 1 you do not opt into a library, you opt into its layers. */
+  layers: ReadonlyArray<{ token: string; description?: string }>;
+  /** What is in the box, across every layer. */
+  provides: {
+    entities: number;
+    abstracts: number;
+    requirements: number;
+    generators: readonly string[];
+  };
+  project?: LibraryProjectFacts;
+}
+
+export interface LibraryProjectFacts {
+  /** Does this project's `libraries` name this library at all? */
+  optedIn: boolean;
+  /** The tokens this project selected, in config order. Empty when not opted in. */
+  selectedLayers: readonly string[];
+  /** Project entities whose `extends` chain reaches a node this library owns — the
+   *  adoption that opting out would break. `null` unless the model was loaded. */
+  extendedBy: readonly string[] | null;
+  /** Tables this library's SELECTED layers contribute to the loaded model. Zero for a
+   *  core-only selection, which is the inertness promise expressed as a number. */
+  tablesAdded: number | null;
+  /** Requirement entries the library put into this project's ledger. */
+  requirementsAdded: number | null;
+  /** Generators the manifest says this library implies, which this project has not
+   *  wired. Not an error: the library is metadata, and wiring is the adopter's call. */
+  impliedGeneratorsNotWired: readonly string[];
+}
+
+/** What a `--list` caller knows about the project, for the library rows. */
+export interface LibraryProjectContext {
+  /** The project's `libraries` selection, verbatim. */
+  libraries: readonly string[];
+  /** Stable names wired in `generators: [...]`. */
+  wiredNames: ReadonlySet<string>;
+  /** The loaded model, when one was loaded (`--probe`). */
+  metadata?: MetaData;
+}
+
+/** Every selection token belonging to one library, core first. */
+function tokensOf(name: string): string[] {
+  return knownLibraryTokens().filter((t) => splitLayerToken(t)[0] === name);
+}
+
+/** Walk every node, since a requirement nests to any depth and an object does not. */
+function walk(node: MetaData, visit: (n: MetaData) => void): void {
+  for (const child of node.children()) {
+    visit(child);
+    walk(child, visit);
+  }
+}
+
+function effectivePackage(node: MetaData): string {
+  return node.package ?? node.fileDefaultPackage ?? "";
+}
+
+/**
+ * Load one library with ALL of its layers and count what it ships.
+ *
+ * The FULL selection, not the core: `provides` answers "what is in this library",
+ * and an adopter reading it is deciding whether to opt in at all. What their current
+ * selection actually added is the project block's job.
+ */
+async function providesOf(name: string, manifest: LibraryManifest): Promise<LibraryCatalogRow["provides"]> {
+  const result = await new MetaDataLoader({ strict: true }).load(librarySources(tokensOf(name)));
+  let entities = 0;
+  let abstracts = 0;
+  let requirements = 0;
+  walk(result.root, (n) => {
+    if (n.type === TYPE_REQUIREMENT) requirements++;
+    else if (n.type === TYPE_OBJECT && n.subType === OBJECT_SUBTYPE_ENTITY) {
+      if (n.isAbstract) abstracts++;
+      else entities++;
+    }
+  });
+  return {
+    entities,
+    abstracts,
+    requirements,
+    generators: (manifest.generators ?? []).map((g) => g.name),
+  };
+}
+
+/**
+ * The project facts for one library.
+ *
+ * `extendedBy` and the two counts read the LOADED model rather than the library,
+ * because that is the question being answered: not "what does iam contain" but "what
+ * is iam doing in this repo". Without `--probe` there is no model and they are null —
+ * never zero, which would read as "nothing", the opposite of "not measured".
+ */
+function projectFactsFor(
+  manifest: LibraryManifest,
+  ctx: LibraryProjectContext,
+): LibraryProjectFacts {
+  const name = manifest.name;
+  const selectedLayers = ctx.libraries.filter((t) => splitLayerToken(t)[0] === name);
+  const impliedGeneratorsNotWired = (manifest.generators ?? [])
+    .map((g) => g.name)
+    .filter((g) => !ctx.wiredNames.has(g));
+
+  const facts: LibraryProjectFacts = {
+    optedIn: selectedLayers.length > 0,
+    selectedLayers,
+    extendedBy: null,
+    tablesAdded: null,
+    requirementsAdded: null,
+    impliedGeneratorsNotWired,
+  };
+  if (ctx.metadata === undefined) return facts;
+
+  const owned = new Set(manifest.packages ?? []);
+  const extendedBy: string[] = [];
+  let tablesAdded = 0;
+  let requirementsAdded = 0;
+  walk(ctx.metadata, (n) => {
+    const mine = owned.has(effectivePackage(n));
+    if (n.type === TYPE_REQUIREMENT && mine) requirementsAdded++;
+    if (n.type !== TYPE_OBJECT) return;
+    if (mine) {
+      // A writable source is what migrate keys a CREATE TABLE off (#248 —
+      // persistability derives from source presence, never from the subtype), so
+      // counting them here and counting tables there cannot drift apart.
+      if (n.children().some(isWritableSource)) tablesAdded++;
+      return;
+    }
+    // A project entity reaching this library through `extends`, at any depth: the
+    // adoption an adopter would break by removing the library from `libraries`.
+    for (let sup = n.superData; sup !== undefined; sup = sup.superData) {
+      if (owned.has(effectivePackage(sup))) {
+        extendedBy.push(`${effectivePackage(n)}::${n.name}`);
+        return;
+      }
+    }
+  });
+
+  facts.extendedBy = extendedBy.sort();
+  facts.tablesAdded = tablesAdded;
+  facts.requirementsAdded = requirementsAdded;
+  return facts;
+}
+
+/** Every shipped library, as `--list` rows, in name order. */
+export async function buildLibraryRows(
+  ctx?: LibraryProjectContext,
+): Promise<LibraryCatalogRow[]> {
+  const rows: LibraryCatalogRow[] = [];
+  for (const [name, manifest] of Object.entries(libraryManifests()).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    const layers = tokensOf(name).map((token) => {
+      const layer = (manifest.layers ?? {})[splitLayerToken(token)[1]];
+      return layer?.description === undefined
+        ? { token }
+        : { token, description: layer.description };
+    });
+    rows.push({
+      name,
+      kind: "library",
+      libraryKind: manifest.kind ?? "feature",
+      stability: manifest.stability ?? "preview",
+      ports: SERVER_LANGS,
+      description: manifest.description ?? "",
+      ...(manifest.useWhen !== undefined ? { useWhen: manifest.useWhen } : {}),
+      packages: manifest.packages ?? [],
+      layers,
+      provides: await providesOf(name, manifest),
+      ...(ctx === undefined ? {} : { project: projectFactsFor(manifest, ctx) }),
+    });
+  }
+  return rows;
+}
+
+function plural(n: number, one: string, many: string): string {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/** The human rendering — one section, after the generator layers. */
+export function renderLibraryText(rows: readonly LibraryCatalogRow[]): string[] {
+  if (rows.length === 0) return [];
+  const lines: string[] = [];
+  lines.push("");
+  lines.push("libraries  —  declared design you opt into, a LAYER at a time; the core layer adds no tables");
+  for (const r of rows) {
+    const marks: string[] = [r.stability];
+    if (r.project?.optedIn) marks.push(`opted in: ${r.project.selectedLayers.join(", ")}`);
+    if (r.project?.tablesAdded) marks.push(`${plural(r.project.tablesAdded, "table", "tables")} added`);
+    lines.push(`  ${r.name}  —  ${r.description}  [${marks.join(", ")}]`);
+    if (r.useWhen !== undefined) lines.push(`      use when: ${r.useWhen}`);
+    lines.push(
+      `      provides: ${plural(r.provides.entities, "entity", "entities")}, ` +
+        `${r.provides.abstracts} abstract, ` +
+        `${plural(r.provides.requirements, "requirement", "requirements")}`,
+    );
+    lines.push(`      layers:   ${r.layers.map((l) => l.token).join(", ")}`);
+    if (r.project !== null && r.project?.impliedGeneratorsNotWired.length) {
+      lines.push(
+        `      implies:  ${r.project.impliedGeneratorsNotWired.join(", ")} (not wired)`,
+      );
+    }
+  }
+  lines.push("");
+  lines.push('Opt in with `"libraries": ["iam", "iam/db"]` in .metaobjects/config.json —');
+  lines.push("the bare name is the core layer, and a layer token implies it.");
+  return lines;
+}