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

package/packages/extension/src/__tests__/no-session-replacement-calls.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Repo-level invariant: the bridge MUST NOT call pi's session-replacement
+ * APIs (`pi.newSession(...)`, `ctx.fork(...)`, `ctx.switchSession(...)`)
+ * from any code under `packages/extension/src/`.
+ *
+ * Rationale: pi 0.69.0+ invalidates captured pre-replacement `pi`/`ctx`/
+ * session-bound objects on next access after these calls. The bridge
+ * holds long-lived caches (`cachedCtx`, `cachedModelRegistry`,
+ * `cachedHasUI` in `bridge.ts`; `modelRegistry` in `provider-register.ts`)
+ * that depend on pi being the ONLY originator of session replacement, so
+ * we can re-capture inside the resulting `session_start` handler keyed on
+ * `event.reason ∈ {"new","fork","resume"}`.
+ *
+ * If this test fails: do NOT add the call. Either drive the user-facing
+ * action through the dashboard server (which prompts the user, who
+ * triggers replacement via pi's UI), or wrap your post-switch work in
+ * the `withSession` callback that pi 0.69+ exposes on each replacement
+ * API and capture the freshly-emitted ReplacedSessionContext there.
+ *
+ * See change: pi-zero-seventy-compat.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/**
+ * Each pattern matches `<receiver>.<method>(` allowing for whitespace and
+ * tolerating common variations like `await pi.newSession(...)`. Prefixed
+ * with a non-word boundary so we don't flag method names embedded in
+ * longer identifiers.
+ */
+const PATTERNS: ReadonlyArray<{ name: string; re: RegExp }> = [
+  { name: "pi.newSession",     re: /(?:^|[^.\w])pi\.newSession\s*\(/ },
+  { name: "ctx.fork",          re: /(?:^|[^.\w])ctx\.fork\s*\(/ },
+  { name: "ctx.switchSession", re: /(?:^|[^.\w])ctx\.switchSession\s*\(/ },
+];
+
+/**
+ * Per-line opt-out marker. Use only for documented exceptions (e.g. a
+ * future migration cell that intentionally drives a replacement and
+ * fully re-binds via `withSession`):
+ *   await pi.newSession({ withSession: ... }); // ban:session-replacement-ok
+ */
+const OPT_OUT_MARKER = "ban:session-replacement-ok";
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "__tests__") continue;
+      yield* walk(full);
+    } else if (entry.isFile() && /\.(ts|tsx|mts|cts)$/.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+describe("no session-replacement API calls in packages/extension/src/", () => {
+  it("bridge code never invokes pi.newSession / ctx.fork / ctx.switchSession", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const srcDir = path.resolve(here, "..");
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+
+    const violations: Array<{ file: string; line: number; pattern: string; text: string }> = [];
+
+    for await (const file of walk(srcDir)) {
+      const content = await fs.readFile(file, "utf-8");
+      const lines = content.split(/\r?\n/);
+      lines.forEach((line, idx) => {
+        if (line.includes(OPT_OUT_MARKER)) return;
+        for (const { name, re } of PATTERNS) {
+          if (re.test(line)) {
+            violations.push({
+              file: path.relative(repoRoot, file),
+              line: idx + 1,
+              pattern: name,
+              text: line.trim(),
+            });
+          }
+        }
+      });
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Bridge code MUST NOT call pi session-replacement APIs.\n` +
+        `pi 0.69.0+ invalidates captured pre-replacement pi/ctx after these calls;\n` +
+        `the bridge relies on pi being the sole originator of replacement so it can\n` +
+        `re-capture state inside the resulting session_start handler.\n\n` +
+        `Offenders (${violations.length}):\n` +
+        violations
+          .map((v) => `  ${v.file}:${v.line}  [${v.pattern}]  ${v.text}`)
+          .join("\n");
+      expect(violations, msg).toEqual([]);
+    }
+  });
+});

package/packages/extension/src/__tests__/no-tui-multiselect-arm-regression.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Repo-level invariant: `packages/extension/src/bridge.ts` MUST NOT
+ * contain the co-occurrence of two substrings:
+ *
+ *   1. `originals.custom`
+ *   2. `prompt.type === "multiselect"`
+ *
+ * If both appear in the same file, a contributor has (re)introduced the
+ * TUI PromptBus-adapter multiselect arm that was removed by change
+ * `fix-multiselect-tui-arm-self-cancel`. The arm is forbidden because
+ * pi 0.70's RPC mode (the only mode dashboard headless sessions run
+ * under) defines `ExtensionUIContext.custom` as an unconditional no-op
+ * (`async custom() { return undefined; }`, see
+ * `~/.nvm/.../@mariozechner/pi-coding-agent/dist/modes/rpc/rpc-mode.js`
+ * lines 150-153). Awaiting that primitive resolves to `undefined`
+ * synchronously, and the TUI arm's `bus.respond({ cancelled: true,
+ * source: "tui" })` triggers the PromptBus's first-response-wins
+ * dismissal — which auto-cancels the dashboard's already-rendered
+ * `MultiselectRenderer` within ~1 event-loop tick.
+ *
+ * The bus-routed `(ctx.ui as any).multiselect = (...) => bus.request(...)`
+ * patch site uses the substring `type: "multiselect"` (object-literal
+ * shape), not `prompt.type === "multiselect"` (equality-check shape),
+ * so it is unaffected by this lint.
+ *
+ * To remove a legitimate `originals.custom` reference (e.g. for a
+ * future use that does not include multiselect prompt routing), keep
+ * one substring and ensure the other does not co-occur.
+ *
+ * See change: fix-multiselect-tui-arm-self-cancel.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+const FORBIDDEN_A = "originals.custom";
+const FORBIDDEN_B = 'prompt.type === "multiselect"';
+
+function findLineNumbers(src: string, needle: string): number[] {
+  const lines = src.split(/\r?\n/);
+  const hits: number[] = [];
+  lines.forEach((line, idx) => {
+    if (line.includes(needle)) hits.push(idx + 1);
+  });
+  return hits;
+}
+
+describe("no TUI multiselect arm regression in bridge.ts", () => {
+  it("bridge.ts MUST NOT contain both `originals.custom` and `prompt.type === \"multiselect\"`", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const bridgePath = path.resolve(here, "..", "bridge.ts");
+    const src = await fs.readFile(bridgePath, "utf-8");
+
+    const hasA = src.includes(FORBIDDEN_A);
+    const hasB = src.includes(FORBIDDEN_B);
+
+    if (hasA && hasB) {
+      const linesA = findLineNumbers(src, FORBIDDEN_A);
+      const linesB = findLineNumbers(src, FORBIDDEN_B);
+      const msg =
+        `Forbidden co-occurrence in ${path.relative(process.cwd(), bridgePath)}:\n` +
+        `  - "${FORBIDDEN_A}" found on line(s): ${linesA.join(", ")}\n` +
+        `  - "${FORBIDDEN_B}" found on line(s): ${linesB.join(", ")}\n` +
+        `\n` +
+        `This pattern was removed by change "fix-multiselect-tui-arm-self-cancel".\n` +
+        `pi 0.70 RPC mode's ctx.ui.custom is a no-op, so a TUI multiselect\n` +
+        `arm that awaits originals.custom auto-cancels the dashboard-rendered\n` +
+        `dialog within ~1 event-loop tick. The bus-routed ctx.ui.multiselect\n` +
+        `patch + DashboardDefaultAdapter handle multiselect end-to-end without\n` +
+        `any TUI arm participation. See:\n` +
+        `  openspec/changes/archive/<date>-fix-multiselect-tui-arm-self-cancel/\n` +
+        `(or openspec/changes/fix-multiselect-tui-arm-self-cancel/ if not yet archived).`;
+      expect.fail(msg);
+    }
+
+    // Guardrail: at least one of the two substrings absent (we already
+    // assert above that both-present is illegal). Either-alone is fine.
+    expect(hasA && hasB).toBe(false);
+  });
+});

package/packages/extension/src/__tests__/openspec-activity-detector.test.ts

@@ -229,4 +229,41 @@ describe("detectOpenSpecActivity", () => {
       expect(result).toBeNull();
     });
   });
+
+  describe("flag-shaped change names", () => {
+    it("returns null for `openspec archive --help`", () => {
+      const result = detectOpenSpecActivity("bash", {
+        command: "openspec archive --help",
+      });
+      expect(result).toBeNull();
+    });
+
+    it("returns null for `openspec new change --help`", () => {
+      const result = detectOpenSpecActivity("bash", {
+        command: "openspec new change --help",
+      });
+      expect(result).toBeNull();
+    });
+
+    it("returns null when --change is followed by another flag", () => {
+      const result = detectOpenSpecActivity("bash", {
+        command: "openspec foo --change --help",
+      });
+      expect(result).toBeNull();
+    });
+
+    it("still extracts a real change name from `openspec archive add-auth`", () => {
+      const result = detectOpenSpecActivity("bash", {
+        command: "openspec archive add-auth",
+      });
+      expect(result).toEqual({ changeName: "add-auth", isActive: true });
+    });
+
+    it("still extracts a quoted change name from `openspec archive \"add-auth\"`", () => {
+      const result = detectOpenSpecActivity("bash", {
+        command: 'openspec archive "add-auth"',
+      });
+      expect(result).toEqual({ changeName: "add-auth", isActive: true });
+    });
+  });
 });

package/packages/extension/src/__tests__/ui-decorators.test.ts

@@ -0,0 +1,309 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { refreshUiModules, subscribeUiInvalidate, type UiModulesBridgeCtx } from "../ui-modules.js";
+import type { DecoratorDescriptor, ExtensionUiModule } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+/**
+ * Phase-2 (`add-extension-ui-decorations`) bridge contract:
+ *
+ *   - `refreshUiModules` partitions probe.modules by `kind` — `management-modal`
+ *     keeps flowing through `ui_modules_list`; the five Phase-2 kinds each
+ *     forward as one `ext_ui_decorator` message.
+ *   - Decorators MUST carry a `namespace` matching `/^[a-z0-9-]+$/`; malformed
+ *     namespaces are dropped with a warning.
+ *   - `(kind, namespace, id)` collisions within one probe → warning + last-write-wins.
+ *   - `removed: true` is forwarded verbatim.
+ *   - `ui:invalidate` re-runs the partitioned probe.
+ *   - Per-session invalidate rate cap: ≤20 invalidations/second; excess
+ *     coalesced to a trailing-edge probe with one warning.
+ */
+
+function createTestCtx(sessionId = "s1") {
+  const listeners = new Map<string, Array<(...args: any[]) => any>>();
+  const sent: any[] = [];
+
+  const ctx: UiModulesBridgeCtx & { _sent: any[]; _listeners: typeof listeners } = {
+    pi: {
+      events: {
+        on: vi.fn((event: string, fn: (...args: any[]) => any) => {
+          if (!listeners.has(event)) listeners.set(event, []);
+          listeners.get(event)!.push(fn);
+        }) as any,
+        emit: vi.fn((event: string, ...args: any[]) => {
+          const handlers = listeners.get(event) ?? [];
+          for (const h of handlers) h(...args);
+        }) as any,
+      },
+    },
+    connection: {
+      send: vi.fn((msg: unknown) => {
+        sent.push(msg);
+      }) as any,
+    },
+    getSessionId: () => sessionId,
+    _sent: sent,
+    _listeners: listeners,
+  };
+  return ctx;
+}
+
+const sampleModule = (id: string, command: string): ExtensionUiModule => ({
+  kind: "management-modal",
+  id,
+  command,
+  title: id,
+  view: { kind: "table", dataEvent: `${id}:rows`, fields: [{ key: "id", label: "ID", kind: "text" }] },
+});
+
+const footerSeg = (namespace: string, id: string, text: string): DecoratorDescriptor => ({
+  kind: "footer-segment",
+  namespace,
+  id,
+  payload: { text },
+});
+
+const gate = (namespace: string, id: string, flowId: string, available: boolean, reason?: string): DecoratorDescriptor => ({
+  kind: "gate",
+  namespace,
+  id,
+  payload: { flowId, available, reason },
+});
+
+const toast = (namespace: string, id: string, message: string): DecoratorDescriptor => ({
+  kind: "toast",
+  namespace,
+  id,
+  payload: { level: "info", message },
+});
+
+describe("refreshUiModules — Phase-2 partitioning", () => {
+  it("partitions a mixed probe into one ui_modules_list (modal-only) plus one ext_ui_decorator per decorator", () => {
+    const ctx = createTestCtx("S");
+    ctx._listeners.set("ui:list-modules", [
+      (probe: { modules: any[] }) => {
+        probe.modules.push(sampleModule("judo-status", "/judo:status"));
+        probe.modules.push(footerSeg("judo", "model-state", "3 mut"));
+        probe.modules.push(gate("judo", "save", "judo:save", false, "Not in workspace"));
+        probe.modules.push(toast("flows", "done", "Flow finished"));
+      },
+    ]);
+
+    refreshUiModules(ctx);
+
+    // Exactly one ui_modules_list, exactly three ext_ui_decorator.
+    const moduleMsgs = ctx._sent.filter((m) => m.type === "ui_modules_list");
+    const decoratorMsgs = ctx._sent.filter((m) => m.type === "ext_ui_decorator");
+    expect(moduleMsgs).toHaveLength(1);
+    expect(decoratorMsgs).toHaveLength(3);
+
+    expect(moduleMsgs[0]).toMatchObject({
+      type: "ui_modules_list",
+      sessionId: "S",
+      modules: [expect.objectContaining({ id: "judo-status", kind: "management-modal" })],
+    });
+
+    const kinds = decoratorMsgs.map((m) => m.descriptor.kind).sort();
+    expect(kinds).toEqual(["footer-segment", "gate", "toast"]);
+    for (const m of decoratorMsgs) {
+      expect(m.sessionId).toBe("S");
+      expect(m.removed).toBeUndefined();
+    }
+  });
+
+  it("forwards no decorator messages when only modal modules are pushed", () => {
+    const ctx = createTestCtx();
+    ctx._listeners.set("ui:list-modules", [
+      (probe: { modules: any[] }) => {
+        probe.modules.push(sampleModule("a", "/a"));
+      },
+    ]);
+    refreshUiModules(ctx);
+    expect(ctx._sent.filter((m) => m.type === "ext_ui_decorator")).toHaveLength(0);
+    expect(ctx._sent.filter((m) => m.type === "ui_modules_list")).toHaveLength(1);
+  });
+
+  it("forwards decorator-only probe with empty modules list", () => {
+    const ctx = createTestCtx();
+    ctx._listeners.set("ui:list-modules", [
+      (probe: { modules: any[] }) => {
+        probe.modules.push(footerSeg("judo", "f1", "x"));
+        probe.modules.push(footerSeg("judo", "f2", "y"));
+      },
+    ]);
+    refreshUiModules(ctx);
+    const modulesMsg = ctx._sent.find((m) => m.type === "ui_modules_list");
+    expect(modulesMsg).toBeDefined();
+    expect(modulesMsg.modules).toEqual([]);
+    expect(ctx._sent.filter((m) => m.type === "ext_ui_decorator")).toHaveLength(2);
+  });
+
+  it("rejects decorators with malformed namespace and warns", () => {
+    const ctx = createTestCtx();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      ctx._listeners.set("ui:list-modules", [
+        (probe: { modules: any[] }) => {
+          probe.modules.push(footerSeg("", "id1", "bad-empty"));
+          probe.modules.push(footerSeg("UPPER", "id2", "bad-case"));
+          probe.modules.push(footerSeg("with space", "id3", "bad-space"));
+          probe.modules.push(footerSeg("ok-ns", "id4", "good"));
+        },
+      ]);
+      refreshUiModules(ctx);
+
+      const decoratorMsgs = ctx._sent.filter((m) => m.type === "ext_ui_decorator");
+      expect(decoratorMsgs).toHaveLength(1);
+      expect(decoratorMsgs[0].descriptor.namespace).toBe("ok-ns");
+      // Three bad descriptors → at least one warning each (or one combined).
+      expect(warn).toHaveBeenCalled();
+      const allWarnText = warn.mock.calls.map((c) => String(c[0])).join("\n");
+      expect(allWarnText).toMatch(/namespace/i);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("collisions on (kind, namespace, id) within one probe warn once and last-write-wins", () => {
+    const ctx = createTestCtx();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      ctx._listeners.set("ui:list-modules", [
+        (probe: { modules: any[] }) => {
+          probe.modules.push(footerSeg("judo", "x", "first"));
+          probe.modules.push(footerSeg("judo", "x", "second"));
+          probe.modules.push(footerSeg("judo", "x", "third"));
+        },
+      ]);
+      refreshUiModules(ctx);
+
+      const decoratorMsgs = ctx._sent.filter((m) => m.type === "ext_ui_decorator");
+      expect(decoratorMsgs).toHaveLength(1);
+      expect((decoratorMsgs[0].descriptor.payload as any).text).toBe("third");
+      // One warning per colliding key, regardless of how many duplicates.
+      const collisionWarnings = warn.mock.calls.filter((c) => /footer-segment:judo:x/.test(String(c[0])));
+      expect(collisionWarnings.length).toBe(1);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("different namespaces with the same id are NOT a collision", () => {
+    const ctx = createTestCtx();
+    ctx._listeners.set("ui:list-modules", [
+      (probe: { modules: any[] }) => {
+        probe.modules.push(footerSeg("judo", "model-state", "judo-text"));
+        probe.modules.push(footerSeg("flows", "model-state", "flows-text"));
+      },
+    ]);
+    refreshUiModules(ctx);
+    const decoratorMsgs = ctx._sent.filter((m) => m.type === "ext_ui_decorator");
+    expect(decoratorMsgs).toHaveLength(2);
+    const namespaces = decoratorMsgs.map((m) => m.descriptor.namespace).sort();
+    expect(namespaces).toEqual(["flows", "judo"]);
+  });
+
+  it("forwards `removed: true` verbatim on decorator descriptors", () => {
+    const ctx = createTestCtx();
+    ctx._listeners.set("ui:list-modules", [
+      (probe: { modules: any[] }) => {
+        probe.modules.push({ ...gate("judo", "save", "judo:save", true), removed: true });
+      },
+    ]);
+    refreshUiModules(ctx);
+    const decoratorMsgs = ctx._sent.filter((m) => m.type === "ext_ui_decorator");
+    expect(decoratorMsgs).toHaveLength(1);
+    expect(decoratorMsgs[0].removed).toBe(true);
+    expect(decoratorMsgs[0].descriptor.kind).toBe("gate");
+  });
+
+  it("does not regress Phase-1 module-only probes", () => {
+    // Mirrors the Phase-1 test "emits ui:list-modules and forwards collected
+    // modules as ui_modules_list" — Phase-2 partitioning MUST be a no-op when
+    // no decorators are pushed.
+    const ctx = createTestCtx("session-A");
+    ctx._listeners.set("ui:list-modules", [
+      (probe: { modules: ExtensionUiModule[] }) => {
+        probe.modules.push(sampleModule("judo-status", "/judo:status"));
+        probe.modules.push(sampleModule("ragger-workspaces", "/ragger:workspaces"));
+      },
+    ]);
+    refreshUiModules(ctx);
+    const moduleMsgs = ctx._sent.filter((m) => m.type === "ui_modules_list");
+    expect(moduleMsgs).toHaveLength(1);
+    expect(moduleMsgs[0].modules).toHaveLength(2);
+    expect(ctx._sent.filter((m) => m.type === "ext_ui_decorator")).toHaveLength(0);
+  });
+});
+
+describe("subscribeUiInvalidate — Phase-2 re-forwarding", () => {
+  it("re-runs the partitioned probe on every ui:invalidate (leading + trailing under throttle)", () => {
+    vi.useFakeTimers();
+    try {
+      const ctx = createTestCtx();
+      let counter = 0;
+      ctx._listeners.set("ui:list-modules", [
+        (probe: { modules: any[] }) => {
+          counter++;
+          probe.modules.push(footerSeg("judo", "model-state", `count=${counter}`));
+        },
+      ]);
+      subscribeUiInvalidate(ctx);
+
+      // Leading-edge probe.
+      ctx.pi.events!.emit("ui:invalidate", { id: "model-state" });
+      // Coalesced into trailing-edge probe — flush by advancing timers past
+      // the 50ms throttle window.
+      ctx.pi.events!.emit("ui:invalidate", { id: "model-state" });
+      vi.advanceTimersByTime(100);
+
+      const decoratorMsgs = ctx._sent.filter((m) => m.type === "ext_ui_decorator");
+      expect(decoratorMsgs).toHaveLength(2);
+      expect((decoratorMsgs[0].descriptor.payload as any).text).toBe("count=1");
+      expect((decoratorMsgs[1].descriptor.payload as any).text).toBe("count=2");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("Per-session ui:invalidate rate cap", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("coalesces a 100-invalidation burst to a small bounded number of probes with exactly one warning", () => {
+    const ctx = createTestCtx();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      let probeCount = 0;
+      ctx._listeners.set("ui:list-modules", [
+        (probe: { modules: any[] }) => {
+          probeCount++;
+          probe.modules.push(footerSeg("judo", "model-state", `p${probeCount}`));
+        },
+      ]);
+
+      subscribeUiInvalidate(ctx);
+
+      // Fire 100 invalidations within ~200ms (well over the 20/sec cap).
+      for (let i = 0; i < 100; i++) {
+        ctx.pi.events!.emit("ui:invalidate", { id: "x" });
+        vi.advanceTimersByTime(2);
+      }
+      // Allow any trailing-edge timer to fire.
+      vi.advanceTimersByTime(2000);
+
+      // Probes are bounded — at minimum 1 (the first), at most a handful, NOT 100.
+      expect(probeCount).toBeGreaterThanOrEqual(1);
+      expect(probeCount).toBeLessThanOrEqual(10);
+
+      // Exactly one rate-cap warning per offending burst.
+      const rateWarnings = warn.mock.calls.filter((c) => /rate|invalidat/i.test(String(c[0])));
+      expect(rateWarnings.length).toBe(1);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});