@openparachute/hub 0.5.13-rc.13 → 0.5.13-rc.21

package/package.json

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

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

@@ -70,6 +70,14 @@ function postReq(path: string, headers: Record<string, string>): Request {
   return new Request(`http://localhost${path}`, { method: "POST", headers });
 }
 
+function postReqJson(path: string, headers: Record<string, string>, body: unknown): Request {
+  return new Request(`http://localhost${path}`, {
+    method: "POST",
+    headers: { ...headers, "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
 function getReq(path: string, headers: Record<string, string>): Request {
   return new Request(`http://localhost${path}`, { method: "GET", headers });
 }
@@ -347,6 +355,222 @@ describe("POST /api/modules/:short/install", () => {
     expect(calls).not.toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
   });
 
+  // hub#337 — per-request channel in body + PARACHUTE_INSTALL_CHANNEL env var.
+  // Precedence: body.channel > PARACHUTE_INSTALL_CHANNEL env > hub_settings row > "latest".
+
+  test("body { channel: 'rc' } overrides the hub_settings row (hub#337)", async () => {
+    // SPA-driven "install X at rc" affordance: per-call override that
+    // doesn't flip the cluster-wide toggle.
+    setModuleInstallChannel(h.db, "latest");
+    const { supervisor } = makeIdleSupervisor();
+    const { run, calls } = alwaysOkRun();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleInstall(
+      postReqJson(
+        "/api/modules/vault/install",
+        { authorization: `Bearer ${bearer}` },
+        { channel: "rc" },
+      ),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run,
+      },
+    );
+    expect(res.status).toBe(202);
+    await new Promise((r) => setTimeout(r, 10));
+    expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
+    expect(calls).not.toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
+  });
+
+  test("body { channel: 'latest' } overrides hub_settings.module_install_channel = rc (hub#337)", async () => {
+    setModuleInstallChannel(h.db, "rc");
+    const { supervisor } = makeIdleSupervisor();
+    const { run, calls } = alwaysOkRun();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    await handleInstall(
+      postReqJson(
+        "/api/modules/vault/install",
+        { authorization: `Bearer ${bearer}` },
+        { channel: "latest" },
+      ),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run,
+      },
+    );
+    await new Promise((r) => setTimeout(r, 10));
+    expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
+    expect(calls).not.toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
+  });
+
+  test("body { channel: 'banana' } returns 400 invalid_channel (hub#337)", async () => {
+    // Operator-typed garbage in the SPA → don't silently fall through to
+    // the default; surface the typo immediately.
+    const { supervisor } = makeIdleSupervisor();
+    const { run } = alwaysOkRun();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleInstall(
+      postReqJson(
+        "/api/modules/vault/install",
+        { authorization: `Bearer ${bearer}` },
+        { channel: "banana" },
+      ),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run,
+      },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string; error_description: string };
+    expect(body.error).toBe("invalid_channel");
+    expect(body.error_description).toMatch(/banana/);
+  });
+
+  test("missing body / empty body falls through to hub_settings channel (back-compat)", async () => {
+    // Pre-hub#337 callers don't send a JSON body. The existing SPA paths
+    // (and the first-boot wizard) keep working unchanged.
+    setModuleInstallChannel(h.db, "rc");
+    const { supervisor } = makeIdleSupervisor();
+    const { run, calls } = alwaysOkRun();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    await handleInstall(
+      postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run,
+      },
+    );
+    await new Promise((r) => setTimeout(r, 10));
+    expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
+  });
+
+  test("PARACHUTE_INSTALL_CHANNEL env overrides hub_settings.module_install_channel (hub#337)", async () => {
+    // The Render-deploy cascade shape: the platform sets the env var to
+    // `rc`, hub's API path picks it up over the DB-stored default. Lets
+    // an operator-toggle override that the platform-team hasn't pinned
+    // still work via the SPA toggle below it — but with the env in
+    // play, the env wins.
+    setModuleInstallChannel(h.db, "latest");
+    const prior = process.env.PARACHUTE_INSTALL_CHANNEL;
+    process.env.PARACHUTE_INSTALL_CHANNEL = "rc";
+    try {
+      const { supervisor } = makeIdleSupervisor();
+      const { run, calls } = alwaysOkRun();
+      const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+      await handleInstall(
+        postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+        "vault",
+        {
+          db: h.db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          supervisor,
+          run,
+        },
+      );
+      await new Promise((r) => setTimeout(r, 10));
+      expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
+      expect(calls).not.toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
+    } finally {
+      // Bun's process.env supports the `[key]: undefined` shape
+      // (biome's noDelete rule preferred this over `delete`).
+      if (prior === undefined) process.env.PARACHUTE_INSTALL_CHANNEL = undefined;
+      else process.env.PARACHUTE_INSTALL_CHANNEL = prior;
+    }
+  });
+
+  test("body channel wins over PARACHUTE_INSTALL_CHANNEL env (hub#337)", async () => {
+    // Per-request override beats the platform default — the SPA's
+    // "install this one at latest even though the cluster's on rc" path.
+    setModuleInstallChannel(h.db, "latest");
+    const prior = process.env.PARACHUTE_INSTALL_CHANNEL;
+    process.env.PARACHUTE_INSTALL_CHANNEL = "rc";
+    try {
+      const { supervisor } = makeIdleSupervisor();
+      const { run, calls } = alwaysOkRun();
+      const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+      await handleInstall(
+        postReqJson(
+          "/api/modules/vault/install",
+          { authorization: `Bearer ${bearer}` },
+          { channel: "latest" },
+        ),
+        "vault",
+        {
+          db: h.db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          supervisor,
+          run,
+        },
+      );
+      await new Promise((r) => setTimeout(r, 10));
+      expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
+      expect(calls).not.toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
+    } finally {
+      // Bun's process.env supports the `[key]: undefined` shape
+      // (biome's noDelete rule preferred this over `delete`).
+      if (prior === undefined) process.env.PARACHUTE_INSTALL_CHANNEL = undefined;
+      else process.env.PARACHUTE_INSTALL_CHANNEL = prior;
+    }
+  });
+
+  test("garbage PARACHUTE_INSTALL_CHANNEL env falls back to hub_settings (no crash)", async () => {
+    // Operator typo at the platform layer shouldn't crash installs.
+    // Warns + falls through to the DB-stored channel.
+    setModuleInstallChannel(h.db, "rc");
+    const prior = process.env.PARACHUTE_INSTALL_CHANNEL;
+    process.env.PARACHUTE_INSTALL_CHANNEL = "banana";
+    try {
+      const { supervisor } = makeIdleSupervisor();
+      const { run, calls } = alwaysOkRun();
+      const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+      const res = await handleInstall(
+        postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+        "vault",
+        {
+          db: h.db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          supervisor,
+          run,
+        },
+      );
+      expect(res.status).toBe(202);
+      await new Promise((r) => setTimeout(r, 10));
+      // Falls back to the DB-stored rc, not "@latest".
+      expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
+    } finally {
+      // Bun's process.env supports the `[key]: undefined` shape
+      // (biome's noDelete rule preferred this over `delete`).
+      if (prior === undefined) process.env.PARACHUTE_INSTALL_CHANNEL = undefined;
+      else process.env.PARACHUTE_INSTALL_CHANNEL = prior;
+    }
+  });
+
   test("failed bun-add surfaces failed status on the operation", async () => {
     const { supervisor } = makeIdleSupervisor();
     // Run returns 1 + findGlobalInstall returns null = real failure.
@@ -490,6 +714,39 @@ describe("POST /api/modules/:short/upgrade", () => {
     expect(calls).not.toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
   });
 
+  test("PARACHUTE_INSTALL_CHANNEL env cascades to upgrade too (hub#339 symmetry)", async () => {
+    // The Render-deploy operator sets PARACHUTE_INSTALL_CHANNEL=rc cluster-
+    // wide expecting BOTH install and upgrade through the admin SPA to
+    // honor it. Asymmetry between the two paths would surprise them.
+    setModuleInstallChannel(h.db, "latest"); // DB says latest
+    const prior = process.env.PARACHUTE_INSTALL_CHANNEL;
+    process.env.PARACHUTE_INSTALL_CHANNEL = "rc"; // env says rc — should win
+    try {
+      const { supervisor } = makeIdleSupervisor();
+      await supervisor.start({ short: "vault", cmd: ["parachute-vault", "serve"] });
+      const { run, calls } = alwaysOkRun();
+      const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+      await handleUpgrade(
+        postReq("/api/modules/vault/upgrade", { authorization: `Bearer ${bearer}` }),
+        "vault",
+        {
+          db: h.db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          supervisor,
+          run,
+        },
+      );
+      await new Promise((r) => setTimeout(r, 10));
+      expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@rc"]);
+      expect(calls).not.toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
+    } finally {
+      if (prior === undefined) process.env.PARACHUTE_INSTALL_CHANNEL = undefined;
+      else process.env.PARACHUTE_INSTALL_CHANNEL = prior;
+    }
+  });
+
   test("fails with 'try install first' when module is installed but never supervised", async () => {
     // Module has a services.json row (e.g. seeded by `parachute install`
     // pre-supervisor era) but the supervisor never spawned it.
@@ -680,7 +937,6 @@ describe("well-known regen after module ops", () => {
     manifest: {
       name: string;
       manifestName: string;
-      kind: "api" | "frontend" | "tool";
       port: number;
       paths: string[];
       health: string;
@@ -708,7 +964,6 @@ describe("well-known regen after module ops", () => {
     const install = fakeInstall("@openparachute/vault", {
       name: "vault",
       manifestName: "parachute-vault",
-      kind: "api",
       port: 1940,
       paths: ["/vault/default"],
       health: "/vault/default/health",
@@ -812,7 +1067,6 @@ describe("well-known regen after module ops", () => {
     const install = fakeInstall("@openparachute/vault", {
       name: "vault",
       manifestName: "parachute-vault",
-      kind: "api",
       port: 1940,
       paths: ["/vault/default"],
       health: "/vault/default/health",
@@ -902,7 +1156,6 @@ describe("well-known regen after module ops", () => {
     const install = fakeInstall("@openparachute/vault", {
       name: "vault",
       manifestName: "parachute-vault",
-      kind: "api",
       port: 1940,
       paths: ["/vault/default"],
       health: "/vault/default/health",

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

@@ -315,6 +315,96 @@ describe("GET /api/modules", () => {
     expect(body.supervisor_available).toBe(true);
   });
 
+  test("populates management_url from a relative managementUrl + module mount (hub#342)", async () => {
+    // Vault declares `managementUrl: "/admin"` in its module.json — hub
+    // resolves that against the entry's mount path (`/vault/default`)
+    // to produce the absolute admin URL the SPA's "Open" button targets.
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.4.5",
+        installDir: "/install/dir/vault",
+      },
+    ]);
+    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 () => null,
+      readModuleManifest: async (installDir) => {
+        // Return a minimal module.json with managementUrl set. Cast the
+        // shape via `as unknown as ...` because the test only exercises
+        // the consumer-side resolver, not the validator (which lives in
+        // module-manifest.ts and has its own test suite).
+        if (installDir === "/install/dir/vault") {
+          return {
+            name: "parachute-vault",
+            manifestName: "parachute-vault",
+            displayName: "Vault",
+            tagline: "",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/health",
+            managementUrl: "/admin",
+          } as unknown as Awaited<
+            ReturnType<typeof import("../module-manifest.ts").readModuleManifest>
+          >;
+        }
+        return null;
+      },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      modules: Array<{ short: string; management_url: string | null }>;
+    };
+    const vault = body.modules.find((m) => m.short === "vault");
+    expect(vault?.management_url).toBe("/vault/default/admin");
+  });
+
+  test("management_url is null when the module declares neither managementUrl nor uiUrl (hub#342)", async () => {
+    // Scribe + runner today: no managementUrl declared yet. The SPA's
+    // "Open" button renders disabled with a follow-up tooltip in that
+    // case — null on the wire is the canonical signal.
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-scribe",
+        port: 1942,
+        paths: ["/scribe"],
+        health: "/scribe/health",
+        version: "0.1.0",
+        installDir: "/install/dir/scribe",
+      },
+    ]);
+    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 () => null,
+      readModuleManifest: async () =>
+        ({
+          name: "parachute-scribe",
+          manifestName: "parachute-scribe",
+          displayName: "Scribe",
+          tagline: "",
+          port: 1942,
+          paths: ["/scribe"],
+          health: "/health",
+        }) as unknown as Awaited<
+          ReturnType<typeof import("../module-manifest.ts").readModuleManifest>
+        >,
+    });
+    const body = (await res.json()) as {
+      modules: Array<{ short: string; management_url: string | null }>;
+    };
+    const scribe = body.modules.find((m) => m.short === "scribe");
+    expect(scribe?.management_url).toBeNull();
+  });
+
   test("npm probe failure → latest_version is null but response still 200", async () => {
     // The whole point of the probe-is-opportunistic posture: a flaky
     // npm registry must not break the page render. The UI handles

package/src/__tests__/cli.test.ts

@@ -64,6 +64,19 @@ describe("cli", () => {
     expect(stderr).toMatch(/usage: parachute install/);
   });
 
+  test("install --channel without a value exits 1 (hub#337)", async () => {
+    const { code, stderr } = await runCli(["install", "vault", "--channel"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/--channel requires a value/);
+  });
+
+  test("install --channel with an invalid value exits 1 (hub#337)", async () => {
+    const { code, stderr } = await runCli(["install", "vault", "--channel", "banana"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/--channel must be "rc" or "latest"/);
+    expect(stderr).toMatch(/banana/);
+  });
+
   test("unknown command exits 1", async () => {
     const { code, stderr } = await runCli(["wat"]);
     expect(code).toBe(1);

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

@@ -243,7 +243,6 @@ describe("hubFetch routing", () => {
         readModuleManifest: async () => ({
           name: "vault",
           manifestName: "parachute-vault",
-          kind: "api",
           port: 1940,
           paths: ["/vault/default"],
           health: "/health",
@@ -298,7 +297,6 @@ describe("hubFetch routing", () => {
         readModuleManifest: async () => ({
           name: "notes",
           manifestName: "parachute-notes",
-          kind: "frontend",
           port: 5173,
           paths: ["/notes"],
           health: "/health",
@@ -335,7 +333,6 @@ describe("hubFetch routing", () => {
         readModuleManifest: async () => ({
           name: "notes",
           manifestName: "parachute-notes",
-          kind: "frontend",
           port: 5173,
           paths: ["/notes"],
           health: "/health",
@@ -362,7 +359,6 @@ describe("hubFetch routing", () => {
         readModuleManifest: async () => ({
           name: "vault",
           manifestName: "parachute-vault",
-          kind: "api",
           port: 1940,
           paths: ["/vault/default"],
           health: "/health",
@@ -1940,19 +1936,20 @@ describe("hubFetch /<svc>/* generic proxy dispatch (#182)", () => {
     }
   });
 
-  test("routes a deep /agent/api/health to the matching upstream", async () => {
-    // Agent registers `/agent`; deeper paths route by prefix.
+  test("routes a deep /someapp/api/health to the matching upstream", async () => {
+    // A generic third-party module registers `/someapp`; deeper paths
+    // route by prefix.
     const h = makeHarness();
-    const upstream = startUpstream("agent");
+    const upstream = startUpstream("someapp");
     try {
       writeManifest(
         {
           services: [
             {
-              name: "agent",
+              name: "someapp",
               port: upstream.port,
-              paths: ["/agent"],
-              health: "/agent/api/health",
+              paths: ["/someapp"],
+              health: "/someapp/api/health",
               version: "0.1.0",
             },
           ],
@@ -1960,11 +1957,11 @@ describe("hubFetch /<svc>/* generic proxy dispatch (#182)", () => {
         h.manifestPath,
       );
       const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
-      const res = await fetcher(req("/agent/api/health?probe=1"));
+      const res = await fetcher(req("/someapp/api/health?probe=1"));
       expect(res.status).toBe(200);
       const body = (await res.json()) as { tag: string; pathname: string; search: string };
-      expect(body.tag).toBe("agent");
-      expect(body.pathname).toBe("/agent/api/health");
+      expect(body.tag).toBe("someapp");
+      expect(body.pathname).toBe("/someapp/api/health");
       expect(body.search).toBe("?probe=1");
     } finally {
       upstream.stop();