@openparachute/hub 0.3.0-rc.1

package/src/__tests__/hub-control.test.ts

@@ -0,0 +1,346 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type HubPortProbe,
+  type HubSpawner,
+  clearHubPort,
+  ensureHubRunning,
+  hubPortPath,
+  readHubPort,
+  stopHub,
+  writeHubPort,
+} from "../hub-control.ts";
+import { pidPath, readPid, writePid } from "../process-state.ts";
+
+interface Harness {
+  configDir: string;
+  wellKnownDir: string;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-hub-ctl-"));
+  return {
+    configDir: dir,
+    wellKnownDir: join(dir, "well-known"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+interface SpawnerStub {
+  spawn: HubSpawner["spawn"];
+  calls: Array<{ cmd: readonly string[]; logFile: string }>;
+}
+
+function makeSpawner(pid: number): SpawnerStub {
+  const calls: Array<{ cmd: readonly string[]; logFile: string }> = [];
+  return {
+    calls,
+    spawn(cmd, logFile) {
+      calls.push({ cmd: [...cmd], logFile });
+      return pid;
+    },
+  };
+}
+
+/** Probe that claims every port in a set is taken. */
+function probeTaken(taken: Set<number>): HubPortProbe {
+  return async (p) => !taken.has(p);
+}
+
+describe("port persistence helpers", () => {
+  test("writeHubPort + readHubPort round-trip", () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1942, h.configDir);
+      expect(readHubPort(h.configDir)).toBe(1942);
+      expect(existsSync(hubPortPath(h.configDir))).toBe(true);
+      clearHubPort(h.configDir);
+      expect(readHubPort(h.configDir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("ensureHubRunning", () => {
+  test("spawns with --port + --well-known-dir, writes pid + port files", async () => {
+    const h = makeHarness();
+    try {
+      const spawner = makeSpawner(5555);
+      const result = await ensureHubRunning({
+        configDir: h.configDir,
+        wellKnownDir: h.wellKnownDir,
+        spawner,
+        alive: () => true,
+        probe: probeTaken(new Set()),
+        readyWaitMs: 0,
+      });
+      expect(result.started).toBe(true);
+      expect(result.pid).toBe(5555);
+      expect(result.port).toBe(1939);
+      expect(spawner.calls).toHaveLength(1);
+      const cmd = spawner.calls[0]?.cmd ?? [];
+      expect(cmd[0]).toBe("bun");
+      expect(cmd).toContain("--port");
+      expect(cmd).toContain("1939");
+      expect(cmd).toContain("--well-known-dir");
+      expect(cmd).toContain(h.wellKnownDir);
+      expect(readPid("hub", h.configDir)).toBe(5555);
+      expect(readHubPort(h.configDir)).toBe(1939);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("default fallback is 1 slot: fails when 1939 is taken", async () => {
+    // Canonical layout pins hub to 1939. Walking up would collide with the
+    // next service's slot, so the default is to fail and let the user unblock
+    // the port — not quietly land somewhere else.
+    const h = makeHarness();
+    try {
+      const spawner = makeSpawner(7777);
+      await expect(
+        ensureHubRunning({
+          configDir: h.configDir,
+          wellKnownDir: h.wellKnownDir,
+          spawner,
+          alive: () => true,
+          probe: probeTaken(new Set([1939])),
+          readyWaitMs: 0,
+        }),
+      ).rejects.toThrow(/lsof -iTCP:1939/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("fallback walks up when caller widens the range (debug/tests only)", async () => {
+    const h = makeHarness();
+    try {
+      const spawner = makeSpawner(7777);
+      const result = await ensureHubRunning({
+        configDir: h.configDir,
+        wellKnownDir: h.wellKnownDir,
+        spawner,
+        alive: () => true,
+        probe: probeTaken(new Set([1939, 1940])),
+        readyWaitMs: 0,
+        fallbackRange: 5,
+      });
+      expect(result.port).toBe(1941);
+      expect(readHubPort(h.configDir)).toBe(1941);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("idempotent: returns existing pid + port when hub is already running", async () => {
+    const h = makeHarness();
+    try {
+      writePid("hub", 12345, h.configDir);
+      writeHubPort(1944, h.configDir);
+      const spawner = makeSpawner(9999);
+      const result = await ensureHubRunning({
+        configDir: h.configDir,
+        wellKnownDir: h.wellKnownDir,
+        spawner,
+        alive: () => true,
+        probe: probeTaken(new Set()),
+        readyWaitMs: 0,
+      });
+      expect(result.started).toBe(false);
+      expect(result.pid).toBe(12345);
+      expect(result.port).toBe(1944);
+      expect(spawner.calls).toHaveLength(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("stale pid (process gone) is cleared and a fresh hub is spawned", async () => {
+    const h = makeHarness();
+    try {
+      writePid("hub", 99, h.configDir);
+      writeHubPort(1939, h.configDir);
+      const spawner = makeSpawner(100);
+      const result = await ensureHubRunning({
+        configDir: h.configDir,
+        wellKnownDir: h.wellKnownDir,
+        spawner,
+        alive: () => false,
+        probe: probeTaken(new Set()),
+        readyWaitMs: 0,
+      });
+      expect(result.started).toBe(true);
+      expect(result.pid).toBe(100);
+      expect(spawner.calls).toHaveLength(1);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("throws when no port in the fallback range is free", async () => {
+    const h = makeHarness();
+    try {
+      const spawner = makeSpawner(1);
+      await expect(
+        ensureHubRunning({
+          configDir: h.configDir,
+          wellKnownDir: h.wellKnownDir,
+          spawner,
+          alive: () => true,
+          probe: async () => false,
+          readyWaitMs: 0,
+          fallbackRange: 3,
+        }),
+      ).rejects.toThrow(/unavailable/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("skips reserved service ports during fallback (widened range)", async () => {
+    // Fallback is off by default (range=1). When a caller opens it up for
+    // debug, reservedPorts must still be honored so the hub never steals a
+    // registered service's slot even if the service isn't yet bound.
+    const h = makeHarness();
+    try {
+      const spawner = makeSpawner(3333);
+      const result = await ensureHubRunning({
+        configDir: h.configDir,
+        wellKnownDir: h.wellKnownDir,
+        spawner,
+        alive: () => true,
+        probe: probeTaken(new Set([1939])), // default port is held
+        reservedPorts: [1940], // vault's reservation
+        readyWaitMs: 0,
+        fallbackRange: 5,
+      });
+      // 1939 is taken, 1940 is reserved → we get 1941.
+      expect(result.port).toBe(1941);
+      expect(readHubPort(h.configDir)).toBe(1941);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("honors startPort override", async () => {
+    const h = makeHarness();
+    try {
+      const spawner = makeSpawner(2222);
+      const result = await ensureHubRunning({
+        configDir: h.configDir,
+        wellKnownDir: h.wellKnownDir,
+        spawner,
+        alive: () => true,
+        probe: probeTaken(new Set()),
+        readyWaitMs: 0,
+        startPort: 18080,
+      });
+      expect(result.port).toBe(18080);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("stopHub", () => {
+  test("SIGTERMs running hub, clears pid + port", async () => {
+    const h = makeHarness();
+    try {
+      writePid("hub", 4242, h.configDir);
+      writeHubPort(1939, h.configDir);
+      let aliveNow = true;
+      const signals: NodeJS.Signals[] = [];
+      const stopped = await stopHub({
+        configDir: h.configDir,
+        kill: (_pid, sig) => {
+          signals.push(sig as NodeJS.Signals);
+          aliveNow = false;
+        },
+        alive: () => aliveNow,
+        sleep: async () => {},
+        now: () => 0,
+      });
+      expect(stopped).toBe(true);
+      expect(signals).toEqual(["SIGTERM"]);
+      expect(existsSync(pidPath("hub", h.configDir))).toBe(false);
+      expect(readHubPort(h.configDir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("escalates to SIGKILL when SIGTERM doesn't land", async () => {
+    const h = makeHarness();
+    try {
+      writePid("hub", 4242, h.configDir);
+      writeHubPort(1939, h.configDir);
+      let t = 0;
+      const signals: NodeJS.Signals[] = [];
+      const stopped = await stopHub({
+        configDir: h.configDir,
+        kill: (_pid, sig) => {
+          signals.push(sig as NodeJS.Signals);
+        },
+        alive: () => true,
+        sleep: async () => {
+          t += 1000;
+        },
+        now: () => t,
+        killWaitMs: 100,
+        pollIntervalMs: 10,
+      });
+      expect(stopped).toBe(true);
+      expect(signals).toEqual(["SIGTERM", "SIGKILL"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no-op + cleans port file when no pid recorded", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const stopped = await stopHub({
+        configDir: h.configDir,
+        kill: () => {
+          throw new Error("must not be called");
+        },
+        alive: () => true,
+        sleep: async () => {},
+        now: () => 0,
+      });
+      expect(stopped).toBe(false);
+      expect(readHubPort(h.configDir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("stale pid (process already gone) clears state without killing", async () => {
+    const h = makeHarness();
+    try {
+      writePid("hub", 77, h.configDir);
+      writeHubPort(1939, h.configDir);
+      let killCalled = false;
+      const stopped = await stopHub({
+        configDir: h.configDir,
+        kill: () => {
+          killCalled = true;
+        },
+        alive: () => false,
+        sleep: async () => {},
+        now: () => 0,
+      });
+      expect(stopped).toBe(false);
+      expect(killCalled).toBe(false);
+      expect(existsSync(pidPath("hub", h.configDir))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/hub-server.test.ts

@@ -0,0 +1,157 @@
+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 { hubFetch } from "../hub-server.ts";
+
+interface Harness {
+  dir: string;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-hub-server-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+function req(path: string, init?: RequestInit): Request {
+  return new Request(`http://127.0.0.1/${path.replace(/^\//, "")}`, init);
+}
+
+describe("hubFetch routing", () => {
+  test("/ serves hub.html with text/html content-type", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "hub.html"), "<html><body>hi</body></html>");
+      const res = hubFetch(h.dir)(req("/"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      expect(await res.text()).toContain("<html>");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("/hub.html serves the same file as /", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "hub.html"), "<html>x</html>");
+      const res = hubFetch(h.dir)(req("/hub.html"));
+      expect(res.status).toBe(200);
+      expect(await res.text()).toBe("<html>x</html>");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("/.well-known/parachute.json serves JSON with application/json", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "parachute.json"), '{"vaults":[]}\n');
+      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/json");
+      expect(await res.text()).toBe('{"vaults":[]}\n');
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // CORS on the well-known doc: browsers running the Notes UI on
+  // http://localhost:1942 fetch this manifest cross-origin to auto-discover
+  // the user's vault. Without these headers the browser blocks the response
+  // body and the auto-discover flow silently falls back to manual paste.
+  // The doc itself is public (no secrets, no PII), so wildcard origin is OK.
+  test("/.well-known/parachute.json includes wildcard CORS headers on GET", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "parachute.json"), '{"vaults":[]}\n');
+      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      expect(res.headers.get("access-control-allow-methods")).toBe("GET, OPTIONS");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("OPTIONS preflight on /.well-known/parachute.json returns 204 + CORS", async () => {
+    const h = makeHarness();
+    try {
+      // Note: no parachute.json on disk — preflight must not depend on it.
+      const res = hubFetch(h.dir)(req("/.well-known/parachute.json", { method: "OPTIONS" }));
+      expect(res.status).toBe(204);
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      expect(res.headers.get("access-control-allow-methods")).toBe("GET, OPTIONS");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("missing parachute.json still returns CORS headers on the 404", async () => {
+    // If the response 404s without CORS, the browser treats it as a network
+    // error and the consumer can't even tell the server is reachable.
+    const h = makeHarness();
+    try {
+      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(404);
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("unknown paths return 404", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "hub.html"), "<html/>");
+      const res = hubFetch(h.dir)(req("/nope"));
+      expect(res.status).toBe(404);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("missing hub.html returns 404 rather than crashing", async () => {
+    const h = makeHarness();
+    try {
+      // dir exists but no files in it
+      const res = hubFetch(h.dir)(req("/"));
+      expect(res.status).toBe(404);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("missing parachute.json returns 404 rather than crashing", async () => {
+    const h = makeHarness();
+    try {
+      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(404);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("live Bun.serve round-trip: / and /.well-known resolve", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "hub.html"), "<html>live</html>");
+      writeFileSync(join(h.dir, "parachute.json"), '{"services":[]}');
+      const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: hubFetch(h.dir) });
+      try {
+        const base = `http://127.0.0.1:${server.port}`;
+        const r1 = await fetch(`${base}/`);
+        expect(r1.status).toBe(200);
+        expect(await r1.text()).toBe("<html>live</html>");
+        const r2 = await fetch(`${base}/.well-known/parachute.json`);
+        expect(r2.headers.get("content-type")).toBe("application/json");
+        expect(await r2.json()).toEqual({ services: [] });
+      } finally {
+        server.stop(true);
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/hub.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { renderHub, writeHubFile } from "../hub.ts";
+
+describe("renderHub", () => {
+  const html = renderHub();
+
+  test("is a self-contained HTML document with inline styles and script", () => {
+    expect(html).toStartWith("<!doctype html>");
+    expect(html).toContain("<style>");
+    expect(html).toContain("<script>");
+  });
+
+  test("fetches /.well-known/parachute.json and iterates services[]", () => {
+    expect(html).toContain("/.well-known/parachute.json");
+    expect(html).toContain("doc.services");
+    expect(html).toContain("infoUrl");
+  });
+
+  test("uses parachute.computer sage palette and serif/sans fonts", () => {
+    expect(html).toContain("#4a7c59");
+    expect(html).toContain("#faf8f4");
+    expect(html).toContain("Instrument Serif");
+    expect(html).toContain("DM Sans");
+  });
+
+  test("supports prefers-color-scheme dark", () => {
+    expect(html).toContain("prefers-color-scheme: dark");
+  });
+
+  test("falls back to a generic icon when service has none", () => {
+    expect(html).toContain("fallbackIcon");
+  });
+
+  test("branches card rendering on info.kind (api/tool → interactive, else link)", () => {
+    // Script picks the element type and wires up toggling based on info.kind.
+    expect(html).toContain("isInteractiveKind");
+    expect(html).toContain("'api'");
+    expect(html).toContain("'tool'");
+    expect(html).toContain("'frontend'");
+  });
+
+  test("interactive cards get keyboard + aria affordances", () => {
+    expect(html).toContain("role");
+    expect(html).toContain("tabindex");
+    expect(html).toContain("aria-expanded");
+    expect(html).toContain("Enter");
+  });
+
+  test("detail panel surfaces OAuth discovery, MCP, open-in-Notes, service URL", () => {
+    expect(html).toContain("/.well-known/oauth-authorization-server");
+    expect(html).toContain("info.mcpUrl");
+    expect(html).toContain("info.openInNotesUrl");
+    expect(html).toContain("Service URL");
+    expect(html).toContain("OAuth discovery");
+  });
+
+  test("details panel is hidden until the card is expanded", () => {
+    expect(html).toContain(".details {");
+    expect(html).toContain("display: none");
+    expect(html).toContain(".card.expanded .details");
+  });
+
+  test("lazy-fetches /.parachute/config/schema + /.parachute/config on first expand", () => {
+    expect(html).toContain("fetchConfig");
+    expect(html).toContain("/.parachute/config/schema");
+    expect(html).toContain("/.parachute/config");
+    // Lazy: fetch happens inside the toggle, guarded by configLoaded.
+    expect(html).toContain("configLoaded");
+  });
+
+  test("renders config form fields with disabled inputs (read-only in this launch)", () => {
+    expect(html).toContain("renderConfigField");
+    expect(html).toContain("input.disabled = true");
+    expect(html).toContain("aria-readonly");
+    // Hint text tells users where to edit instead.
+    expect(html).toContain("read-only in this launch");
+  });
+
+  test("config field types: enum→select, boolean→checkbox, number→number, uri→url", () => {
+    expect(html).toContain("schema.enum");
+    expect(html).toContain("'checkbox'");
+    expect(html).toContain("'number'");
+    expect(html).toContain("'url'");
+  });
+
+  test("writeOnly fields render a bullet placeholder instead of the raw value", () => {
+    expect(html).toContain("writeOnly");
+    // Six bullets as the placeholder (template literal resolves \u2022 → •).
+    expect(html).toContain("\u2022\u2022\u2022\u2022\u2022\u2022");
+  });
+
+  test("schema 404 path renders nothing (no error surfaced)", () => {
+    // fetchConfig returns null on non-ok; caller skips render.
+    expect(html).toContain("if (!schemaResp || !schemaResp.ok) return null");
+    expect(html).toContain("if (data)");
+  });
+});
+
+describe("writeHubFile", () => {
+  test("writes the rendered HTML to the given path, creating parent dirs", () => {
+    const dir = mkdtempSync(join(tmpdir(), "pcli-hub-"));
+    try {
+      const path = join(dir, "well-known", "hub.html");
+      const written = writeHubFile(path);
+      expect(written).toBe(path);
+      expect(existsSync(path)).toBe(true);
+      const content = readFileSync(path, "utf8");
+      expect(content).toBe(renderHub());
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});