@openparachute/hub 0.3.0-rc.1 → 0.5.0

package/src/__tests__/hub.test.ts

@@ -13,10 +13,10 @@ describe("renderHub", () => {
     expect(html).toContain("<script>");
   });
 
-  test("fetches /.well-known/parachute.json and iterates services[]", () => {
+  test("fetches /.well-known/parachute.json and reads services[] + vaults[]", () => {
     expect(html).toContain("/.well-known/parachute.json");
     expect(html).toContain("doc.services");
-    expect(html).toContain("infoUrl");
+    expect(html).toContain("doc.vaults");
   });
 
   test("uses parachute.computer sage palette and serif/sans fonts", () => {
@@ -30,72 +30,79 @@ describe("renderHub", () => {
     expect(html).toContain("prefers-color-scheme: dark");
   });
 
-  test("falls back to a generic icon when service has none", () => {
+  test("falls back to a generic icon for module tiles", () => {
     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("renders one tile per module type, not per service instance", () => {
+    expect(html).toContain("aggregate(services, vaults)");
+    expect(html).toContain("renderTile");
+    expect(html).toContain("MODULE_ORDER");
   });
 
-  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("known module display order is vault → scribe → notes → agent", () => {
+    expect(html).toContain("['vault', 'scribe', 'notes', 'agent']");
   });
 
-  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("vault tile counts vaults[] (per instance) and links to /vault", () => {
+    // Vault count is the length of doc.vaults — one entry per /vault/<name>
+    // mount, so a single ServiceEntry with paths=[a,b,c] still shows "3
+    // registered". The manage link is the hub's vault SPA at /vault
+    // (renamed from /hub/vaults in the realignment), never an individual
+    // vault backend.
+    expect(html).toContain("vaults.length");
+    expect(html).toContain("'/vault'");
   });
 
-  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("non-vault tiles take their manageUrl from the service's path", () => {
+    // shortName('parachute-scribe') = 'scribe' → tile links to svc.path,
+    // which is whatever the module declared (e.g. /scribe, /notes, /agent).
+    // Hardcoding the link would silently break on a custom mount.
+    expect(html).toContain("manageUrl: svc.path");
   });
 
-  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("tiles for module types with zero instances are hidden", () => {
+    // Aggregate only inserts a group when the type has at least one entry;
+    // tilesInOrder iterates the map. No "0 registered" surface.
+    expect(html).not.toContain("0 registered");
+    expect(html).toContain("count === 1 ? '1 registered'");
   });
 
-  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("module labels are humanized (Vault / Scribe / Notes / Agent)", () => {
+    expect(html).toContain("vault: 'Vault'");
+    expect(html).toContain("scribe: 'Scribe'");
+    expect(html).toContain("notes: 'Notes'");
+    expect(html).toContain("agent: 'Agent'");
   });
 
-  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("vault-name detection covers parachute-vault and parachute-vault-<name>", () => {
+    // Phase-1 multi-vault keeps a single ServiceEntry with multiple paths
+    // (parachute-vault), but the door is open for per-instance entries
+    // (parachute-vault-techne). isVaultName has to accept both.
+    expect(html).toContain("isVaultName");
+    expect(html).toContain("'parachute-vault'");
+    expect(html).toContain("'parachute-vault-'");
   });
 
-  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("empty state when no modules are registered", () => {
+    expect(html).toContain("No modules installed yet");
+    expect(html).toContain("parachute install vault");
   });
 
-  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)");
+  test("error state surfaces the underlying message", () => {
+    expect(html).toContain("Could not load modules");
+  });
+
+  test("does not retain the per-service interactive-card / config-form code", () => {
+    // The home page is now a directory of modules — per-instance config
+    // forms and detail panels live behind the Manage links (vault SPA at
+    // /vault, the running module's own UI elsewhere). Keeping the
+    // dead code around is a maintenance trap.
+    expect(html).not.toContain("renderConfigField");
+    expect(html).not.toContain("fetchConfig");
+    expect(html).not.toContain("kind-badge");
+    expect(html).not.toContain("info.mcpUrl");
+    expect(html).not.toContain("info.openInNotesUrl");
   });
 });
 

package/src/__tests__/install.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { install } from "../commands/install.ts";
@@ -15,7 +15,7 @@ function makeTempPath(): { path: string; configDir: string; cleanup: () => void
 }
 
 describe("install", () => {
-  test("rejects unknown service with exit 1", async () => {
+  test("rejects third-party package with no module.json (hard error)", async () => {
     const { path, cleanup } = makeTempPath();
     try {
       const logs: string[] = [];
@@ -28,7 +28,7 @@ describe("install", () => {
         log: (l) => logs.push(l),
       });
       expect(code).toBe(1);
-      expect(logs.join("\n")).toMatch(/unknown service/);
+      expect(logs.join("\n")).toMatch(/does not ship \.parachute\/module\.json/);
     } finally {
       cleanup();
     }
@@ -1142,4 +1142,328 @@ describe("install", () => {
       cleanup();
     }
   });
+
+  test("third-party npm package with valid module.json installs", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install("@acme/widget", {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        readManifest: async () => ({
+          name: "widget",
+          manifestName: "@acme/widget",
+          kind: "api",
+          port: 1950,
+          paths: ["/widget"],
+          health: "/healthz",
+        }),
+        findGlobalInstall: () => "/fake/prefix/@acme/widget/package.json",
+      });
+      expect(code).toBe(0);
+      expect(calls[0]).toEqual(["bun", "add", "-g", "@acme/widget"]);
+      // hub#85: third-party rows are keyed by `manifest.name` (canonical
+      // short — what `parachute start <svc>` accepts), not `manifestName`.
+      const seeded = findService("widget", path);
+      expect(seeded?.name).toBe("widget");
+      expect(seeded?.port).toBe(1950);
+      expect(findService("@acme/widget", path)).toBeUndefined();
+      expect(logs.join("\n")).toMatch(/Seeded services\.json entry for widget/);
+      expect(logs.join("\n")).toMatch(/widget registered on port 1950/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("third-party npm package without module.json hard-errors", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("@acme/widget", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        readManifest: async () => null,
+        findGlobalInstall: () => "/fake/prefix/@acme/widget/package.json",
+      });
+      expect(code).toBe(1);
+      expect(logs.join("\n")).toMatch(/does not ship \.parachute\/module\.json/);
+      expect(logs.join("\n")).toMatch(/module-json-extensibility\.md/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("third-party module name colliding with first-party shortname is rejected", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("@evil/squatter", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        readManifest: async () => ({
+          name: "vault",
+          manifestName: "@evil/squatter",
+          kind: "api",
+          port: 1950,
+          paths: ["/vault"],
+          health: "/healthz",
+        }),
+        findGlobalInstall: () => "/fake/prefix/@evil/squatter/package.json",
+      });
+      expect(code).toBe(1);
+      expect(logs.join("\n")).toMatch(/collides with a first-party/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("local absolute path resolves package name + module.json", async () => {
+    const { path, cleanup } = makeTempPath();
+    const pkgDir = mkdtempSync(join(tmpdir(), "pcli-localpkg-"));
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install(pkgDir, {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        readManifest: async () => ({
+          name: "demo",
+          manifestName: "@local/demo",
+          kind: "api",
+          port: 1951,
+          paths: ["/demo"],
+          health: "/healthz",
+        }),
+        readPackageName: () => "@local/demo",
+      });
+      expect(code).toBe(0);
+      expect(calls[0]).toEqual(["bun", "add", "-g", pkgDir]);
+      // hub#85: third-party row keys by `manifest.name`, not `manifestName`.
+      const seeded = findService("demo", path);
+      expect(seeded?.name).toBe("demo");
+      expect(findService("@local/demo", path)).toBeUndefined();
+      // hub#83: lifecycle needs installDir to find module.json + spawn cwd.
+      expect(seeded?.installDir).toBe(pkgDir);
+    } finally {
+      cleanup();
+      rmSync(pkgDir, { recursive: true, force: true });
+    }
+  });
+
+  test("local-path re-install skips bun add when symlink already points at it (hub#89)", async () => {
+    // Reproduces the lockfile-pollution loop from hub#89: every
+    // `parachute install /path/to/checkout` shells out `bun add -g
+    // /path/to/checkout`, which appends a duplicate dependency to
+    // ~/.bun/install/global/package.json. After ~5 re-installs bun's
+    // lockfile parser gives up. Fix: if the global symlink already
+    // resolves to this exact path, the install is a no-op for bun-add.
+    const { path, cleanup } = makeTempPath();
+    const pkgDir = mkdtempSync(join(tmpdir(), "pcli-localpkg-"));
+    // macOS tmpdir is symlinked (/var → /private/var); install resolves
+    // both sides via realpath, so the stub must too.
+    const pkgDirReal = realpathSync(pkgDir);
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install(pkgDir, {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        // The symlink at <bun-globals>/node_modules/@local/demo already
+        // points at the same checkout we're installing — second-+ run.
+        linkedPath: (pkg) => (pkg === "@local/demo" ? pkgDirReal : null),
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        readManifest: async () => ({
+          name: "demo",
+          manifestName: "@local/demo",
+          kind: "api",
+          port: 1951,
+          paths: ["/demo"],
+          health: "/healthz",
+        }),
+        readPackageName: () => "@local/demo",
+      });
+      expect(code).toBe(0);
+      // No `bun add -g <pkgDir>` invocation — that's the whole point.
+      const bunAddCalls = calls.filter((c) => c[0] === "bun" && c[1] === "add");
+      expect(bunAddCalls).toEqual([]);
+      // Downstream init/seed/installDir wiring still ran.
+      const seeded = findService("demo", path);
+      expect(seeded?.installDir).toBe(pkgDir);
+      // Operator-visible breadcrumb so they understand why `bun add` was skipped.
+      expect(logs.join("\n")).toMatch(/already linked at .* — skipping bun add/);
+    } finally {
+      cleanup();
+      rmSync(pkgDir, { recursive: true, force: true });
+    }
+  });
+
+  test("local-path install still bun-adds when symlink points elsewhere (hub#89)", async () => {
+    // Operator moved their checkout: the global symlink is stale, pointing at
+    // a different abspath. Re-run bun add against the new path so the link
+    // gets refreshed (don't silently keep using the old target).
+    const { path, cleanup } = makeTempPath();
+    const pkgDir = mkdtempSync(join(tmpdir(), "pcli-localpkg-"));
+    try {
+      const calls: string[][] = [];
+      const code = await install(pkgDir, {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        linkedPath: () => "/Users/someone/old/checkout",
+        portProbe: async () => false,
+        log: () => {},
+        readManifest: async () => ({
+          name: "demo",
+          manifestName: "@local/demo",
+          kind: "api",
+          port: 1951,
+          paths: ["/demo"],
+          health: "/healthz",
+        }),
+        readPackageName: () => "@local/demo",
+      });
+      expect(code).toBe(0);
+      expect(calls[0]).toEqual(["bun", "add", "-g", pkgDir]);
+    } finally {
+      cleanup();
+      rmSync(pkgDir, { recursive: true, force: true });
+    }
+  });
+
+  test("npm-installed third-party module persists installDir from bun globals", async () => {
+    // hub#83: for `parachute install <npm-pkg>`, installDir is dirname of
+    // the package.json that findGlobalInstall returns. Without this,
+    // lifecycle has no way to locate the module's `.parachute/module.json`
+    // and third-party `parachute start <name>` fails post-install.
+    const { path, cleanup } = makeTempPath();
+    try {
+      const fakePrefix = "/fake/bun-globals/node_modules/@vendor/widget";
+      const code = await install("@vendor/widget", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: () => {},
+        readManifest: async () => ({
+          name: "widget",
+          manifestName: "@vendor/widget",
+          kind: "api",
+          port: 1952,
+          paths: ["/widget"],
+          health: "/widget/health",
+        }),
+        findGlobalInstall: () => `${fakePrefix}/package.json`,
+      });
+      expect(code).toBe(0);
+      // hub#85: third-party row keys by `manifest.name`, not `manifestName`.
+      const seeded = findService("widget", path);
+      expect(seeded?.installDir).toBe(fakePrefix);
+      expect(findService("@vendor/widget", path)).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("third-party with diverging name/manifestName keys services.json by name (hub#85)", async () => {
+    // Repro for parachute-hub#85: parachute-agent ships `name: "agent",
+    // manifestName: "parachute-agent"`. Install used to seed services.json
+    // under `parachute-agent` (the npm label) while lifecycle looks up by
+    // `agent` (the canonical short) → "unknown service". Fix: services.json
+    // key is always `manifest.name` for third-party.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const startCalls: string[] = [];
+      const logs: string[] = [];
+      const code = await install("parachute-agent", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async (short) => {
+          startCalls.push(short);
+          return 0;
+        },
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        readManifest: async () => ({
+          name: "agent",
+          manifestName: "parachute-agent",
+          kind: "api",
+          port: 1945,
+          paths: ["/agent"],
+          health: "/agent/health",
+          startCmd: ["bun", "server.ts"],
+        }),
+        findGlobalInstall: () => "/fake/prefix/parachute-agent/package.json",
+      });
+      expect(code).toBe(0);
+      // services.json is keyed by `name`, not `manifestName`.
+      expect(findService("agent", path)?.name).toBe("agent");
+      expect(findService("parachute-agent", path)).toBeUndefined();
+      // Auto-start receives the canonical short name (= manifest.name).
+      expect(startCalls).toEqual(["agent"]);
+      // Log lines speak in the canonical short name too. Port comes from
+      // assignServicePort (third-party gets the first unassigned canonical
+      // slot, currently 1944), not the manifest's port hint.
+      const joined = logs.join("\n");
+      expect(joined).toMatch(/Seeded services\.json entry for agent/);
+      expect(joined).toMatch(/agent registered on port \d+/);
+      expect(joined).not.toMatch(/Seeded services\.json entry for parachute-agent/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("local absolute path that doesn't exist fails fast", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("/nonexistent/path/xyz", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(1);
+      expect(logs.join("\n")).toMatch(/path does not exist/);
+    } finally {
+      cleanup();
+    }
+  });
 });

package/src/__tests__/jwks.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import { pemToJwk } from "../jwks.ts";
+
+function freshRsaPem(): string {
+  const { publicKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+  return publicKey.export({ format: "pem", type: "spki" }).toString();
+}
+
+describe("pemToJwk", () => {
+  test("returns a JWK with kty=RSA, alg=RS256, use=sig, and the supplied kid", () => {
+    const pem = freshRsaPem();
+    const jwk = pemToJwk(pem, "test-kid");
+    expect(jwk.kty).toBe("RSA");
+    expect(jwk.alg).toBe("RS256");
+    expect(jwk.use).toBe("sig");
+    expect(jwk.kid).toBe("test-kid");
+    // n + e are non-empty base64url strings.
+    expect(jwk.n.length).toBeGreaterThan(0);
+    expect(jwk.e.length).toBeGreaterThan(0);
+    expect(jwk.n).not.toMatch(/[+/=]/);
+    expect(jwk.e).not.toMatch(/[+/=]/);
+  });
+
+  test("rejects a non-RSA key", () => {
+    const { publicKey } = generateKeyPairSync("ed25519");
+    const pem = publicKey.export({ format: "pem", type: "spki" }).toString();
+    expect(() => pemToJwk(pem, "bad")).toThrow();
+  });
+
+  test("is deterministic for the same PEM + kid", () => {
+    const pem = freshRsaPem();
+    const a = pemToJwk(pem, "k");
+    const b = pemToJwk(pem, "k");
+    expect(b).toEqual(a);
+  });
+});