@openparachute/hub 0.3.0-rc.1

package/src/__tests__/auto-wire.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SCRIBE_AUTH_ENV_KEY, SCRIBE_URL_ENV_KEY, autoWireScribeAuth } from "../auto-wire.ts";
+import { writePid } from "../process-state.ts";
+
+function makeHarness(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-autowire-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+const DEFAULT_SCRIBE_URL = "http://127.0.0.1:1943";
+
+describe("autoWireScribeAuth", () => {
+  test("first call: writes new token + SCRIBE_URL to vault .env and token to scribe config.json", async () => {
+    const h = makeHarness();
+    try {
+      const logs: string[] = [];
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "deadbeef00".repeat(6),
+        log: (l) => logs.push(l),
+      });
+      expect(result.generated).toBe(true);
+      expect(result.token).toBe("deadbeef00".repeat(6));
+      expect(result.scribeUrl).toBe(DEFAULT_SCRIBE_URL);
+
+      const envText = readFileSync(join(h.dir, "vault", ".env"), "utf8");
+      expect(envText).toContain(`${SCRIBE_AUTH_ENV_KEY}=${result.token}`);
+      expect(envText).toContain(`${SCRIBE_URL_ENV_KEY}=${DEFAULT_SCRIBE_URL}`);
+
+      const scribeCfg = JSON.parse(readFileSync(join(h.dir, "scribe", "config.json"), "utf8"));
+      expect(scribeCfg).toEqual({ auth: { required_token: result.token } });
+
+      expect(logs.join("\n")).toMatch(/Auto-wired shared secret \+ SCRIBE_URL/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("idempotent: pre-existing SCRIBE_AUTH_TOKEN in vault .env is preserved; SCRIBE_URL still wired", async () => {
+    const h = makeHarness();
+    try {
+      // Seed a prior wire (or operator-set token). The helper must not
+      // regenerate on repeat install — churning the token would break a
+      // running vault worker that already has the old one in its process env.
+      // SCRIBE_URL was missing from the prior write (this is a 0.2.4 → 0.2.5
+      // upgrade scenario), so it should still be added.
+      const envPath = join(h.dir, "vault", ".env");
+      const seed = "seeded-token-abc123";
+      mkdirSync(join(h.dir, "vault"), { recursive: true });
+      writeFileSync(envPath, `FOO=bar\n${SCRIBE_AUTH_ENV_KEY}=${seed}\nOTHER=baz\n`);
+
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "should-not-be-used",
+        log: () => {},
+      });
+      expect(result.generated).toBe(false);
+      expect(result.token).toBe(seed);
+      expect(result.scribeUrl).toBe(DEFAULT_SCRIBE_URL);
+
+      const envText = readFileSync(envPath, "utf8");
+      expect(envText).toContain("FOO=bar");
+      expect(envText).toContain(`${SCRIBE_AUTH_ENV_KEY}=${seed}`);
+      expect(envText).toContain("OTHER=baz");
+      expect(envText).toContain(`${SCRIBE_URL_ENV_KEY}=${DEFAULT_SCRIBE_URL}`);
+      // And scribe config.json gets the seeded value (so drift between the
+      // two sides repairs on repeat install).
+      const scribeCfg = JSON.parse(readFileSync(join(h.dir, "scribe", "config.json"), "utf8"));
+      expect(scribeCfg.auth.required_token).toBe(seed);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("preserves operator-set SCRIBE_URL (e.g., a non-loopback override)", async () => {
+    const h = makeHarness();
+    try {
+      const envPath = join(h.dir, "vault", ".env");
+      const customUrl = "http://scribe.lan:1943";
+      mkdirSync(join(h.dir, "vault"), { recursive: true });
+      writeFileSync(envPath, `${SCRIBE_URL_ENV_KEY}=${customUrl}\n`);
+
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "fresh-token",
+        log: () => {},
+      });
+      expect(result.scribeUrl).toBe(customUrl);
+
+      const envText = readFileSync(envPath, "utf8");
+      expect(envText).toContain(`${SCRIBE_URL_ENV_KEY}=${customUrl}`);
+      expect(envText).not.toContain(`${SCRIBE_URL_ENV_KEY}=${DEFAULT_SCRIBE_URL}`);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("appends SCRIBE_AUTH_TOKEN without clobbering other vault .env keys", async () => {
+    const h = makeHarness();
+    try {
+      const envPath = join(h.dir, "vault", ".env");
+      mkdirSync(join(h.dir, "vault"), { recursive: true });
+      writeFileSync(envPath, "VAULT_SECRET=xyz\nLOG_LEVEL=debug\n");
+
+      await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "fresh-token-123",
+        log: () => {},
+      });
+
+      const envText = readFileSync(envPath, "utf8");
+      expect(envText).toContain("VAULT_SECRET=xyz");
+      expect(envText).toContain("LOG_LEVEL=debug");
+      expect(envText).toContain(`${SCRIBE_AUTH_ENV_KEY}=fresh-token-123`);
+      expect(envText).toContain(`${SCRIBE_URL_ENV_KEY}=${DEFAULT_SCRIBE_URL}`);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("merges into existing scribe config.json, preserving other keys", async () => {
+    const h = makeHarness();
+    try {
+      const scribeCfgPath = join(h.dir, "scribe", "config.json");
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeCfgPath,
+        JSON.stringify({ whisper: { model: "medium.en" }, auth: { other: "kept" } }, null, 2),
+      );
+
+      await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "tok",
+        log: () => {},
+      });
+
+      const cfg = JSON.parse(readFileSync(scribeCfgPath, "utf8"));
+      expect(cfg.whisper.model).toBe("medium.en");
+      expect(cfg.auth.other).toBe("kept");
+      expect(cfg.auth.required_token).toBe("tok");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("handles quoted token values in vault .env (preserves the raw value)", async () => {
+    const h = makeHarness();
+    try {
+      const envPath = join(h.dir, "vault", ".env");
+      mkdirSync(join(h.dir, "vault"), { recursive: true });
+      writeFileSync(envPath, `${SCRIBE_AUTH_ENV_KEY}="quoted-value"\n`);
+
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "should-not-be-used",
+        log: () => {},
+      });
+      expect(result.generated).toBe(false);
+      expect(result.token).toBe("quoted-value");
+
+      const cfg = JSON.parse(readFileSync(join(h.dir, "scribe", "config.json"), "utf8"));
+      expect(cfg.auth.required_token).toBe("quoted-value");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("creates vault/ and scribe/ dirs if missing", async () => {
+    const h = makeHarness();
+    try {
+      expect(existsSync(join(h.dir, "vault"))).toBe(false);
+      expect(existsSync(join(h.dir, "scribe"))).toBe(false);
+      await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "tok",
+        log: () => {},
+      });
+      expect(existsSync(join(h.dir, "vault", ".env"))).toBe(true);
+      expect(existsSync(join(h.dir, "scribe", "config.json"))).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("restarts vault when the worker is running so the new env takes effect", async () => {
+    // The whole point of writing SCRIBE_URL is that vault's transcription
+    // worker can find scribe. If vault is already running when we wire,
+    // the worker keeps its stale env until we restart it — exactly the
+    // launch-day footgun where voice memos sat on `_Transcript pending._`
+    // forever. Mirrors the auto-restart-on-expose pattern from PR #39.
+    const h = makeHarness();
+    try {
+      writePid("vault", 4242, h.dir);
+      const restartCalls: string[] = [];
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "tok",
+        log: () => {},
+        alive: () => true,
+        restartService: async (short) => {
+          restartCalls.push(short);
+          return 0;
+        },
+      });
+      expect(result.restartedVault).toBe(true);
+      expect(restartCalls).toEqual(["vault"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("does not restart vault when nothing changed (idempotent repeat call)", async () => {
+    // Both keys already present, vault running — there's nothing to pick up
+    // on restart, so we shouldn't churn a healthy daemon.
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "vault"), { recursive: true });
+      writeFileSync(
+        join(h.dir, "vault", ".env"),
+        `${SCRIBE_AUTH_ENV_KEY}=already\n${SCRIBE_URL_ENV_KEY}=${DEFAULT_SCRIBE_URL}\n`,
+      );
+      writePid("vault", 4242, h.dir);
+      const restartCalls: string[] = [];
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        log: () => {},
+        alive: () => true,
+        restartService: async (short) => {
+          restartCalls.push(short);
+          return 0;
+        },
+      });
+      expect(result.restartedVault).toBe(false);
+      expect(restartCalls).toEqual([]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("does not restart vault when it isn't running", async () => {
+    // No PID file → processState reports "unknown" → no restart. Avoids
+    // launching a daemon as a side effect of install.
+    const h = makeHarness();
+    try {
+      const restartCalls: string[] = [];
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "tok",
+        log: () => {},
+        restartService: async (short) => {
+          restartCalls.push(short);
+          return 0;
+        },
+      });
+      expect(result.restartedVault).toBe(false);
+      expect(restartCalls).toEqual([]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("logs a clear hint when the auto-restart fails", async () => {
+    const h = makeHarness();
+    try {
+      writePid("vault", 4242, h.dir);
+      const logs: string[] = [];
+      const result = await autoWireScribeAuth({
+        configDir: h.dir,
+        randomToken: () => "tok",
+        log: (l) => logs.push(l),
+        alive: () => true,
+        restartService: async () => 1,
+      });
+      expect(result.restartedVault).toBe(false);
+      expect(logs.join("\n")).toMatch(/vault restart failed.*parachute restart vault/);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/cli.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CLI = join(import.meta.dir, "..", "cli.ts");
+
+async function runCli(
+  args: string[],
+  env: Record<string, string> = {},
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(["bun", CLI, ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      HOME: "/tmp/parachute-hub-nonexistent-home",
+      PARACHUTE_HOME: "/tmp/parachute-hub-nonexistent-home",
+      ...env,
+    },
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stdout, stderr };
+}
+
+describe("cli", () => {
+  test("--version prints version from package.json", async () => {
+    const { code, stdout } = await runCli(["--version"]);
+    expect(code).toBe(0);
+    expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  test("--help lists commands", async () => {
+    const { code, stdout } = await runCli(["--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute install/);
+    expect(stdout).toMatch(/parachute status/);
+    expect(stdout).toMatch(/parachute auth/);
+    expect(stdout).toMatch(/parachute vault/);
+    expect(stdout).toMatch(/expose tailnet/);
+    expect(stdout).toMatch(/expose public/);
+  });
+
+  test("expose with unknown layer exits 1", async () => {
+    const { code, stderr } = await runCli(["expose", "wat"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/unknown layer/);
+    expect(stderr).toMatch(/expose public/);
+  });
+
+  test("no args prints help", async () => {
+    const { code, stdout } = await runCli([]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/Usage:/);
+  });
+
+  test("install with no service name exits 1", async () => {
+    const { code, stderr } = await runCli(["install"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/usage: parachute install/);
+  });
+
+  test("unknown command exits 1", async () => {
+    const { code, stderr } = await runCli(["wat"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/unknown command/);
+  });
+});
+
+describe("cli per-subcommand help", () => {
+  test("install --help shows install usage", async () => {
+    const { code, stdout } = await runCli(["install", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute install/);
+    expect(stdout).toMatch(/bun add -g/);
+  });
+
+  test("install -h also works", async () => {
+    const { code, stdout } = await runCli(["install", "-h"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute install/);
+  });
+
+  test("status --help shows status usage", async () => {
+    const { code, stdout } = await runCli(["status", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute status/);
+    expect(stdout).toMatch(/Exit codes/);
+  });
+
+  test("expose --help shows both layers and Funnel notes", async () => {
+    const { code, stdout } = await runCli(["expose", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/expose tailnet/);
+    expect(stdout).toMatch(/expose public/);
+    expect(stdout).toMatch(/Funnel/);
+    expect(stdout).toMatch(/443/);
+    expect(stdout).toMatch(/--cloudflare/);
+    expect(stdout).toMatch(/--domain/);
+  });
+
+  test("expose public --cloudflare without --domain exits 1 with usage hint", async () => {
+    const { code, stderr } = await runCli(["expose", "public", "--cloudflare"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/--domain <hostname> is required/);
+    expect(stderr).toMatch(/dash\.cloudflare\.com/);
+  });
+
+  test("expose tailnet --cloudflare is rejected (cloudflare is public-only)", async () => {
+    const { code, stderr } = await runCli([
+      "expose",
+      "tailnet",
+      "--cloudflare",
+      "--domain",
+      "vault.example.com",
+    ]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/--cloudflare only applies to `public`/);
+  });
+
+  test("expose with missing --domain value exits 1", async () => {
+    const { code, stderr } = await runCli(["expose", "public", "--cloudflare", "--domain"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/--domain requires a hostname argument/);
+  });
+
+  test("expose tailnet --help shows full expose help", async () => {
+    const { code, stdout } = await runCli(["expose", "tailnet", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/expose tailnet/);
+  });
+
+  test("vault with no args forwards --help to parachute-vault", async () => {
+    // Clear PATH so the dispatcher reliably hits the ENOENT branch — that
+    // proves the CLI is forwarding rather than printing local help. Spawn
+    // bun by absolute path so the outer shell-out isn't affected by PATH=''.
+    const proc = Bun.spawn([process.execPath, CLI, "vault"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        PATH: "",
+        HOME: "/tmp/parachute-hub-nonexistent-home",
+        PARACHUTE_HOME: "/tmp/parachute-hub-nonexistent-home",
+      },
+    });
+    const [stderr, code] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+    expect(code).toBe(127);
+    expect(stderr).toMatch(/parachute-vault not found on PATH/);
+    expect(stderr).toMatch(/parachute install vault/);
+  });
+
+  test("vault tokens create in non-TTY passes through without prompting", async () => {
+    // Spawned-subprocess stdio is piped, so isTtyInteractive() returns false
+    // and the command falls through to the passthrough. Clearing PATH forces
+    // ENOENT — same probe as the `vault no-args` test. If we regressed into
+    // prompting, this subprocess would hang on stdin instead of exiting 127.
+    const proc = Bun.spawn([process.execPath, CLI, "vault", "tokens", "create"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        PATH: "",
+        HOME: "/tmp/parachute-hub-nonexistent-home",
+        PARACHUTE_HOME: "/tmp/parachute-hub-nonexistent-home",
+      },
+    });
+    const [stderr, code] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+    expect(code).toBe(127);
+    expect(stderr).toMatch(/parachute-vault not found on PATH/);
+  });
+});
+
+describe("cli friendly errors", () => {
+  test("malformed services.json prints friendly error not stack trace", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pcli-bad-"));
+    try {
+      writeFileSync(join(dir, "services.json"), "this is not json{");
+      const { code, stderr } = await runCli(["status"], { PARACHUTE_HOME: dir });
+      expect(code).toBe(1);
+      expect(stderr).toMatch(/services\.json is malformed/);
+      expect(stderr).not.toMatch(/at process\./);
+      expect(stderr).not.toMatch(/Error:.*at \//);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/cloudflare-config.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { renderConfig, writeConfig } from "../cloudflare/config.ts";
+
+describe("cloudflare config", () => {
+  test("renderConfig produces a valid cloudflared YAML with one-hostname ingress + catch-all 404", () => {
+    const yaml = renderConfig({
+      tunnelUuid: "2c1a7c7e-1234-5678-9abc-def012345678",
+      credentialsFile: "/Users/x/.cloudflared/2c1a7c7e-1234-5678-9abc-def012345678.json",
+      hostname: "vault.example.com",
+      servicePort: 1940,
+    });
+    expect(yaml).toContain("tunnel: 2c1a7c7e-1234-5678-9abc-def012345678");
+    expect(yaml).toContain(
+      'credentials-file: "/Users/x/.cloudflared/2c1a7c7e-1234-5678-9abc-def012345678.json"',
+    );
+    expect(yaml).toContain("- hostname: vault.example.com");
+    expect(yaml).toContain("service: http://localhost:1940");
+    expect(yaml).toContain("- service: http_status:404");
+  });
+
+  test("renderConfig double-quotes credentials-file so paths with spaces survive YAML parse", () => {
+    const yaml = renderConfig({
+      tunnelUuid: "uuid",
+      credentialsFile: "/Users/John Doe/.cloudflared/uuid.json",
+      hostname: "vault.example.com",
+      servicePort: 1940,
+    });
+    expect(yaml).toContain('credentials-file: "/Users/John Doe/.cloudflared/uuid.json"');
+  });
+
+  test("writeConfig creates the parent directory and writes to the given path", () => {
+    const dir = mkdtempSync(join(tmpdir(), "pcli-cfg-"));
+    const path = join(dir, "nested", "subdir", "config.yml");
+    try {
+      writeConfig(
+        {
+          tunnelUuid: "uuid",
+          credentialsFile: "/tmp/creds.json",
+          hostname: "vault.example.com",
+          servicePort: 1940,
+        },
+        path,
+      );
+      const contents = readFileSync(path, "utf8");
+      expect(contents).toContain("tunnel: uuid");
+      expect(contents).toContain("hostname: vault.example.com");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/cloudflare-detect.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  cloudflaredInstallHint,
+  isCloudflaredInstalled,
+  isCloudflaredLoggedIn,
+} from "../cloudflare/detect.ts";
+import type { CommandResult, Runner } from "../tailscale/run.ts";
+
+function stubRunner(result: CommandResult | Error): Runner {
+  return async (_cmd) => {
+    if (result instanceof Error) throw result;
+    return result;
+  };
+}
+
+describe("cloudflare detect", () => {
+  test("isCloudflaredInstalled returns true on exit 0", async () => {
+    const runner = stubRunner({ code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" });
+    expect(await isCloudflaredInstalled(runner)).toBe(true);
+  });
+
+  test("isCloudflaredInstalled returns false on non-zero exit", async () => {
+    const runner = stubRunner({ code: 127, stdout: "", stderr: "not found" });
+    expect(await isCloudflaredInstalled(runner)).toBe(false);
+  });
+
+  test("isCloudflaredInstalled swallows ENOENT (binary missing → not installed)", async () => {
+    // Bun.spawn throws synchronously when the binary is missing; the detector
+    // has to read that as "not installed" rather than propagating the error.
+    const runner = stubRunner(new Error("ENOENT: cloudflared not on PATH"));
+    expect(await isCloudflaredInstalled(runner)).toBe(false);
+  });
+
+  test("isCloudflaredInstalled matches on .code === 'ENOENT' too", async () => {
+    const err = Object.assign(new Error("spawn failed"), { code: "ENOENT" });
+    expect(await isCloudflaredInstalled(stubRunner(err))).toBe(false);
+  });
+
+  test("isCloudflaredInstalled propagates non-ENOENT errors (don't lie about why)", async () => {
+    // An EACCES (binary found but not executable) is real misconfiguration,
+    // not a missing install. Swallowing it here would mask the actual fix.
+    const err = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" });
+    await expect(isCloudflaredInstalled(stubRunner(err))).rejects.toMatchObject({
+      code: "EACCES",
+    });
+  });
+
+  test("isCloudflaredLoggedIn reads cert.pem presence in the passed home dir", () => {
+    const home = mkdtempSync(join(tmpdir(), "cf-home-"));
+    try {
+      expect(isCloudflaredLoggedIn(home)).toBe(false);
+      writeFileSync(join(home, "cert.pem"), "-----BEGIN CERTIFICATE-----\n...\n");
+      expect(isCloudflaredLoggedIn(home)).toBe(true);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("install hint names brew on darwin and a URL elsewhere", () => {
+    expect(cloudflaredInstallHint("darwin")).toContain("brew install cloudflared");
+    expect(cloudflaredInstallHint("linux")).toContain(
+      "developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads",
+    );
+  });
+});

package/src/__tests__/cloudflare-state.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type CloudflaredState,
+  CloudflaredStateError,
+  clearCloudflaredState,
+  readCloudflaredState,
+  writeCloudflaredState,
+} from "../cloudflare/state.ts";
+
+function makeTempPath(): { path: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-cfstate-"));
+  return {
+    path: join(dir, "cloudflared-state.json"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+const sample: CloudflaredState = {
+  version: 1,
+  pid: 12345,
+  tunnelUuid: "2c1a7c7e-1234-5678-9abc-def012345678",
+  tunnelName: "parachute",
+  hostname: "vault.example.com",
+  startedAt: "2026-04-22T12:00:00.000Z",
+  configPath: "/home/x/.parachute/cloudflared/config.yml",
+};
+
+describe("cloudflared state", () => {
+  test("read returns undefined when the file doesn't exist", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      expect(readCloudflaredState(path)).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("write + read round-trip", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeCloudflaredState(sample, path);
+      expect(readCloudflaredState(path)).toEqual(sample);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("clear removes the file", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeCloudflaredState(sample, path);
+      expect(existsSync(path)).toBe(true);
+      clearCloudflaredState(path);
+      expect(existsSync(path)).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("throws on unsupported version", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(path, JSON.stringify({ ...sample, version: 99 }));
+      expect(() => readCloudflaredState(path)).toThrow(/unsupported version/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("throws on non-positive pid", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(path, JSON.stringify({ ...sample, pid: -1 }));
+      expect(() => readCloudflaredState(path)).toThrow(CloudflaredStateError);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("throws on malformed JSON", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(path, "{not json");
+      expect(() => readCloudflaredState(path)).toThrow(/failed to parse/);
+    } finally {
+      cleanup();
+    }
+  });
+});