@ultimat3/cli 7.0.0 → 9.0.0

package/src/templates/scaffold-entries.ts

@@ -0,0 +1,131 @@
+// The two entry files a deploy needs — `apps/web/server.ts` and `apps/web/prerender.ts`. Split out
+// of `scaffold-app.ts` because that file is the three SURFACES and these are neither: they are what
+// a container starts and what a CDN is handed. Both are deliberately thin — which role a container
+// is, which port it binds, how it drains and what a static build enumerates are the framework's
+// answers, so an upgrade moves them without a codemod in every app that ever shipped.
+
+import type { GeneratedFile } from './naming';
+
+const server =
+  (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
+// ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
+// applies the migrations and exits. PORT is bound on every interface, because a container bound to
+// localhost is unreachable through its own port mapping.
+
+import { join } from 'node:path';
+import { runRole } from '@ultimat3/cli';
+
+// MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
+//
+//   import { configureIdempotency } from '@ultimat3/action';
+//   configureIdempotency({ scope: 'shared' });
+//
+// \`idempotent: true\` on an action promises that a retry does not repeat the work. Under the
+// process-scoped default that promise holds inside ONE process — a client retrying
+// \`POST /api/payments/charge\` after a timeout lands on another replica, which has never seen the
+// key, and charges the card twice, silently, with \`x verify\` green. Declaring \`'shared'\` is what
+// makes that a boot error (\`X_IDEMPOTENCY_NOT_SHARED\`) unless a shared store is installed.
+// \`runRole\` installs the Postgres one for you, on the connection it resolved from \`DATABASE_URL\`,
+// so the declaration is all this app owes. It must run before \`runRole\` imports the actions.
+
+/**
+ * Where the app is. From this file normally — the image's WORKDIR is not the app root's business.
+ * A \`--compile\` binary is the exception: its \`import.meta.dir\` is Bun's virtual filesystem, which
+ * holds this module's bundled imports and none of the app's source, and the framework's registries
+ * are filled by scanning that source at boot. So a binary reads its root from the directory it is
+ * started in — it is a launcher for an app tree, not a self-contained copy of one.
+ */
+const root = import.meta.dir.startsWith('/$bunfs')
+  ? process.cwd()
+  : join(import.meta.dir, '..', '..');
+
+// Guarded, because the framework's module scan imports every file under apps/*/ to fill its
+// registries — an unguarded boot would start a server inside \`x verify\`.
+if (import.meta.main) {
+  await runRole({ root, env: Bun.env });
+}
+`;
+
+const prerender =
+  (): string => `// The static entry. \`x build --target static\` runs this with \`--out <dir>\` and it writes one HTML
+// file per \`render: 'static'\` route — a CDN or an object store then serves site/ with no process
+// behind it. Every other render mode needs a running app and is reported as skipped, never emitted.
+//
+// Skipped is not unweighed: a route that declares a \`budget:\` is rendered in memory and measured
+// whatever its mode, so \`x verify\`'s \`budgets\` step has a number for it. \`unmeasured\` is the list
+// this build could not render — each one is an X_BUDGET_UNMEASURED at the gate, and this is where
+// the reason is.
+//
+// It writes the whole of \`pages\` and \`skipped\`, never a COUNT of either. A count is what let a
+// partial artifact read as a complete one: someone pointed a screenshot tool at \`.x/static\` and
+// filed "the island did not mount" against a route that had never been emitted (issue #242). Each
+// skipped route carries its own \`reason\` and \`why\`, and \`report\` is where the same inventory
+// landed on disk — which is what \`x build --target static --json\` reads back.
+
+import { join } from 'node:path';
+import { DEFAULT_ORIGIN, type PrerenderReport, prerenderSite } from '@ultimat3/cli';
+import { routeEntries } from '@ultimat3/render';
+import { buildRobots, buildSitemap, type RouteRecord } from '@ultimat3/seo';
+
+const root = join(import.meta.dir, '..', '..');
+const flag = Bun.argv.indexOf('--out');
+const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', 'static');
+// SITE_ORIGIN is what canonical and og:url are built from; the default is only ever a local build.
+// Property access, not \`Bun.env['SITE_ORIGIN']\`: the scaffolded tsconfig does not set
+// \`noPropertyAccessFromIndexSignature\`, so the bracket form is the one biome's useLiteralKeys
+// reports — a diagnostic in an app's first lint run over a file the app never wrote.
+const origin = Bun.env.SITE_ORIGIN;
+
+/**
+ * The route table as \`@ultimat3/seo\` reads it. \`RouteRecord\` is a static row and \`defineRoute\`
+ * is a live declaration, so one has to be projected onto the other — and \`prerenderSite\` has
+ * already loaded the app by the time this runs, which is what fills \`routeEntries()\`.
+ *
+ * A DYNAMIC route contributes exactly the URLs this build enumerated for it, read back off the
+ * report rather than by calling \`prerender()\` a second time: the sitemap then cannot name a page
+ * the artifact does not contain, which is the only failure mode a sitemap really has.
+ */
+const siteRoutes = (report: PrerenderReport): readonly RouteRecord[] =>
+  routeEntries()
+    .filter((entry) => entry.surface === 'site')
+    .map((entry) => ({
+      path: entry.path,
+      file: entry.file,
+      surface: 'site' as const,
+      render: entry.config.render,
+      prerender: () =>
+        report.pages.filter((page) => page.route === entry.path).map((page) => page.path),
+    }));
+
+/**
+ * \`sitemap.xml\` and \`robots.txt\`, into the same directory the HTML went. Both belong to the
+ * ARTIFACT rather than to a request: a static export is served with no process behind it, so a
+ * route that answered them at run time would be a file the CDN never has.
+ *
+ * \`buildRobots\` fails closed — anything that is not \`ULTIMATE_ENV=production\` emits
+ * \`Disallow: /\` and advertises no sitemap — so a preview build cannot outrank the real site.
+ */
+async function writeSeoFiles(report: PrerenderReport, baseUrl: string): Promise<readonly string[]> {
+  const sitemap = await buildSitemap(siteRoutes(report), { baseUrl });
+  // Past 50,000 URLs \`files\` are \`/sitemap-N.xml\` and the index is \`/sitemap.xml\`; below it,
+  // \`files\` is that one file and there is no index. Writing both lists covers each case once.
+  const written = sitemap.index === undefined ? sitemap.files : [sitemap.index, ...sitemap.files];
+  for (const file of written) await Bun.write(join(out, file.path), file.xml);
+  await Bun.write(join(out, 'robots.txt'), buildRobots({ baseUrl, sitemaps: ['/sitemap.xml'] }));
+  return [...written.map((file) => file.path), '/robots.txt'];
+}
+
+if (import.meta.main) {
+  const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
+  const seo = await writeSeoFiles(report, origin ?? DEFAULT_ORIGIN);
+  await Bun.stdout.write(
+    \`\${JSON.stringify({ ok: true, out: report.out, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report, seo })}\\n\`,
+  );
+}
+`;
+
+/** The two files, in the order a deploy meets them: the process, then the artifact. */
+export const entryFiles = (): readonly GeneratedFile[] => [
+  { path: 'apps/web/server.ts', contents: server() },
+  { path: 'apps/web/prerender.ts', contents: prerender() },
+];

package/src/templates/scaffold-guards.ts

@@ -0,0 +1,26 @@
+// The `guards/` directory `x new` writes, and the one list that names every guard in it.
+//
+// `x new` shipped ZERO guards while the `AGENTS.md` it writes stated nine non-negotiables — five of
+// which nothing enforced, each measured green on `x verify` in a scaffolded app. The mechanism was
+// never missing: `guards/` is discovered, not registered, and runs inside the `boundaries` step
+// (`packages/cli/src/guards.ts`). What was missing is any guard to discover. Four of the five are
+// here; the fifth, money-as-float, has no static signature and is answered by the `Money` type
+// instead — `scaffold-docs.ts` says so where an author reads it.
+
+import { bareErrorGuardFiles } from './guard-bare-error';
+import { rawColourGuardFiles } from './guard-raw-colour';
+import { untranslatedStringGuardFiles } from './guard-untranslated-string';
+import { unzonedDateGuardFiles } from './guard-unzoned-date';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Every guard `x new` ships, each with its test. One module per guard, because an app deletes a
+ * rule it does not want by deleting one file — and a guard the app then writes for itself is
+ * `x g guard <name>`, the same shape.
+ */
+export const scaffoldGuardFiles = (): readonly GeneratedFile[] => [
+  ...bareErrorGuardFiles(),
+  ...rawColourGuardFiles(),
+  ...untranslatedStringGuardFiles(),
+  ...unzonedDateGuardFiles(),
+];

package/src/templates/scaffold-repo.ts

@@ -12,6 +12,7 @@ import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
 import { domainPackageFiles } from './scaffold-domain-package';
 import { envExampleSource, envSchemaSource } from './scaffold-env';
+import { scaffoldGuardFiles } from './scaffold-guards';
 import { i18nFiles } from './scaffold-i18n';
 import { mcpPackageFiles } from './scaffold-mcp-package';
 import { uiPackageFiles } from './scaffold-ui-package';
@@ -70,6 +71,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/query": "^${version}",
     "@ultimat3/render": "^${version}",
     "@ultimat3/schema": "^${version}",
+    "@ultimat3/seo": "^${version}",
     "@ultimat3/ui": "^${version}",
     "solid-js": "1.9.14"
   },
@@ -121,11 +123,13 @@ const envDeclaration = (): string => `${envSchemaSource()}
 export const env = defineEnv(envSchema);`;
 
 /**
- * No `installPrompt`. `PwaConfig` declares it, `defineConfig` defaults it, and NO file reads it —
- * `packages/core/src/config.ts` carries the marker saying so. Scaffolding it wrote a switch with
- * no wire into every generated app, and the note belongs HERE rather than in the emitted file: an
- * app author has no use for a comment about a framework key their config does not name. Deleting
- * the key itself is core's edit; not writing it is this template's half.
+ * No `installPrompt`, no `afterSignInPath`, no `modelEnv`. All three were declared by
+ * `defineConfig`, defaulted by it, and read by NO file; all three are DELETED from
+ * `packages/core/src/config.ts` as of 2026-08-22, whose header now records the removal rather than
+ * the marker this comment used to cite. So scaffolding one is no longer a switch with no wire — it
+ * is `TS2353` in the generated app's first `x verify`. The note belongs HERE rather than in the
+ * emitted file: an app author has no use for a comment about keys their config does not name.
+ * `scaffold-config.test.ts` is what keeps them from growing back.
  */
 const appConfig = (
   app: NameSet,
@@ -145,7 +149,9 @@ export const config = defineConfig({
   defaultCurrency: 'USD',
   // Env KEYS, never the value: the same image deploys to every environment. The database is
   // configured entirely from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`.
-  cache: { driver: 'memory', tiers: ['memo', 'lru'] },
+  // The tiers ARE the cache selection: add 'redis' to build the shared rung, which reads
+  // \`REDIS_URL\` and refuses the boot when it is unset.
+  cache: { tiers: ['request-memo', 'lru'] },
   jobs: { queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
   realtime: { enabled: true, tier: 'live-queries', transport: 'memory' },
@@ -164,10 +170,34 @@ export const config = defineConfig({
 // otherwise fail `lint` on a file no author typed and `x db gen` would rewrite anyway.
 // `preset`, not `recommended`: the older key is deprecated from 2.5 on and every `bun run lint`
 // in the scaffolded app printed the migration notice for a config the app never wrote by hand.
+//
+// `!**/.x` is the one that makes the app's fix chain terminate. `x build` writes MINIFIED island
+// bundles to `.x/static/islands/<name>-<contenthash>.js`; without the exclusion `lint` reported
+// ~175 `noCommaOperator`/`noAssignInExpressions` errors in Bun's own output, and the `fix:` for
+// that step — `biome check --write .` — still exits 1, so `x verify` was red forever on a pristine
+// scaffold the moment `x build` ran (which the `budgets` step's own `fix:` tells the author to do).
+// `--unsafe` was worse: it REWROTE a content-hashed chunk in place, 55,499 → 83,605 bytes, so the
+// name no longer matched the bytes and `.x/build-stats.json` no longer matched the artifact.
+// `--no-example` hid it, because an app with no island has nothing under `.x/static/islands`.
+//
+// `vcs.useIgnoreFile` is the second half and not a duplicate of the first: it makes every future
+// generated directory the app adds to `.gitignore` excluded by the act of ignoring it, rather than
+// by an edit to this file nobody will remember to make. It needs `.gitignore` to EXIST — Biome
+// exits 1 with `couldn't find an ignore file` when it does not — which `x new` writes, and which
+// is why the two are declared together rather than one of them alone.
 const biome = (): string => `{
   "$schema": "https://biomejs.dev/schemas/${BIOME_VERSION}/schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
   "files": {
-    "includes": ["**", "!**/migrations", "!x.manifest.json", "!openapi.json"]
+    "includes": [
+      "**",
+      "!**/.x",
+      "!**/dist",
+      "!**/.output",
+      "!**/migrations",
+      "!x.manifest.json",
+      "!openapi.json"
+    ]
   },
   "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
   "linter": {
@@ -304,6 +334,9 @@ export function repoFiles(
     // One call per workspace package, in write order. Each owns its own files (`scaffold-i18n.ts`
     // already did), so this list stays a table of contents rather than a second copy of every
     // package's contents.
+    // The app's own conventions, as build errors. Not a package — `guards/` sits at the repo root
+    // because the gate discovers it there, and every rule it holds is about the whole app.
+    ...scaffoldGuardFiles(),
     ...domainPackageFiles(app),
     ...dbPackageFiles(app, example),
     ...i18nFiles(app, version),

package/src/test-select.ts

@@ -2,12 +2,13 @@
 // validation behind the type positional and `--sample`. Selection only — nothing here splits a
 // shard or spawns a process, so a wrong file list is always this file's bug and never a race.
 
+import { join } from 'node:path';
 // Bun ships no equivalent: `join` builds the host-separator path from the scan root to a hit.
 // Sizing is Bun's own (`Bun.file().size`), so nothing here reaches for `node:fs`.
-import { join } from 'node:path';
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
-import { flagString, nearest } from './parse';
+import { flagString } from './parse';
 import type { TestType } from './verify-tests';
 import { ownerOf, TEST_TYPES } from './verify-tests';
 
@@ -103,7 +104,7 @@ export function readType(raw: string | undefined): TestType | undefined {
   if (raw === undefined) return undefined;
   const known: readonly string[] = TEST_TYPES;
   if (known.includes(raw)) return raw as TestType;
-  const suggestion = nearest(raw, known);
+  const suggestion = nearestName(raw, known);
   throw new BadFlagError({
     flag: 'type',
     command: 'test',

package/src/verify-run.ts

@@ -16,6 +16,10 @@ import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 /**
  * Run every step in order, never bailing early: an agent fixing three things at once needs all
  * three findings from one run, not one per round-trip.
+ *
+ * `ctx.only` narrows the list to one step. The narrowing lives HERE rather than in `cmd-verify.ts`
+ * so that every caller of the runner — the command, `x build`, the MCP host — gets the banner and
+ * the `--json` flag with it, instead of one of them filtering a list quietly.
  */
 export async function runVerify(
   steps: readonly VerifyStep[],
@@ -23,7 +27,8 @@ export async function runVerify(
 ): Promise<CommandResult> {
   const floor = await readVerifyFloor(ctx.root);
   const results: StepResult[] = [];
-  for (const step of steps) {
+  const selected = ctx.only === undefined ? steps : steps.filter((step) => step.name === ctx.only);
+  for (const step of selected) {
     const applies = step.applies === undefined ? true : await step.applies(ctx);
     if (!applies) {
       // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
@@ -67,14 +72,31 @@ export async function runVerify(
   const failedSteps = results.filter((step) => !step.ok).map((step) => step.name);
   const skippedSteps = results.filter((step) => step.skipped === true).map((step) => step.name);
   const totalMs = results.reduce((sum, step) => sum + step.durationMs, 0);
+  const summary = verifySummary({
+    results,
+    failed: failedSteps,
+    skipped: skippedSteps,
+    totalMs,
+  });
   return {
     ok: failedSteps.length === 0,
     command: 'verify',
-    summary: verifySummary({ results, failed: failedSteps, skipped: skippedSteps, totalMs }),
+    // Rendered through the catalog like every other summary this file emits; the machine marker
+    // is `data.notAGateRun` below. It was a bare `NOT A GATE RUN` constant, which put one
+    // user-facing string outside `messages.ts` for a fact `--json` was already carrying twice.
+    summary: ctx.only === undefined ? summary : msg('cli.verify.notAGateRun', { summary }),
     steps: results,
     // `skipped` is a list beside `failed` and not a count, because the two answer the same kind of
     // question — *which* steps, not how many — and a caller ratcheting on coverage needs the names.
-    data: { failed: failedSteps, skipped: skippedSteps, durationMs: totalMs },
+    data: {
+      failed: failedSteps,
+      skipped: skippedSteps,
+      durationMs: totalMs,
+      // A BOOLEAN beside the banner, so a reader of `--json` never has to substring-match a
+      // summary line to learn that this run checked one thing.
+      ...(ctx.only === undefined ? {} : { notAGateRun: true, only: ctx.only }),
+    },
+    // The step's own status: one step, so `failedSteps` is that step and nothing else.
     exitCode: failedSteps.length === 0 ? 0 : 1,
   };
 }

package/src/verify-step.ts

@@ -59,10 +59,19 @@ export interface VerifyContext {
   readonly hostChecks?: Partial<Record<VerifyStepName, HostCheck>>;
   /**
    * How wide the parallel test steps go. Absent means `defaultWorkers()` — a knob, never a
-   * narrowing: no value of it changes which steps run or what "green" means, which is why this is
-   * the only flag `x verify` accepts beyond the global ones.
+   * narrowing: no value of it changes which steps run or what "green" means.
    */
   readonly workers?: number;
+  /**
+   * ONE step, by name — an iteration loop, and the one thing here that IS a narrowing. Every
+   * iteration of the whole gate costs ~18s (14s of it `tsc -b`), which is the cost of asking a
+   * question about one step. It does not weaken axiom 5, and the two rules that keep it honest are
+   * mechanical rather than remembered: a run with this set prints `NOT A GATE RUN` in the summary
+   * AND carries `notAGateRun` in `--json` (`verify-run.ts`), so no reader of either can mistake it
+   * for the gate; and nothing writes `x.verify.json`, so the suite floor cannot be lowered by a
+   * run that never executed the suites. Green still means the no-flag run, unchanged.
+   */
+  readonly only?: VerifyStepName;
 }
 
 export interface StepOutcome {

package/src/verify-tests.ts

@@ -10,6 +10,8 @@
 // and `join` builds the host-separator path to its config file.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import type { TestType } from '@ultimat3/testing';
+import { TEST_TYPES } from '@ultimat3/testing';
 import { checkEvalBaselines, checkEvalCoverage, checkEvalRecording } from './app-evals';
 import { APP_CONFIG_FILE } from './app-root';
 import { countsOf } from './test-counts';
@@ -20,9 +22,15 @@ import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
 import { runParallel } from './verify-test-run';
 
-export const TEST_TYPES = ['unit', 'contract', 'live', 'job', 'e2e', 'eval'] as const;
-
-export type TestType = (typeof TEST_TYPES)[number];
+/**
+ * The six types are `@ultimat3/testing`'s declaration, not a list restated here: `unitTest`,
+ * `contractTest` and the rest prefix a test's reported name with one of these words, and this
+ * package selects a suite by the same word. A copy is one edit away from a step that discovers
+ * files no helper produces. `cli -> testing` is a declared sideways edge (`scripts/lib/tiers.ts`)
+ * and `@ultimat3/testing` is already a runtime dependency of this package.
+ */
+export type { TestType } from '@ultimat3/testing';
+export { TEST_TYPES } from '@ultimat3/testing';
 
 type TypedTest = Exclude<TestType, 'unit'>;
 

package/src/write-line.ts

@@ -1,6 +1,7 @@
-// The one stdout write every published entry point uses. Its own module because there are two of
-// them — `packages/cli/src/bin.ts` and `create-ultimate`'s — and the second shipped
-// `process.stdout.write` + `process.exit`, the exact pair the note below exists to rule out.
+// The two writes every published entry point uses, one per fd — `packages/cli/src/bin.ts` and
+// `create-ultimate`'s, the second of which shipped the `process.stdout.write` + `process.exit`
+// pair the note below rules out. fd 2 exists because fd 1 is not always a log: under
+// `x mcp serve --transport stdio` it is the protocol, under `--json` one document a caller parses.
 
 // `node:fs`, and unavoidable: Bun has no synchronous stdout write of its own.
 import { writeSync } from 'node:fs';
@@ -21,14 +22,31 @@ import { writeSync } from 'node:fs';
  * took the whole command down on a runner, emitting nothing at all. The reader drains in
  * microseconds; the retry is the correct response to "would block".
  */
-export function writeLine(line: string): void {
+function writeTo(fd: 1 | 2, line: string): void {
   const buffer = Buffer.from(`${line}\n`);
   let written = 0;
   while (written < buffer.length) {
     try {
-      written += writeSync(1, buffer, written, buffer.length - written);
+      written += writeSync(fd, buffer, written, buffer.length - written);
     } catch (cause) {
       if ((cause as NodeJS.ErrnoException).code !== 'EAGAIN') throw cause;
     }
   }
 }
+
+export function writeLine(line: string): void {
+  writeTo(1, line);
+}
+
+/**
+ * The same write, on fd 2: for a line that is not the command's answer. `dispatch` sends a result
+ * here when it declares `stream: 'stderr'` — `x mcp serve --transport stdio`, whose stdout carries
+ * JSON-RPC frames and where a `✓ …` banner is a malformed one to whatever is reading.
+ *
+ * Every guarantee above is the same guarantee here, and that is the reason this is one loop and
+ * not two: fd 2 is a pipe under `2>` and in CI exactly as fd 1 is, so a second copy would be a
+ * second place for the truncation and the `EAGAIN` handling to drift apart.
+ */
+export function writeErrorLine(line: string): void {
+  writeTo(2, line);
+}