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

package/packages/shared/src/__tests__/resolve-jiti.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from "vitest";
-import { buildJitiRegisterUrl, resolveJitiImport } from "../resolve-jiti.js";
+import {
+  buildJitiRegisterUrl,
+  resolveJitiImport,
+  pickJitiRegisterUrl,
+  pickJitiFromAnchor,
+  JITI_PACKAGES,
+} from "../resolve-jiti.js";
 
 describe("buildJitiRegisterUrl", () => {
   // Pure function: given a jiti package.json path, return the file:// URL of
@@ -38,16 +44,141 @@ describe("buildJitiRegisterUrl", () => {
 });
 
 describe("resolveJitiImport", () => {
-  // Integration-lite: in vitest context (not inside pi's jiti loader),
-  // process.argv[1] points at the test runner, not pi — so peer-dep
-  // resolution fails and the function throws a helpful error. The
-  // URL-contract behavior is covered by buildJitiRegisterUrl above.
+  // Integration-lite: behaviour depends on what's resolvable from
+  // process.argv[1] (the vitest runner). Two valid outcomes:
+  //   (a) vitest's own transitive `jiti` dep resolves → returns a URL.
+  //   (b) nothing resolves → throws the documented error.
+  // The URL-contract behaviour is covered by buildJitiRegisterUrl above
+  // and the lookup-order behaviour by pickJitiRegisterUrl below. This
+  // describe block exercises only the runtime-anchor branch.
 
-  it("throws with clear error when pi-coding-agent is not resolvable", () => {
-    expect(() => resolveJitiImport()).toThrow("Cannot find pi's TypeScript loader");
+  it("either returns a file:// URL or throws the documented error", () => {
+    let result: string | undefined;
+    let err: Error | undefined;
+    try {
+      result = resolveJitiImport();
+    } catch (e) {
+      err = e as Error;
+    }
+    if (result !== undefined) {
+      expect(result.startsWith("file://")).toBe(true);
+      expect(result.endsWith("/lib/jiti-register.mjs")).toBe(true);
+    } else {
+      expect(err).toBeDefined();
+      expect(err!.message).toContain("Cannot find pi's TypeScript loader");
+      expect(err!.message).toContain("pi-coding-agent");
+    }
+  });
+});
+
+describe("JITI_PACKAGES contract", () => {
+  // The lookup-order contract: upstream first, legacy fork as fallback.
+  // Pinned so a future contributor doesn't accidentally re-order and
+  // silently change resolution priority for users mid-migration.
+  // See change: pi-fork migration to @earendil-works (drops @oh-my-pi).
+  it("contains the supported provider names in lookup order", () => {
+    expect(JITI_PACKAGES).toEqual(["jiti", "@mariozechner/jiti"]);
+  });
+});
+
+describe("pickJitiRegisterUrl (test seam)", () => {
+  // Mock a Node-style resolver. Returns a path when the spec matches
+  // a configured "installed" package; throws like Node's resolve() does
+  // for unfound modules.
+  function makeResolver(installed: Record<string, string>) {
+    return (spec: string): string => {
+      if (spec in installed) return installed[spec];
+      throw new Error(`Cannot find module '${spec}'`);
+    };
+  }
+
+  it("returns @mariozechner/jiti's URL when only the legacy fork is installed", () => {
+    const resolver = makeResolver({
+      "@mariozechner/jiti/package.json": "/r/node_modules/@mariozechner/jiti/package.json",
+    });
+    const url = pickJitiRegisterUrl(resolver);
+    expect(url).not.toBeNull();
+    expect(url!).toContain("@mariozechner/jiti");
+    expect(url!.endsWith("/lib/jiti-register.mjs")).toBe(true);
+  });
+
+  it("returns upstream jiti's URL when only upstream is installed (pi 0.73.1+)", () => {
+    const resolver = makeResolver({
+      "jiti/package.json": "/r/node_modules/jiti/package.json",
+    });
+    const url = pickJitiRegisterUrl(resolver);
+    expect(url).not.toBeNull();
+    // Match `/jiti/lib/...` but NOT `/@mariozechner/jiti/lib/...`
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+    expect(url!).not.toContain("@mariozechner");
+    expect(url!).not.toContain("@oh-my-pi");
+  });
+
+  it("prefers upstream jiti when BOTH upstream and legacy fork are present", () => {
+    const calls: string[] = [];
+    const resolver = (spec: string): string => {
+      calls.push(spec);
+      if (
+        spec === "@mariozechner/jiti/package.json" ||
+        spec === "jiti/package.json"
+      ) {
+        return `/r/node_modules/${spec}`;
+      }
+      throw new Error("nope");
+    };
+    const url = pickJitiRegisterUrl(resolver);
+    // Match `/jiti/lib/...` but NOT `/@mariozechner/jiti/lib/...`
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+    expect(url!).not.toContain("@mariozechner");
+    // Crucially: the resolver was NOT asked for the legacy fork because
+    // upstream won first.
+    expect(calls).toEqual(["jiti/package.json"]);
+  });
+
+  it("returns null when no provider resolves", () => {
+    const resolver = makeResolver({});
+    expect(pickJitiRegisterUrl(resolver)).toBeNull();
+  });
+});
+
+describe("pickJitiFromAnchor (test seam)", () => {
+  function makeResolver(installed: Record<string, string>) {
+    return (spec: string): string => {
+      if (spec in installed) return installed[spec];
+      throw new Error(`Cannot find module '${spec}'`);
+    };
+  }
+
+  it("returns upstream jiti's URL when only upstream is on the anchor's chain", () => {
+    const resolver = makeResolver({
+      "jiti/package.json": "/anchor/node_modules/jiti/package.json",
+    });
+    const pathExists = (p: string): boolean =>
+      p === "/anchor/node_modules/jiti/lib/jiti-register.mjs";
+    const url = pickJitiFromAnchor(resolver, pathExists);
+    expect(url).not.toBeNull();
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+  });
+
+  it("skips a provider whose register file does not exist on disk", () => {
+    // Resolver finds package.json but jiti-register.mjs is missing
+    // (corrupt install). Expect skip-to-next, ultimately null.
+    const resolver = makeResolver({
+      "@mariozechner/jiti/package.json":
+        "/anchor/node_modules/@mariozechner/jiti/package.json",
+    });
+    const pathExists = (): boolean => false;
+    expect(pickJitiFromAnchor(resolver, pathExists)).toBeNull();
   });
 
-  it("error message mentions pi-coding-agent", () => {
-    expect(() => resolveJitiImport()).toThrow("pi-coding-agent");
+  it("returns null when nothing resolves", () => {
+    expect(
+      pickJitiFromAnchor(
+        () => {
+          throw new Error("nope");
+        },
+        () => true,
+      ),
+    ).toBeNull();
   });
 });

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");
+  });
+});

package/packages/shared/src/__tests__/tool-registry-definitions.test.ts

@@ -104,7 +104,7 @@ describe("pi binary definition", () => {
 });
 
 describe("pi-coding-agent module definition", () => {
-  it("probes both @mariozechner and @oh-my-pi alias names", () => {
+  it("probes both @earendil-works (preferred) and @mariozechner (legacy fallback) alias names", () => {
     const r = freshRegistry({ exists: () => false });
     const res = r.resolve("pi-coding-agent");
     const names = res.tried.map((t) => t.strategy);

package/packages/shared/src/bootstrap-install.ts

@@ -12,8 +12,15 @@
  *
  * See change: unified-bootstrap-install.
  */
-import { spawn as cpSpawn } from "./platform/exec.js";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { spawn as cpSpawn, spawnSync as cpSpawnSync } from "./platform/exec.js";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import path from "node:path";
 import { getManagedDir } from "./managed-paths.js";
 import { getDefaultRegistry, type ToolRegistry } from "./tool-registry/index.js";
@@ -206,7 +213,194 @@ export async function bootstrapInstallDefaults(
   progress?: ProgressCallback,
 ): Promise<BootstrapInstallResult> {
   return bootstrapInstall({
-    packages: ["@mariozechner/pi-coding-agent", "@fission-ai/openspec", "tsx"],
+    packages: ["@earendil-works/pi-coding-agent", "@fission-ai/openspec", "tsx"],
     progress,
   });
 }
+
+// ── Managed Node runtime install ───────────────────────────────────────
+//
+// See change: embed-managed-node-runtime (spec: managed-node-runtime).
+//
+// `installManagedNode` copies a bundled Node distribution into
+// `<managedDir>/node/` and writes a `<managedDir>/node/.version` marker.
+// Idempotent: skip when marker matches the bundled version, replace on
+// mismatch, no-op when the bundled source isn't available (standalone
+// CLI install with no Electron resources).
+
+export interface InstallManagedNodeOptions {
+  /**
+   * Source directory containing the bundled Node distribution.
+   * Layout matches the upstream Node zip/tar:
+   *   Windows: `<dir>/node.exe`, `<dir>/npm.cmd`, `<dir>/npx.cmd`
+   *   Unix:    `<dir>/bin/node`, `<dir>/bin/npm`, `<dir>/bin/npx`
+   *
+   * Caller resolves this (Electron uses `path.dirname(getBundledNodePath())`
+   * after stripping the platform-specific suffix). Pass `null` /
+   * `undefined` for the standalone CLI install case — the function
+   * no-ops without error.
+   */
+  bundledNodeDir?: string | null;
+  /** Root of the managed install. Defaults to `getManagedDir()`. */
+  managedDir?: string;
+  /** Called on every progress tick. Mirrors `bootstrapInstall` shape. */
+  progress?: ProgressCallback;
+  /**
+   * Test seam: override how the bundled Node version is read. Default
+   * spawns `<bundledNodeDir>/bin/node --version` (or `node.exe` on
+   * Windows) and trims stdout. Tests inject a fake to avoid real spawns.
+   */
+  _readVersion?: (sourceBinary: string) => string | null;
+}
+
+export interface InstallManagedNodeResult {
+  /** True iff the operation succeeded (including the no-op cases). */
+  ok: boolean;
+  /** Did we actually copy files? false when no-op or skipped. */
+  copied: boolean;
+  /** Resolved managed Node directory (`<managedDir>/node`). */
+  managedNodeDir: string;
+  /** Bundled Node version (e.g. `v22.12.0`) when known. */
+  version?: string;
+  /** Reason for skip / failure. Always set when `copied === false`. */
+  reason?: string;
+  /** Error message when `ok === false`. */
+  error?: string;
+}
+
+/** Path to the source `node` / `node.exe` binary inside `bundledNodeDir`. */
+function sourceNodeBinary(bundledNodeDir: string): string {
+  return process.platform === "win32" // platform-branch-ok: Node distribution layout differs Windows vs Unix
+    ? path.join(bundledNodeDir, "node.exe")
+    : path.join(bundledNodeDir, "bin", "node");
+}
+
+/**
+ * Spawn `<nodeBinary> --version` and return the trimmed stdout (e.g.
+ * `v22.12.0`). Returns null on failure or when the binary is missing.
+ * Synchronous because bootstrap is naturally serial.
+ */
+function readNodeVersion(nodeBinary: string): string | null {
+  if (!existsSync(nodeBinary)) return null;
+  try {
+    const r = cpSpawnSync(nodeBinary, ["--version"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 5_000,
+      encoding: "utf-8",
+    });
+    if (r.status !== 0) return null;
+    const out = (r.stdout ?? "").toString().trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read the `<managedNodeDir>/.version` marker if present, else null. */
+function readManagedMarker(managedNodeDir: string): string | null {
+  const markerPath = path.join(managedNodeDir, ".version");
+  if (!existsSync(markerPath)) return null;
+  try {
+    return readFileSync(markerPath, "utf-8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Idempotently copy the bundled Node distribution into `<managedDir>/node/`.
+ *
+ * - First-run: full recursive copy + write `.version` marker.
+ * - Re-run with matching marker: no-op.
+ * - Mismatched marker (or missing marker with dir present): replace +
+ *   rewrite marker.
+ * - Bundled source absent or `bundledNodeDir == null`: no-op.
+ * - Failed copy mid-flight: marker NOT written, so next call retries.
+ */
+export async function installManagedNode(
+  opts: InstallManagedNodeOptions = {},
+): Promise<InstallManagedNodeResult> {
+  const managedDir = opts.managedDir ?? getManagedDir();
+  const managedNodeDir = path.join(managedDir, "node");
+  const step = "node-runtime";
+
+  const bundledDir = opts.bundledNodeDir ?? null;
+  if (!bundledDir) {
+    return {
+      ok: true,
+      copied: false,
+      managedNodeDir,
+      reason: "no bundled source",
+    };
+  }
+
+  const sourceBinary = sourceNodeBinary(bundledDir);
+  const sourceVersion = (opts._readVersion ?? readNodeVersion)(sourceBinary);
+  if (!sourceVersion) {
+    return {
+      ok: true,
+      copied: false,
+      managedNodeDir,
+      reason: `bundled node binary missing or unreadable: ${sourceBinary}`,
+    };
+  }
+
+  const existingMarker = readManagedMarker(managedNodeDir);
+  if (existingMarker === sourceVersion) {
+    return {
+      ok: true,
+      copied: false,
+      managedNodeDir,
+      version: sourceVersion,
+      reason: "version matches bundled — no copy needed",
+    };
+  }
+
+  opts.progress?.({
+    step,
+    status: "running",
+    output: `Installing Node ${sourceVersion} runtime`,
+  });
+
+  try {
+    // Replace any existing dir (handles the mismatch + missing-marker
+    // cases) so the copy is from a clean slate.
+    if (existsSync(managedNodeDir)) {
+      rmSync(managedNodeDir, { recursive: true, force: true });
+    }
+    mkdirSync(path.dirname(managedNodeDir), { recursive: true });
+
+    cpSync(bundledDir, managedNodeDir, {
+      recursive: true,
+      force: true,
+      // dereference: false keeps symlinks-as-symlinks (Unix npm shim).
+      // verbatimSymlinks would also work in newer Node; default is fine.
+    });
+
+    // Marker last — partial copy on failure leaves no marker, so the
+    // next invocation treats the dir as missing and retries.
+    writeFileSync(
+      path.join(managedNodeDir, ".version"),
+      sourceVersion + "\n",
+      "utf-8",
+    );
+
+    opts.progress?.({ step, status: "done", output: `Node ${sourceVersion}` });
+    return {
+      ok: true,
+      copied: true,
+      managedNodeDir,
+      version: sourceVersion,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    opts.progress?.({ step, status: "error", error: message });
+    return {
+      ok: false,
+      copied: false,
+      managedNodeDir,
+      version: sourceVersion,
+      error: message,
+    };
+  }
+}