@metaobjectsdev/codegen-ts 1.0.0-rc.5 → 1.0.0-rc.7

package/src/index.ts

@@ -8,6 +8,10 @@ export type { RunGenOpts, RunGenResult } from "./runner.js";
 
 export type { Generator, GenContext, EmittedFile, GeneratorFactory } from "./generator.js";
 export { perEntity, perPackage, perModel, oncePerRun } from "./generator.js";
+// The one aggregation of the UI-tier markers. Exported because `meta docs` is the
+// SECOND door onto `agent/ui.md` and must answer "does this run emit a UI tier?"
+// with the same function the gen runner uses, not a second derivation of it.
+export { runEmitsUiTier, runEmitsHonoRoutes, UI_TIER_GENERATOR_NAMES } from "./ui-tier-gate.js";
 
 // SP-1 declarative Mustache template-codegen — scope walks, neutral data dict,
 // output-pattern, and the JSON template-spec the CLI ports reuse.
@@ -42,7 +46,7 @@ export { defineConfig, normalizeConfig, resolveGenerators, resolveDocsConfig } f
 // The dialect every generator falls back to when a config declares none. Exported because
 // `meta docs` must apply the SAME default `normalizeConfig` does — a command that resolved
 // the dialect differently would document a schema the toolchain does not produce.
-export { DEFAULT_DIALECT } from "./metaobjects-config.js";
+export { DEFAULT_DIALECT, DEFAULT_DOCS_DIR } from "./metaobjects-config.js";
 // The runner's own "does this model need a dialect?" guard. `meta docs` must ask it rather
 // than defaulting, because DEFAULT_DIALECT is inert and a DB project with no dialect is one
 // `meta gen` REFUSES — documenting it as sqlite states an answer the toolchain never gave.
@@ -78,7 +82,7 @@ export { decideAndWrite, GitMissingError, WRITE_STATUSES } from "./overwrite-pol
 export { contentHash, readGeneratedHash, listGeneratedPaths } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
-export { GENERATED_HEADER, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, type RetiredCodegenAttr } from "./constants.js";
+export { GENERATED_HEADER, NAMES_FILE_SUFFIX, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, type RetiredCodegenAttr } from "./constants.js";
 export { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 
 export { formatTs } from "./format.js";

package/src/metaobjects-config.ts

@@ -63,6 +63,11 @@ export interface ResolvedGenConfig {
    *  Undefined ⇒ false. Templates read the same fact off `RenderContext.includeNames`,
    *  which the runner sets from this same aggregation. */
   includeNames?: boolean;
+  /** Whether any CLIENT UI generator (form, hook, grid, columns) is active in the
+   *  run — aggregated by the runner from the suite's `emitsUiTier` markers.
+   *  `agent/ui.md` reads this to decide whether a UI tier exists to describe;
+   *  a metadata predicate can only say a UI *could* be generated. Undefined ⇒ false. */
+  includeUiTier?: boolean;
   /**
    * FR-019 / ADR-0026: the module specifier from which an externally-PROVIDED
    * shared enum (`@provided: true` on an abstract package-level `field.enum`) is
@@ -289,13 +294,27 @@ export interface ResolvedDocsConfig {
 /** Merge the config `docs:` block with CLI overrides over documented defaults.
  *  `fallbackLayout` is the project's `outputLayout` so docs default to the same
  *  page placement as codegen when `docs.layout` is unset. */
+/**
+ * Where `meta docs` writes when nothing says otherwise. A SUB-directory on purpose: the
+ * generated pages are MetaObjects' to own and overwrite, and `docs/` as a whole is not.
+ */
+export const DEFAULT_DOCS_DIR = "./docs/generated";
+
 export function resolveDocsConfig(
   block: DocsConfig | undefined,
   cli: Partial<ResolvedDocsConfig>,
   fallbackLayout: OutputLayout,
 ): ResolvedDocsConfig {
   return {
-    outDir: cli.outDir ?? block?.outDir ?? "./docs",
+    // F57 — NOT "./docs". `docs/` is the human documentation folder in most repos: one
+    // estate's held a business-strategy .docx, product screenshots, email drafts and an
+    // analytics roadmap, and a bare `meta docs` scattered 29 generated pages through it
+    // and wanted to own `docs/README.md`. The gate's own design language is right —
+    // "docs.outDir is a directory, not a namespace MetaObjects owns" — and that is
+    // precisely the argument for not defaulting into the most-owned directory name in
+    // the ecosystem. `meta init` scaffolds this key explicitly so a new project's choice
+    // is visible rather than implied.
+    outDir: cli.outDir ?? block?.outDir ?? DEFAULT_DOCS_DIR,
     layout: cli.layout ?? block?.layout ?? fallbackLayout,
     baseUrl: cli.baseUrl ?? block?.baseUrl ?? "",
     // `requirements` defaults ON. Safe ONLY because requirementsFile() emits ZERO

package/src/overwrite-policy.ts

@@ -60,6 +60,12 @@ export const WRITE_STATUSES = [
   "conflict",
   "refused",
   "skipped",
+  /** `--baseline=adopt` — the file WOULD have been refused, and instead its current
+   *  content was recorded as the merge base. Nothing was written. Its own status
+   *  rather than "unchanged" or "skipped" because the run's whole product is the
+   *  manifest it just created: a summary that reported these as unchanged would
+   *  hide the one thing the adopter has to commit. */
+  "adopted",
   /** FR-038 §8 — deleted because it was generated by a previous run, is no longer
    *  generated, and was never edited by hand. Reported as a file outcome rather
    *  than a warning because a deletion is exactly as consequential as a write,
@@ -81,8 +87,20 @@ export type MergeStrategy = "overwrite" | "skip-existing";
 /** "default" — the standard three-way merge flow described in the file header.
  *  "fresh" — opt-in via `meta gen --baseline=fresh`. When .gen-state is absent
  *  but the file exists, OVERWRITE with fresh content and seed .gen-state from
- *  the fresh content (caveat 3 escape hatch). */
-export type BaselineMode = "default" | "fresh";
+ *  the fresh content (caveat 3 escape hatch).
+ *  "adopt" — opt-in via `meta gen --baseline=adopt`. Same population, opposite
+ *  half: where the run would REFUSE, record the file's CURRENT content as the
+ *  merge base and write nothing. It exists because the refusal's leading remedy
+ *  ("commit .hashes.json") could not be performed by the population it named —
+ *  nothing writes a manifest until a gen succeeds, and gen refuses until one
+ *  exists. `adopt` is the run that produces the file to commit.
+ *
+ *  What it is NOT: protection for an edit already inside one of those files. The
+ *  base becomes the edited text, so base == ours and the next regen's three-way
+ *  merge takes fresh output wholesale. It protects edits made FROM THEN ON, and
+ *  it guarantees that establishing the baseline writes nothing — which is what
+ *  lets the content change land as its own reviewable diff afterwards. */
+export type BaselineMode = "default" | "fresh" | "adopt";
 
 export interface DecideAndWriteOpts {
   strategy?: MergeStrategy;
@@ -468,6 +486,7 @@ type WriteCase =
   | { kind: "no-snapshot-unchanged" }
   | { kind: "no-snapshot-pristine-overwrite" }
   | { kind: "no-snapshot-refused"; hasRecord: boolean }
+  | { kind: "no-snapshot-adopt"; currentText: string }
   | { kind: "snapshot-unchanged" }
   | { kind: "snapshot-merge-required"; snapshotText: string };
 
@@ -521,6 +540,18 @@ function classifyWrite(
 
     // Either somebody edited it (hash mismatch) or we have no record of writing
     // it at all (no hash). Both are unprovable, so fail closed.
+    //
+    // …unless the caller has explicitly adopted what is on disk. `adopt` is placed
+    // HERE, at the refusal, rather than at the top of the no-snapshot branch, and
+    // that placement is the design: it means adopting can only ever convert a
+    // refusal into a recorded baseline. Everything else — unchanged, and the
+    // pristine-file overwrite a fresh clone depends on — keeps behaving exactly as
+    // it does without the flag, so a project cannot accidentally freeze its
+    // regeneration by passing it.
+    if ((opts.baseline ?? "default") === "adopt") {
+      return { kind: "no-snapshot-adopt", currentText: current };
+    }
+
     return {
       kind: "no-snapshot-refused",
       hasRecord: readGeneratedHash(genStateDir, relPath) !== undefined,
@@ -570,6 +601,8 @@ export function previewWriteStatus(
       return "overwrite";
     case "no-snapshot-refused":
       return "refused";
+    case "no-snapshot-adopt":
+      return "adopted";
     case "snapshot-merge-required":
       return "overwrite";
   }
@@ -641,6 +674,14 @@ export function decideAndWrite(
             "--baseline=fresh to overwrite it and adopt fresh output as the baseline.",
       };
 
+    case "no-snapshot-adopt":
+      // Record what is ON DISK — deliberately `kase.currentText`, never `content`.
+      // Recording fresh output would claim we wrote a file we did not, and the next
+      // run would then read the adopter's file as edited-since-generated and refuse
+      // all over again, which is the loop this mode exists to end.
+      advanceSnapshot(genStateDir, relPath, kase.currentText);
+      return { path, status: "adopted" };
+
     case "snapshot-unchanged":
       return { path, status: "unchanged" };
 

package/src/reference/names.ts

@@ -36,6 +36,7 @@ import {
   namesArtifactSuperOf,
   renderNamesDecl,
   resolveObjectNames,
+  NAMES_FILE_SUFFIX,
   type EmittedFile,
   type GenContext,
   type Generator,
@@ -78,7 +79,10 @@ export function namesFile(opts?: NamesFileOpts): Generator {
         // its entity sits at <pkg>/<Entity>.ts — an unresolvable import, and a hard
         // conflicting-duplicate-path failure as soon as two packages declare a
         // same-bare-named entity.
-        entityOutputPath(layout, effectivePackage(obj), `${obj.name}.names.ts`);
+        // NAMES_FILE_SUFFIX, not a literal: `meta verify --codegen` treats this artifact as
+        // fail-closed (a hand edit in it IS drift, unlike every other generated file) and
+        // recognises it BY THIS SUFFIX. Rename it and you opt out of that protection.
+        entityOutputPath(layout, effectivePackage(obj), `${obj.name}${NAMES_FILE_SUFFIX}`);
 
       const superSpecifierFor = (obj: MetaObject): string | undefined => {
         const sup = namesArtifactSuperOf(obj);

package/src/runner.ts

@@ -1,5 +1,6 @@
 import { join, relative, resolve, isAbsolute, dirname } from "node:path";
 import { warnMissingPromptGenerators } from "./prompt-generator-gate.js";
+import { runEmitsHonoRoutes, runEmitsUiTier, warnUnmarkedUiGenerators } from "./ui-tier-gate.js";
 import { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -469,7 +470,20 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // Auto-detect: is the OPT-IN Hono routes generator in the active suite? If so,
   // surface it on every generator's ctx.config so api-docs documents the Hono
   // CRUD surface it actually emits (rather than silently omitting it).
-  const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
+  // The explicit config key WINS over the marker aggregation, at both doors. `meta docs`
+  // already read `loadedConfig?.includeHonoRoutes ?? …`, and the runner did not — so an
+  // adopter who set the key got the surface documented and not emitted, or the reverse.
+  // The key is settable because `MetaobjectsGenConfig extends Omit<ResolvedGenConfig,…>`,
+  // and it is the escape hatch for an owned generator whose name was changed; an escape
+  // hatch honoured by one of two doors is the defect these flags exist to close.
+  const includeHonoRoutes = config.includeHonoRoutes ?? runEmitsHonoRoutes(config.generators);
+
+  // Same auto-detection for the CLIENT UI tier. `agent/ui.md` describes forms, grids
+  // and the endpoints their hooks call; whether any of that is emitted is a generator
+  // fact, and the page's own gate could only see metadata. Run-scoped like
+  // includeHonoRoutes — the page asks "is this surface in the run?", never "does it
+  // land in my target?".
+  const includeUiTier = config.includeUiTier ?? runEmitsUiTier(config.generators);
 
   // §A6 — same auto-detection for the OPT-IN names generator. The entity tier may only
   // REFERENCE `<Entity>Names` when something in this run actually emits it; the names
@@ -493,6 +507,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // this, said nothing — while `meta verify` reported the template "clean". See
   // prompt-generator-gate.ts. Self-extinguishing; warning only.
   warnMissingPromptGenerators(root, config.generators, (m) => warnings.push(m));
+  warnUnmarkedUiGenerators(config.generators, (m) => warnings.push(m));
 
   // <Entity>Names is opt-in on TypeScript and an existing project gets no signal that
   // it exists. Fires ONCE, on the first gen after crossing the release that made it the
@@ -598,6 +613,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         outputLayout: selfTarget.outputLayout,
         includeHonoRoutes,
         includeNames: namesTargets.has(selfTarget.name),
+        includeUiTier,
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),
@@ -719,10 +735,15 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         `no codegen hash manifest — so 'meta gen' cannot tell your edits from its own ` +
         `stale output, and it will not guess. This is the expected first run for a ` +
         `project created before the manifest was committed. ` +
-        `ONE-TIME FIX: commit '.metaobjects/.gen-state/.hashes.json' (un-ignore it in ` +
-        `.metaobjects/.gitignore with '.gen-state/*' + '!.gen-state/.hashes.json'), ` +
-        `then re-run. To adopt fresh output and DISCARD any hand edits in these files ` +
-        `instead, re-run with --baseline=fresh. Files: ${names.join(", ")}${more}.`,
+        `ONE-TIME FIX: re-run with --baseline=adopt — it records the files you have as ` +
+        `the merge base and writes NOTHING — then commit ` +
+        `'.metaobjects/.gen-state/.hashes.json' (un-ignore it in .metaobjects/.gitignore ` +
+        `with '.gen-state/*' + '!.gen-state/.hashes.json') and run 'meta gen' again, where ` +
+        `the regeneration arrives as its own reviewable diff. Adopting DECLARES these files ` +
+        `to be generated output, so an edit already inside one of them is part of the ` +
+        `baseline and that regeneration will replace it — commit before you run it. ` +
+        `To write fresh output NOW and DISCARD any hand edits in these files, ` +
+        `--baseline=fresh does both in one step. Files: ${names.join(", ")}${more}.`,
       );
       return;
     }
@@ -762,6 +783,28 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     );
   };
 
+  // `--baseline=adopt` — the counterpart of the aggregate above, and aggregated for the
+  // same reason: every adopted file has one cause and one next step. Reported even though
+  // nothing failed, because a run that writes nothing and exits 0 is otherwise
+  // indistinguishable from a no-op, and the file it DID produce (`.hashes.json`) is the
+  // one the adopter now has to commit.
+  const reportAdoptions = (): void => {
+    const adopted = writes.filter((w) => w.status === "adopted");
+    if (adopted.length === 0) return;
+    const names = adopted.slice(0, MAX_NAMED).map((w) => relativeForDisplay(w.path));
+    const more = adopted.length > MAX_NAMED ? `, and ${adopted.length - MAX_NAMED} more` : "";
+    warnings.push(
+      `Recorded ${adopted.length} existing file(s) as the codegen baseline and wrote ` +
+      `nothing. NEXT: commit '.metaobjects/.gen-state/.hashes.json' (un-ignore it in ` +
+      `.metaobjects/.gitignore with '.gen-state/*' + '!.gen-state/.hashes.json'), then run ` +
+      `'meta gen' — these files regenerate normally from here, as their own reviewable ` +
+      `diff. Adopting DECLARED them to be generated output: an edit already inside one is ` +
+      `part of the baseline and that regeneration will replace it, so check the diff ` +
+      `against git. Edits you make FROM NOW ON merge, because the base now exists. ` +
+      `Files: ${names.join(", ")}${more}.`,
+    );
+  };
+
   const sweep = (dryRun: boolean): void => {
     if (projectRoot === undefined || orphanJobs.length === 0) return;
 
@@ -863,6 +906,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       });
     }
     reportRefusals();
+    reportAdoptions();
     // A preview that hides a pending deletion is worse than no preview at all, so
     // the sweep still runs — in decide-and-report mode, touching nothing.
     sweep(true);
@@ -896,6 +940,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   }
 
   reportRefusals();
+  reportAdoptions();
 
   // Sweep AFTER the writes: writing is the primary job, and a deletion that runs
   // first would be unrecoverable if a later write threw. Ordering cannot change

package/src/ui-tier-gate.ts

@@ -0,0 +1,79 @@
+import type { Generator } from "./generator.js";
+
+/**
+ * Generators that emit a CLIENT UI artifact — a form, a hook, a grid or its columns.
+ *
+ * Names, not identities, for the same reason `PROMPT_GENERATOR_NAMES` uses names: under
+ * ADR-0034 scaffold-and-own an adopter runs their OWN copy, and `meta eject` copies the
+ * template verbatim, so the name survives the copy while the object identity does not.
+ *
+ * This set exists ONLY as a compatibility path for a copy ejected before `emitsUiTier`
+ * existed. The marker is the mechanism; a name match makes the run behave as it did
+ * before AND says the marker is missing (see {@link warnUnmarkedUiGenerators}), because
+ * a page silently disappearing is exactly the kind of degradation that must announce
+ * itself.
+ */
+export const UI_TIER_GENERATOR_NAMES: ReadonlySet<string> = new Set([
+  "form-file",
+  "tanstack-query",
+  "tanstack-grid",
+  "tanstack-grid-hook",
+  "angular-form",
+  "angular-grid",
+  "angular-service",
+]);
+
+/** Generators in the suite that emit a UI artifact but carry no `emitsUiTier` marker. */
+function unmarked(generators: readonly Generator[]): Generator[] {
+  return generators.filter(
+    (g) => g.emitsUiTier !== true && UI_TIER_GENERATOR_NAMES.has(g.name),
+  );
+}
+
+/**
+ * Does this run emit a client UI tier?
+ *
+ * The declared marker OR the legacy name. `agent/ui.md` gates on the answer: its own
+ * predicate was metadata-only (`servesReadApi`), which says a UI *could* be generated
+ * for an object and never that this run generates one — so a project with
+ * `generators: []` was handed a confident page naming endpoints nothing serves.
+ */
+export function runEmitsUiTier(generators: readonly Generator[]): boolean {
+  return generators.some((g) => g.emitsUiTier === true) || unmarked(generators).length > 0;
+}
+
+/**
+ * A generator ejected before `emitsUiTier` existed still emits its tier, so the run is
+ * NOT degraded — the name match above keeps `agent/ui.md` emitting. It is warned about
+ * anyway: an adopter who renames their copy loses the page with no signal at all, and
+ * the one-line fix belongs where the fact is known rather than in a migration note
+ * nobody re-reads. Self-extinguishing — adding the marker silences it forever.
+ */
+export function warnUnmarkedUiGenerators(
+  generators: readonly Generator[],
+  warn: (msg: string) => void,
+): void {
+  const stale = unmarked(generators);
+  if (stale.length === 0) return;
+  const names = stale.map((g) => `'${g.name}'`).join(", ");
+  warn(
+    `${names} emit${stale.length === 1 ? "s" : ""} a UI artifact but carr${stale.length === 1 ? "ies" : "y"} no ` +
+      `'emitsUiTier: true' marker — an owned copy ejected before the marker existed. ` +
+      `agent/ui.md still emits (matched by name), but a renamed copy would not: add ` +
+      `'emitsUiTier: true' beside 'name:' in your copy, or re-eject it.`,
+  );
+}
+
+/**
+ * Does this run emit the OPT-IN Hono routes surface?
+ *
+ * Lives beside `runEmitsUiTier` for one reason: both are "aggregate a marker across the
+ * suite", and both were being re-derived at the `meta docs` door — which read the RAW
+ * config, where a generator wired by stable name (`generators: ["routes-hono"]`, legal
+ * under ADR-0021 #1) is a string carrying no marker at all. So `api-docs` omitted the
+ * Hono surface for a project that had wired it. One helper, called after the strings are
+ * resolved, is what stops the two doors disagreeing again.
+ */
+export function runEmitsHonoRoutes(generators: readonly Generator[]): boolean {
+  return generators.some((g) => g.emitsHonoRoutes === true);
+}