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

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

package/packages/shared/src/__tests__/bridge-register.test.ts

@@ -46,22 +46,45 @@ describe("shared bridge-register", () => {
     });
 
     it("returns null when extension dir does not exist", () => {
-      expect(findBundledExtension(tmpDir)).toBeNull();
+      // Disable Strategy 2 (node-resolver fallback) so we test Strategy 1 in isolation.
+      expect(findBundledExtension(tmpDir, { resolvePackage: () => null })).toBeNull();
     });
 
     it("returns null when no package.json in extension dir", () => {
       const extDir = path.join(tmpDir, "packages", "extension");
       fs.mkdirSync(extDir, { recursive: true });
       // No package.json
-      expect(findBundledExtension(tmpDir)).toBeNull();
+      expect(findBundledExtension(tmpDir, { resolvePackage: () => null })).toBeNull();
     });
 
     it("returns null for AppImage temp mount paths", () => {
-      // We can't easily create a /tmp/.mount_ path, but we can verify
-      // the function handles it via the string check
       const mockBase = "/tmp/.mount_PI1234/resources/server";
-      // findBundledExtension will check existsSync which returns false for this
-      expect(findBundledExtension(mockBase)).toBeNull();
+      // Even with a resolvable node-modules extension, if that resolved path is
+      // itself under /tmp/.mount_* it must be rejected (tested separately below).
+      expect(findBundledExtension(mockBase, { resolvePackage: () => null })).toBeNull();
+    });
+
+    it("Strategy 2 — falls back to require.resolve when baseDir has no packages/extension", () => {
+      // Simulate `npm i -g pi-dashboard` layout: baseDir is the server
+      // package root and contains no `packages/extension/`, but the
+      // extension is resolvable as a runtime dep via node_modules.
+      const fakeExtDir = path.join(tmpDir, "fake-node_modules", "pi-dashboard-extension");
+      fs.mkdirSync(fakeExtDir, { recursive: true });
+      fs.writeFileSync(path.join(fakeExtDir, "package.json"), '{"name":"fake"}');
+      const resolved = findBundledExtension(tmpDir, {
+        resolvePackage: () => path.join(fakeExtDir, "package.json"),
+      });
+      expect(resolved).toBe(fakeExtDir);
+    });
+
+    it("Strategy 2 — rejects AppImage-mount paths even when resolvable", () => {
+      // A /tmp/.mount_* path must be rejected regardless of which strategy
+      // surfaced it.
+      const appImageExtDir = "/tmp/.mount_PI1234/node_modules/@blackbelt-technology/pi-dashboard-extension";
+      const resolved = findBundledExtension(tmpDir, {
+        resolvePackage: () => path.join(appImageExtDir, "package.json"),
+      });
+      expect(resolved).toBeNull();
     });
   });
 

package/packages/shared/src/__tests__/config-openspec.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { loadConfig, DEFAULT_OPENSPEC_POLL } from "../config.js";
+
+describe("loadConfig — openspec poll block", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-config-openspec-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("applies all defaults when openspec block is missing", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+    const cfg = loadConfig();
+    expect(cfg.openspec).toEqual(DEFAULT_OPENSPEC_POLL);
+    expect(cfg.openspec.pollIntervalSeconds).toBe(30);
+    expect(cfg.openspec.maxConcurrentSpawns).toBe(3);
+    expect(cfg.openspec.changeDetection).toBe("mtime");
+    expect(cfg.openspec.jitterSeconds).toBe(5);
+  });
+
+  it("accepts valid values", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: 60, maxConcurrentSpawns: 5, changeDetection: "always", jitterSeconds: 10 },
+    }));
+    const cfg = loadConfig();
+    expect(cfg.openspec.pollIntervalSeconds).toBe(60);
+    expect(cfg.openspec.maxConcurrentSpawns).toBe(5);
+    expect(cfg.openspec.changeDetection).toBe("always");
+    expect(cfg.openspec.jitterSeconds).toBe(10);
+  });
+
+  it("clamps pollIntervalSeconds below the minimum (5)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { pollIntervalSeconds: 1 } }));
+    expect(loadConfig().openspec.pollIntervalSeconds).toBe(5);
+  });
+
+  it("clamps pollIntervalSeconds above the maximum (3600)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { pollIntervalSeconds: 999_999 } }));
+    expect(loadConfig().openspec.pollIntervalSeconds).toBe(3600);
+  });
+
+  it("clamps maxConcurrentSpawns to [1, 16]", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { maxConcurrentSpawns: 0 } }));
+    expect(loadConfig().openspec.maxConcurrentSpawns).toBe(1);
+
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { maxConcurrentSpawns: 100 } }));
+    expect(loadConfig().openspec.maxConcurrentSpawns).toBe(16);
+  });
+
+  it("clamps jitterSeconds to [0, 60]", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { jitterSeconds: -5 } }));
+    expect(loadConfig().openspec.jitterSeconds).toBe(0);
+
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { jitterSeconds: 120 } }));
+    expect(loadConfig().openspec.jitterSeconds).toBe(60);
+  });
+
+  it("falls back to 'mtime' when changeDetection is unknown", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { changeDetection: "bogus" } }));
+    expect(loadConfig().openspec.changeDetection).toBe("mtime");
+  });
+
+  it("coerces non-number values to defaults", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: "thirty", maxConcurrentSpawns: null, jitterSeconds: undefined },
+    }));
+    const cfg = loadConfig();
+    expect(cfg.openspec.pollIntervalSeconds).toBe(30);
+    expect(cfg.openspec.maxConcurrentSpawns).toBe(3);
+    expect(cfg.openspec.jitterSeconds).toBe(5);
+  });
+
+  it("ignores unknown keys in the openspec block", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: 45, nonsenseField: "ignored", another: 42 },
+    }));
+    const cfg = loadConfig();
+    expect(cfg.openspec.pollIntervalSeconds).toBe(45);
+    expect((cfg.openspec as any).nonsenseField).toBeUndefined();
+    expect((cfg.openspec as any).another).toBeUndefined();
+  });
+
+  it("is stable through round-trip (load → stringify → load)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: 90, maxConcurrentSpawns: 4, changeDetection: "always", jitterSeconds: 12 },
+    }));
+    const first = loadConfig();
+    fs.writeFileSync(configFile, JSON.stringify(first));
+    const second = loadConfig();
+    expect(second.openspec).toEqual(first.openspec);
+  });
+});

package/packages/shared/src/__tests__/config.test.ts

@@ -27,7 +27,7 @@ describe("loadConfig", () => {
     expect(config.port).toBe(8000);
     expect(config.piPort).toBe(9999);
     expect(config.autoStart).toBe(true);
-    expect(config.autoShutdown).toBe(true);
+    expect(config.autoShutdown).toBe(false);
     expect(config.lastServer).toBeUndefined();
     expect(config.shutdownIdleSeconds).toBe(300);
   });
@@ -52,7 +52,7 @@ describe("loadConfig", () => {
     expect(config.port).toBe(3000);
     expect(config.piPort).toBe(9999);
     expect(config.autoStart).toBe(true);
-    expect(config.autoShutdown).toBe(true);
+    expect(config.autoShutdown).toBe(false);
     expect(config.shutdownIdleSeconds).toBe(300);
   });
 
@@ -304,6 +304,62 @@ describe("loadConfig", () => {
     const config = loadConfig();
     expect(config.electronMode).toBe(false);
   });
+
+  // ── fix-trusted-networks-no-oauth regression tests ──────────────────
+  // These assert that auth.bypassHosts and auth.bypassUrls are honored
+  // at load time EVEN WHEN auth.providers is empty or absent. Before the
+  // fix, parseAuthConfig returned undefined whenever providers was empty,
+  // nuking bypassHosts before the resolvedTrustedNetworks merge could
+  // read it. See openspec/changes/fix-trusted-networks-no-oauth/.
+
+  it("should honor auth.bypassHosts when providers is {} (task 1.1)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { providers: {}, bypassHosts: ["192.168.1.0/24"] },
+    }));
+    const config = loadConfig();
+    expect(config.auth).toBeDefined();
+    expect(config.auth!.bypassHosts).toEqual(["192.168.1.0/24"]);
+    expect(config.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+  });
+
+  it("should honor auth.bypassHosts when no providers key at all (task 1.2)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { bypassHosts: ["10.0.0.0/8"] },
+    }));
+    const config = loadConfig();
+    expect(config.auth).toBeDefined();
+    expect(config.auth!.bypassHosts).toEqual(["10.0.0.0/8"]);
+    expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
+
+  it("should honor auth.bypassUrls when providers is {} (task 1.3)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { providers: {}, bypassUrls: ["/webhooks/"] },
+    }));
+    const config = loadConfig();
+    expect(config.auth).toBeDefined();
+    expect(config.auth!.bypassUrls).toEqual(["/webhooks/"]);
+  });
+
+  it("should return auth undefined when providers={} and all bypass arrays are empty (task 1.4 boundary)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { providers: {}, bypassHosts: [], bypassUrls: [] },
+    }));
+    const config = loadConfig();
+    // Truly empty auth → still undefined (boundary preserved)
+    expect(config.auth).toBeUndefined();
+    expect(config.resolvedTrustedNetworks).toEqual([]);
+  });
+
+  it("should merge top-level trustedNetworks with bypassHosts when no providers", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24"],
+      auth: { providers: {}, bypassHosts: ["10.0.0.0/8"] },
+    }));
+    const config = loadConfig();
+    expect(config.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+    expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
 });
 
 describe("ensureConfig", () => {
@@ -333,7 +389,7 @@ describe("ensureConfig", () => {
     expect(content.port).toBe(8000);
     expect(content.piPort).toBe(9999);
     expect(content.autoStart).toBe(true);
-    expect(content.autoShutdown).toBe(true);
+    expect(content.autoShutdown).toBe(false);
     expect(content.shutdownIdleSeconds).toBe(300);
     expect(content.devBuildOnReload).toBe(false);
     expect(content.electronMode).toBeUndefined();