@ultimat3/cli 20.1.2 → 20.1.4

package/src/mcp-ui.ts

@@ -0,0 +1,136 @@
+// The dev MCP server's two eyes: `ui.shot` (a route) and `ui.island` (a component's states), as
+// the `DevCapabilities` half `packages/mcp` declares and cannot satisfy — a browser is the CLI's
+// to launch. Both are `x shot` under another name: the same server lookup (a running `x dev` is
+// reused through its lock, otherwise a scratch one boots), the same driver, the same verdict.
+// Nothing here is a new capability; it is the existing one made reachable from inside the loop
+// an agent already works in, so "does it look right" stops needing a hand-written script.
+
+// why: Bun exposes no path-join primitive, and the picture's directory is a path an agent opens.
+import { join } from 'node:path';
+import { UltimateError } from '@ultimat3/core';
+import type { UiIslandInput, UiIslandResult, UiShotInput, UiShotResult } from '@ultimat3/mcp';
+import { describeRoutes } from '@ultimat3/render';
+import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
+import { appBrowser } from './browser-launcher';
+import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
+import { islandShot } from './cmd-shot-island';
+import type { Env } from './dev-services';
+import { islandVerdictJson } from './island-verdict';
+import { shotBrowserChoice } from './shot-browser';
+import { devServerFor } from './shot-server';
+import { verdictJson } from './shot-verdict';
+
+/** Kernel-picked, as `x shot` picks it: a scratch server never fights another project for :3000. */
+const SCRATCH_PORT = 0;
+
+/**
+ * The route a picture is of has to be a route this app declares WITH a JS budget. The gate
+ * refuses an unmeasured route (`X_BUDGET_UNMEASURED`), and a picture of a route nobody has
+ * finished declaring is a picture of a draft — an agent judging it would judge the wrong thing.
+ * Matched on the declared pattern, so `/links/abc123` finds `/links/:slug`.
+ */
+export interface DeclaredRoute {
+  readonly path: string;
+  readonly file: string;
+  readonly budgetJs: string | null;
+}
+
+export function assertBudgetedRoute(route: string, declared: readonly DeclaredRoute[]): void {
+  const path = route.split('?')[0] ?? route;
+  const hit = declared.find((entry) => matches(entry.path, path));
+  if (hit === undefined) {
+    throw new UltimateError({
+      code: 'X_UI_SHOT_ROUTE_UNKNOWN',
+      cause: `no route in this app answers ${route}`,
+      fix: 'x routes --json   # then ui.shot with one of its `path` values',
+    });
+  }
+  if (hit.budgetJs === null) {
+    throw new UltimateError({
+      code: 'X_UI_SHOT_ROUTE_UNBUDGETED',
+      cause: `${hit.file} declares no budget.js, so x verify would refuse it as X_BUDGET_UNMEASURED — a picture of it would be a picture of a draft`,
+      fix: `declare budget: { js: '<n>kb' } in ${hit.file}, then: x build --target static --json && x verify --only budgets --json`,
+    });
+  }
+}
+
+/** `/links/:slug` matches `/links/abc123`; one segment per `:param`, no globbing. */
+export function matches(pattern: string, path: string): boolean {
+  const want = pattern.split('/');
+  const have = path.split('/');
+  if (want.length !== have.length) return false;
+  return want.every((segment, index) => segment.startsWith(':') || segment === have[index]);
+}
+
+export interface UiHostInput {
+  readonly root: string;
+  readonly env: Env;
+}
+
+export function uiCapabilities(input: UiHostInput): {
+  shotRoute(shot: UiShotInput): Promise<UiShotResult>;
+  shotIsland(island: UiIslandInput): Promise<UiIslandResult>;
+} {
+  const { root, env } = input;
+  const boot = () => devServerFor(root, env, SCRATCH_PORT);
+  // The same choice `x shot` makes from the environment: `PUPPETEER_EXECUTABLE_PATH`, a
+  // provider's CDP URL, or the launcher's own discovery.
+  const browser = () => shotBrowserChoice({ cdpFlag: undefined, browserFlag: undefined, env });
+
+  return {
+    async shotRoute(shot) {
+      assertBudgetedRoute(shot.route, describeRoutes());
+      const { cdpUrl, executablePath } = browser();
+      const driver = await appBrowser({
+        root,
+        viewport: shot.viewport,
+        ...(executablePath === undefined ? {} : { executablePath }),
+        ...(cdpUrl === undefined ? {} : { cdpUrl }),
+      });
+      // One directory per (route, viewport, scheme), so two pictures of one route at two widths
+      // never overwrite each other and an agent can hold both.
+      const outDir = join(
+        root,
+        SHOT_DIR,
+        shotSlug(shot.route),
+        `${shot.viewport.width}x${shot.viewport.height}-${shot.colorScheme}`,
+      );
+      const artifacts = await runShot({
+        route: shot.route,
+        outDir,
+        driver,
+        boot,
+        settleMs: DEFAULT_SETTLE_MS,
+        timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
+        fullPage: shot.fullPage,
+        colorScheme: shot.colorScheme,
+      });
+      return {
+        ok: artifacts.verdict.ok,
+        image: artifacts.image,
+        verdictFile: artifacts.verdictFile,
+        verdict: verdictJson(artifacts.verdict),
+      };
+    },
+
+    async shotIsland(island) {
+      const { cdpUrl, executablePath } = browser();
+      const artifacts = await islandShot({
+        root,
+        island: island.island,
+        ...(island.state === undefined ? {} : { state: island.state }),
+        settleMs: DEFAULT_SETTLE_MS,
+        timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
+        ...(executablePath === undefined ? {} : { executablePath }),
+        ...(cdpUrl === undefined ? {} : { cdpUrl }),
+        boot,
+      });
+      return {
+        ok: artifacts.verdict.ok,
+        dir: artifacts.dir,
+        verdictFile: artifacts.verdictFile,
+        verdict: islandVerdictJson(artifacts.verdict),
+      };
+    },
+  };
+}

package/src/output.ts

@@ -64,7 +64,7 @@ export interface CommandResult {
    * Which fd this result is written to. `stdout` for every command, absent included — and
    * `stderr` for the one case where fd 1 is not the command's to write on: `x mcp serve
    * --transport stdio`, whose stdout carries JSON-RPC frames, and where the `✓ mcp stdio serving
-   * 13 tools` line printed after the loop exits is a malformed frame to whatever is reading.
+   * 15 tools` line printed after the loop exits is a malformed frame to whatever is reading.
    *
    * Behaviour, not a fact, exactly like `hold` above — so NEITHER renderer carries it. It says
    * where a rendered line goes, and a payload that also claimed it would be a second answer to a

package/src/scaffold-fixture.ts

@@ -21,6 +21,31 @@ export const HANDWRITTEN_ERRORS = `import { UltimateError } from '@ultimat3/core
 export class LedgerClosedError extends UltimateError {}
 `;
 
+/**
+ * A feature slice whose entity is NOT tenant-scoped — the shape `x g entity`'s own comment
+ * describes for a single-tenant app, and never a shape the generator writes itself. The
+ * generator's INPUT only, the same way `HANDWRITTEN_ERRORS` above is: `x g job`/`x g task` read
+ * this from a real `entity.ts`, and a fixture that never exercised it compiled only the shape
+ * that never failed.
+ */
+export const HANDWRITTEN_ENTITY_NO_TENANT = `import { entity, text, uuid } from '@ultimat3/entity';
+
+export const shortLink = entity('short_links', {
+  columns: { id: uuid().primaryKey(), url: text({ max: 2000 }) },
+});
+
+export type ShortLink = typeof shortLink.$row;
+`;
+
+/** The paired `repo.ts`: no `byId`, no `listByOrg` — nothing this slice's job may call. */
+export const HANDWRITTEN_REPO_NO_TENANT = `import { db, sql } from '@ultimat3/db';
+import type { ShortLink } from './entity';
+
+export async function list(limit = 50): Promise<readonly ShortLink[]> {
+  return db().query<ShortLink>(sql\`select * from short_links order by url limit \${limit}\`);
+}
+`;
+
 /**
  * One realistic invocation of every generator, on top of `x new --example`. Names differ from
  * their feature on purpose: `x g query invoice --feature invoice` would collide with the entity
@@ -47,6 +72,23 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },
   { kind: 'backfill', name: 'reindex-invoices', feature: 'invoice' },
   { kind: 'task', name: 'nightly-sweep', feature: 'invoice' },
+  // The other shape both templates have: a feature whose entity names no tenant column, so the
+  // job/task must not assume one — compiled here beside the tenant-scoped pair above, exactly as
+  // `ping-invoice`/`touch-invoice` compile the action's other shape beside `send-invoice`.
+  {
+    kind: 'job',
+    name: 'purge-orphans',
+    feature: 'short-link',
+    sliceEntity: HANDWRITTEN_ENTITY_NO_TENANT,
+    sliceRepo: HANDWRITTEN_REPO_NO_TENANT,
+  },
+  {
+    kind: 'task',
+    name: 'nightly-purge',
+    feature: 'short-link',
+    sliceEntity: HANDWRITTEN_ENTITY_NO_TENANT,
+    sliceRepo: HANDWRITTEN_REPO_NO_TENANT,
+  },
   { kind: 'route', name: 'pricing', surface: 'site' },
   { kind: 'route', name: 'billing', surface: 'app' },
   // `--at`, pointed at the `site/` route above: an island's whole reason to exist is a 0kb page

package/src/templates/guard-unzoned-date.ts

@@ -74,10 +74,17 @@ export function unzonedDates(files: readonly SourceFile[]): readonly Finding[] {
       const open = match.index + match[0].length - 1;
       if (argumentsOf(text, open).includes('timeZone')) continue;
       const line = lineOf(text, match.index);
+      // The bare \`.toLocaleString(\` is ALSO \`Number.prototype.toLocaleString\`, and a regex cannot
+      // tell a count from a date. The match stands — a date formatted this way is the defect this
+      // guard exists for — but the fix names the number exit too, because \`{ timeZone }\` is not
+      // one: a number ignores it, and an author following the fix verbatim would ship a lie.
+      const bare = match[0].trim() === '.toLocaleString(';
       findings.push({
         code: CODE,
         cause: \`\${file.path}:\${line} calls \${match[0].trim()}) with no timeZone — it formats in whatever zone the process happens to run in, so one row reads as two different days across two containers\`,
-        fix: \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
+        fix: bare
+          ? \`in \${file.path}: a Date → pass an explicit IANA zone, at.toLocaleString(locale, { timeZone: 'UTC' }); a NUMBER → new Intl.NumberFormat(locale).format(n) instead — then: x verify\`
+          : \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
         at: file.path,
       });
     }
@@ -130,6 +137,16 @@ unitTest('Intl.DateTimeFormat and toLocaleTimeString are the same rule', () => {
   expect(unzonedDates(file("at.toLocaleTimeString('en-US');"))).toHaveLength(1);
 });
 
+unitTest('the bare toLocaleString names the number exit, since a count matches it too', () => {
+  const findings = unzonedDates(file("const shown = count.toLocaleString('en-US');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.fix).toContain('Intl.NumberFormat');
+  expect(findings[0]?.fix).toContain('timeZone');
+  // The dated forms are unambiguous and keep the zone-only fix.
+  const dated = unzonedDates(file("at.toLocaleDateString('en-US');"));
+  expect(dated[0]?.fix).not.toContain('Intl.NumberFormat');
+});
+
 unitTest('a commented-out call is a note, not a call', () => {
   expect(unzonedDates(file("// at.toLocaleDateString('en-US');"))).toEqual([]);
 });

package/src/templates/index.ts

@@ -12,7 +12,8 @@ export { entityFiles } from './entity';
 export { guardCode, guardFiles } from './guard';
 export type { IslandOptions } from './island';
 export { islandFiles } from './island';
-export { jobFiles, taskFiles } from './job';
+export type { JobOptions } from './job';
+export { isTenantScopedSlice, jobFiles, taskFiles } from './job';
 export { CATALOG_ROOT, catalogPath, DEFAULT_LOCALES, resolveLocales } from './locales';
 // All three members of the `GeneratedFile` union, not two: the barrel exported the union and the
 // foundation variant only, so a consumer could hold a `GeneratedFile` and had no name to narrow it

package/src/templates/job.ts

@@ -3,10 +3,11 @@
 // both; the generated test pins them through a real driver, because a key that is not stable is a
 // job that runs twice and a tenant that is not declared is a job that reads the wrong org's rows.
 
+import { stripComments } from '../ts-scan';
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { sliceFoundation } from './slice-foundation';
+import { sliceExports, sliceFoundation } from './slice-foundation';
 
 const jobSource = (
   name: NameSet,
@@ -39,6 +40,42 @@ export const ${name.camel} = job({
 });
 `;
 
+/**
+ * The other shape: this feature's own `entity.ts` names no tenant column (or names `'none'`), or
+ * its `repo.ts` does not export the `byId`/`listByOrg` pair the tenant-scoped body above calls —
+ * checked by `isTenantScopedSlice` against what is actually on the app's disk, never assumed. The
+ * body imports neither `../entity` nor `../repo`, so it compiles whether this feature has an
+ * entity yet or has one with no tenant, and `tenant: 'none'` is stated rather than defaulted so a
+ * reviewer sees the decision instead of an absence.
+ */
+const neutralJobSource = (
+  name: NameSet,
+): string => `// ${name.camel}: multi-step durable work with no tenant behind it. Each step is retried
+// independently and its result is stored under its name — step names are stable identifiers, not
+// labels. \`t\` comes from @ultimat3/jobs, not @ultimat3/schema: a job file imports one package.
+
+import { job, t } from '@ultimat3/jobs';
+
+export const ${name.camel} = job({
+  input: t.object({ id: t.uuid }),
+  // This feature has no tenant column to derive an org from — either it has no entity yet, or its
+  // entity names none. \`tenant: 'none'\` STRIPS the org from the run rather than leaving one
+  // behind, so a tenant-scoped read added later fails closed with X_TENANCY_ACTOR_ORG_REQUIRED
+  // instead of reading whichever org the enqueuer happened to hold. Once this feature's entity
+  // declares \`tenant: 'orgId'\` and its repo exports \`byId\`/\`listByOrg\`, the next \`x g job\` in
+  // this slice scaffolds the tenant-scoped shape above instead.
+  tenant: 'none',
+  idempotencyKey: ({ id }) => \`${name.kebab}:\${id}\`,
+  retry: { attempts: 5, backoff: 'exponential' },
+  async run({ step }) {
+    await step.run('process', async () => {
+      // TODO: this job's own work.
+    });
+    return { processed: true };
+  },
+});
+`;
+
 const taskSource = (
   name: NameSet,
   jobName: NameSet,
@@ -65,6 +102,25 @@ export const ${name.camel} = task({
 });
 `;
 
+/** The task's other shape: enqueues the neutral job above, so its payload carries no `orgId`. */
+const neutralTaskSource = (
+  name: NameSet,
+  jobName: NameSet,
+): string => `// ${name.camel}: a scheduled trigger. Tasks only enqueue jobs — the work itself is durable and
+// retryable, and the schedule carries an explicit IANA time zone.
+
+import { task } from '@ultimat3/jobs';
+import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
+
+export const ${name.camel} = task({
+  cron: '0 3 * * *',
+  tz: 'UTC',
+  // No org in the payload: the job this enqueues declares \`tenant: 'none'\`, because this
+  // feature's entity names no tenant column (or has none yet).
+  enqueue: () => [[${jobName.camel}, { id: '00000000-0000-4000-8000-000000000001' }]],
+});
+`;
+
 const jobTest = (
   name: NameSet,
 ): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
@@ -121,6 +177,63 @@ jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
 });
 `;
 
+/** The job test's other shape: no `orgId` anywhere, and a `tenantFor` that reads `undefined`. */
+const neutralJobTest = (
+  name: NameSet,
+): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
+// are the framework's, so what this pins is that THIS job's steps run and are idempotent.
+import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '00000000-0000-4000-8000-000000000001';
+const input = { id };
+// The key this job owes, spelled once. Named rather than inlined so the assertion below carries
+// the job's own name and still fits the formatter width the app's \`lint\` step enforces.
+const expectedKey = \`${name.kebab}:\${id}\`;
+
+// The driver is process-global, so it is installed and released around this file rather than
+// left behind for whichever test happens to run next.
+beforeAll(() => {
+  setJobDriver(createMemoryDriver());
+});
+afterAll(resetJobDriver);
+
+jobTest('${name.camel} declares a key and a retry policy', () => {
+  expect(${name.camel}.kind).toBe('job');
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(expectedKey);
+  expect(${name.camel}.retry.attempts).toBeGreaterThan(1);
+});
+
+jobTest('${name.camel} derives the same key for the same input', () => {
+  const key = ${name.camel}.idempotencyKeyFor(input);
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(key);
+});
+
+jobTest('${name.camel} declares no tenant', () => {
+  // This feature's entity names no tenant column (or has none yet) — \`tenant: 'none'\` is the
+  // declaration for that, and it strips one rather than inheriting the worker's, which is what
+  // stands between a read added here later and X_TENANCY_ACTOR_ORG_REQUIRED, or worse, another
+  // org's rows if this ever gains one.
+  expect(${name.camel}.tenantFor(input)).toBeUndefined();
+});
+
+jobTest('${name.camel} projects itself into the manifest', () => {
+  const described = ${name.camel}.describe();
+  expect(described.queue).toBe('default');
+  expect(described.retry.attempts).toBe(5);
+});
+
+jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
+  // The whole point of the key: an at-least-once caller may enqueue twice and the work still
+  // happens once. \`.enqueue()\` is the one queue path — a job is never run inline.
+  const first = await ${name.camel}.enqueue(input);
+  expect(first.deduped).toBe(false);
+  const again = await ${name.camel}.enqueue(input);
+  expect(again.deduped).toBe(true);
+});
+`;
+
 const taskTest = (
   name: NameSet,
   jobName: NameSet,
@@ -163,28 +276,75 @@ jobTest('${name.camel} fires its declared entries', async () => {
 });
 `;
 
-export function jobFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+export interface JobOptions extends FeatureTarget {
+  /**
+   * This feature's own `entity.ts` as it stands on disk, or absent when the feature has none yet.
+   * Supplied by `run` for the same reason `ActionOptions.sliceErrors` is: whether the slice is
+   * tenant-scoped is a fact about THIS app, and a template that assumed `tenant: 'orgId'` wrote
+   * `repo.byId`/`repo.listByOrg` calls into a feature whose repo never declared them —
+   * `x g task purgeOrphans --feature links` on a `links` slice with no `orgId` produced files that
+   * did not compile.
+   */
+  readonly sliceEntity?: string;
+  /** This feature's own `repo.ts` as it stands on disk, or absent alongside `sliceEntity`. */
+  readonly sliceRepo?: string;
+}
+
+/**
+ * Whether `x g job`/`x g task` may assume the tenant-scoped shape: an `entity.ts` this feature
+ * does not have yet is about to be scaffolded fresh by `sliceFoundation` below, tenant-scoped by
+ * default — so absent counts as scoped. One that exists is trusted over that default: it declares
+ * a real, non-`'none'` `tenant`, AND its `repo.ts` actually exports the `byId`/`listByOrg` pair the
+ * tenant-scoped body calls. Both have to hold — an entity that still names `tenant: 'orgId'` after
+ * an author trimmed `listByOrg` out of `repo.ts` (or never generated one) is not a slice this job
+ * can read through either.
+ */
+export function isTenantScopedSlice(
+  sliceEntity: string | undefined,
+  sliceRepo: string | undefined,
+): boolean {
+  if (sliceEntity === undefined) return true;
+  const declaresTenant = /\btenant\s*:\s*'(?!none')[^']+'/.test(stripComments(sliceEntity));
+  if (!declaresTenant) return false;
+  if (sliceRepo === undefined) return true;
+  return sliceExports(sliceRepo, 'byId') && sliceExports(sliceRepo, 'listByOrg');
+}
+
+export function jobFiles(rawName: string, target: JobOptions): readonly GeneratedFile[] {
   const name = names(rawName);
   const dir = `${target.surfaceDir}/${target.feature}/jobs`;
+  const scoped = isTenantScopedSlice(target.sliceEntity, target.sliceRepo);
   return [
     // The job's steps read through `../repo`, which carries `../entity` for its row type. No
     // policy: a job has no request behind it and evaluates none, so a generated one would be a
     // file nobody asked for. `x g task` inherits this by composing `jobFiles` below.
-    ...sliceFoundation(target, ['entity']),
-    { path: `${dir}/${name.kebab}.ts`, contents: jobSource(name) },
+    // Only for the tenant-scoped shape: the neutral job below reads neither module, and a slice
+    // this feature does not own the tenancy of is not this generator's to scaffold an entity into.
+    ...(scoped ? sliceFoundation(target, ['entity']) : []),
+    {
+      path: `${dir}/${name.kebab}.ts`,
+      contents: scoped ? jobSource(name) : neutralJobSource(name),
+    },
     // `.job.test.ts`, because the gate types a test by its FILENAME: a `jobTest` in a plain
     // `<name>.test.ts` runs under `unit`, and `x test job` answers X_TEST_NO_FILES in an app that
     // is full of them. Same lesson `x g route` already carries for `page.e2e.test.ts`.
-    { path: `${dir}/${name.kebab}.job.test.ts`, contents: jobTest(name) },
+    {
+      path: `${dir}/${name.kebab}.job.test.ts`,
+      contents: scoped ? jobTest(name) : neutralJobTest(name),
+    },
   ];
 }
 
-export function taskFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+export function taskFiles(rawName: string, target: JobOptions): readonly GeneratedFile[] {
   const name = names(rawName);
   const jobName = names(`${rawName}-job`);
   const dir = `${target.surfaceDir}/${target.feature}/tasks`;
+  const scoped = isTenantScopedSlice(target.sliceEntity, target.sliceRepo);
   return [
-    { path: `${dir}/${name.kebab}.ts`, contents: taskSource(name, jobName) },
+    {
+      path: `${dir}/${name.kebab}.ts`,
+      contents: scoped ? taskSource(name, jobName) : neutralTaskSource(name, jobName),
+    },
     // A task's test is a `jobTest` too — it drives a queue — so it takes the same suffix.
     { path: `${dir}/${name.kebab}.job.test.ts`, contents: taskTest(name, jobName) },
     ...jobFiles(`${rawName}-job`, target),

package/src/templates/scaffold-auth.ts

@@ -23,9 +23,13 @@ const devActor = (
 // \`X_CONFIG_INVALID\` — which is what a scaffolded app did on its very first \`x dev\`.
 //
 // DEVELOPMENT ONLY, and the guard is the point: a viewer that followed this to staging would sign
-// every visitor in as an admin. \`bun test\` sets \`NODE_ENV=test\`, so it does not install there
-// either — a fixture mints its own actor, and a second one arriving from a cookie would decide
-// which actor a test is about.
+// every visitor in as an admin. FAILS CLOSED (\`fallback: 'production'\`) rather than trusting
+// \`tryResolveEnvironment\`'s own default: that default is \`development\`, so a process that named
+// NEITHER \`ULTIMATE_ENV\` nor \`NODE_ENV\` would otherwise read as development too — indistinguishable
+// from the one this file exists to allow. \`x dev\` declares \`ULTIMATE_ENV=development\` for exactly
+// this reason (whenever neither key is already set), so a bare \`x dev\` still installs this viewer;
+// \`bun test\` sets \`NODE_ENV=test\`, so it does not install there either — a fixture mints its own
+// actor, and a second one arriving from a cookie would decide which actor a test is about.
 //
 // REPLACE IT with the real thing: resolve a session cookie to a row, and return that actor.
 // Everything downstream — pages, policies, live subscribers, MCP tools — reads what this returns.
@@ -78,7 +82,7 @@ export const devActorFor = (role: DevRole): Actor => ({
 export function installDevAuthenticator(
   env: Readonly<Record<string, string | undefined>> = process.env,
 ): boolean {
-  if (tryResolveEnvironment({ env }) !== 'development') return false;
+  if (tryResolveEnvironment({ env, fallback: 'production' }) !== 'development') return false;
   configureAuthenticator((request) => devActorFor(devRoleFrom(request.header('cookie'))));
   logger.warn('every request is answered as a development viewer', {
     role: DEFAULT_DEV_ROLE,
@@ -133,6 +137,11 @@ unitTest('it installs in development and in no other environment', () => {
 
   expect(installDevAuthenticator({ ULTIMATE_ENV: 'production' })).toBe(false);
   expect(installDevAuthenticator({ ULTIMATE_ENV: 'staging' })).toBe(false);
+  // FAILS CLOSED: a process naming NEITHER key is production here, never the default-development
+  // a bare \`tryResolveEnvironment({ env })\` would answer. \`x dev\` is what makes a real \`x dev\`
+  // still install this viewer — it declares \`ULTIMATE_ENV=development\` before this module loads,
+  // for exactly the process this call simulates having none of.
+  expect(installDevAuthenticator({})).toBe(false);
   expect(configuredAuthenticator()).toBeUndefined();
 
   expect(installDevAuthenticator({ ULTIMATE_ENV: 'development' })).toBe(true);

package/src/templates/slice-foundation.ts

@@ -115,8 +115,12 @@ const listedExports = (code: string): readonly string[] =>
  */
 export function sliceExports(source: string, name: string): boolean {
   const code = stripComments(source);
+  // `(?:async\s+)?` before `function`: an `export async function byId` — every repo function
+  // `x g entity` scaffolds — matched neither this nor `listedExports`, so a caller checking for
+  // `byId`/`listByOrg` on a real repo.ts always read `false`. `async` has no meaning before
+  // `class`/`const`/`let`/`var`/`enum`, so it is scoped to `function` only.
   const declared = new RegExp(
-    `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|function|enum)\\s+${name}\\b`,
+    `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|(?:async\\s+)?function|enum)\\s+${name}\\b`,
   );
   return declared.test(code) || listedExports(code).includes(name);
 }

package/src/test-dotenv.ts

@@ -0,0 +1,125 @@
+// Single responsibility: which env keys reached THIS `x` process only because Bun auto-loaded
+// `.env.development` / `.env.development.local` at startup — so a `bun test` child this process
+// spawns (`test-shards.ts`, `verify-tests.ts`, `verify-test-run.ts`, `mcp-host.ts`'s `runTests`)
+// does not inherit a key a bare `bun test` would never have seen.
+//
+// PROBED ON BUN 1.4.2, and the probe decided the rule: an ambient env var SHADOWS a dotenv file's
+// own value for the same key (`FOO=dev bun test` with a fixture `.env.test` declaring `FOO=test`
+// still read `FOO=dev` inside the test). So a leaked key is never made safe by a legitimate test
+// file (`.env`, `.env.test`, …) also declaring it — if we left it in place, the leaked value would
+// go on shadowing that file's own value exactly as it shadows `.env.test` above. The only question
+// worth asking is the one `devOnlyLeakedKeys` answers: does this process's CURRENT value match
+// what `.env.development`/`.env.development.local` would have set? If yes, delete it and let the
+// child's own dotenv load (or absence of one) answer instead. If the current value differs, this
+// process's env holds something dotenv did not put there — a real export, CI, `.env.local` — and
+// deleting it is not this function's call to make.
+//
+// KNOWN LIMITATION, stated rather than hidden: a real ambient value that happens to COINCIDE with
+// the dev file's value is indistinguishable from a leak from here — there is no pre-dotenv
+// snapshot to compare against. This function resolves that ambiguity toward closing the leak.
+//
+// A SECOND PARSER, not a call to `env-example.ts`'s `parseEnvKeys`: that function is deliberately
+// keys-only ("half of them are placeholders" — it feeds `.env.example` rendering, where a secret's
+// value must never appear), and widening it to return values would change what a template
+// generator ships. This one exists to COMPARE values, a different job with a different file.
+
+import { readFileSync } from 'node:fs'; // why: Bun ships no synchronous file read with a graceful-missing return.
+// why: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+
+/** Bun's own grammar, matched against `env-example.ts`'s `ENV_KEY_RE` (kept separate: see header). */
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * One dotenv file's key/value pairs. A `Map`, not an object literal: a key of `constructor` or
+ * `__proto__` passes `ENV_KEY_RE` and reads back as a function on `Object.prototype`, the exact
+ * defect this repo's `verify-tests.ts` header names thirteen instances of.
+ *
+ * Quoting: a value opening with `"` or `'` runs to its closing quote (or end of value if the
+ * dotenv file never closes it), `#` included — Bun does not stop a quoted value at an internal
+ * `#`. An unquoted value stops at the first `#`, which is where an inline comment starts.
+ */
+export function parseDotenvValues(text: string): ReadonlyMap<string, string> {
+  const values = new Map<string, string>();
+  for (const raw of text.split('\n')) {
+    const line = raw.trim().replace(/^export\s+/, '');
+    if (line === '' || line.startsWith('#')) continue;
+    const separator = line.indexOf('=');
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    if (!ENV_KEY_RE.test(key)) continue;
+    const rest = line.slice(separator + 1).trim();
+    const quote = rest.startsWith('"') || rest.startsWith("'") ? rest[0] : undefined;
+    if (quote === undefined) {
+      const hash = rest.indexOf('#');
+      values.set(key, (hash >= 0 ? rest.slice(0, hash) : rest).trim());
+      continue;
+    }
+    const closing = rest.indexOf(quote, 1);
+    values.set(key, closing >= 0 ? rest.slice(1, closing) : rest.slice(1));
+  }
+  return values;
+}
+
+export interface DevOnlyLeakInput {
+  /** `.env.development`'s text, or `''` when the file does not exist. */
+  readonly devText: string;
+  /** `.env.development.local`'s text, or `''` — wins over `devText` for a shared key, Bun's own precedence. */
+  readonly devLocalText: string;
+  /** This process's environment, as `exec.ts` would spawn a child with it (before any override). */
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * The pure decision, no filesystem: every key `.env.development`/`.env.development.local` would
+ * set, where `env`'s CURRENT value for that key is exactly what the file would have set. See this
+ * file's header for why a legitimate test file declaring the same key does not exempt it.
+ */
+export function devOnlyLeakedKeys(input: DevOnlyLeakInput): readonly string[] {
+  const merged = new Map(parseDotenvValues(input.devText));
+  for (const [key, value] of parseDotenvValues(input.devLocalText)) merged.set(key, value);
+  const leaked: string[] = [];
+  for (const [key, devValue] of merged) {
+    // `Object.hasOwn` FIRST: `key` is data (a name out of a dotenv file), and `env['constructor']`
+    // on a plain object answers `Object.prototype`'s member, not `undefined` — the rule
+    // `scripts/proto-index.ts` ratchets, with its own sanctioned repair.
+    if (Object.hasOwn(input.env, key) && input.env[key] === devValue) leaked.push(key);
+  }
+  return leaked;
+}
+
+/** A missing dotenv file is the common case (no `.env.development.local` in most checkouts). */
+function readIfPresent(path: string): string {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The env override a `bun test` child spawned FROM `root` should get: every dev-only leaked key
+ * deleted. `exec.ts`'s `ExecOptions.env` reads an `undefined` value as "unset for this child,
+ * even though the parent has it" — see that file for why the merge could not otherwise express
+ * a deletion.
+ *
+ * `root` is the app/repo root the caller already resolved — NOT necessarily `process.cwd()`, which
+ * is what Bun actually auto-loaded `.env.development` relative to at this process's own startup.
+ * The two agree for every command that boots from the repo/app root, which is every one of them
+ * today; a future command invoked from a subdirectory would fail SAFE here (the file this reads
+ * would differ from the one Bun loaded, values would not match, and nothing gets stripped) rather
+ * than stripping the wrong key.
+ */
+export function testEnvOverrides(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+): Readonly<Record<string, string | undefined>> {
+  const leaked = devOnlyLeakedKeys({
+    devText: readIfPresent(join(root, '.env.development')),
+    devLocalText: readIfPresent(join(root, '.env.development.local')),
+    env,
+  });
+  const overrides: Record<string, string | undefined> = {};
+  for (const key of leaked) overrides[key] = undefined;
+  return overrides;
+}