@metaobjectsdev/codegen-ts 0.24.5 → 1.0.0-rc.1

package/dist/generators/agent-schema-page.js

@@ -0,0 +1,241 @@
+// `agent/schema.md` — the physical schema, for an agent about to touch persistence.
+//
+// WHY THIS PAGE EXISTS AND WHY IT LOOKS LIKE THIS
+//
+// The strongest measured finding behind this surface is not about format: roughly 2K
+// tokens of BUSINESS SEMANTICS beside the schema is worth an order of magnitude more
+// than any table-versus-YAML-versus-DDL choice. So every table and column carries its
+// `@description`, and the descriptions come from the snapshot itself — `migrate-ts`
+// already threads them there to emit `COMMENT ON`, which means the page and the database
+// comment cannot disagree.
+//
+// IT DOES NOT RESTATE THE DDL. The migration files ARE the DDL, they are generated, and
+// they are what actually runs. A page that reproduces `CREATE TABLE` is a second spelling
+// of the same fact that goes stale the first time someone regenerates without it — so
+// this page describes the schema and CITES the migrations for the statements.
+//
+// It is TABLE-DRIVEN, not entity-driven, and that is deliberate: a TPH hierarchy folds
+// several entities into one table, an abstract base has none, and an `@unmanaged` object
+// is excluded — all rules `buildExpectedSchema`'s Pass 1 already owns. Walking entities
+// here would mean re-implementing those skip rules and drifting from them. The declaring
+// object is named per table from the provenance map instead.
+import { GENERATION_INCREMENT, GENERATION_UUID } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
+/** Markdown-escape a cell whose text may contain a `|` (a CHECK expression can). */
+function mdCell(text) {
+    return text.replace(/\|/g, "\\|");
+}
+/** Collapse a description to one line — a newline inside a table cell ends the row. */
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** `` `a`, `b` `` — a column list, or an em-dash when empty. */
+function cols(list) {
+    return list.length === 0 ? "—" : list.map((c) => `\`${c}\``).join(", ");
+}
+/**
+ * The KEY cell: primary / foreign / unique / indexed, most-specific first.
+ *
+ * A COMPOSITE index is labelled as one. A bare `unique` on a column that is merely one
+ * member of a two-column unique index asserts that the column alone is unique — which is
+ * false, and false in the direction that makes a reader write a lookup that returns more
+ * than one row. The Indexes section below carries the full key; this cell only has to stop
+ * being wrong about it.
+ */
+function keyCell(table, column) {
+    const roles = [];
+    if (table.primaryKey.includes(column.name)) {
+        roles.push(table.primaryKey.length > 1 ? "PK (composite)" : "PK");
+    }
+    const fk = table.foreignKeys.find((f) => f.columns.includes(column.name));
+    if (fk !== undefined)
+        roles.push(`FK → \`${fk.refTable}\``);
+    const covering = table.indexes.filter((i) => i.columns.includes(column.name));
+    const unique = covering.find((i) => i.unique);
+    const index = unique ?? covering[0];
+    if (index !== undefined) {
+        const label = unique !== undefined ? "unique" : "indexed";
+        roles.push(index.columns.length > 1 ? `${label} (composite)` : label);
+    }
+    return roles.length === 0 ? "" : roles.join(" · ");
+}
+/** The DEFAULT cell. An `expr` default is shown as SQL; a literal as a literal. */
+function defaultCell(column) {
+    if (column.identity === GENERATION_INCREMENT)
+        return "auto-increment";
+    if (column.identity === GENERATION_UUID)
+        return "generated uuid";
+    if (column.default === undefined)
+        return "";
+    return `\`${mdCell(column.default.value)}\``;
+}
+function indexLine(ix) {
+    const key = ix.expr !== undefined ? `\`${mdCell(ix.expr)}\`` : cols(ix.columns);
+    const parts = [`\`${ix.name}\``, ix.unique ? "unique" : "index", `on ${key}`];
+    if (ix.using !== undefined && ix.using !== "" && ix.using !== "btree")
+        parts.push(`using \`${ix.using}\``);
+    if (ix.where !== undefined && ix.where !== "")
+        parts.push(`where \`${mdCell(ix.where)}\``);
+    return `- ${parts.join(" · ")}`;
+}
+function fkLine(fk) {
+    const parts = [
+        `\`${fk.name}\``,
+        `${cols(fk.columns)} → \`${fk.refTable}\`(${cols(fk.refColumns)})`,
+    ];
+    if (fk.onDelete !== undefined && fk.onDelete !== "")
+        parts.push(`on delete \`${fk.onDelete}\``);
+    if (fk.onUpdate !== undefined && fk.onUpdate !== "")
+        parts.push(`on update \`${fk.onUpdate}\``);
+    return `- ${parts.join(" · ")}`;
+}
+/**
+ * One table's section: the declaring object, its description, the column table, then
+ * whichever of indexes / foreign keys / checks the table actually has.
+ *
+ * `declaredBy` maps a physical column name back to the FIELD that declared it — the
+ * mapping an agent needs to go from a query it is reading to the metadata it must edit,
+ * and the one thing the snapshot alone cannot supply.
+ */
+function tableSection(table, input, fqn, declaredBy) {
+    const out = [];
+    const qualified = table.schema === undefined ? `\`${table.name}\`` : `\`${table.schema}.${table.name}\``;
+    out.push(`### ${qualified}`);
+    out.push("");
+    if (fqn !== undefined)
+        out.push(`Declared by \`${fqn}\`.`);
+    if (table.description !== undefined && table.description !== "") {
+        out.push("");
+        out.push(`> ${oneLine(table.description)}`);
+    }
+    out.push("");
+    out.push("| Column | Field | Declared | SQL type | Null | Default | Key |");
+    out.push("|---|---|---|---|---|---|---|");
+    for (const c of table.columns) {
+        const declared = declaredBy.get(c.name);
+        out.push(`| \`${c.name}\` | ${declared === undefined ? "" : `\`${declared.field}\``} | ` +
+            `${declared === undefined ? "" : `\`${declared.type}\``} | \`${mdCell(input.columnType(c))}\` | ` +
+            `${c.nullable ? "yes" : "no"} | ${defaultCell(c)} | ${keyCell(table, c)} |`);
+    }
+    // Column descriptions ride BELOW the table rather than as an eighth cell: a sentence
+    // in a cell forces the whole table wide, and most columns have none.
+    const described = table.columns.filter((c) => c.description !== undefined && c.description !== "");
+    if (described.length > 0) {
+        out.push("");
+        for (const c of described)
+            out.push(`- \`${c.name}\` — ${oneLine(c.description ?? "")}`);
+    }
+    if (table.indexes.length > 0) {
+        out.push("");
+        out.push("**Indexes**");
+        out.push("");
+        for (const ix of table.indexes)
+            out.push(indexLine(ix));
+    }
+    if (table.foreignKeys.length > 0) {
+        out.push("");
+        out.push("**Foreign keys**");
+        out.push("");
+        for (const fk of table.foreignKeys)
+            out.push(fkLine(fk));
+    }
+    if (table.checks.length > 0) {
+        out.push("");
+        out.push("**Checks**");
+        out.push("");
+        for (const ck of table.checks)
+            out.push(`- \`${ck.name}\` — \`${mdCell(ck.expression)}\``);
+    }
+    out.push("");
+    return out;
+}
+/**
+ * Render the whole page. Returns "" when there is no physical schema at all, which is
+ * what lets the surface emit no FILE rather than a page describing nothing.
+ */
+export function renderAgentSchemaPage(input, opts) {
+    if (input.tables.length === 0 && input.views.length === 0)
+        return "";
+    const out = [];
+    out.push(GENERATED_MARKER);
+    out.push("");
+    out.push("# Schema");
+    out.push("");
+    out.push(`The physical shape of the \`${input.dialect}\` database this model generates. ` +
+        "Read it before writing a query, a migration, or anything that names a table or a column.");
+    out.push("");
+    out.push("- The **DDL is not repeated here.** The migration files are the DDL, they are " +
+        "generated, and they are what runs — this page describes the schema they produce.");
+    out.push("- Change the schema by changing the **metadata** and running `meta migrate`. Never " +
+        "hand-apply SQL to a live database: it drifts from the migration history and " +
+        "collides at the next migrate.");
+    out.push("- `Field` and `Declared` are the METADATA names. Edit those; the column name follows.");
+    out.push("");
+    // The semantics nudge. A schema page carrying business meaning beside the columns is
+    // worth more to a reader working from it than any format choice this page could make —
+    // and those sentences come from `@description` on the entity and the field, which the
+    // snapshot already threads here to emit `COMMENT ON`. A model declaring none renders a
+    // page of names with nothing to disambiguate them, and says so, because silently
+    // omitting the highest-value content teaches an adopter that it does not exist.
+    const anyDescription = input.tables.some((t) => (t.description !== undefined && t.description !== "") ||
+        t.columns.some((c) => c.description !== undefined && c.description !== ""));
+    if (!anyDescription && input.tables.length > 0) {
+        out.push("> **Nothing in this model declares a `description`.** The tables and columns below " +
+            "are named but not explained. Adding `description` to an entity or a field is the " +
+            "single highest-value change to this page: it is what tells a reader *which* of " +
+            "two plausible columns to use, and it is the same text `meta migrate` emits as a " +
+            "`COMMENT ON`, so it lands in the database too.");
+        out.push("");
+    }
+    if (input.tables.length > 0) {
+        out.push("## Tables");
+        out.push("");
+        for (const table of [...input.tables].sort((a, b) => a.name.localeCompare(b.name))) {
+            const key = input.qualify(table);
+            out.push(...tableSection(table, input, input.provenance.get(key), opts.declaredBy.get(key) ?? new Map()));
+        }
+    }
+    if (input.views.length > 0) {
+        out.push("## Views");
+        out.push("");
+        out.push("A view is generated from its projection's `origin.*` children — it is derived, " +
+            "never hand-written. Editing the view SQL directly is drift the tool cannot see.");
+        out.push("");
+        for (const view of [...input.views].sort((a, b) => a.name.localeCompare(b.name))) {
+            const key = input.qualify(view);
+            const qualified = view.schema === undefined ? `\`${view.name}\`` : `\`${view.schema}.${view.name}\``;
+            out.push(`### ${qualified}`);
+            out.push("");
+            const fqn = input.provenance.get(key);
+            if (fqn !== undefined)
+                out.push(`Declared by \`${fqn}\`.`);
+            const lineage = opts.viewLineage.get(key) ?? [];
+            if (lineage.length > 0) {
+                out.push("");
+                out.push("| Column | Lineage |");
+                out.push("|---|---|");
+                out.push(...lineage);
+            }
+            out.push("");
+        }
+    }
+    if (opts.relationships.length > 0) {
+        out.push("## Relationships");
+        out.push("");
+        out.push(...opts.relationships);
+        out.push("");
+    }
+    if (opts.enums.length > 0) {
+        out.push("## Enums");
+        out.push("");
+        out.push("Members are the values the wire and the generated types use. Whether the DATABASE " +
+            "also refuses a value outside the set is that table's **Checks** above — an " +
+            "`@isArray` enum carries none, and neither does a view column.");
+        out.push("");
+        out.push(...opts.enums);
+        out.push("");
+    }
+    return `${out.join("\n").replace(/\n+$/, "")}\n`;
+}
+//# sourceMappingURL=agent-schema-page.js.map

package/dist/generators/agent-schema-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-schema-page.js","sourceRoot":"","sources":["../../src/generators/agent-schema-page.ts"],"names":[],"mappings":"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"}

package/dist/generators/agent-ui-page.d.ts

@@ -0,0 +1,22 @@
+import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+/**
+ * True when a UI generator would emit for this object.
+ *
+ * `servesReadApi` — the api-surface predicate the hook, grid and form generators
+ * themselves gate on — NOT "has fields" and never an object-subtype test. A form, a grid
+ * and a hook are all clients of a generated endpoint, so an object with no endpoint has no
+ * UI to document.
+ *
+ * Getting this wrong is not cosmetic. Gating on "has fields" put a prompt payload
+ * (`object.value`, no source, no routes) on the page under a heading that announced an
+ * endpoint derived from its name — an address that does not exist, stated as fact, on the
+ * page an agent is told to trust. Instance artifacts derive from a declared SOURCE; the
+ * UI tier asks the endpoint question and never a storage or subtype one.
+ */
+export declare function hasUiSurface(obj: MetaObject): boolean;
+/**
+ * Render the page. Returns "" when no object in the model has a UI surface — the surface
+ * then emits no FILE, so a headless project sees nothing rather than an empty page.
+ */
+export declare function renderAgentUiPage(root: MetaRoot, apiPrefix?: string): string;
+//# sourceMappingURL=agent-ui-page.d.ts.map

package/dist/generators/agent-ui-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-ui-page.d.ts","sourceRoot":"","sources":["../../src/generators/agent-ui-page.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAY,UAAU,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAiH/E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAErD;AAqBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,SAAK,GAAG,MAAM,CA4FxE"}

package/dist/generators/agent-ui-page.js

@@ -0,0 +1,253 @@
+// `agent/ui.md` — the generated UI surface, for an agent about to touch a form or a grid.
+//
+// The gap this closes is narrow and real: the neutral model entity page renders NO
+// `view.*` or `layout.*` metadata at all, so an agent asked to change a form had nowhere
+// to learn what the form already is and would read the generated TSX — the disposable
+// artifact — as if it were the source.
+//
+// EVERY FIELD ROW COMES FROM `buildEntityUiDescriptor`, the same derivation
+// `renderEntityConstants` emits as the `<Entity>` const in `<Entity>.meta.ts`, which is
+// what `useEntityForm` reads at runtime. One derivation, two renderings: the page cannot
+// describe a control the form does not render, because both answers come from the same
+// call. That is the point of the descriptor extraction, not a nicety.
+//
+// The three columns the descriptor does NOT carry — `@formExclude`, `@filterable` and
+// `@sortable` — are read here from the field, and `@sortable`'s inherit-from-`@filterable`
+// default resolves through `isSortableField`, the SAME predicate the generated
+// `<Entity>SortAllowlist` is built from, so the page cannot say a field is sortable that
+// the endpoint will reject. They are deliberately absent from the descriptor: the
+// descriptor describes how a field is PRESENTED, while those three say whether it appears
+// at all and what the LIST endpoint will accept, which is a different question the form
+// control has no opinion on.
+//
+// THREE THINGS THE DESCRIPTOR ALONE CANNOT ANSWER, each read from the predicate the
+// generator that decides it uses, never re-derived here:
+//
+//   • WHERE the object is served — `restPath`, because a TPH subtype is mounted under its
+//     discriminator base and its own `$path` names nothing;
+//   • WHETHER a form exists at all — `hasGeneratedForm`, the form generator's own filter,
+//     because a discriminator base has a write endpoint and still gets no form;
+//   • WHAT the control is for a `field.object` — `valueObjectFor`, shared with the form
+//     generator, because a resolvable `@objectRef` is rendered as a nested sub-form and
+//     the field's view kind is not consulted.
+import { FIELD_ATTR_FILTERABLE, FIELD_ATTR_FORM_EXCLUDE, LAYOUT_DATA_GRID_ATTR_COLUMNS, LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD, LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER, LAYOUT_DATA_GRID_ATTR_PAGE_SIZE, LAYOUT_SUBTYPE_DATA_GRID, TYPE_LAYOUT, } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { hasGeneratedForm, restPath, servedPath, servesReadApi } from "../api-surface.js";
+import { buildEntityUiDescriptor, } from "../templates/entity-ui-descriptor.js";
+import { isSortableField } from "../templates/filter-shared.js";
+import { isTphDiscriminatorBase } from "../templates/tph-discriminator.js";
+import { declaresTphDiscriminator } from "../templates/zod-validators.js";
+const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
+function mdCell(text) {
+    return text.replace(/\|/g, "\\|");
+}
+/** One rule, as a reader wants to see it — the value, not the message. */
+function ruleText(r) {
+    switch (r.kind) {
+        case "required":
+            return "required";
+        case "minLength":
+            return `minLength ${r.value}`;
+        case "maxLength":
+            return `maxLength ${r.value}`;
+        case "pattern":
+            return `pattern \`${mdCell(r.pattern)}\``;
+    }
+}
+/**
+ * The CONTROL cell — what the generated form renders, which is not always a `view.*`
+ * subtype.
+ *
+ * A `field.object` whose `@objectRef` resolves is emitted as a nested `<fieldset>`
+ * sub-form (a `useFieldArray` repeatable group when the field is an array), and the form
+ * generator never consults the field's view kind for it. This column used to print that
+ * view kind — `text`, the `defaultViewForSubType` fallback — which said the control was a
+ * free-text input for a field that has no input at all. Same shape as the `field.enum`
+ * descriptor bug, one subtype family over; the predicate is shared with the form
+ * generator (`valueObjectFor`) so the two cannot answer differently again.
+ */
+function controlCell(f) {
+    if (f.nested === undefined)
+        return `\`${f.view}\``;
+    return f.nested.isArray ? "nested sub-form (repeatable)" : "nested sub-form";
+}
+/** The HTML type cell — empty for a nested sub-form, which is not an input at all. */
+function htmlTypeCell(f) {
+    if (f.nested !== undefined || f.htmlType === undefined)
+        return "";
+    return `\`${f.htmlType}\``;
+}
+/** `yes` / `` — an empty cell reads better than a column of "no". */
+function flag(value) {
+    return value === true ? "yes" : "";
+}
+/**
+ * The endpoint line under an object's heading.
+ *
+ * THE `apiPrefix` IS PART OF THE ADDRESS. `routes-file.ts` registers every mount inside
+ * `fastify.register(…, { prefix: apiPrefix })`, so a project configuring `/api` serves
+ * `/api/owners` and nothing at `/owners`. This page states that its heading is the address
+ * the routes mount at, so omitting the prefix made that promise false for every project
+ * that sets one — and a reader following it gets a 404.
+ *
+ * `restPath`, NOT `descriptor.path`: a TPH subtype's own `$path` names an address
+ * nothing mounts — the hierarchy is mounted from the discriminator base, each subtype
+ * at `<base>/<segment>` — and this page printed that non-existent address as fact.
+ * Whether a form exists is `hasGeneratedForm` — the form generator's OWN filter —
+ * never `servesWriteApi`. A read-only object (a projection, a view-backed entity) has
+ * no Insert/Update schema; a TPH discriminator BASE has both and still gets no form,
+ * because you cannot create a base and its polymorphic mount is read-only by
+ * construction. Saying so is the difference between "the form is missing" and "there
+ * is deliberately no form"; asking the endpoint question announced one for every base.
+ */
+function endpointLine(obj, root, apiPrefix) {
+    const endpoint = servedPath(obj, apiPrefix);
+    if (hasGeneratedForm(obj))
+        return `Endpoint \`${endpoint}\`.`;
+    // `isTphDiscriminatorBase`, which requires at least one CONCRETE subtype — the same
+    // predicate `routes-file.ts` switches on. `@discriminator` with no subtype yet is a
+    // refactor-in-progress shape: the routes generator emits the VANILLA full-CRUD file for
+    // it, so "each concrete subtype below has its own" would name subtypes that do not
+    // exist, on an object that does have a write endpoint.
+    // THREE reasons, not two. `isTphDiscriminatorBase` requires at least one CONCRETE
+    // subtype — the same predicate `routes-file.ts` switches on — and the case it excludes
+    // is real: an object declaring `@discriminator` with no subtype yet gets the VANILLA
+    // full-CRUD routes file, so it is NOT read-only, while the form generator declines it
+    // for declaring `@discriminator` at all. Calling that "read-only" is false in the one
+    // direction that matters, since a reader would conclude it cannot be written to.
+    const reason = isTphDiscriminatorBase(obj, root)
+        ? "for a discriminator base — its own mount is list/get only, and each concrete " +
+            "subtype below has its own form"
+        : declaresTphDiscriminator(obj)
+            ? "— the form generator declines any object declaring `@discriminator`, and this " +
+                "one has no concrete subtype yet. Its routes are the ordinary full CRUD set"
+            : "(read-only)";
+    return (`Endpoint \`${endpoint}\` — **no form is generated** ${reason}. ` +
+        "The fields below describe the grid and the filters.");
+}
+/** The `layout.dataGrid` children an object declares. ADR-0039: resolving. */
+function dataGrids(obj) {
+    return obj
+        .children()
+        .filter((c) => c.type === TYPE_LAYOUT && c.subType === LAYOUT_SUBTYPE_DATA_GRID);
+}
+/**
+ * True when a UI generator would emit for this object.
+ *
+ * `servesReadApi` — the api-surface predicate the hook, grid and form generators
+ * themselves gate on — NOT "has fields" and never an object-subtype test. A form, a grid
+ * and a hook are all clients of a generated endpoint, so an object with no endpoint has no
+ * UI to document.
+ *
+ * Getting this wrong is not cosmetic. Gating on "has fields" put a prompt payload
+ * (`object.value`, no source, no routes) on the page under a heading that announced an
+ * endpoint derived from its name — an address that does not exist, stated as fact, on the
+ * page an agent is told to trust. Instance artifacts derive from a declared SOURCE; the
+ * UI tier asks the endpoint question and never a storage or subtype one.
+ */
+export function hasUiSurface(obj) {
+    return servesReadApi(obj);
+}
+function gridSection(grid) {
+    const out = [];
+    out.push(`**Grid \`${grid.name}\`**`);
+    out.push("");
+    const columns = grid.attr(LAYOUT_DATA_GRID_ATTR_COLUMNS);
+    if (Array.isArray(columns) && columns.length > 0) {
+        out.push(`- columns: ${columns.map((c) => `\`${String(c)}\``).join(", ")}`);
+    }
+    const sortField = grid.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
+    if (typeof sortField === "string" && sortField !== "") {
+        const order = grid.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER);
+        const suffix = typeof order === "string" && order !== "" ? `:${order}` : "";
+        out.push(`- default sort: \`${sortField}${suffix}\``);
+    }
+    const pageSize = grid.attr(LAYOUT_DATA_GRID_ATTR_PAGE_SIZE);
+    if (typeof pageSize === "number")
+        out.push(`- page size: ${pageSize}`);
+    return out;
+}
+/**
+ * Render the page. Returns "" when no object in the model has a UI surface — the surface
+ * then emits no FILE, so a headless project sees nothing rather than an empty page.
+ */
+export function renderAgentUiPage(root, apiPrefix = "") {
+    const objects = root.objects();
+    const withUi = objects.filter(hasUiSurface);
+    if (withUi.length === 0)
+        return "";
+    const out = [];
+    out.push(GENERATED_MARKER);
+    out.push("");
+    out.push("# UI");
+    out.push("");
+    out.push("What the generated forms and grids already are. Read it before changing a form, a " +
+        "grid or a filter — the generated `.tsx` is the disposable artifact, this is what " +
+        "produced it.");
+    out.push("");
+    out.push("- Every row here is the SAME derivation the runtime reads — `buildEntityUiDescriptor`, " +
+        "which is emitted as the `<Entity>` const in `<Entity>.meta.ts` and consumed by " +
+        "`useEntityForm`. Changing the metadata changes both. A READ-ONLY projection's const " +
+        "carries the subset that applies to it (no form, so no rules and no HTML type) plus " +
+        "the `dbCol` only a view-backed const has.");
+    out.push("- `Control` is what the FORM renders. A field declaring several views is described by " +
+        "the one named `form`; a `field.object` whose `@objectRef` resolves is not an input " +
+        "at all but a nested sub-form over that value object, and says so.");
+    out.push("- `Filter` / `Sort` are what the generated LIST endpoint accepts. `@sortable` " +
+        "defaults to `@filterable`, and the resolved answer is what is shown.");
+    out.push("");
+    for (const obj of withUi) {
+        out.push(`## \`${obj.resolutionKey()}\``);
+        out.push("");
+        const descriptor = buildEntityUiDescriptor(obj, root);
+        out.push(endpointLine(obj, root, apiPrefix));
+        out.push("");
+        if (descriptor.fields.length > 0) {
+            // The field nodes, keyed by name, so the three non-descriptor columns can be read
+            // off the field the descriptor row came from.
+            const byName = new Map(obj.fields().map((f) => [f.name, f]));
+            out.push("| Field | Label | Control | HTML type | Rules | Excluded | Filter | Sort |");
+            out.push("|---|---|---|---|---|---|---|---|");
+            for (const f of descriptor.fields) {
+                const node = byName.get(f.name);
+                const cells = [
+                    `\`${f.name}\``,
+                    mdCell(f.label),
+                    controlCell(f),
+                    htmlTypeCell(f),
+                    f.rules.map(ruleText).join(" · "),
+                    node === undefined ? "" : flag(node.attr(FIELD_ATTR_FORM_EXCLUDE)),
+                    node === undefined ? "" : flag(node.attr(FIELD_ATTR_FILTERABLE)),
+                    node === undefined ? "" : flag(isSortableField(node)),
+                ];
+                out.push(`| ${cells.join(" | ")} |`);
+            }
+            // Which value object a nested field expands into rides below the table: it is the
+            // one thing a reader needs to go and edit, and it does not fit a cell.
+            const nested = descriptor.fields.filter((f) => f.nested !== undefined);
+            if (nested.length > 0) {
+                out.push("");
+                for (const f of nested) {
+                    out.push(`- \`${f.name}\` — expands \`${f.nested?.objectRef}\`` +
+                        `${f.nested?.isArray === true ? ", one group per element" : ""}. Change the ` +
+                        "fields inside it on that value object, not here.");
+                }
+            }
+            const money = descriptor.fields.filter((f) => f.currency !== undefined);
+            if (money.length > 0) {
+                out.push("");
+                for (const f of money) {
+                    out.push(`- \`${f.name}\` — money: \`${f.currency?.currency}\` formatted for ` +
+                        `\`${f.currency?.locale}\`. Stored and sent as INTEGER MINOR UNITS; never format it server-side.`);
+                }
+            }
+        }
+        for (const grid of dataGrids(obj)) {
+            out.push("");
+            out.push(...gridSection(grid));
+        }
+        out.push("");
+    }
+    return `${out.join("\n").replace(/\n+$/, "")}\n`;
+}
+//# sourceMappingURL=agent-ui-page.js.map

package/dist/generators/agent-ui-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-ui-page.js","sourceRoot":"","sources":["../../src/generators/agent-ui-page.ts"],"names":[],"mappings":"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"}

package/dist/generators/api-docs-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-docs-file.d.ts","sourceRoot":"","sources":["../../src/generators/api-docs-file.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAa,gBAAgB,EAAe,MAAM,iBAAiB,CAAC;AA2BhF,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;qEAGiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAwEnB,gBAAgB,CAAC,eAAe,CAAC,CAAC"}
+{"version":3,"file":"api-docs-file.d.ts","sourceRoot":"","sources":["../../src/generators/api-docs-file.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAa,gBAAgB,EAAe,MAAM,iBAAiB,CAAC;AA2BhF,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;qEAGiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EA2EnB,gBAAgB,CAAC,eAAe,CAAC,CAAC"}

package/dist/generators/api-docs-file.js

@@ -18,12 +18,16 @@
 // Part 3) — so it appears in `gen --list` and is selectable by its stable name
 // `api-docs`. It is NOT a `meta docs` mode.
 //
-// It is NOT (yet) part of the default `meta gen` scaffold suite: it is
-// registry-listed but not auto-run. Turning it on by default in the scaffold,
-// and surfacing the agent form (AGENT-API.md) to a coding agent via a pointer
-// from the installed `.metaobjects/` context, are tracked as agent-context-
-// coordination follow-ups — deliberately deferred here to avoid colliding with
-// the live agent-context work.
+// It is NOT part of the default `meta gen` scaffold suite: it is registry-listed but not
+// auto-run. `meta docs` is the door that emits it.
+//
+// THE POINTER IS NO LONGER DEFERRED. This header used to record "surfacing the agent form
+// (AGENT-API.md) to a coding agent via a pointer from the installed `.metaobjects/`
+// context" as an agent-context-coordination follow-up. It was deferred, no roadmap item
+// tracked it, and for as long as that held, the page existed and nothing routed an agent
+// to it. `agent-context/templates/always-on.md.mustache` now names this file and the three
+// `agent/` pages, and says when to read each. If you rename or move this artifact, that
+// template is the other half.
 import { docPageOutputPath, surfaceCrossHref, assertNoDuplicateDocPaths, } from "../docs-paths.js";
 import { projectProvider } from "../render-engine/framework-provider.js";
 import { buildApiModel } from "./api-model.js";
@@ -66,6 +70,9 @@ export const apiDocsFile = function apiDocsFile(opts) {
                 loadedRoot: ctx.loadedRoot,
                 outputLayout: layout,
                 includeHonoRoutes: ctx.config.includeHonoRoutes ?? false,
+                // The project's prefix, because every route is mounted inside it. Without
+                // this the page documents `/authors` for routes served at `/api/authors`.
+                apiPrefix: ctx.renderContext?.apiPrefix ?? "",
                 ...(ctx.renderContext?.pkMap !== undefined && { pkMap: ctx.renderContext.pkMap }),
             });
             // Track (path, fqn) for the SAME hard collision backstop docsFile() uses —

package/dist/generators/api-docs-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-docs-file.js","sourceRoot":"","sources":["../../src/generators/api-docs-file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-docs-file.js","sourceRoot":"","sources":["../../src/generators/api-docs-file.ts"],"names":[],"mappings":"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"}

package/dist/generators/api-model.d.ts

@@ -117,6 +117,12 @@ export interface ApiModelContext {
      *  run didn't configure). The Fastify REST surface is always documented (it is
      *  the default-suite routes generator). Defaults to false. */
     includeHonoRoutes?: boolean;
+    /** The project's `apiPrefix`. Every generated route is mounted inside
+     *  `fastify.register(…, { prefix: apiPrefix })`, so it is part of the address a
+     *  documented endpoint is served at — a page that omits it is one path segment
+     *  short. Threaded explicitly rather than read off the RenderContext below,
+     *  which is a `{ pkMap }` shim and carries nothing else. Defaults to "". */
+    apiPrefix?: string;
 }
 export declare function buildApiModel(root: MetaRoot, ctx: ApiModelContext): ApiModel;
 //# sourceMappingURL=api-model.d.ts.map