@openparachute/hub 0.6.2 → 0.6.3-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.2",
+  "version": "0.6.3-rc.1",
   "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

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { MissingDependencyError, lookupDep } from "@openparachute/depcheck";
@@ -7,8 +7,11 @@ import {
   API_MODULES_OPS_REQUIRED_SCOPE,
   _resetOperationsRegistryForTests,
   handleInstall,
+  handleLogs,
   handleOperationGet,
   handleRestart,
+  handleStart,
+  handleStop,
   handleUninstall,
   handleUpgrade,
   parseModulesPath,
@@ -88,6 +91,11 @@ function makeIdleSupervisor(): {
   spawns: SpawnRequest[];
 } {
   const spawns: SpawnRequest[] = [];
+  // Track each spawned proc by pid so the injected group-aware `killFn` can
+  // forward the signal to the right fake (post-hub#88, `stop()` signals via
+  // `killFn`, not `proc.kill` — so without this seam the fake's `exited` never
+  // resolves and `stop`/`restart` time out).
+  const byPid = new Map<number, SupervisedProc & { kill: () => void }>();
   const spawnFn = (req: SpawnRequest): SupervisedProc => {
     spawns.push(req);
     // The fake's `exited` resolves when kill() is called, mirroring a
@@ -97,15 +105,22 @@ function makeIdleSupervisor(): {
     const exited = new Promise<number | null>((r) => {
       resolveExit = r;
     });
-    return {
+    const proc: SupervisedProc & { kill: () => void } = {
       pid: 7777,
       exited,
       stdout: null,
       stderr: null,
       kill: () => resolveExit(0),
     };
+    byPid.set(proc.pid, proc);
+    return proc;
+  };
+  // Mirrors production's group-aware kill: the supervisor passes the leader
+  // pid, we forward to the matching fake's `kill` (which resolves `exited`).
+  const killFn = (pid: number): void => {
+    byPid.get(Math.abs(pid))?.kill();
   };
-  return { supervisor: new Supervisor({ spawnFn }), spawns };
+  return { supervisor: new Supervisor({ spawnFn, killFn }), spawns };
 }
 
 function writeManifest(path: string, services: unknown[]): void {
@@ -152,6 +167,17 @@ describe("parseModulesPath", () => {
     });
   });
 
+  test("recognizes the Phase 1 start / stop verbs", () => {
+    expect(parseModulesPath("/api/modules/vault/start")).toEqual({
+      short: "vault",
+      rest: "start",
+    });
+    expect(parseModulesPath("/api/modules/scribe/stop")).toEqual({
+      short: "scribe",
+      rest: "stop",
+    });
+  });
+
   test("rejects non-curated shorts (no marketplace yet)", () => {
     // Channel exists in FIRST_PARTY_FALLBACKS but is exploration, not
     // in CURATED_MODULES — the v0.6 surface refuses to drive it via
@@ -740,6 +766,207 @@ describe("POST /api/modules/:short/install", () => {
   });
 });
 
+describe("POST /api/modules/:short/start", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+    _resetOperationsRegistryForTests();
+  });
+  afterEach(() => h.cleanup());
+
+  /** Seed a minimal installed vault row (in services.json) for the start tests. */
+  function seedVault(port = 1940): void {
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.0.0-linked",
+      },
+    ]);
+  }
+
+  test("401 on missing bearer", async () => {
+    seedVault();
+    const { supervisor } = makeIdleSupervisor();
+    const res = await handleStart(postReq("/api/modules/vault/start", {}), "vault", {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("403 on bearer without parachute:host:admin (host-admin gated)", async () => {
+    seedVault();
+    const { supervisor } = makeIdleSupervisor();
+    const bearer = await mintBearer(h, ["parachute:host:auth"]);
+    const res = await handleStart(
+      postReq("/api/modules/vault/start", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("pure supervisor.start of an installed module — NOT install (no bun add)", async () => {
+    seedVault();
+    const { supervisor, spawns } = makeIdleSupervisor();
+    const { run, calls } = alwaysOkRun();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleStart(
+      postReq("/api/modules/vault/start", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run,
+      },
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { short: string; state: { status: string } };
+    expect(body.short).toBe("vault");
+    expect(["starting", "running"]).toContain(body.state.status);
+    // The supervisor was handed the boot-derived spawn request.
+    expect(spawns.find((s) => s.short === "vault")?.cmd).toEqual(["parachute-vault", "serve"]);
+    // Crucially: start is a PURE spawn — it must NOT run the install path.
+    expect(calls).toEqual([]);
+  });
+
+  test("start carries boot-derived PORT + PARACHUTE_HUB_ORIGIN child env", async () => {
+    seedVault(1940);
+    const { supervisor, spawns } = makeIdleSupervisor();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    await handleStart(
+      postReq("/api/modules/vault/start", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(spawns.length).toBe(1);
+    expect(spawns[0]?.env?.PORT).toBe("1940");
+    expect(spawns[0]?.env?.PARACHUTE_HUB_ORIGIN).toBe(ISSUER);
+  });
+
+  test("start layers the per-service .env into the supervisor spawn env", async () => {
+    // The boot-derived spawn contract (buildModuleSpawnRequest) reads
+    // `<configDir>/<short>/.env` and merges it into the child env. This is
+    // the asymmetry the spawnSupervised doc comment calls out: install spawns
+    // with install-env only; the operator-written `.env` is layered in on the
+    // next `start` / boot. Prove a distinctive var written to vault's `.env`
+    // reaches the recorded SpawnRequest.
+    seedVault(1940);
+    mkdirSync(join(h.dir, "vault"), { recursive: true });
+    writeFileSync(join(h.dir, "vault", ".env"), "MY_CUSTOM_VAR=sentinel123\n");
+    const { supervisor, spawns } = makeIdleSupervisor();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    await handleStart(
+      postReq("/api/modules/vault/start", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(spawns.length).toBe(1);
+    expect(spawns[0]?.env?.MY_CUSTOM_VAR).toBe("sentinel123");
+  });
+
+  test("400 not_installed when the module isn't in services.json (no silent install)", async () => {
+    // No seedVault — services.json has no vault row.
+    const { supervisor, spawns } = makeIdleSupervisor();
+    const { run, calls } = alwaysOkRun();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleStart(
+      postReq("/api/modules/vault/start", { authorization: `Bearer ${bearer}` }),
+      "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 };
+    expect(body.error).toBe("not_installed");
+    // Did NOT spawn + did NOT install.
+    expect(spawns).toEqual([]);
+    expect(calls).toEqual([]);
+  });
+});
+
+describe("POST /api/modules/:short/stop", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+    _resetOperationsRegistryForTests();
+  });
+  afterEach(() => h.cleanup());
+
+  test("401 on missing bearer", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const res = await handleStop(postReq("/api/modules/vault/stop", {}), "vault", {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("403 on bearer without parachute:host:admin (host-admin gated)", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const bearer = await mintBearer(h, ["parachute:host:auth"]);
+    const res = await handleStop(
+      postReq("/api/modules/vault/stop", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("calls supervisor.stop on a running module → stopped: true", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    await supervisor.start({ short: "vault", cmd: ["parachute-vault", "serve"] });
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleStop(
+      postReq("/api/modules/vault/stop", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      short: string;
+      stopped: boolean;
+      state: { status: string };
+    };
+    expect(body.short).toBe("vault");
+    expect(body.stopped).toBe(true);
+    expect(body.state.status).toBe("stopped");
+    // Supervisor truly transitioned the module to stopped.
+    expect(supervisor.get("vault")?.status).toBe("stopped");
+  });
+
+  test("idempotent: stopping a not-supervised module → stopped: false (no error)", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleStop(
+      postReq("/api/modules/vault/stop", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { short: string; stopped: boolean };
+    expect(body.stopped).toBe(false);
+  });
+});
+
 describe("POST /api/modules/:short/restart", () => {
   let h: Harness;
   beforeEach(async () => {
@@ -1415,3 +1642,132 @@ describe("well-known regen after module ops", () => {
     expect(second).toBe(first);
   });
 });
+
+describe("GET /api/modules/:short/logs (§6.5 ring-buffer tap)", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+    _resetOperationsRegistryForTests();
+  });
+  afterEach(() => h.cleanup());
+
+  /**
+   * Supervisor whose child exposes a controllable stdout stream so the test
+   * can push lines into the ring buffer, then tap them through the endpoint.
+   */
+  function makeEmittingSupervisor(): {
+    supervisor: Supervisor;
+    emit: (chunk: string) => void;
+  } {
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    const stdout = new ReadableStream<Uint8Array>({
+      start(c) {
+        controller = c;
+      },
+    });
+    const enc = new TextEncoder();
+    const spawnFn = (): SupervisedProc => ({
+      pid: 4321,
+      exited: new Promise<number | null>(() => {}),
+      stdout,
+      stderr: null,
+      kill: () => {},
+    });
+    return {
+      supervisor: new Supervisor({ spawnFn, killFn: () => {} }),
+      emit: (chunk) => controller.enqueue(enc.encode(chunk)),
+    };
+  }
+
+  function logsDeps(supervisor: Supervisor) {
+    return { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor };
+  }
+
+  test("401 on missing bearer", async () => {
+    const { supervisor } = makeEmittingSupervisor();
+    const res = await handleLogs(
+      getReq("/api/modules/vault/logs", {}),
+      "vault",
+      logsDeps(supervisor),
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("403 on bearer without parachute:host:admin (host-admin gated)", async () => {
+    const { supervisor } = makeEmittingSupervisor();
+    const bearer = await mintBearer(h, ["parachute:host:auth"]);
+    const res = await handleLogs(
+      getReq("/api/modules/vault/logs", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      logsDeps(supervisor),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("405 on non-GET", async () => {
+    const { supervisor } = makeEmittingSupervisor();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleLogs(
+      postReq("/api/modules/vault/logs", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      logsDeps(supervisor),
+    );
+    expect(res.status).toBe(405);
+  });
+
+  test("404 not_supervised for a module that isn't supervised", async () => {
+    const { supervisor } = makeEmittingSupervisor();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleLogs(
+      getReq("/api/modules/vault/logs", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      logsDeps(supervisor),
+    );
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("not_supervised");
+  });
+
+  test("replays the ring buffer (lines emitted before the tap) as lines + text", async () => {
+    const { supervisor, emit } = makeEmittingSupervisor();
+    await supervisor.start({ short: "vault", cmd: ["parachute-vault", "serve"] });
+    // Output happens BEFORE the operator opens the logs view.
+    emit("booting\n");
+    emit("FATAL: boom\n");
+    await new Promise((r) => setTimeout(r, 20));
+
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleLogs(
+      getReq("/api/modules/vault/logs", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      logsDeps(supervisor),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { short: string; lines: string[]; text: string };
+    expect(body.short).toBe("vault");
+    expect(body.lines).toEqual(["[vault] booting\n", "[vault] FATAL: boom\n"]);
+    expect(body.text).toBe("[vault] booting\n[vault] FATAL: boom\n");
+  });
+
+  test("?follow=1 streams the buffered replay first (text/plain)", async () => {
+    const { supervisor, emit } = makeEmittingSupervisor();
+    await supervisor.start({ short: "vault", cmd: ["parachute-vault", "serve"] });
+    emit("pre-connect line\n");
+    await new Promise((r) => setTimeout(r, 20));
+
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleLogs(
+      getReq("/api/modules/vault/logs?follow=1", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      logsDeps(supervisor),
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/plain");
+    // Read the first chunk — it must contain the replayed buffer line.
+    const reader = res.body!.getReader();
+    const { value } = await reader.read();
+    const text = new TextDecoder().decode(value);
+    expect(text).toContain("[vault] pre-connect line\n");
+    await reader.cancel();
+  });
+});

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

@@ -325,6 +325,60 @@ describe("GET /api/modules", () => {
     expect(body.supervisor_available).toBe(true);
   });
 
+  test("projects the supervisor's structured startError onto supervisor_start_error (§6.4/#188)", async () => {
+    // The Phase 3c `parachute status` supervisor arm reads this field to show
+    // the SAME friendly missing-dependency note the detached path persists. A
+    // fake supervisor whose list() returns a `crashed` state carrying a
+    // structured `startError` exercises the projection.
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.4.5",
+      },
+    ]);
+    const fakeSupervisor = {
+      list: () => [
+        {
+          short: "vault",
+          status: "crashed" as const,
+          restartsInWindow: 1,
+          startError: {
+            error_type: "missing_dependency",
+            error_description: "parachute-vault is required",
+            binary: "parachute-vault",
+            at: "2026-06-01T00:00:00Z",
+          },
+        },
+      ],
+    } as unknown as Supervisor;
+
+    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,
+      supervisor: fakeSupervisor,
+      fetchLatestVersion: async () => null,
+    });
+    const body = (await res.json()) as {
+      modules: Array<{
+        short: string;
+        supervisor_status: string | null;
+        supervisor_start_error: { binary?: string; error_type?: string } | null;
+      }>;
+    };
+    const vault = body.modules.find((m) => m.short === "vault");
+    expect(vault?.supervisor_status).toBe("crashed");
+    expect(vault?.supervisor_start_error?.binary).toBe("parachute-vault");
+    expect(vault?.supervisor_start_error?.error_type).toBe("missing_dependency");
+    // A module with no supervisor entry surfaces null (uniform wire shape).
+    const scribe = body.modules.find((m) => m.short === "scribe");
+    expect(scribe?.supervisor_start_error).toBeNull();
+  });
+
   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`)