@ultimat3/cli 23.0.0 → 25.0.0

package/src/app-permissions-site.ts

@@ -0,0 +1,48 @@
+// Single responsibility: a declaration site — a stack FRAME `@ultimat3/policy` recorded for a
+// `defineRoles()` or `definePermissions()` call — reduced to the file it names, absolute or
+// app-root-relative. Both `policy` step questions key their findings by it.
+
+// why: Bun ships no path API, and `posix.relative` is what turns a frame's absolute path into the
+// app-root-relative one every finding is keyed by — on POSIX-normalised input, so a Windows frame
+// and root compare the same way on every host.
+import { posix } from 'node:path';
+
+/**
+ * The location at the END of a frame — `at fn (<path>:<line>:<col>)` or `at <path>:<line>:<col>` —
+ * read lazily from the first place a path can start, so a `(` INSIDE the path (`/srv/shop (copy)/`)
+ * is part of it, and a drive letter (`C:\…`) is a path start too. Anchored at the end because a
+ * frame's location is always its last token, and the function name before it is not a path.
+ */
+const FRAME_LOCATION = /(?:^|[\s(])((?:[A-Za-z]:)?[\\/].*?\.[cm]?tsx?)(?::\d+){0,2}\)?\s*$/;
+
+/** The absolute source path a frame names, exactly as written, or `undefined`. */
+export function frameFile(site: string): string | undefined {
+  return FRAME_LOCATION.exec(site)?.[1];
+}
+
+/**
+ * `\` → `/`, and a drive letter rooted like a POSIX path with its case folded (`C:\a` → `/c:/a`):
+ * `@ultimat3/policy`'s `declaration-site.ts` compares frames `/`-normalised for the same reason —
+ * on Windows neither a frame nor a root holds a `/`, and a shell spells the drive either way.
+ */
+const comparable = (path: string): string => {
+  const slashed = path.replaceAll('\\', '/');
+  const drive = /^([A-Za-z]):\//.exec(slashed);
+  return drive === null ? slashed : `/${(drive[1] ?? '').toLowerCase()}:${slashed.slice(2)}`;
+};
+
+/** `file` relative to `root`, `/`-separated, whichever OS printed either of them. */
+export const rootRelative = (root: string, file: string): string =>
+  posix.relative(comparable(root), comparable(file));
+
+/**
+ * The frame's file relative to the app root, or `undefined` outside it: a locator nobody can act on
+ * is worse than none. The frame is the only place the declaring module's name exists by the time
+ * the declaration runs.
+ */
+export function siteFile(root: string, site: string): string | undefined {
+  const absolute = frameFile(site);
+  if (absolute === undefined) return undefined;
+  const rel = rootRelative(root, absolute);
+  return rel.startsWith('..') || rel.length === 0 || rel.startsWith('/') ? undefined : rel;
+}

package/src/app-permissions.ts

@@ -7,9 +7,6 @@
 // required it on `/dashboard`, declared it nowhere, and served HTTP 500 on two of its three routes
 // with `x verify` green (#F1). This is the question nothing asked.
 
-// why: Bun ships no path API, and `relative` is what turns a stack frame's absolute path into
-// the app-root-relative one every finding is keyed by.
-import { relative } from 'node:path';
 import {
   grantMatches,
   isKnownPermission,
@@ -21,6 +18,8 @@ import {
 import { routeEntries } from '@ultimat3/render';
 import { definedStorage } from '@ultimat3/storage';
 import { loadApp } from './app-load';
+import { borrowedFinding, borrowedPermissions, permissionsFile } from './app-permissions-borrowed';
+import { siteFile } from './app-permissions-site';
 import type { DuplicateProbe } from './duplicate-packages';
 import { duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import type { Finding } from './output';
@@ -45,19 +44,6 @@ export interface PermissionReference {
 /** What this check needs of a boot — the seam `i18n-registration.ts` already established. */
 export type AppLoader = (root: string) => Promise<{ readonly findings: readonly Finding[] }>;
 
-/**
- * A role's declaration site is a stack FRAME (`at foo (/abs/path.ts:3:1)`), which is the only
- * place the declaring module's name exists by the time `defineRoles` runs. Reduced to the
- * app-relative path an agent opens, or dropped: a locator nobody can act on is worse than none.
- */
-export function siteFile(root: string, site: string): string | undefined {
-  const match = /\(?(\/[^():]+\.[cm]?tsx?)(?::\d+)?(?::\d+)?\)?/.exec(site);
-  const absolute = match?.[1];
-  if (absolute === undefined) return undefined;
-  const rel = relative(root, absolute).replaceAll('\\', '/');
-  return rel.startsWith('..') || rel.length === 0 ? undefined : rel;
-}
-
 /** Every permission a registered role grants, with where that role was declared. */
 export function grantedReferences(root: string): readonly PermissionReference[] {
   const sites = roleDeclarationSites();
@@ -198,7 +184,11 @@ export async function policyFindings(
     unknown.length === 0
       ? ungrantedRequirements().map((rule) => ungrantedFinding(rule, rolesAt))
       : [];
-  const findings = [...duplicated, ...unknown, ...ungranted];
+  // Asked of KNOWN names only (`borrowedPermissions` skips the rest), so it rides beside the
+  // unknown half rather than behind it: one fault, one finding.
+  const declaredIn = permissionsFile(root);
+  const borrowed = borrowedPermissions(root).map((entry) => borrowedFinding(entry, declaredIn));
+  const findings = [...duplicated, ...unknown, ...borrowed, ...ungranted];
   return findings.length === 0 ? [] : [...findings, ...app.findings];
 }
 

package/src/app-root.ts

@@ -20,10 +20,14 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * the gate's dominant step, with `x doctor` reporting the runtime as fine. `--parallel` arrived in
  * the same release and is emitted now, so the floor may never fall below that patch.
  *
- * `1.4.0` rather than `1.3.13` because a floor is a claim about a runtime somebody TESTED: CI pins
- * `1.4.x`, both images build on `oven/bun:1.4-*`, and the per-worker database rests on
- * `BUN_TEST_WORKER_ID`'s numbering, probed on 1.4.0 and on nothing older. `scripts/bun-pin.test.ts`
- * holds this to the same series as every other pin.
+ * A 1.4 patch rather than `1.3.13` because a floor is a claim about a runtime somebody TESTED: CI
+ * pins one exact patch, both images build on that patch's `oven/bun:1.4-*` digest, and the
+ * per-worker database rests on `BUN_TEST_WORKER_ID`'s numbering, probed on 1.4 and on nothing older.
+ * It moved 1.4.0 → 1.4.2 with CI's pin (plan 2026/10/04/101, sweep 3): from then on 1.4.0 was a
+ * runtime nothing here ran, and the bundler defects fixed in 1.4.1 (oven-sh/bun#40578, #40650,
+ * #40657) change what `x build` emits. `scaffold-repo.ts` and the scaffold's CI read this constant,
+ * so a new app's `engines.bun` and its CI runtime move with it. `scripts/bun-pin.test.ts` holds it
+ * to the exact patch CI runs.
  *
  * **Lowering it to 1.3.14 was tried on 2026-08-27 and refused**, and the argument for trying was
  * sound — `--isolate` and `--parallel` are 1.3.13 features, no package here calls a 1.4-only API
@@ -34,7 +38,7 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * declared supported would hang on graceful shutdown the moment its database went away. The full
  * measurement is in `.github/actions/setup/action.yml`; read it before lowering this.
  */
-export const REQUIRED_BUN = '1.4.0';
+export const REQUIRED_BUN = '1.4.2';
 
 export interface AppRoot {
   readonly dir: string;

package/src/bin.ts

@@ -4,6 +4,7 @@
 
 import { dispatch } from './dispatch';
 import { resolveLocalCli } from './local-cli';
+import { handOff } from './local-cli-handoff';
 import { cwdFromArgv } from './root-env';
 // The writes themselves are `write-line.ts`: `create-ultimate`'s entry point needs the identical
 // one, and a second copy of a note about pipe truncation is a second copy that drifts. Two sinks,
@@ -24,13 +25,8 @@ const local = resolveLocalCli({
 });
 if (local !== undefined) {
   writeErrorLine(`x: using the app's own @ultimat3/cli at ${local}`);
-  const child = Bun.spawn([process.execPath, local, ...Bun.argv.slice(2)], {
-    stdin: 'inherit',
-    stdout: 'inherit',
-    stderr: 'inherit',
-    env: Bun.env,
-  });
-  process.exit(await child.exited);
+  // Stop signals are forwarded and the child's code is ours: see local-cli-handoff.ts.
+  process.exit(await handOff([process.execPath, local, ...Bun.argv.slice(2)], Bun.env));
 }
 
 // `x dev` supervises a child that serves (`dev-supervisor.ts`): a save that reaches a module which

package/src/browser-launcher.ts

@@ -39,7 +39,8 @@ export class ShotChromeMissingError extends UltimateError {
       // One literal, so `fix-scan.ts` can read it. A path is the one repair that works whatever the
       // browser is and wherever the distribution put it; `--cdp-url` is the answer for a box that
       // will never have one, and it is a flag `x shot` already ships.
-      fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome or Chromium binary; a box that will never have one attaches instead: x shot / --cdp-url wss://cdp.example.com/session/abc',
+      // The `#` names the macOS and Windows spellings: one literal for every platform.
+      fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome, Chromium or Edge binary — macOS: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; Windows PowerShell: $env:CHROME_PATH = "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" (Edge: "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"); a box that will never have one attaches instead: x shot / --cdp-url wss://cdp.example.com/session/abc',
       meta: { tried: [...CHROME_CANDIDATES], vars: [...BROWSER_PATH_VARS] },
     });
   }
@@ -67,7 +68,8 @@ export const browserBinaryExists = (path: string): boolean => existsSync(path);
 /**
  * The path a run will launch, or `undefined` when this machine has no browser to launch.
  *
- * The last step is a PROBE — the four paths `cdp-launch.ts` tries for the e2e driver, imported
+ * The last step is a PROBE — the paths `cdp-launch.ts` tries for the e2e driver on THIS platform
+ * (`/usr/bin` on Linux, the app bundles on macOS, Chrome and Edge on Windows), imported
  * rather than restated, because two lists of Chrome locations that must agree is the drift axiom 2
  * refuses — so a box with no browser is refused before a dev-server boot, not one launch later.
  *

package/src/budgets-charged.ts

@@ -0,0 +1,60 @@
+// What a route's measured JavaScript was made of, file by file: the clause and the `--json` facts
+// `X_BUDGET_EXCEEDED` carries, so a reader can tell a heavier chunk from a byte counted twice
+// without re-running the build. Split from `budgets.ts`, which measures and compares.
+
+import type { JsonValue } from './output';
+
+/** One app file a document made the browser fetch, and its bytes on disk. */
+export interface ChargedFile {
+  readonly url: string;
+  readonly bytes: number;
+}
+
+/**
+ * Named in the cause; the rest are summed. A page carries one or two files in practice, and a
+ * sentence listing forty is one nobody reads — `meta.charged` still holds every one of them.
+ */
+const NAMED_FILES = 5;
+
+/** Heaviest first, then by URL, so the clause and the stats file are reproducible. */
+export function heaviestFirst(files: readonly ChargedFile[]): readonly ChargedFile[] {
+  return [...files].sort((a, b) =>
+    b.bytes !== a.bytes ? b.bytes - a.bytes : a.url < b.url ? -1 : a.url > b.url ? 1 : 0,
+  );
+}
+
+/**
+ * `; charged: /islands/post-form-04f75f18.js 81306 B, inline scripts 855 B` — exact bytes, never
+ * `formatBytes`: a 22 kB disagreement between two platforms is the question this answers, and a
+ * rounded figure hides the byte a duplicate shows up as. Empty for a row an older build wrote.
+ */
+export function chargedClause(
+  charged: readonly ChargedFile[] | undefined,
+  inlineBytes: number | undefined,
+): string {
+  const files = heaviestFirst(charged ?? []);
+  const parts = files.slice(0, NAMED_FILES).map((one) => `${one.url} ${String(one.bytes)} B`);
+  const rest = files.slice(NAMED_FILES);
+  if (rest.length > 0) {
+    const bytes = rest.reduce((sum, one) => sum + one.bytes, 0);
+    parts.push(`${String(rest.length)} more files ${String(bytes)} B`);
+  }
+  if (inlineBytes !== undefined && inlineBytes > 0) {
+    parts.push(`inline scripts ${String(inlineBytes)} B`);
+  }
+  return parts.length === 0 ? '' : `; charged: ${parts.join(', ')}`;
+}
+
+/** The same facts as data, or `undefined` when the row predates them — absent is not empty. */
+export function chargedMeta(
+  jsBytes: number,
+  charged: readonly ChargedFile[] | undefined,
+  inlineBytes: number | undefined,
+): { readonly [key: string]: JsonValue } | undefined {
+  if (charged === undefined && inlineBytes === undefined) return undefined;
+  return {
+    jsBytes,
+    charged: heaviestFirst(charged ?? []).map((one) => ({ url: one.url, bytes: one.bytes })),
+    inlineJsBytes: inlineBytes ?? 0,
+  };
+}

package/src/budgets-scan.ts

@@ -0,0 +1,76 @@
+// How the budget measurer READS an emitted document: which tags are code, which attribute names an
+// island entry, which path a URL is fetched at, and which files a module makes the browser load.
+// Split from `budgets.ts`, which decides what of that is charged and compares it to the budget.
+
+import { SPECULATION_RULES_TYPE } from '@ultimat3/render';
+
+export const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
+export const SRC_ATTR = /\ssrc="(?<src>[^"]*)"/;
+const TYPE_ATTR = /\stype="(?<type>[^"]*)"/;
+
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code — the rule
+ * `@ultimat3/render`'s `head.ts` already states, restated because its `carriesJson` reads a
+ * `HeadTag` and is not exported, and this side has an attribute string off the emitted document.
+ * Without it a page shipping only `meta.ld` structured data and island props measured 8kb of JS
+ * and failed a 2kb budget with a `fix:` naming an import chain that does not exist.
+ */
+export const carriesJson = (attrs: string): boolean => {
+  // Everything from the first `;` is a MIME PARAMETER and not the type: a real document writes
+  // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
+  // test alone charged an SEO structured-data block as executable JavaScript all over again.
+  const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
+  const declared = type.trim().toLowerCase();
+  // Speculation rules are JSON under a type that does not say so: read by the browser's
+  // prefetcher, never executed — the one script a 0kb page may carry for free.
+  return declared.endsWith('json') || declared === SPECULATION_RULES_TYPE;
+};
+
+/**
+ * An island's chunk is reached by `import()` from inside the hydration runtime, so it never appears
+ * as a `<script src>` — and a document weighed by script tags alone was charged for the runtime and
+ * never for the code that runtime boots. The entry attribute is that module URL, so it is read as
+ * exactly what it is: a file the browser will execute.
+ */
+export const ENTRY_ATTR = /\sdata-x-entry="(?<url>[^"]*)"/g;
+
+/**
+ * Static imports and `import()` both. A chunk reached by `import()` was INLINED into its island
+ * before islands were split, so charging it keeps a route's number what it was; and it is fetched
+ * the moment the island needs it, which is before the page does what it was loaded for.
+ */
+const LOADS: ReadonlySet<string> = new Set(['import-statement', 'dynamic-import']);
+
+/** The origin every artifact path is resolved against — a name that can never be a real host. */
+const ARTIFACT_ORIGIN = 'https://artifact.invalid';
+
+/**
+ * The path a browser fetches for a root-relative `url`, or `undefined` for one that is not this
+ * artifact's. Resolved with the WHATWG parser, the browser's own: it reads `\` as `/`, folds `.`
+ * and `..`, drops a query, and makes `//host/a.js` another origin. The dedupe below is keyed by
+ * this, because it is the FETCH that is counted once, and a raw string kept two spellings of one
+ * file apart — which `join` on Windows then turned back into one real path, charged twice.
+ */
+export function artifactPath(url: string): string | undefined {
+  if (!url.startsWith('/')) return undefined;
+  const resolved = URL.parse(url, ARTIFACT_ORIGIN);
+  return resolved?.origin === ARTIFACT_ORIGIN ? resolved.pathname : undefined;
+}
+
+/** Same-origin paths `code`, served at `url`, makes the browser load. Cross-origin and bare are not this build's. */
+export function loadedBy(url: string, code: string): readonly string[] {
+  let imports: readonly { readonly path: string; readonly kind: string }[];
+  try {
+    imports = new Bun.Transpiler({ loader: 'js' }).scanImports(code);
+  } catch {
+    // A file that does not parse as JavaScript imports nothing this gate can name; its own bytes
+    // are already charged.
+    return [];
+  }
+  const base = new URL(url, ARTIFACT_ORIGIN);
+  return imports
+    .filter((one) => LOADS.has(one.kind) && /^\.{0,2}\//.test(one.path))
+    .map((one) => new URL(one.path, base))
+    .filter((target) => target.origin === base.origin)
+    .map((target) => target.pathname);
+}

package/src/budgets-unmeasured.ts

@@ -0,0 +1,91 @@
+// Single responsibility: the finding for a budgeted route a build RAN and could not weigh, read off
+// the static report's `unmeasured` entry — under the failure's own code when that code is the
+// instruction, as an actor edit when the measurement actor was refused, the report otherwise.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Finding } from './output';
+import type { UnmeasuredRoute } from './static-report';
+
+/**
+ * The ONE code a failed measurement is reported under by its own name rather than as
+ * `X_BUDGET_UNMEASURED`. Its cause is complete — the island, the prop, its bytes, the cap — and
+ * its fix is an edit to the page, so the step's own "run x build and read the list" would put a
+ * second command between the author and a sentence the build had already composed. Every other
+ * render failure keeps the generic finding: a `TypeError` from a `load` that wanted a request is
+ * a reason to read the report, not an instruction.
+ *
+ * ONE code and not "any coded error", deliberately. `X_NO_CONTEXT` and `X_DB_UNAVAILABLE` from a
+ * measurement render are facts about the BUILD's environment, and reporting them under their own
+ * codes would tell the author to fix a database the gate never had. The list grows by a decision,
+ * per code, here.
+ */
+const REPORTED_BY_OWN_CODE: ReadonlySet<string> = new Set([
+  'X_ISLAND_PROPS_INVALID',
+  // A dynamic route that lists no `prerender()` path: the edit is in the route, not the build.
+  'X_BUDGET_PARAMS_UNDECLARED',
+]);
+
+/**
+ * Refusals of WHO the render ran as. The actor is the app's own declaration (core's
+ * `defineMeasurementActor`, in `app.config.ts`), so these ARE an instruction — but the refusal's
+ * own `fix:` was written for a request ("sign in", "mint the actor with its tenant at the request
+ * boundary") and names no build-time edit. The default actor is a service actor holding `*` with
+ * no org and no roles: a page whose policy names a role, or whose `load` reads a tenant-scoped
+ * entity, is refused under it (#675).
+ */
+const ACTOR_REFUSALS: ReadonlySet<string> = new Set([
+  'X_FORBIDDEN',
+  'X_UNAUTHENTICATED',
+  'X_TENANCY_ACTOR_ORG_REQUIRED',
+]);
+
+function ownCodeFinding(url: string, entry: UnmeasuredRoute): Finding {
+  return {
+    code: entry.code ?? 'X_BUDGET_UNMEASURED',
+    cause: entry.cause ?? entry.reason,
+    fix: entry.fix ?? `x build --target static --json   # its "unmeasured" list has ${url}`,
+    docs: ERROR_DOCS_URL,
+    at: url,
+  };
+}
+
+/** `CODE: cause` when the failure had a code, its rendered reason otherwise. */
+const refusalOf = (entry: UnmeasuredRoute): string =>
+  entry.code === undefined ? entry.reason : `${entry.code}: ${entry.cause ?? entry.reason}`;
+
+/**
+ * A build ran and has no row for `url`. `entry` is the report's account of why, when it has one:
+ * an instruction under its own code, an actor edit, or — for a failure that is a fact about the
+ * build's environment — the report, with the refusal already in the cause.
+ */
+export function builtUnmeasuredFinding(
+  url: string,
+  declared: string,
+  statsFile: string,
+  entry: UnmeasuredRoute | undefined,
+): Finding {
+  if (entry?.code !== undefined && REPORTED_BY_OWN_CODE.has(entry.code)) {
+    return ownCodeFinding(url, entry);
+  }
+  const base = `${url} declares a ${declared} budget and ${statsFile} has no row for it, so the build ran and could not weigh it`;
+  if (entry?.code !== undefined && ACTOR_REFUSALS.has(entry.code)) {
+    const actor = entry.actor ?? 'the measurement actor';
+    return {
+      code: 'X_BUDGET_UNMEASURED',
+      cause: `${base}: rendered as ${actor}, it was refused ${refusalOf(entry)}`,
+      // The paste: one declaration in the one file every build imports.
+      fix: "defineMeasurementActor(() => userActor({ id: 'measure', orgId: '<an org your dev seed creates>', roles: ['<the role this page requires>'] }))   # in app.config.ts",
+      docs: ERROR_DOCS_URL,
+      at: url,
+    };
+  }
+  return {
+    code: 'X_BUDGET_UNMEASURED',
+    cause: entry === undefined ? base : `${base}: ${refusalOf(entry)}`,
+    // When a build already ran, the report is where the rest of the answer is — it names every
+    // route it could not weigh, and why.
+    fix: `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`,
+    docs: ERROR_DOCS_URL,
+    at: url,
+  };
+}