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

package/packages/shared/src/__tests__/installable-list.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mergeInstallableList, readInstallableList, writeInstallableList } from "../installable-list.js";
+import type { InstallableList } from "../installable-list.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// ── mergeInstallableList tests ──────────────────────────────────────────────
+
+describe("mergeInstallableList", () => {
+  it("keep-user-pin: user version wins when it differs from bundled", () => {
+    const existing: InstallableList = {
+      version: "1",
+      packages: [{ name: "tsx", version: "^4.0.0", required: true, kind: "npm" }],
+    };
+    const bundled: InstallableList = {
+      version: "2",
+      packages: [{ name: "tsx", version: "^5.0.0", required: true, kind: "npm" }],
+    };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "tsx");
+    expect(found?.version).toBe("^4.0.0");
+    expect(warnings.length).toBeGreaterThan(0);
+    expect(warnings[0]).toContain("tsx");
+    expect(warnings[0]).toContain("^4.0.0");
+    expect(warnings[0]).toContain("^5.0.0");
+  });
+
+  it("drop-pin-warn: package in existing but not in bundled gets deprecated=true + warning", () => {
+    const existing: InstallableList = {
+      version: "1",
+      packages: [{ name: "old-tool", version: "^1.0.0", required: false, kind: "npm" }],
+    };
+    const bundled: InstallableList = { version: "2", packages: [] };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "old-tool");
+    expect(found?.deprecated).toBe(true);
+    expect(warnings.length).toBeGreaterThan(0);
+    expect(warnings[0]).toContain("old-tool");
+  });
+
+  it("add-new-required: new required package from bundled is added as-is", () => {
+    const existing: InstallableList = { version: "1", packages: [] };
+    const bundled: InstallableList = {
+      version: "2",
+      packages: [{ name: "pi", version: "*", required: true, kind: "npm" }],
+    };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "pi");
+    expect(found).toBeDefined();
+    expect(found?.required).toBe(true);
+    expect(found?.defaultOff).toBeFalsy();
+    expect(warnings).toHaveLength(0);
+  });
+
+  it("add-new-optional: new optional package from bundled is added with defaultOff=true", () => {
+    const existing: InstallableList = { version: "1", packages: [] };
+    const bundled: InstallableList = {
+      version: "2",
+      packages: [{ name: "openspec", version: "*", required: false, kind: "npm" }],
+    };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "openspec");
+    expect(found).toBeDefined();
+    expect(found?.defaultOff).toBe(true);
+    expect(warnings).toHaveLength(0);
+  });
+
+  it("version marker in result comes from bundled", () => {
+    const existing: InstallableList = { version: "1", packages: [] };
+    const bundled: InstallableList = { version: "42", packages: [] };
+    const { list } = mergeInstallableList(existing, bundled);
+    expect(list.version).toBe("42");
+  });
+});
+
+// ── readInstallableList tests ───────────────────────────────────────────────
+// Use a real temp directory (HOME is already ephemeral in the test runner).
+
+describe("readInstallableList", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "installable-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("returns null when file is absent", async () => {
+    const result = await readInstallableList(tmpDir);
+    expect(result).toBeNull();
+  });
+
+  it("drops entries with invalid kind and warns", async () => {
+    const list: InstallableList = {
+      version: "1",
+      packages: [
+        { name: "good-pkg", version: "*", required: true, kind: "npm" },
+        { name: "bad-pkg", version: "*", required: true, kind: "unknown-kind" as any },
+      ],
+    };
+    // Write via writeInstallableList (bypasses the drop-invalid-kind guard).
+    const filePath = path.join(tmpDir, "installable.json");
+    fs.writeFileSync(filePath, JSON.stringify(list), "utf-8");
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = await readInstallableList(tmpDir);
+
+    expect(result).not.toBeNull();
+    expect(result!.packages.map((p) => p.name)).toEqual(["good-pkg"]);
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy.mock.calls[0]![0]).toContain("bad-pkg");
+  });
+
+  it("reads a valid file and returns the list", async () => {
+    const list: InstallableList = {
+      version: "3",
+      packages: [{ name: "tsx", version: "^5.0.0", required: true, kind: "npm" }],
+    };
+    await writeInstallableList(list, tmpDir);
+    const result = await readInstallableList(tmpDir);
+    expect(result).not.toBeNull();
+    expect(result!.version).toBe("3");
+    expect(result!.packages).toHaveLength(1);
+    expect(result!.packages[0]!.name).toBe("tsx");
+  });
+});

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

@@ -0,0 +1,122 @@
+/**
+ * Unit tests for `prependManagedNodeToPath` and friends.
+ *
+ * Real tmp HOME (per setup-home tripwire) so `getManagedDir()` resolves
+ * under the tmp tree. We create / remove the managed Node binary on
+ * disk to flip the present/absent branches.
+ *
+ * See change: embed-managed-node-runtime (task 2.5).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  getManagedNodeBinDir,
+  getManagedNodeBinary,
+  isManagedNodePresent,
+  prependManagedNodeToPath,
+} from "../platform/managed-node-path.js";
+import { getManagedDir } from "../managed-paths.js";
+
+const isWin = process.platform === "win32";
+
+describe("getManagedNodeBinDir", () => {
+  it("returns <managedDir>/node on Windows", () => {
+    const env = { homedir: "/fake/home" };
+    expect(getManagedNodeBinDir(env, "win32")).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node"),
+    );
+  });
+
+  it("returns <managedDir>/node/bin on Unix", () => {
+    const env = { homedir: "/fake/home" };
+    expect(getManagedNodeBinDir(env, "linux")).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node", "bin"),
+    );
+    expect(getManagedNodeBinDir(env, "darwin")).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node", "bin"),
+    );
+  });
+});
+
+describe("getManagedNodeBinary", () => {
+  it("uses node.exe on Windows", () => {
+    expect(getManagedNodeBinary({ homedir: "/h" }, "win32")).toBe(
+      path.join("/h", ".pi-dashboard", "node", "node.exe"),
+    );
+  });
+
+  it("uses bin/node on Unix", () => {
+    expect(getManagedNodeBinary({ homedir: "/h" }, "linux")).toBe(
+      path.join("/h", ".pi-dashboard", "node", "bin", "node"),
+    );
+  });
+});
+
+describe("prependManagedNodeToPath", () => {
+  let tmpHome: string;
+  let origHome: string | undefined;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "managed-node-path-"));
+    origHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (origHome === undefined) delete process.env.HOME;
+    else process.env.HOME = origHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  function installFakeManagedNode(): string {
+    // os.homedir() reads HOME on Unix and USERPROFILE on Windows. The
+    // setup-home tripwire only sets HOME, so on Windows tests we set
+    // USERPROFILE here too.
+    if (isWin) process.env.USERPROFILE = tmpHome;
+    const dir = getManagedNodeBinDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const binary = getManagedNodeBinary();
+    fs.writeFileSync(binary, "fake");
+    return dir;
+  }
+
+  it("no-op (returns clone) when managed runtime is absent", () => {
+    const base = { PATH: "/usr/bin:/bin", FOO: "bar" };
+    const out = prependManagedNodeToPath(base);
+    expect(out).not.toBe(base);
+    expect(out.PATH).toBe("/usr/bin:/bin");
+    expect(out.FOO).toBe("bar");
+  });
+
+  it("does not mutate process.env", () => {
+    const beforePath = process.env.PATH;
+    prependManagedNodeToPath();
+    expect(process.env.PATH).toBe(beforePath);
+  });
+
+  it("prepends managed Node bin dir when present", () => {
+    const dir = installFakeManagedNode();
+    const base = { PATH: "/usr/bin:/bin", X: "y" };
+    const out = prependManagedNodeToPath(base);
+    expect(out).not.toBe(base);
+    expect(out.PATH?.startsWith(dir)).toBe(true);
+    expect(out.PATH).toBe(`${dir}${path.delimiter}/usr/bin:/bin`);
+    expect(out.X).toBe("y");
+  });
+
+  it("does not double-prepend when dir already at head", () => {
+    const dir = installFakeManagedNode();
+    const initial = `${dir}${path.delimiter}/usr/bin`;
+    const base = { PATH: initial };
+    const out = prependManagedNodeToPath(base);
+    expect(out.PATH).toBe(initial);
+  });
+
+  it("isManagedNodePresent flips with the binary on disk", () => {
+    expect(isManagedNodePresent()).toBe(false);
+    installFakeManagedNode();
+    expect(isManagedNodePresent()).toBe(true);
+  });
+});

package/packages/shared/src/__tests__/managed-runtime-strategy.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Unit tests for `managedRuntimeStrategy` in isolation.
+ *
+ * Strategy receives a `StrategyCtx` (overrides + platform + env). We
+ * inject a fake `exists` so no real filesystem is touched.
+ *
+ * See change: embed-managed-node-runtime (task 2.6).
+ */
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { managedRuntimeStrategy } from "../tool-registry/strategies.js";
+import type { StrategyCtx } from "../tool-registry/types.js";
+
+function ctx(opts: Partial<StrategyCtx> = {}): StrategyCtx {
+  return {
+    overrides: {},
+    platform: opts.platform ?? "linux",
+    env: opts.env ?? { homedir: "/fake/home" },
+  };
+}
+
+describe("managedRuntimeStrategy", () => {
+  it("Unix node: returns <managedDir>/node/bin/node when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "bin", "node");
+    const s = managedRuntimeStrategy("node", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "linux" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Unix npm: returns <managedDir>/node/bin/npm when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "bin", "npm");
+    const s = managedRuntimeStrategy("npm", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "linux" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Windows node: returns <managedDir>/node/node.exe when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "node.exe");
+    const s = managedRuntimeStrategy("node", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "win32" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Windows npm: returns <managedDir>/node/npm.cmd when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "npm.cmd");
+    const s = managedRuntimeStrategy("npm", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "win32" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Windows npx: returns <managedDir>/node/npx.cmd when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "npx.cmd");
+    const s = managedRuntimeStrategy("npx", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "win32" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("returns failure with reason when binary absent", () => {
+    const s = managedRuntimeStrategy("node", { exists: () => false });
+    const r = s.run(ctx({ platform: "linux" }));
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/missing:/);
+  });
+
+  it("strategy is named 'managed' (classifies as managed source)", () => {
+    const s = managedRuntimeStrategy("node");
+    expect(s.name).toBe("managed");
+  });
+});

package/packages/shared/src/__tests__/no-installable-list-in-bridge.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Contract test: the bridge auto-spawn code path (server-launcher.ts) must
+ * NOT import from `installable-list`. Only Electron seeds `installable.json`
+ * on first run; Bridge and Standalone starters must not produce or consume
+ * that file.
+ *
+ * This is a static source scan — no runtime execution. If this test fails,
+ * a dependency on installable-list was accidentally added to the bridge
+ * launcher which would break the "file-absent is a no-op" contract on
+ * Bridge/Standalone bootstraps.
+ *
+ * See change: simplify-electron-bootstrap-derived-state (task 5.7).
+ */
+import { describe, expect, it } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "..", "..", "..", "..");
+
+/** Files that form the bridge auto-spawn contract. */
+const BRIDGE_SPAWN_FILES: readonly string[] = [
+  "packages/extension/src/server-launcher.ts",
+  "packages/extension/src/server-auto-start.ts",
+  "packages/extension/src/connection.ts",
+];
+
+describe("bridge auto-spawn does not reference installable-list", () => {
+  for (const rel of BRIDGE_SPAWN_FILES) {
+    it(`${rel} does not import from installable-list`, () => {
+      const file = path.resolve(repoRoot, rel);
+      if (!fs.existsSync(file)) {
+        // File absent (optional extension file) — contract trivially satisfied.
+        return;
+      }
+      const source = fs.readFileSync(file, "utf-8");
+
+      // Strip line comments before checking so a commented-out import
+      // does not trigger a false positive.
+      const stripped = source
+        .replace(/\/\/[^\n]*/g, "")
+        .replace(/\/\*[\s\S]*?\*\//g, "");
+
+      expect(
+        stripped,
+        `${rel} must not import from "installable-list" — only Electron seeds installable.json. ` +
+          `Bridge/Standalone starters must not produce or consume that file.`,
+      ).not.toMatch(/installable-list/);
+    });
+  }
+});

package/packages/shared/src/__tests__/no-raw-openspec-status-in-skills.test.ts

@@ -38,7 +38,12 @@ const GOVERNED_SKILLS = [
 ];
 
 describe("OpenSpec workflow skills must use effective-status.sh", () => {
-  it("no raw `openspec status --json` outside the wrapper script", async () => {
+  // SKIPPED: the .pi/skills/openspec-*/SKILL.md files this lint targets are
+  // vendored from upstream and gitignored (see .pi/.gitignore) — they get
+  // overwritten on every install, so we can't enforce dashboard-local
+  // semantics on them from here. Re-enable if/when those skills are
+  // forked into the repo, or move the wrapper-enforcement upstream.
+  it.skip("no raw `openspec status --json` outside the wrapper script", async () => {
     const here = path.dirname(url.fileURLToPath(import.meta.url));
     const repoRoot = path.resolve(here, "..", "..", "..", "..");
     const skillsRoot = path.resolve(repoRoot, ".pi", "skills");

package/packages/shared/src/__tests__/skill-block-parser.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest";
+import { parseSkillBlock, buildSkillBlock } from "../skill-block-parser.js";
+
+describe("parseSkillBlock", () => {
+  it("matches a well-formed wrapper with args", () => {
+    const text =
+      `<skill name="foo" location="/x/SKILL.md">\nReferences are relative to /x.\n\nbody\n</skill>\n\nargs here`;
+    const block = parseSkillBlock(text);
+    expect(block).not.toBeNull();
+    expect(block!.name).toBe("foo");
+    expect(block!.location).toBe("/x/SKILL.md");
+    expect(block!.body).toBe("body");
+    expect(block!.args).toBe("args here");
+    expect(block!.condensed).toBe("/skill:foo args here");
+  });
+
+  it("strips the 'References are relative to <baseDir>.\\n\\n' preamble from body", () => {
+    const text =
+      `<skill name="foo" location="/x/SKILL.md">\nReferences are relative to /x.\n\nfirst body line\nsecond body line\n</skill>`;
+    const block = parseSkillBlock(text);
+    expect(block!.body).toBe("first body line\nsecond body line");
+    expect(block!.body.startsWith("References are relative")).toBe(false);
+  });
+
+  it("falls back to verbatim content when preamble is absent", () => {
+    // Hand-crafted wrapper without the standard preamble (defensive: pi may evolve).
+    const text = `<skill name="foo" location="/x">\nbody only\n</skill>`;
+    expect(parseSkillBlock(text)!.body).toBe("body only");
+  });
+
+  it("matches a wrapper without args (no preamble)", () => {
+    const text = `<skill name="foo" location="/x">\nbody\n</skill>`;
+    const block = parseSkillBlock(text);
+    expect(block).not.toBeNull();
+    expect(block!.args).toBeUndefined();
+    expect(block!.condensed).toBe("/skill:foo");
+    expect(block!.body).toBe("body");
+  });
+
+  it("preserves multi-line user args verbatim", () => {
+    const text =
+      `<skill name="foo" location="/x">\nbody\n</skill>\n\nline1\nline2\nline3`;
+    const block = parseSkillBlock(text);
+    expect(block!.args).toBe("line1\nline2\nline3");
+    expect(block!.condensed).toBe("/skill:foo line1\nline2\nline3");
+  });
+
+  it("returns null for plain text", () => {
+    expect(parseSkillBlock("Hello, this is just text.")).toBeNull();
+    expect(parseSkillBlock("")).toBeNull();
+    expect(parseSkillBlock("/skill:foo args (unexpanded)")).toBeNull();
+  });
+
+  it("returns null for mid-document <skill> (anchor enforcement)", () => {
+    const text = `prefix\n<skill name="foo" location="/x">\nbody\n</skill>`;
+    expect(parseSkillBlock(text)).toBeNull();
+  });
+
+  it("returns null for trailing whitespace after </skill>", () => {
+    // Anchor end-of-string: a stray newline after </skill> with no args fails the optional-args group.
+    const text = `<skill name="foo" location="/x">\nbody\n</skill>\n`;
+    expect(parseSkillBlock(text)).toBeNull();
+  });
+
+  it("does not terminate prematurely on body containing literal <skill> text", () => {
+    const text =
+      `<skill name="real" location="/x">\nReferences are relative to /x.\n\nDocumented like: <skill name="example">…</skill>\nThat ended.\n</skill>`;
+    const block = parseSkillBlock(text);
+    expect(block).not.toBeNull();
+    expect(block!.name).toBe("real");
+    expect(block!.body).toContain('Documented like: <skill name="example">…</skill>');
+    expect(block!.body).toContain("That ended.");
+    // preamble was stripped — body starts with the user-visible content
+    expect(block!.body.startsWith("Documented")).toBe(true);
+  });
+
+  it("handles an empty body (no preamble)", () => {
+    const text = `<skill name="empty" location="/x">\n\n</skill>`;
+    const block = parseSkillBlock(text);
+    expect(block).not.toBeNull();
+    expect(block!.body).toBe("");
+  });
+
+  it("condensed form has a single space between name and args", () => {
+    const text = `<skill name="x" location="/p">\nb\n</skill>\n\nfoo`;
+    expect(parseSkillBlock(text)!.condensed).toBe("/skill:x foo");
+  });
+
+  it("condensed form has no trailing space when args is absent", () => {
+    const text = `<skill name="x" location="/p">\nb\n</skill>`;
+    expect(parseSkillBlock(text)!.condensed).toBe("/skill:x");
+  });
+});
+
+describe("buildSkillBlock", () => {
+  it("emits pi's exact wrapper format with args", () => {
+    const out = buildSkillBlock({
+      name: "openspec-explore",
+      filePath: "/x/openspec-explore/SKILL.md",
+      baseDir: "/x/openspec-explore",
+      body: "Enter explore mode.",
+      userArgs: "continue with X",
+    });
+    expect(out).toBe(
+      `<skill name="openspec-explore" location="/x/openspec-explore/SKILL.md">\n` +
+        `References are relative to /x/openspec-explore.\n\n` +
+        `Enter explore mode.\n` +
+        `</skill>\n\n` +
+        `continue with X`,
+    );
+  });
+
+  it("emits wrapper without trailing args block when userArgs is absent", () => {
+    const out = buildSkillBlock({
+      name: "foo",
+      filePath: "/x/foo/SKILL.md",
+      baseDir: "/x/foo",
+      body: "body line",
+    });
+    expect(out.endsWith("</skill>")).toBe(true);
+    expect(out).not.toContain("</skill>\n\n");
+  });
+});
+
+describe("buildSkillBlock + parseSkillBlock round-trip", () => {
+  it("round-trips name / body / args (with args)", () => {
+    const built = buildSkillBlock({
+      name: "round",
+      filePath: "/p/SKILL.md",
+      baseDir: "/p",
+      body: "Some body\nwith multiple lines",
+      userArgs: "the args here",
+    });
+    const parsed = parseSkillBlock(built);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.name).toBe("round");
+    expect(parsed!.location).toBe("/p/SKILL.md");
+    expect(parsed!.body).toBe("Some body\nwith multiple lines");
+    expect(parsed!.args).toBe("the args here");
+  });
+
+  it("round-trips with no args", () => {
+    const built = buildSkillBlock({
+      name: "noargs",
+      filePath: "/p/SKILL.md",
+      baseDir: "/p",
+      body: "Body only",
+    });
+    const parsed = parseSkillBlock(built);
+    expect(parsed!.args).toBeUndefined();
+    expect(parsed!.condensed).toBe("/skill:noargs");
+  });
+});