@cosmicdrift/kumiko-guards 0.281.0 → 0.283.0

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

@@ -34,18 +34,24 @@
  * 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
+ * carrying a 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
+ * than a `HandlerContext` from its own registration). `reason` may be a
+ * string/template literal or an Identifier resolving to a module-local
+ * `const` with such an initializer (`_lib/generic-reason.ts`'s
+ * `resolveReasonText`, shared by R2/R3/R4's four call sites) — so one shared
+ * constant covers several declarations without repeating the literal text.
+ * An import, a function call, or a template with substitutions stays
+ * unresolved and the R2/R3 finding names that explicitly. 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).
+ * keys, and a non-literal, non-module-local-const `escapeHatch`/`reason`
+ * value 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 — except a `declareEscapeHatch`
@@ -72,7 +78,7 @@ import {
   type SourceFile,
   SyntaxKind,
 } from "ts-morph";
-import { isGenericReason, literalReasonText } from "./_lib/generic-reason";
+import { isGenericReason, resolveReasonText } from "./_lib/generic-reason";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
 const SCAN: ScanSpec = {
@@ -208,7 +214,8 @@ function findUnsafeRawFindings(
       line: call.getStartLineNumber(),
       rule: "unsafe-raw-outside-system-scope",
       message:
-        'unsafeRaw(...) used outside a systemScope feature and outside a handler/hook declaring escapeHatch — declare { escapeHatch: { reason: "..." } } on the handler or hook, declare the feature systemScope, or use ctx.systemDb.acknowledgeCrossTenant(reason) for a scoped read.',
+        'unsafeRaw(...) used outside a systemScope feature and outside a handler/hook declaring escapeHatch — declare { escapeHatch: { reason: "..." } } on the handler or hook, declare the feature systemScope, call declareEscapeHatch({ reason: "..." }) as a direct body statement of a named hook, or use ctx.systemDb.acknowledgeCrossTenant(reason) for a scoped read.' +
+        unresolvableDeclareEscapeHatchHint(call),
     });
   }
   return out;
@@ -372,27 +379,84 @@ function findReasonPropertyAssignment(
     );
 }
 
-// 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;
+// Syntactic extraction only — shared by the clearance check below and by
+// the "why" hint on R2/R3, which needs the reason node even when it turns
+// out not to resolve.
+function declareEscapeHatchReasonNode(stmt: Node): Node | undefined {
+  if (!stmt.isKind(SyntaxKind.ExpressionStatement)) return undefined;
   const expr = stmt.getExpression();
-  if (!expr.isKind(SyntaxKind.CallExpression)) return false;
+  if (!expr.isKind(SyntaxKind.CallExpression)) return undefined;
   const callee = expr.getExpression();
   if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
-    return false;
+    return undefined;
   }
   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());
+  if (args.length !== 1 || !arg?.isKind(SyntaxKind.ObjectLiteralExpression)) return undefined;
+  return findReasonPropertyAssignment(arg)?.getInitializer();
+}
+
+// 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 {
+  const reasonNode = declareEscapeHatchReasonNode(stmt);
+  if (!reasonNode) return false;
+  const reasonText = resolveReasonText(reasonNode);
   return reasonText !== undefined && !isGenericReason(reasonText);
 }
 
+// The three reason shapes the guard can name a concrete cause for: an
+// import, a function call, or a template with substitutions — none of
+// those are statically judgeable. An ambient/uninitialized identifier
+// (e.g. a `declare const` parameter) stays silently unresolved instead;
+// there is nothing more specific to say about it.
+function isExplicitlyUnresolvableReason(node: Node): boolean {
+  if (node.isKind(SyntaxKind.CallExpression)) return true;
+  if (node.isKind(SyntaxKind.TemplateExpression)) return true;
+  if (!node.isKind(SyntaxKind.Identifier)) return false;
+  const decls = node.getSymbol()?.getDeclarations() ?? [];
+  return decls.some(
+    (decl) =>
+      decl.isKind(SyntaxKind.ImportSpecifier) ||
+      decl.isKind(SyntaxKind.ImportClause) ||
+      decl.isKind(SyntaxKind.NamespaceImport),
+  );
+}
+
+const UNRESOLVABLE_REASON_HINT =
+  " A declareEscapeHatch({ reason }) call was found here, but its reason is an import, a function call, or a template with substitutions — none of those can be statically judged, so declareEscapeHatch needs a string literal or a module-local const instead.";
+
+// Walks the same ancestor chain as isInsideEscapeHatchDeclaredFunction, but
+// looks for a declareEscapeHatch statement whose reason is one of the three
+// explicitly-unresolvable shapes above, to explain a still-firing R2/R3
+// finding rather than leave the reader to guess why a visible
+// declareEscapeHatch call didn't clear it.
+function unresolvableDeclareEscapeHatchHint(node: Node): string {
+  let ancestor: Node | undefined = node.getParent();
+  while (ancestor) {
+    if (
+      ancestor.isKind(SyntaxKind.ArrowFunction) ||
+      ancestor.isKind(SyntaxKind.FunctionExpression) ||
+      ancestor.isKind(SyntaxKind.MethodDeclaration) ||
+      ancestor.isKind(SyntaxKind.FunctionDeclaration)
+    ) {
+      const body = ancestor.getBody();
+      if (body?.isKind(SyntaxKind.Block)) {
+        for (const stmt of body.getStatements()) {
+          const reasonNode = declareEscapeHatchReasonNode(stmt);
+          if (reasonNode && isExplicitlyUnresolvableReason(reasonNode)) {
+            return UNRESOLVABLE_REASON_HINT;
+          }
+        }
+      }
+    }
+    ancestor = ancestor.getParent();
+  }
+  return "";
+}
+
 // 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).
@@ -457,7 +521,9 @@ function findSystemIdentityFindings(
       file: path.relative(root, sf.getFilePath()),
       line: call.getStartLineNumber(),
       rule: "system-identity-outside-declared-scope",
-      message: `${methodName}(...) called with a system identity outside a declared scope — restrict to a systemScope feature, a .job.ts / r.job(...) job, or declare { escapeHatch: { reason: "..." } } on the handler or hook.`,
+      message:
+        `${methodName}(...) called with a system identity outside a declared scope — restrict to a systemScope feature, a .job.ts / r.job(...) job, declare { escapeHatch: { reason: "..." } } on the handler or hook, or call declareEscapeHatch({ reason: "..." }) as a direct body statement of a named hook.` +
+        unresolvableDeclareEscapeHatchHint(call),
     });
   }
   return out;
@@ -525,7 +591,7 @@ function findGenericReasonMethodCalls(sf: SourceFile, root: string): GenericReas
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
     const methodName = expr.getName();
     if (!GENERIC_REASON_METHODS.has(methodName)) continue;
-    const reasonText = literalReasonText(call.getArguments()[0]);
+    const reasonText = resolveReasonText(call.getArguments()[0]);
     if (reasonText === undefined || !isGenericReason(reasonText)) continue;
     out.push({
       file: path.relative(root, sf.getFilePath()),
@@ -554,7 +620,7 @@ function findGenericReasonDeclareEscapeHatchCalls(
     if (!arg?.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
     const reasonProp = findReasonPropertyAssignment(arg);
     if (!reasonProp) continue;
-    const reasonText = literalReasonText(reasonProp.getInitializer());
+    const reasonText = resolveReasonText(reasonProp.getInitializer());
     if (reasonText === undefined || !isGenericReason(reasonText)) continue;
     out.push({
       file: path.relative(root, sf.getFilePath()),
@@ -579,7 +645,7 @@ function findGenericReasonObjectProperty(
     if (!init?.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
     const reasonProp = init.getProperty("reason");
     if (!reasonProp?.isKind(SyntaxKind.PropertyAssignment)) continue;
-    const reasonText = literalReasonText(reasonProp.getInitializer());
+    const reasonText = resolveReasonText(reasonProp.getInitializer());
     if (reasonText === undefined) continue;
     // Empty/whitespace is the boot validator's job — no double-check.
     if (reasonText.trim() === "") continue;

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)));
 }