@stigmer/cli 3.0.8

package/src/local/state/pidfile.ts

@@ -0,0 +1,37 @@
+// PID-file read/write/remove helpers.
+//
+// PID files are how the daemon, its children, and a fresh CLI invocation find
+// each other across process boundaries. Some PID files written by other tools
+// (notably Temporal's) carry extra lines after the PID; readPidFile reads only
+// the first line so it tolerates both single-line and multi-line formats.
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Write a PID file (creating its directory if needed). */
+export function writePidFile(path: string, pid: number): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${pid}\n`, "utf8");
+}
+
+/**
+ * Read a PID from a PID file. Returns null if the file is missing or its first
+ * line is not a positive integer, so callers branch on presence rather than
+ * catching exceptions.
+ */
+export function readPidFile(path: string): number | null {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  const firstLine = raw.split("\n", 1)[0]?.trim() ?? "";
+  const pid = Number.parseInt(firstLine, 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+/** Remove a PID file. Best-effort: a missing file is not an error. */
+export function removePidFile(path: string): void {
+  rmSync(path, { force: true });
+}

package/src/local/state/proc.ts

@@ -0,0 +1,66 @@
+// OS-level process queries used by supervision and status.
+//
+// Liveness is a signal-0 probe (no signal delivered, only permission/existence
+// checked) — the same mechanism the Go CLI uses. The port-based lookup is a
+// fallback for locating the daemon when its PID file is missing; it shells to
+// `lsof`, so it is POSIX-only and best-effort (returns null on any failure).
+
+import { execFileSync } from "node:child_process";
+
+/** Report whether a process with the given PID currently exists. */
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but is owned by another user — still alive.
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** Send a signal to a single process. Returns false if the process is gone. */
+export function killProcess(pid: number, signal: NodeJS.Signals = "SIGTERM"): boolean {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Signal an entire process group (POSIX: kill(-pid)). The target must have been
+ * spawned as a group leader (`detached: true`) for this to reach its children.
+ * Returns false if the group is already gone.
+ */
+export function killProcessGroup(pid: number, signal: NodeJS.Signals = "SIGTERM"): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch {
+    // Fall back to signaling just the leader (e.g. non-POSIX or already reaped).
+    return killProcess(pid, signal);
+  }
+}
+
+/**
+ * Find the PID of the process listening on a TCP port via `lsof`. Returns null
+ * if nothing is listening or `lsof` is unavailable. POSIX-only fallback.
+ */
+export function findProcessByPort(port: number): number | null {
+  let output: string;
+  try {
+    output = execFileSync("lsof", ["-t", "-i", `:${port}`, "-sTCP:LISTEN"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+  const firstLine = output.split("\n").find((line) => line.trim() !== "");
+  if (firstLine === undefined) return null;
+  const pid = Number.parseInt(firstLine.trim(), 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}

package/src/local/state/startup-config.ts

@@ -0,0 +1,51 @@
+// Configuration captured at `up` time so the daemon can restart components with
+// the same settings the user launched with. Persisted as `startup-config.json`
+// in the data dir; JSON keys are snake_case to match the Go CLI's file.
+
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { STARTUP_CONFIG_FILE } from "../constants.js";
+
+/** The persisted launch configuration. Mirrors the Go `StartupConfig` struct. */
+export interface StartupConfig {
+  data_dir: string;
+  log_dir: string;
+  temporal_addr: string;
+  llm_provider: string;
+  llm_model: string;
+  llm_base_url: string;
+  execution_mode: string;
+  sandbox_image: string;
+  sandbox_auto_pull: boolean;
+  sandbox_cleanup: boolean;
+  sandbox_ttl: number;
+  stigmer_server_pid: number;
+  server_only: boolean;
+}
+
+/** Write the startup config into the data dir. */
+export function saveStartupConfig(dataDir: string, config: StartupConfig): void {
+  const path = join(dataDir, STARTUP_CONFIG_FILE);
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+/** Load the startup config from the data dir, or null if absent/unreadable. */
+export function loadStartupConfig(dataDir: string): StartupConfig | null {
+  const path = join(dataDir, STARTUP_CONFIG_FILE);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw) as StartupConfig;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove the startup config (best-effort). */
+export function removeStartupConfig(dataDir: string): void {
+  rmSync(join(dataDir, STARTUP_CONFIG_FILE), { force: true });
+}

package/src/local/state/state.test.ts

@@ -0,0 +1,166 @@
+import { mkdtempSync, readFileSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { type HealthState, loadHealthState, writeHealthState } from "./health-state.js";
+import { acquireLock } from "./lock.js";
+import { cleanupOldLogs, rotateLogs } from "./log-rotation.js";
+import { readPidFile, removePidFile, writePidFile } from "./pidfile.js";
+import { isProcessAlive } from "./proc.js";
+import { loadStartupConfig, removeStartupConfig, saveStartupConfig, type StartupConfig } from "./startup-config.js";
+
+function tempDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+// A PID that is exceedingly unlikely to belong to a live process.
+const DEAD_PID = 2 ** 31 - 1;
+
+describe("pidfile", () => {
+  it("writes, reads, and removes a PID", () => {
+    const path = join(tempDir("stigmer-pid-"), "daemon.pid");
+    writePidFile(path, 4321);
+    expect(readPidFile(path)).toBe(4321);
+    removePidFile(path);
+    expect(readPidFile(path)).toBeNull();
+  });
+
+  it("returns null for a missing file", () => {
+    expect(readPidFile(join(tempDir("stigmer-pid-"), "absent.pid"))).toBeNull();
+  });
+
+  it("reads only the first line of a multi-line (Temporal-style) PID file", () => {
+    const path = join(tempDir("stigmer-pid-"), "temporal.pid");
+    writeFileSync(path, "1234\ntemporal server start-dev\n2026-06-13T00:00:00Z\n");
+    expect(readPidFile(path)).toBe(1234);
+  });
+
+  it("returns null for a non-numeric first line", () => {
+    const path = join(tempDir("stigmer-pid-"), "bad.pid");
+    writeFileSync(path, "not-a-pid\n");
+    expect(readPidFile(path)).toBeNull();
+  });
+});
+
+describe("isProcessAlive", () => {
+  it("is true for the current process and false for a dead PID", () => {
+    expect(isProcessAlive(process.pid)).toBe(true);
+    expect(isProcessAlive(DEAD_PID)).toBe(false);
+    expect(isProcessAlive(0)).toBe(false);
+    expect(isProcessAlive(-1)).toBe(false);
+  });
+});
+
+describe("health-state", () => {
+  it("round-trips an atomic write/read", () => {
+    const path = join(tempDir("stigmer-health-"), "health-state.json");
+    const state: HealthState = {
+      daemon_pid: 100,
+      started_at: "2026-06-13T10:00:00.000Z",
+      components: {
+        "stigmer-server": { pid: 101, state: "running", started_at: "2026-06-13T10:00:01.000Z", restart_count: 0 },
+        runner: { pid: 102, state: "unhealthy", started_at: "2026-06-13T10:00:02.000Z", restart_count: 1, last_error: "boom" },
+      },
+    };
+    writeHealthState(path, state);
+    expect(loadHealthState(path)).toEqual(state);
+  });
+
+  it("returns null for a missing or corrupt file", () => {
+    const dir = tempDir("stigmer-health-");
+    expect(loadHealthState(join(dir, "absent.json"))).toBeNull();
+    const corrupt = join(dir, "corrupt.json");
+    writeFileSync(corrupt, "{not json");
+    expect(loadHealthState(corrupt)).toBeNull();
+  });
+});
+
+describe("startup-config", () => {
+  it("saves, loads, and removes", () => {
+    const dir = tempDir("stigmer-startup-");
+    const config: StartupConfig = {
+      data_dir: dir,
+      log_dir: join(dir, "logs"),
+      temporal_addr: "127.0.0.1:7233",
+      llm_provider: "anthropic",
+      llm_model: "claude",
+      llm_base_url: "",
+      execution_mode: "local",
+      sandbox_image: "",
+      sandbox_auto_pull: false,
+      sandbox_cleanup: true,
+      sandbox_ttl: 0,
+      stigmer_server_pid: 999,
+      server_only: false,
+    };
+    saveStartupConfig(dir, config);
+    expect(loadStartupConfig(dir)).toEqual(config);
+    removeStartupConfig(dir);
+    expect(loadStartupConfig(dir)).toBeNull();
+  });
+});
+
+describe("log-rotation", () => {
+  it("rotates non-empty logs and leaves empty ones in place", () => {
+    const dir = tempDir("stigmer-logs-");
+    writeFileSync(join(dir, "daemon.log"), "some output\n");
+    writeFileSync(join(dir, "runner.log"), ""); // empty — skipped
+    const now = new Date("2026-06-13T14:15:02");
+
+    const rotated = rotateLogs(dir, { now });
+
+    expect(rotated).toBe(1);
+    expect(() => statSync(join(dir, "daemon.log"))).toThrow(); // renamed away
+    expect(statSync(join(dir, "daemon.log.2026-06-13-141502")).size).toBeGreaterThan(0);
+    expect(statSync(join(dir, "runner.log")).size).toBe(0); // untouched
+  });
+
+  it("prunes archives older than the retention window but keeps recent ones", () => {
+    const dir = tempDir("stigmer-logs-");
+    const now = new Date("2026-06-13T00:00:00");
+
+    const old = join(dir, "daemon.log.2026-05-01-000000");
+    const recent = join(dir, "runner.err.2026-06-12-000000");
+    writeFileSync(old, "old");
+    writeFileSync(recent, "recent");
+    const eightDaysAgo = now.getTime() / 1000 - 8 * 86400;
+    utimesSync(old, eightDaysAgo, eightDaysAgo);
+
+    const deleted = cleanupOldLogs(dir, 7, now);
+
+    expect(deleted).toBe(1);
+    expect(() => statSync(old)).toThrow();
+    expect(statSync(recent).size).toBeGreaterThan(0);
+  });
+});
+
+describe("lock", () => {
+  it("grants the lock once and refuses a second live acquirer", () => {
+    const path = join(tempDir("stigmer-lock-"), "temporal.lock");
+    const first = acquireLock(path);
+    expect(first).not.toBeNull();
+    expect(readFileSync(path, "utf8").trim()).toBe(String(process.pid));
+
+    // A second acquire while we (a live process) hold it must fail.
+    expect(acquireLock(path)).toBeNull();
+
+    first?.release();
+    expect(acquireLock(path)).not.toBeNull();
+  });
+
+  it("reclaims a lock left behind by a dead process", () => {
+    const path = join(tempDir("stigmer-lock-"), "temporal.lock");
+    writeFileSync(path, `${DEAD_PID}\n`);
+    const lock = acquireLock(path);
+    expect(lock).not.toBeNull();
+    expect(readFileSync(path, "utf8").trim()).toBe(String(process.pid));
+  });
+
+  it("release is idempotent and only removes our own lock", () => {
+    const path = join(tempDir("stigmer-lock-"), "temporal.lock");
+    const lock = acquireLock(path);
+    lock?.release();
+    lock?.release(); // no throw
+    expect(acquireLock(path)).not.toBeNull();
+  });
+});

package/src/local/status.test.ts

@@ -0,0 +1,88 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+import { configPath } from "../config/paths.js";
+import { DAEMON_PID_FILE } from "./constants.js";
+import { dataDir } from "./paths.js";
+import type { HealthState } from "./state/health-state.js";
+import { buildStatusResult, formatDuration } from "./status.js";
+
+let home: string;
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "stigmer-status-"));
+});
+
+const open = async () => true;
+const closed = async () => false;
+
+function field(result: Awaited<ReturnType<typeof buildStatusResult>>, section: string, key: string): string | undefined {
+  return result.sections.find((s) => s.title === section)?.fields.find((f) => f.key === key)?.value;
+}
+
+function writeHealth(state: HealthState): void {
+  mkdirSync(dataDir(home), { recursive: true });
+  writeFileSync(join(dataDir(home), DAEMON_PID_FILE), String(process.pid));
+  writeFileSync(join(dataDir(home), "health-state.json"), JSON.stringify(state));
+}
+
+describe("buildStatusResult", () => {
+  it("reports not-running when no daemon and the port is closed", async () => {
+    const result = await buildStatusResult(home, closed);
+    expect(result.status).toBe("warning");
+    expect(result.message).toMatch(/not running/);
+  });
+
+  it("renders components in order, with runner readiness", async () => {
+    writeHealth({
+      daemon_pid: process.pid,
+      started_at: new Date().toISOString(),
+      components: {
+        temporal: { pid: 10, state: "running", restart_count: 0, started_at: new Date().toISOString() },
+        "stigmer-server": { pid: 11, state: "running", restart_count: 0, started_at: new Date().toISOString() },
+        runner: { pid: 12, state: "running", restart_count: 1, started_at: new Date().toISOString(), ready: true },
+      },
+    });
+    writeFileSync(configPath(home), "backend:\n  type: local\n  local:\n    llm:\n      provider: anthropic\n      api_key: sk-x\n");
+
+    const result = await buildStatusResult(home, open);
+    expect(result.status).toBe("success");
+
+    const titles = result.sections.map((s) => s.title);
+    expect(titles.indexOf("Temporal")).toBeLessThan(titles.indexOf("Stigmer Server"));
+    expect(titles.indexOf("Stigmer Server")).toBeLessThan(titles.indexOf("Runner"));
+
+    expect(field(result, "Runner", "Status")).toBe("Running ✓ (polling)");
+    expect(field(result, "Runner", "Restarts")).toBe("1");
+    expect(field(result, "LLM Configuration", "Provider")).toBe("Anthropic (Cloud)");
+    expect(field(result, "LLM Configuration", "API Key")).toBe("Configured ✓");
+    expect(field(result, "Web UI", "Temporal")).toBe("http://localhost:8233");
+  });
+
+  it("shows runner as starting before the readiness marker", async () => {
+    writeHealth({
+      daemon_pid: process.pid,
+      started_at: new Date().toISOString(),
+      components: {
+        runner: { pid: 12, state: "running", restart_count: 0, started_at: new Date().toISOString(), ready: false },
+      },
+    });
+    const result = await buildStatusResult(home, open);
+    expect(field(result, "Runner", "Status")).toBe("Running ✓ (starting)");
+  });
+
+  it("synthesizes a running server when only the port answers", async () => {
+    const result = await buildStatusResult(home, open);
+    expect(result.status).toBe("success");
+    expect(field(result, "Stigmer Server", "Status")).toBe("Running ✓");
+  });
+});
+
+describe("formatDuration", () => {
+  it("renders coarse human durations", () => {
+    expect(formatDuration(5_000)).toBe("5s");
+    expect(formatDuration(125_000)).toBe("2m 5s");
+    expect(formatDuration(3_700_000)).toBe("1h 1m");
+    expect(formatDuration(90_000_000)).toBe("1d 1h");
+  });
+});

package/src/local/status.ts

@@ -0,0 +1,186 @@
+// `stigmer status` — render the local stack's health as a structured result.
+//
+// Source of truth is `health-state.json`, written by the daemon's health
+// monitor. If it is missing but the server port answers (the daemon wrote a PID
+// but not yet a snapshot, or an older daemon), we synthesize a minimal snapshot
+// from a TCP probe so `status` never lies about a running server. Components are
+// always rendered in a fixed, dependency-ordered sequence so the output reads
+// the same on every machine.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { load as loadConfig } from "../config/config.js";
+import { configPath } from "../config/paths.js";
+import { CommandResult } from "../output/command-result.js";
+import { SERVER_PORT, TEMPORAL_UI_PORT, WEB_CONSOLE_PORT } from "./constants.js";
+import { resolveApiKey, resolveModel, resolveProvider } from "./llm-config.js";
+import { tcpConnects } from "./net/tcp.js";
+import { dataDir } from "./paths.js";
+import { type ComponentState, type HealthState, loadHealthState } from "./state/health-state.js";
+import { DAEMON_PID_FILE } from "./constants.js";
+import { readPidFile } from "./state/pidfile.js";
+import { isProcessAlive } from "./state/proc.js";
+
+const COMPONENT_ORDER = ["temporal", "stigmer-server", "runner", "web-console"] as const;
+const COMPONENT_LABELS: Record<string, string> = {
+  temporal: "Temporal",
+  "stigmer-server": "Stigmer Server",
+  runner: "Runner",
+  "web-console": "Web Console",
+};
+
+/** Probe a port for liveness; the real one connects over TCP. Injectable so
+ * status rendering is testable without depending on a real listener. */
+export type PortProbe = (port: number) => Promise<boolean>;
+
+const defaultProbe: PortProbe = (port) => tcpConnects(port, "127.0.0.1", 1000);
+
+/** Build the status result for the local stack rooted at `home`. */
+export async function buildStatusResult(home: string = homedir(), probe: PortProbe = defaultProbe): Promise<CommandResult> {
+  const data = dataDir(home);
+  const pid = readPidFile(join(data, DAEMON_PID_FILE));
+  const daemonAlive = pid !== null && isProcessAlive(pid);
+  const portOpen = await probe(SERVER_PORT);
+
+  if (!daemonAlive && !portOpen) {
+    return CommandResult.warning("Stigmer server is not running").hint("To start: stigmer up");
+  }
+
+  const health = loadHealthState(join(data, "health-state.json")) ?? synthesizeHealth(pid, portOpen);
+
+  const result = CommandResult.success("Stigmer server is running");
+
+  const daemon = result.addSection("Daemon");
+  daemon.field("PID", String(health.daemon_pid));
+  daemon.field("Port", String(SERVER_PORT));
+  daemon.field("Data", data);
+  const uptime = uptimeFrom(health.started_at);
+  if (uptime !== null) daemon.field("Uptime", uptime);
+
+  for (const name of COMPONENT_ORDER) {
+    const component = health.components[name];
+    if (component === undefined) {
+      if (name === "web-console") continue; // optional; omit when absent
+      result.addSection(COMPONENT_LABELS[name]).field("Status", "Not Running ○");
+      continue;
+    }
+    addComponentSection(result, name, COMPONENT_LABELS[name], component);
+  }
+
+  addLlmSection(result, home);
+  addWebUiSection(result, health);
+
+  return result;
+}
+
+function synthesizeHealth(pid: number | null, portOpen: boolean): HealthState {
+  // No snapshot on disk: report only what a TCP probe can prove. If the port
+  // answers the server is running; otherwise leave components empty so the
+  // renderer shows them as "Not Running" rather than inventing a state.
+  const components: HealthState["components"] = portOpen
+    ? { "stigmer-server": { pid: 0, state: "running", restart_count: 0, started_at: "" } }
+    : {};
+  return { daemon_pid: pid ?? 0, started_at: "", components };
+}
+
+function addComponentSection(result: CommandResult, name: string, label: string, component: ComponentState): void {
+  const section = result.addSection(label);
+  const state = component.state || "unknown";
+
+  let status = `${displayState(state)} ${symbolFor(state)}`;
+  // The runner reports observed readiness (it polls its Temporal queue) on top
+  // of mere liveness — the truthful-visibility improvement over the Go CLI.
+  if (name === "runner" && state === "running") {
+    status += component.ready === true ? " (polling)" : " (starting)";
+  }
+  section.field("Status", status);
+
+  if (component.pid > 0) section.field("PID", String(component.pid));
+  const uptime = uptimeFrom(component.started_at);
+  if (uptime !== null) section.field("Uptime", uptime);
+  section.field("Restarts", String(component.restart_count));
+
+  if (component.last_error && (state === "failed" || state === "stopped")) {
+    section.field("Last Error", component.last_error);
+  }
+  if (state === "failed" || state === "stopped") {
+    result.hint(`View ${name} logs: stigmer logs --component ${name}`);
+  }
+}
+
+function addLlmSection(result: CommandResult, home: string): void {
+  const config = loadConfig(configPath(home));
+  const provider = resolveProvider(config);
+  const section = result.addSection("LLM Configuration");
+
+  if (provider === "") {
+    section.field("Provider", "Not configured");
+    section.field("Status", "Agents will not execute");
+    result.hint("Configure a provider: stigmer setup");
+    return;
+  }
+
+  const model = resolveModel(config);
+  switch (provider) {
+    case "ollama":
+      section.field("Provider", "Local (Ollama)");
+      section.field("Model", model);
+      break;
+    case "anthropic":
+    case "openai":
+      section.field("Provider", provider === "anthropic" ? "Anthropic (Cloud)" : "OpenAI (Cloud)");
+      section.field("Model", model);
+      section.field("API Key", resolveApiKey(config) !== "" ? "Configured ✓" : "Not configured ✗");
+      break;
+    default:
+      section.field("Provider", `Unknown (${provider})`);
+  }
+}
+
+function addWebUiSection(result: CommandResult, health: HealthState): void {
+  const temporalRunning = health.components.temporal?.state === "running";
+  const webRunning = health.components["web-console"]?.state === "running";
+  if (!temporalRunning && !webRunning) return;
+
+  const section = result.addSection("Web UI");
+  if (webRunning) section.field("Console", `http://localhost:${WEB_CONSOLE_PORT}`);
+  if (temporalRunning) section.field("Temporal", `http://localhost:${TEMPORAL_UI_PORT}`);
+}
+
+const STATE_SYMBOLS: Record<string, string> = {
+  running: "✓",
+  unhealthy: "◐",
+  starting: "◌",
+  stopped: "○",
+  failed: "✗",
+  unknown: "○",
+};
+
+function symbolFor(state: string): string {
+  return STATE_SYMBOLS[state] ?? "○";
+}
+
+function displayState(state: string): string {
+  return state.charAt(0).toUpperCase() + state.slice(1);
+}
+
+function uptimeFrom(startedAt: string): string | null {
+  if (startedAt === "") return null;
+  const started = Date.parse(startedAt);
+  if (Number.isNaN(started)) return null;
+  return formatDuration(Date.now() - started);
+}
+
+/** Human-readable, coarse duration ("2h 5m", "3m 12s", "8s"). */
+export function formatDuration(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+  const days = Math.floor(totalSeconds / 86_400);
+  const hours = Math.floor((totalSeconds % 86_400) / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}

package/src/local/temporal/download.test.ts

@@ -0,0 +1,64 @@
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gzipSync } from "fflate";
+import { describe, expect, it } from "vitest";
+import { downloadTemporalCli, extractTarEntry } from "./download.js";
+
+// Build a minimal ustar archive containing a single regular-file entry. Only
+// the fields the reader uses (name, octal size, type flag) are populated.
+function makeTar(name: string, content: Buffer): Buffer {
+  const header = Buffer.alloc(512);
+  header.write(name, 0, "utf8");
+  header.write(content.length.toString(8).padStart(11, "0"), 124, "ascii");
+  header.write("0", 156, "ascii");
+  const data = Buffer.alloc(Math.ceil(content.length / 512) * 512);
+  content.copy(data);
+  const trailer = Buffer.alloc(1024); // two zero blocks end the archive
+  return Buffer.concat([header, data, trailer]);
+}
+
+describe("extractTarEntry", () => {
+  it("extracts a named regular file", () => {
+    const payload = Buffer.from("#!/bin/sh\necho temporal\n");
+    const tar = makeTar("temporal", payload);
+    const out = extractTarEntry(new Uint8Array(tar), "temporal");
+    expect(out).not.toBeNull();
+    expect(Buffer.from(out!).toString("utf8")).toBe(payload.toString("utf8"));
+  });
+
+  it("matches by basename for nested entries", () => {
+    const payload = Buffer.from("binary-bytes");
+    const tar = makeTar("temporal_cli/temporal", payload);
+    const out = extractTarEntry(new Uint8Array(tar), "temporal");
+    expect(Buffer.from(out!).toString("utf8")).toBe("binary-bytes");
+  });
+
+  it("returns null when the entry is absent", () => {
+    const tar = makeTar("something-else", Buffer.from("x"));
+    expect(extractTarEntry(new Uint8Array(tar), "temporal")).toBeNull();
+  });
+});
+
+describe("downloadTemporalCli", () => {
+  it("downloads, gunzips, untars, and writes an executable binary", async () => {
+    const payload = Buffer.from("the-temporal-binary");
+    const gz = gzipSync(new Uint8Array(makeTar("temporal", payload)));
+    const fetchImpl = (async () => ({
+      ok: true,
+      status: 200,
+      arrayBuffer: async () => gz.buffer.slice(gz.byteOffset, gz.byteOffset + gz.byteLength),
+    })) as unknown as typeof fetch;
+
+    const binPath = join(mkdtempSync(join(tmpdir(), "stigmer-temporal-")), "bin", "temporal");
+    await downloadTemporalCli({ version: "1.5.1", binPath, fetchImpl });
+
+    expect(readFileSync(binPath, "utf8")).toBe("the-temporal-binary");
+  });
+
+  it("fails clearly on a non-OK response", async () => {
+    const fetchImpl = (async () => ({ ok: false, status: 404, arrayBuffer: async () => new ArrayBuffer(0) })) as unknown as typeof fetch;
+    const binPath = join(mkdtempSync(join(tmpdir(), "stigmer-temporal-")), "temporal");
+    await expect(downloadTemporalCli({ version: "9.9.9", binPath, fetchImpl })).rejects.toThrow(/HTTP 404/);
+  });
+});