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

package/packages/shared/src/__tests__/platform-npm.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Tests for packages/shared/src/platform/npm.ts — Recipe argv + parse.
+ * Live npm calls are out of scope (npm may or may not be on PATH in CI).
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  NPM_ROOT_GLOBAL,
+  NPM_OUTDATED,
+  NPM_OUTDATED_GLOBAL,
+  NPM_INSTALL,
+  NPM_INSTALL_GLOBAL,
+  NPM_VIEW_VERSION,
+  NPM_RECIPES,
+  _resetNpmRootCache,
+} from "../platform/npm.js";
+
+beforeEach(() => {
+  _resetNpmRootCache();
+});
+
+describe("NPM_ROOT_GLOBAL", () => {
+  it("produces `npm root -g`", () => {
+    expect(NPM_ROOT_GLOBAL.argv({})).toEqual(["npm", "root", "-g"]);
+  });
+
+  it("trims stdout", () => {
+    expect(NPM_ROOT_GLOBAL.parse("/usr/lib/node_modules\n", {})).toBe("/usr/lib/node_modules");
+  });
+});
+
+describe("NPM_OUTDATED", () => {
+  it("project-wide form", () => {
+    expect(NPM_OUTDATED.argv({})).toEqual(["npm", "outdated", "--json"]);
+  });
+
+  it("scoped to a single package", () => {
+    expect(NPM_OUTDATED.argv({ pkg: "pi-web-access" })).toEqual([
+      "npm", "outdated", "pi-web-access", "--json",
+    ]);
+  });
+
+  it("parses JSON stdout", () => {
+    const json = '{"pi-flows":{"current":"1.0.0","wanted":"1.1.0"}}';
+    expect(NPM_OUTDATED.parse(json, {})).toEqual({
+      "pi-flows": { current: "1.0.0", wanted: "1.1.0" },
+    });
+  });
+
+  it("returns null for empty or malformed stdout", () => {
+    expect(NPM_OUTDATED.parse("", {})).toBeNull();
+    expect(NPM_OUTDATED.parse("not json", {})).toBeNull();
+  });
+
+  it("tolerates exit code 1 (npm exits 1 when updates exist)", () => {
+    expect(NPM_OUTDATED.tolerate).toContain(1);
+  });
+});
+
+describe("NPM_OUTDATED_GLOBAL", () => {
+  it("includes `-g` flag", () => {
+    expect(NPM_OUTDATED_GLOBAL.argv({})).toEqual(["npm", "outdated", "-g", "--json"]);
+  });
+
+  it("scoped form", () => {
+    expect(NPM_OUTDATED_GLOBAL.argv({ pkg: "typescript" })).toEqual([
+      "npm", "outdated", "-g", "typescript", "--json",
+    ]);
+  });
+
+  it("tolerates exit 1", () => {
+    expect(NPM_OUTDATED_GLOBAL.tolerate).toContain(1);
+  });
+});
+
+describe("NPM_INSTALL", () => {
+  it("installs latest when version omitted", () => {
+    expect(NPM_INSTALL.argv({ pkg: "pi-flows" })).toEqual(["npm", "install", "pi-flows"]);
+  });
+
+  it("installs pinned version", () => {
+    expect(NPM_INSTALL.argv({ pkg: "pi-flows", version: "1.2.3" })).toEqual([
+      "npm", "install", "pi-flows@1.2.3",
+    ]);
+  });
+
+  it("has a long timeout for install", () => {
+    expect(NPM_INSTALL.timeout).toBeGreaterThanOrEqual(60_000);
+  });
+});
+
+describe("NPM_INSTALL_GLOBAL", () => {
+  it("includes `-g` flag with version", () => {
+    expect(NPM_INSTALL_GLOBAL.argv({ pkg: "typescript", version: "5.0.0" })).toEqual([
+      "npm", "install", "-g", "typescript@5.0.0",
+    ]);
+  });
+
+  it("omits version suffix when not given", () => {
+    expect(NPM_INSTALL_GLOBAL.argv({ pkg: "typescript" })).toEqual([
+      "npm", "install", "-g", "typescript",
+    ]);
+  });
+});
+
+describe("NPM_VIEW_VERSION", () => {
+  it("produces `npm view <pkg> version`", () => {
+    expect(NPM_VIEW_VERSION.argv({ pkg: "@blackbelt-technology/pi-agent-dashboard" })).toEqual([
+      "npm", "view", "@blackbelt-technology/pi-agent-dashboard", "version",
+    ]);
+  });
+
+  it("trims the version string", () => {
+    expect(NPM_VIEW_VERSION.parse("1.2.3\n", { pkg: "x" })).toBe("1.2.3");
+  });
+});
+
+describe("NPM_RECIPES registry", () => {
+  it("enumerates all 6 recipes", () => {
+    expect(Object.keys(NPM_RECIPES).sort()).toEqual([
+      "NPM_INSTALL",
+      "NPM_INSTALL_GLOBAL",
+      "NPM_OUTDATED",
+      "NPM_OUTDATED_GLOBAL",
+      "NPM_ROOT_GLOBAL",
+      "NPM_VIEW_VERSION",
+    ]);
+  });
+
+  it("every recipe has argv and parse functions", () => {
+    for (const [name, recipe] of Object.entries(NPM_RECIPES)) {
+      expect(typeof recipe.argv, `${name}.argv`).toBe("function");
+      expect(typeof recipe.parse, `${name}.parse`).toBe("function");
+    }
+  });
+});

package/packages/shared/src/__tests__/platform-openspec.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Tests for packages/shared/src/platform/openspec.ts.
+ *
+ * Pure argv + parse tests; integration with a live openspec binary is
+ * out of scope for unit tests (openspec may not be on PATH in CI).
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  OPENSPEC_LIST,
+  OPENSPEC_STATUS,
+  OPENSPEC_ARCHIVE_COMPLETED,
+  OPENSPEC_RECIPES,
+} from "../platform/openspec.js";
+
+describe("OPENSPEC_LIST", () => {
+  it("produces `openspec list --json`", () => {
+    expect(OPENSPEC_LIST.argv({ cwd: "/tmp" })).toEqual(["openspec", "list", "--json"]);
+  });
+
+  it("parses valid JSON output", () => {
+    const input = { cwd: "/tmp" };
+    const out = OPENSPEC_LIST.parse('{"changes":[{"name":"x"}]}', input);
+    expect(out).toEqual({ changes: [{ name: "x" }] });
+  });
+
+  it("returns null for empty stdout", () => {
+    expect(OPENSPEC_LIST.parse("", { cwd: "/tmp" })).toBeNull();
+    expect(OPENSPEC_LIST.parse("   \n", { cwd: "/tmp" })).toBeNull();
+  });
+
+  it("returns null for malformed JSON", () => {
+    expect(OPENSPEC_LIST.parse("not json", { cwd: "/tmp" })).toBeNull();
+    expect(OPENSPEC_LIST.parse("{broken", { cwd: "/tmp" })).toBeNull();
+  });
+});
+
+describe("OPENSPEC_STATUS", () => {
+  it("produces `openspec status --change <name> --json`", () => {
+    expect(OPENSPEC_STATUS.argv({ cwd: "/tmp", change: "add-feature" })).toEqual([
+      "openspec", "status", "--change", "add-feature", "--json",
+    ]);
+  });
+
+  it("parses status result JSON", () => {
+    const input = { cwd: "/tmp", change: "x" };
+    const out = OPENSPEC_STATUS.parse('{"artifacts":[{"id":"proposal","status":"done"}]}', input);
+    expect(out).toEqual({ artifacts: [{ id: "proposal", status: "done" }] });
+  });
+
+  it("accepts change names with special characters verbatim (no shell escaping needed)", () => {
+    // argv is an array, so special chars flow through unchanged
+    expect(OPENSPEC_STATUS.argv({ cwd: "/tmp", change: "a b/c" })).toEqual([
+      "openspec", "status", "--change", "a b/c", "--json",
+    ]);
+  });
+});
+
+describe("OPENSPEC_ARCHIVE_COMPLETED", () => {
+  it("produces `openspec archive --completed`", () => {
+    expect(OPENSPEC_ARCHIVE_COMPLETED.argv({ cwd: "/tmp" })).toEqual([
+      "openspec", "archive", "--completed",
+    ]);
+  });
+
+  it("returns stdout verbatim (no JSON parsing)", () => {
+    expect(OPENSPEC_ARCHIVE_COMPLETED.parse("Archived 3 changes\n", { cwd: "/tmp" }))
+      .toBe("Archived 3 changes\n");
+  });
+
+  it("has a longer timeout than list/status (archive can be slow)", () => {
+    expect(OPENSPEC_ARCHIVE_COMPLETED.timeout).toBeGreaterThanOrEqual(15_000);
+  });
+});
+
+describe("OPENSPEC_RECIPES registry", () => {
+  it("enumerates all exported recipes", () => {
+    expect(Object.keys(OPENSPEC_RECIPES).sort()).toEqual([
+      "OPENSPEC_ARCHIVE_COMPLETED",
+      "OPENSPEC_LIST",
+      "OPENSPEC_STATUS",
+    ]);
+  });
+
+  it("every recipe has argv and parse functions", () => {
+    for (const [name, recipe] of Object.entries(OPENSPEC_RECIPES)) {
+      expect(typeof recipe.argv, `${name}.argv`).toBe("function");
+      expect(typeof recipe.parse, `${name}.parse`).toBe("function");
+    }
+  });
+});

package/packages/shared/src/__tests__/platform-paths.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Tests for packages/shared/src/platform/paths.ts.
+ *
+ * Every test explicitly passes a `platform: NodeJS.Platform` argument so
+ * both Windows and Unix branches run on every CI host. No mutation of
+ * `process.platform`, no `vi.mock`.
+ *
+ * See change: platform-path-normalization.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  normalizePath,
+  samePath,
+  parsePathInput,
+  withTrailingSep,
+  joinForDisplay,
+  isFilesystemRoot,
+} from "../platform/paths.js";
+
+// ── normalizePath ───────────────────────────────────────────────────────────
+
+describe("normalizePath — Windows", () => {
+  it("strips trailing separator from non-root path", () => {
+    expect(normalizePath("C:\\Dev\\BB\\pi-agent-dashboard\\", "win32"))
+      .toBe("C:\\Dev\\BB\\pi-agent-dashboard");
+  });
+
+  it("canonicalizes mixed separators to backslash", () => {
+    expect(normalizePath("C:/Dev\\BB/pi-agent-dashboard", "win32"))
+      .toBe("C:\\Dev\\BB\\pi-agent-dashboard");
+  });
+
+  it("preserves drive root trailing separator", () => {
+    expect(normalizePath("C:\\", "win32")).toBe("C:\\");
+  });
+
+  it("preserves UNC root", () => {
+    expect(normalizePath("\\\\server\\share\\path\\", "win32"))
+      .toBe("\\\\server\\share\\path");
+  });
+
+  it("resolves .. and . segments within a drive", () => {
+    expect(normalizePath("C:\\Dev\\BB\\..\\.\\pi-agent-dashboard", "win32"))
+      .toBe("C:\\Dev\\pi-agent-dashboard");
+  });
+
+  it("preserves case (no lowercasing)", () => {
+    expect(normalizePath("C:\\Dev\\BB", "win32")).toBe("C:\\Dev\\BB");
+    expect(normalizePath("b:\\Dev\\BB", "win32")).toBe("b:\\Dev\\BB");
+  });
+
+  it("preserves different drive letters independently", () => {
+    expect(normalizePath("A:\\Foo\\Bar", "win32")).toBe("A:\\Foo\\Bar");
+    expect(normalizePath("B:\\Foo\\Bar", "win32")).toBe("B:\\Foo\\Bar");
+    expect(normalizePath("Z:\\Something", "win32")).toBe("Z:\\Something");
+  });
+
+  it("treats bare drive letter as drive root, not cwd-relative", () => {
+    // Must NOT fall through to path.win32.resolve which would return
+    // <cwd-on-B-drive>, leaking process.cwd() into the result.
+    expect(normalizePath("B:", "win32")).toBe("B:\\");
+    expect(normalizePath("Z:", "win32")).toBe("Z:\\");
+  });
+
+  it("treats drive-relative typed form as drive-rooted", () => {
+    // "B:Dev" → treat as "B:\Dev", NOT as <B-drive-cwd>\Dev
+    expect(normalizePath("B:Dev", "win32")).toBe("B:\\Dev");
+    expect(normalizePath("C:Users\\me", "win32")).toBe("C:\\Users\\me");
+  });
+
+  it("drops duplicate separators", () => {
+    expect(normalizePath("D:\\\\", "win32")).toBe("D:\\");
+    expect(normalizePath("C:\\\\Users\\\\me", "win32")).toBe("C:\\Users\\me");
+  });
+});
+
+describe("normalizePath — POSIX", () => {
+  it("strips trailing separator from non-root path", () => {
+    expect(normalizePath("/Users/me/Projects/", "linux"))
+      .toBe("/Users/me/Projects");
+  });
+
+  it("preserves root", () => {
+    expect(normalizePath("/", "linux")).toBe("/");
+    expect(normalizePath("/", "darwin")).toBe("/");
+  });
+
+  it("resolves .. and . segments", () => {
+    expect(normalizePath("/Users/me/Dev/../Projects", "linux"))
+      .toBe("/Users/me/Projects");
+  });
+
+  it("collapses duplicate slashes", () => {
+    expect(normalizePath("/Users//me///Projects", "linux"))
+      .toBe("/Users/me/Projects");
+  });
+
+  it("preserves case", () => {
+    expect(normalizePath("/Users/Robson/Dev", "linux")).toBe("/Users/Robson/Dev");
+  });
+});
+
+// ── samePath ────────────────────────────────────────────────────────────────
+
+describe("samePath — Windows (case-insensitive)", () => {
+  it("matches identical paths", () => {
+    expect(samePath("C:\\Dev", "C:\\Dev", "win32")).toBe(true);
+  });
+
+  it("matches with different case", () => {
+    expect(samePath("C:\\Dev\\BB", "c:\\dev\\bb", "win32")).toBe(true);
+  });
+
+  it("matches with different separator style", () => {
+    expect(samePath("C:\\Dev\\BB", "C:/Dev/BB", "win32")).toBe(true);
+  });
+
+  it("matches with trailing-separator drift", () => {
+    expect(samePath("C:\\Dev\\BB", "C:\\Dev\\BB\\", "win32")).toBe(true);
+  });
+
+  it("matches drive-letter case drift alone", () => {
+    expect(samePath("B:\\Dev\\BB", "b:\\Dev\\BB", "win32")).toBe(true);
+  });
+
+  it("DOES NOT merge different drive letters", () => {
+    expect(samePath("A:\\Foo", "B:\\Foo", "win32")).toBe(false);
+    expect(samePath("C:\\Users\\me\\Dev", "D:\\Users\\me\\Dev", "win32")).toBe(false);
+  });
+
+  it("DOES NOT merge UNC path with drive-letter path", () => {
+    expect(samePath("\\\\server\\share\\x", "B:\\x", "win32")).toBe(false);
+  });
+
+  it("returns false for genuinely different paths", () => {
+    expect(samePath("C:\\a", "C:\\b", "win32")).toBe(false);
+  });
+});
+
+describe("samePath — macOS (case-insensitive, HFS+ default)", () => {
+  it("matches with different case", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/dev", "darwin")).toBe(true);
+  });
+
+  it("matches with trailing-separator drift", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/Dev/", "darwin")).toBe(true);
+  });
+});
+
+describe("samePath — Linux (case-sensitive)", () => {
+  it("does NOT match on case drift", () => {
+    expect(samePath("/Users/me/Dev", "/users/me/dev", "linux")).toBe(false);
+  });
+
+  it("matches identical paths", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/Dev", "linux")).toBe(true);
+  });
+
+  it("matches with trailing-separator drift", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/Dev/", "linux")).toBe(true);
+  });
+
+  it("returns false for different paths", () => {
+    expect(samePath("/a/b", "/a/c", "linux")).toBe(false);
+  });
+});
+
+// ── parsePathInput ──────────────────────────────────────────────────────────
+
+describe("parsePathInput — Windows", () => {
+  it("splits path ending in separator", () => {
+    expect(parsePathInput("C:\\Users\\mboto\\", "win32"))
+      .toEqual({ parent: "C:\\Users\\mboto", partial: "" });
+  });
+
+  it("splits path with partial trailing segment", () => {
+    expect(parsePathInput("C:\\Users\\mboto\\Dev", "win32"))
+      .toEqual({ parent: "C:\\Users\\mboto", partial: "Dev" });
+  });
+
+  it("treats drive root with trailing separator as root", () => {
+    expect(parsePathInput("C:\\", "win32"))
+      .toEqual({ parent: "C:\\", partial: "" });
+  });
+
+  it("treats bare drive letter as drive root", () => {
+    // Critical: must NOT leak cwd via path.win32.resolve fallback.
+    expect(parsePathInput("B:", "win32"))
+      .toEqual({ parent: "B:\\", partial: "" });
+    expect(parsePathInput("Z:", "win32"))
+      .toEqual({ parent: "Z:\\", partial: "" });
+  });
+
+  it("treats drive-relative typed form as drive root + partial", () => {
+    expect(parsePathInput("B:Dev", "win32"))
+      .toEqual({ parent: "B:\\", partial: "Dev" });
+    expect(parsePathInput("C:Users", "win32"))
+      .toEqual({ parent: "C:\\", partial: "Users" });
+  });
+
+  it("splits drive root + partial when separator present", () => {
+    expect(parsePathInput("C:\\Us", "win32"))
+      .toEqual({ parent: "C:\\", partial: "Us" });
+  });
+
+  it("handles UNC path with trailing separator", () => {
+    expect(parsePathInput("\\\\server\\share\\dir\\", "win32"))
+      .toEqual({ parent: "\\\\server\\share\\dir", partial: "" });
+  });
+
+  it("tolerates mixed separators", () => {
+    expect(parsePathInput("C:\\Users\\mboto/Dev", "win32"))
+      .toEqual({ parent: "C:\\Users\\mboto", partial: "Dev" });
+  });
+
+  it("is drive-letter symmetric", () => {
+    // Same shape regardless of drive letter.
+    for (const d of ["A", "B", "C", "D", "Z"]) {
+      expect(parsePathInput(`${d}:\\Foo\\B`, "win32"))
+        .toEqual({ parent: `${d}:\\Foo`, partial: "B" });
+    }
+  });
+});
+
+describe("parsePathInput — POSIX", () => {
+  it("splits absolute path with trailing separator", () => {
+    expect(parsePathInput("/Users/me/", "linux"))
+      .toEqual({ parent: "/Users/me", partial: "" });
+  });
+
+  it("splits absolute path with partial", () => {
+    expect(parsePathInput("/Users/me/Dev", "linux"))
+      .toEqual({ parent: "/Users/me", partial: "Dev" });
+  });
+
+  it("treats root alone as root", () => {
+    expect(parsePathInput("/", "linux"))
+      .toEqual({ parent: "/", partial: "" });
+  });
+
+  it("treats partial-under-root as such", () => {
+    expect(parsePathInput("/U", "linux"))
+      .toEqual({ parent: "/", partial: "U" });
+  });
+});
+
+// ── withTrailingSep & joinForDisplay ────────────────────────────────────────
+
+describe("withTrailingSep", () => {
+  it("appends \\ on Windows", () => {
+    expect(withTrailingSep("C:\\Users\\me", "win32")).toBe("C:\\Users\\me\\");
+  });
+  it("appends / on POSIX", () => {
+    expect(withTrailingSep("/Users/me", "linux")).toBe("/Users/me/");
+  });
+  it("does not double-append when already terminated", () => {
+    expect(withTrailingSep("C:\\Users\\me\\", "win32")).toBe("C:\\Users\\me\\");
+    expect(withTrailingSep("/Users/me/", "linux")).toBe("/Users/me/");
+  });
+});
+
+describe("joinForDisplay", () => {
+  it("joins Windows paths with backslash", () => {
+    expect(joinForDisplay("C:\\Users", "me", "win32")).toBe("C:\\Users\\me");
+  });
+  it("joins POSIX paths with forward slash", () => {
+    expect(joinForDisplay("/Users", "me", "linux")).toBe("/Users/me");
+  });
+});
+
+// ── isFilesystemRoot ────────────────────────────────────────────────────────
+
+describe("isFilesystemRoot", () => {
+  it("recognises Windows drive roots", () => {
+    expect(isFilesystemRoot("C:\\", "win32")).toBe(true);
+    expect(isFilesystemRoot("B:\\", "win32")).toBe(true);
+    expect(isFilesystemRoot("C:\\Users", "win32")).toBe(false);
+  });
+
+  it("recognises Unix root", () => {
+    expect(isFilesystemRoot("/", "linux")).toBe(true);
+    expect(isFilesystemRoot("/Users", "linux")).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/platform-process-scan.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Tests for packages/shared/src/platform/process-scan.ts.
+ * Platform behavior is exercised via injected `platform` + `exec`.
+ * See change: consolidate-platform-handlers.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { parseEtime, isProcessRunning } from "../platform/process-scan.js";
+
+describe("parseEtime", () => {
+  it("parses mm:ss format", () => expect(parseEtime("02:15")).toBe(135_000));
+  it("parses hh:mm:ss format", () => expect(parseEtime("01:30:00")).toBe(5_400_000));
+  it("parses dd-hh:mm:ss format", () => expect(parseEtime("2-03:00:00")).toBe(183_600_000));
+  it("parses 1-00:00:00 as 1 day", () => expect(parseEtime("1-00:00:00")).toBe(86_400_000));
+  it("parses 00:05 as 5 seconds", () => expect(parseEtime("00:05")).toBe(5_000));
+  it("returns 0 for empty", () => expect(parseEtime("")).toBe(0));
+  it("returns 0 for whitespace", () => expect(parseEtime("   ")).toBe(0));
+  it("returns 0 for garbage", () => expect(parseEtime("not-a-time")).toBe(0));
+  it("returns 0 for single number (not a time)", () => expect(parseEtime("42")).toBe(0));
+});
+
+describe("isProcessRunning", () => {
+  it("uses tasklist on Windows and matches image name", () => {
+    const exec = vi.fn().mockReturnValue(
+      "Code.exe                    12345 Console                    1    50,000 K\n",
+    );
+    expect(isProcessRunning("Code.exe", { platform: "win32", exec })).toBe(true);
+    expect(exec.mock.calls[0][0]).toMatch(/tasklist\s+\/FI\s+"IMAGENAME eq Code\.exe"/);
+  });
+
+  it("returns false on Windows when image name is missing from output", () => {
+    const exec = vi.fn().mockReturnValue("INFO: No tasks are running.\n");
+    expect(isProcessRunning("Missing.exe", { platform: "win32", exec })).toBe(false);
+  });
+
+  it("uses pgrep on Unix and returns true when exit code is 0", () => {
+    const exec = vi.fn().mockReturnValue("12345\n");
+    expect(isProcessRunning("/Applications/Zed.app", { platform: "darwin", exec })).toBe(true);
+    expect(exec.mock.calls[0][0]).toMatch(/pgrep\s+-f\s+"\/Applications\/Zed\.app"/);
+  });
+
+  it("returns false on Unix when pgrep throws (no match)", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("exit code 1");
+    });
+    expect(isProcessRunning("nothing", { platform: "linux", exec })).toBe(false);
+  });
+
+  it("returns false on any platform when exec throws unexpectedly", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("boom");
+    });
+    expect(isProcessRunning("Code.exe", { platform: "win32", exec })).toBe(false);
+    expect(isProcessRunning("zed", { platform: "linux", exec })).toBe(false);
+  });
+});