@blackbelt-technology/pi-agent-dashboard 0.5.1 → 0.5.2

package/packages/extension/src/slash-dispatch.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared extension-slash-command dispatch branch used by both bridge.ts
+ * (sessionPrompt callback) and command-handler.ts (slash else-arm fallback).
+ *
+ * Routing-step 9 from `command-routing` spec — three-way decision:
+ *   - Path B: when `pi.dispatchCommand` is a function → call it directly.
+ *   - Path C: when `pi.dispatchCommand` is absent AND the bridge runs inside a
+ *     dashboard-spawned headless `pi --mode rpc` AND a `connection` is wired
+ *     → emit `dispatch_extension_command` to the server (server forwards to
+ *     the per-session RPC keeper UDS and emits the terminal command_feedback).
+ *   - Path D (stopgap, last resort): `pi.dispatchCommand` absent AND the bridge
+ *     is NOT headless (tmux / wt / unrecognized spawn shape) OR no `connection`
+ *     was supplied → emit `command_feedback {status:"error"}` with a pi-version
+ *     reminder.
+ *
+ * If `text` is NOT an extension command, return `false` so the caller can
+ * fall through to its existing template-expansion / sendUserMessage path.
+ *
+ * Guarantees: EXACTLY ONE `started` event AND EXACTLY ONE terminal event
+ * (`completed` xor `error`) per dispatch, across all three paths combined.
+ * Path C does NOT emit a terminal event — the server emits it.
+ *
+ * See change: fix-extension-slash-commands-in-dashboard,
+ *             add-rpc-stdin-dispatch-with-keeper-sidecar.
+ */
+import crypto from "node:crypto";
+import type { ExtensionToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
+import { hasDispatchCommand, isExtensionSlashCommand, isHeadlessRpcSession } from "./bridge-context.js";
+
+export type FeedbackSink = (msg: ExtensionToServerMessage) => void;
+
+/**
+ * Minimal connection surface used by Path C. Concrete implementation is
+ * `ConnectionManager` (`connection.ts`) but a structural type keeps this
+ * helper unit-testable without a real WebSocket.
+ */
+export interface DispatchConnection {
+  send(msg: ExtensionToServerMessage): void;
+}
+
+const PI_071_REQUIRED =
+  "Extension slash commands cannot be dispatched from the dashboard yet — requires pi 0.71+ (`pi.dispatchCommand`). Invoke from the pi TUI, or use the extension's tools directly.";
+
+function emitFeedback(
+  sink: FeedbackSink | undefined,
+  sessionId: string,
+  command: string,
+  status: "started" | "completed" | "error",
+  message?: string,
+): void {
+  if (!sink) return;
+  sink({
+    type: "event_forward",
+    sessionId,
+    event: {
+      eventType: "command_feedback",
+      timestamp: Date.now(),
+      data: message === undefined ? { command, status } : { command, status, message },
+    },
+  });
+}
+
+/**
+ * Try to dispatch a slash command as an extension command.
+ *
+ * @returns `true` if the helper handled the text (extension command detected;
+ *          dispatch attempted or stopgap emitted). The caller MUST NOT fall
+ *          through to template expansion or `sendUserMessage`.
+ * @returns `false` if `text` is not an extension slash command. The caller
+ *          SHOULD continue with its existing fallback path.
+ */
+export async function tryDispatchExtensionCommand(
+  pi: unknown,
+  text: string,
+  sessionId: string,
+  sink: FeedbackSink | undefined,
+  connection?: DispatchConnection,
+): Promise<boolean> {
+  // Defensive: pi.getCommands() can throw on a stale ctx during dispose.
+  let commands: Array<{ name: string; source?: string }> = [];
+  try {
+    const got = (pi as any)?.getCommands?.();
+    if (Array.isArray(got)) commands = got;
+  } catch (err) {
+    console.warn("[dashboard] getCommands stale on slash-dispatch", err);
+    return false; // fall through to existing path; preserve today's behavior
+  }
+
+  if (!isExtensionSlashCommand(text, commands)) return false;
+
+  emitFeedback(sink, sessionId, text, "started");
+
+  // Path B (preferred when available): pi 0.71+ exposes dispatchCommand.
+  if (hasDispatchCommand(pi)) {
+    try {
+      await (pi as any).dispatchCommand(text, { streamingBehavior: "followUp" });
+      emitFeedback(sink, sessionId, text, "completed");
+    } catch (err: any) {
+      const message = err instanceof Error ? err.message : String(err);
+      emitFeedback(sink, sessionId, text, "error", message);
+    }
+    return true;
+  }
+
+  // Path C: headless RPC session, dispatchCommand absent. Hand off to the
+  // server, which writes the line to the session's RPC keeper UDS and
+  // emits the terminal command_feedback. The bridge does NOT emit a
+  // terminal event for this path — that would duplicate the reducer's
+  // started→terminal upsert. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+  if (connection && isHeadlessRpcSession()) {
+    connection.send({
+      type: "dispatch_extension_command",
+      sessionId,
+      command: text,
+      requestId: crypto.randomUUID(),
+    });
+    return true;
+  }
+
+  // Path D (stopgap): no dispatchCommand and not headless (tmux / wt / unrecognized).
+  emitFeedback(sink, sessionId, text, "error", PI_071_REQUIRED);
+  return true;
+}

package/packages/server/bin/pi-dashboard.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * pi-dashboard CLI entry point.
+ *
+ * The actual CLI is `../src/cli.ts`. This wrapper exists because a
+ * `#!/usr/bin/env` shebang cannot interpolate a dynamic `--import`
+ * loader path. The wrapper resolves jiti from pi's tree at runtime
+ * and re-execs Node with `--import <jiti-url> cli.ts <args>`.
+ *
+ * No tsx fallback: if jiti cannot be resolved, the wrapper exits 1
+ * with an install-hint pointing at pi. Mirrors the resolution shape
+ * in `packages/shared/src/resolve-jiti.ts` (cannot import the .ts
+ * module before a TS loader is registered, so the lookup is inlined).
+ *
+ * See change: replace-tsx-with-jiti.
+ */
+import { createRequire } from "node:module";
+import { realpathSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliPath = resolve(here, "..", "src", "cli.ts");
+
+// Mirrors packages/shared/src/resolve-jiti.ts JITI_PACKAGES.
+const JITI_PACKAGES = ["jiti", "@mariozechner/jiti"];
+
+/** Resolve pi's jiti register hook as a file:// URL. Returns null on miss. */
+function resolveJitiUrl() {
+  const anchor = process.argv[1];
+  if (!anchor) return null;
+  let resolved;
+  try {
+    resolved = realpathSync(anchor);
+  } catch {
+    return null;
+  }
+  const req = createRequire(resolved);
+  for (const pkg of JITI_PACKAGES) {
+    try {
+      const pkgJson = req.resolve(`${pkg}/package.json`);
+      const registerPath = join(dirname(pkgJson), "lib", "jiti-register.mjs");
+      return pathToFileURL(registerPath).href;
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+const loader = resolveJitiUrl();
+if (!loader) {
+  process.stderr.write(
+    "pi-dashboard: cannot find jiti. " +
+      "Install pi: 'npm install -g @earendil-works/pi-coding-agent'\n",
+  );
+  process.exit(1);
+}
+
+// Mirrors shouldUrlWrapEntry() in packages/shared/src/platform/node-spawn.ts:
+// jiti needs the entry URL-wrapped on Windows (Node rejects raw drive-letter
+// paths for --import). POSIX takes the raw path.
+const entry = process.platform === "win32" ? pathToFileURL(cliPath).href : cliPath;
+
+const child = spawn(
+  process.execPath,
+  ["--import", loader, entry, ...process.argv.slice(2)],
+  { stdio: "inherit", windowsHide: true },
+);
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Re-raise the signal so the parent shell sees the same exit reason.
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});
+
+child.on("error", (err) => {
+  process.stderr.write(`pi-dashboard: failed to spawn Node: ${err.message}\n`);
+  process.exit(1);
+});

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
   "repository": {
@@ -21,9 +21,10 @@
   },
   "main": "src/cli.ts",
   "bin": {
-    "pi-dashboard": "src/cli.ts"
+    "pi-dashboard": "bin/pi-dashboard.mjs"
   },
   "files": [
+    "bin/",
     "src/",
     "scripts/"
   ],
@@ -31,9 +32,9 @@
     "postinstall": "node scripts/fix-pty-permissions.cjs"
   },
   "dependencies": {
-    "@blackbelt-technology/dashboard-plugin-runtime": "^0.5.1",
-    "@blackbelt-technology/pi-dashboard-extension": "^0.5.1",
-    "@blackbelt-technology/pi-dashboard-shared": "^0.5.1",
+    "@blackbelt-technology/dashboard-plugin-runtime": "^0.5.2",
+    "@blackbelt-technology/pi-dashboard-extension": "^0.5.2",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.5.2",
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.0.0",

package/packages/server/scripts/fix-pty-permissions.cjs

@@ -0,0 +1,52 @@
+/**
+ * Fix node-pty native prebuild permissions after npm install.
+ *
+ * The prebuilt `spawn-helper` (and occasionally `pty.node`) may be unpacked
+ * without the execute bit, which causes `posix_spawnp failed` errors when
+ * calling `pty.spawn(...)` on macOS/Linux.
+ *
+ * This script is hoist-aware: it locates `node-pty` via `require.resolve`
+ * rather than a hardcoded relative path, so it works whether the dependency
+ * is nested under a workspace package's node_modules or hoisted to the
+ * workspace root.
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+if (os.platform() === "win32") process.exit(0);
+
+let prebuildsDir;
+try {
+  const ptyPkg = require.resolve("node-pty/package.json");
+  prebuildsDir = path.join(path.dirname(ptyPkg), "prebuilds");
+} catch {
+  // node-pty not installed (e.g. running from a workspace that doesn't depend
+  // on it, or the package hasn't been installed yet). Silent no-op.
+  process.exit(0);
+}
+
+let prebuildDirs;
+try {
+  prebuildDirs = fs.readdirSync(prebuildsDir);
+} catch {
+  // prebuilds dir missing — unusual, but not fatal. Silent no-op.
+  process.exit(0);
+}
+
+for (const dir of prebuildDirs) {
+  for (const name of ["spawn-helper", "pty.node"]) {
+    const target = path.join(prebuildsDir, dir, name);
+    try {
+      fs.chmodSync(target, 0o755);
+    } catch (err) {
+      // Individual chmod failures are logged to stderr (not swallowed) so
+      // real problems become visible, but we still try remaining files.
+      if (err && err.code !== "ENOENT") {
+        process.stderr.write(
+          `[fix-pty-permissions] chmod ${target} failed: ${err.message}\n`,
+        );
+      }
+    }
+  }
+}

package/packages/server/src/__tests__/cli-parse.test.ts

@@ -76,27 +76,21 @@ describe("parseArgs", () => {
 });
 
 describe("daemon spawn jiti resolution", () => {
-  it("resolveJitiImport either returns a file:// URL or throws the documented error", async () => {
-    // After change `support-upstream-jiti-resolution`, the resolver
-    // also looks for upstream `jiti` (bare name). Vitest itself depends
-    // transitively on `jiti`, so when the test runner is the anchor,
-    // resolution may succeed. Either outcome is valid — we just assert
-    // the contract: success returns a `file://` URL, failure throws the
-    // documented error.
-    const { resolveJitiImport } = await import(
-      "@blackbelt-technology/pi-dashboard-shared/resolve-jiti.js"
+  it("ToolResolver.resolveJiti either returns a file:// URL or null", async () => {
+    // After change `unify-server-launch-ts-loader`, jiti resolution
+    // is owned by `ToolResolver.resolveJiti()` which walks managed pi
+    // → system pi → anchor → argv. Vitest's transitive `jiti` dep
+    // makes resolution likely succeed under the test runner; either
+    // outcome is valid — we just assert the contract: success returns
+    // a `file://` URL, miss returns null (no throw).
+    const { ToolResolver } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js"
     );
-    let url: string | undefined;
-    let err: Error | undefined;
-    try {
-      url = resolveJitiImport();
-    } catch (e) {
-      err = e as Error;
-    }
-    if (url !== undefined) {
+    const url = new ToolResolver().resolveJiti();
+    if (url !== null) {
       expect(url.startsWith("file://")).toBe(true);
     } else {
-      expect(err?.message).toContain("Cannot find pi's TypeScript loader");
+      expect(url).toBeNull();
     }
   });
 });

package/packages/server/src/__tests__/directory-service-openspec-enabled.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for `openspec.enabled` gating in DirectoryService.
+ *
+ * Confirms:
+ *   - `refreshOpenSpec` short-circuits (no CLI spawn, returns cleared shape).
+ *   - `pollDirectoryGated` short-circuits.
+ *   - `scheduleOpenSpecTick` short-circuits.
+ *   - `reconfigurePolling({ enabled: false })` clears every cached cwd and
+ *     broadcasts `openspec_update` via the onChange callback.
+ *
+ * See change: auto-hide-empty-session-subcards.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createDirectoryService, type DirectoryService } from "../directory-service.js";
+import type { PreferencesStore } from "../preferences-store.js";
+import type { SessionManager } from "../memory-session-manager.js";
+import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import { DEFAULT_OPENSPEC_POLL } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+
+// Mock CLI entry points so we can spy on whether they get called.
+vi.mock("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js", async (importOriginal) => {
+  const actual = await importOriginal<
+    typeof import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js")
+  >();
+  return {
+    ...actual,
+    pollOpenSpecAsync: vi.fn(async () => ({ initialized: true, changes: [] })),
+    runOpenSpecList: vi.fn(async () => null),
+    runOpenSpecStatus: vi.fn(async () => null),
+  };
+});
+
+vi.mock("../pi-resource-scanner.js", () => ({
+  scanPiResources: vi.fn(async () => ({
+    local: { extensions: [], skills: [], prompts: [] },
+    global: { extensions: [], skills: [], prompts: [] },
+    packages: [],
+  })),
+}));
+vi.mock("@blackbelt-technology/pi-dashboard-shared/state-replay.js", () => ({
+  replayEntriesAsEvents: vi.fn(() => []),
+}));
+vi.mock("../session-discovery.js", () => ({
+  discoverSessionsForCwd: vi.fn(() => []),
+}));
+vi.mock("../session-file-reader.js", () => ({
+  loadSessionEntries: vi.fn(() => []),
+}));
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  SessionManager: {
+    list: vi.fn(async () => []),
+    open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),
+  },
+}));
+
+function makePrefs(pinnedDirs: string[] = []): PreferencesStore {
+  return {
+    getPinnedDirectories: () => pinnedDirs,
+    getSessionOrder: () => ({}),
+    setSessionOrder: vi.fn(),
+    setPinnedDirectories: vi.fn(),
+    pinDirectory: vi.fn(),
+    unpinDirectory: vi.fn(),
+    reorderPinnedDirs: vi.fn(),
+    flush: vi.fn(),
+    dispose: vi.fn(),
+  };
+}
+function makeSessionMgr(sessions: DashboardSession[] = []): SessionManager {
+  const map = new Map<string, DashboardSession>();
+  for (const s of sessions) map.set(s.id, s);
+  return {
+    register: vi.fn(),
+    restore: vi.fn(),
+    unregister: vi.fn(),
+    update: vi.fn(),
+    get: (id: string) => map.get(id),
+    listActive: () => Array.from(map.values()).filter(s => s.status !== "ended"),
+    listAll: () => Array.from(map.values()),
+  };
+}
+
+describe("DirectoryService — openspec.enabled gate", () => {
+  let service: DirectoryService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  afterEach(() => {
+    service?.stopPolling();
+  });
+
+  it("refreshOpenSpec returns cleared shape and spawns no CLI when disabled", async () => {
+    const prefs = makePrefs(["/repo"]);
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr, { ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const { pollOpenSpecAsync, runOpenSpecList, runOpenSpecStatus } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js"
+    );
+
+    const data = await service.refreshOpenSpec("/repo");
+    expect(data).toEqual({
+      initialized: false,
+      pending: false,
+      changes: [],
+      hasOpenspecDir: false,
+    });
+    expect(pollOpenSpecAsync).not.toHaveBeenCalled();
+    expect(runOpenSpecList).not.toHaveBeenCalled();
+    expect(runOpenSpecStatus).not.toHaveBeenCalled();
+  });
+
+  it("pollDirectoryGated returns cleared shape and spawns no CLI when disabled", async () => {
+    const prefs = makePrefs();
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr, { ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const { runOpenSpecList } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js"
+    );
+
+    const data = await service.pollDirectoryGated("/repo");
+    expect(data).toEqual({
+      initialized: false,
+      pending: false,
+      changes: [],
+      hasOpenspecDir: false,
+    });
+    expect(runOpenSpecList).not.toHaveBeenCalled();
+  });
+
+  it("reconfigurePolling({ enabled: false }) broadcasts cleared payload for every cached cwd", async () => {
+    const prefs = makePrefs(["/a", "/b"]);
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr); // starts enabled
+
+    // Seed the cache by calling refresh while enabled.
+    const { runOpenSpecList, runOpenSpecStatus } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js"
+    );
+    (runOpenSpecList as any).mockResolvedValue({
+      mtimeMs: 1,
+      result: { changes: [], specs: [] },
+    });
+    (runOpenSpecStatus as any).mockResolvedValue(null);
+    await service.refreshOpenSpec("/a");
+    await service.refreshOpenSpec("/b");
+
+    expect(service.getOpenSpecData("/a")).toBeDefined();
+    expect(service.getOpenSpecData("/b")).toBeDefined();
+
+    // Wire the broadcast callback then flip the master gate.
+    const broadcasts: Array<{ cwd: string; data: unknown }> = [];
+    service.startPolling((cwd, data) => broadcasts.push({ cwd, data }));
+
+    service.reconfigurePolling({ ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const cleared = { initialized: false, pending: false, changes: [], hasOpenspecDir: false };
+    const cwds = new Set(broadcasts.map(b => b.cwd));
+    expect(cwds.has("/a")).toBe(true);
+    expect(cwds.has("/b")).toBe(true);
+    for (const b of broadcasts) {
+      expect(b.data).toEqual(cleared);
+    }
+    expect(service.getOpenSpecData("/a")).toEqual(cleared);
+    expect(service.getOpenSpecData("/b")).toEqual(cleared);
+  });
+
+  it("no broadcast on disabled→disabled or enabled→enabled reconfiguration", async () => {
+    const prefs = makePrefs(["/a"]);
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr, { ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const broadcasts: Array<{ cwd: string }> = [];
+    service.startPolling((cwd) => broadcasts.push({ cwd }));
+
+    // disabled → disabled with new interval — should not trigger the
+    // disable-broadcast path.
+    service.reconfigurePolling({
+      ...DEFAULT_OPENSPEC_POLL,
+      enabled: false,
+      pollIntervalSeconds: 90,
+    });
+    expect(broadcasts).toHaveLength(0);
+  });
+});

package/packages/server/src/__tests__/directory-service.test.ts

@@ -633,7 +633,7 @@ describe("DirectoryService", () => {
       const sessionManager = createMockSessionManager();
       service = createDirectoryService(stateStore, sessionManager);
       await service.refreshOpenSpec("/x");
-      service.reconfigurePolling({ pollIntervalSeconds: 60, maxConcurrentSpawns: 5, changeDetection: "mtime", jitterSeconds: 0 });
+      service.reconfigurePolling({ enabled: true, pollIntervalSeconds: 60, maxConcurrentSpawns: 5, changeDetection: "mtime", jitterSeconds: 0 });
       expect(service.getOpenSpecData("/x")).toBeDefined();
     });
   });