@metaobjectsdev/cli 1.0.0-rc.4 → 1.0.0-rc.6

package/src/commands/verify.ts

@@ -12,12 +12,14 @@ import { parseVerifyArgs, type MigrateFlags } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { emitStructured, type OutputFormat } from "../lib/format.js";
 import {
-  antiPatternRows, ranSection, skippedSection, warnCapped,
+  antiPatternRows, missingBaseUrlRows, ranSection, skippedSection, warnCapped,
   type AdvisoryDiagnosticRow, type AdvisoryFindingRow, type AdvisorySection,
 } from "../lib/advisory.js";
 import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
+import { scanForMissingBaseUrl, type BaseUrlFinding } from "../lib/base-url-advisory.js";
+import { replayRemedy } from "../lib/replay-remedy.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
@@ -85,6 +87,7 @@ import {
   REQUIREMENT_STATUSES,
 } from "@metaobjectsdev/metadata";
 import { verify, ERR_REQUIRED_SLOT_UNUSED, ERR_PARTIAL_UNRESOLVED } from "@metaobjectsdev/render";
+import { describeLoadError, reportLoadError } from "../lib/load-error.js";
 
 const DEFAULT_PROMPTS_DIR = "prompts";
 
@@ -250,7 +253,10 @@ export async function verifyCommand(
     });
   } catch (err) {
     const msg = (err as Error).message;
-    log.error(`failed to load metadata: ${msg}`);
+    // Everything the loader's envelope carried, not just the message: the stable code a
+    // CI job keys on, and the FILE + json path the message itself can never name.
+    const report = describeLoadError(err);
+    log.error(`failed to load metadata: ${report.text}`);
     // Strict-load rejection (ADR-0023). Two different failures reach here and they need
     // different advice:
     //
@@ -263,8 +269,11 @@ export async function verifyCommand(
     // retired attribute and the author gets a green `meta verify` over a value that now
     // reaches nothing: a correct, loud failure converted into a quiet, wrong pass. That is
     // strictly worse than the error it replaced.
-    const code = (err as { code?: string }).code;
-    const suggestions = (err as { suggestions?: string[] }).suggestions;
+    // Off the REPORT, not the raw error a second time: `describeLoadError` has already
+    // decided what the envelope carried (and filtered empty entries), so re-reading the
+    // throwable would be a second answer to a question already answered above.
+    const code = report.code;
+    const suggestions = report.suggestions;
     const strictHint =
       "meta verify is strict (ADR-0023): every authored @attr must be declared. " +
       "Fix: register the attr on a metadata provider, OR move arbitrary " +
@@ -280,6 +289,14 @@ export async function verifyCommand(
     // report — only why there is none.
     emitStructured({
       error: `failed to load metadata: ${msg}`,
+      // ADR-0009 promises a stable `code`, and the docs name codes a CI job is meant to
+      // branch on — but this payload used to carry the message string and nothing else,
+      // so there was nothing to branch on. Each field is present only when the loader
+      // actually supplied it; absence here means the loader had none, never that it was
+      // dropped in transit.
+      ...(report.code !== undefined ? { code: report.code } : {}),
+      ...(report.files !== undefined ? { files: [...report.files] } : {}),
+      ...(report.jsonPath !== undefined ? { jsonPath: report.jsonPath } : {}),
       hint: suggestions !== undefined && suggestions.length > 0
         ? suggestions.join(" ")
         : isStrictAttr ? strictHint : "fix the metadata error above and re-run",
@@ -404,12 +421,23 @@ export async function verifyCommand(
       return 2;
     }
 
-    // --dialect wins; else migrate's resolved dialect; else refuse. There is no --db
-    // to infer from, so guessing would replay a postgres chain through sqlite.
-    const dialect: Dialect | undefined = flags.dialect ?? migrateConfig.dialect;
+    // --dialect wins; else migrate's resolved dialect; else the project's DECLARED
+    // dialect from metaobjects.config.ts; else refuse. There is no --db to infer
+    // from, so guessing would replay a postgres chain through sqlite.
+    //
+    // The last fallback was missing, and its absence made one fact need two
+    // spellings: a TypeScript project declares `dialect: "postgres"` in
+    // metaobjects.config.ts, `meta gen`, `meta verify --codegen` and `meta migrate`
+    // all honour it, and `--replay` alone refused and demanded `migrate.dialect` in
+    // .metaobjects/config.json — the spelling a TypeScript project is least likely
+    // to have. migrate's own resolution still WINS where it has an answer, because
+    // it is the more specific statement about the chain being replayed.
+    const dialect: Dialect | undefined =
+      flags.dialect ?? migrateConfig.dialect ?? forgeConfig?.dialect;
     if (dialect === undefined) {
       log.error(
-        `meta verify --replay: no dialect — pass --dialect <postgres|sqlite>, or set migrate.dialect in .metaobjects/config.json`,
+        `meta verify --replay: no dialect — pass --dialect <postgres|sqlite>, ` +
+          `set 'dialect' in metaobjects.config.ts, or set migrate.dialect in .metaobjects/config.json`,
       );
       return 2;
     }
@@ -438,11 +466,7 @@ export async function verifyCommand(
         applied = await applyPending(engine.db, dir, { dryRun: false, dialect });
       } catch (err) {
         log.error(`meta verify --replay: ${(err as Error).message}`);
-        log.error(
-          `meta verify --replay: the committed chain does not apply to an empty database. ` +
-            `Applied migrations are immutable, so fix this with a NEW migration that creates the ` +
-            `missing object — not by editing a committed up.sql.`,
-        );
+        for (const line of replayRemedy(err)) log.error(`meta verify --replay: ${line}`);
         return 1;
       }
 
@@ -700,13 +724,33 @@ export async function verifyCommand(
       antiPatternSection = skippedSection(`the scan failed: ${(err as Error).message}`);
       return;
     }
-    antiPatternSection = ranSection(antiPatternRows(findings));
-    if (findings.length === 0) return;
-    log.warn(
-      `meta verify — ${findings.length} place(s) hand-roll what MetaObjects can model ` +
-        `(advisory — does not fail the build):`,
-    );
-    warnCapped(findings.map((f) => `  ${f.message}`), flags.limit, { structured });
+    // F52 — the one gate that can see a provider silently missing its base. Folded into
+    // this pass rather than given its own, because it is the same KIND of finding (a
+    // teachable warning that never touches the exit code) and one --no-antipatterns
+    // should suppress the whole advisory tier, not half of it.
+    let baseUrl: BaseUrlFinding[] = [];
+    try {
+      baseUrl = scanForMissingBaseUrl(projectRoot, forgeConfig?.apiPrefix ?? "");
+    } catch {
+      // Same discipline as above: an advisory scan never breaks verify. The anti-pattern
+      // half already ran, so its rows are still reported rather than lost to this catch.
+    }
+
+    antiPatternSection = ranSection([...antiPatternRows(findings), ...missingBaseUrlRows(baseUrl)]);
+    if (findings.length > 0) {
+      log.warn(
+        `meta verify — ${findings.length} place(s) hand-roll what MetaObjects can model ` +
+          `(advisory — does not fail the build):`,
+      );
+      warnCapped(findings.map((f) => `  ${f.message}`), flags.limit, { structured });
+    }
+    if (baseUrl.length > 0) {
+      log.warn(
+        `meta verify — ${baseUrl.length} entity-fetcher provider(s) mounted with no baseUrl ` +
+          `while apiPrefix is "${forgeConfig?.apiPrefix ?? ""}" (advisory — does not fail the build):`,
+      );
+      warnCapped(baseUrl.map((f) => `  ${f.message}`), flags.limit, { structured });
+    }
   }
 
   // -- template (prompt / output) drift --------------------------------------
@@ -1189,11 +1233,11 @@ export async function verifyCommand(
           strict: !flags.lax,
         });
       } catch (err) {
-        log.error(`verify --codegen: failed to load this package's metadata: ${(err as Error).message}`);
-        // The second door onto the same strict load. It carried no remedy at all, which
-        // meant a retirement diagnosed here told the author what broke and nothing about
-        // how to fix it — the half-true rule this file's sibling comment warns about.
-        for (const s of (err as { suggestions?: string[] }).suggestions ?? []) log.error(`  ${s}`);
+        // The second door onto the same strict load, and it must carry the same provenance
+        // as the first: the ADR-0009 code, the FILE and json path the message cannot name,
+        // and the loader's own remedies. It printed a bare message plus a hand-rolled
+        // suggestions read — the half-true rule this file's sibling comment warns about.
+        reportLoadError(log, "verify --codegen: failed to load this package's metadata", err);
         return 2;
       }
     }
@@ -1212,7 +1256,11 @@ export async function verifyCommand(
     }
 
     if (result.clean) {
-      say("meta verify — generated output is in sync with the metadata (no codegen drift).");
+      // Says what it CHECKED, not more. Since 0.24.3 this gate asks whether each file's
+      // GENERATED contribution is current — a hand edit `meta gen` preserves is exempt —
+      // so "output is in sync with the metadata" claimed a stronger property than it had
+      // verified, and did so over a file whose committed content contradicted the model.
+      say("meta verify — every file's generated contribution is current (no codegen drift).");
       return 0;
     }
 
@@ -1220,15 +1268,32 @@ export async function verifyCommand(
       `meta verify — codegen drift (${result.driftedFiles.length} file(s) differ from a fresh regen):`,
     );
     for (const line of result.lines) log.error(`  ${line}`);
-    log.error("Run 'meta gen' to regenerate, then commit the result.");
+    // The remedy is PER CONVICTION KIND, not one line for the whole gate. `meta gen`
+    // fixes stale generated output; it cannot fix a hand-edited names artifact, because
+    // it MERGES the edit and exits 0 — so prescribing it there was the unbreakable loop
+    // the hand-edit exemption exists to end, reintroduced for the one file the exemption
+    // deliberately excludes. Both lines print when the drift set holds both kinds.
+    if (result.driftedFiles.length > result.handEditedNames.length) {
+      log.error("Run 'meta gen' to regenerate, then commit the result.");
+    }
+    if (result.handEditedNames.length > 0) {
+      log.error(
+        "For the names artifact(s) above, 'meta gen' will NOT help — it preserves a hand " +
+          "edit by design. Revert the edit (or delete the file and re-run 'meta gen' to " +
+          "re-emit it), and keep constants of your own in a file of your own.",
+      );
+    }
     return 1;
   }
 
   // -- docs drift -------------------------------------------------------------
   // Gated on --docs. Runs `meta docs` into a temp dir and diffs the committed docs
-  // tree. See lib/docs-drift.ts for the two deliberate differences from --codegen
-  // (a byte difference IS drift here, and a committed file a regen would not emit is
-  // never reported — `docs.outDir` is full of files MetaObjects did not write).
+  // tree. See lib/docs-drift.ts for the deliberate differences from --codegen: a byte
+  // difference IS drift here; a committed file a regen would not emit is reported ONLY
+  // under `agent/` and only when it opens with the @generated marker (`docs.outDir` is
+  // otherwise full of files MetaObjects did not write); and a page the project
+  // GIT-IGNORES is exempt, because `docs.outDir` is a directory rather than a namespace
+  // MetaObjects owns.
   //
   // It needs a config for the same reason `--codegen` does: `docs.outDir` says which
   // tree to compare against, and the `agent` surface will not even materialise
@@ -1264,21 +1329,44 @@ export async function verifyCommand(
       return 2;
     }
 
+    // What the gate did NOT check, on BOTH the passing and the failing line. A gate
+    // that quietly compared two of 589 pages and reported "no drift" would be
+    // indistinguishable from one that compared everything.
+    const notChecked =
+      result.ignoreReason !== undefined
+        ? `; .gitignore not consulted — ${result.ignoreReason} — so every page a fresh run emits was expected to be committed`
+        : result.ignored > 0
+          ? `; ${result.ignored} git-ignored page(s) not checked`
+          : "";
+
     if (result.clean) {
       // The denominator is what was actually COMPARED, so the passing line and the
       // failing line below count the same set. A gate whose two halves divide by
       // different numbers is how `verify --templates` came to report seven templates
       // vanishing between a red run and a green one.
-      say(`meta verify — ${result.checked} docs page(s) match a fresh 'meta docs' (no docs drift).`);
+      say(
+        `meta verify — ${result.checked} docs page(s) match a fresh 'meta docs' ` +
+          `(no docs drift${notChecked}).`,
+      );
       return 0;
     }
 
     log.error(
       `meta verify — docs drift (${result.driftedFiles.length} of ${result.checked} page(s) ` +
-        `differ from a fresh 'meta docs'):`,
+        `differ from a fresh 'meta docs'${notChecked}):`,
     );
     for (const line of result.lines) log.error(`  ${line}`);
     log.error("Run 'meta docs' to regenerate, then commit the result.");
+    // The one-command path to green, named at the point of conviction — a page reported
+    // as uncommitted is the one case where regenerating is NOT the answer.
+    if (result.lines.some((l) => l.startsWith("+ "))) {
+      log.error(
+        result.ignoreReason === undefined
+          ? "A page you deliberately do not commit is exempt once it is git-ignored."
+          : `.gitignore was not consulted (${result.ignoreReason}), so a page you ` +
+            `deliberately do not commit is reported above.`,
+      );
+    }
     return 1;
   }
 }

package/src/index.ts

@@ -55,6 +55,14 @@ GLOBAL OPTIONS:
 
 GEN FLAGS:
   --dry-run             Compute and print, don't write
+  --list                Print the generator registry (name, tier, options) and exit —
+                        no config or metadata required
+  --baseline <default|adopt|fresh>
+                        First-time-on-existing-file behavior. Default: refuse a file that
+                        cannot be proved to be generated output. "adopt" records the files
+                        you have as the merge base and writes NOTHING — the first run a
+                        project with no committed .hashes.json can perform. "fresh"
+                        overwrites them with fresh output and re-baselines (discards edits).
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --limit <n|all>       How many advisory lines TEXT output prints before it truncates
                         (default 20). Never applies to --format toon/json, which
@@ -69,7 +77,11 @@ DOCS FLAGS:
   [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
                         your metadata, NOT the metadata directory. Passing it SCOPES the run
                         (default: cwd)
-  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
+                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
+                        for a directory that persists, which is what 'meta verify --docs'
+                        measures. The default is a sub-directory on purpose: these pages are
+                        regenerated and overwritten, and 'docs/' itself is usually yours.
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
   --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
 
@@ -127,7 +139,7 @@ ship in later sub-projects. See https://metaobjects.com for docs.
 `;
 
 /** Focused per-subcommand usage slices shown by `<cmd> --help`. */
-const COMMAND_HELP: Record<string, string> = {
+export const COMMAND_HELP: Record<string, string> = {
   gen: `meta gen — codegen TS targets from your declared metadata
 
 USAGE:
@@ -135,6 +147,14 @@ USAGE:
 
 FLAGS:
   --dry-run             Compute and print, don't write
+  --list                Print the generator registry (name, tier, options) and exit —
+                        no config or metadata required
+  --baseline <default|adopt|fresh>
+                        First-time-on-existing-file behavior. Default: refuse a file that
+                        cannot be proved to be generated output. "adopt" records the files
+                        you have as the merge base and writes NOTHING — the first run a
+                        project with no committed .hashes.json can perform. "fresh"
+                        overwrites them with fresh output and re-baselines (discards edits).
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --limit <n|all>       Advisory lines TEXT output prints before truncating (default 20)
   --format <toon|json|text>   Output format (global flag; default toon off-TTY)
@@ -179,10 +199,17 @@ USAGE:
 
 FLAGS:
   --templates           Template/prompt {{field}}↔payload drift (default when bare)
-  --codegen             Codegen drift — regenerate to temp dir and diff committed output
+  --codegen             Codegen drift — is the GENERATED contribution current? A hand
+                        edit 'meta gen' preserves is not drift; a stale generated part is.
+                        An <Entity>.names.ts artifact is the exception: it must match a
+                        fresh regen exactly — a hand edit in it is itself the defect.
                         Needs metaobjects.config.ts; exit 2 if absent.
   --docs                Docs drift — run 'meta docs' to a temp dir and diff docs.outDir
-                        Needs metaobjects.config.ts; exit 2 if absent.
+                        Needs metaobjects.config.ts; exit 2 if absent. A page the
+                        project GIT-IGNORES is exempt (docs.outDir is a directory, not
+                        a namespace MetaObjects owns); the count of exempt pages is
+                        reported either way, and a run where every page is ignored is
+                        refused rather than reported clean.
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
@@ -204,6 +231,10 @@ FLAGS:
   --d1 <binding>        D1 binding name from wrangler.toml (only with --dialect d1)
   --remote              Target remote D1 instead of local (only with --dialect d1) —
                         the ONLY way to verify the actual deployed D1 database
+  --lax                 Load with the legacy OPEN attribute set instead of strict
+                        (ADR-0023). Strict is the default: an undeclared or typo'd own
+                        @attr fails verify with ERR_UNKNOWN_ATTR. Use only while
+                        migrating a model onto a registered provider.
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
   --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
@@ -249,7 +280,11 @@ FLAGS:
                         it SCOPES the run to that directory's own sources; no ancestor
                         .metaobjects/config.json is consulted. Omitted (default), the project
                         is discovered by walking up.
-  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
+                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
+                        for a directory that persists, which is what 'meta verify --docs'
+                        measures. The default is a sub-directory on purpose: these pages are
+                        regenerated and overwritten, and 'docs/' itself is usually yours.
   --model               Emit the markdown model surface (entity + template pages)
   --api                 Emit the markdown api surface (generated SDK reference)
   --requirements        Emit the declared requirement ledger (requirements.md + .toon).
@@ -258,7 +293,9 @@ FLAGS:
                         agent/ui.md (the generated forms and grids) and
                         agent/requirements.md (the ledger plus a claimed-node index).
                         Needs metaobjects.config.ts (the dialect and physical names come
-                        from it); each page is skipped when its tier has nothing to describe.
+                        from it); each page is skipped when its tier has nothing to describe
+                        — agent/ui.md needs a UI generator (a form, hook or grid) in the
+                        suite, not merely objects that could have one.
   --metamodel           Document the built-in metamodel vocabulary (no metadata needed)
   --site                Generate the browsable HTML documentation site (<out>/site/)
   --scaffold-site       Copy the site's templates + assets into codegen/docs-site/ to own (theme) them
@@ -274,6 +311,16 @@ USAGE:
 
 FLAGS:
   --refresh-docs        Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
+  --docs-only           Write only the agent-context files — no metadata sources, no
+                        codegen scaffold, no config. Pair with --refresh-docs to update
+                        an existing project after upgrading.
+  --server <lang>       Declare a server language for the agent context (repeatable):
+                        typescript | java | kotlin | csharp | python
+                        ('node' is accepted as an alias for typescript; an unknown
+                        value is refused, never dropped)
+  --client <fw>         Declare a client framework for the agent context (repeatable):
+                        react | tanstack | angular
+  --no-skills           Skip the .claude/skills/ scaffold
   --force               Overwrite existing files
   --quiet               Suppress output
   --print-only          Print what would be written, don't write
@@ -289,8 +336,8 @@ USAGE:
   meta agent-docs [--server <lang>]... [--client <fw>]... [--out <dir>] [flags]
 
 FLAGS:
-  --server <lang>       Server language (repeatable; e.g. csharp, kotlin, python, node)
-  --client <fw>         Client framework (repeatable; e.g. react, vue)
+  --server <lang>       Server language (repeatable): typescript|java|kotlin|csharp|python
+  --client <fw>         Client framework (repeatable): react|tanstack|angular
   --out <dir>           Output directory (default: current directory)
   --no-skills           Skip .claude/skills/ scaffold
   --no-wire-root        Skip wiring root CLAUDE.md @import

package/src/lib/advisory.ts

@@ -22,6 +22,7 @@
 
 import { log } from "./log.js";
 import type { AntiPatternFinding } from "./anti-patterns.js";
+import type { BaseUrlFinding } from "./base-url-advisory.js";
 
 /**
  * How many advisory lines TEXT output prints before it truncates.
@@ -119,6 +120,20 @@ export function antiPatternRows(findings: readonly AntiPatternFinding[]): Adviso
   }));
 }
 
+/**
+ * F52 findings in the same row shape, so the structured payload has ONE advisory list
+ * rather than a second one a consumer has to learn about. `rule` is the discriminator.
+ */
+export function missingBaseUrlRows(findings: readonly BaseUrlFinding[]): AdvisoryFindingRow[] {
+  return findings.map((f) => ({
+    file: f.file,
+    line: f.line,
+    rule: "missing-base-url",
+    construct: f.construct,
+    message: f.message,
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // text output
 // ---------------------------------------------------------------------------

package/src/lib/anti-patterns.ts

@@ -16,7 +16,8 @@
 // nag a legitimate one.
 
 import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative, sep } from "node:path";
+import { join } from "node:path";
+import { relPosix } from "./rel-posix.js";
 
 export interface AntiPatternFinding {
   file: string; // path relative to the scan root (posix-ish, sep-normalized)
@@ -220,10 +221,6 @@ function findingFor(file: string, lineNo: number, raw: string, isSql: boolean):
   };
 }
 
-function relPosix(root: string, abs: string): string {
-  return relative(root, abs).split(sep).join("/");
-}
-
 function walk(dir: string, root: string, ignore: readonly RegExp[], acc: AntiPatternFinding[]): void {
   let entries;
   try {