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

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

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

@@ -0,0 +1,180 @@
+/**
+ * Public type contract for the tool registry.
+ *
+ * The registry resolves every external binary, module, or directory the
+ * dashboard depends on through an ordered list of strategies. Each
+ * resolution records a diagnostic trail (what was tried + why it
+ * succeeded/failed) alongside the winning path.
+ *
+ * See change: consolidate-tool-resolution.
+ */
+
+/** What kind of artifact a tool definition resolves. */
+export type ToolKind = "binary" | "module" | "directory" | "executor";
+
+/**
+ * How a resolved path was obtained. Strategy name → source mapping is
+ * declared by each tool definition's `classify()` (see registry).
+ */
+export type Source =
+  | "override"
+  | "managed"
+  | "system"
+  | "npm-global"
+  | "bare-import";
+
+/** Result returned by a single strategy attempt. */
+export type StrategyResult =
+  | { ok: true; path: string }
+  | { ok: false; reason: string };
+
+/** One attempt recorded on a Resolution's `tried[]` list. */
+export interface TriedEntry {
+  /** Strategy name, e.g. "override", "managed", "npm-global". */
+  strategy: string;
+  /** "ok" on success, the strategy's failure reason on miss. */
+  result: "ok" | string;
+}
+
+/** Output of `ToolRegistry.resolve(name)`. */
+export interface Resolution {
+  /** Tool name as registered. */
+  name: string;
+  /** True if any strategy produced a valid path. */
+  ok: boolean;
+  /** Absolute path (binary / module entry / directory). Null on failure. */
+  path: string | null;
+  /** Source classification of the winning strategy. Null on failure. */
+  source: Source | null;
+  /** Ordered diagnostic trail — one entry per attempted strategy. */
+  tried: TriedEntry[];
+  /** Epoch ms when resolution completed. */
+  resolvedAt: number;
+}
+
+/**
+ * Output of `ToolRegistry.resolveExecutor(name)` — extends Resolution
+ * with `argv`, the ready-to-spawn command array.
+ *
+ * Callers spawn via `spawn(argv[0], [...argv.slice(1), ...userArgs])`.
+ * For simple binaries `argv = [path]`; for scripts that need an
+ * interpreter (e.g. pi's `node dist/cli.js` on Windows) `argv =
+ * [interpreter, scriptPath]`.
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+export interface ExecutorResolution extends Resolution {
+  argv: string[];
+}
+
+/** Context passed to every strategy function. */
+export interface StrategyCtx {
+  /** Per-registry override map, { [toolName]: absolutePath }. */
+  overrides: Readonly<Record<string, string>>;
+  /** Platform discriminator (injectable for tests). */
+  platform: NodeJS.Platform;
+  /**
+   * Environment overrides used by HOME-sensitive strategies (managed/*,
+   * npm-global under APPDATA on win32, etc.). Production registries
+   * populate from `os.homedir()` + `process.cwd()`; tests inject fakes
+   * so the harness can reason about alternate HOME directories without
+   * mutating globals.
+   */
+  env?: {
+    homedir?: string;
+    cwd?: string;
+  };
+}
+
+/** A single resolution strategy. Pure function of its ctx + the tool's data. */
+export interface Strategy {
+  /** Name recorded in `tried[]`. */
+  name: string;
+  /** Attempt resolution. Never throws — signal failure via { ok: false }. */
+  run(ctx: StrategyCtx): StrategyResult;
+}
+
+/**
+ * Transform a successfully-resolved path into an argv ready to pass
+ * to `spawn(argv[0], argv.slice(1))`.
+ *
+ * Default behaviour (when a definition omits `toArgv`): `argv = [path]`.
+ * Scripts that need an interpreter (e.g. pi's `cli.js` on Windows)
+ * return `[interpreterPath, scriptPath]`.
+ *
+ * The function may call `registry.resolve(...)` to look up peer tools
+ * (e.g. `node`). It MUST NOT throw — return the path-only fallback
+ * `[path]` if a peer tool is missing.
+ */
+export type ToArgvFn = (resolvedPath: string, ctx: { platform: NodeJS.Platform; registry: ToolRegistryLike }) => string[];
+
+/** Minimal interface used by `toArgv` functions to look up peer tools. */
+export interface ToolRegistryLike {
+  resolve(name: string): Resolution;
+}
+
+/** Declarative tool registration. */
+export interface ToolDefinition {
+  /** Registry key — unique within the registry. */
+  name: string;
+  /** Kind drives how `resolveModule()` / path validation behaves. */
+  kind: ToolKind;
+  /**
+   * Ordered strategies used when no platform-specific override exists
+   * for the current OS. First successful strategy wins.
+   */
+  strategies: Strategy[];
+  /**
+   * Optional per-platform strategy override. Present key wins over
+   * `strategies`. Absent key falls back to `strategies`.
+   *
+   * Use this when the chain itself is OS-dependent — e.g. pi on
+   * Windows looks for a JS entry (dist/cli.js via module strategies),
+   * while on Unix it looks for a `pi` binary on PATH.
+   */
+  platformStrategies?: Partial<Record<NodeJS.Platform, Strategy[]>>;
+  /**
+   * Optional transform from resolved path → ready-to-spawn argv.
+   * Used by `resolveExecutor(name)`. Omitted → argv defaults to `[path]`.
+   */
+  toArgv?: ToArgvFn;
+  /**
+   * Map a winning strategy name → Source. Unknown strategy names fall
+   * back to the default ("system"). Definitions usually set this so
+   * that e.g. "managed" → "managed", "bare-import" → "bare-import".
+   */
+  classify?(strategyName: string): Source;
+  /**
+   * Optional post-resolution validation (e.g. "dist/index.js exists").
+   * If provided and returns a reason, the strategy is demoted to a
+   * failure carrying that reason, and the next strategy is tried.
+   */
+  validate?(resolvedPath: string): { ok: true } | { ok: false; reason: string };
+}
+
+// ── Errors ──────────────────────────────────────────────────────────────────
+
+/** Thrown by `resolve()` / `resolveModule()` for unregistered names. */
+export class UnknownToolError extends Error {
+  public readonly tool: string;
+  constructor(tool: string) {
+    super(`Unknown tool: ${tool}`);
+    this.name = "UnknownToolError";
+    this.tool = tool;
+  }
+}
+
+/** Thrown by `resolveModule()` when every strategy fails. */
+export class ModuleResolutionError extends Error {
+  public readonly resolution: Resolution;
+  constructor(resolution: Resolution) {
+    const trail = resolution.tried
+      .map((t) => `  - ${t.strategy}: ${t.result}`)
+      .join("\n");
+    super(
+      `Could not resolve module "${resolution.name}". Tried:\n${trail}`,
+    );
+    this.name = "ModuleResolutionError";
+    this.resolution = resolution;
+  }
+}

package/packages/shared/src/types.ts

@@ -140,6 +140,13 @@ export interface OpenSpecChange {
   completedTasks: number;
   totalTasks: number;
   artifacts: OpenSpecArtifact[];
+  /**
+   * Artifact-authoring completeness reported by `openspec status --change <name> --json`.
+   * `true` when all required artifacts for the change's workflow are present/done.
+   * Orthogonal to task-tally completeness; used by the dashboard to surface an
+   * "Archive anyway" escape hatch when artifacts are authored but tasks remain unchecked.
+   */
+  isComplete?: boolean;
 }
 
 /** Lifecycle state of an OpenSpec change, derived from artifacts + task status */