@openparachute/hub 0.5.14-rc.13 → 0.5.14-rc.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.14-rc.13",
+  "version": "0.5.14-rc.15",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/account-home-ui.test.ts

@@ -57,6 +57,23 @@ describe("renderAccountHome", () => {
     expect(html).not.toContain("Authorization: Bearer");
     // Copy-button progressive-enhancement script is present.
     expect(html).toContain("navigator.clipboard");
+    // Friendlier framing: the block leads with "connect your AI assistant"
+    // rather than MCP jargon up top.
+    expect(html).toContain('data-testid="connect-ai-heading"');
+    expect(html).toContain("Connect your AI");
+    // BOTH connect methods render as distinct, labelled blocks.
+    expect(html).toContain('data-testid="connect-method-claude-code"');
+    expect(html).toContain("Claude Code");
+    expect(html).toContain('data-testid="connect-method-claude-ai"');
+    expect(html).toContain("Claude.ai");
+    // The Claude.ai path mirrors the install.njk canonical phrasing
+    // (Settings → Connectors → Add custom connector, paste the endpoint).
+    expect(html).toContain("Connectors");
+    expect(html).toContain("Add custom connector");
+    // A brief "any other MCP client" line is present (no bloat — just one).
+    expect(html).toContain('data-testid="connect-any-client-hint"');
+    // Notes CTA still present, now framed as the browser-UI option.
+    expect(html).toContain('data-testid="open-notes-cta"');
   });
 
   test("assigned-vault branch — trailing slash on hubOrigin is normalized", () => {
@@ -112,11 +129,16 @@ describe("renderAccountHome", () => {
       twoFactorEnabled: false,
     });
     expect(html).toContain("Welcome, ghost");
-    expect(html).toContain("Ask the hub operator");
+    // The message explains WHY there's nothing to connect (no vault yet) and
+    // gives a clear next step — not just a bare "ask your admin".
+    expect(html).toContain("Ask the hub operator to assign you a vault");
+    expect(html).toContain("don't have a vault yet");
     // No /admin/ link in this branch — they have no admin role.
     expect(html).not.toContain('href="/admin/"');
     // No Notes CTA.
     expect(html).not.toContain("notes.parachute.computer/add");
+    // No connect block — you can't connect a vault you don't have.
+    expect(html).not.toContain('data-testid="mcp-connect"');
   });
 
   test("account card — change-password link and sign-out form are present", () => {

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

@@ -551,6 +551,191 @@ describe("exposeCloudflareUp", () => {
     }
   });
 
+  test("hub#487: kills orphan connectors found by pgrep before spawning, not just the state pid", async () => {
+    // The orphan-accumulation bug: each re-expose spawned a fresh connector
+    // without killing prior ones, and state only tracked the most-recent pid.
+    // Orphans the state file lost track of (crashed mid-rewrite, started by
+    // hand) must still be swept — `connectorPids` finds them by UUID/config
+    // path. Here state knows pid 99999, but pgrep also surfaces 88888 + 77777
+    // serving the same tunnel; all three get SIGTERM before the new spawn.
+    const env = makeEnv();
+    try {
+      const uuid = "cccccccc-0000-0000-0000-000000000003";
+      const priorRecord: CloudflaredTunnelRecord = {
+        pid: 99999,
+        tunnelUuid: uuid,
+        tunnelName: "parachute",
+        hostname: "vault.example.com",
+        startedAt: "2026-04-21T00:00:00.000Z",
+        configPath: env.configPath,
+      };
+      writeCloudflaredState({ version: 2, tunnels: { parachute: priorRecord } }, env.statePath);
+
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" }, // route dns
+      ]);
+      const { spawner, seen } = fakeSpawner(42010);
+      const killed: number[] = [];
+
+      const code = await exposeCloudflareUp("vault.example.com", {
+        runner,
+        spawner,
+        alive: () => true, // all candidate pids report alive
+        kill: (pid) => killed.push(pid),
+        // pgrep surfaces two orphans the state record didn't track.
+        connectorPids: () => [88888, 77777],
+        resolveHost: async () => ["104.16.0.1"], // Cloudflare — no DNS warning
+        log: () => {},
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      // Every prior connector (state pid + both pgrep orphans) is stopped
+      // before the new one spawns.
+      expect(killed.sort()).toEqual([77777, 88888, 99999]);
+      // Exactly one fresh connector spawned, and it's the one recorded.
+      expect(seen).toHaveLength(1);
+      expect(findTunnelRecord(readCloudflaredState(env.statePath), "parachute")?.pid).toBe(42010);
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: warns when DNS doesn't resolve yet (pending zone)", async () => {
+    // route dns succeeded but the hostname doesn't resolve — the "pending"
+    // zone shape (NS not switched at the registrar). Non-fatal: still exit 0,
+    // still print the URLs, but add the nameserver-switch nudge.
+    const env = makeEnv();
+    try {
+      const uuid = "dddddddd-0000-0000-0000-000000000004";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42020);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("vault.newzone.com", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => [], // NXDOMAIN / not live yet
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0); // non-fatal — the expose still completes
+      const joined = logs.join("\n");
+      expect(joined).toContain("DNS isn't live yet for vault.newzone.com");
+      expect(joined).toContain("dig +short newzone.com NS");
+      expect(joined).toContain("ns.cloudflare.com");
+      // The success URLs still print.
+      expect(joined).toContain("https://vault.newzone.com/admin/");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: warns when hostname resolves but not to Cloudflare (shadowed)", async () => {
+    // route dns succeeded but the hostname resolves to a non-Cloudflare IP —
+    // a Pages project / grey-cloud A record shadowing the tunnel → edge 404.
+    const env = makeEnv();
+    try {
+      const uuid = "eeeeeeee-0000-0000-0000-000000000006";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42021);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("docs.parachute.computer", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => ["203.0.113.10"], // not a Cloudflare range
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("not to Cloudflare's edge");
+      expect(joined).toContain("shadowed");
+      expect(joined).toContain("Pages project");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: no DNS warning when hostname resolves at Cloudflare's edge", async () => {
+    const env = makeEnv();
+    try {
+      const uuid = "ffffffff-0000-0000-0000-000000000007";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42022);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("vault.example.com", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => ["104.18.32.7"], // 104.16.0.0/13 — Cloudflare
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).not.toContain("DNS isn't live yet");
+      expect(joined).not.toContain("not to Cloudflare's edge");
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("two tunnels with different --tunnel-name coexist in state", async () => {
     const env = makeEnv();
     try {
@@ -929,6 +1114,46 @@ describe("exposeCloudflareOff", () => {
     }
   });
 
+  test("hub#487: off sweeps orphan connectors the state record didn't track", async () => {
+    const env = makeEnv();
+    try {
+      const uuid = "abababab-0000-0000-0000-000000000009";
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            parachute: {
+              pid: 55555,
+              tunnelUuid: uuid,
+              tunnelName: "parachute",
+              hostname: "vault.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+      const killed: number[] = [];
+      const code = await exposeCloudflareOff({
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => true,
+        kill: (pid) => killed.push(pid),
+        // pgrep finds the tracked pid (skipped — already signalled) plus an
+        // untracked orphan 66666 serving the same tunnel.
+        connectorPids: () => [55555, 66666],
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      // Tracked pid stopped once, orphan also stopped — no double-kill of 55555.
+      expect(killed.sort()).toEqual([55555, 66666]);
+      expect(existsSync(env.statePath)).toBe(false);
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("targets the named tunnel and leaves siblings intact", async () => {
     const env = makeEnv();
     try {

package/src/__tests__/hub.test.ts

@@ -5,7 +5,15 @@ import { join } from "node:path";
 import { renderHub, writeHubFile } from "../hub.ts";
 
 describe("renderHub", () => {
-  const html = renderHub();
+  // The verbose discovery body (Get started / Services / Admin) + its
+  // data-loading script render only for a signed-in visitor (the signed-out
+  // landing is slimmed — see the "signed-out slimming" describe block below).
+  // Assertions about that verbose body therefore run against a signed-in
+  // render; assertions about the page shell (doctype, styles, brand) hold for
+  // both and use whichever render is convenient.
+  const html = renderHub({
+    session: { displayName: "operator", csrfToken: "csrf-shell" },
+  });
 
   test("is a self-contained HTML document with inline styles and script", () => {
     expect(html).toStartWith("<!doctype html>");
@@ -162,12 +170,72 @@ describe("renderHub", () => {
   });
 
   test("default render (no session) emits the 'Sign in' affordance", () => {
-    expect(html).toContain('class="auth-indicator"');
-    expect(html).toContain("Sign in");
-    expect(html).toContain('href="/login?next=/"');
+    const out = renderHub();
+    expect(out).toContain('class="auth-indicator"');
+    expect(out).toContain("Sign in");
+    expect(out).toContain('href="/login?next=/"');
     // No POST form, no CSRF input — those only appear when signed in.
-    expect(html).not.toContain('action="/logout"');
-    expect(html).not.toContain("__csrf");
+    expect(out).not.toContain('action="/logout"');
+    expect(out).not.toContain("__csrf");
+  });
+});
+
+describe("renderHub — signed-out slimming (operator feedback)", () => {
+  // A signed-out visitor should see a clean, minimal landing: brand +
+  // tagline (in the header) + a single clear "Sign in" call. The hub's
+  // internal detail — the service catalog, vault listings, admin surfaces,
+  // and the well-known-driven loading script — must NOT render until the
+  // visitor authenticates. The signed-in render is unchanged.
+  const signedOut = renderHub();
+  const signedIn = renderHub({
+    session: { displayName: "operator", csrfToken: "csrf-xyz" },
+  });
+
+  test("signed-out: brand wordmark + tagline still render (the slim landing keeps the brand)", () => {
+    expect(signedOut).toContain("<h1>Parachute</h1>");
+    expect(signedOut).toContain("Truly personal computing. Your knowledge belongs with you.");
+  });
+
+  test("signed-out: a clear 'Sign in' call is the primary affordance", () => {
+    expect(signedOut).toContain('data-testid="signed-out-signin"');
+    expect(signedOut).toContain('href="/login?next=/"');
+    expect(signedOut).toContain("Sign in");
+  });
+
+  test("signed-out: the verbose Services / Admin / Get started sections are absent", () => {
+    expect(signedOut).not.toContain('id="services-section"');
+    expect(signedOut).not.toContain('id="admin-section"');
+    expect(signedOut).not.toContain('id="get-started-section"');
+    expect(signedOut).not.toContain("<h2>Services</h2>");
+    expect(signedOut).not.toContain("<h2>Admin</h2>");
+    // Admin links / token surface must not be exposed pre-auth.
+    expect(signedOut).not.toContain("/admin/vaults");
+    expect(signedOut).not.toContain("/admin/tokens");
+  });
+
+  test("signed-out: the well-known service-catalog loading script is not emitted", () => {
+    // No data-driven discovery body to populate when signed out → no script.
+    // (The brand mark is an inline SVG, not a <script>; assert on the IIFE's
+    // load function rather than a blanket "no <script>".) The footer's
+    // public "discovery" anchor → /.well-known/parachute.json stays — it's a
+    // plain link, not the catalog-fetching script — so assert on the fetch
+    // call + the loader function, not the URL string.
+    expect(signedOut).not.toContain("loadServices");
+    expect(signedOut).not.toContain("renderServices");
+    expect(signedOut).not.toContain("fetch('/.well-known/parachute.json'");
+    expect(signedOut).not.toContain("<script>");
+  });
+
+  test("signed-in: the verbose sections + loading script DO render (signed-in view unchanged)", () => {
+    expect(signedIn).toContain('id="services-section"');
+    expect(signedIn).toContain('id="admin-section"');
+    expect(signedIn).toContain('id="get-started-section"');
+    expect(signedIn).toContain("/admin/vaults");
+    expect(signedIn).toContain("/.well-known/parachute.json");
+    expect(signedIn).toContain("loadServices");
+    // And the signed-out lede / standalone Sign-in CTA is gone (the
+    // auth-indicator carries sign-out instead).
+    expect(signedIn).not.toContain('data-testid="signed-out-signin"');
   });
 });
 

package/src/__tests__/lifecycle.test.ts

@@ -783,6 +783,159 @@ describe("parachute start", () => {
       h.cleanup();
     }
   });
+
+  // hub#487 — readiness gating beyond the bare liveness settle. Aaron hit this
+  // on a fresh EC2 box: `parachute start vault` printed "✓ vault started" while
+  // the process died ~instantly on EADDRINUSE (an orphan held 1940), and
+  // `parachute status` then showed it inactive.
+
+  /**
+   * A stub spawner that also seeds the service's log file with `content`, so
+   * the readiness-failure path's log-tail + EADDRINUSE detection can read a
+   * realistic boot error. Mirrors how the real spawner appends stdout/stderr
+   * to the logfile.
+   */
+  function makeSpawnerWithLog(pid: number, content: string): SpawnerStub {
+    const calls: SpawnerStub["calls"] = [];
+    return {
+      calls,
+      spawn(cmd, logFile, opts) {
+        calls.push({ cmd: [...cmd], logFile, env: opts?.env, cwd: opts?.cwd });
+        // The start path calls ensureLogPath() before spawn, so logFile's
+        // parent dir already exists — just write the simulated boot output.
+        writeFileSync(logFile, content);
+        return pid;
+      },
+    };
+  }
+
+  test("hub#487: EADDRINUSE in the log → port-in-use message + log tail, not ✓", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawnerWithLog(
+        4242,
+        "booting vault…\nerror: listen EADDRINUSE: address already in use 0.0.0.0:1940\n",
+      );
+      const lines: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => false, // process died right after the EADDRINUSE throw
+        sleep: async () => {},
+        startSettleMs: 1,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(readPid("vault", h.configDir)).toBeUndefined();
+      const out = lines.join("\n");
+      expect(out).toMatch(/port 1940 is already in use/);
+      expect(out).toMatch(/lsof -ti:1940/);
+      // The real boot error is surfaced inline so the operator doesn't have to
+      // go tail the log themselves.
+      expect(out).toMatch(/EADDRINUSE/);
+      expect(out).not.toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#487: process survives settle but never binds its port → failure with log tail", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawnerWithLog(4242, "vault crashed mid-boot\n");
+      const lines: string[] = [];
+      let aliveCalls = 0;
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        // Alive through the settle + first readiness poll, then dies — the
+        // slow-EADDRINUSE / crash-after-boot shape.
+        alive: () => {
+          aliveCalls++;
+          return aliveCalls <= 1;
+        },
+        sleep: async () => {},
+        startSettleMs: 1,
+        startReadyMs: 50,
+        startReadyPollMs: 1,
+        portListening: async () => false, // never binds
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(readPid("vault", h.configDir)).toBeUndefined();
+      const out = lines.join("\n");
+      expect(out).toMatch(/✗ vault failed to start/);
+      expect(out).toMatch(/exited during startup/);
+      expect(out).not.toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#487: alive but port silent past the window → non-fatal warning, exit 0", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const lines: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => true, // stays up the whole time
+        sleep: async () => {},
+        startSettleMs: 1,
+        startReadyMs: 10,
+        startReadyPollMs: 1,
+        portListening: async () => false, // slow boot — not listening yet
+        log: (l) => lines.push(l),
+      });
+      // A slow-but-alive daemon isn't a hard failure — we warn rather than fail.
+      expect(code).toBe(0);
+      expect(readPid("vault", h.configDir)).toBe(4242);
+      const out = lines.join("\n");
+      expect(out).toMatch(/port 1940 isn't accepting connections yet/);
+      expect(out).not.toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#487: alive + port listening → success", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const lines: string[] = [];
+      let probeCalls = 0;
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => true,
+        sleep: async () => {},
+        startSettleMs: 1,
+        startReadyMs: 50,
+        startReadyPollMs: 1,
+        // Not listening on the first poll, bound on the second — exercises the
+        // poll loop rather than an instant true.
+        portListening: async () => {
+          probeCalls++;
+          return probeCalls >= 2;
+        },
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      expect(readPid("vault", h.configDir)).toBe(4242);
+      expect(lines.join("\n")).toMatch(/✓ vault started \(pid 4242\)/);
+    } finally {
+      h.cleanup();
+    }
+  });
 });
 
 describe("parachute stop", () => {