@cosmicdrift/kumiko-guards 0.281.0 → 0.282.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.281.0",
+  "version": "0.282.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -27,7 +27,7 @@
     "kumiko-guards": "./src/cli.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.281.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.282.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/guard-kit.ts

@@ -479,6 +479,23 @@ export function guardKitPreflightError(guardCount: number, rootCount: number): s
   return undefined;
 }
 
+/**
+ * Validates CLI args for one subcommand against the flags it actually
+ * understands — every arg must match `known` exactly (not just a `--`-prefix
+ * check, which let a single-dash typo or a stray positional through
+ * unnoticed). An unknown arg must fail loud, never pass through silently.
+ */
+export function cliFlagsError(
+  subcommand: string,
+  argv: readonly string[],
+  known: readonly string[],
+): string | undefined {
+  const unknown = argv.filter((arg) => !known.includes(arg));
+  if (unknown.length === 0) return undefined;
+  const knownList = known.length > 0 ? known.join(", ") : "(none)";
+  return `Unknown argument${unknown.length > 1 ? "s" : ""} for "${subcommand}": ${unknown.join(", ")}. Known flags: ${knownList}`;
+}
+
 export type GuardKitBannerDeps = {
   readonly resolution?: RootResolution;
 };
@@ -505,6 +522,47 @@ export function printGuardKitBanner(
   if (project) console.log(`Project: ${project.getSourceFiles().length} files`);
 }
 
+export type SuiteInventory = {
+  readonly count: number;
+  readonly names: readonly string[];
+};
+
+export type GuardKitInventory = {
+  readonly version: string;
+  readonly total: number;
+  readonly suites: {
+    readonly guards: SuiteInventory;
+    readonly ui: SuiteInventory;
+    readonly checks: SuiteInventory;
+  };
+};
+
+function suiteInventory(items: readonly { readonly name: string }[]): SuiteInventory {
+  const names = items.map((item) => item.name);
+  return { count: names.length, names };
+}
+
+/**
+ * Static registration inventory for the three suites — reads each array's
+ * `.name` only, no scan/project/guard.run(). What a consumer's CI checks
+ * against instead of running the guards, e.g. so a guard dropped from a
+ * suite's array is missing here too, not just silently absent from a run.
+ */
+export function buildGuardKitInventory(args: {
+  readonly guards: readonly { readonly name: string }[];
+  readonly uiGuards: readonly { readonly name: string }[];
+  readonly checks: readonly { readonly name: string }[];
+}): GuardKitInventory {
+  const guards = suiteInventory(args.guards);
+  const ui = suiteInventory(args.uiGuards);
+  const checks = suiteInventory(args.checks);
+  return {
+    version: guardKitVersion(),
+    total: guards.count + ui.count + checks.count,
+    suites: { guards, ui, checks },
+  };
+}
+
 /**
  * Vacuity floor for guards with their own `main()`.
  *

package/src/changes.json

@@ -1,4 +1,21 @@
 [
+  {
+    "version": "0.282.0",
+    "type": "fix",
+    "title": "kumiko-guards bin now passes flags through to the guards, ui, and checks subcommands",
+    "detail": "The bin's `guards` subcommand called run-guards.ts's suite runner directly, skipping the `--explain`/`--write-security-baseline`/`--strict-security-baseline` handling that only existed in run-guards.ts's own `if (import.meta.main)` block — a consumer running `bunx @cosmicdrift/kumiko-guards guards --write-security-baseline` got a normal guard run with the flag silently dropped. Each suite (guards, ui, checks) now exports a `run*Cli(argv)` function that validates argv against that suite's known flags and applies them; both the bin and the suite's own direct-invocation entry point call the same function, so they cannot drift apart again. Validation matches each arg exactly against the known list (not just a `--`-prefix check), so a single-dash typo or a stray positional also exits 1 with the flags that subcommand accepts, rather than passing through unnoticed."
+  },
+  {
+    "version": "0.282.0",
+    "type": "improvement",
+    "title": "kumiko-guards list prints the registration inventory as JSON"
+  },
+  {
+    "version": "0.282.0",
+    "type": "improvement",
+    "title": "Port the upgrade-state and runtime-isolation guards",
+    "detail": "guard-upgrade-state and check-runtime-isolation ported from the private infra/guards package into the public @cosmicdrift/kumiko-guards package, rebuilt onto the public RepoCheck pattern with single-repo root resolution. guard-app-dockerfile, guard-doc-status, check-licenses, and check-security stay in infra/guards as CDGS-specific house rules (private registry scope, CDGS doc taxonomy, and CDGS license/security exception files with no equivalent consumer-facing mechanism in the public package) — they were deliberately not ported, not forgotten."
+  },
   {
     "version": "0.3.0",
     "type": "improvement",

package/src/check-runtime-isolation.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+// Runtime-Isolation Guard.
+//
+// Prevents production code (runtime) from transitively loading test or
+// tooling modules — the original trigger was a top-level Vitest import in a
+// testing helper that crashed drizzle-kit under Node. Every file gets a
+// runtime context assigned; every import edge is checked against a compat
+// matrix.
+//
+// Per-file classification (highest priority first):
+//   1. File directive       →  // @runtime <kind>  in the first 5 lines
+//   2. Path pattern         →  *.test.ts, *.integration.ts, *.e2e.ts,
+//                               **/__tests__/**, **/testing/**  → test;
+//                               plus a handful of verified-isomorphic
+//                               single-file/directory carve-outs (see
+//                               runtime-isolation-classify.ts)
+//   3. Workspace             →  package.json `"kumiko": { "runtime": "..." }`
+//   4. Client reachability   →  transitively reachable, via value imports,
+//                                from a browser-bundle entry
+//                                (`src/client-*.tsx`) or from any file that
+//                                already classifies as "client" on its own
+//                                (directive/path/workspace)
+//   5. Default                →  runtime
+//
+// Compat matrix: which runtime context may import which.
+//   runtime → runtime, client
+//   client  → client
+//   dev     → runtime, client, dev, tooling
+//   tooling → runtime, client, dev, tooling, test
+//   test    → everything
+//
+// Single-repo only (unlike infra/guards' check-runtime-isolation.ts, which
+// scans every sibling checkout in one shared ts-morph project): this public
+// package only ever resolves the repo `cwd` sits in, so there is exactly one
+// repo root to classify files against.
+//
+// Pure classification + violation detection live in
+// `runtime-isolation-classify.ts` (unit-testable with an in-memory ts-morph
+// project) — this file only does the repo/glob resolution, ts-morph project
+// setup, and RepoCheck wiring.
+//
+// A file/import edge classified "client" importing "runtime" can be a real
+// finding this guard needs to see, but can also be a known, reviewed
+// exception (e.g. samples/recipes are worked examples, not the framework's
+// own production surface — see kumiko-framework#2337 for the one currently
+// frozen here). Exceptions are tracked via a per-repo baseline file
+// (`.kumiko-runtime-isolation-baseline.json`, same `baselineRatchet`
+// mechanism as check-complexity/guard-pii-annotations/etc.), not a
+// hardcoded list in this source file: a consumer repo can freeze or clear
+// its own findings the same way, with `--write-baseline`.
+//
+// Usage:
+//   bun packages/guards/src/check-runtime-isolation.ts
+//   bun packages/guards/src/check-runtime-isolation.ts --write-baseline
+
+import * as path from "node:path";
+import { Project } from "ts-morph";
+import {
+  baselineRatchet,
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import { frameworkTsConfigPath, type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
+import {
+  classify,
+  computeClientReachablePaths,
+  findRuntimeIsolationViolations,
+  isClientEntryPath,
+  type Runtime,
+} from "./runtime-isolation-classify";
+
+const SCAN: ScanSpec = { scope: "source", extensions: ["ts", "tsx"] };
+const BASELINE_FILE = ".kumiko-runtime-isolation-baseline.json";
+
+type RawViolation = {
+  readonly file: string;
+  readonly line: number;
+  readonly fileRuntime: Runtime;
+  readonly importedSpec: string;
+  readonly importedRuntime: Runtime;
+};
+
+function printViolation(v: RawViolation, root: string): void {
+  const fileRel = path.relative(root, v.file);
+  console.log(`  ${fileRel}:${v.line}`);
+  console.log(`    [${v.fileRuntime}] imports [${v.importedRuntime}] "${v.importedSpec}"`);
+}
+
+function violationKey(rootAbsPath: string, v: RawViolation): string {
+  return `${path.relative(rootAbsPath, v.file)}::${v.importedSpec}`;
+}
+
+function countByKey(
+  rootAbsPath: string,
+  violations: readonly RawViolation[],
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const v of violations) {
+    const key = violationKey(rootAbsPath, v);
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function ratchetFor(rootAbsPath: string) {
+  return baselineRatchet({
+    file: path.join(rootAbsPath, BASELINE_FILE),
+    formatVersion: 1,
+    unit: "runtime-isolation violation(s)",
+  });
+}
+
+function scanRoot(root: RepoRoot): {
+  allViolations: readonly RawViolation[];
+  outsideRoot: readonly string[];
+  scannedFiles: number;
+} {
+  const tsConfigFilePath = frameworkTsConfigPath();
+  const project =
+    tsConfigFilePath !== undefined
+      ? new Project({
+          tsConfigFilePath,
+          skipAddingFilesFromTsConfig: true,
+          skipFileDependencyResolution: true,
+        })
+      : new Project({ skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: true });
+
+  const paths = scanFiles(SCAN, [root]);
+  // Exact-path lookup, never a re-glob: `project.getSourceFiles(paths)`
+  // treats each array entry as a glob pattern — pathologically slow (and,
+  // for a bracketed filename like `[id].tsx`, a broken character class)
+  // over thousands of paths. `getSourceFile(path)` is an exact lookup.
+  const scannedFiles = paths
+    .map((p) => project.getSourceFile(p) ?? project.addSourceFileAtPath(p))
+    .filter((f) => {
+      const fp = f.getFilePath();
+      return !fp.includes("/node_modules/") && !fp.includes("/dist/");
+    });
+
+  const workspaceCache = new Map<string, Runtime | null>();
+  const clientReachable = computeClientReachablePaths(scannedFiles, (sf) => {
+    const rel = path.relative(root.absPath, sf.getFilePath());
+    if (isClientEntryPath(rel)) return true;
+    return classify(sf.getFilePath(), root.absPath, workspaceCache) === "client";
+  });
+
+  const { violations: allViolations, outsideRoot } = findRuntimeIsolationViolations(
+    scannedFiles,
+    root.absPath,
+    workspaceCache,
+    clientReachable,
+  );
+
+  return { allViolations, outsideRoot, scannedFiles: scannedFiles.length };
+}
+
+export const check: RepoCheck = {
+  name: "Runtime-Isolation Check",
+  hint:
+    "runtime may import runtime/client only; client may import client only; " +
+    "dev/tooling/test are more permissive. See runtime-isolation-classify.ts for the compat matrix. " +
+    "New, deliberate exception? `bun packages/guards/src/check-runtime-isolation.ts --write-baseline`",
+  run(roots) {
+    const root = roots[0];
+    if (!root) return { violations: [], matchedFiles: 0, notApplicable: true };
+    const rootAbsPath = root.absPath;
+
+    const { allViolations, outsideRoot, scannedFiles } = scanRoot(root);
+    for (const v of allViolations) printViolation(v, rootAbsPath);
+
+    const counts = countByKey(rootAbsPath, allViolations);
+    const resolveLine = (key: string): number => {
+      const relFile = key.split("::")[0];
+      return allViolations.find((v) => path.relative(rootAbsPath, v.file) === relFile)?.line ?? 1;
+    };
+    const violations: GuardViolation[] = ratchetFor(rootAbsPath).check(
+      counts,
+      "runtime may import runtime/client only; client may import client only — see runtime-isolation-classify.ts for the compat matrix.",
+      {
+        formatDriftRemediation:
+          "Run `bun packages/guards/src/check-runtime-isolation.ts --write-baseline` once.",
+        resolveLine,
+      },
+    );
+
+    if (outsideRoot.length > 0) {
+      console.log(
+        `  Runtime-Isolation Check: ${outsideRoot.length} import target(s) outside the repo root (skipped).`,
+      );
+    }
+
+    return { violations, matchedFiles: scannedFiles, notApplicable: false };
+  },
+};
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  if (args.includes("--write-baseline")) {
+    const root = resolveRepoRoots()[0];
+    if (!root) {
+      console.error("No repo root resolved — nothing to baseline.");
+      process.exit(1);
+    }
+    const { allViolations } = scanRoot(root);
+    for (const v of allViolations) printViolation(v, root.absPath);
+    ratchetFor(root.absPath).write(countByKey(root.absPath, allViolations));
+    process.exit(0);
+  }
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/cli.ts

@@ -1,55 +1,79 @@
 #!/usr/bin/env bun
 // Consumer entry point for `bunx @cosmicdrift/kumiko-guards`. Runs all three
 // suites (or one, via subcommand) using the exact call forms the three
-// runners already use in their own `if (import.meta.main)` blocks.
-import {
-  buildSharedProject,
-  printGuardKitBanner,
-  reportResults,
-  runGuards,
-  runRepoChecks,
-} from "./_lib/guard-kit";
-import { GUARDS } from "./run-guards";
-import { REPO_CHECKS } from "./run-repo-checks";
-import { UI_GUARDS } from "./run-ui-guards";
-
-const SUBCOMMANDS = ["guards", "ui", "checks"] as const;
+// runners already use in their own `if (import.meta.main)` blocks — including
+// flags, which each runner's own *Cli function validates and applies so this
+// bin and the direct `bun run-*.ts` invocation can never drift apart.
+import { buildGuardKitInventory, cliFlagsError } from "./_lib/guard-kit";
+import { GUARD_FLAGS, GUARDS, runGuardsCli } from "./run-guards";
+import { REPO_CHECK_FLAGS, REPO_CHECKS, runRepoChecksCli } from "./run-repo-checks";
+import { runUiGuardsCli, UI_GUARD_FLAGS, UI_GUARDS } from "./run-ui-guards";
+
+const SUBCOMMANDS = ["guards", "ui", "checks", "list"] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
 
+const SUBCOMMAND_FLAGS: Record<Subcommand, readonly string[]> = {
+  guards: GUARD_FLAGS,
+  ui: UI_GUARD_FLAGS,
+  checks: REPO_CHECK_FLAGS,
+  list: [],
+};
+
 function isSubcommand(value: string): value is Subcommand {
   return (SUBCOMMANDS as readonly string[]).includes(value);
 }
 
-function runGuardsSuite(): number {
-  const project = buildSharedProject(GUARDS);
-  printGuardKitBanner(GUARDS.length, project);
-  return reportResults(runGuards(GUARDS, project));
-}
-
-function runUiGuardsSuite(): number {
-  const project = buildSharedProject(UI_GUARDS);
-  printGuardKitBanner(UI_GUARDS.length, project);
-  return reportResults(runGuards(UI_GUARDS, project));
-}
-
-async function runRepoChecksSuite(): Promise<number> {
-  printGuardKitBanner(REPO_CHECKS.length);
-  return reportResults(await runRepoChecks(REPO_CHECKS));
+function printHelp(): void {
+  console.log("Usage: kumiko-guards [guards|ui|checks|list] [flags]");
+  console.log();
+  for (const sub of SUBCOMMANDS) {
+    const flags = SUBCOMMAND_FLAGS[sub];
+    console.log(`  ${sub}${flags.length > 0 ? ` [${flags.join("|")}]` : ""}`);
+  }
 }
 
 async function main(): Promise<void> {
   const subcommand = process.argv[2];
+  if (subcommand === "--help" || subcommand === "-h") {
+    printHelp();
+    process.exit(0);
+  }
   if (subcommand !== undefined && !isSubcommand(subcommand)) {
     console.error(
       `Unknown subcommand "${subcommand}". Valid subcommands: ${SUBCOMMANDS.join(", ")}`,
     );
     process.exit(1);
   }
+  const flags = process.argv.slice(3);
+
+  if (subcommand === "list") {
+    const flagsError = cliFlagsError("list", flags, SUBCOMMAND_FLAGS.list);
+    if (flagsError !== undefined) {
+      console.error(flagsError);
+      process.exit(1);
+    }
+    // Registration inventory only — no scan, no project, no guard.run(). What
+    // CI checks against instead of running the guards: a guard dropped from a
+    // suite's array goes missing here too, not just silently from a run.
+    const inventory = buildGuardKitInventory({
+      guards: GUARDS,
+      uiGuards: UI_GUARDS,
+      checks: REPO_CHECKS,
+    });
+    console.log(JSON.stringify(inventory));
+    return;
+  }
 
   let failed = 0;
-  if (subcommand === undefined || subcommand === "guards") failed += runGuardsSuite();
-  if (subcommand === undefined || subcommand === "ui") failed += runUiGuardsSuite();
-  if (subcommand === undefined || subcommand === "checks") failed += await runRepoChecksSuite();
+  if (subcommand === undefined || subcommand === "guards") {
+    failed += runGuardsCli(subcommand === "guards" ? flags : []);
+  }
+  if (subcommand === undefined || subcommand === "ui") {
+    failed += runUiGuardsCli(subcommand === "ui" ? flags : []);
+  }
+  if (subcommand === undefined || subcommand === "checks") {
+    failed += await runRepoChecksCli(subcommand === "checks" ? flags : []);
+  }
 
   process.exit(failed > 0 ? 1 : 0);
 }

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

package/src/runtime-isolation-classify.ts

@@ -0,0 +1,337 @@
+// Pure classification helpers for the runtime-isolation guard.
+//
+// Extracted from `check-runtime-isolation.ts` so the regex/path logic
+// can be unit-tested in isolation. The orchestration (ts-morph,
+// process.exit, file walks) stays in the script.
+//
+// Why: the path-pattern table has historically had quiet bugs
+// (e.g. `\/scripts\/` did not match `scripts/foo.ts` at repo-root,
+// silently misclassifying tooling files as `runtime`). The unit-tests
+// in `__tests__/runtime-isolation-classify.test.ts` lock the
+// classification rules down so future edits trip a test, not a
+// production drift.
+
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import type { ImportDeclaration, SourceFile } from "ts-morph";
+
+export type Runtime = "runtime" | "client" | "dev" | "tooling" | "test";
+
+export const ALL_RUNTIMES: ReadonlySet<string> = new Set([
+  "runtime",
+  "client",
+  "dev",
+  "tooling",
+  "test",
+]);
+
+export const COMPAT: Record<Runtime, ReadonlySet<Runtime>> = {
+  runtime: new Set(["runtime", "client"]),
+  client: new Set(["client"]),
+  dev: new Set(["runtime", "client", "dev", "tooling"]),
+  tooling: new Set(["runtime", "client", "dev", "tooling", "test"]),
+  test: new Set(["runtime", "client", "dev", "tooling", "test"]),
+};
+
+/**
+ * Classify a file by its path relative to the repo root. Returns null
+ * if no path-pattern matched (caller falls back to workspace / default).
+ *
+ * Pure function — accepts a repo-relative path string, no I/O.
+ */
+export function classifyByPath(repoRelativePath: string): Runtime | null {
+  const rel = repoRelativePath.replace(/\\/g, "/");
+  if (/\/(__tests__|testing)\//.test(rel)) return "test";
+  if (/\/testing\.tsx?$/.test(rel)) return "test";
+  if (/\.(test|integration|e2e)\.[tj]sx?$/.test(rel)) return "test";
+  if (/(?:^|\/)scripts\//.test(rel)) return "tooling";
+  if (/(?:^|\/)bin\//.test(rel)) return "tooling";
+  if (/\/drizzle\/[^/]+\.ts$/.test(rel)) return "tooling";
+  if (/\/drizzle\.config\.[tj]s$/.test(rel)) return "tooling";
+
+  // Shared UI types are used by both client and runtime. In the kumiko isolation
+  // model, "client" is the most permissive production category that "runtime"
+  // can also import.
+  if (/(?:^|\/)ui-types\//.test(rel)) return "client";
+
+  // Same reasoning, two more shapes: a `web.ts`/`web/` subpath is the
+  // established convention (locale-de, locale-es, bundled-features) for the
+  // client-safe slice of an otherwise `"runtime"`-marked package — the
+  // package.json marker classifies the whole package, this carves the
+  // deliberately-named exception back out. Deliberately workspace-wide (any
+  // repo, any depth), not framework-only: app repos' own `src/features/*/web/`
+  // dirs follow the identical convention. `time`/`utils`/`engine/types`/`errors`
+  // are framework's other isomorphic exports (published as their own subpath
+  // exports, empirically zero Node-only or cross-module value imports, same
+  // shape as `ui-types`). Scoped to `packages/framework/src/` specifically —
+  // `utils`/`errors` are common enough directory names elsewhere that a
+  // repo-wide match risks misclassifying an unrelated server-only folder in
+  // some other package.
+  if (/(?:^|\/)web\//.test(rel) || /\/web\.tsx?$/.test(rel)) return "client";
+  if (/^packages\/framework\/src\/(?:time|utils|engine\/types|errors)\//.test(rel)) return "client";
+
+  // More single-file carve-outs, same "package marker is coarser than the
+  // file" shape, verified case by case rather than by a directory
+  // convention:
+  //  - locale-{de,es}/src/strings.ts: pure string-constant data (zero
+  //    imports), re-exported by the already-client `web.ts` sibling in the
+  //    same package but shadowed by the package's own `"runtime"` marker.
+  if (/^packages\/locale-(?:de|es)\/src\/strings\.ts$/.test(rel)) return "client";
+  //  - dev-server/src/env-schema.ts: a zod-only schema, no dev-server-
+  //    internal imports — safe to carve out on its own.
+  if (/^packages\/dev-server\/src\/env-schema\.ts$/.test(rel)) return "client";
+
+  return null;
+}
+
+/**
+ * App-repo browser bundle entry, mirroring kumiko-build's own discovery
+ * (`discoverClientEntries` in kumiko-framework's
+ * `packages/server-runtime/src/build-prod-bundle.ts`): `src/client.tsx`/
+ * `src/client.ts` (single-entry) or `src/client-<suffix>.tsx?` (multi-entry).
+ * Framework/enterprise packages never match — their sources live under
+ * `packages/*\/src/`, not a repo-root `src/`. Kept independent of the
+ * framework's own regex (cross-package import would be a build-vs-lint
+ * layering violation) — if kumiko-build's discovery pattern changes, this
+ * drifts and needs a matching update.
+ */
+export function isClientEntryPath(repoRelativePath: string): boolean {
+  const rel = repoRelativePath.replace(/\\/g, "/");
+  return /^src\/client(-[a-z][a-z0-9-]*)?\.tsx?$/.test(rel);
+}
+
+/**
+ * An import declaration that survives `verbatimModuleSyntax` stripping and
+ * therefore carries real runtime weight. Shared by the direct-edge check and
+ * the client-reachability walk so both agree on what counts as an edge.
+ */
+export function isValueImport(decl: ImportDeclaration): boolean {
+  if (decl.isTypeOnly()) return false;
+  const named = decl.getNamedImports();
+  if (
+    named.length > 0 &&
+    named.every((n) => n.isTypeOnly()) &&
+    !decl.getDefaultImport() &&
+    !decl.getNamespaceImport()
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Map dist declaration files back to src. Project References make ts-morph
+ * resolve imports to `.d.ts` under `dist/`; classification and the reachable
+ * set must use the same path.
+ */
+export function toEffectivePath(filePath: string): string {
+  if (filePath.endsWith(".d.ts") && filePath.includes("/dist/")) {
+    const base = filePath.replace("/dist/", "/src/").replace(/\.d\.ts$/, "");
+    if (existsSync(`${base}.ts`)) return `${base}.ts`;
+    if (existsSync(`${base}.tsx`)) return `${base}.tsx`;
+  }
+  return filePath;
+}
+
+/**
+ * BFS over value-import edges starting at every file `isEntry` accepts.
+ * Files reached this way are part of a browser bundle even when nothing in
+ * their own path/directive/workspace marks them "client" — a plain helper
+ * file, several hops from `src/client-*.tsx`, value-importing a server
+ * subpath is exactly the drift this catches. Crossing into node_modules is
+ * fine (ts-morph resolves workspace symlinks to the real package file);
+ * only literal `node_modules/`/`dist/` targets are excluded, matching the
+ * direct-edge check.
+ */
+export function computeClientReachablePaths(
+  sourceFiles: readonly SourceFile[],
+  isEntry: (sourceFile: SourceFile) => boolean,
+): ReadonlySet<string> {
+  const reached = new Set<string>();
+  const queue: SourceFile[] = sourceFiles.filter(isEntry);
+  while (queue.length > 0) {
+    const sf = queue.shift();
+    if (!sf) break;
+    const fp = toEffectivePath(sf.getFilePath());
+    if (fp.includes("/node_modules/") || fp.includes("/dist/")) continue;
+    if (reached.has(fp)) continue;
+    reached.add(fp);
+    for (const decl of sf.getImportDeclarations()) {
+      if (!isValueImport(decl)) continue;
+      const target = decl.getModuleSpecifierSourceFile();
+      if (!target) continue;
+      const targetPath = toEffectivePath(target.getFilePath());
+      if (targetPath.includes("/node_modules/") || targetPath.includes("/dist/")) continue;
+      if (!reached.has(targetPath)) queue.push(target);
+    }
+  }
+  return reached;
+}
+
+/**
+ * Classify a file by its top-of-file `// @runtime <kind>` directive.
+ * Reads the first 600 bytes only (cap blast radius on huge files).
+ */
+export function classifyByDirective(filePath: string): Runtime | null {
+  let head: string;
+  try {
+    head = readFileSync(filePath, "utf8").slice(0, 600);
+  } catch {
+    return null;
+  }
+  for (const line of head.split("\n").slice(0, 8)) {
+    const m = line.match(/\/\/\s*@runtime\s+(\w+)/);
+    if (m && ALL_RUNTIMES.has(m[1] ?? "")) return m[1] as Runtime;
+  }
+  return null;
+}
+
+/**
+ * Walk upward from `filePath` looking for the nearest package.json that
+ * carries a `kumiko.runtime` marker. Stops at `repoRoot`. Caches per
+ * directory in the supplied map so a long scan only reads each
+ * package.json once.
+ */
+export function findWorkspaceRuntime(
+  filePath: string,
+  repoRoot: string,
+  cache: Map<string, Runtime | null>,
+): Runtime | null {
+  let dir = path.dirname(filePath);
+  while (dir.startsWith(repoRoot) && dir !== repoRoot) {
+    const r = readWorkspaceRuntime(dir, cache);
+    if (r) return r;
+    // Stop at the first package.json — don't fall through to a parent
+    // workspace that happens to have a marker.
+    try {
+      readFileSync(path.join(dir, "package.json"), "utf8");
+      return null;
+    } catch {
+      // No package.json here — keep climbing.
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function readWorkspaceRuntime(dir: string, cache: Map<string, Runtime | null>): Runtime | null {
+  const cached = cache.get(dir);
+  if (cached !== undefined) return cached;
+  const pkgPath = path.join(dir, "package.json");
+  let result: Runtime | null = null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const r = pkg.kumiko?.runtime;
+    if (typeof r === "string" && ALL_RUNTIMES.has(r)) result = r as Runtime;
+  } catch {
+    // package.json missing or unreadable — unmarked
+  }
+  cache.set(dir, result);
+  return result;
+}
+
+/**
+ * Compose the classification layers (directive > path > workspace >
+ * client-reachability > default) into one call. The cache is owned by the
+ * caller so a single scan amortizes the workspace-lookup across files.
+ *
+ * `clientReachable` only ever promotes the *default* — a file with an
+ * explicit directive, a matched path pattern, or a workspace marker keeps
+ * that classification regardless of reachability. This is what lets a
+ * framework file explicitly marked `"runtime"` (e.g. `engine/index.ts`) stay
+ * "runtime" even when a client bundle reaches it — which is exactly the
+ * violation this guard needs to see, not paper over.
+ */
+export function classify(
+  filePath: string,
+  repoRoot: string,
+  workspaceCache: Map<string, Runtime | null>,
+  clientReachable?: ReadonlySet<string>,
+): Runtime {
+  const effectivePath = toEffectivePath(filePath);
+
+  const rel = path.relative(repoRoot, effectivePath);
+  return (
+    classifyByDirective(effectivePath) ??
+    classifyByPath(rel) ??
+    findWorkspaceRuntime(effectivePath, repoRoot, workspaceCache) ??
+    (clientReachable?.has(effectivePath) ? "client" : undefined) ??
+    "runtime"
+  );
+}
+
+export type Violation = {
+  readonly file: string;
+  readonly line: number;
+  readonly fileRuntime: Runtime;
+  readonly importedSpec: string;
+  readonly importedFile: string;
+  readonly importedRuntime: Runtime;
+};
+
+/**
+ * The direct-edge half of the guard: classify every scanned file, then flag
+ * every value-import whose target runtime the source runtime isn't allowed
+ * to depend on (`COMPAT`). `clientReachable` (from `computeClientReachablePaths`)
+ * is threaded through so a file pulled into a browser bundle gets judged as
+ * "client" even without its own directive/path/workspace marker.
+ */
+export function findRuntimeIsolationViolations(
+  sourceFiles: readonly SourceFile[],
+  repoRoot: string,
+  workspaceCache: Map<string, Runtime | null>,
+  clientReachable: ReadonlySet<string> = new Set(),
+): {
+  readonly violations: readonly Violation[];
+  readonly stats: Record<Runtime, number>;
+  /** Import targets (or scanned files) that resolved outside the repo root. */
+  readonly outsideRoot: readonly string[];
+} {
+  const violations: Violation[] = [];
+  const outsideRoot: string[] = [];
+  const seenOutside = new Set<string>();
+  const noteOutside = (fp: string) => {
+    if (seenOutside.has(fp)) return;
+    seenOutside.add(fp);
+    outsideRoot.push(fp);
+  };
+  const stats: Record<Runtime, number> = { runtime: 0, client: 0, dev: 0, tooling: 0, test: 0 };
+  const withinRoot = (fp: string) => fp === repoRoot || fp.startsWith(`${repoRoot}/`);
+
+  for (const sf of sourceFiles) {
+    const fp = sf.getFilePath();
+    if (fp.includes("/node_modules/") || fp.includes("/dist/")) continue;
+    if (!withinRoot(fp)) {
+      noteOutside(fp);
+      continue;
+    }
+    const fileRt = classify(fp, repoRoot, workspaceCache, clientReachable);
+    stats[fileRt]++;
+
+    for (const decl of sf.getImportDeclarations()) {
+      if (!isValueImport(decl)) continue;
+      const target = decl.getModuleSpecifierSourceFile();
+      if (!target) continue;
+      const targetPath = target.getFilePath();
+      if (targetPath.includes("/node_modules/")) continue;
+      if (!withinRoot(targetPath)) {
+        noteOutside(targetPath);
+        continue;
+      }
+      const targetRt = classify(targetPath, repoRoot, workspaceCache, clientReachable);
+
+      if (!COMPAT[fileRt].has(targetRt)) {
+        violations.push({
+          file: fp,
+          line: decl.getStartLineNumber(),
+          fileRuntime: fileRt,
+          importedSpec: decl.getModuleSpecifierValue(),
+          importedFile: targetPath,
+          importedRuntime: targetRt,
+        });
+      }
+    }
+  }
+
+  return { violations, stats, outsideRoot };
+}