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

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

@@ -0,0 +1,220 @@
+/**
+ * Safe child-process wrappers that always set `windowsHide: true`.
+ *
+ * Rationale
+ * ─────────
+ * On Windows, spawning a `.cmd` shim (or anything node.exe wraps via cmd.exe)
+ * flashes a cmd-prompt window unless `windowsHide: true` is passed. This is
+ * a universal source of visible-UI bugs in this project: bridge process
+ * scanners, git polls, openspec polls, terminal subprocess checks, etc.
+ * Every spawn site needed to remember to set the flag, and we kept missing
+ * some (session-diff, git-operations, update-checker, doctor, tunnel, ...).
+ *
+ * Rather than fixing this per call site forever, this module wraps the
+ * Node `child_process` API with `windowsHide: true` as the default. Callers
+ * can still override by explicitly passing `windowsHide: false` if they
+ * genuinely want a visible console (none of our callers do).
+ *
+ * **Every spawn in packages/*\/src SHOULD import from here** instead of
+ * directly from `node:child_process`. A repo-level check can fail if
+ * direct imports sneak back in. See change: consolidate-platform-handlers.
+ */
+import {
+  execSync as nodeExecSync,
+  exec as nodeExec,
+  execFile as nodeExecFile,
+  spawnSync as nodeSpawnSync,
+  spawn as nodeSpawn,
+  type ExecSyncOptions,
+  type ExecOptions,
+  type ExecFileOptions,
+  type SpawnSyncOptions,
+  type SpawnOptions,
+  type ChildProcess,
+  type SpawnSyncReturns,
+} from "node:child_process";
+import { promisify } from "node:util";
+
+// ── Argv safety (Windows .cmd / .bat handling) ─────────────────────────────
+
+/**
+ * Build a spawn-safe argv for ANY command on ANY platform.
+ *
+ * The canonical way to invoke subprocesses without flashing cmd.exe
+ * console windows on Windows. Handles three cases:
+ *
+ *   1. Windows + `.cmd` / `.bat` shim → explicit `cmd.exe /c <cmd> <args>`.
+ *      This is the ONLY reliable way to invoke `.cmd` files without the
+ *      flashing-console bug (Node issue #21825, which happens when
+ *      `shell: true` is combined with `.cmd` + `detached` + `windowsHide`).
+ *      cmd.exe respects `windowsHide: true` on its own console directly.
+ *
+ *   2. Windows + native binary (`.exe`) → direct argv.
+ *
+ *   3. Unix (any binary or shell script) → direct argv.
+ *
+ * Always returns `{ shell: false, windowsHide: true }` — NEVER uses
+ * `shell: true`. Callers pass these spawn options along with the argv.
+ *
+ * Example:
+ *   const { argv, spawnOptions } = buildSafeArgv("npm.cmd", ["root", "-g"]);
+ *   spawnSync(argv[0], argv.slice(1), { cwd, env, ...spawnOptions });
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+export interface SafeArgv {
+  argv: string[];
+  spawnOptions: { shell: false; windowsHide: true };
+}
+
+export function buildSafeArgv(
+  cmd: string,
+  args: readonly string[] = [],
+  platform: NodeJS.Platform = process.platform,
+): SafeArgv {
+  if (platform === "win32") {
+    // Route through cmd.exe for TWO cases:
+    //   1. Explicit .cmd/.bat shim — Node can't spawn these directly
+    //      with shell:false (CVE-2024-27980 fix in Node >= 20.12).
+    //   2. Extensionless name (e.g. "npm", "pi", "git") — Windows
+    //      resolves these via PATHEXT, but only shells do. Without
+    //      cmd.exe, spawn("npm") returns ENOENT because there's no
+    //      literal "npm" binary — just "npm.cmd".
+    // Native .exe / absolute paths bypass cmd.exe (no PATHEXT needed).
+    //
+    // /d = skip AutoRun, /s = treat quoted first token as command
+    // (preserves spaces), /c = run and exit. cmd.exe honors
+    // windowsHide on its console, so inner .cmd's node.exe inherits an
+    // invisible console — no flash.
+    const isShim = /\.(cmd|bat)$/i.test(cmd);
+    const hasExtension = /\.[A-Za-z0-9]+$/.test(cmd);
+    if (isShim || !hasExtension) {
+      return {
+        argv: ["cmd.exe", "/d", "/s", "/c", cmd, ...args],
+        spawnOptions: { shell: false, windowsHide: true },
+      };
+    }
+  }
+  return {
+    argv: [cmd, ...args],
+    spawnOptions: { shell: false, windowsHide: true },
+  };
+}
+
+// ── Option helpers ──────────────────────────────────────────────────────────
+
+type AnyOptions = { windowsHide?: boolean } | undefined;
+
+/**
+ * Merge caller options with `windowsHide: true` as the default.
+ * Explicit `windowsHide: false` from the caller is honored (for the rare
+ * case where a visible console is actually desired).
+ */
+function withHide<T extends AnyOptions>(opts: T): T & { windowsHide: boolean } {
+  const hide = opts?.windowsHide ?? true;
+  return { ...(opts ?? {}), windowsHide: hide } as T & { windowsHide: boolean };
+}
+
+// ── Synchronous wrappers ────────────────────────────────────────────────────
+
+/** Wrapped `execSync`. Always `windowsHide: true` unless overridden. */
+export function execSync(command: string, options: ExecSyncOptions & { encoding: BufferEncoding }): string;
+export function execSync(command: string, options?: ExecSyncOptions): Buffer | string;
+export function execSync(
+  command: string,
+  options?: ExecSyncOptions,
+): Buffer | string {
+  return nodeExecSync(command, withHide(options));
+}
+
+/** Wrapped `spawnSync`. Always `windowsHide: true` unless overridden. */
+export function spawnSync<T extends string | Buffer = Buffer>(
+  command: string,
+  args?: readonly string[],
+  options?: SpawnSyncOptions,
+): SpawnSyncReturns<T> {
+  return nodeSpawnSync(command, args ?? [], withHide(options)) as SpawnSyncReturns<T>;
+}
+
+// ── Asynchronous (callback) wrappers ────────────────────────────────────────
+
+/** Wrapped `exec` (callback form). */
+export function exec(
+  command: string,
+  callback?: (err: Error | null, stdout: string, stderr: string) => void,
+): ChildProcess;
+export function exec(
+  command: string,
+  options: ExecOptions,
+  callback?: (err: Error | null, stdout: string | Buffer, stderr: string | Buffer) => void,
+): ChildProcess;
+export function exec(
+  command: string,
+  optionsOrCallback?: ExecOptions | ((err: Error | null, stdout: any, stderr: any) => void),
+  maybeCallback?: (err: Error | null, stdout: any, stderr: any) => void,
+): ChildProcess {
+  if (typeof optionsOrCallback === "function") {
+    return nodeExec(command, withHide(undefined) as ExecOptions, optionsOrCallback);
+  }
+  return nodeExec(command, withHide(optionsOrCallback) as ExecOptions, maybeCallback);
+}
+
+/** Wrapped `execFile` (callback form). */
+export function execFile(
+  file: string,
+  args: readonly string[] | undefined,
+  options: ExecFileOptions,
+  callback?: (err: Error | null, stdout: string | Buffer, stderr: string | Buffer) => void,
+): ChildProcess;
+export function execFile(
+  file: string,
+  args?: readonly string[],
+  callback?: (err: Error | null, stdout: string, stderr: string) => void,
+): ChildProcess;
+export function execFile(
+  file: string,
+  args?: readonly string[],
+  optionsOrCallback?: ExecFileOptions | ((err: Error | null, stdout: any, stderr: any) => void),
+  maybeCallback?: (err: Error | null, stdout: any, stderr: any) => void,
+): ChildProcess {
+  if (typeof optionsOrCallback === "function") {
+    return nodeExecFile(file, args ?? [], withHide(undefined) as ExecFileOptions, optionsOrCallback);
+  }
+  return nodeExecFile(file, args ?? [], withHide(optionsOrCallback) as ExecFileOptions, maybeCallback);
+}
+
+/** Wrapped `spawn`. Always `windowsHide: true` unless overridden. */
+export function spawn(
+  command: string,
+  args?: readonly string[],
+  options?: SpawnOptions,
+): ChildProcess {
+  return nodeSpawn(command, args ?? [], withHide(options));
+}
+
+// ── Promise-returning variants ──────────────────────────────────────────────
+
+/** Promise-returning exec. */
+export const execAsync = promisify(exec) as unknown as (
+  command: string,
+  options?: ExecOptions,
+) => Promise<{ stdout: string | Buffer; stderr: string | Buffer }>;
+
+/** Promise-returning execFile. */
+export const execFileAsync = promisify(execFile) as unknown as (
+  file: string,
+  args?: readonly string[],
+  options?: ExecFileOptions,
+) => Promise<{ stdout: string | Buffer; stderr: string | Buffer }>;
+
+// ── Types pass-through for convenience ──────────────────────────────────────
+
+export type {
+  ExecSyncOptions,
+  ExecOptions,
+  ExecFileOptions,
+  SpawnSyncOptions,
+  SpawnOptions,
+  ChildProcess,
+  SpawnSyncReturns,
+};

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,16 @@
+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 * from "./node-spawn.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/node-spawn.ts

@@ -0,0 +1,154 @@
+/**
+ * Canonical helper for spawning `node --import <loader> <entry>` argv.
+ *
+ * Node ≥ 20's ESM loader parses BOTH the `--import` loader position AND
+ * the entry-script position as URLs. Raw Windows paths like
+ * `B:\Dev\foo.ts` URL-parse to scheme `b:`, which is not in the ESM
+ * loader's allowlist (file, data, node) → the process crashes with
+ * `ERR_UNSUPPORTED_ESM_URL_SCHEME` before any filesystem access.
+ *
+ * Node's internal drive-letter heuristic catches the common cases
+ * (`C:\`, `D:\`) but has known gaps for `A:`, `B:`, and other letters.
+ * Rather than relying on the heuristic, we wrap the loader position
+ * with `file://` unconditionally.
+ *
+ * The entry-script position needs a more nuanced rule. Node's default
+ * resolver AND jiti's ESM hook both accept `file://` URL entries. But
+ * **tsx's ESM hook rejects `file://` URLs as entries** — tsx's resolver
+ * treats the entry as a user-typed specifier and attempts bare-import
+ * / relative-path resolution, producing `<cwd>/file:/...` errors.
+ * Since tsx is used as the jiti fallback on dev machines without pi
+ * installed (the most common Linux dev path), we must NOT URL-wrap
+ * the entry when the loader is tsx. Detection: the loader path
+ * contains `/tsx/` (every tsx install ships its hook under a `tsx/`
+ * directory; jiti's hook is under `jiti/`).
+ *
+ * This module is the canonical chokepoint. The repo-level lint test
+ * `no-raw-node-import.test.ts` refuses any other call site that
+ * passes a raw path to `--import` / `--loader`.
+ *
+ * See change: fix-windows-entry-script-url.
+ */
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { SpawnOptions, ChildProcess } from "node:child_process"; // ban:child_process-ok — types only
+import { spawn as execSpawn } from "./exec.js";
+
+export interface SpawnNodeScriptOptions {
+  /** Path to node.exe / node (raw OS path — binary, not ESM-loaded). */
+  nodeBin?: string;
+
+  /** Path to the script Node will run. Raw path OR file:// URL. */
+  entry: string;
+
+  /** Optional ESM loader for --import. Raw path OR file:// URL. */
+  loader?: string;
+
+  /** Arguments passed to the script (after entry). */
+  args?: string[];
+
+  /** Standard spawn options (cwd, env, stdio, detached, etc.). */
+  spawnOptions?: SpawnOptions;
+}
+
+/**
+ * Detect whether a loader (file:// URL or raw path) is tsx.
+ *
+ * tsx's ESM hook rejects `file://` URLs at the entry-script position,
+ * so the caller must pass a raw OS path for the entry when this
+ * returns true. jiti and Node's default resolver both accept URL
+ * entries.
+ *
+ * Heuristic: every tsx install places its hook under a `tsx/` package
+ * directory (e.g. `.../node_modules/tsx/dist/esm/index.mjs`). The
+ * check is tolerant of `file://` URLs, raw POSIX paths, and raw
+ * Windows paths with either slash direction.
+ */
+export function isTsxLoader(loader: string | null | undefined): boolean {
+  if (!loader) return false;
+  // Normalize backslashes so the `/tsx/` probe works on Windows paths.
+  const normalized = loader.replace(/\\/g, "/");
+  return /\/tsx\//i.test(normalized);
+}
+
+/**
+ * Convert a path-or-url string to a file:// URL.
+ *
+ * Pure and idempotent. Safe to call on strings that are already
+ * file:// URLs — returns them unchanged.
+ *
+ * Handles Windows-style input (drive letter + backslash) regardless of
+ * host OS, so unit tests on Linux/macOS can exercise the Windows path
+ * contract. Mirrors the pattern in
+ * `packages/shared/src/resolve-jiti.ts::buildJitiRegisterUrl`.
+ */
+export function toFileUrl(pathOrUrl: string): string {
+  if (pathOrUrl.startsWith("file:")) return pathOrUrl;
+
+  const isWindowsStyle = /^[A-Za-z]:[\\/]/.test(pathOrUrl);
+  if (isWindowsStyle) {
+    // pathToFileURL on POSIX hosts URL-encodes backslashes rather than
+    // treating them as separators. Build the URL manually so tests on
+    // Linux produce the same result a Windows host would.
+    return `file:///${pathOrUrl.replace(/\\/g, "/")}`;
+  }
+
+  // Use path.resolve to ensure absolute path on the host OS, then
+  // let Node's pathToFileURL handle any host-specific quirks.
+  const absolute = path.isAbsolute(pathOrUrl) ? pathOrUrl : path.resolve(pathOrUrl);
+  return pathToFileURL(absolute).href;
+}
+
+/**
+ * Decide whether the entry-script position needs `file://` URL wrapping.
+ *
+ * Rule:
+ *   - tsx loader: always raw path (tsx rejects file:// entries on every OS)
+ *   - non-tsx (jiti / Node default) on POSIX: raw path
+ *     (POSIX has no drive-letter / URL-scheme collision; jiti's resolver
+ *      actively MISBEHAVES when handed `file://` URL entries — it
+ *      normalises away the triple-slash and then treats `file:/...` as
+ *      a relative specifier, producing `<cwd>/file:/...` ENOENT errors.)
+ *   - non-tsx on Windows: file:// URL
+ *     (Node parses drive letters like `B:` / `A:` as URL schemes in argv
+ *      before loaders run, throwing ERR_UNSUPPORTED_ESM_URL_SCHEME.
+ *      Wrapping with `file://` sidesteps the parse.)
+ *
+ * Keeps a `platform` parameter for testability so unit tests on a POSIX
+ * host can exercise the Windows branch without mutating `process.platform`.
+ */
+export function shouldUrlWrapEntry(
+  loader: string | null | undefined,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (isTsxLoader(loader)) return false;
+  return platform === "win32";
+}
+
+/**
+ * Spawn `node` with an optional `--import` loader and a script entry.
+ *
+ * The loader position is always URL-wrapped (Node's ESM loader
+ * requires `file://` on Windows drive letters outside the heuristic).
+ *
+ * The entry position follows `shouldUrlWrapEntry(loader, platform)` —
+ * URL on Windows + non-tsx, raw everywhere else.
+ *
+ * Delegates actual spawning to `platform/exec.ts::spawn` so the
+ * `windowsHide: true` default and other safe-spawn invariants are
+ * preserved. Does not import `node:child_process` directly (the type
+ * imports above are annotated with the opt-out marker).
+ */
+export function spawnNodeScript(opts: SpawnNodeScriptOptions): ChildProcess {
+  const nodeBin = opts.nodeBin ?? process.execPath;
+  const wrapEntry = shouldUrlWrapEntry(opts.loader);
+
+  const argv: string[] = [];
+  if (opts.loader) {
+    argv.push("--import", toFileUrl(opts.loader));
+  }
+  argv.push(wrapEntry ? toFileUrl(opts.entry) : opts.entry);
+  if (opts.args) argv.push(...opts.args);
+
+  return execSpawn(nodeBin, argv, opts.spawnOptions ?? {});
+}