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

package/packages/shared/src/test-support/setup-home.ts

@@ -0,0 +1,74 @@
+/**
+ * Vitest globalSetup: tripwire + directory bootstrap.
+ *
+ * Wired via `test.globalSetup` in each package's `vitest.config.ts`. Runs ONCE
+ * at vitest boot, before any test file is loaded.
+ *
+ * Responsibilities:
+ *   1. Tripwire — throws if `process.env.HOME` still points at the developer's
+ *      real user home (meaning the root `npm test` script wasn't used and HOME
+ *      wasn't overridden). Aborts the entire run before any destructive code
+ *      can touch real ~/.pi/.
+ *   2. Pre-create `<HOME>/.pi/agent/sessions/` and `<HOME>/.pi/dashboard/` so
+ *      production code that reads those paths finds empty but well-formed
+ *      directories.
+ *
+ * Why globalSetup (not setupFiles):
+ *   setupFiles' `beforeAll` can run AFTER a test file's top-level imports
+ *   execute destructive module-level code. globalSetup runs strictly before
+ *   ANY test file is loaded. Combined with the `npm test` process-level HOME
+ *   override, there is zero window in which code can see real HOME.
+ *
+ * The process-level HOME override in package.json is the primary isolation
+ * layer; this module is the second-line tripwire that catches regressions.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+
+/** Vitest globalSetup default export. Returns a teardown function. */
+export default function setup() {
+  const currentHome = process.env.HOME ?? "";
+  const realHome = os.userInfo().homedir;
+
+  if (!currentHome) {
+    throw new Error(
+      "[test-isolation] process.env.HOME is empty. " +
+        "Run tests via `npm test` (which sets HOME to a tmp dir) " +
+        "or prefix manually: `HOME=$(mktemp -d) npx vitest run`.",
+    );
+  }
+
+  if (currentHome === realHome) {
+    throw new Error(
+      `[test-isolation] process.env.HOME (${currentHome}) equals the real user home ` +
+        `(${realHome}). This would let tests read and mutate ~/.pi/, potentially killing ` +
+        `live pi sessions. Run tests via \`npm test\` — it sets HOME to an ephemeral tmp dir. ` +
+        `If you invoked vitest directly, prefix with \`HOME=$(mktemp -d)\`.`,
+    );
+  }
+
+  if (!currentHome.startsWith(os.tmpdir())) {
+    // Not strictly fatal — developer may have pointed HOME at a custom scratch dir —
+    // but warn loudly because it's unusual.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[test-isolation] HOME (${currentHome}) is not under os.tmpdir() (${os.tmpdir()}). ` +
+        `Tests will still run but this layout is unusual.`,
+    );
+  }
+
+  // Pre-create expected .pi subdirectories so code that reads them finds empty dirs.
+  mkdirSync(join(currentHome, ".pi", "agent", "sessions"), { recursive: true });
+  mkdirSync(join(currentHome, ".pi", "dashboard"), { recursive: true });
+
+  // eslint-disable-next-line no-console
+  console.log(`[test-isolation] HOME=${currentHome} (real=${realHome})`);
+
+  // Teardown: nothing to do. The tmp HOME was created by the npm script's
+  // `$(mktemp -d)`; leaving the dir on disk is fine (OS cleans tmpdir).
+  // Tests that need per-file isolation continue to use their own mkdtemp.
+  return () => {
+    /* no-op */
+  };
+}

package/packages/shared/src/tool-registry/definitions.ts

@@ -0,0 +1,342 @@
+/**
+ * Registered tool definitions.
+ *
+ * Each definition declares an ordered strategy chain. Individual
+ * strategies are responsible for validating their own resolved paths
+ * (they use the injected `exists` from StrategyDeps), so tests can
+ * inject fakes without triggering real `fs.existsSync` lookups.
+ *
+ * See change: consolidate-tool-resolution.
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import type { ToolDefinition, Source } from "./types.js";
+import type { ToolRegistry } from "./registry.js";
+import {
+  type StrategyDeps,
+  bareImportStrategy,
+  managedBinStrategy,
+  managedModuleStrategy,
+  npmGlobalStrategy,
+  overrideStrategy,
+  whereStrategy,
+} from "./strategies.js";
+
+// ── Classifier ──────────────────────────────────────────────────────────────
+
+/** Classifier: strategies → Source. Shared across binary and module tools. */
+function classify(strategyName: string): Source {
+  if (strategyName === "override") return "override";
+  if (strategyName === "managed") return "managed";
+  if (strategyName === "npm-global") return "npm-global";
+  if (strategyName === "bare-import") return "bare-import";
+  // `where` and anything else — resolved via PATH — classifies as system.
+  return "system";
+}
+
+// ── Binary definitions ──────────────────────────────────────────────────────
+
+function binaryDef(binaryName: string, deps?: StrategyDeps): ToolDefinition {
+  return {
+    name: binaryName,
+    kind: "binary",
+    strategies: [
+      overrideStrategy(binaryName, deps),
+      managedBinStrategy(binaryName, deps),
+      whereStrategy(binaryName, deps),
+    ],
+    classify,
+  };
+}
+
+// ── Module definitions ──────────────────────────────────────────────────────
+
+/** Sibling probe for an aliased package name (pi: `@mariozechner/*` + `@oh-my-pi/*`). */
+function moduleDefWithAliases(
+  canonicalName: string,
+  pkgNames: readonly string[],
+  entry: string,
+  deps?: StrategyDeps,
+): ToolDefinition {
+  const strategies = [overrideStrategy(canonicalName, deps)];
+  for (const pkg of pkgNames) strategies.push(bareImportStrategy(pkg));
+  for (const pkg of pkgNames) strategies.push(managedModuleStrategy(pkg, entry, deps));
+  for (const pkg of pkgNames) strategies.push(npmGlobalStrategy(pkg, entry, deps));
+  return { name: canonicalName, kind: "module", strategies, classify };
+}
+
+// ── Registration ─────────────────────────────────────────────────
+
+// Tools intentionally NOT registered:
+//   - `tsx` — a TypeScript *loader* used via `node --import tsx`,
+//     not a tool the dashboard spawns. When pi is installed, pi ships
+//     jiti which the server prefers; otherwise tsx is co-installed
+//     as a dev dep of the server package.
+//   - `pi-dashboard` — that's the package this code is part of.
+//     "Is it installed" is a bootstrap concern handled directly in
+//     `packages/electron/src/lib/dependency-detector.ts`.
+// See change: consolidate-tool-resolution (follow-up).
+
+/**
+ * Shared `toArgv` for Node-script executors (pi, openspec, npm).
+ *
+ * On Windows + `.js` resolved path → prepend node.exe to bypass the
+ * `.cmd` shim entirely (no cmd.exe in the spawn chain → no console
+ * flash). Elsewhere → direct invocation.
+ *
+ * This is the heart of the "no cmd flash" story: every CLI that ships
+ * as `.cmd` on Windows and is actually a Node script should be
+ * registered with this `toArgv` so the spawn becomes
+ * `node.exe <script.js>` (pure console-subsystem inherit, no new
+ * window ever).
+ */
+const nodeScriptToArgv: ToolDefinition["toArgv"] = (resolvedPath, { platform, registry }) => {
+  if (platform === "win32" && /\.js$/i.test(resolvedPath)) {
+    const node = registry.resolve("node");
+    if (node.ok && node.path) return [node.path, resolvedPath];
+  }
+  return [resolvedPath];
+};
+
+/**
+ * Executor definition for `pi` — ONE tool, OS dispatch inside.
+ *
+ * On Windows, the strategy chain finds pi-coding-agent's `dist/cli.js`
+ * (managed → bare-import → npm-global), and `toArgv` wraps it with
+ * `node.exe` to produce `[node.exe, cli.js]`. Falls back to `pi.cmd`
+ * on PATH when the cli.js is nowhere to be found.
+ *
+ * On Unix, the chain finds `pi` on PATH; argv = [pi].
+ */
+function piExecutorDef(deps?: StrategyDeps): ToolDefinition {
+  const piPkgAliases = ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"];
+  const cliEntry = path.join("dist", "cli.js");
+
+  const winStrategies = [
+    overrideStrategy("pi", deps),
+    ...piPkgAliases.map((pkg) => bareImportCliStrategy(pkg, cliEntry, deps)),
+    ...piPkgAliases.map((pkg) => managedModuleStrategy(pkg, cliEntry, deps)),
+    ...piPkgAliases.map((pkg) => npmGlobalStrategy(pkg, cliEntry, deps)),
+    managedBinStrategy("pi", deps),
+    whereStrategy("pi", deps),
+  ];
+
+  const unixStrategies = [
+    overrideStrategy("pi", deps),
+    managedBinStrategy("pi", deps),
+    whereStrategy("pi", deps),
+  ];
+
+  return {
+    name: "pi",
+    kind: "executor",
+    strategies: unixStrategies,
+    platformStrategies: { win32: winStrategies },
+    toArgv: nodeScriptToArgv,
+    classify,
+  };
+}
+
+/**
+ * Executor definition for `openspec`.
+ *
+ * On Windows: finds `@fission-ai/openspec/bin/openspec.js` via managed
+ * → bare-import → npm-global. `toArgv` wraps with node.exe.
+ * On Unix: finds `openspec` binary on PATH.
+ */
+function openspecExecutorDef(deps?: StrategyDeps): ToolDefinition {
+  const pkgName = "@fission-ai/openspec";
+  const cliEntry = path.join("bin", "openspec.js");
+
+  const winStrategies = [
+    overrideStrategy("openspec", deps),
+    bareImportCliStrategy(pkgName, cliEntry),
+    managedModuleStrategy(pkgName, cliEntry, deps),
+    npmGlobalStrategy(pkgName, cliEntry, deps),
+    managedBinStrategy("openspec", deps),
+    whereStrategy("openspec", deps),
+  ];
+
+  const unixStrategies = [
+    overrideStrategy("openspec", deps),
+    managedBinStrategy("openspec", deps),
+    whereStrategy("openspec", deps),
+  ];
+
+  return {
+    name: "openspec",
+    kind: "executor",
+    strategies: unixStrategies,
+    platformStrategies: { win32: winStrategies },
+    toArgv: nodeScriptToArgv,
+    classify,
+  };
+}
+
+/**
+ * Executor definition for `npm`.
+ *
+ * npm is bundled with Node itself, not a standalone npm install. On
+ * Windows: find `<node-dir>/node_modules/npm/bin/npm-cli.js` by
+ * looking beside the resolved `node.exe`. Fallback: PATH lookup
+ * (which returns npm.cmd).
+ * On Unix: find `npm` on PATH.
+ *
+ * Motivation: npm.cmd internally runs `node.exe npm-cli.js`, and the
+ * inner node.exe can allocate a new console (Node issue #21825). By
+ * resolving to npm-cli.js directly + spawning via node.exe ourselves,
+ * we bypass cmd.exe + npm.cmd entirely.
+ */
+function npmExecutorDef(deps?: StrategyDeps): ToolDefinition {
+  const npmRelativeToNode = path.join("node_modules", "npm", "bin", "npm-cli.js");
+
+  // Custom strategy: find npm-cli.js beside the resolved node.exe.
+  // We can't pre-compute the node path at definition time (the registry
+  // isn't fully constructed yet), so the strategy resolves node
+  // lazily at run time via the global registry hook.
+  const npmCliBesideNodeStrategy = {
+    name: "managed", // classified as managed because it ships with node
+    run(): { ok: true; path: string } | { ok: false; reason: string } {
+      // Find node.exe from process.execPath or environment.
+      const nodeExe = process.execPath;
+      if (!nodeExe) return { ok: false, reason: "process.execPath unset" };
+      const nodeDir = path.dirname(nodeExe);
+      const candidate = path.join(nodeDir, npmRelativeToNode);
+      try {
+        if (existsSync(candidate)) return { ok: true, path: candidate };
+        return { ok: false, reason: `missing: ${candidate}` };
+      } catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+
+  const winStrategies = [
+    overrideStrategy("npm", deps),
+    npmCliBesideNodeStrategy,
+    whereStrategy("npm", deps),
+  ];
+
+  const unixStrategies = [
+    overrideStrategy("npm", deps),
+    whereStrategy("npm", deps),
+  ];
+
+  return {
+    name: "npm",
+    kind: "executor",
+    strategies: unixStrategies,
+    platformStrategies: { win32: winStrategies },
+    toArgv: nodeScriptToArgv,
+    classify,
+  };
+}
+
+/**
+ * Helper: bare-import strategy that, on success, transforms the
+ * resolved `package.json` into the sibling `<entry>` path. Used by
+ * the pi executor to find pi-coding-agent's cli.js via the same
+ * module-resolution algorithm as `import()`.
+ */
+function bareImportCliStrategy(
+  pkgName: string,
+  entryRelative: string,
+  deps?: StrategyDeps,
+) {
+  // Default uses the real module resolver anchored to this file;
+  // tests inject a fake via deps.resolveModule.
+  const resolveModule: NonNullable<StrategyDeps["resolveModule"]> =
+    deps?.resolveModule
+    ?? ((id, from) => {
+      try {
+        return createRequire(from).resolve(id);
+      } catch {
+        return null;
+      }
+    });
+  return {
+    name: "bare-import",
+    run(): { ok: true; path: string } | { ok: false; reason: string } {
+      const pkgJson = resolveModule(`${pkgName}/package.json`, import.meta.url);
+      if (!pkgJson) {
+        return { ok: false, reason: `cannot resolve ${pkgName}/package.json` };
+      }
+      const entry = path.join(path.dirname(pkgJson), entryRelative);
+      return { ok: true, path: entry };
+    },
+  };
+}
+
+/**
+ * Register the standard set of dashboard tools. Idempotent — callers
+ * may re-register to supply custom strategy deps (e.g. tests).
+ */
+export function registerDefaultTools(registry: ToolRegistry, deps?: StrategyDeps): void {
+  // Executor-kind tools — Node scripts shipped as .cmd shims on
+  // Windows. Each registers as [node.exe, <script>.js] to bypass
+  // cmd.exe and the console-flash chain (Node issue #21825).
+  registry.register(piExecutorDef(deps));
+  registry.register(openspecExecutorDef(deps));
+  registry.register(npmExecutorDef(deps));
+
+  // Native binaries — no interpreter needed.
+  registry.register(binaryDef("node", deps));
+  registry.register(binaryDef("git", deps));
+  registry.register(binaryDef("zrok", deps));
+
+  // Platform-conditional process-inspection utilities. These are only
+  // called by `packages/shared/src/platform/process.ts` on their native
+  // platform — registering the non-native tools would surface as red
+  // "not found" rows in the Settings → Tools UI even though the code
+  // never calls them there.
+  //
+  // Honours the registry's `platform` so tests that inject `platform:
+  // "win32"` from a Linux host still exercise the Windows tool set.
+  //
+  // Windows system utilities used by the bridge's process scanner.
+  // Registered so callers resolve to full `.exe` paths (e.g.
+  // `C:\Windows\System32\wbem\wmic.exe`) and spawn directly — no
+  // PATHEXT resolution, no cmd.exe wrapping, windowsHide:true honored
+  // all the way down. See change: consolidate-windows-spawn-and-platform-handlers.
+  if (registry.getPlatform() === "win32") {
+    registry.register(binaryDef("wmic", deps));
+    registry.register(binaryDef("powershell", deps));
+    registry.register(binaryDef("tasklist", deps));
+    registry.register(binaryDef("taskkill", deps));
+  } else {
+    // POSIX process-inspection utilities. Used by `isProcessRunning`,
+    // `findPidByMarker`, `isProcessLikePi` in platform/process.ts.
+    registry.register(binaryDef("ps", deps));
+    registry.register(binaryDef("pgrep", deps));
+  }
+  // Windows Terminal — optional, override + where only (not part of
+  // managed install, not on Unix).
+  registry.register({
+    name: "wt",
+    kind: "binary",
+    strategies: [
+      overrideStrategy("wt", deps),
+      whereStrategy("wt", deps),
+    ],
+    classify,
+  });
+
+  // Node module entry for pi-coding-agent — used by DefaultPackageManager
+  // to IMPORT pi as a library (not spawn it as a process). Distinct from
+  // the `pi` executor above.
+  registry.register(
+    moduleDefWithAliases(
+      "pi-coding-agent",
+      ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"],
+      path.join("dist", "index.js"),
+      deps,
+    ),
+  );
+}
+
+/** Handy re-exports for callers that want raw definitions for testing. */
+export const _internals = {
+  binaryDef,
+  moduleDefWithAliases,
+};

package/packages/shared/src/tool-registry/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Tool registry — single-source resolver for every external binary/module
+ * the dashboard depends on. See change: consolidate-tool-resolution.
+ *
+ * Quick start:
+ *
+ *   import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry";
+ *   const r = getDefaultRegistry().resolve("pi");
+ *   if (r.ok) spawn(r.path!, args);
+ */
+export * from "./types.js";
+export { OverridesStore, defaultOverridesPath } from "./overrides.js";
+export { ToolRegistry } from "./registry.js";
+export { registerDefaultTools } from "./definitions.js";
+export * from "./strategies.js";
+
+import { ToolRegistry } from "./registry.js";
+import { registerDefaultTools } from "./definitions.js";
+
+/**
+ * Lazily-constructed process-wide registry. Most callers should use this
+ * instead of constructing their own. Tests should pass a fresh
+ * `new ToolRegistry({...})` with injected deps.
+ *
+ * The registry is also published on `globalThis` under a symbol so that
+ * `platform/runner.ts` can pick it up synchronously without a module
+ * import (which would create a load-order cycle through `platform/npm.ts`).
+ */
+const GLOBAL_KEY = Symbol.for("pi-dashboard.tool-registry");
+type GlobalSlot = { [GLOBAL_KEY]?: ToolRegistry };
+
+let defaultRegistry: ToolRegistry | null = null;
+export function getDefaultRegistry(): ToolRegistry {
+  if (!defaultRegistry) {
+    defaultRegistry = new ToolRegistry();
+    registerDefaultTools(defaultRegistry);
+    (globalThis as unknown as GlobalSlot)[GLOBAL_KEY] = defaultRegistry;
+  }
+  return defaultRegistry;
+}
+
+/**
+ * Global accessor for consumers that cannot import this module at the
+ * top level (i.e. `platform/runner.ts`, which is part of a load-order
+ * cycle). Returns `null` if `getDefaultRegistry()` hasn't been called
+ * yet anywhere in the process.
+ */
+export function peekGlobalRegistry(): ToolRegistry | null {
+  return (globalThis as unknown as GlobalSlot)[GLOBAL_KEY] ?? null;
+}
+
+/** Test-only: drop the process-wide registry so the next call rebuilds. */
+export function _resetDefaultRegistry(): void {
+  defaultRegistry = null;
+  (globalThis as unknown as GlobalSlot)[GLOBAL_KEY] = undefined;
+}

package/packages/shared/src/tool-registry/overrides.ts

@@ -0,0 +1,118 @@
+/**
+ * Persistent per-tool path overrides at `~/.pi/dashboard/tool-overrides.json`.
+ *
+ * Schema:
+ *   { "version": 1, "overrides": { "<toolName>": { "path": "<abs>" } } }
+ *
+ * Design notes (see change: consolidate-tool-resolution, design §5):
+ *   - Separate from `config.json` — path overrides are machine-local and
+ *     should NOT follow a user's dotfiles across machines.
+ *   - Atomic write via the same tmp+rename pattern used by
+ *     `server/src/json-store.ts` (duplicated here to keep `shared`
+ *     self-contained; the two live in different packages).
+ *   - Malformed files are treated as empty. No throw, no crash.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/** Path to the overrides file. Exposed for tests and the settings UI. */
+export function defaultOverridesPath(): string {
+  return path.join(os.homedir(), ".pi", "dashboard", "tool-overrides.json");
+}
+
+/** Internal shape persisted to disk. `version` lets us evolve later. */
+interface OverridesFile {
+  version: 1;
+  overrides: Record<string, { path: string }>;
+}
+
+export interface OverridesStoreDeps {
+  filePath?: string;
+  /** Logger hook (defaults to console.warn). Tests inject a sink. */
+  warn?(message: string): void;
+}
+
+/**
+ * Read-through + write-through in-memory store. One instance per registry.
+ * Keeps the disk read lazy — the file is only touched on first access.
+ */
+export class OverridesStore {
+  private readonly filePath: string;
+  private readonly warn: (message: string) => void;
+  private cache: Record<string, string> | null = null;
+
+  constructor(deps: OverridesStoreDeps = {}) {
+    this.filePath = deps.filePath ?? defaultOverridesPath();
+    this.warn = deps.warn ?? ((m) => console.warn(`[tool-registry] ${m}`));
+  }
+
+  /** Snapshot of current overrides. Lazy-loads from disk on first call. */
+  list(): Readonly<Record<string, string>> {
+    if (this.cache === null) this.cache = this.load();
+    return this.cache;
+  }
+
+  /** Set one override + persist. */
+  set(name: string, overridePath: string): void {
+    const current = this.cache ?? this.load();
+    current[name] = overridePath;
+    this.cache = current;
+    this.persist(current);
+  }
+
+  /** Remove one override + persist. No-op if absent. */
+  clear(name: string): void {
+    const current = this.cache ?? this.load();
+    if (!(name in current)) return;
+    delete current[name];
+    this.cache = current;
+    this.persist(current);
+  }
+
+  /** Drop the in-memory cache; next `list()` re-reads the file. */
+  invalidate(): void {
+    this.cache = null;
+  }
+
+  // ── Internal ─────────────────────────────────────────────────────────
+
+  private load(): Record<string, string> {
+    try {
+      if (!fs.existsSync(this.filePath)) return {};
+      const raw = fs.readFileSync(this.filePath, "utf-8");
+      if (!raw.trim()) return {};
+      const parsed = JSON.parse(raw) as Partial<OverridesFile>;
+      if (!parsed || typeof parsed !== "object" || !parsed.overrides) {
+        this.warn(`malformed overrides file at ${this.filePath}; ignoring`);
+        return {};
+      }
+      const out: Record<string, string> = {};
+      for (const [name, entry] of Object.entries(parsed.overrides)) {
+        if (entry && typeof entry === "object" && typeof (entry as { path?: unknown }).path === "string") {
+          out[name] = (entry as { path: string }).path;
+        }
+      }
+      return out;
+    } catch (err) {
+      this.warn(
+        `failed to read overrides file at ${this.filePath}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return {};
+    }
+  }
+
+  private persist(overrides: Record<string, string>): void {
+    const dir = path.dirname(this.filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const data: OverridesFile = {
+      version: 1,
+      overrides: Object.fromEntries(
+        Object.entries(overrides).map(([k, v]) => [k, { path: v }]),
+      ),
+    };
+    const tmpPath = this.filePath + ".tmp";
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
+    fs.renameSync(tmpPath, this.filePath);
+  }
+}