@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/shared/src/__tests__/doctor-fault-tolerance.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Doctor fault-tolerance helpers — safeCheck / safeExec / assumedMandatory.
+ * See change: doctor-rich-output (design.md Decision 7).
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, rmSync, existsSync, statSync, writeFileSync, readFileSync, chmodSync } from "node:fs";
+
+import {
+  safeCheck,
+  safeExec,
+  assumedMandatory,
+  stripAnsi,
+} from "../doctor-core.js";
+
+describe("stripAnsi", () => {
+  it("removes CSI sequences", () => {
+    expect(stripAnsi("\u001b[31mred\u001b[0m text")).toBe("red text");
+    expect(stripAnsi("\u001b[1;33;40myellow\u001b[m")).toBe("yellow");
+  });
+  it("removes OSC sequences", () => {
+    expect(stripAnsi("\u001b]0;title\u0007hello")).toBe("hello");
+  });
+  it("preserves printable text untouched", () => {
+    expect(stripAnsi("a | b | c\nfoo")).toBe("a | b | c\nfoo");
+  });
+  it("handles empty input", () => {
+    expect(stripAnsi("")).toBe("");
+  });
+});
+
+describe("safeCheck", () => {
+  it("returns the row on success", async () => {
+    const r = await safeCheck("X", "diagnostics", () => ({
+      name: "X",
+      section: "diagnostics",
+      status: "ok",
+      message: "fine",
+    }));
+    expect(r.status).toBe("ok");
+    expect(r.name).toBe("X");
+  });
+
+  it("swallows synchronous throws and returns a fallback row", async () => {
+    const r = await safeCheck("Boom", "runtime", () => {
+      throw new Error("kaboom");
+    });
+    expect(r.status).toBe("error");
+    expect(r.message).toMatch(/Check failed/i);
+    expect(r.detail).toContain("kaboom");
+    expect(r.suggestion?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  it("swallows promise rejections and returns a fallback row", async () => {
+    const r = await safeCheck("Boom", "runtime", async () => {
+      throw new Error("async-boom");
+    });
+    expect(r.status).toBe("error");
+    expect(r.detail).toContain("async-boom");
+  });
+
+  it("never throws even when fn returns a non-DoctorCheck", async () => {
+    // @ts-expect-error — exercising runtime tolerance
+    const r = await safeCheck("X", "runtime", () => null);
+    // The post-pass treats the missing section as the wrapper-provided
+    // default, so we should still get a row of some shape.
+    expect(r).toBeDefined();
+  });
+});
+
+describe("safeExec — error classification", () => {
+  it("classifies ENOENT as not-found", () => {
+    const r = safeExec("definitely-not-a-binary-xyz-1729 --version", { timeoutMs: 2000 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      // Some shells/platforms classify the missing executable differently:
+      // POSIX with /bin/sh raises a non-zero shell exit (kind=non-zero-exit),
+      // direct exec gets ENOENT (kind=not-found). Both are acceptable failure
+      // signals for "binary missing".
+      expect(["not-found", "non-zero-exit", "unknown"]).toContain(r.kind);
+    }
+  });
+
+  it("classifies non-zero exits", () => {
+    const r = safeExec(`node -e "process.exit(7)"`, { timeoutMs: 5000 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.kind).toBe("non-zero-exit");
+      expect(r.exitCode).toBe(7);
+    }
+  });
+
+  it("captures stderr tail and runs it through stripAnsi", () => {
+    const r = safeExec(
+      `node -e "process.stderr.write('\\u001b[31mboom\\u001b[0m'); process.exit(1)"`,
+      { timeoutMs: 5000 },
+    );
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stderrTail).toContain("boom");
+      expect(r.stderrTail).not.toContain("\u001b");
+    }
+  });
+
+  it("classifies timeouts and reflects the deadline in the message", () => {
+    const r = safeExec(`node -e "setTimeout(()=>{}, 5000)"`, { timeoutMs: 200 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      // Node's execSync timeout typically surfaces as ETIMEDOUT or
+      // SIGTERM signal — both classify as "timeout" in our wrapper.
+      expect(r.kind).toBe("timeout");
+      expect(r.message).toMatch(/0?\s*s/);
+    }
+  });
+
+  it("honours the 15s timeout override (uses it for cold-start probes)", () => {
+    // We don't actually wait 15s; we just verify the wrapper carries the
+    // configured timeoutMs into the SafeExecErr.
+    const r = safeExec(`node -e "process.exit(1)"`, { timeoutMs: 15000 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.timeoutMs).toBe(15000);
+    }
+  });
+
+  it("returns ok with stdout on success", () => {
+    const r = safeExec(`node -e "console.log('hi')"`, { timeoutMs: 5000 });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.stdout.trim()).toBe("hi");
+    }
+  });
+});
+
+describe("assumedMandatory", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(path.join(os.tmpdir(), "doctor-am-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns ok value when fn does not throw", () => {
+    const r = assumedMandatory("read-foo", () => 42, { managedDir: tmp });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value).toBe(42);
+  });
+
+  it("logs to <managedDir>/doctor.log on throw and surfaces a diagnostics row", () => {
+    const r = assumedMandatory(
+      "read-foo",
+      () => {
+        throw new Error("filesystem-down");
+      },
+      { managedDir: tmp },
+    );
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.row.section).toBe("diagnostics");
+      expect(r.row.status).toBe("error");
+      expect(r.row.name).toMatch(/Doctor internal: read-foo/);
+      expect(r.row.detail).toContain("filesystem-down");
+      expect(r.row.suggestion?.length ?? 0).toBeGreaterThan(0);
+    }
+    const logPath = path.join(tmp, "doctor.log");
+    expect(existsSync(logPath)).toBe(true);
+    const log = readFileSync(logPath, "utf-8").trim();
+    const parsed = JSON.parse(log.split("\n")[0]);
+    expect(parsed.label).toBe("read-foo");
+    expect(parsed.message).toBe("filesystem-down");
+  });
+
+  it("tolerates an unwriteable log file (never propagates)", () => {
+    // Make managedDir read-only — append should fail silently.
+    if (process.platform === "win32") {
+      // chmod semantics on Windows are unreliable; skip.
+      return;
+    }
+    chmodSync(tmp, 0o500);
+    try {
+      const r = assumedMandatory(
+        "x",
+        () => {
+          throw new Error("z");
+        },
+        { managedDir: tmp },
+      );
+      expect(r.ok).toBe(false);
+      // Did not throw.
+    } finally {
+      chmodSync(tmp, 0o700);
+    }
+  });
+
+  it("rotates doctor.log when it exceeds 1 MB", () => {
+    const logPath = path.join(tmp, "doctor.log");
+    // Pre-fill log with > 1 MB of data.
+    writeFileSync(logPath, Buffer.alloc(1.2 * 1024 * 1024, "x".charCodeAt(0)));
+    const beforeSize = statSync(logPath).size;
+    expect(beforeSize).toBeGreaterThan(1024 * 1024);
+
+    assumedMandatory(
+      "rotate-test",
+      () => {
+        throw new Error("trigger");
+      },
+      { managedDir: tmp },
+    );
+
+    const rotated = path.join(tmp, "doctor.log.1");
+    expect(existsSync(rotated)).toBe(true);
+    // The fresh log should be small (just one JSON line).
+    const fresh = statSync(logPath).size;
+    expect(fresh).toBeLessThan(2048);
+  });
+});

package/packages/shared/src/__tests__/doctor-format.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Doctor markdown formatter — section ordering, escaping, remediation list.
+ * See change: doctor-rich-output (design.md Decision 8).
+ */
+import { describe, it, expect } from "vitest";
+import {
+  formatDoctorReportMarkdown,
+  formatDoctorReportPlain,
+  type DoctorReport,
+  type DoctorCheck,
+} from "../doctor-core.js";
+
+function mkReport(checks: DoctorCheck[]): DoctorReport {
+  const summary = {
+    ok: checks.filter((c) => c.status === "ok").length,
+    warnings: checks.filter((c) => c.status === "warning").length,
+    errors: checks.filter((c) => c.status === "error").length,
+  };
+  return { checks, summary };
+}
+
+describe("formatDoctorReportMarkdown", () => {
+  it("emits one table per non-empty section in fixed order", () => {
+    const report = mkReport([
+      { name: "API key", section: "setup", status: "ok", message: "Configured" },
+      { name: "pi CLI", section: "pi-tooling", status: "ok", message: "v1" },
+      { name: "Electron", section: "runtime", status: "ok", message: "v40" },
+      {
+        name: "Managed install (~/.pi-dashboard)",
+        section: "diagnostics",
+        status: "ok",
+        message: "fine",
+      },
+    ]);
+    const md = formatDoctorReportMarkdown(report);
+    const runtimeIdx = md.indexOf("## Runtime");
+    const piIdx = md.indexOf("## PI Tooling");
+    const setupIdx = md.indexOf("## Setup");
+    const diagIdx = md.indexOf("## Diagnostics");
+    // Server section absent — skipped silently.
+    expect(md.includes("## Server")).toBe(false);
+    expect(runtimeIdx).toBeGreaterThan(0);
+    expect(runtimeIdx).toBeLessThan(piIdx);
+    expect(piIdx).toBeLessThan(setupIdx);
+    expect(setupIdx).toBeLessThan(diagIdx);
+  });
+
+  it("includes summary line", () => {
+    const report = mkReport([
+      { name: "Electron", section: "runtime", status: "ok", message: "v40" },
+      { name: "pi CLI", section: "pi-tooling", status: "error", message: "missing", detail: "x" },
+    ]);
+    const md = formatDoctorReportMarkdown(report);
+    expect(md).toMatch(/Summary:.*1 ok.*0 warning.*1 error/);
+  });
+
+  it("omits the Remediation section when all rows are ok", () => {
+    const report = mkReport([{ name: "Electron", section: "runtime", status: "ok", message: "v40" }]);
+    const md = formatDoctorReportMarkdown(report);
+    expect(md.includes("## Remediation")).toBe(false);
+  });
+
+  it("renders Remediation bullets for non-ok rows with suggestions", () => {
+    const report = mkReport([
+      {
+        name: "pi CLI",
+        section: "pi-tooling",
+        status: "error",
+        message: "Not found",
+        detail: "PATH searched",
+        suggestion: "Run setup wizard.",
+      },
+    ]);
+    const md = formatDoctorReportMarkdown(report);
+    expect(md).toContain("## Remediation");
+    expect(md).toContain("- **pi CLI** — Run setup wizard.");
+  });
+
+  it("escapes pipe / newline / backtick in detail so the table column count is preserved", () => {
+    const detail = "line1 | with pipe\nline2 with `backtick`";
+    const report = mkReport([
+      {
+        name: "Server launch test",
+        section: "server",
+        status: "error",
+        message: "boom",
+        detail,
+      },
+    ]);
+    const md = formatDoctorReportMarkdown(report);
+    // Find the row line in the output. Each row must have exactly 4 separators
+    // outside the leading/trailing ones — i.e. the row should start with `| `
+    // and contain exactly 5 `|` characters.
+    const tableRow = md
+      .split("\n")
+      .find((l) => l.startsWith("| ") && l.includes("Server launch test"));
+    expect(tableRow).toBeDefined();
+    // A 4-column row has 5 unescaped pipes. Count unescaped pipes.
+    const unescaped = tableRow!
+      .split("")
+      .reduce(
+        (acc, ch, i, arr) =>
+          ch === "|" && arr[i - 1] !== "\\" ? acc + 1 : acc,
+        0,
+      );
+    expect(unescaped).toBe(5);
+    // No literal newline inside the cell.
+    expect(tableRow!.includes("\n")).toBe(false);
+  });
+});
+
+describe("formatDoctorReportPlain (legacy)", () => {
+  it("contains the canonical header and summary footer", () => {
+    const report = mkReport([
+      { name: "Electron", section: "runtime", status: "ok", message: "v40" },
+    ]);
+    const out = formatDoctorReportPlain(report);
+    expect(out).toContain("PI Dashboard Doctor");
+    expect(out).toContain("1 passed, 0 warnings, 0 errors");
+  });
+});

package/packages/shared/src/__tests__/install-managed-node-bootstrap-order.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Pin the call order in `installStandalone` (the Electron entry that
+ * the spec calls `installAllTools`):
+ *
+ *     installManagedNode(...) <  any sharedBootstrapInstall(...)
+ *
+ * We can't easily run installStandalone end-to-end here (it's Electron
+ * code, requires a packaged resources path, spawns real npm). So this
+ * is a script-text test that greps the dependency-installer source for
+ * the call sites and asserts their byte offsets are in the right order.
+ * If a refactor moves installManagedNode after the first npm install,
+ * the regression \u2014 a fresh Windows install having no managed Node when
+ * the very first install runs \u2014 cannot land silently.
+ *
+ * See change: embed-managed-node-runtime (task 4.3).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+import { describe, expect, it } from "vitest";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+// packages/shared/src/__tests__/ \u2192 ../../../electron/src/lib/dependency-installer.ts
+const SOURCE_PATH = path.resolve(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "electron",
+  "src",
+  "lib",
+  "dependency-installer.ts",
+);
+
+describe("installStandalone call order", () => {
+  it("installManagedNode runs before sharedBootstrapInstall", () => {
+    const text = fs.readFileSync(SOURCE_PATH, "utf-8");
+
+    // Locate the installStandalone function body.
+    const fnIdx = text.indexOf("export async function installStandalone");
+    expect(fnIdx).toBeGreaterThan(-1);
+
+    // Scope the search to the function body — find its closing brace.
+    // Cheap bracket counter: starts after the first `{` after fnIdx.
+    const bodyStart = text.indexOf("{", fnIdx);
+    let depth = 0;
+    let bodyEnd = bodyStart;
+    for (let i = bodyStart; i < text.length; i++) {
+      const ch = text[i];
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          bodyEnd = i;
+          break;
+        }
+      }
+    }
+    const body = text.slice(bodyStart, bodyEnd);
+
+    const managedIdx = body.indexOf("installManagedNode(");
+    const sharedIdx = body.indexOf("sharedBootstrapInstall(");
+
+    expect(managedIdx).toBeGreaterThan(-1);
+    expect(sharedIdx).toBeGreaterThan(-1);
+    expect(managedIdx).toBeLessThan(sharedIdx);
+  });
+});

package/packages/shared/src/__tests__/install-managed-node.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Unit tests for `installManagedNode` from `bootstrap-install.ts`.
+ *
+ * Uses a real tmp HOME (per the global setup-home tripwire) and a
+ * real-on-disk fake bundled-node directory. The bundled-Node version
+ * is read via the `_readVersion` test seam so we never spawn `node`
+ * here.
+ *
+ * See change: embed-managed-node-runtime (task 2.4).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { installManagedNode } from "../bootstrap-install.js";
+
+const isWin = process.platform === "win32";
+
+function makeFakeBundle(dir: string, opts?: { partial?: boolean }): void {
+  fs.mkdirSync(dir, { recursive: true });
+  if (isWin) {
+    fs.writeFileSync(path.join(dir, "node.exe"), "fake-node-binary");
+    if (!opts?.partial) {
+      fs.writeFileSync(path.join(dir, "npm.cmd"), "@echo off\nnpm");
+      fs.writeFileSync(path.join(dir, "npx.cmd"), "@echo off\nnpx");
+    }
+    fs.mkdirSync(path.join(dir, "node_modules", "npm", "bin"), {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      path.join(dir, "node_modules", "npm", "bin", "npm-cli.js"),
+      "// npm-cli",
+    );
+  } else {
+    fs.mkdirSync(path.join(dir, "bin"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "bin", "node"), "fake-node-binary");
+    fs.writeFileSync(path.join(dir, "bin", "npm"), "#!/bin/sh\nnpm");
+    fs.writeFileSync(path.join(dir, "bin", "npx"), "#!/bin/sh\nnpx");
+    fs.mkdirSync(path.join(dir, "lib", "node_modules", "npm", "bin"), {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      path.join(dir, "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+      "// npm-cli",
+    );
+  }
+}
+
+describe("installManagedNode", () => {
+  let tmpRoot: string;
+  let bundledDir: string;
+  let managedDir: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "managed-node-test-"));
+    bundledDir = path.join(tmpRoot, "bundled");
+    managedDir = path.join(tmpRoot, "managed");
+    makeFakeBundle(bundledDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("first run: copies tree and writes .version marker", async () => {
+    const r = await installManagedNode({
+      bundledNodeDir: bundledDir,
+      managedDir,
+      _readVersion: () => "v22.12.0",
+    });
+    expect(r.ok).toBe(true);
+    expect(r.copied).toBe(true);
+    expect(r.version).toBe("v22.12.0");
+
+    const targetBinary = isWin
+      ? path.join(managedDir, "node", "node.exe")
+      : path.join(managedDir, "node", "bin", "node");
+    expect(fs.existsSync(targetBinary)).toBe(true);
+
+    const marker = fs.readFileSync(
+      path.join(managedDir, "node", ".version"),
+      "utf-8",
+    );
+    expect(marker.trim()).toBe("v22.12.0");
+  });
+
+  it("idempotent re-run with matching version is a no-op", async () => {
+    await installManagedNode({
+      bundledNodeDir: bundledDir,
+      managedDir,
+      _readVersion: () => "v22.12.0",
+    });
+    const targetBinary = isWin
+      ? path.join(managedDir, "node", "node.exe")
+      : path.join(managedDir, "node", "bin", "node");
+    const mtimeBefore = fs.statSync(targetBinary).mtimeMs;
+
+    // Wait one tick to ensure mtime would change if we recopied.
+    await new Promise((r) => setTimeout(r, 10));
+
+    const r = await installManagedNode({
+      bundledNodeDir: bundledDir,
+      managedDir,
+      _readVersion: () => "v22.12.0",
+    });
+    expect(r.ok).toBe(true);
+    expect(r.copied).toBe(false);
+    expect(r.reason).toMatch(/version matches/);
+    const mtimeAfter = fs.statSync(targetBinary).mtimeMs;
+    expect(mtimeAfter).toBe(mtimeBefore);
+  });
+
+  it("mismatched version triggers a re-copy", async () => {
+    await installManagedNode({
+      bundledNodeDir: bundledDir,
+      managedDir,
+      _readVersion: () => "v22.12.0",
+    });
+
+    // Bundle now reports a newer version.
+    const r = await installManagedNode({
+      bundledNodeDir: bundledDir,
+      managedDir,
+      _readVersion: () => "v22.13.0",
+    });
+    expect(r.ok).toBe(true);
+    expect(r.copied).toBe(true);
+    expect(r.version).toBe("v22.13.0");
+
+    const marker = fs.readFileSync(
+      path.join(managedDir, "node", ".version"),
+      "utf-8",
+    );
+    expect(marker.trim()).toBe("v22.13.0");
+  });
+
+  it("missing bundled source: no-op without error", async () => {
+    const r = await installManagedNode({
+      bundledNodeDir: null,
+      managedDir,
+    });
+    expect(r.ok).toBe(true);
+    expect(r.copied).toBe(false);
+    expect(r.reason).toMatch(/no bundled source/);
+    expect(fs.existsSync(path.join(managedDir, "node"))).toBe(false);
+  });
+
+  it("bundled binary missing: no-op (treat as no source)", async () => {
+    const emptyBundled = path.join(tmpRoot, "empty");
+    fs.mkdirSync(emptyBundled, { recursive: true });
+    const r = await installManagedNode({
+      bundledNodeDir: emptyBundled,
+      managedDir,
+      _readVersion: () => null,
+    });
+    expect(r.ok).toBe(true);
+    expect(r.copied).toBe(false);
+    expect(r.reason).toMatch(/bundled node binary/);
+  });
+
+  it("dir present but marker missing: re-copies (treats as mismatch)", async () => {
+    // Pretend a partial copy left behind a directory with no marker.
+    fs.mkdirSync(path.join(managedDir, "node", "leftover"), { recursive: true });
+
+    const r = await installManagedNode({
+      bundledNodeDir: bundledDir,
+      managedDir,
+      _readVersion: () => "v22.12.0",
+    });
+    expect(r.ok).toBe(true);
+    expect(r.copied).toBe(true);
+    // Leftover should be gone after the rm-then-copy.
+    expect(
+      fs.existsSync(path.join(managedDir, "node", "leftover")),
+    ).toBe(false);
+    expect(
+      fs.existsSync(path.join(managedDir, "node", ".version")),
+    ).toBe(true);
+  });
+
+  it("reports progress through the callback", async () => {
+    const events: Array<{ step: string; status: string }> = [];
+    await installManagedNode({
+      bundledNodeDir: bundledDir,
+      managedDir,
+      _readVersion: () => "v22.12.0",
+      progress: (p) => events.push({ step: p.step, status: p.status }),
+    });
+    expect(events.some((e) => e.step === "node-runtime" && e.status === "running")).toBe(true);
+    expect(events.some((e) => e.step === "node-runtime" && e.status === "done")).toBe(true);
+  });
+});