@openparachute/hub 0.5.12-rc.4 → 0.5.13-rc.4

package/package.json

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

package/src/__tests__/api-modules-config.test.ts

@@ -490,3 +490,252 @@ describe("handleApiModulesConfig — stripPrefix=false (notes-shape)", () => {
     expect(upstream.calls[0]?.url).toBe("http://127.0.0.1:1941/notes/.parachute/config/schema");
   });
 });
+
+/**
+ * hub#307: modules that declare `/.parachute` in their `paths[]` host the
+ * universal protocol endpoints at the bare URL — runner is the first
+ * example. Before this fix the proxy built `/runner/.parachute/config`
+ * (mount-prefixed because stripPrefix is false) and runner returned 404.
+ *
+ * The fix detects the `/.parachute` declaration in `paths[]` and routes
+ * to the bare URL regardless of `stripPrefix`. These tests pin that
+ * behavior + verify vault (mount-routed per-vault) keeps its prefixed
+ * path so the fix doesn't regress vault config.
+ */
+describe("handleApiModulesConfig — hostsBareParachute (hub#307)", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  test("runner (stripPrefix:false + /.parachute in paths) → bare /.parachute/config", async () => {
+    // Runner's FIRST_PARTY_FALLBACKS shape: paths includes `/.parachute`
+    // explicitly because runner serves the universal protocol at the bare
+    // URL. The services.json entry can carry either path first; we put
+    // `/runner` first to mirror what `parachute install runner` writes
+    // (matches the FIRST_PARTY_FALLBACKS manifest paths order).
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-runner",
+        port: 1945,
+        paths: ["/runner", "/.parachute"],
+        health: "/runner/healthz",
+        version: "0.1.0",
+        stripPrefix: false,
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_CONFIG_REQUIRED_SCOPE]);
+    const upstream = makeFakeUpstream(() =>
+      Response.json({ type: "object", properties: { intervalSeconds: { type: "number" } } }),
+    );
+    const res = await handleApiModulesConfig(
+      makeReq("/api/modules/runner/config/schema", {
+        headers: { authorization: `Bearer ${bearer}` },
+      }),
+      { short: "runner", suffix: "schema" },
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        upstreamFetch: upstream.fetchFn,
+      },
+    );
+    expect(res.status).toBe(200);
+    // No /runner prefix — bare /.parachute/config/schema. This is the
+    // hub#307 fix: pre-fix the URL was http://127.0.0.1:1945/runner/.parachute/config/schema
+    // and runner returned 404.
+    expect(upstream.calls[0]?.url).toBe("http://127.0.0.1:1945/.parachute/config/schema");
+  });
+
+  test("runner GET /config (no schema) also routes bare", async () => {
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-runner",
+        port: 1945,
+        paths: ["/runner", "/.parachute"],
+        health: "/runner/healthz",
+        version: "0.1.0",
+        stripPrefix: false,
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_CONFIG_REQUIRED_SCOPE]);
+    const upstream = makeFakeUpstream(() => Response.json({ intervalSeconds: 60 }));
+    await handleApiModulesConfig(
+      makeReq("/api/modules/runner/config", {
+        headers: { authorization: `Bearer ${bearer}` },
+      }),
+      { short: "runner", suffix: "" },
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        upstreamFetch: upstream.fetchFn,
+      },
+    );
+    expect(upstream.calls[0]?.url).toBe("http://127.0.0.1:1945/.parachute/config");
+  });
+
+  test("runner PUT /config also routes bare with body", async () => {
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-runner",
+        port: 1945,
+        paths: ["/runner", "/.parachute"],
+        health: "/runner/healthz",
+        version: "0.1.0",
+        stripPrefix: false,
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_CONFIG_REQUIRED_SCOPE]);
+    const upstream = makeFakeUpstream(() => Response.json({ restart_required: [] }));
+    await handleApiModulesConfig(
+      makeReq("/api/modules/runner/config", {
+        method: "PUT",
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ intervalSeconds: 120 }),
+      }),
+      { short: "runner", suffix: "" },
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        upstreamFetch: upstream.fetchFn,
+      },
+    );
+    const call = upstream.calls[0];
+    if (!call) throw new Error("upstream not called");
+    expect(call.url).toBe("http://127.0.0.1:1945/.parachute/config");
+    expect(call.method).toBe("PUT");
+    expect(call.body).toBe(JSON.stringify({ intervalSeconds: 120 }));
+  });
+
+  test("runner fallback (no services.json entry) — picks up /.parachute from FIRST_PARTY_FALLBACKS paths", async () => {
+    // bun-link / fresh-install case: the runner row isn't in services.json
+    // yet but the fallback declares the shape. resolveUpstream returns
+    // not-installed when neither the row nor the fallback can prove the
+    // module is up — so this case actually 404s. Pinned as the expected
+    // shape: hub#307 only changes the upstream-URL math, not the
+    // installed-detection contract.
+    const bearer = await mintBearer(h, [API_MODULES_CONFIG_REQUIRED_SCOPE]);
+    const res = await handleApiModulesConfig(
+      makeReq("/api/modules/runner/config", {
+        headers: { authorization: `Bearer ${bearer}` },
+      }),
+      { short: "runner", suffix: "" },
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+      },
+    );
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("module_not_installed");
+  });
+
+  test("vault (stripPrefix:false, no /.parachute in paths) — keeps /vault/<name> prefix (unchanged)", async () => {
+    // Vault's `.parachute/config` is per-vault, scoped under the
+    // `/vault/<name>` mount. Routing it bare would lose the vault-name
+    // context. This test pins that hub#307 doesn't regress vault.
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.5.0",
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_CONFIG_REQUIRED_SCOPE]);
+    const upstream = makeFakeUpstream(() => Response.json({ type: "object", properties: {} }));
+    await handleApiModulesConfig(
+      makeReq("/api/modules/vault/config/schema", {
+        headers: { authorization: `Bearer ${bearer}` },
+      }),
+      { short: "vault", suffix: "schema" },
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        upstreamFetch: upstream.fetchFn,
+      },
+    );
+    // Preserved mount — same as pre-hub#307.
+    expect(upstream.calls[0]?.url).toBe(
+      "http://127.0.0.1:1940/vault/default/.parachute/config/schema",
+    );
+  });
+
+  test("scribe (stripPrefix:true) — bare URL preserved (unchanged)", async () => {
+    // Pre-hub#307: stripPrefix:true produced /.parachute/config (via the
+    // stripPrefix branch). Post-fix: same result via the hostsBareParachute
+    // branch when /.parachute is in paths, or via the stripPrefix branch
+    // when it isn't. Scribe ships `paths: ["/scribe"]` (no /.parachute),
+    // so it takes the stripPrefix branch. Either way, the upstream URL is
+    // identical to pre-fix behavior.
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-scribe",
+        port: 1943,
+        paths: ["/scribe"],
+        health: "/health",
+        version: "0.4.0",
+        stripPrefix: true,
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_CONFIG_REQUIRED_SCOPE]);
+    const upstream = makeFakeUpstream(() => Response.json({ type: "object", properties: {} }));
+    await handleApiModulesConfig(
+      makeReq("/api/modules/scribe/config/schema", {
+        headers: { authorization: `Bearer ${bearer}` },
+      }),
+      { short: "scribe", suffix: "schema" },
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        upstreamFetch: upstream.fetchFn,
+      },
+    );
+    // Unchanged from pre-hub#307.
+    expect(upstream.calls[0]?.url).toBe("http://127.0.0.1:1943/.parachute/config/schema");
+  });
+
+  test("mixed: stripPrefix:false module with both /custom and /.parachute → bare for protocol, prefix for others", async () => {
+    // The hostsBareParachute branch only governs the `/.parachute/config*`
+    // proxy here. Other proxy code-paths (the generic services-proxy in
+    // hub-server.ts) handle non-protocol requests; this surface only ever
+    // forwards to `/.parachute/config[/schema]`, so verifying just that
+    // route is the right scope.
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-runner",
+        port: 1945,
+        // Order doesn't matter for hostsBareParachute detection.
+        paths: ["/.parachute", "/runner"],
+        health: "/runner/healthz",
+        version: "0.1.0",
+        stripPrefix: false,
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_CONFIG_REQUIRED_SCOPE]);
+    const upstream = makeFakeUpstream(() => Response.json({ type: "object", properties: {} }));
+    await handleApiModulesConfig(
+      makeReq("/api/modules/runner/config/schema", {
+        headers: { authorization: `Bearer ${bearer}` },
+      }),
+      { short: "runner", suffix: "schema" },
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        upstreamFetch: upstream.fetchFn,
+      },
+    );
+    expect(upstream.calls[0]?.url).toBe("http://127.0.0.1:1945/.parachute/config/schema");
+  });
+});

package/src/__tests__/api-modules.test.ts

@@ -149,8 +149,8 @@ describe("GET /api/modules", () => {
 
   test("200 + curated list on fresh container (empty services.json)", async () => {
     // The v0.6 hot path: brand-new Render container, no services.json
-    // yet. UI must render "install vault / notes / scribe" cards even
-    // though nothing's installed.
+    // yet. UI must render "install vault / notes / scribe / runner"
+    // cards even though nothing's installed.
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
     const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
       db: h.db,
@@ -168,8 +168,8 @@ describe("GET /api/modules", () => {
       }>;
       supervisor_available: boolean;
     };
-    // Curated order is preserved: vault → notes → scribe.
-    expect(body.modules.map((m) => m.short)).toEqual(["vault", "notes", "scribe"]);
+    // Curated order is preserved: vault → notes → scribe → runner.
+    expect(body.modules.map((m) => m.short)).toEqual(["vault", "notes", "scribe", "runner"]);
     expect(body.modules.every((m) => m.available)).toBe(true);
     expect(body.modules.every((m) => !m.installed)).toBe(true);
     expect(body.modules.every((m) => m.latest_version === "0.9.9")).toBe(true);
@@ -177,6 +177,36 @@ describe("GET /api/modules", () => {
     expect(body.supervisor_available).toBe(false);
   });
 
+  test("runner row carries package + display props from FIRST_PARTY_FALLBACKS (#305)", async () => {
+    // hub#305 added runner to CURATED_MODULES + FIRST_PARTY_FALLBACKS so
+    // the admin SPA install catalog surfaces it. Spot-check the wire
+    // shape resolves the runner-specific fields (package, displayName,
+    // tagline) from the vendored fallback rather than a stale default.
+    const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => "0.1.0",
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      modules: Array<{
+        short: string;
+        package: string;
+        display_name: string;
+        tagline: string;
+        available: boolean;
+      }>;
+    };
+    const runner = body.modules.find((m) => m.short === "runner");
+    expect(runner).toBeDefined();
+    expect(runner?.package).toBe("@openparachute/runner");
+    expect(runner?.display_name).toBe("Runner");
+    expect(runner?.tagline).toContain("Vault-as-job-substrate");
+    expect(runner?.available).toBe(true);
+  });
+
   test("surfaces installed_version from services.json", async () => {
     writeManifest(h.manifestPath, [
       {

package/src/__tests__/post-install.test.ts

@@ -0,0 +1,294 @@
+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 { finalizeModuleInstall, refreshWellKnown, stampInstallDirOnRow } from "../post-install.ts";
+import { findService, upsertService } from "../services-manifest.ts";
+
+/**
+ * Tail-end helpers shared between CLI install (`commands/install.ts`) and
+ * API install (`api-modules-ops.ts`). Cover the two responsibilities
+ * independently + the paired `finalizeModuleInstall` entry point so a
+ * future drift in either call site (the failure mode hub#292 / hub#298
+ * traced) surfaces here.
+ */
+
+function makeHarness(): {
+  dir: string;
+  servicesJsonPath: string;
+  wellKnownPath: string;
+  cleanup: () => void;
+} {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-post-install-"));
+  return {
+    dir,
+    servicesJsonPath: join(dir, "services.json"),
+    wellKnownPath: join(dir, "well-known.json"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+describe("stampInstallDirOnRow", () => {
+  test("stamps installDir on an existing row + returns true", () => {
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/vault/default/health",
+          version: "0.2.4",
+        },
+        h.servicesJsonPath,
+      );
+      const wrote = stampInstallDirOnRow({
+        manifestName: "parachute-vault",
+        installDir: "/fake/install/vault",
+        servicesJsonPath: h.servicesJsonPath,
+      });
+      expect(wrote).toBe(true);
+      const row = findService("parachute-vault", h.servicesJsonPath);
+      expect(row?.installDir).toBe("/fake/install/vault");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no-ops when the row already carries the same installDir", () => {
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/vault/default/health",
+          version: "0.2.4",
+          installDir: "/fake/install/vault",
+        },
+        h.servicesJsonPath,
+      );
+      const wrote = stampInstallDirOnRow({
+        manifestName: "parachute-vault",
+        installDir: "/fake/install/vault",
+        servicesJsonPath: h.servicesJsonPath,
+      });
+      expect(wrote).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no-ops + returns false when the row doesn't exist", () => {
+    const h = makeHarness();
+    try {
+      const wrote = stampInstallDirOnRow({
+        manifestName: "parachute-vault",
+        installDir: "/fake/install/vault",
+        servicesJsonPath: h.servicesJsonPath,
+      });
+      expect(wrote).toBe(false);
+      expect(findService("parachute-vault", h.servicesJsonPath)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("refreshWellKnown", () => {
+  test("writes the on-disk doc + logs the regenerated path", async () => {
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/vault/default/health",
+          version: "0.2.4",
+        },
+        h.servicesJsonPath,
+      );
+      const logs: string[] = [];
+      await refreshWellKnown({
+        servicesJsonPath: h.servicesJsonPath,
+        canonicalOrigin: "https://hub.example.com",
+        wellKnownPath: h.wellKnownPath,
+        log: (msg) => logs.push(msg),
+      });
+      expect(existsSync(h.wellKnownPath)).toBe(true);
+      expect(logs).toEqual([`regenerated ${h.wellKnownPath}`]);
+      const doc = JSON.parse(readFileSync(h.wellKnownPath, "utf8")) as {
+        services: Array<{ name: string }>;
+        vaults: Array<{ name: string }>;
+      };
+      expect(doc.services.some((s) => s.name === "parachute-vault")).toBe(true);
+      expect(doc.vaults.some((v) => v.name === "default")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("logs failure + does not throw when the well-known write itself errors", async () => {
+    const h = makeHarness();
+    try {
+      // Point wellKnownPath at a directory rather than a file — writeFileSync
+      // → renameSync surfaces as EISDIR (or platform-equivalent), which the
+      // helper must catch and report rather than letting it propagate up
+      // and abort an otherwise-successful install op.
+      const logs: string[] = [];
+      await refreshWellKnown({
+        servicesJsonPath: h.servicesJsonPath,
+        canonicalOrigin: "https://hub.example.com",
+        wellKnownPath: h.dir, // tempdir itself, not a file inside it
+        log: (msg) => logs.push(msg),
+      });
+      expect(logs.some((l) => l.startsWith("well-known regen failed:"))).toBe(true);
+      expect(logs.some((l) => l.startsWith("regenerated"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("threads readModuleManifest through to the regen so uiUrl lands", async () => {
+    const h = makeHarness();
+    try {
+      const installDir = "/fake/install/notes";
+      upsertService(
+        {
+          name: "parachute-notes",
+          port: 5173,
+          paths: ["/notes"],
+          health: "/notes/health",
+          version: "0.1.0",
+          installDir,
+        },
+        h.servicesJsonPath,
+      );
+      await refreshWellKnown({
+        servicesJsonPath: h.servicesJsonPath,
+        canonicalOrigin: "https://hub.example.com",
+        wellKnownPath: h.wellKnownPath,
+        log: () => {},
+        readModuleManifest: async (dir) =>
+          dir === installDir
+            ? {
+                name: "notes",
+                manifestName: "parachute-notes",
+                kind: "frontend",
+                port: 5173,
+                paths: ["/notes"],
+                health: "/notes/health",
+                uiUrl: "/notes",
+                displayName: "Notes",
+              }
+            : null,
+      });
+      const doc = JSON.parse(readFileSync(h.wellKnownPath, "utf8")) as {
+        services: Array<{ name: string; uiUrl?: string; displayName?: string }>;
+      };
+      const row = doc.services.find((s) => s.name === "parachute-notes");
+      expect(row?.uiUrl).toBe("https://hub.example.com/notes");
+      expect(row?.displayName).toBe("Notes");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("finalizeModuleInstall", () => {
+  test("stamps installDir AND regenerates well-known in one call", async () => {
+    const h = makeHarness();
+    try {
+      const installDir = "/fake/install/vault";
+      upsertService(
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/vault/default/health",
+          version: "0.2.4",
+        },
+        h.servicesJsonPath,
+      );
+      const logs: string[] = [];
+      await finalizeModuleInstall({
+        manifestName: "parachute-vault",
+        installDir,
+        servicesJsonPath: h.servicesJsonPath,
+        canonicalOrigin: "https://hub.example.com",
+        wellKnownPath: h.wellKnownPath,
+        log: (msg) => logs.push(msg),
+      });
+      // Stamp landed.
+      const row = findService("parachute-vault", h.servicesJsonPath);
+      expect(row?.installDir).toBe(installDir);
+      // Well-known reflects the stamped row.
+      expect(existsSync(h.wellKnownPath)).toBe(true);
+      const doc = JSON.parse(readFileSync(h.wellKnownPath, "utf8")) as {
+        services: Array<{ name: string; version: string }>;
+      };
+      expect(doc.services.some((s) => s.name === "parachute-vault")).toBe(true);
+      // The regen-success log fired exactly once — no double-regen from
+      // the helper.
+      expect(logs.filter((l) => l.startsWith("regenerated"))).toHaveLength(1);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("CLI- and API-path inputs produce byte-identical well-known docs", async () => {
+    // The PR's pure-refactor invariant (hub#293): both paths funnel
+    // through this helper, so given the same row state + same origin +
+    // same module manifest, the on-disk doc must be identical regardless
+    // of which call site drove it. Regression canary against the helper
+    // silently growing per-caller branching.
+    const cli = makeHarness();
+    const api = makeHarness();
+    try {
+      const installDir = "/fake/install/vault";
+      const row = {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.2.4",
+      };
+      upsertService(row, cli.servicesJsonPath);
+      upsertService(row, api.servicesJsonPath);
+      const manifest = {
+        name: "vault",
+        manifestName: "parachute-vault",
+        kind: "api" as const,
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        managementUrl: "/vault/default/admin",
+      };
+      const opts = {
+        manifestName: "parachute-vault",
+        installDir,
+        canonicalOrigin: "https://hub.example.com",
+        log: () => {},
+        readModuleManifest: async (dir: string) => (dir === installDir ? manifest : null),
+      };
+      await finalizeModuleInstall({
+        ...opts,
+        servicesJsonPath: cli.servicesJsonPath,
+        wellKnownPath: cli.wellKnownPath,
+      });
+      await finalizeModuleInstall({
+        ...opts,
+        servicesJsonPath: api.servicesJsonPath,
+        wellKnownPath: api.wellKnownPath,
+      });
+      const cliDoc = readFileSync(cli.wellKnownPath, "utf8");
+      const apiDoc = readFileSync(api.wellKnownPath, "utf8");
+      expect(cliDoc).toEqual(apiDoc);
+    } finally {
+      cli.cleanup();
+      api.cleanup();
+    }
+  });
+});

package/src/__tests__/setup.test.ts

@@ -122,6 +122,7 @@ describe("setup", () => {
         { name: "parachute-notes", port: 1942 },
         { name: "parachute-scribe", port: 1943 },
         { name: "parachute-channel", port: 1941 },
+        { name: "parachute-runner", port: 1945 },
       ];
       for (const s of seeds) {
         upsertService(