@cosmicdrift/kumiko-guards 0.3.0 → 0.282.0

package/src/guard-escape-hatch-declared.ts

@@ -6,15 +6,18 @@
  *   R1 raw-outside-system-scope: a TenantDb `.raw` escape used outside a
  *      `r.systemScope()` feature.
  *   R2 unsafe-raw-outside-system-scope: `ctx.systemDb.unsafeRaw(...)` outside
- *      systemScope, a job scope, an explicit `withUnsafeRawGrant(...)`, or a
- *      handler/hook that lexically declares `escapeHatch`.
+ *      systemScope, a job scope, an explicit `withUnsafeRawGrant(...)`, a
+ *      handler/hook that lexically declares `escapeHatch`, or a standalone
+ *      function whose direct body declares `declareEscapeHatch({ reason: "..." })`.
  *   R3 system-identity-outside-declared-scope: `queryAs`/`writeAs` called
  *      with a system identity outside systemScope, `.job.ts`, an `r.job(...)`
- *      call, a `*Job` function, or a handler/hook that lexically declares
- *      `escapeHatch`.
- *   R4 generic-reason: `acknowledgeCrossTenant`/`unsafeRaw`, or a declared
- *      `escapeHatch: { reason }`/`unsafeAllTenants: { reason }`, given a
- *      placeholder reason literal — hard-fails everywhere, not baselined.
+ *      call, a `*Job` function, a handler/hook that lexically declares
+ *      `escapeHatch`, or a standalone function whose direct body declares
+ *      `declareEscapeHatch({ reason: "..." })`.
+ *   R4 generic-reason: `acknowledgeCrossTenant`/`unsafeRaw`, a declared
+ *      `escapeHatch: { reason }`/`unsafeAllTenants: { reason }`, or a
+ *      `declareEscapeHatch({ reason })` call, given a placeholder reason
+ *      literal — hard-fails everywhere, not baselined.
  *   R5 unsafe-all-tenants-outside-declared-scope: an `unsafeAllTenants: true`
  *      or `unsafeAllTenants: { reason: "..." }` option, passed directly as a
  *      call argument, outside systemScope, `.job.ts`, an `r.job(...)` call,
@@ -26,26 +29,49 @@
  * FunctionExpression, under any key name — e.g. `handler`, `export`,
  * `delete`), or in an options object passed to
  * `r.hook`/`writeHandler`/`queryHandler`/`streamHandler`/`useExtension`
- * alongside the handler function argument. Referenced-by-variable functions,
- * spread options, computed/string keys, and non-literal escapeHatch values
- * are conservatively not recognized (miss, don't falsely clear).
+ * alongside the handler function argument. A standalone function (arrow
+ * function, function expression, method declaration, or function
+ * declaration) is additionally recognized when a statement in its own direct
+ * body — not a nested function's, not inside an `if` — calls the bare
+ * identifier `declareEscapeHatch` with exactly one object-literal argument
+ * carrying a literal, non-placeholder `reason` (from
+ * `@cosmicdrift/kumiko-framework/engine`'s `declareEscapeHatch`: a helper
+ * that escalates on a `HandlerContext` handed to it by its caller, rather
+ * than a `HandlerContext` from its own registration). The declaration does
+ * not propagate upward: it covers escalations inside that function's own
+ * body, not the function it is nested inside. This detection is purely
+ * lexical — the guard matches on the name `declareEscapeHatch`, not on where
+ * it was imported from, so a same-named local function clears just as well;
+ * consistent with `escapeHatch:` itself, which is likewise never checked for
+ * origin. Referenced-by-variable functions, spread options, computed/string
+ * keys, and non-literal escapeHatch/reason values are conservatively not
+ * recognized (miss, don't falsely clear).
  *
  * Empty reasons, `openToAll.personalData` and PII are the framework boot validator's
- * job (access-declarations.ts), not this guard's. Known false-negatives:
- * multi-hop aliasing, `ctx["db"]` through an intermediate variable, and a
- * TenantDb/system-identity handed to another function across file
- * boundaries — all conservative (miss, don't falsely flag). R5 additionally
- * misses `unsafeAllTenants` given via an identifier, a ternary, `false`, or
- * `undefined`, and an options object passed by variable reference or spread
- * rather than as a literal call argument — all conservative (miss, don't
- * falsely flag).
+ * job (access-declarations.ts), not this guard's — except a `declareEscapeHatch`
+ * reason, which has no boot validator behind it: an empty or placeholder
+ * reason there is never recognized as a valid declaration (see R4). Known
+ * false-negatives: multi-hop aliasing, `ctx["db"]` through an intermediate
+ * variable, and a TenantDb/system-identity handed to another function across
+ * file boundaries with no `declareEscapeHatch` call at the escalation site
+ * (declarable now, so no longer a blanket false-negative) — all conservative
+ * (miss, don't falsely flag). R5 additionally misses `unsafeAllTenants`
+ * given via an identifier, a ternary, `false`, or `undefined`, and an
+ * options object passed by variable reference or spread rather than as a
+ * literal call argument — all conservative (miss, don't falsely flag).
  *
  * Usage:
  *   bun guards/guard-escape-hatch-declared.ts
  *   Baseline: bun guards/run-guards.ts --write-security-baseline
  */
 import * as path from "node:path";
-import { type Node, type ObjectLiteralExpression, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type Node,
+  type ObjectLiteralExpression,
+  type PropertyAssignment,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
 import { isGenericReason, literalReasonText } from "./_lib/generic-reason";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
@@ -330,15 +356,72 @@ function isEscapeHatchDeclaredFunction(fn: Node): boolean {
   return false;
 }
 
+// The bare-identifier `reason` PropertyAssignment on an object literal —
+// shared between the declareEscapeHatch statement check below and its R4
+// generic-reason collector, so both agree on what counts as the reason.
+function findReasonPropertyAssignment(
+  obj: ObjectLiteralExpression,
+): PropertyAssignment | undefined {
+  return obj
+    .getProperties()
+    .find(
+      (prop): prop is PropertyAssignment =>
+        prop.isKind(SyntaxKind.PropertyAssignment) &&
+        prop.getNameNode().isKind(SyntaxKind.Identifier) &&
+        prop.getNameNode().getText() === "reason",
+    );
+}
+
+// declareEscapeHatch({ reason: "..." }) as a direct-body statement of a
+// standalone function. No boot validator backs this form (unlike the
+// escapeHatch: {...} property, which access-declarations.ts checks at boot),
+// so an empty/placeholder reason is rejected here rather than left to it.
+function isValidDeclareEscapeHatchCall(stmt: Node): boolean {
+  if (!stmt.isKind(SyntaxKind.ExpressionStatement)) return false;
+  const expr = stmt.getExpression();
+  if (!expr.isKind(SyntaxKind.CallExpression)) return false;
+  const callee = expr.getExpression();
+  if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
+    return false;
+  }
+  const args = expr.getArguments();
+  const arg = args[0];
+  if (args.length !== 1 || !arg?.isKind(SyntaxKind.ObjectLiteralExpression)) return false;
+  const reasonProp = findReasonPropertyAssignment(arg);
+  if (!reasonProp) return false;
+  const reasonText = literalReasonText(reasonProp.getInitializer());
+  return reasonText !== undefined && !isGenericReason(reasonText);
+}
+
+// Only the function's own direct body — not a nested function's, not an
+// `if`'s — so a declareEscapeHatch call does not cover the function it is
+// itself nested inside (miss, don't falsely clear).
+function hasDeclaredEscapeHatchStatement(fn: Node): boolean {
+  let body: Node | undefined;
+  if (
+    fn.isKind(SyntaxKind.ArrowFunction) ||
+    fn.isKind(SyntaxKind.FunctionExpression) ||
+    fn.isKind(SyntaxKind.MethodDeclaration) ||
+    fn.isKind(SyntaxKind.FunctionDeclaration)
+  ) {
+    body = fn.getBody();
+  }
+  if (!body?.isKind(SyntaxKind.Block)) return false;
+  return body.getStatements().some((stmt) => isValidDeclareEscapeHatchCall(stmt));
+}
+
 function isInsideEscapeHatchDeclaredFunction(node: Node): boolean {
   let ancestor: Node | undefined = node.getParent();
   while (ancestor) {
     if (
       ancestor.isKind(SyntaxKind.ArrowFunction) ||
       ancestor.isKind(SyntaxKind.FunctionExpression) ||
-      ancestor.isKind(SyntaxKind.MethodDeclaration)
+      ancestor.isKind(SyntaxKind.MethodDeclaration) ||
+      ancestor.isKind(SyntaxKind.FunctionDeclaration)
     ) {
-      if (isEscapeHatchDeclaredFunction(ancestor)) return true;
+      if (isEscapeHatchDeclaredFunction(ancestor) || hasDeclaredEscapeHatchStatement(ancestor)) {
+        return true;
+      }
     }
     ancestor = ancestor.getParent();
   }
@@ -453,6 +536,35 @@ function findGenericReasonMethodCalls(sf: SourceFile, root: string): GenericReas
   return out;
 }
 
+// The declareEscapeHatch({ reason }) form falls through both existing R4
+// collectors: its callee is a bare identifier, not a PropertyAccessExpression
+// (unlike acknowledgeCrossTenant/unsafeRaw), and its reason sits directly in
+// the call argument, not under an escapeHatch:/unsafeAllTenants: property.
+function findGenericReasonDeclareEscapeHatchCalls(
+  sf: SourceFile,
+  root: string,
+): GenericReasonFinding[] {
+  const out: GenericReasonFinding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
+      continue;
+    }
+    const arg = call.getArguments()[0];
+    if (!arg?.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
+    const reasonProp = findReasonPropertyAssignment(arg);
+    if (!reasonProp) continue;
+    const reasonText = literalReasonText(reasonProp.getInitializer());
+    if (reasonText === undefined || !isGenericReason(reasonText)) continue;
+    out.push({
+      file: path.relative(root, sf.getFilePath()),
+      line: call.getStartLineNumber(),
+      message: `declareEscapeHatch({ reason: "${reasonText}" }) uses a placeholder reason — give a concrete, reviewable justification for this cross-tenant/unsafe access.`,
+    });
+  }
+  return out;
+}
+
 const REASON_OBJECT_PROPERTY_NAMES = ["escapeHatch", "unsafeAllTenants"] as const;
 
 function findGenericReasonObjectProperty(
@@ -488,6 +600,7 @@ export function findGenericReasonCalls(
   const out: GenericReasonFinding[] = [];
   for (const sf of scannableFiles(files)) {
     out.push(...findGenericReasonMethodCalls(sf, root));
+    out.push(...findGenericReasonDeclareEscapeHatchCalls(sf, root));
     for (const propertyName of REASON_OBJECT_PROPERTY_NAMES) {
       out.push(...findGenericReasonObjectProperty(sf, root, propertyName));
     }

package/src/guard-upgrade-state.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env bun
+/**
+ * Guard: a consumer repo's `.kumiko/upgrade-state.json` marker must be
+ * caught up with the installed Kumiko framework version.
+ *
+ * The marker is written by `kumiko-upgrade --apply` (local bin from
+ * `@cosmicdrift/kumiko-dev-server`) and records the version it was applied
+ * at. This guard re-runs `kumiko-upgrade --from <marker version> --json` and
+ * fails if any changelog entries are still pending — meaning the marker is
+ * stale and the repo hasn't run the upgrade since.
+ *
+ * Single-repo only, like `guard-upgrade-state.ts` in infra/guards but
+ * without that package's multi-repo `resolveRepoRoots()` scan loop — this
+ * package's `resolveRepoRoots()` only ever resolves the one repo `roots[0]`
+ * sits in. Repos without the marker file are `notApplicable` — this guard
+ * only fires once a repo has adopted the upgrade-state workflow at all.
+ *
+ * Usage:
+ *   bun guard-upgrade-state.ts
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+
+const MARKER_REL = ".kumiko/upgrade-state.json";
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+type UpgradeMarker = { readonly version: string };
+
+type PendingEntry = {
+  readonly version: string;
+  readonly type: string;
+  readonly title: string;
+};
+
+type UpgradeJson = {
+  readonly currentVersion: string;
+  readonly installedVersion?: string | null;
+  readonly pending: readonly PendingEntry[];
+};
+
+export function resolveInstalledVersion(json: UpgradeJson): string {
+  return json.installedVersion ?? json.currentVersion;
+}
+
+export function isPendingEntry(value: unknown): value is PendingEntry {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["version"] === "string" &&
+    typeof v["type"] === "string" &&
+    typeof v["title"] === "string"
+  );
+}
+
+export function isUpgradeJson(value: unknown): value is UpgradeJson {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  const installed = v["installedVersion"];
+  return (
+    typeof v["currentVersion"] === "string" &&
+    (installed === undefined || installed === null || typeof installed === "string") &&
+    Array.isArray(v["pending"]) &&
+    v["pending"].every(isPendingEntry)
+  );
+}
+
+export function readMarker(root: string): UpgradeMarker | { error: string } {
+  const markerPath = join(root, MARKER_REL);
+  if (!existsSync(markerPath)) {
+    return {
+      error: `missing ${MARKER_REL} — run \`bun run kumiko-upgrade --apply\` once and commit the marker file`,
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(markerPath, "utf-8"));
+  } catch {
+    return { error: `${MARKER_REL} is not valid JSON — broken marker file` };
+  }
+  const version =
+    parsed && typeof parsed === "object"
+      ? (parsed as Record<string, unknown>)["version"]
+      : undefined;
+  if (typeof version !== "string" || !SEMVER_RE.test(version)) {
+    return {
+      error: `${MARKER_REL} is missing a valid "version" field (expected semver x.y.z[-pre][+build]) — broken marker file`,
+    };
+  }
+  return { version };
+}
+
+/** Pending changelog entries turned into guard violations — pure, testable without a subprocess. */
+export function pendingViolations(json: UpgradeJson, markerVersion: string): GuardViolation[] {
+  if (json.pending.length === 0) return [];
+  const installedVersion = resolveInstalledVersion(json);
+  return json.pending.map((entry) => ({
+    file: MARKER_REL,
+    line: 1,
+    message:
+      `${MARKER_REL} is at ${markerVersion}, installed is ${installedVersion} — pending: ` +
+      `${entry.version} · ${entry.type} · ${entry.title}. Run \`bun run kumiko-upgrade --apply\`.`,
+  }));
+}
+
+function resolveKumikoUpgradeBin(cwd: string): string | undefined {
+  const which = Bun.which("kumiko-upgrade");
+  if (which) return which;
+  let dir = cwd;
+  for (;;) {
+    const candidate = join(dir, "node_modules", ".bin", "kumiko-upgrade");
+    if (existsSync(candidate)) return candidate;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+async function runKumikoUpgrade(
+  version: string,
+  cwd: string,
+): Promise<{ ok: true; json: UpgradeJson } | { ok: false; error: string }> {
+  const binPath = resolveKumikoUpgradeBin(cwd);
+  if (!binPath) {
+    return {
+      ok: false,
+      error:
+        "`kumiko-upgrade` not resolvable — add `@cosmicdrift/kumiko-dev-server` as a devDependency or repair the install",
+    };
+  }
+  const proc = Bun.spawn({
+    cmd: [binPath, "--from", version, "--json"],
+    cwd,
+    env: { ...process.env, INIT_CWD: cwd },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    return {
+      ok: false,
+      error: `\`kumiko-upgrade --from ${version} --json\` exited ${exitCode}:\n${stderr || stdout}`,
+    };
+  }
+  let parsed: unknown;
+  try {
+    const jsonStart = stdout.indexOf("{");
+    parsed = JSON.parse(jsonStart >= 0 ? stdout.slice(jsonStart) : stdout);
+  } catch {
+    return {
+      ok: false,
+      error: `\`kumiko-upgrade --from ${version} --json\` did not print valid JSON:\n${stdout}${stderr}`,
+    };
+  }
+  if (!isUpgradeJson(parsed)) {
+    return {
+      ok: false,
+      error: `\`kumiko-upgrade --from ${version} --json\` printed JSON without a valid "pending" array:\n${stdout}`,
+    };
+  }
+  return { ok: true, json: parsed };
+}
+
+export const check: RepoCheck = {
+  name: "Upgrade-State Guard",
+  hint: "Marker is written by `kumiko-upgrade --apply` — run it once the pending changelog entries are handled.",
+  async run(roots) {
+    const root = roots[0];
+    if (!root) return { violations: [], matchedFiles: 0, notApplicable: true };
+    const rootAbsPath = root.absPath;
+    if (!existsSync(join(rootAbsPath, MARKER_REL))) {
+      return { violations: [], matchedFiles: 0, notApplicable: true };
+    }
+    const marker = readMarker(rootAbsPath);
+    if ("error" in marker) {
+      return {
+        violations: [{ file: MARKER_REL, line: 1, message: marker.error }],
+        matchedFiles: 1,
+        notApplicable: false,
+      };
+    }
+    const result = await runKumikoUpgrade(marker.version, rootAbsPath);
+    if (!result.ok) {
+      return {
+        violations: [{ file: MARKER_REL, line: 1, message: result.error }],
+        matchedFiles: 1,
+        notApplicable: false,
+      };
+    }
+    return {
+      violations: pendingViolations(result.json, marker.version),
+      matchedFiles: 1,
+      notApplicable: false,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 export {
   type AstGuard,
+  buildGuardKitInventory,
   buildSharedProject,
   explainGuards,
   filesForGuard,
+  type GuardKitInventory,
   type GuardOutcome,
   type GuardViolation,
   isSecurityGuard,
@@ -14,6 +16,7 @@ export {
   runGuards,
   runRepoChecks,
   type ScanSpec,
+  type SuiteInventory,
 } from "./_lib/guard-kit";
 export { findLocalRepo, type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 export {

package/src/run-guards.ts

@@ -9,6 +9,7 @@
 // security guards.
 import {
   buildSharedProject,
+  cliFlagsError,
   explainGuards,
   isSecurityGuard,
   printGuardKitBanner,
@@ -86,26 +87,43 @@ export const GUARDS = [
   libTestCoverage,
 ];
 
-// Only run on direct invocation — otherwise `import { GUARDS }` would kick
-// off the whole suite and the list wouldn't be testable.
-if (import.meta.main) {
-  if (process.argv.includes("--explain")) {
+export const GUARD_FLAGS = [
+  "--explain",
+  "--write-security-baseline",
+  "--strict-security-baseline",
+] as const;
+
+// Shared by the direct `bun run-guards.ts` invocation below and by the
+// `guards` subcommand in cli.ts — one place for the flag behavior so the
+// two entry points can never drift.
+export function runGuardsCli(argv: readonly string[]): number {
+  const flagsError = cliFlagsError("guards", argv, GUARD_FLAGS);
+  if (flagsError !== undefined) {
+    console.error(flagsError);
+    return 1;
+  }
+  if (argv.includes("--explain")) {
     for (const line of explainGuards(GUARDS, buildSharedProject(GUARDS))) {
       console.log(line);
     }
-    process.exit(0);
+    return 0;
   }
-  if (process.argv.includes("--write-security-baseline")) {
+  if (argv.includes("--write-security-baseline")) {
     writeSecurityBaselines(
       GUARDS.filter(isSecurityGuard),
       buildSharedProject(GUARDS.filter(isSecurityGuard)),
     );
-    process.exit(0);
+    return 0;
   }
-  const strictSecurityBaseline = process.argv.includes("--strict-security-baseline");
+  const strictSecurityBaseline = argv.includes("--strict-security-baseline");
   const guards = strictSecurityBaseline ? GUARDS.filter(isSecurityGuard) : GUARDS;
   const project = buildSharedProject(guards);
   printGuardKitBanner(guards.length, project);
-  const failed = reportResults(runGuards(guards, project, { strictSecurityBaseline }));
-  process.exit(failed > 0 ? 1 : 0);
+  return reportResults(runGuards(guards, project, { strictSecurityBaseline }));
+}
+
+// Only run on direct invocation — otherwise `import { GUARDS }` would kick
+// off the whole suite and the list wouldn't be testable.
+if (import.meta.main) {
+  process.exit(runGuardsCli(process.argv.slice(2)));
 }

package/src/run-repo-checks.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
-import { printGuardKitBanner, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { cliFlagsError, printGuardKitBanner, reportResults, runRepoChecks } from "./_lib/guard-kit";
 // Standalone-`main()` guards ported as RepoCheck — run in-process, no
 // per-guard subprocess/project.
+import { check as runtimeIsolation } from "./check-runtime-isolation";
 import { check as secretLiterals } from "./check-secret-literals";
 import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
 import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
@@ -10,6 +11,7 @@ import { check as rawSql } from "./guard-raw-sql";
 import { check as rendererBoundaries } from "./guard-renderer-boundaries";
 import { check as testStackDrift } from "./guard-test-stack-drift";
 import { check as thinWrappers } from "./guard-thin-wrappers";
+import { check as upgradeState } from "./guard-upgrade-state";
 
 export const REPO_CHECKS = [
   rawSql,
@@ -20,12 +22,28 @@ export const REPO_CHECKS = [
   secretLiterals,
   featureIntegrationTests,
   testStackDrift,
+  runtimeIsolation,
+  upgradeState,
 ];
 
-if (import.meta.main) {
+// No flags today — the array stays so an unknown flag still fails loud
+// instead of silently doing nothing, and so a future flag has one place to land.
+export const REPO_CHECK_FLAGS: readonly string[] = [];
+
+// Shared by the direct `bun run-repo-checks.ts` invocation below and by the
+// `checks` subcommand in cli.ts.
+export async function runRepoChecksCli(argv: readonly string[]): Promise<number> {
+  const flagsError = cliFlagsError("checks", argv, REPO_CHECK_FLAGS);
+  if (flagsError !== undefined) {
+    console.error(flagsError);
+    return 1;
+  }
   // No shared ts-morph Project here — RepoCheck.run() does its own file
   // walk per check, so the banner omits the "Project: N files" line.
   printGuardKitBanner(REPO_CHECKS.length);
-  const failed = reportResults(await runRepoChecks(REPO_CHECKS));
-  process.exit(failed > 0 ? 1 : 0);
+  return reportResults(await runRepoChecks(REPO_CHECKS));
+}
+
+if (import.meta.main) {
+  process.exit(await runRepoChecksCli(process.argv.slice(2)));
 }

package/src/run-ui-guards.ts

@@ -3,6 +3,7 @@
 // Project over the UI enforcement guards.
 import {
   buildSharedProject,
+  cliFlagsError,
   printGuardKitBanner,
   reportResults,
   runGuards,
@@ -25,10 +26,24 @@ export const UI_GUARDS = [
   i18nUiStrings,
 ];
 
-// Same as run-guards.ts: only run on direct invocation.
-if (import.meta.main) {
+// No flags today — the array stays so an unknown flag still fails loud
+// instead of silently doing nothing, and so a future flag has one place to land.
+export const UI_GUARD_FLAGS: readonly string[] = [];
+
+// Shared by the direct `bun run-ui-guards.ts` invocation below and by the
+// `ui` subcommand in cli.ts.
+export function runUiGuardsCli(argv: readonly string[]): number {
+  const flagsError = cliFlagsError("ui", argv, UI_GUARD_FLAGS);
+  if (flagsError !== undefined) {
+    console.error(flagsError);
+    return 1;
+  }
   const project = buildSharedProject(UI_GUARDS);
   printGuardKitBanner(UI_GUARDS.length, project);
-  const failed = reportResults(runGuards(UI_GUARDS, project));
-  process.exit(failed > 0 ? 1 : 0);
+  return reportResults(runGuards(UI_GUARDS, project));
+}
+
+// Same as run-guards.ts: only run on direct invocation.
+if (import.meta.main) {
+  process.exit(runUiGuardsCli(process.argv.slice(2)));
 }