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

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

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

@@ -0,0 +1,262 @@
+/**
+ * ToolRegistry — single-source resolver for every external binary, module,
+ * and directory the dashboard depends on.
+ *
+ * Design (see change: consolidate-tool-resolution, design §1-§4):
+ *   - Ordered strategy chain per tool (override → managed → bare-import →
+ *     npm-global → where).
+ *   - One Resolution record per tool, cached in the registry.
+ *   - Rescan invalidates one or all cached Resolutions.
+ *   - Module resolution dynamically imports the resolved entry and caches
+ *     the loaded ES module alongside the Resolution.
+ */
+import { pathToFileURL } from "node:url";
+import {
+  type ExecutorResolution,
+  ModuleResolutionError,
+  type Resolution,
+  type Source,
+  type StrategyCtx,
+  type ToolDefinition,
+  UnknownToolError,
+  type TriedEntry,
+} from "./types.js";
+import { OverridesStore } from "./overrides.js";
+
+/**
+ * Minimal platform-environment snapshot injected into strategies.
+ * Production leaves this undefined and strategies fall back to
+ * `os.homedir()` / `process.cwd()`. Tests inject fakes so the bootstrap
+ * harness can reason about alternate HOME directories.
+ */
+export interface PlatformEnv {
+  homedir?: string;
+  cwd?: string;
+}
+
+export interface ToolRegistryDeps {
+  overrides?: OverridesStore;
+  platform?: NodeJS.Platform;
+  /** Injected for tests; default uses native dynamic `import(url)`. */
+  importModule?: (url: string) => Promise<unknown>;
+  /** Clock injector (used by tests for deterministic `resolvedAt`). */
+  now?: () => number;
+  /** Environment overrides threaded into `StrategyCtx.env` (see types.ts). */
+  env?: PlatformEnv;
+}
+
+/** Default strategy → source mapping when a definition doesn't override it. */
+const DEFAULT_CLASSIFY = (strategyName: string): Source => {
+  switch (strategyName) {
+    case "override":
+      return "override";
+    case "managed":
+      return "managed";
+    case "bare-import":
+      return "bare-import";
+    case "npm-global":
+      return "npm-global";
+    default:
+      return "system";
+  }
+};
+
+export class ToolRegistry {
+  private readonly definitions = new Map<string, ToolDefinition>();
+  private readonly cache = new Map<string, Resolution>();
+  private readonly moduleCache = new Map<string, unknown>();
+  private readonly overrides: OverridesStore;
+  private readonly platform: NodeJS.Platform;
+  private readonly importModule: (url: string) => Promise<unknown>;
+  private readonly now: () => number;
+  private readonly env: PlatformEnv | undefined;
+
+  constructor(deps: ToolRegistryDeps = {}) {
+    this.overrides = deps.overrides ?? new OverridesStore();
+    this.platform = deps.platform ?? process.platform;
+    this.importModule = deps.importModule ?? ((url) => import(/* @vite-ignore */ url));
+    this.now = deps.now ?? (() => Date.now());
+    this.env = deps.env;
+  }
+
+  /**
+   * Platform the registry was created for (or the current runtime's
+   * `process.platform`). Exposed so platform-conditional tool registration
+   * (e.g. skip `ps`/`pgrep` on Windows) in `registerDefaultTools` honours
+   * the test's injected platform instead of always reading the host.
+   */
+  getPlatform(): NodeJS.Platform {
+    return this.platform;
+  }
+
+  /** Register a tool definition. Last registration wins (tests re-register). */
+  register(def: ToolDefinition): void {
+    this.definitions.set(def.name, def);
+    this.cache.delete(def.name);
+    this.moduleCache.delete(def.name);
+  }
+
+  /** True when the name has a registered definition. */
+  has(name: string): boolean {
+    return this.definitions.has(name);
+  }
+
+  /** Snapshot of every registered tool's resolution. Triggers resolution as needed. */
+  list(): Resolution[] {
+    return Array.from(this.definitions.keys()).map((n) => this.resolve(n));
+  }
+
+  /** Resolve a binary/directory/module-path. Uses cached result when present. */
+  resolve(name: string): Resolution {
+    const def = this.definitions.get(name);
+    if (!def) throw new UnknownToolError(name);
+
+    const cached = this.cache.get(name);
+    if (cached) return cached;
+
+    const ctx: StrategyCtx = {
+      overrides: this.overrides.list(),
+      platform: this.platform,
+      env: this.env,
+    };
+
+    const tried: TriedEntry[] = [];
+    let winner: { strategy: string; path: string } | null = null;
+
+    // Platform-specific strategy chain overrides the default when
+    // present. Use case: tool resolution chain itself differs per OS
+    // (e.g. `pi` on Windows finds pi-coding-agent's cli.js; on Unix
+    // finds the `pi` binary on PATH).
+    const strategies = def.platformStrategies?.[this.platform] ?? def.strategies;
+
+    for (const strategy of strategies) {
+      const result = strategy.run(ctx);
+      if (!result.ok) {
+        tried.push({ strategy: strategy.name, result: result.reason });
+        continue;
+      }
+      // Optional validation (existence check, "must end in dist/index.js", ...).
+      if (def.validate) {
+        const v = def.validate(result.path);
+        if (!v.ok) {
+          tried.push({ strategy: strategy.name, result: `invalid: ${v.reason}` });
+          continue;
+        }
+      }
+      tried.push({ strategy: strategy.name, result: "ok" });
+      winner = { strategy: strategy.name, path: result.path };
+      break;
+    }
+
+    const classify = def.classify ?? DEFAULT_CLASSIFY;
+    const resolution: Resolution = winner
+      ? {
+          name,
+          ok: true,
+          path: winner.path,
+          source: classify(winner.strategy),
+          tried,
+          resolvedAt: this.now(),
+        }
+      : {
+          name,
+          ok: false,
+          path: null,
+          source: null,
+          tried,
+          resolvedAt: this.now(),
+        };
+
+    this.cache.set(name, resolution);
+    return resolution;
+  }
+
+  /**
+   * Resolve a tool and return its spawn-ready argv.
+   *
+   * Uses `resolve()` to find the artifact path, then applies the
+   * definition's `toArgv` transform (if any) to produce argv. Default:
+   * `argv = [path]` — appropriate for binary-kind tools resolved to an
+   * absolute path on PATH.
+   *
+   * For executor-kind tools with platform-specific interpreter needs
+   * (e.g. pi on Windows → `[node.exe, cli.js]`), `toArgv` does the
+   * assembly. `toArgv` may call `this.resolve(peer)` to find peer
+   * tools (e.g. `node`) and MUST fall back to `[path]` if peers are
+   * missing.
+   *
+   * Callers spawn via `spawn(argv[0], [...argv.slice(1), ...userArgs])`.
+   *
+   * See change: consolidate-windows-spawn-and-platform-handlers.
+   */
+  resolveExecutor(name: string): ExecutorResolution {
+    const def = this.definitions.get(name);
+    if (!def) throw new UnknownToolError(name);
+
+    const resolution = this.resolve(name);
+    if (!resolution.ok || !resolution.path) {
+      return { ...resolution, argv: [] };
+    }
+
+    const argv = def.toArgv
+      ? def.toArgv(resolution.path, { platform: this.platform, registry: this })
+      : [resolution.path];
+
+    return { ...resolution, argv };
+  }
+
+  /**
+   * Resolve AND dynamically import a registered module-kind tool.
+   * Throws `ModuleResolutionError` with the full `tried[]` trail when
+   * every strategy fails. The loaded ES module is cached alongside the
+   * Resolution; `rescan(name)` invalidates both.
+   */
+  async resolveModule<T = unknown>(name: string): Promise<{ resolution: Resolution; module: T }> {
+    const def = this.definitions.get(name);
+    if (!def) throw new UnknownToolError(name);
+    if (def.kind !== "module") {
+      throw new Error(`Tool "${name}" is not kind: "module"; use resolve() instead.`);
+    }
+
+    const resolution = this.resolve(name);
+    if (!resolution.ok || !resolution.path) {
+      throw new ModuleResolutionError(resolution);
+    }
+
+    const cached = this.moduleCache.get(name) as T | undefined;
+    if (cached) return { resolution, module: cached };
+
+    const url = pathToFileURL(resolution.path).href;
+    const loaded = (await this.importModule(url)) as T;
+    this.moduleCache.set(name, loaded);
+    return { resolution, module: loaded };
+  }
+
+  /** Drop cached Resolution(s). Next resolve() re-runs strategies. */
+  rescan(name?: string): void {
+    if (name === undefined) {
+      this.cache.clear();
+      this.moduleCache.clear();
+      this.overrides.invalidate();
+      return;
+    }
+    this.cache.delete(name);
+    this.moduleCache.delete(name);
+  }
+
+  /** Set a path override. Invalidates the target's cache. */
+  setOverride(name: string, overridePath: string): void {
+    if (!this.definitions.has(name)) throw new UnknownToolError(name);
+    this.overrides.set(name, overridePath);
+    this.cache.delete(name);
+    this.moduleCache.delete(name);
+  }
+
+  /** Clear a path override. Invalidates the target's cache. */
+  clearOverride(name: string): void {
+    if (!this.definitions.has(name)) throw new UnknownToolError(name);
+    this.overrides.clear(name);
+    this.cache.delete(name);
+    this.moduleCache.delete(name);
+  }
+}

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

@@ -0,0 +1,198 @@
+/**
+ * Reusable resolution strategies shared across tool definitions.
+ *
+ * Strategies are pure functions over their `StrategyCtx` — filesystem
+ * access (`existsSync`) is the only side effect. They never spawn; PATH
+ * search delegates to `ToolResolver.which()` which is injectable for
+ * tests via the `lookup` parameter.
+ *
+ * See change: consolidate-tool-resolution (design §2).
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { ToolResolver } from "../platform/binary-lookup.js";
+import { getManagedBin, getManagedDir } from "../managed-paths.js";
+import * as npm from "../platform/npm.js";
+import type { Strategy, StrategyCtx, StrategyResult } from "./types.js";
+
+/**
+ * Injectable surfaces used by strategies.
+ *
+ * - `exists` — fs existence probe (memfs in tests).
+ * - `which` — PATH search.
+ * - `npmRootGlobal` — result of `npm root -g` (tests inject to avoid spawn).
+ * - `resolveModule` — node-module resolution (id, from) → absolute path.
+ *   Production uses `createRequire(from).resolve(id)`; tests walk fake
+ *   node_modules trees.
+ */
+export interface StrategyDeps {
+  exists?(p: string): boolean;
+  which?(name: string): string | null;
+  npmRootGlobal?(): string;
+  resolveModule?(id: string, from: string): string | null;
+}
+
+function defaultResolveModule(id: string, from: string): string | null {
+  try {
+    return createRequire(from).resolve(id);
+  } catch {
+    return null;
+  }
+}
+
+function defaults(): Required<StrategyDeps> {
+  const resolver = new ToolResolver({
+    processExecPath: process.execPath,
+    useLoginShell: true,
+  });
+  return {
+    exists: existsSync,
+    which: (name) => resolver.which(name),
+    npmRootGlobal: () => npm.rootGlobalOr(""),
+    resolveModule: defaultResolveModule,
+  };
+}
+
+/** Merge caller-supplied deps over the live defaults. */
+function d(deps?: StrategyDeps): Required<StrategyDeps> {
+  const base = defaults();
+  if (!deps) return base;
+  return {
+    exists: deps.exists ?? base.exists,
+    which: deps.which ?? base.which,
+    npmRootGlobal: deps.npmRootGlobal ?? base.npmRootGlobal,
+    resolveModule: deps.resolveModule ?? base.resolveModule,
+  };
+}
+
+// ── Strategies ──────────────────────────────────────────────────────────────
+
+/**
+ * Look up a registered path override by tool name. Existence is checked
+ * here so invalid overrides fall through with reason `invalid: <...>`
+ * without requiring callers to wire a separate validator.
+ */
+export function overrideStrategy(toolName: string, deps?: StrategyDeps): Strategy {
+  const { exists } = d(deps);
+  return {
+    name: "override",
+    run(ctx): StrategyResult {
+      const p = ctx.overrides[toolName];
+      if (!p) return { ok: false, reason: "no override set" };
+      if (!exists(p)) return { ok: false, reason: `invalid: path does not exist: ${p}` };
+      return { ok: true, path: p };
+    },
+  };
+}
+
+/**
+ * Managed install: `~/.pi-dashboard/node_modules/.bin/<name>(.cmd)` for
+ * binaries, or any explicit relative path under `MANAGED_DIR` for
+ * modules/directories.
+ */
+export function managedBinStrategy(
+  binaryName: string,
+  deps?: StrategyDeps,
+): Strategy {
+  const { exists } = d(deps);
+  return {
+    name: "managed",
+    run(ctx): StrategyResult {
+      const ext = ctx.platform === "win32" ? ".cmd" : "";
+      const candidate = path.join(getManagedBin(ctx.env), binaryName + ext);
+      if (exists(candidate)) return { ok: true, path: candidate };
+      return { ok: false, reason: `missing: ${candidate}` };
+    },
+  };
+}
+
+/**
+ * Managed module entry: `~/.pi-dashboard/node_modules/<pkg>/dist/index.js`
+ * (or a caller-specified relative entry).
+ */
+export function managedModuleStrategy(
+  pkgName: string,
+  entryRelative: string = path.join("dist", "index.js"),
+  deps?: StrategyDeps,
+): Strategy {
+  const { exists } = d(deps);
+  return {
+    name: "managed",
+    run(ctx: StrategyCtx): StrategyResult {
+      const candidate = path.join(getManagedDir(ctx.env), "node_modules", pkgName, entryRelative);
+      if (exists(candidate)) return { ok: true, path: candidate };
+      return { ok: false, reason: `missing: ${candidate}` };
+    },
+  };
+}
+
+/**
+ * Global npm install: `<npm root -g>/<pkg>/<entry>`. Falls back to
+ * `{ ok: false }` when `npm root -g` fails or the file is absent.
+ */
+export function npmGlobalStrategy(
+  pkgName: string,
+  entryRelative: string = path.join("dist", "index.js"),
+  deps?: StrategyDeps,
+): Strategy {
+  const { exists, npmRootGlobal } = d(deps);
+  return {
+    name: "npm-global",
+    run(): StrategyResult {
+      const root = npmRootGlobal();
+      if (!root) return { ok: false, reason: "npm root -g failed" };
+      const candidate = path.join(root, pkgName, entryRelative);
+      if (exists(candidate)) return { ok: true, path: candidate };
+      return { ok: false, reason: `missing: ${candidate}` };
+    },
+  };
+}
+
+/**
+ * PATH search via `ToolResolver.which()`. This is the plain-old "is it
+ * on PATH" strategy and should appear last in most chains.
+ */
+export function whereStrategy(binaryName: string, deps?: StrategyDeps): Strategy {
+  const { which } = d(deps);
+  return {
+    name: "where",
+    run(): StrategyResult {
+      const p = which(binaryName);
+      if (p) return { ok: true, path: p };
+      return { ok: false, reason: `not found on PATH` };
+    },
+  };
+}
+
+/**
+ * Bare `import("<pkg>")` — succeeds when the package is reachable from
+ * the caller's node_modules tree. We probe synchronously via
+ * `createRequire(import.meta.url).resolve(pkgName)`, which follows the
+ * same module-resolution algorithm as `import()` but returns a path.
+ *
+ * The returned path is the resolved entry file; `resolveModule()` then
+ * dynamically imports it via `pathToFileURL`. This keeps strategies
+ * uniformly sync and keeps the diagnostic trail honest (if the package
+ * isn't resolvable, we record the reason here instead of letting it
+ * surface as an opaque `import()` throw later).
+ *
+ * `anchor` determines which node_modules tree we search. Default is
+ * this file's URL (i.e. the shared package) — which is typically what
+ * callers want: "is pi a dependency of the dashboard?"
+ */
+export function bareImportStrategy(
+  pkgName: string,
+  anchor: string = import.meta.url,
+  deps?: StrategyDeps,
+): Strategy {
+  const { resolveModule } = d(deps);
+  return {
+    name: "bare-import",
+    run(): StrategyResult {
+      const resolved = resolveModule(pkgName, anchor);
+      if (!resolved) return { ok: false, reason: `cannot resolve ${pkgName} from ${anchor}` };
+      return { ok: true, path: resolved };
+    },
+  };
+}