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

package/packages/shared/src/platform/git.ts

@@ -0,0 +1,155 @@
+/**
+ * Git tool module — Recipe-based API for git operations the dashboard runs
+ * from multiple call sites (session-diff, git-info extension, doctor).
+ *
+ * Every function in this file is a thin wrapper over `run(recipe, input)`:
+ * no `child_process` imports, no `process.platform` branches, no inline
+ * shell-escape logic. The Recipe objects describe *what* git invocation
+ * to run; the runner handles *how* to spawn it safely.
+ *
+ * Exit codes:
+ *   `git diff`   exits 0 when there's a diff, 1 when there's nothing to
+ *                show (we tolerate 1).
+ *   Other commands exit 0 on success and non-zero on real errors.
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+// ── Recipes (pure data) ─────────────────────────────────────────────────────
+
+const GIT_TIMEOUT = 15_000;
+
+interface WithCwd {
+  cwd: string;
+}
+
+export const GIT_IS_REPO: Recipe<WithCwd, boolean> = {
+  argv: () => ["git", "rev-parse", "--is-inside-work-tree"],
+  parse: (out) => out.trim() === "true",
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_CURRENT_BRANCH: Recipe<WithCwd, string | undefined> = {
+  argv: () => ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+  parse: (out) => out.trim() || undefined,
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_HEAD_SHA: Recipe<WithCwd & { short?: boolean }, string | undefined> = {
+  argv: ({ short }) => short ? ["git", "rev-parse", "--short", "HEAD"] : ["git", "rev-parse", "HEAD"],
+  parse: (out) => out.trim() || undefined,
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_REMOTE_URL: Recipe<WithCwd & { remote?: string }, string | undefined> = {
+  argv: ({ remote }) => ["git", "remote", "get-url", remote ?? "origin"],
+  parse: (out) => out.trim() || undefined,
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_DIFF: Recipe<WithCwd & { path: string; ref?: string }, string> = {
+  argv: ({ path, ref }) => ["git", "diff", ref ?? "HEAD", "--", path],
+  parse: (out) => out,
+  timeout: GIT_TIMEOUT,
+  // git diff exits 1 when --exit-code is set or in some configurations;
+  // no diff is not an error for our callers.
+  tolerate: [1],
+};
+
+export const GIT_STATUS_PORCELAIN: Recipe<WithCwd & { path?: string }, string> = {
+  argv: ({ path }) =>
+    path === undefined
+      ? ["git", "status", "--porcelain"]
+      : ["git", "status", "--porcelain", "--", path],
+  parse: (out) => out,
+  timeout: GIT_TIMEOUT,
+};
+
+/**
+ * `gh pr view --json number -q .number` — requires the `gh` CLI.
+ * Returns undefined when there is no PR for the current branch (gh exits 1).
+ */
+export const GH_PR_NUMBER: Recipe<WithCwd, number | undefined> = {
+  argv: () => ["gh", "pr", "view", "--json", "number", "-q", ".number"],
+  parse: (out) => {
+    const n = parseInt(out.trim(), 10);
+    return Number.isFinite(n) ? n : undefined;
+  },
+  timeout: GIT_TIMEOUT,
+  tolerate: [1], // gh exits 1 when no PR exists — not an error
+};
+
+// ── Registry (for lint / docs / enumeration) ────────────────────────────────
+
+export const GIT_RECIPES = {
+  GIT_IS_REPO,
+  GIT_CURRENT_BRANCH,
+  GIT_HEAD_SHA,
+  GIT_REMOTE_URL,
+  GIT_DIFF,
+  GIT_STATUS_PORCELAIN,
+  GH_PR_NUMBER,
+} as const;
+
+// ── Public API — typed functions (use Result for explicit control) ──────────
+
+export function isGitRepo(input: WithCwd): Result<boolean> {
+  return run(GIT_IS_REPO, input, { cwd: input.cwd });
+}
+
+export function currentBranch(input: WithCwd): Result<string | undefined> {
+  return run(GIT_CURRENT_BRANCH, input, { cwd: input.cwd });
+}
+
+export function headSha(input: WithCwd & { short?: boolean }): Result<string | undefined> {
+  return run(GIT_HEAD_SHA, input, { cwd: input.cwd });
+}
+
+export function remoteUrl(input: WithCwd & { remote?: string }): Result<string | undefined> {
+  return run(GIT_REMOTE_URL, input, { cwd: input.cwd });
+}
+
+export function diff(input: WithCwd & { path: string; ref?: string }): Result<string> {
+  return run(GIT_DIFF, input, { cwd: input.cwd });
+}
+
+export function statusPorcelain(input: WithCwd & { path?: string }): Result<string> {
+  return run(GIT_STATUS_PORCELAIN, input, { cwd: input.cwd });
+}
+
+export function prNumber(input: WithCwd): Result<number | undefined> {
+  return run(GH_PR_NUMBER, input, { cwd: input.cwd });
+}
+
+// ── Best-effort convenience wrappers (swallow errors → default) ─────────────
+// Callers that only want "the value or a default" without dealing with Result
+// discriminants can use these instead.
+
+export function isGitRepoOr(input: WithCwd, fallback = false): boolean {
+  return unwrap(isGitRepo(input), fallback);
+}
+
+export function currentBranchOr(input: WithCwd, fallback?: string): string | undefined {
+  return unwrap(currentBranch(input), fallback);
+}
+
+export function headShaOr(input: WithCwd & { short?: boolean }, fallback?: string): string | undefined {
+  return unwrap(headSha(input), fallback);
+}
+
+export function remoteUrlOr(input: WithCwd & { remote?: string }, fallback?: string): string | undefined {
+  return unwrap(remoteUrl(input), fallback);
+}
+
+export function diffOr(input: WithCwd & { path: string; ref?: string }, fallback = ""): string {
+  return unwrap(diff(input), fallback);
+}
+
+export function statusPorcelainOr(input: WithCwd & { path?: string }, fallback = ""): string {
+  return unwrap(statusPorcelain(input), fallback);
+}
+
+export function prNumberOr(input: WithCwd, fallback?: number): number | undefined {
+  return unwrap(prNumber(input), fallback);
+}

package/packages/shared/src/platform/index.ts

@@ -0,0 +1,15 @@
+export * from "./binary-lookup.js";
+export * from "./process.js";
+export * from "./process-scan.js";
+export * from "./shell.js";
+export * from "./commands.js";
+export * from "./exec.js";
+export * from "./runner.js";
+export * from "./detached-spawn.js";
+export * from "./spawn-mechanism.js";
+export * from "./process-identify.js";
+export * from "./subprocess-adapter.js";
+export * as git from "./git.js";
+export * as openspec from "./openspec.js";
+export * as npm from "./npm.js";
+export * as paths from "./paths.js";

package/packages/shared/src/platform/npm.ts

@@ -0,0 +1,162 @@
+/**
+ * npm tool module — Recipe-based API for the npm CLI.
+ *
+ * Covers the subset of npm operations the dashboard actually invokes:
+ *   - `npm root -g`          (resolve the global node_modules path)
+ *   - `npm outdated`         (check for updates, local or global)
+ *   - `npm install`          (install a package, local or global)
+ *   - `npm view <pkg> version` (read upstream version)
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+const NPM_TIMEOUT_FAST = 10_000;
+const NPM_TIMEOUT_INSTALL = 120_000;
+
+interface WithCwd {
+  cwd?: string;
+}
+
+// ── Recipes ─────────────────────────────────────────────────────────────────
+
+/**
+ * `npm root -g` — returns the absolute path to the global node_modules.
+ * Cached by callers (it's stable per Node install).
+ */
+export const NPM_ROOT_GLOBAL: Recipe<Record<string, never>, string> = {
+  argv: () => ["npm", "root", "-g"],
+  parse: (out) => out.trim(),
+  timeout: NPM_TIMEOUT_FAST,
+};
+
+/**
+ * `npm outdated <pkg> --json` (or without `<pkg>` for project-wide).
+ * npm exits 1 when updates are available and 0 when up-to-date — we tolerate
+ * exit 1 so callers see the JSON body either way.
+ */
+export const NPM_OUTDATED: Recipe<WithCwd & { pkg?: string }, unknown | null> = {
+  argv: ({ pkg }) => pkg === undefined
+    ? ["npm", "outdated", "--json"]
+    : ["npm", "outdated", pkg, "--json"],
+  parse: (out) => {
+    const trimmed = out.trim();
+    if (!trimmed) return null;
+    try { return JSON.parse(trimmed); } catch { return null; }
+  },
+  timeout: NPM_TIMEOUT_FAST,
+  tolerate: [1],
+};
+
+/**
+ * `npm outdated -g <pkg> --json`. Same exit-1 tolerance.
+ */
+export const NPM_OUTDATED_GLOBAL: Recipe<{ pkg?: string }, unknown | null> = {
+  argv: ({ pkg }) => pkg === undefined
+    ? ["npm", "outdated", "-g", "--json"]
+    : ["npm", "outdated", "-g", pkg, "--json"],
+  parse: (out) => {
+    const trimmed = out.trim();
+    if (!trimmed) return null;
+    try { return JSON.parse(trimmed); } catch { return null; }
+  },
+  timeout: NPM_TIMEOUT_FAST,
+  tolerate: [1],
+};
+
+/**
+ * `npm install <pkg>@<version>` — local install. Long timeout.
+ */
+export const NPM_INSTALL: Recipe<WithCwd & { pkg: string; version?: string }, string> = {
+  argv: ({ pkg, version }) => ["npm", "install", version ? `${pkg}@${version}` : pkg],
+  parse: (out) => out,
+  timeout: NPM_TIMEOUT_INSTALL,
+};
+
+/**
+ * `npm install -g <pkg>@<version>` — global install.
+ */
+export const NPM_INSTALL_GLOBAL: Recipe<{ pkg: string; version?: string }, string> = {
+  argv: ({ pkg, version }) => ["npm", "install", "-g", version ? `${pkg}@${version}` : pkg],
+  parse: (out) => out,
+  timeout: NPM_TIMEOUT_INSTALL,
+};
+
+/**
+ * `npm view <pkg> version` — the single-value shorthand for "latest version".
+ */
+export const NPM_VIEW_VERSION: Recipe<{ pkg: string }, string> = {
+  argv: ({ pkg }) => ["npm", "view", pkg, "version"],
+  parse: (out) => out.trim(),
+  timeout: NPM_TIMEOUT_FAST,
+};
+
+export const NPM_RECIPES = {
+  NPM_ROOT_GLOBAL,
+  NPM_OUTDATED,
+  NPM_OUTDATED_GLOBAL,
+  NPM_INSTALL,
+  NPM_INSTALL_GLOBAL,
+  NPM_VIEW_VERSION,
+} as const;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * `npm root -g`. Returns a `Result` for explicit error handling; use
+ * `rootGlobalOr` for best-effort semantics.
+ *
+ * Previous versions cached the result in a module-level variable. That
+ * cache is now owned by `ToolRegistry` (the runner consults the
+ * registry for every resolved binary including `npm` itself). Cache
+ * invalidation flows through `registry.rescan()`.
+ *
+ * See change: consolidate-tool-resolution.
+ */
+export function rootGlobal(): Result<string> {
+  return run(NPM_ROOT_GLOBAL, {}, {});
+}
+
+/**
+ * Test-only no-op kept for backward compatibility with existing test
+ * suites. The `cachedGlobalRoot` variable no longer exists.
+ */
+export function _resetNpmRootCache(): void { /* no-op */ }
+
+export function outdated(input: WithCwd & { pkg?: string }): Result<unknown | null> {
+  return run(NPM_OUTDATED, input, { cwd: input.cwd });
+}
+
+export function outdatedGlobal(input: { pkg?: string } = {}): Result<unknown | null> {
+  return run(NPM_OUTDATED_GLOBAL, input, {});
+}
+
+export function install(input: WithCwd & { pkg: string; version?: string }): Result<string> {
+  return run(NPM_INSTALL, input, { cwd: input.cwd });
+}
+
+export function installGlobal(input: { pkg: string; version?: string }): Result<string> {
+  return run(NPM_INSTALL_GLOBAL, input, {});
+}
+
+export function viewVersion(input: { pkg: string }): Result<string> {
+  return run(NPM_VIEW_VERSION, input, {});
+}
+
+// ── Best-effort variants ────────────────────────────────────────────────────
+
+export function rootGlobalOr(fallback = ""): string {
+  return unwrap(rootGlobal(), fallback);
+}
+
+export function outdatedOr(input: WithCwd & { pkg?: string }, fallback: unknown | null = null): unknown | null {
+  return unwrap(outdated(input), fallback);
+}
+
+export function outdatedGlobalOr(input: { pkg?: string } = {}, fallback: unknown | null = null): unknown | null {
+  return unwrap(outdatedGlobal(input), fallback);
+}
+
+export function viewVersionOr(input: { pkg: string }, fallback = ""): string {
+  return unwrap(viewVersion(input), fallback);
+}

package/packages/shared/src/platform/openspec.ts

@@ -0,0 +1,91 @@
+/**
+ * OpenSpec tool module — Recipe-based API for the openspec CLI.
+ *
+ * Replaces the ad-hoc spawnSync/execFile calls in `openspec-poller.ts`
+ * with typed Recipes executed through the runner. The higher-level
+ * `pollOpenSpec` / `pollOpenSpecAsync` functions remain in
+ * `openspec-poller.ts` (they aggregate list + per-change status into
+ * the dashboard's OpenSpecData shape) and now use these primitives.
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+const OPENSPEC_TIMEOUT = 10_000;
+
+interface WithCwd {
+  cwd: string;
+}
+
+/** Parse JSON from stdout; returns null on parse failure. */
+function parseJsonOrNull(out: string): unknown | null {
+  const trimmed = out.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+// ── Recipes ─────────────────────────────────────────────────────────────────
+
+export const OPENSPEC_LIST: Recipe<WithCwd, unknown | null> = {
+  argv: () => ["openspec", "list", "--json"],
+  parse: parseJsonOrNull,
+  timeout: OPENSPEC_TIMEOUT,
+};
+
+export const OPENSPEC_STATUS: Recipe<WithCwd & { change: string }, unknown | null> = {
+  argv: ({ change }) => ["openspec", "status", "--change", change, "--json"],
+  parse: parseJsonOrNull,
+  timeout: OPENSPEC_TIMEOUT,
+};
+
+/**
+ * `openspec archive --completed` — bulk-archives all completed changes.
+ * Stdout is human-readable (not JSON); callers typically don't parse it,
+ * they just await success/failure.
+ */
+export const OPENSPEC_ARCHIVE_COMPLETED: Recipe<WithCwd, string> = {
+  argv: () => ["openspec", "archive", "--completed"],
+  parse: (out) => out,
+  // Archive operations can be slow when many changes are processed.
+  timeout: 30_000,
+};
+
+export const OPENSPEC_RECIPES = {
+  OPENSPEC_LIST,
+  OPENSPEC_STATUS,
+  OPENSPEC_ARCHIVE_COMPLETED,
+} as const;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/** Run `openspec list --json` and return the parsed JSON, or null on failure. */
+export function list(input: WithCwd): Result<unknown | null> {
+  return run(OPENSPEC_LIST, input, { cwd: input.cwd });
+}
+
+/** Run `openspec status --change <name> --json` and return parsed JSON or null. */
+export function status(input: WithCwd & { change: string }): Result<unknown | null> {
+  return run(OPENSPEC_STATUS, input, { cwd: input.cwd });
+}
+
+/** Run `openspec archive --completed`. Returns raw stdout on success. */
+export function archiveCompleted(input: WithCwd): Result<string> {
+  return run(OPENSPEC_ARCHIVE_COMPLETED, input, { cwd: input.cwd });
+}
+
+// ── Best-effort variants (mirror the pattern established in git.ts) ─────────
+
+export function listOr(input: WithCwd, fallback: unknown | null = null): unknown | null {
+  return unwrap(list(input), fallback);
+}
+
+export function statusOr(
+  input: WithCwd & { change: string },
+  fallback: unknown | null = null,
+): unknown | null {
+  return unwrap(status(input), fallback);
+}