@ultimat3/cli 23.0.0 → 24.0.0

package/src/errors.ts

@@ -2,6 +2,7 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
+import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
@@ -301,14 +302,59 @@ export class FixTargetUnknownError extends UltimateError {
   }
 }
 
-// The build and bundle refusals live in `build-errors.ts` (split at the 500-line ceiling); re-exported
-// here so every existing `from './errors'` import keeps resolving.
-export type { FrameworkScriptKind } from './build-errors';
-export {
-  BuildEntryMissingError,
-  FrameworkScriptBuildFailedError,
-  IslandBuildFailedError,
-} from './build-errors';
+/**
+ * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
+ * entry point like any other, and the target's own logs are what says which line. The fix builds
+ * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
+ */
+export class IslandBuildFailedError extends UltimateError {
+  constructor(input: { file: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
+      fix: `bun build --target browser ${input.file}`,
+    });
+  }
+}
+
+/** Which framework script a page ships: the sync worker, the page boot, or the client router. */
+export type FrameworkScriptKind = 'sync worker' | 'page boot' | 'client router';
+
+/**
+ * One of the page's framework scripts would not bundle. Same code as an island: "a browser entry
+ * the framework builds did not build" is one condition, and the entry here is framework code, not
+ * the app's — the cause names WHICH script, so the reader knows what the page is now missing.
+ */
+export class FrameworkScriptBuildFailedError extends UltimateError {
+  constructor(input: { what: FrameworkScriptKind; entry: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the ${input.what} (${input.entry}) would not bundle for the browser: ${input.logs}`,
+      fix: `bun build --target browser --format iife ${quoteArg(input.entry)}`,
+    });
+  }
+}
+
+/**
+ * A static build over an app whose modules did not all import. The route registry is filled BY the
+ * import, so a page whose module threw is not skipped but absent — and an export without it, with
+ * `x build` green, is a deploy that deletes a page. The `manifest` step owns load findings
+ * (`load-findings.ts`), so the fix is the command that lists every one with its own fix.
+ */
+export class PrerenderLoadFailedError extends UltimateError {
+  constructor(findings: readonly Finding[]) {
+    const listed = findings.map((finding) =>
+      finding.at === undefined
+        ? `${finding.code} ${finding.cause}`
+        : `${finding.at}: ${finding.code} ${finding.cause}`,
+    );
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the static export renders the routes the app's modules register, and ${findings.length} module load finding(s) left it short: ${listed.join('; ')}`,
+      fix: 'x verify --only manifest --json',
+    });
+  }
+}
 
 /**
  * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would
@@ -363,36 +409,6 @@ export class PortInvalidError extends UltimateError {
   }
 }
 
-/**
- * `x env` was run in an app whose `app.config.ts` exports no `envSchema`. Not a silent success:
- * writing a `.env.example` with no variables in it, or reporting "0 declared variables, all
- * present", both read as a working environment declaration to whoever runs the command next.
- *
- * `X_CONFIG_INVALID` is core's code for "a configuration this process cannot boot on — env or
- * `app.config.ts`", which is exactly this; the CLI names it in `CLI_BORROWED_ERROR_CODES` rather
- * than minting a synonym.
- */
-export class EnvSchemaMissingError extends UltimateError {
-  constructor(input: { subcommand: string }) {
-    super({
-      code: 'X_CONFIG_INVALID',
-      cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
-      fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
-    });
-  }
-}
-
-/** An interface-complete command path whose remote/native half is not written yet. */
-export class CliNotImplementedError extends UltimateError {
-  constructor(input: { feature: string; fix: string }) {
-    super({
-      code: 'X_NOT_IMPLEMENTED',
-      cause: `${input.feature} is not implemented in this build`,
-      fix: input.fix,
-    });
-  }
-}
-
 /**
  * The process could not obtain a storage disk to write to.
  *
@@ -432,48 +448,3 @@ export class LocalDiskUnsafeError extends UltimateError {
     });
   }
 }
-
-/**
- * `x secrets edit` decrypts into a buffer and hands it to `$EDITOR`. There is no fallback editor:
- * guessing one and opening a decrypted file in it is the last place a surprise belongs.
- */
-export class SecretsEditorMissingError extends UltimateError {
-  constructor(input: { vars: readonly string[] }) {
-    super({
-      code: 'X_SECRETS_EDITOR_MISSING',
-      cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
-      fix: 'EDITOR=nano x secrets edit',
-    });
-  }
-}
-
-/**
- * The editor exited non-zero — a crash, or a deliberate abort. The buffer is discarded either way
- * and the committed file is left exactly as it was: resealing a buffer whose editor failed would
- * commit whatever half-written state the crash left behind.
- */
-export class SecretsEditFailedError extends UltimateError {
-  constructor(input: { editor: string; code: number }) {
-    super({
-      code: 'X_SECRETS_EDIT_FAILED',
-      cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
-      fix: 'x secrets edit',
-    });
-  }
-}
-
-/**
- * `x secrets init` would overwrite a file that already exists. `X_GENERATE_CONFLICT` is this
- * package's own code for exactly that, and a second name for "a generator would clobber something"
- * is the duplication the code registry exists to prevent. Losing a master key is unrecoverable —
- * the committed file it opens is then ciphertext nobody can read again.
- */
-export class SecretsExistsError extends UltimateError {
-  constructor(input: { path: string; fix: string }) {
-    super({
-      code: 'X_GENERATE_CONFLICT',
-      cause: `${input.path} already exists, and x secrets init would replace it`,
-      fix: input.fix,
-    });
-  }
-}

package/src/framework-schema-apply.ts

@@ -0,0 +1,78 @@
+// The two ways a boot meets the framework schema (plan 101, s1-con #5): `applyLockedSchema` runs the
+// DDL in ONE transaction behind the migration advisory lock with a bounded `lock_timeout`, then
+// stamps the build; `verifySchema` runs no DDL and refuses a database this build was never applied
+// to. Which boot takes which is `runtime-queue.ts`'s `SchemaMode`.
+
+import { frameworkVersion, logger } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import {
+  literal,
+  MIGRATION_LOCK_KEY,
+  MIGRATION_LOCK_WAIT_MS,
+  poolProfileFor,
+  raw,
+  withTransaction,
+} from '@ultimat3/db';
+import { applyFrameworkSchema } from './framework-schema';
+import {
+  FrameworkSchemaUnappliedError,
+  frameworkSchemaHash,
+  nextStamp,
+  parseStamp,
+  STAMP_RELATION,
+  type StampEntry,
+  stampVerdict,
+} from './framework-schema-stamp';
+
+const thisBuild = (): StampEntry => ({
+  version: frameworkVersion(),
+  schema: frameworkSchemaHash(),
+});
+
+/** The stamp as the catalog holds it; `null` when the relation or its comment is absent. */
+async function readStamp(client: DbClient): Promise<string | null> {
+  const rows = await client.query<{ readonly stamp: string | null }>(
+    raw(`select obj_description(to_regclass('${STAMP_RELATION}'), 'pg_class') as stamp`),
+  );
+  return rows[0]?.stamp ?? null;
+}
+
+/**
+ * The migration lock, not a lock of its own: a second migrator — another `ROLE=migrate` pod, an
+ * `x db migrate` — waits behind this one instead of racing its `create table`s into `23505`. A
+ * transaction-scoped lock (`pg_advisory_xact_lock`), so no pinned session: COMMIT releases it.
+ *
+ * Two `lock_timeout`s: the lock wait is the migrator's own (`MIGRATION_LOCK_WAIT_MS`), and every
+ * DDL statement after it is the migrate pool's (`poolProfileFor('migrate')`), so an `alter table`
+ * behind an open transaction fails in seconds rather than queueing every enqueue behind it.
+ */
+export async function applyLockedSchema(client: DbClient): Promise<void> {
+  await withTransaction(
+    async (tx) => {
+      await tx.execute(raw(`set local lock_timeout = ${Math.round(MIGRATION_LOCK_WAIT_MS)}`));
+      await tx.execute(raw(`select pg_advisory_xact_lock(${MIGRATION_LOCK_KEY})`));
+      const ddlTimeoutMs = Math.round(poolProfileFor('migrate').lockTimeoutMs);
+      await tx.execute(raw(`set local lock_timeout = ${ddlTimeoutMs}`));
+      await applyFrameworkSchema((statement) => tx.execute(raw(statement)));
+      const stamp = nextStamp(await readStamp(tx), thisBuild());
+      await tx.execute(raw(`comment on table ${STAMP_RELATION} is ${literal(stamp).text}`));
+    },
+    { client },
+  );
+}
+
+/**
+ * One catalog read. A build absent from the stamp is refused with the command that applies it; a
+ * fleet straddling a major is reported once and served — refusing it would crash-loop the old pods
+ * of every rolling deploy across a breaking release.
+ */
+export async function verifySchema(client: DbClient): Promise<void> {
+  const mine = thisBuild();
+  const verdict = stampVerdict(parseStamp(await readStamp(client)), mine);
+  if (!verdict.applied) throw new FrameworkSchemaUnappliedError({ mine, newest: verdict.newest });
+  if (verdict.skew === undefined) return;
+  logger.warn('ultimate framework major skew', {
+    cause: `this process runs ${mine.version} and the database's framework schema was last applied by ${verdict.skew.version}: a fleet across a major boundary is mid-rollout or half rolled back`,
+    fix: 'kubectl rollout status deployment --selector app.kubernetes.io/component=web',
+  });
+}

package/src/framework-schema-stamp.ts

@@ -0,0 +1,96 @@
+// Which builds have applied the framework schema to this database: a stamp `ROLE=migrate` leaves
+// in `x_jobs`' table comment, and the verdict a serving role reads from it instead of running DDL
+// itself (plan 101, s1-con #5). Pure: the statements live in `framework-schema-apply.ts`.
+
+import { UltimateError } from '@ultimat3/core';
+import { FRAMEWORK_SCHEMA } from './framework-schema';
+
+/**
+ * The relation that carries the stamp. A comment, not a table: a new framework table moves every
+ * app's committed schema dump (`packages/db/schema/framework/`), and a comment is in none of them.
+ */
+export const STAMP_RELATION = 'x_jobs';
+
+/** The first line of a stamp — what tells it apart from a comment someone else wrote. */
+const STAMP_HEADER = 'ultimate-framework-schema';
+
+/** Enough for a rolling deploy and its rollback, small enough to stay one readable comment. */
+const STAMP_KEEP = 16;
+
+export interface StampEntry {
+  readonly version: string;
+  readonly schema: string;
+}
+
+/** This build's DDL, as one short hash: two builds with the same DDL are the same schema. */
+export function frameworkSchemaHash(): string {
+  const hasher = new Bun.CryptoHasher('sha256');
+  for (const entry of FRAMEWORK_SCHEMA) for (const ddl of entry.ddl) hasher.update(ddl);
+  return hasher.digest('hex').slice(0, 16);
+}
+
+/** Every build a stamp records, newest first. Anything that is not a stamp records none. */
+export function parseStamp(comment: string | null | undefined): readonly StampEntry[] {
+  if (typeof comment !== 'string') return [];
+  const [header, ...lines] = comment.split('\n');
+  if (header !== STAMP_HEADER) return [];
+  return lines.flatMap((line) => {
+    const [version, schema] = line.trim().split(' ');
+    return version !== undefined &&
+      /^[0-9A-Za-z.+-]{1,64}$/.test(version) &&
+      schema !== undefined &&
+      /^[0-9a-f]{16}$/.test(schema)
+      ? [{ version, schema }]
+      : [];
+  });
+}
+
+/** The stamp after `mine` applied: it first, every other build kept, the oldest dropped. */
+export function nextStamp(previous: string | null | undefined, mine: StampEntry): string {
+  const kept = parseStamp(previous).filter((entry) => entry.schema !== mine.schema);
+  const entries = [mine, ...kept].slice(0, STAMP_KEEP);
+  return [STAMP_HEADER, ...entries.map((entry) => `${entry.version} ${entry.schema}`)].join('\n');
+}
+
+const majorOf = (version: string): string => version.split('.')[0] ?? version;
+
+export type StampVerdict =
+  | { readonly applied: true; readonly skew?: StampEntry }
+  | { readonly applied: false; readonly newest?: StampEntry };
+
+/**
+ * Applied when this build's hash is anywhere in the stamp: an old pod restarting mid-rollout finds
+ * its own build there, behind the new one. `skew` is the newest build when its MAJOR differs from
+ * this process's — a fleet straddling a breaking release, which a boot reports and never refuses.
+ */
+export function stampVerdict(entries: readonly StampEntry[], mine: StampEntry): StampVerdict {
+  const newest = entries[0];
+  if (!entries.some((entry) => entry.schema === mine.schema)) {
+    return newest === undefined ? { applied: false } : { applied: false, newest };
+  }
+  return newest !== undefined && majorOf(newest.version) !== majorOf(mine.version)
+    ? { applied: true, skew: newest }
+    : { applied: true };
+}
+
+/** A serving role over a database its build's framework tables were never applied to. */
+export class FrameworkSchemaUnappliedError extends UltimateError {
+  constructor(input: { readonly mine: StampEntry; readonly newest: StampEntry | undefined }) {
+    super({
+      code: 'X_FRAMEWORK_SCHEMA_UNAPPLIED',
+      cause:
+        `this build (${input.mine.version}, framework schema ${input.mine.schema}) has not been applied ` +
+        `to this database — ${
+          input.newest === undefined
+            ? `${STAMP_RELATION} carries no stamp, so no ROLE=migrate of this release ran`
+            : `the newest applied build is ${input.newest.version} (${input.newest.schema})`
+        }. A serving role verifies and never runs DDL: the migrate step must run first`,
+      fix: 'x db migrate',
+      meta: {
+        version: input.mine.version,
+        schema: input.mine.schema,
+        ...(input.newest === undefined ? {} : { newest: { ...input.newest } }),
+      },
+    });
+  }
+}

package/src/framework-schema.ts

@@ -11,7 +11,11 @@ import { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from '@ultimat3/admin/schema
 import { AUTH_TABLE_NAMES, AUTH_TABLES, SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
 import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
 import { SQL_JOBS_TABLE } from '@ultimat3/jobs';
-import { SQL_NOTIFY_DELIVERIES_TABLE, SQL_NOTIFY_INBOX_TABLE } from '@ultimat3/notify';
+import {
+  SQL_NOTIFY_DELIVERIES_TABLE,
+  SQL_NOTIFY_DIGESTS_TABLE,
+  SQL_NOTIFY_INBOX_TABLE,
+} from '@ultimat3/notify';
 import { FrameworkSchemaFailedError } from './schema-errors';
 
 export interface FrameworkSchema {
@@ -76,7 +80,7 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
   }),
   Object.freeze({
     pkg: '@ultimat3/auth',
-    tables: Object.freeze(['x_auth_failures', 'x_auth_lockouts']),
+    tables: Object.freeze(['x_auth_lockouts']),
     ddl: Object.freeze([SQL_AUTH_LIMIT_TABLES]),
   }),
   /**
@@ -113,6 +117,13 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze(['x_notify_inbox']),
     ddl: Object.freeze([SQL_NOTIFY_INBOX_TABLE]),
   }),
+  // `createPgDigestStore`'s windows. Installed whether or not the app picks that store, for the
+  // reason every notify row is: `setNotifyStores` is the app's boot line and runs after this one.
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze(['x_notify_digests']),
+    ddl: Object.freeze([SQL_NOTIFY_DIGESTS_TABLE]),
+  }),
   /**
    * The admin's durable audit trail — what `postgresAuditLog()` writes and every detail page's
    * history card reads. Without this row an app that chose the durable log met `42P01` on the

package/src/generate-files.ts

@@ -2,7 +2,8 @@
 // `cmd-generate.ts` so a generator's output can be asserted on — by the generator tests, the
 // scaffold fixture and `x new` — without a command line, an app root or a filesystem.
 
-import { BadFlagError, CliNotImplementedError } from './errors';
+import { NotImplementedError } from '@ultimat3/core';
+import { BadFlagError } from './errors';
 import type { Generator } from './generate-kinds';
 import { assertLiveSupported, assertSurfaceSupported, GENERATORS } from './generate-kinds';
 import { dedupe } from './generate-write';
@@ -233,8 +234,8 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         }),
       );
     default:
-      throw new CliNotImplementedError({
-        feature: `generator "${String(options.kind)}"`,
+      throw new NotImplementedError({
+        cause: `generator "${String(options.kind)}" is not implemented in this build`,
         fix: `x g ${GENERATORS.join('|')}`,
       });
   }

package/src/generate-kinds.ts

@@ -11,7 +11,7 @@ import {
 } from './errors';
 import { quoteArg } from './shell-quote';
 import type { Surface } from './templates';
-import { camel, kebab } from './templates/naming';
+import { camel, kebab, plural, singularOf } from './templates/naming';
 
 export const GENERATORS = [
   'resource',
@@ -137,10 +137,42 @@ export function readName(raw: string | undefined, kind: Generator): string {
   // directory that serves it. Every other generator's name is one directory segment.
   if (kind === 'route') return readRoutePath(raw);
   refusePath(raw, 'name', kind);
+  refuseNonAscii(raw, kind);
   refuseBadIdentifier(raw, kind);
+  refusePlural(raw, kind);
   return raw;
 }
 
+/**
+ * Every derived spelling keeps `[a-zA-Z0-9]` and drops the rest as a separator, so a letter
+ * outside ASCII vanished: `x g entity Über` wrote `ber`. Refused, with the name folded to ASCII.
+ */
+function refuseNonAscii(raw: string, kind: Generator): void {
+  if (!/[^\p{ASCII}]/u.test(raw)) return;
+  const folded = kebab(raw.normalize('NFKD').replace(/[^\p{ASCII}]/gu, ''));
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${raw}" holds a letter outside ASCII, and every file, identifier and table name the generator derives from it keeps ASCII letters and digits only`,
+    fix: folded === '' ? exampleFor(kind) : ['x g', kind, folded].join(' '),
+  });
+}
+
+/** The generators that pluralise their name into a table and a page. */
+const PLURALISED: ReadonlySet<Generator> = new Set<Generator>(['resource', 'entity']);
+
+/** `x g resource posts` declared `entity('postses')`: a plural name is pluralised again. */
+function refusePlural(raw: string, kind: Generator): void {
+  const singular = PLURALISED.has(kind) ? singularOf(raw) : undefined;
+  if (singular === undefined) return;
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${raw}" is already plural, and the generator pluralises the name for its table and page — "${plural(camel(raw))}"`,
+    fix: ['x g', kind, singular].join(' '),
+  });
+}
+
 /** A static segment, or `[param]` / `[...rest]` — the directory convention `x routes` reads. */
 const ROUTE_SEGMENT = /^(?:[A-Za-z0-9][A-Za-z0-9_-]*|\[(?:\.\.\.)?[A-Za-z][A-Za-z0-9_-]*\])$/;
 

package/src/generate-shadow.ts

@@ -0,0 +1,46 @@
+// A generator name whose type spelling the emitted code ALSO uses as a global or a local alias:
+// `x g resource promise` imports `type { Promise }` beside `Promise<Row>`, and `row` writes
+// `type Row = Row`. Decided on the planned files themselves, so a template that starts using
+// another global is covered the day it does — and the names that clash nowhere stay allowed.
+
+import { BadFlagError } from './errors';
+import type { Generator } from './generate-kinds';
+import type { GeneratedFile } from './templates';
+import { kebab, names } from './templates/naming';
+
+/** The emitted file that imports `type` from the slice AND uses the same name as its own. */
+function shadowingFile(files: readonly GeneratedFile[], type: string): string | undefined {
+  // A pascal spelling is `[A-Za-z0-9]` only (`naming.ts`), so it splices into a pattern as is.
+  const imported = new RegExp(
+    `import\\s+(?:type\\s+)?\\{[^}]*\\b${type}\\b[^}]*\\}\\s+from\\s+'\\.`,
+  );
+  const reused = new RegExp(
+    `\\b${type}<|^\\s*(?:export\\s+)?(?:type\\s+${type}\\s*=|interface\\s+${type}\\b)`,
+    'm',
+  );
+  return files.find(
+    (file) =>
+      typeof file.contents === 'string' &&
+      /\.tsx?$/.test(file.path) &&
+      imported.test(file.contents) &&
+      reused.test(file.contents),
+  )?.path;
+}
+
+/** Refuses `name` when its type spelling would shadow a name the planned files rely on. */
+export function refuseShadowedTypes(
+  files: readonly GeneratedFile[],
+  kind: Generator,
+  name: string,
+): void {
+  const type = names(name).pascal;
+  const file = shadowingFile(files, type);
+  if (file === undefined) return;
+  const noun = kind.split(':').at(-1) ?? kind;
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${name}" becomes the type ${type}, and ${file} imports it beside its own use of ${type} — the global or local type the template means is shadowed and the file does not compile`,
+    fix: ['x g', kind, `${kebab(name)}-${noun}`].join(' '),
+  });
+}

package/src/generate-write.ts

@@ -102,7 +102,7 @@ export function containedPath(root: string, path: string): string {
       dir: base,
       // Command first, the caveat behind a `#`: the line runs verbatim and the shell drops the
       // rest. `x g <kind> <name>` pasted into bash is a redirect, not a command.
-      fix: `x g resource posts --dry-run   # name every file relative to the app root, no ".." segment`,
+      fix: `x g resource post --dry-run   # name every file relative to the app root, no ".." segment`,
     });
   return target;
 }
@@ -198,14 +198,56 @@ function planFile(
   return { kind: 'write', file, absolute, contents: file.contents };
 }
 
+/** Every file's plan, decided without touching the disk — the first of `writeFiles`' two passes. */
+async function planAll(
+  root: string,
+  files: readonly GeneratedFile[],
+  force: boolean,
+  invocation: string,
+): Promise<readonly WritePlan[]> {
+  const plans: WritePlan[] = [];
+  for (const file of files) {
+    const absolute = containedPath(root, file.path);
+    plans.push(
+      file.merge === 'json'
+        ? await planJsonMerge(file, absolute)
+        : planFile(file, absolute, force, invocation),
+    );
+  }
+  return plans;
+}
+
+const conflictsOf = (plans: readonly WritePlan[]): readonly Finding[] =>
+  plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
+
+/**
+ * What `writeFiles` WOULD do, and nothing else: the paths it would write and the conflicts that
+ * would stop it. `x g --dry-run` answers with this — the bare file list said "would write 33"
+ * where the real run was `X_GENERATE_CONFLICT`, and listed slice modules the run skips as writes.
+ */
+export async function planWrites(
+  root: string,
+  files: readonly GeneratedFile[],
+  force: boolean,
+  invocation = 'x g <kind> <name>',
+): Promise<WriteReport> {
+  const plans = await planAll(root, files, force, invocation);
+  const conflicts = conflictsOf(plans);
+  if (conflicts.length > 0) return { written: [], conflicts };
+  return {
+    written: plans.flatMap((plan) => (plan.kind === 'write' ? [plan.file.path] : [])),
+    conflicts: [],
+  };
+}
+
 /**
  * Never clobbers, and never half-writes. A generator that overwrites is a generator nobody runs
  * twice; a generator that lands four of seven files and then reports a conflict is worse, because
  * the next run conflicts on the files the failed one wrote.
  *
  * Two passes, and the split is the point: the first decides — containment, existence, whether a
- * catalog can be merged into — and touches nothing, the second writes only when the first found
- * no conflict at all. Containment was already proven up front and the rest was not.
+ * catalog can be merged into — and touches nothing (`planWrites` is that pass alone), the second
+ * writes only when the first found no conflict at all.
  */
 export async function writeFiles(
   root: string,
@@ -218,16 +260,8 @@ export async function writeFiles(
    */
   invocation = 'x g <kind> <name>',
 ): Promise<WriteReport> {
-  const plans: WritePlan[] = [];
-  for (const file of files) {
-    const absolute = containedPath(root, file.path);
-    plans.push(
-      file.merge === 'json'
-        ? await planJsonMerge(file, absolute)
-        : planFile(file, absolute, force, invocation),
-    );
-  }
-  const conflicts = plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
+  const plans = await planAll(root, files, force, invocation);
+  const conflicts = conflictsOf(plans);
   if (conflicts.length > 0) return { written: [], conflicts };
 
   const written: string[] = [];

package/src/gh-target.ts

@@ -76,18 +76,23 @@ const PR_VIEW = t.object({ number: t.number });
  * The pull request for the current branch. gh exits non-zero when there is none, with a message
  * that names the branch — so the refusal keeps gh's own sentence and adds the remedy gh has no
  * opinion about: name the number, or open the PR.
+ *
+ * No `--repo`: gh refuses `pr view --repo <slug>` without a number, url or branch before any
+ * network call, so that argv could never succeed. The checkout-scoped form resolves the branch's
+ * tracking remote itself — the same resolution `gh repo view` gave `resolveRepo`. `repo` names the
+ * pull request in the refusal only.
  */
 export async function resolvePrNumber(host: GhHost, repo: GhRepo): Promise<number> {
   try {
-    const viewed = await ghJson(
-      host,
-      ['pr', 'view', '--repo', repo.slug, '--json', 'number'],
-      PR_VIEW,
-      { label: 'gh pr view', fix: 'x pr review --pr 241 --json' },
-    );
+    const viewed = await ghJson(host, ['pr', 'view', '--json', 'number'], PR_VIEW, {
+      label: 'gh pr view',
+      fix: 'x pr review --pr 241 --json',
+    });
     return viewed.number;
   } catch (error) {
-    if (error instanceof GhFailedError) throw new PrNotFoundError({ detail: error.cause });
+    if (error instanceof GhFailedError) {
+      throw new PrNotFoundError({ detail: `${repo.slug}: ${error.cause}` });
+    }
     throw error;
   }
 }

package/src/i18n-audit.ts

@@ -28,13 +28,16 @@ import { CATALOG_ROOT, catalogPath } from './templates/locales';
  * glob set every text-scanning gate step already shares (`errors`, `filesize`) — a second glob
  * here would mean this command and `x verify` disagree on what "the app's source" is. Test files
  * are excluded: a fixture's `t('fixture.key')` is not a gap the shipped catalogs owe an answer to.
+ * So are `guards/`: gate tooling renders nothing, and its fix lines quote `t('…')` as an example.
  * `extractFromFiles` reads by absolute path, so its `file` label is rewritten back to the same
  * root-relative POSIX shape `app-load.ts` uses for every other CLI-reported path.
  */
+const isGuard = (file: string): boolean => file.startsWith('guards/');
+
 export async function scanSource(root: string): Promise<Extraction> {
   const files: string[] = [];
   for await (const file of eachSourceFile(root)) {
-    if (!isTest(file)) files.push(file);
+    if (!isTest(file) && !isGuard(file)) files.push(file);
   }
   const extraction = await extractFromFiles(files.map((file) => join(root, file)));
   const toRelative = (file: string): string => relative(root, file).split(sep).join('/');

package/src/index.ts

@@ -21,7 +21,7 @@ export { appManifest, writeAppManifest } from './app-manifest';
 export { requireAppRoot } from './app-root';
 export type { RouteStats } from './budgets';
 export { checkBudgets, FRAMEWORK_INLINE_SCRIPTS, FRAMEWORK_SCRIPTS } from './budgets';
-export { BUILD_ENTRY, BUILD_TARGETS, readTarget } from './cmd-build';
+export { BUILD_ENTRY, BUILD_TARGETS, BuildEntryMissingError, readTarget } from './cmd-build';
 export { dbCommand } from './cmd-db';
 export { planDeploy } from './cmd-deploy';
 export { startDev } from './cmd-dev';
@@ -69,10 +69,8 @@ export {
 export { checkErrorCodesThrown } from './error-unthrown';
 export {
   BadFlagError,
-  BuildEntryMissingError,
   BunVersionError,
   CatalogExistsError,
-  CliNotImplementedError,
   DeclarationUnknownError,
   ErrorCodeUnknownError,
   FixTargetUnknownError,