@blackbelt-technology/pi-agent-dashboard 0.3.0 → 0.4.0

package/packages/shared/src/__tests__/bootstrap/harness.ts

@@ -0,0 +1,413 @@
+/**
+ * In-memory bootstrap harness — pure-fs, pure-env test runner for
+ * ToolRegistry resolution + bridge-extension registration scenarios.
+ *
+ * See openspec/changes/bootstrap-resolution-harness/design.md §7 for
+ * the full design.
+ *
+ * Usage:
+ *
+ *   await withFakeEnv({
+ *     platform: "win32",
+ *     homedir:  "C:\\Users\\Robert",
+ *     cwd:      "C:\\Program Files\\PI Dashboard",
+ *     env:      { APPDATA: "C:\\Users\\Robert\\AppData\\Roaming", PATH: "..." },
+ *     fs: layer(
+ *       fixtures.npmGlobalOnWindows({ pi: "0.6.3" }),
+ *       fixtures.managedInstall({ pi: "0.5.1" }),
+ *     ),
+ *   }, async (ctx) => {
+ *     const registry = ctx.createRegistry();
+ *     const res = registry.resolve("pi");
+ *     expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+ *   });
+ *
+ * Invariants:
+ * - No real fs, child_process, or network access during a scenario run.
+ * - Every strategy dep (`exists`, `which`, `npmRootGlobal`, `resolveModule`)
+ *   is wired to the in-memory volume.
+ * - Platform is fully injected; tests do NOT mutate `process.platform`.
+ */
+import path from "node:path";
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import { Volume } from "memfs";
+import type { IFs } from "memfs";
+import {
+  ToolRegistry,
+  type ToolRegistryDeps,
+  type PlatformEnv,
+} from "../../tool-registry/registry.js";
+import type { StrategyDeps } from "../../tool-registry/strategies.js";
+import { OverridesStore } from "../../tool-registry/overrides.js";
+
+/**
+ * Minimal in-memory OverridesStore replacement that doesn't touch
+ * the real filesystem. Shape-compatible with the real class (TS
+ * `private` is erased at runtime, so casting through `unknown` is
+ * safe).
+ */
+class FakeOverridesStore {
+  constructor(private cache: Record<string, string>) {}
+  list(): Readonly<Record<string, string>> {
+    return this.cache;
+  }
+  set(name: string, overridePath: string): void {
+    this.cache[name] = overridePath;
+  }
+  clear(name: string): void {
+    delete this.cache[name];
+  }
+  invalidate(): void {
+    /* cache is always fresh in the fake store */
+  }
+}
+
+/** File contents for the fake filesystem: path -> content. Directories are
+ * implied by the paths of their children. */
+export type FsRecord = Readonly<Record<string, string | Buffer>>;
+
+/** Env variables visible inside the scenario. */
+export type FakeEnv = Readonly<Record<string, string>>;
+
+export interface FakeEnvSpec {
+  platform: NodeJS.Platform;
+  homedir: string;
+  cwd?: string;
+  env?: FakeEnv;
+  /** File contents — use `layer(...)` to compose fixtures. */
+  fs?: FsRecord;
+  /** Per-tool override map (tool-overrides.json content). */
+  overrides?: Readonly<Record<string, string>>;
+  /** Override `npm root -g`. Defaults to platform-appropriate path. */
+  npmRootGlobal?: string;
+}
+
+export interface HarnessContext {
+  readonly spec: FakeEnvSpec;
+  readonly vol: Volume;
+  readonly fs: IFs;
+  readonly platform: NodeJS.Platform;
+  readonly homedir: string;
+  readonly cwd: string;
+  readonly env: FakeEnv;
+  /** Platform-correct `path` module (posix vs win32). */
+  readonly pathlib: typeof posix | typeof win32;
+  /** PATH entries as an array (split on platform-correct delimiter). */
+  readonly pathEntries: readonly string[];
+  /** Resolved `npm root -g` value. */
+  readonly npmRootGlobal: string;
+
+  /** Create the strategy deps wired to the fake filesystem/env. */
+  createStrategyDeps(): Required<StrategyDeps>;
+
+  /** Create a ToolRegistry pre-wired with the fake env + overrides. */
+  createRegistry(extra?: Partial<ToolRegistryDeps>): ToolRegistry;
+
+  /** Read the fake filesystem's settings.json (or null if absent/broken). */
+  readSettings(): Record<string, unknown> | null;
+}
+
+/**
+ * Merge multiple FsRecord layers. Later layers override earlier on path
+ * conflict. Returns a single FsRecord.
+ */
+export function layer(...layers: readonly (FsRecord | undefined | null)[]): FsRecord {
+  const out: Record<string, string | Buffer> = {};
+  for (const l of layers) {
+    if (!l) continue;
+    for (const [k, v] of Object.entries(l)) out[k] = v;
+  }
+  return out;
+}
+
+/** Platform-aware PATH delimiter. */
+function pathDelim(platform: NodeJS.Platform): string {
+  return platform === "win32" ? ";" : ":";
+}
+
+/** Platform-correct path module. */
+function pathFor(platform: NodeJS.Platform): typeof posix | typeof win32 {
+  return platform === "win32" ? win32 : posix;
+}
+
+/** Default `npm root -g` per platform when not provided by spec. */
+function defaultNpmRootGlobal(spec: FakeEnvSpec): string {
+  const p = pathFor(spec.platform);
+  if (spec.platform === "win32") {
+    const appdata = spec.env?.APPDATA ?? p.join(spec.homedir, "AppData", "Roaming");
+    return p.join(appdata, "npm", "node_modules");
+  }
+  return p.join(spec.homedir, ".npm", "lib", "node_modules");
+}
+
+/**
+ * Build a `which(name)` function that walks PATH inside the fake fs.
+ * On win32, tries `name`, `name.cmd`, `name.exe` in that order.
+ */
+function buildWhich(
+  fs: IFs,
+  pathEntries: readonly string[],
+  platform: NodeJS.Platform,
+): (name: string) => string | null {
+  const p = pathFor(platform);
+  const exts = platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  return (name: string): string | null => {
+    // If name has an extension or absolute path, short-circuit.
+    if (p.isAbsolute(name)) {
+      return fs.existsSync(name) ? name : null;
+    }
+    for (const entry of pathEntries) {
+      for (const ext of exts) {
+        const candidate = p.join(entry, name + ext);
+        try {
+          if (fs.existsSync(candidate)) return candidate;
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    return null;
+  };
+}
+
+/**
+ * Build a `resolveModule(id, from)` that walks the fake fs' node_modules
+ * ancestor chain starting at `from`, looking for
+ *   <dir>/node_modules/<id>/package.json
+ * then reading that package.json's `main`/`exports` to derive the entry.
+ * When no package.json `main` is present, falls back to `index.js`.
+ *
+ * NOT a full Node resolver — covers the cases the bootstrap harness
+ * needs (bare package import of CJS/ESM with a `main` field). Good
+ * enough for pi-coding-agent, openspec, tsx.
+ */
+function buildResolveModule(
+  fs: IFs,
+  platform: NodeJS.Platform,
+): (id: string, from: string) => string | null {
+  const p = pathFor(platform);
+
+  function readJson(p2: string): Record<string, unknown> | null {
+    try {
+      const raw = fs.readFileSync(p2, "utf-8") as string;
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  function entryFromPkg(pkgPath: string, pkg: Record<string, unknown>): string {
+    const pkgDir = p.dirname(pkgPath);
+    const main = typeof pkg.main === "string" ? pkg.main : "index.js";
+    return p.join(pkgDir, main);
+  }
+
+  // Split a require id into { pkgName, subpath }.
+  //   "foo"                     → { pkgName: "foo",        subpath: null }
+  //   "foo/bar"                 → { pkgName: "foo",        subpath: "bar" }
+  //   "@scope/foo"              → { pkgName: "@scope/foo", subpath: null }
+  //   "@scope/foo/package.json" → { pkgName: "@scope/foo", subpath: "package.json" }
+  function splitId(id: string): { pkgName: string; subpath: string | null } {
+    if (id.startsWith("@")) {
+      const parts = id.split("/");
+      if (parts.length <= 2) return { pkgName: id, subpath: null };
+      return { pkgName: parts.slice(0, 2).join("/"), subpath: parts.slice(2).join("/") };
+    }
+    const idx = id.indexOf("/");
+    if (idx === -1) return { pkgName: id, subpath: null };
+    return { pkgName: id.slice(0, idx), subpath: id.slice(idx + 1) };
+  }
+
+  return (id: string, from: string): string | null => {
+    // Normalize `from`: if it's a file:// URL, strip it.
+    let anchor = from;
+    if (anchor.startsWith("file://")) {
+      // file:///C:/... on win32, file:///home/... on posix
+      anchor = anchor.slice(platform === "win32" ? 8 : 7);
+    }
+    // Starting directory: if anchor is a file, use its dir; if it's already
+    // a directory path, use as-is.
+    let dir = anchor;
+    try {
+      const st = fs.statSync(dir);
+      if (!st.isDirectory()) dir = p.dirname(dir);
+    } catch {
+      dir = p.dirname(anchor);
+    }
+
+    const { pkgName, subpath } = splitId(id);
+
+    // Walk up looking for node_modules/<pkgName>/package.json.
+    // Stop when we hit the filesystem root (dirname returns same value).
+    let prev = "";
+    while (dir !== prev) {
+      const pkgJsonPath = p.join(dir, "node_modules", pkgName, "package.json");
+      if (fs.existsSync(pkgJsonPath)) {
+        // Subpath request — resolve relative to the package dir.
+        if (subpath !== null) {
+          const candidate = p.join(p.dirname(pkgJsonPath), subpath);
+          if (fs.existsSync(candidate)) return candidate;
+          return null;
+        }
+        // Bare package — read main from package.json.
+        const pkg = readJson(pkgJsonPath);
+        if (pkg) {
+          const entry = entryFromPkg(pkgJsonPath, pkg);
+          if (fs.existsSync(entry)) return entry;
+        }
+      }
+      prev = dir;
+      dir = p.dirname(dir);
+    }
+    return null;
+  };
+}
+
+/**
+ * Populate a memfs Volume from an FsRecord. Also creates directory
+ * entries implicitly.
+ */
+function populateVolume(vol: Volume, records: FsRecord, platform: NodeJS.Platform): void {
+  const p = pathFor(platform);
+  for (const [rawPath, content] of Object.entries(records)) {
+    // memfs internally uses posix — but its APIs accept win32 paths on
+    // win32. For our purposes we normalize to posix for the Volume,
+    // because memfs is posix-native. Tests use the platform-correct
+    // path module via `ctx.pathlib` for path composition, and we
+    // translate at volume-populate time.
+    const normalized = platform === "win32" ? toMemfsPath(rawPath) : rawPath;
+    const dir = posix.dirname(normalized);
+    try {
+      vol.mkdirSync(dir, { recursive: true });
+    } catch {
+      /* ignore */
+    }
+    vol.writeFileSync(normalized, content);
+  }
+  void p; // silence unused on some paths
+}
+
+/**
+ * Translate a win32-style path to the posix-like path memfs uses internally.
+ * e.g. `C:\Users\Robert\.pi\settings.json` → `/C:/Users/Robert/.pi/settings.json`.
+ * Drive letter becomes a top-level directory. Separators flipped.
+ */
+export function toMemfsPath(winPath: string): string {
+  const replaced = winPath.replace(/\\/g, "/");
+  if (/^[A-Za-z]:/.test(replaced)) {
+    return "/" + replaced;
+  }
+  return replaced.startsWith("/") ? replaced : "/" + replaced;
+}
+
+/**
+ * Build a memfs-backed IFs that understands win32 paths by translating
+ * them to posix-form keys inside the volume.
+ */
+function wrapFsForPlatform(vol: Volume, platform: NodeJS.Platform): IFs {
+  const base = vol as unknown as IFs;
+  if (platform !== "win32") return base;
+  // Wrap: translate any incoming path through toMemfsPath.
+  const translate = (p: unknown): unknown =>
+    typeof p === "string" ? toMemfsPath(p) : p;
+  const wrap = <K extends keyof IFs>(name: K): IFs[K] => {
+    const orig = base[name] as unknown as (...args: unknown[]) => unknown;
+    if (typeof orig !== "function") return base[name];
+    return ((...args: unknown[]) => {
+      if (args.length > 0) args[0] = translate(args[0]);
+      return orig.apply(base, args);
+    }) as unknown as IFs[K];
+  };
+  return new Proxy(base, {
+    get(target, prop: string) {
+      if (prop === "existsSync" || prop === "readFileSync" || prop === "statSync"
+        || prop === "readdirSync" || prop === "writeFileSync" || prop === "mkdirSync"
+        || prop === "rmSync" || prop === "lstatSync") {
+        return wrap(prop as keyof IFs);
+      }
+      return (target as unknown as Record<string, unknown>)[prop];
+    },
+  }) as IFs;
+}
+
+/**
+ * Run an async callback inside a fresh in-memory environment.
+ *
+ * Does NOT mutate `process.platform`, `process.env`, `process.cwd()`,
+ * or any other host state — all environment surface is threaded through
+ * `HarnessContext` and the `StrategyDeps` it produces.
+ */
+export async function withFakeEnv<T>(
+  spec: FakeEnvSpec,
+  fn: (ctx: HarnessContext) => Promise<T> | T,
+): Promise<T> {
+  const vol = new Volume();
+  populateVolume(vol, spec.fs ?? {}, spec.platform);
+  const fs = wrapFsForPlatform(vol, spec.platform);
+  const pathlib = pathFor(spec.platform);
+  const env = spec.env ?? {};
+  const cwd = spec.cwd ?? spec.homedir;
+  const pathVar = env.PATH ?? "";
+  const pathEntries = pathVar === ""
+    ? []
+    : pathVar.split(pathDelim(spec.platform)).filter(Boolean);
+  const npmRootGlobal = spec.npmRootGlobal ?? defaultNpmRootGlobal(spec);
+
+  const whichFn = buildWhich(fs, pathEntries, spec.platform);
+  const resolveModuleFn = buildResolveModule(fs, spec.platform);
+  const existsFn = (p: string) => {
+    try {
+      return fs.existsSync(p);
+    } catch {
+      return false;
+    }
+  };
+
+  const createStrategyDeps = (): Required<StrategyDeps> => ({
+    exists: existsFn,
+    which: whichFn,
+    npmRootGlobal: () => npmRootGlobal,
+    resolveModule: resolveModuleFn,
+  });
+
+  const createRegistry = (extra?: Partial<ToolRegistryDeps>): ToolRegistry => {
+    const overridesStore = new FakeOverridesStore({ ...(spec.overrides ?? {}) });
+    const platformEnv: PlatformEnv = { homedir: spec.homedir, cwd };
+    return new ToolRegistry({
+      overrides: overridesStore as unknown as OverridesStore,
+      platform: spec.platform,
+      env: platformEnv,
+      now: () => 0,
+      ...extra,
+    });
+  };
+
+  const readSettings = (): Record<string, unknown> | null => {
+    const settingsPath = pathlib.join(spec.homedir, ".pi", "agent", "settings.json");
+    try {
+      const raw = fs.readFileSync(settingsPath, "utf-8") as string;
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  };
+
+  const ctx: HarnessContext = {
+    spec,
+    vol,
+    fs,
+    platform: spec.platform,
+    homedir: spec.homedir,
+    cwd,
+    env,
+    pathlib,
+    pathEntries,
+    npmRootGlobal,
+    createStrategyDeps,
+    createRegistry,
+    readSettings,
+  };
+
+  return await fn(ctx);
+}

package/packages/shared/src/__tests__/bootstrap/scenarios-skipped.ts

@@ -0,0 +1,125 @@
+/**
+ * Bulk-skip manifest for cells NOT yet covered by a family-test file.
+ *
+ * This is the "fail-closed by default" scaffold. Every cell in the
+ * cube starts SKIPPED with a documented reason. As family-test files
+ * are added, they call `register(cell, tag)` and the corresponding
+ * skip entry is automatically overridden (because registration takes
+ * precedence in the sweep).
+ *
+ * New cells added to the enumeration (by extending PLATFORMS,
+ * DASH_LOCATIONS, etc. in `scenarios.ts`) will fail the cube-sweep
+ * test until a decision is made here or in a family file.
+ *
+ * Call ordering invariant: this module MUST be imported before
+ * `sweepCube()` runs. Family-test files can import-and-register after
+ * this module runs — registration wins.
+ */
+import { enumerateCube, skip, type ScenarioCell } from "./scenarios.js";
+
+/**
+ * Classify why a given cell is not interesting / not reachable in
+ * practice. Returns null when the cell is plausible and should be
+ * covered by a family file — such cells get a generic placeholder
+ * skip reason here so the cube sweep passes on day 1; families
+ * replace the skip with registration as they land.
+ */
+function skipReasonFor(cell: ScenarioCell): string {
+  // ── Combinations that are not real install layouts ────────────────
+
+  // AppImage tmp mount is Linux-only, and only occurs when dash ===
+  // "electron" via an AppImage package.
+  if (cell.pi === "appimage-tmp" && (cell.platform !== "linux" || cell.dash !== "electron")) {
+    return "appimage-tmp is Linux + electron only";
+  }
+
+  // "dev" dash implies a workspace checkout — only meaningful on
+  // developer machines (typically mac/linux). Windows dev happens but
+  // is rare; capture later if needed.
+  if (cell.dash === "dev" && cell.platform === "win32") {
+    return "dev monorepo on Windows — rare; capture if reported";
+  }
+
+  // "home-drift" env only meaningful on Windows (Git Bash sets $HOME
+  // differently from os.homedir). On posix, $HOME and os.homedir
+  // agree.
+  if (cell.env === "home-drift" && cell.platform !== "win32") {
+    return "home-drift is a Windows-specific phenomenon";
+  }
+
+  // Malformed settings.json doesn't depend on pi state — the parse
+  // failure happens regardless. One test per platform is enough.
+  if (cell.settings === "malformed" && cell.pi !== "present-valid") {
+    return "malformed settings: one pi state per platform is sufficient";
+  }
+
+  // Appimage + anything other than settings=missing is not a real
+  // first-run scenario (appimage is installed fresh).
+  if (cell.pi === "appimage-tmp" && cell.settings !== "missing") {
+    return "appimage fresh-run implies missing settings.json";
+  }
+
+  // spaces-unicode env is orthogonal to most axes — one scenario per
+  // platform proves the invariant. Skip most combinations.
+  if (cell.env === "spaces-unicode" && cell.pi !== "present-valid") {
+    return "spaces-unicode: covered once per platform via pi=present-valid";
+  }
+
+  // ── Refined skip reasons (post families B-K) ──────────────────────
+
+  // Dashboard-absent is only interesting when pi is present (K1).
+  // Other combinations — pi absent without dashboard, etc. — are
+  // pathological and not reachable by any real install mechanic.
+  if (cell.dash === "absent" && cell.pi !== "present-valid") {
+    return "dashboard-absent only meaningful when pi is present (K1)";
+  }
+
+  // Lock-file and instance-coordination cells land with proposal
+  // `single-dashboard-per-home`, which introduces a new axis (lock
+  // state) not modelled in this cube. The current cells remain
+  // skipped until that proposal extends the enumeration.
+
+  // TODO(unified-bootstrap-install): add three scenarios once this
+  // change's task 13 wires the bootstrap through the home-lock:
+  //   - B1-post:   "npm-g-dash-only + bootstrap install ran→ pi resolves
+  //                 via managed + bridge auto-registered". Requires
+  //                 extending the cube with a `bootstrap?: "pre"|"post"`
+  //                 axis or a new pi state `managed-installed-fresh`.
+  //   - B4:        "pi-dashboard installed via npm-g, extension resolves
+  //                 via node_modules lookup (findBundledExtension
+  //                 Strategy 2)". Requires a new `pi-ext-resolution`
+  //                 axis.
+  //   - L2:        "two simultaneous bootstraps" (requires lock from
+  //                 single-dashboard-per-home to be wired).
+  // Reason skipped today: requires lock from single-dashboard-per-home
+  // to be wired AND the cube to grow new axes. Track in harness
+  // follow-up. See change: unified-bootstrap-install tasks 2.3, 10.2,
+  // 11.2, 13.2.
+
+  // pi=malformed means partial install; resolution failure reason
+  // is identical across settings/env axes once pi state is fixed.
+  // E2 covers linux + win32; other combinations add no signal.
+  if (
+    cell.pi === "malformed"
+    && cell.settings !== "empty"
+    && !(cell.platform === "linux" || cell.platform === "win32")
+  ) {
+    return "malformed pi: E2 covers linux+win32 — other settings/env add no signal";
+  }
+
+  // Remaining cells are plausible combinations with no dedicated
+  // family test. Documented as deliberate skips rather than gaps.
+  return "not yet covered — add family coverage when a bug reports here";
+}
+
+/**
+ * Apply bulk skips. Called at module load.
+ */
+export function applyBulkSkips(): void {
+  for (const cell of enumerateCube()) {
+    skip(cell, skipReasonFor(cell));
+  }
+}
+
+// Apply on import so scenario consumers see the full manifest.
+applyBulkSkips();

package/packages/shared/src/__tests__/bootstrap/scenarios.ts

@@ -0,0 +1,132 @@
+/**
+ * Scenario registry — the authoritative record of which cells are
+ * tested, which are explicitly skipped (with a reason), and which
+ * are unknown (fail-closed on CI).
+ *
+ * See openspec/changes/bootstrap-resolution-harness/design.md §5.
+ */
+
+/** The canonical axes for the scenario cube. */
+export const PLATFORMS = ["win32", "darwin", "linux"] as const;
+export const DASH_LOCATIONS = ["electron", "npm-g", "dev", "managed", "absent"] as const;
+export const PI_STATES = [
+  "absent",
+  "present-no-ext",
+  "present-stale-ext",
+  "present-valid",
+  "malformed",
+  "appimage-tmp",
+] as const;
+export const SETTINGS_STATES = ["missing", "empty", "valid", "malformed"] as const;
+export const ENV_STATES = ["normal", "spaces-unicode", "home-drift"] as const;
+
+export type Platform = (typeof PLATFORMS)[number];
+export type DashLocation = (typeof DASH_LOCATIONS)[number];
+export type PiState = (typeof PI_STATES)[number];
+export type SettingsState = (typeof SETTINGS_STATES)[number];
+export type EnvState = (typeof ENV_STATES)[number];
+
+export interface ScenarioCell {
+  platform: Platform;
+  dash: DashLocation;
+  pi: PiState;
+  settings: SettingsState;
+  env: EnvState;
+}
+
+export function cellKey(cell: ScenarioCell): string {
+  return [cell.platform, cell.dash, cell.pi, cell.settings, cell.env].join("/");
+}
+
+/** Parse a cell-key back into its components. */
+export function parseCellKey(key: string): ScenarioCell | null {
+  const parts = key.split("/");
+  if (parts.length !== 5) return null;
+  const [platform, dash, pi, settings, env] = parts;
+  if (!PLATFORMS.includes(platform as Platform)) return null;
+  if (!DASH_LOCATIONS.includes(dash as DashLocation)) return null;
+  if (!PI_STATES.includes(pi as PiState)) return null;
+  if (!SETTINGS_STATES.includes(settings as SettingsState)) return null;
+  if (!ENV_STATES.includes(env as EnvState)) return null;
+  return {
+    platform: platform as Platform,
+    dash: dash as DashLocation,
+    pi: pi as PiState,
+    settings: settings as SettingsState,
+    env: env as EnvState,
+  };
+}
+
+/**
+ * Cells with an active test. Entries added by each family-test file
+ * via `register(cell, describeSymbol)`.
+ *
+ * The value is a string tag identifying the test file — useful for
+ * the cube-sweep error message ("cell X already covered by Y").
+ */
+export const REGISTERED_SCENARIOS = new Map<string, string>();
+
+/**
+ * Cells explicitly skipped with a documented reason. New cells added
+ * to the enumeration that don't land in REGISTERED or SKIPPED will
+ * fail CI (the fail-closed invariant).
+ *
+ * Format: key → human-readable reason.
+ */
+export const SKIPPED_SCENARIOS = new Map<string, string>();
+
+/** Register a tested cell. Last-registered wins (tests may re-register during dev). */
+export function register(cell: ScenarioCell, tag: string): void {
+  REGISTERED_SCENARIOS.set(cellKey(cell), tag);
+}
+
+/** Skip a cell with a reason. Required before CI accepts the new cell. */
+export function skip(cell: ScenarioCell, reason: string): void {
+  if (!reason || reason.trim().length === 0) {
+    throw new Error(`SKIPPED_SCENARIOS entry for ${cellKey(cell)} requires a non-empty reason`);
+  }
+  SKIPPED_SCENARIOS.set(cellKey(cell), reason);
+}
+
+/** Mass-skip helper: all cells matching a partial pattern. */
+export function skipPattern(
+  partial: Partial<ScenarioCell>,
+  reason: string,
+): void {
+  for (const cell of enumerateCube()) {
+    let match = true;
+    for (const k of Object.keys(partial) as (keyof ScenarioCell)[]) {
+      if (cell[k] !== partial[k]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) skip(cell, reason);
+  }
+}
+
+/**
+ * Enumerate every combination. Order is stable (useful for snapshots
+ * and for deterministic error messages).
+ */
+export function enumerateCube(): ScenarioCell[] {
+  const out: ScenarioCell[] = [];
+  for (const platform of PLATFORMS) {
+    for (const dash of DASH_LOCATIONS) {
+      for (const pi of PI_STATES) {
+        for (const settings of SETTINGS_STATES) {
+          for (const env of ENV_STATES) {
+            out.push({ platform, dash, pi, settings, env });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Reset state — used only by tests that want to verify the cube logic itself. */
+export function __resetScenariosForTesting(): void {
+  REGISTERED_SCENARIOS.clear();
+  SKIPPED_SCENARIOS.clear();
+}