@metaobjectsdev/cli 1.0.2 → 1.0.4-rc.1

package/src/lib/catalog-listing.ts

@@ -0,0 +1,369 @@
+// `meta gen --list` — the catalog as one machine-readable document.
+//
+// The governing rule (opt-in-codegen design §1): stop hard-coding selection decisions
+// into the CLI. The tool's job is to describe what it can do, accurately, and to make
+// each choice cheap to act on. Deciding WHICH generators an application needs belongs
+// to whoever is building it — increasingly an LLM working in the repo, which is well
+// able to make that call given a truthful catalog and is badly served by a default that
+// pre-empts it.
+//
+// Two questions this answers, kept apart on purpose (§D5):
+//
+//   APPLICABILITY — "would this emit anything for MY model?" — is `--probe`, which
+//     cannot drift, because it does not describe the generators, it RUNS them.
+//   COMPATIBILITY — "what does this need in order to work?" — is declared
+//     (`requires`, `runtimePeers`) and therefore has to be gated separately.
+//
+// Conflating the two is how a catalog goes quietly wrong as frameworks are added.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { MetaData } from "@metaobjectsdev/metadata";
+import {
+  runGen,
+  type GeneratorRegistryEntry,
+  type Layer,
+  type MetaobjectsGenConfig,
+} from "@metaobjectsdev/codegen-ts";
+import * as coreTpl from "@metaobjectsdev/codegen-ts";
+import * as reactTpl from "@metaobjectsdev/codegen-ts-react";
+import * as tanstackTpl from "@metaobjectsdev/codegen-ts-tanstack";
+import { listCatalog, packageOf } from "./catalog.js";
+import {
+  buildLibraryRows, renderLibraryText,
+  type LibraryCatalogRow, type LibraryProjectContext,
+} from "./library-listing.js";
+import { installSetFor } from "./install-set.js";
+import { readPackageManifest, declaredDependencyNames } from "./package-manifest.js";
+
+/**
+ * One `--list` row. The cross-port subset is name / layer / tier / description.
+ *
+ * `kind` is the discriminator: FR-043 adds `kind: "library"` rows to THIS table rather
+ * than a parallel one, because an agent about to model a capability should meet the
+ * library that already declares it in the list it was already reading.
+ */
+export type CatalogRow = GeneratorCatalogRow | LibraryCatalogRow;
+
+export type { LibraryCatalogRow };
+
+export interface GeneratorCatalogRow {
+  name: string;
+  kind: "generator";
+  layer: Layer;
+  framework?: string;
+  tier: "native" | "neutral";
+  package: string;
+  description: string;
+  /** From the reference template's `use-when:` header. Absent for a non-ejectable entry. */
+  useWhen?: string;
+  /** From the reference template's `emits:` header. Absent for a non-ejectable entry. */
+  emits?: string;
+  requires?: readonly string[];
+  configKeys?: readonly string[];
+  install: { dev: string[]; runtime: string[] };
+  source: {
+    kind: "reference-template" | "package-only";
+    ejectable: boolean;
+    /** Whether this project already owns a copy. `null` with no project. */
+    owned: boolean | null;
+  };
+  project?: {
+    /** Wired in this project's `generators: [...]`. */
+    wired: boolean;
+    /** This generator's framework is a declared dependency. `null` when neutral or unknown. */
+    frameworkDetected: boolean | null;
+    /** Files this generator WOULD emit for this model. `null` unless --probe. */
+    wouldEmit: number | null;
+    /** Why `wouldEmit` is null despite --probe. Absent when it is a number. */
+    probeError?: string;
+  };
+}
+
+/** Where an ejected copy lands — mirrors `eject.ts`'s constant of the same name. */
+const OWNED_GENERATORS_DIR = "codegen/generators";
+
+/** The npm package a framework token names, for `frameworkDetected`. */
+const FRAMEWORK_PACKAGE: Record<string, string> = {
+  fastify: "fastify",
+  hono: "hono",
+  react: "react",
+  tanstack: "@tanstack/react-query",
+};
+
+// ---------------------------------------------------------------------------
+// reference-template headers
+// ---------------------------------------------------------------------------
+
+/** The three packages that ship reference templates, and their roots. */
+const TEMPLATE_ROOTS: ReadonlyArray<readonly [readonly string[], () => string]> = [
+  [coreTpl.REFERENCE_GENERATOR_NAMES, coreTpl.resolveReferenceRoot],
+  [reactTpl.REFERENCE_GENERATOR_NAMES, reactTpl.resolveReferenceRoot],
+  [tanstackTpl.REFERENCE_GENERATOR_NAMES, tanstackTpl.resolveReferenceRoot],
+];
+
+/**
+ * A `// <facet>:  <text>` header line and its indented continuations, unwrapped.
+ *
+ * Read from the template rather than restated in the registry entry, for the same
+ * reason `eject` reads its import line from the header: the template is the thing an
+ * adopter opens, so a second copy of its own summary in the registry is a second thing
+ * to keep in step. A test asserts every ejectable entry's row actually carries these.
+ */
+function headerFacet(source: string, facet: string): string | undefined {
+  const lines = source.split("\n");
+  const start = lines.findIndex((l) => l.startsWith(`// ${facet}:`));
+  if (start === -1) return undefined;
+  const parts = [lines[start]!.slice(`// ${facet}:`.length).trim()];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]!;
+    // A continuation is a comment line indented past the facet column and NOT itself a
+    // new `facet:` line. Anything else ends the block.
+    if (!/^\/\/ {3,}\S/.test(line) || /^\/\/ {3,}[a-z-]+: /.test(line)) break;
+    parts.push(line.replace(/^\/\/\s+/, "").trim());
+  }
+  return parts.join(" ").trim() || undefined;
+}
+
+function readTemplate(name: string): string | undefined {
+  for (const [names, root] of TEMPLATE_ROOTS) {
+    if (!names.includes(name)) continue;
+    try {
+      return readFileSync(join(root(), `${name}.ts`), "utf8");
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// the probe
+// ---------------------------------------------------------------------------
+
+/**
+ * The project facts a `--list` row can carry. All optional: `--list` with no project at
+ * all is the documented shape (`meta types` behaves the same way), because "what CAN
+ * this engine do" is a question about the installed engine, not about a repo.
+ */
+export interface CatalogProject {
+  projectRoot: string;
+  config: MetaobjectsGenConfig;
+  /** Stable names of the wired generators, as far as they can be identified. */
+  wiredNames: ReadonlySet<string>;
+  /** Owned copies present under `codegen/generators/`. */
+  ownedNames: ReadonlySet<string>;
+  /** Declared dependency names from package.json, for `frameworkDetected`. */
+  declaredDeps: ReadonlySet<string> | undefined;
+  /** FR-043 — the project's `libraries` selection, for the `kind: "library"` rows.
+   *  Defaults to none, so a caller that predates libraries reports "not opted in"
+   *  rather than crashing. */
+  libraries?: readonly string[];
+}
+
+export interface CatalogListingOpts {
+  project?: CatalogProject;
+  /** Run every generator in memory and report a real file count. Needs `project` + `metadata`. */
+  probe?: { metadata: MetaData; scope?: (fqn: string) => boolean };
+}
+
+/**
+ * Dry-run ONE generator and count what it would emit.
+ *
+ * One `runGen` per generator rather than one run over all of them, for isolation: a
+ * generator that throws (or one whose real use requires options `--list` cannot supply,
+ * like `template` and `shared-model`) must report itself and leave every other row
+ * intact. `dryRun` touches nothing on disk.
+ */
+async function probeOne(
+  entry: GeneratorRegistryEntry,
+  project: CatalogProject,
+  metadata: MetaData,
+  scope: ((fqn: string) => boolean) | undefined,
+): Promise<{ count: number } | { error: string }> {
+  try {
+    const result = await runGen({
+      config: { ...project.config, generators: [entry.factory()] },
+      metadata,
+      projectRoot: project.projectRoot,
+      dryRun: true,
+      ...(scope !== undefined ? { scope } : {}),
+    });
+    return { count: result.files.length };
+  } catch (err) {
+    return { error: (err as Error).message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// the listing
+// ---------------------------------------------------------------------------
+
+export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promise<CatalogRow[]> {
+  const rows: CatalogRow[] = [];
+
+  for (const entry of listCatalog()) {
+    const template = entry.ejectable ? readTemplate(entry.name) : undefined;
+    const install = installSetFor([entry]);
+    const pkg = packageOf(entry.name) ?? "";
+
+    const row: GeneratorCatalogRow = {
+      name: entry.name,
+      kind: entry.kind,
+      layer: entry.layer,
+      ...(entry.framework !== undefined ? { framework: entry.framework } : {}),
+      tier: entry.tier,
+      package: pkg,
+      description: entry.description,
+      ...(template !== undefined && headerFacet(template, "use-when") !== undefined
+        ? { useWhen: headerFacet(template, "use-when")! }
+        : {}),
+      ...(template !== undefined && headerFacet(template, "emits") !== undefined
+        ? { emits: headerFacet(template, "emits")! }
+        : {}),
+      ...(entry.requires !== undefined ? { requires: entry.requires } : {}),
+      ...(entry.configKeys !== undefined ? { configKeys: entry.configKeys } : {}),
+      install: { dev: install.dev, runtime: install.runtime },
+      source: {
+        kind: entry.ejectable ? "reference-template" : "package-only",
+        ejectable: entry.ejectable,
+        owned: opts.project === undefined ? null : opts.project.ownedNames.has(entry.name),
+      },
+    };
+
+    if (opts.project !== undefined) {
+      const project = opts.project;
+      const fw = entry.framework;
+      const frameworkDetected =
+        fw === undefined || project.declaredDeps === undefined
+          ? null
+          : project.declaredDeps.has(FRAMEWORK_PACKAGE[fw] ?? fw);
+
+      let wouldEmit: number | null = null;
+      let probeError: string | undefined;
+      if (opts.probe !== undefined) {
+        const outcome = await probeOne(entry, project, opts.probe.metadata, opts.probe.scope);
+        if ("count" in outcome) wouldEmit = outcome.count;
+        else probeError = outcome.error;
+      }
+
+      row.project = {
+        wired: project.wiredNames.has(entry.name),
+        frameworkDetected,
+        wouldEmit,
+        ...(probeError !== undefined ? { probeError } : {}),
+      };
+    }
+
+    rows.push(row);
+  }
+
+  // FR-043 — the library rows, after the generators. Same table, same `--probe`.
+  const libraryCtx: LibraryProjectContext | undefined =
+    opts.project === undefined
+      ? undefined
+      : {
+          libraries: opts.project.libraries ?? [],
+          wiredNames: opts.project.wiredNames,
+          ...(opts.probe !== undefined ? { metadata: opts.probe.metadata } : {}),
+        };
+  rows.push(...(await buildLibraryRows(libraryCtx)));
+
+  return rows;
+}
+
+/**
+ * The stable names wired in a config.
+ *
+ * `generators: [...]` holds constructed Generator objects (and, since ADR-0021 #1,
+ * bare stable-name strings). A constructed generator carries its own kebab-case `name`,
+ * which IS the stable name for every catalog entry — the registry's factory is what
+ * produced it. A generator whose name is not a catalog key is an owned or third-party
+ * one and simply contributes nothing here.
+ */
+export function wiredGeneratorNames(config: MetaobjectsGenConfig): Set<string> {
+  const names = new Set<string>();
+  for (const spec of config.generators ?? []) {
+    if (typeof spec === "string") names.add(spec);
+    else if (typeof spec?.name === "string") names.add(spec.name);
+  }
+  return names;
+}
+
+/** Owned copies present under `codegen/generators/` in this project. */
+export function ownedGeneratorNames(projectRoot: string): Set<string> {
+  const owned = new Set<string>();
+  for (const entry of listCatalog()) {
+    if (!entry.ejectable) continue;
+    try {
+      readFileSync(join(projectRoot, OWNED_GENERATORS_DIR, `${entry.name}.ts`), "utf8");
+      owned.add(entry.name);
+    } catch {
+      // absent — not owned
+    }
+  }
+  return owned;
+}
+
+/** Declared dependency names, or undefined when there is no readable manifest. */
+export function declaredDepsOf(projectRoot: string): Set<string> | undefined {
+  const pkg = readPackageManifest(projectRoot);
+  return pkg === undefined ? undefined : declaredDependencyNames(pkg);
+}
+
+// ---------------------------------------------------------------------------
+// text rendering
+// ---------------------------------------------------------------------------
+
+const LAYER_BLURB: Record<Layer, string> = {
+  model: "the entity modules and the constants beside them",
+  persistence: "how rows are read and written",
+  api: "the HTTP surface — pick ONE framework",
+  client: "the browser tier — form + hooks + grid compose, they do not conflict",
+  docs: "on by default; the canonical door is `meta docs`",
+  capability: "chosen by your MODEL, not by browsing — run --probe",
+};
+
+/** The human rendering: grouped by layer, because layer is the axis you select by. */
+export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
+  const lines: string[] = [];
+  lines.push("Generator catalog — nothing runs until you wire it in `generators: [...]`.");
+  lines.push("");
+
+  const generators = rows.filter((r): r is GeneratorCatalogRow => r.kind === "generator");
+  const width = Math.max(...generators.map((r) => r.name.length));
+  let layer: string | undefined;
+  for (const r of generators) {
+    if (r.layer !== layer) {
+      layer = r.layer;
+      lines.push(`${layer}  —  ${LAYER_BLURB[r.layer]}`);
+    }
+    const marks: string[] = [];
+    if (r.framework !== undefined) marks.push(r.framework);
+    if (r.tier === "neutral") marks.push("neutral");
+    if (r.project?.wired) marks.push("WIRED");
+    if (r.source.owned) marks.push("owned");
+    if (probed && r.project?.wouldEmit !== null && r.project?.wouldEmit !== undefined) {
+      marks.push(`would emit ${r.project.wouldEmit}`);
+    }
+    const suffix = marks.length > 0 ? `  [${marks.join(", ")}]` : "";
+    lines.push(`  ${r.name.padEnd(width)}  —  ${r.description}${suffix}`);
+    if (r.requires !== undefined && r.requires.length > 0) {
+      lines.push(`  ${" ".repeat(width)}     requires: ${r.requires.join(", ")}`);
+    }
+  }
+
+  // The library section sits between the generators and the footer: the footer's
+  // `meta eject` line applies to both kinds, and putting libraries after it buries
+  // the one row an agent modelling a capability most needs to see.
+  lines.push(...renderLibraryText(rows.filter((r): r is LibraryCatalogRow => r.kind === "library")));
+
+  lines.push("");
+  lines.push("`meta eject <name...>` copies a generator into codegen/generators/ and prints");
+  lines.push("the import to add, the entry to wire, and what to install.");
+  if (!probed) {
+    lines.push("Add --probe to see how many files each would emit for YOUR model.");
+  }
+  lines.push("`meta gen --list --format json` is the same catalog, machine-readable.");
+  return lines.join("\n");
+}

package/src/lib/catalog.ts

@@ -0,0 +1,107 @@
+// The TypeScript port's generator CATALOG — the one place all three registry slices
+// are visible at once (ADR-0021 D3; opt-in-codegen design §D2a).
+//
+// `codegen-ts` owns the entry type and its own entries, but cannot import
+// `codegen-ts-react` / `codegen-ts-tanstack` (dependency direction), so each of those
+// exports its own slice and the CLI unions them here — exactly how `eject.ts` already
+// composes its `SOURCES` table over the same three packages.
+//
+// Before this existed, `meta gen --list` read the codegen-ts registry and
+// `meta eject --list` read the reference-template lists, so an agent asking "what can I
+// turn on" got two different answers. After it, they are one table with two views.
+//
+// (The Angular generators stay out until ADR-0048's promotion bar is met — a
+// source-only package is not a catalog entry.)
+
+import {
+  generatorRegistry,
+  GENERATOR_LAYERS,
+  type GeneratorRegistryEntry,
+} from "@metaobjectsdev/codegen-ts";
+import { reactGeneratorRegistry } from "@metaobjectsdev/codegen-ts-react";
+import { tanstackGeneratorRegistry } from "@metaobjectsdev/codegen-ts-tanstack";
+
+/** The slices, in install-boundary order: the engine, then its framework packages. */
+const SLICES: ReadonlyArray<readonly [string, Record<string, GeneratorRegistryEntry>]> = [
+  ["@metaobjectsdev/codegen-ts", generatorRegistry],
+  ["@metaobjectsdev/codegen-ts-react", reactGeneratorRegistry],
+  ["@metaobjectsdev/codegen-ts-tanstack", tanstackGeneratorRegistry],
+];
+
+/**
+ * Which npm package a catalog entry comes from.
+ *
+ * This is the fact composition ADDS: a slice cannot know its own package name without
+ * hard-coding it in every entry, and the package is precisely what `meta eject` has to
+ * name in an install command. Undefined for a name no slice registers.
+ */
+export function packageOf(name: string): string | undefined {
+  return SLICES.find(([, slice]) => name in slice)?.[0];
+}
+
+/** Every `@metaobjectsdev` package that contributes catalog entries. */
+export function catalogPackages(): string[] {
+  return SLICES.map(([pkg]) => pkg);
+}
+
+/**
+ * The composed catalog, keyed by stable name.
+ *
+ * Throws on a name registered by two packages. A stable name identifies ONE generator
+ * across the whole catalog — that is the entire content of ADR-0021 D3 — so a collision
+ * is a build-time defect, not something to resolve by precedence. Silently letting the
+ * last slice win would make `meta gen --list` describe one generator and `meta gen` run
+ * another.
+ */
+export function composeCatalog(): Record<string, GeneratorRegistryEntry> {
+  return composeSlices(SLICES);
+}
+
+/**
+ * The composition itself, over any slice list.
+ *
+ * Separate from {@link composeCatalog} so the REFUSAL is reachable from a test. With the
+ * live `SLICES` closed over, the only thing a test could assert is that today's three
+ * packages happen not to collide — which stays true if the check above is deleted, so
+ * the guard that makes a collision a build failure was never covered by anything.
+ */
+export function composeSlices(
+  slices: ReadonlyArray<readonly [string, Record<string, GeneratorRegistryEntry>]>,
+): Record<string, GeneratorRegistryEntry> {
+  const out: Record<string, GeneratorRegistryEntry> = {};
+  const from: Record<string, string> = {};
+  for (const [pkg, slice] of slices) {
+    for (const [name, entry] of Object.entries(slice)) {
+      if (name in out) {
+        throw new Error(
+          `generator "${name}" is registered by both ${from[name]} and ${pkg} — a stable ` +
+            "name identifies ONE generator across the whole catalog (ADR-0021 D3). Rename " +
+            "one of them, or delete the duplicate registration.",
+        );
+      }
+      out[name] = entry;
+      from[name] = pkg;
+    }
+  }
+  return out;
+}
+
+/**
+ * Every catalog entry, grouped by layer in {@link GENERATOR_LAYERS} order and
+ * alphabetical within a layer.
+ *
+ * Layer order, not tier order: `layer` is the axis an adopter selects by, so it is the
+ * axis the listing is organized along. `tier` still travels on each row.
+ */
+export function listCatalog(): GeneratorRegistryEntry[] {
+  return Object.values(composeCatalog()).sort(
+    (a, b) =>
+      GENERATOR_LAYERS.indexOf(a.layer) - GENERATOR_LAYERS.indexOf(b.layer) ||
+      a.name.localeCompare(b.name),
+  );
+}
+
+/** Resolve one catalog entry by stable name, or undefined. */
+export function catalogEntry(name: string): GeneratorRegistryEntry | undefined {
+  return composeCatalog()[name];
+}

package/src/lib/collection-load-options.ts

@@ -0,0 +1,42 @@
+// server/typescript/packages/cli/src/lib/collection-load-options.ts
+//
+// FR-023 — everything a resolved `Collection` contributes to a metadata LOAD,
+// in one helper.
+//
+// One helper rather than four properties spread by hand at each of the nine
+// `loadMemory` call sites, for the reason `loadMemoryOptionsFrom` exists next
+// door (#333): threading one and forgetting another is how a capability reaches
+// some commands and not others. Here the stakes are higher than a missing
+// provider — a site that passes `files` alone loads a dependency's artifact
+// under a local-looking source id AND loses the
+// `ERR_DEPENDENCY_PACKAGE_NOT_OWNED` refusal, so a node declared into a
+// dependency's package is silently excluded from that command's output instead
+// of being refused by name.
+import type { Collection, LoadMemoryOptions } from "@metaobjectsdev/sdk";
+
+/**
+ * The load half of a `Collection`: the resolved file list (dependency artifacts
+ * first, then the project's own files), the `dep:<name>/<artifact>` source ids
+ * those artifacts load under, and the two imported sets the ownership refusal
+ * reads.
+ *
+ * The return type is a `Pick` of {@link LoadMemoryOptions} rather than a
+ * hand-written shape, so renaming or retyping an option there is a compile
+ * error here rather than a silently-dropped key.
+ */
+export function collectionLoadOptions(
+  collection: Collection,
+): Required<Pick<LoadMemoryOptions, "files" | "fileIds" | "importedPackages" | "importedNodes" | "libraries">> {
+  return {
+    files: collection.files,
+    fileIds: collection.fileIds,
+    importedPackages: collection.importedPackages,
+    importedNodes: collection.importedNodes,
+    // FR-043 — the shipped-library selection moved here from metaobjects.config.ts, so
+    // it now rides the same helper as everything else the collection contributes. That
+    // is the point of the move as much as the neutrality is: `libraries` used to be
+    // threaded by `loadMemoryOptionsFrom`, a SECOND helper, and #333 is on record as the
+    // bug where one of the two reached every command and the other reached none.
+    libraries: collection.libraries,
+  };
+}