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

package/packages/shared/src/__tests__/node-spawn.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Tests for `platform/node-spawn.ts` — the canonical helper for
+ * constructing `node --import <loader> <entry>` argv.
+ *
+ * See change: fix-windows-entry-script-url.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { toFileUrl, spawnNodeScript, isTsxLoader, shouldUrlWrapEntry } from "../platform/node-spawn.js";
+import * as execModule from "../platform/exec.js";
+
+describe("toFileUrl", () => {
+  it("returns a file:// URL input unchanged (idempotent)", () => {
+    expect(toFileUrl("file:///C:/foo.ts")).toBe("file:///C:/foo.ts");
+    expect(toFileUrl("file:///usr/local/bin/cli.js")).toBe("file:///usr/local/bin/cli.js");
+  });
+
+  it("wraps Windows B:\\ drive-letter paths on any host OS", () => {
+    expect(toFileUrl("B:\\Dev\\cli.ts")).toBe("file:///B:/Dev/cli.ts");
+  });
+
+  it("wraps Windows C:\\ drive-letter paths on any host OS", () => {
+    expect(toFileUrl("C:\\Users\\x\\cli.ts")).toBe("file:///C:/Users/x/cli.ts");
+  });
+
+  it("wraps forward-slash Windows paths", () => {
+    expect(toFileUrl("B:/Dev/cli.ts")).toBe("file:///B:/Dev/cli.ts");
+  });
+
+  it("wraps POSIX absolute paths", () => {
+    expect(toFileUrl("/usr/local/bin/cli.js")).toBe("file:///usr/local/bin/cli.js");
+  });
+
+  it("handles uppercase and lowercase drive letters identically", () => {
+    expect(toFileUrl("b:\\Dev\\cli.ts")).toBe("file:///b:/Dev/cli.ts");
+    expect(toFileUrl("Z:\\foo.ts")).toBe("file:///Z:/foo.ts");
+  });
+});
+
+describe("isTsxLoader", () => {
+  it("returns true for loader URLs containing /tsx/", () => {
+    expect(isTsxLoader("file:///home/x/node_modules/tsx/dist/esm/index.mjs")).toBe(true);
+    expect(isTsxLoader("file:///C:/project/node_modules/tsx/dist/esm/index.mjs")).toBe(true);
+  });
+
+  it("returns true for raw paths with /tsx/ segment", () => {
+    expect(isTsxLoader("/home/x/node_modules/tsx/dist/esm/index.mjs")).toBe(true);
+  });
+
+  it("returns true for Windows raw paths with \\tsx\\ segment", () => {
+    expect(isTsxLoader("C:\\project\\node_modules\\tsx\\dist\\esm\\index.mjs")).toBe(true);
+  });
+
+  it("returns false for jiti loader", () => {
+    expect(isTsxLoader("file:///home/x/node_modules/@mariozechner/jiti/lib/jiti-register.mjs")).toBe(false);
+    expect(isTsxLoader("/home/x/node_modules/@mariozechner/jiti/lib/jiti-register.mjs")).toBe(false);
+  });
+
+  it("returns false for undefined / empty", () => {
+    expect(isTsxLoader(undefined)).toBe(false);
+    expect(isTsxLoader("")).toBe(false);
+  });
+});
+
+describe("spawnNodeScript", () => {
+  it("URL-wraps both loader and entry when loader is NOT tsx (jiti/default)", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      nodeBin: "C:\\Program Files\\nodejs\\node.exe",
+      loader: "B:\\jiti\\register.mjs",
+      entry: "B:\\Dev\\cli.ts",
+      args: ["start", "--dev"],
+    });
+
+    expect(spawnSpy).toHaveBeenCalledTimes(1);
+    const [bin, argv] = spawnSpy.mock.calls[0]!;
+    expect(bin).toBe("C:\\Program Files\\nodejs\\node.exe");
+    // On Linux host: entry stays raw even with a Windows-styled path
+    // (shouldUrlWrapEntry consults process.platform, which is Linux).
+    // The Windows-wrapped branch is exercised separately via shouldUrlWrapEntry.
+    expect(argv).toEqual([
+      "--import",
+      "file:///B:/jiti/register.mjs",
+      "B:\\Dev\\cli.ts",
+      "start",
+      "--dev",
+    ]);
+
+    spawnSpy.mockRestore();
+  });
+
+  it("URL-wraps loader but passes RAW entry when loader is tsx", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      nodeBin: "/usr/bin/node",
+      loader: "/home/u/node_modules/tsx/dist/esm/index.mjs",
+      entry: "/home/u/repo/packages/server/src/cli.ts",
+      args: ["start"],
+    });
+
+    const [, argv] = spawnSpy.mock.calls[0]!;
+    expect(argv).toEqual([
+      "--import",
+      "file:///home/u/node_modules/tsx/dist/esm/index.mjs",
+      "/home/u/repo/packages/server/src/cli.ts",  // RAW, not URL
+      "start",
+    ]);
+    spawnSpy.mockRestore();
+  });
+
+  it("defaults nodeBin to process.execPath when omitted", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      entry: "/usr/local/cli.ts",
+    });
+
+    const [bin] = spawnSpy.mock.calls[0]!;
+    expect(bin).toBe(process.execPath);
+    spawnSpy.mockRestore();
+  });
+
+  it("omits --import when no loader is provided", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      entry: "B:\\Dev\\cli.ts",
+      args: ["help"],
+    });
+
+    const [, argv] = spawnSpy.mock.calls[0]!;
+    // No loader → shouldUrlWrapEntry returns false on Linux host → raw entry.
+    expect(argv).toEqual(["B:\\Dev\\cli.ts", "help"]);
+    spawnSpy.mockRestore();
+  });
+
+  it("passes spawnOptions through to exec.spawn unchanged", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    const opts = { detached: true, stdio: ["ignore", 1, 2] as ("ignore" | number)[], env: { FOO: "bar" } };
+    spawnNodeScript({
+      entry: "/usr/local/cli.ts",
+      spawnOptions: opts,
+    });
+
+    const [, , passedOpts] = spawnSpy.mock.calls[0]!;
+    expect(passedOpts).toBe(opts);
+    spawnSpy.mockRestore();
+  });
+
+  it("accepts a loader that is already a file:// URL without double-wrapping", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      loader: "file:///C:/jiti/register.mjs",
+      entry: "B:\\Dev\\cli.ts",
+    });
+
+    const [, argv] = spawnSpy.mock.calls[0]!;
+    // On Linux host with non-tsx loader: entry stays raw.
+    expect(argv).toEqual([
+      "--import",
+      "file:///C:/jiti/register.mjs",
+      "B:\\Dev\\cli.ts",
+    ]);
+    spawnSpy.mockRestore();
+  });
+});
+
+describe("shouldUrlWrapEntry", () => {
+  it("returns false for tsx loader on any platform", () => {
+    const tsxLoader = "file:///home/u/node_modules/tsx/dist/esm/index.mjs";
+    expect(shouldUrlWrapEntry(tsxLoader, "linux")).toBe(false);
+    expect(shouldUrlWrapEntry(tsxLoader, "darwin")).toBe(false);
+    expect(shouldUrlWrapEntry(tsxLoader, "win32")).toBe(false);
+  });
+
+  it("returns false for non-tsx loader on POSIX (jiti MUST get raw entry)", () => {
+    const jiti = "file:///home/u/node_modules/@mariozechner/jiti/lib/jiti-register.mjs";
+    expect(shouldUrlWrapEntry(jiti, "linux")).toBe(false);
+    expect(shouldUrlWrapEntry(jiti, "darwin")).toBe(false);
+  });
+
+  it("returns true for non-tsx loader on Windows (drive letters need file://)", () => {
+    const jiti = "file:///C:/node_modules/@mariozechner/jiti/lib/jiti-register.mjs";
+    expect(shouldUrlWrapEntry(jiti, "win32")).toBe(true);
+  });
+
+  it("returns false when no loader is provided, regardless of platform", () => {
+    // Without a loader, Node's default resolver handles the entry; the URL
+    // wrap was historically used for Windows drive-letter collision, but
+    // if we were to spawn without a loader we'd still default to raw on POSIX.
+    // On Windows without a loader, callers should wrap themselves.
+    expect(shouldUrlWrapEntry(undefined, "linux")).toBe(false);
+    expect(shouldUrlWrapEntry(undefined, "darwin")).toBe(false);
+  });
+});

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

@@ -0,0 +1,108 @@
+/**
+ * Tests for packages/shared/src/platform/commands.ts.
+ * Platform behavior exercised via injected `platform` + `exec` / `asyncExec`.
+ * See change: consolidate-platform-handlers.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { openBrowser, isVirtualMachine } from "../platform/commands.js";
+
+describe("openBrowser", () => {
+  it("uses `open` on macOS", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser("https://example.com", { platform: "darwin", asyncExec });
+    expect(asyncExec).toHaveBeenCalledOnce();
+    expect(asyncExec.mock.calls[0][0]).toMatch(/^open\s+"https:\/\/example\.com"$/);
+  });
+
+  it("uses `start` on Windows", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser("https://example.com", { platform: "win32", asyncExec });
+    expect(asyncExec.mock.calls[0][0]).toMatch(/^start\s+""\s+"https:\/\/example\.com"$/);
+  });
+
+  it("uses `xdg-open` on Linux", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser("https://example.com", { platform: "linux", asyncExec });
+    expect(asyncExec.mock.calls[0][0]).toMatch(/^xdg-open\s+"https:\/\/example\.com"$/);
+  });
+
+  it("escapes URLs via JSON.stringify (quotes, newlines, backslashes)", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser('https://example.com/?q="escaped"', { platform: "linux", asyncExec });
+    // JSON.stringify converts " → \"
+    expect(asyncExec.mock.calls[0][0]).toContain('\\"escaped\\"');
+  });
+
+  it("invokes onError callback when async exec fails", () => {
+    const err = new Error("nope");
+    const onError = vi.fn();
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(err));
+    openBrowser("https://example.com", { platform: "linux", asyncExec, onError });
+    expect(onError).toHaveBeenCalledWith(err);
+  });
+
+  it("does not throw when onError is absent", () => {
+    const err = new Error("nope");
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(err));
+    expect(() =>
+      openBrowser("https://example.com", { platform: "linux", asyncExec }),
+    ).not.toThrow();
+  });
+});
+
+describe("isVirtualMachine", () => {
+  it("detects VMware via sysctl on macOS", () => {
+    const exec = vi.fn().mockReturnValue("VMware7,1\n");
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(true);
+  });
+
+  it("detects VirtualBox via sysctl on macOS", () => {
+    const exec = vi.fn().mockReturnValue("VirtualBox6,0\n");
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(true);
+  });
+
+  it("returns false on physical macOS hardware", () => {
+    const exec = vi.fn().mockReturnValue("MacBookPro18,3\n");
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(false);
+  });
+
+  it("detects VM via systemd-detect-virt on Linux", () => {
+    const exec = vi.fn().mockReturnValue("kvm\n");
+    expect(isVirtualMachine({ platform: "linux", exec })).toBe(true);
+  });
+
+  it("returns false on bare-metal Linux", () => {
+    const exec = vi.fn().mockReturnValue("none\n");
+    expect(isVirtualMachine({ platform: "linux", exec })).toBe(false);
+  });
+
+  it("detects VMware via wmic on Windows", () => {
+    const exec = vi.fn().mockImplementation((cmd: string) => {
+      if (cmd.includes("bios")) return "SerialNumber\nVMware-42 AA BB\n";
+      return "";
+    });
+    expect(isVirtualMachine({ platform: "win32", exec })).toBe(true);
+  });
+
+  it("detects Hyper-V via wmic computersystem on Windows", () => {
+    const exec = vi.fn().mockImplementation((cmd: string) => {
+      if (cmd.includes("bios")) throw new Error("no serial");
+      if (cmd.includes("computersystem")) return "Manufacturer  Model\nMicrosoft Corporation  Virtual Machine\n";
+      return "";
+    });
+    expect(isVirtualMachine({ platform: "win32", exec })).toBe(true);
+  });
+
+  it("returns false on physical Windows when no VM markers found", () => {
+    const exec = vi.fn().mockReturnValue("SerialNumber\nR90ABCDE\n");
+    expect(isVirtualMachine({ platform: "win32", exec })).toBe(false);
+  });
+
+  it("returns false when exec throws unexpectedly", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("boom");
+    });
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(false);
+    expect(isVirtualMachine({ platform: "linux", exec })).toBe(false);
+  });
+});

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

@@ -0,0 +1,103 @@
+/**
+ * Tests for packages/shared/src/platform/exec.ts — the thin wrapper over
+ * node:child_process that sets `windowsHide: true` by default.
+ *
+ * These tests assert the *option passthrough* contract; they do not spawn
+ * real subprocesses. The wrapper is a few lines per function — its only
+ * job is to forward arguments with `windowsHide: true` layered on top.
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect } from "vitest";
+import { execSync, spawn, spawnSync, exec, execFile } from "../platform/exec.js";
+
+describe("platform/exec wrappers", () => {
+  // ── execSync ────────────────────────────────────────────────────────────
+  // Real invocation: we pick commands that exit 0 on every OS (node itself).
+
+  it("execSync exits 0 for `node --version`", () => {
+    const out = execSync(`"${process.execPath}" --version`, { encoding: "utf-8" });
+    expect(String(out).trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+
+  // ── spawnSync ───────────────────────────────────────────────────────────
+
+  it("spawnSync runs `node --version` and captures stdout", () => {
+    const result = spawnSync(process.execPath, ["--version"], { encoding: "utf-8" });
+    expect(result.status).toBe(0);
+    expect(String(result.stdout).trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+
+  it("spawnSync accepts undefined args and defaults to []", () => {
+    // Should not throw — wrapper must coerce undefined args to []
+    const result = spawnSync(process.execPath, undefined, {
+      encoding: "utf-8",
+      input: "process.stdout.write('ok')",
+    });
+    // May or may not work depending on shell, but the call itself must not throw.
+    expect(typeof result).toBe("object");
+  });
+
+  // ── windowsHide default ─────────────────────────────────────────────────
+
+  // The key invariant: wrappers set windowsHide: true when caller omits it.
+  // We verify this by inspecting the spawn metadata (spawnargs / opts).
+  // Node doesn't expose the final options object, so we check by spawning
+  // with a non-overridden call and verifying it completes successfully
+  // (a misconfigured windowsHide would not change functional behavior,
+  // so the real assertion is in D10 below via source inspection).
+
+  it("spawn returns a ChildProcess object", async () => {
+    const child = spawn(process.execPath, ["--version"]);
+    expect(child.pid).toBeGreaterThan(0);
+    await new Promise<void>((resolve) => {
+      child.on("exit", () => resolve());
+    });
+  });
+
+  // ── exec (callback form) ────────────────────────────────────────────────
+
+  it("exec(cmd, cb) invokes callback with stdout", async () => {
+    const out = await new Promise<string>((resolve, reject) => {
+      exec(`"${process.execPath}" --version`, (err, stdout) => {
+        if (err) reject(err);
+        else resolve(String(stdout));
+      });
+    });
+    expect(out.trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+
+  // ── execFile ────────────────────────────────────────────────────────────
+
+  it("execFile(file, args, cb) works", async () => {
+    const out = await new Promise<string>((resolve, reject) => {
+      execFile(process.execPath, ["--version"], (err, stdout) => {
+        if (err) reject(err);
+        else resolve(String(stdout));
+      });
+    });
+    expect(out.trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+});
+
+describe("platform/exec — windowsHide default (source-level assertion)", () => {
+  // Since Node doesn't expose the spawn options after the call, we verify
+  // the windowsHide default by reading the wrapper source and asserting
+  // that every public export merges `windowsHide: true` into its options.
+  //
+  // This catches refactors that accidentally drop the default.
+
+  it("exec.ts source sets windowsHide: true by default", async () => {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const url = await import("node:url");
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const src = await fs.readFile(path.resolve(here, "../platform/exec.ts"), "utf-8");
+
+    // Must define a withHide helper and apply it uniformly.
+    expect(src).toMatch(/windowsHide\??:\s*boolean/);
+    expect(src).toMatch(/windowsHide:\s*hide/);
+    // Default must be true (not false) when caller omits it.
+    expect(src).toMatch(/opts\?\.windowsHide\s*\?\?\s*true/);
+  });
+});

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

@@ -0,0 +1,194 @@
+/**
+ * Tests for packages/shared/src/platform/git.ts — Recipe argv shapes +
+ * light integration tests against the actual repository.
+ *
+ * The argv-shape tests are pure: they verify the Recipe's `argv()`
+ * function produces the expected command without spawning anything.
+ *
+ * The integration tests use the actual repo as a git fixture; they're
+ * smoke tests that the full recipe → runner → git pipeline works.
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import url from "node:url";
+import {
+  GIT_DIFF,
+  GIT_STATUS_PORCELAIN,
+  GIT_IS_REPO,
+  GIT_CURRENT_BRANCH,
+  GIT_HEAD_SHA,
+  GIT_REMOTE_URL,
+  GH_PR_NUMBER,
+  GIT_RECIPES,
+  isGitRepo,
+  currentBranch,
+  headSha,
+  remoteUrl,
+  diff,
+  statusPorcelain,
+  isGitRepoOr,
+  currentBranchOr,
+} from "../platform/git.js";
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(here, "..", "..", "..", "..");
+
+// ── Pure argv tests ─────────────────────────────────────────────────────────
+
+describe("GIT_DIFF.argv", () => {
+  it("produces `git diff HEAD -- <path>` by default", () => {
+    expect(GIT_DIFF.argv({ cwd: "/tmp", path: "src/foo.ts" })).toEqual([
+      "git", "diff", "HEAD", "--", "src/foo.ts",
+    ]);
+  });
+
+  it("respects an explicit ref", () => {
+    expect(GIT_DIFF.argv({ cwd: "/tmp", path: "a.ts", ref: "main" })).toEqual([
+      "git", "diff", "main", "--", "a.ts",
+    ]);
+  });
+
+  it("does not shell-escape the path (argv array is passed verbatim)", () => {
+    // With argv arrays, paths like "a b.ts" flow through as one element.
+    // No JSON.stringify, no quoting — safe by construction.
+    expect(GIT_DIFF.argv({ cwd: "/tmp", path: "a b.ts" })).toEqual([
+      "git", "diff", "HEAD", "--", "a b.ts",
+    ]);
+  });
+
+  it("tolerates exit code 1 (no-diff or empty repo)", () => {
+    expect(GIT_DIFF.tolerate).toContain(1);
+  });
+});
+
+describe("GIT_STATUS_PORCELAIN.argv", () => {
+  it("omits `--` when no path is given", () => {
+    expect(GIT_STATUS_PORCELAIN.argv({ cwd: "/tmp" })).toEqual([
+      "git", "status", "--porcelain",
+    ]);
+  });
+
+  it("adds `-- <path>` when a path is given", () => {
+    expect(GIT_STATUS_PORCELAIN.argv({ cwd: "/tmp", path: "src/foo.ts" })).toEqual([
+      "git", "status", "--porcelain", "--", "src/foo.ts",
+    ]);
+  });
+});
+
+describe("other recipe argv shapes", () => {
+  it("GIT_IS_REPO", () => {
+    expect(GIT_IS_REPO.argv({ cwd: "/tmp" })).toEqual(["git", "rev-parse", "--is-inside-work-tree"]);
+  });
+
+  it("GIT_CURRENT_BRANCH", () => {
+    expect(GIT_CURRENT_BRANCH.argv({ cwd: "/tmp" })).toEqual(["git", "rev-parse", "--abbrev-ref", "HEAD"]);
+  });
+
+  it("GIT_HEAD_SHA (full)", () => {
+    expect(GIT_HEAD_SHA.argv({ cwd: "/tmp" })).toEqual(["git", "rev-parse", "HEAD"]);
+  });
+
+  it("GIT_HEAD_SHA (short)", () => {
+    expect(GIT_HEAD_SHA.argv({ cwd: "/tmp", short: true })).toEqual(["git", "rev-parse", "--short", "HEAD"]);
+  });
+
+  it("GIT_REMOTE_URL (default origin)", () => {
+    expect(GIT_REMOTE_URL.argv({ cwd: "/tmp" })).toEqual(["git", "remote", "get-url", "origin"]);
+  });
+
+  it("GIT_REMOTE_URL (custom remote)", () => {
+    expect(GIT_REMOTE_URL.argv({ cwd: "/tmp", remote: "upstream" })).toEqual([
+      "git", "remote", "get-url", "upstream",
+    ]);
+  });
+
+  it("GH_PR_NUMBER tolerates exit 1 (no PR)", () => {
+    expect(GH_PR_NUMBER.tolerate).toContain(1);
+    expect(GH_PR_NUMBER.argv({ cwd: "/tmp" })).toEqual([
+      "gh", "pr", "view", "--json", "number", "-q", ".number",
+    ]);
+  });
+});
+
+describe("GIT_RECIPES registry", () => {
+  it("enumerates all exported recipes", () => {
+    const keys = Object.keys(GIT_RECIPES).sort();
+    expect(keys).toEqual([
+      "GH_PR_NUMBER",
+      "GIT_CURRENT_BRANCH",
+      "GIT_DIFF",
+      "GIT_HEAD_SHA",
+      "GIT_IS_REPO",
+      "GIT_REMOTE_URL",
+      "GIT_STATUS_PORCELAIN",
+    ]);
+  });
+
+  it("every recipe has argv and parse functions", () => {
+    for (const [name, recipe] of Object.entries(GIT_RECIPES)) {
+      expect(typeof recipe.argv, `${name}.argv`).toBe("function");
+      expect(typeof recipe.parse, `${name}.parse`).toBe("function");
+    }
+  });
+});
+
+// ── Integration tests against the actual repository ────────────────────────
+
+describe("git.* integration (runs against this repo)", () => {
+  it("isGitRepo returns true for the repo root", () => {
+    const result = isGitRepo({ cwd: REPO_ROOT });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(true);
+  });
+
+  it("isGitRepoOr returns false for a non-repo directory", () => {
+    expect(isGitRepoOr({ cwd: require("node:os").tmpdir() })).toBe(false);
+  });
+
+  it("currentBranch returns a string for the repo", () => {
+    const result = currentBranch({ cwd: REPO_ROOT });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(typeof result.value).toBe("string");
+      expect(result.value!.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("headSha returns a 40-char SHA for the repo", () => {
+    const result = headSha({ cwd: REPO_ROOT });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it("headSha short returns a 7-char SHA", () => {
+    const result = headSha({ cwd: REPO_ROOT, short: true });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toMatch(/^[0-9a-f]{7}/);
+  });
+
+  it("remoteUrl returns a URL string if origin is set", () => {
+    // This repo has an origin remote; the value is non-empty.
+    const result = remoteUrl({ cwd: REPO_ROOT });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  it("statusPorcelain returns a string (possibly empty)", () => {
+    const result = statusPorcelain({ cwd: REPO_ROOT });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(typeof result.value).toBe("string");
+  });
+
+  it("diff with exit-1 tolerance does not throw for a clean path", () => {
+    // Pick a file guaranteed to exist and typically be unchanged in test runs.
+    const result = diff({ cwd: REPO_ROOT, path: "package.json" });
+    // tolerate: [1] means no diff is still ok
+    expect(result.ok).toBe(true);
+  });
+
+  it("currentBranchOr returns a fallback when cwd is not a repo", () => {
+    expect(currentBranchOr({ cwd: require("node:os").tmpdir() }, "no-repo")).toBe("no-repo");
+  });
+});