@openparachute/hub 0.6.2 → 0.6.3-rc.1

package/src/api-modules-ops.ts

@@ -39,6 +39,7 @@ import { MissingDependencyError, type MissingDependencyWire } from "@openparachu
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import { isLinked as defaultIsLinked } from "./bun-link.ts";
 import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
+import { buildModuleSpawnRequest } from "./commands/serve-boot.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
 import { readModuleManifest } from "./module-manifest.ts";
@@ -456,6 +457,11 @@ async function spawnSupervised(
   // anchors the child's iss expectation to the same value hub mints with.
   //
   // `deps.spawnEnv` still wins (test seam + first-boot vault-name pass-through).
+  //
+  // No per-service `.env` here, by design: the install path runs before the
+  // operator has had a chance to write `configDir/<short>/.env`, so install
+  // spawns with install-env only. The per-service `.env` is layered in by
+  // `buildModuleSpawnRequest` (serve-boot.ts) on the next `boot` or `start`.
   const childEnv: Record<string, string> = {
     PORT: String(entry.port),
     ...(deps.issuer ? { PARACHUTE_HUB_ORIGIN: deps.issuer } : {}),
@@ -713,6 +719,115 @@ export async function runInstall(
   registry.update(opId, { status: "succeeded" }, `${short} installed + spawned (pid ${state.pid})`);
 }
 
+/**
+ * POST /api/modules/:short/start — synchronous.
+ *
+ * A pure `supervisor.start(req)` of an ALREADY-INSTALLED module, using
+ * the same boot-derived SpawnRequest `bootSupervisedModules` builds
+ * (PORT / per-service .env / PARACHUTE_HUB_ORIGIN injection via the
+ * shared `buildModuleSpawnRequest`). This is the §3.3 endpoint Phase 3
+ * will repoint `parachute start <svc>` onto.
+ *
+ * Explicitly NOT an install: it does not run `bun add -g`, seed
+ * services.json, stamp installDir, or refresh well-known. If the module
+ * isn't in services.json (never installed) it returns 400 `not_installed`
+ * with an actionable hint — not a silent install. If services.json
+ * carries the row but no startCmd is resolvable (CLI-only module,
+ * unreadable module.json), it returns 422 `no_start_cmd`.
+ *
+ * Synchronous like restart: `supervisor.start` returns the new state in
+ * the body; no operation poll needed. Idempotent — starting an
+ * already-running module returns its existing state (the supervisor's
+ * own idempotent `start`).
+ */
+export async function handleStart(
+  req: Request,
+  short: CuratedModuleShort,
+  deps: ApiModulesOpsDeps,
+): Promise<Response> {
+  if (req.method !== "POST") return jsonError(405, "method_not_allowed", "use POST");
+  const authFail = await authorize(req, deps);
+  if (authFail) return authFail;
+
+  const spec = specFor(short);
+
+  // Pure-spawn precondition: the module must already be installed
+  // (present in services.json). `start` never installs — that's the
+  // install endpoint's job, which is far heavier (bun add -g / seed /
+  // stamp). A missing row is an operator error worth a clear message.
+  const entry = findService(spec.manifestName, deps.manifestPath);
+  if (!entry) {
+    return jsonError(
+      400,
+      "not_installed",
+      `${short} is not installed (no services.json entry) — install it first via POST /api/modules/${short}/install`,
+    );
+  }
+
+  // KNOWN_MODULES shorts (vault / scribe / runner): module.json is the
+  // canonical source for startCmd. Re-resolve from
+  // `<installDir>/.parachute/module.json` when installDir is stamped so the
+  // module is authoritative for its own spawn cmd — mirroring runInstall's
+  // post-bun-add re-resolve. Falls back to the imperative `extras.startCmd`
+  // carried by `spec` when installDir is absent or module.json is unreadable.
+  let spawnSpec: ServiceSpec = spec;
+  if (entry.installDir && KNOWN_MODULES[short]) {
+    const resolved = await resolveSpawnSpec(short, entry.installDir);
+    if (resolved) spawnSpec = resolved;
+  }
+
+  const cmd = spawnSpec.startCmd?.(entry);
+  if (!cmd || cmd.length === 0) {
+    return jsonError(
+      422,
+      "no_start_cmd",
+      `${short} has no resolvable startCmd (CLI-only module, or <installDir>/.parachute/module.json missing a startCmd)`,
+    );
+  }
+
+  // Build the SpawnRequest identically to the serve-boot path so `start`
+  // and boot produce the same child env (PORT / .env / HUB_ORIGIN). The
+  // test-seam / first-boot `spawnEnv` rides the shared helper's `extraEnv`
+  // and wins last, matching `spawnSupervised`'s precedence.
+  const spawnReq = buildModuleSpawnRequest(short, entry, cmd, {
+    configDir: deps.configDir,
+    ...(deps.issuer ? { hubOrigin: deps.issuer } : {}),
+    ...(deps.spawnEnv ? { extraEnv: deps.spawnEnv } : {}),
+  });
+
+  const state = await deps.supervisor.start(spawnReq);
+  return jsonOk({ short, state });
+}
+
+/**
+ * POST /api/modules/:short/stop — synchronous.
+ *
+ * A pure `supervisor.stop(short)` — SIGTERM the child, await exit (with
+ * SIGKILL escalation), mark `stopped`. Distinct from uninstall, which
+ * stops-then-removes the services.json row + `bun remove`s the package.
+ * `stop` leaves the module installed; it's the §3.3 endpoint Phase 3
+ * will repoint `parachute stop <svc>` onto.
+ *
+ * Idempotent: stopping a not-supervised module returns 200 with a
+ * `stopped: false` flag (nothing to stop) rather than erroring — the
+ * caller's intent ("ensure it's not running") is already satisfied.
+ */
+export async function handleStop(
+  req: Request,
+  short: CuratedModuleShort,
+  deps: ApiModulesOpsDeps,
+): Promise<Response> {
+  if (req.method !== "POST") return jsonError(405, "method_not_allowed", "use POST");
+  const authFail = await authorize(req, deps);
+  if (authFail) return authFail;
+
+  const state = await deps.supervisor.stop(short);
+  if (!state) {
+    return jsonOk({ short, stopped: false });
+  }
+  return jsonOk({ short, stopped: true, state });
+}
+
 /**
  * POST /api/modules/:short/restart — synchronous.
  *
@@ -741,6 +856,112 @@ export async function handleRestart(
   return jsonOk({ short, state });
 }
 
+/**
+ * GET /api/modules/:short/logs — synchronous.
+ *
+ * Serves the supervisor's bounded per-module ring buffer (§6.5): the most
+ * recent output the child wrote, INCLUDING the boot/crash lines that happened
+ * before the caller connected — which a naive connect-time SSE tap would lose
+ * (and which are "likely the most important one — the exit cause"). This is
+ * the §6 endpoint Phase 3 will repoint `parachute logs <svc>` onto.
+ *
+ * Returns the buffer as both a joined `text` blob and a `lines` array (the CLI
+ * tail wants the blob; a structured consumer wants lines). A module that isn't
+ * supervised returns 404 `not_supervised`, matching the `restart` handler's
+ * error contract for the same state — the caller can fall through to `start`.
+ *
+ * `?follow=1` is accepted as a best-effort streaming tap: we replay the buffer
+ * first (the must-have), then stream subsequent lines as `text/plain` chunks.
+ * The buffer replay is what captures the crash cause; the follow tail is the
+ * nice-to-have. Without `follow`, it's a one-shot JSON snapshot.
+ */
+export async function handleLogs(
+  req: Request,
+  short: CuratedModuleShort,
+  deps: ApiModulesOpsDeps,
+): Promise<Response> {
+  if (req.method !== "GET") return jsonError(405, "method_not_allowed", "use GET");
+  const authFail = await authorize(req, deps);
+  if (authFail) return authFail;
+
+  const lines = deps.supervisor.logs(short);
+  if (lines === undefined) {
+    // Same shape + status as `restart` for a not-supervised module, so the
+    // CLI client can treat both identically (fall through to `start`).
+    return jsonError(
+      404,
+      "not_supervised",
+      `${short} is not currently supervised — install or start it first`,
+    );
+  }
+
+  const follow = new URL(req.url).searchParams.get("follow");
+  if (follow === "1" || follow === "true") {
+    return streamModuleLogs(short, lines, deps);
+  }
+
+  // One-shot snapshot: the buffered lines as both a joined blob + the array.
+  return jsonOk({ short, lines, text: lines.join("") });
+}
+
+/**
+ * Best-effort follow stream (§6.5 nice-to-have). Replays the buffered lines
+ * (the must-have — captures the boot/crash cause) then forwards subsequent
+ * output as `text/plain` chunks by subscribing to a tee of the supervisor's
+ * live tap. The buffer replay is guaranteed; the live tail is opportunistic
+ * (it ends when the client disconnects or the module stops). Implemented via
+ * a polling diff of the ring buffer so it stays decoupled from `pumpLines`'
+ * internal sink and needs no new supervisor wiring.
+ */
+function streamModuleLogs(
+  short: CuratedModuleShort,
+  initial: string[],
+  deps: ApiModulesOpsDeps,
+): Response {
+  const encoder = new TextEncoder();
+  let lastLen = initial.length;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // Replay the buffered lines first — the boot/crash cause.
+      for (const line of initial) controller.enqueue(encoder.encode(line));
+      timer = setInterval(() => {
+        const current = deps.supervisor.logs(short);
+        if (current === undefined) {
+          // Module went away (uninstalled / never-supervised) — end the stream.
+          if (timer) clearInterval(timer);
+          try {
+            controller.close();
+          } catch {
+            // already closed
+          }
+          return;
+        }
+        // The ring buffer may have dropped old lines off the front; only
+        // forward genuinely-new tail lines. If the buffer shrank below our
+        // cursor (eviction), reset to its current length to avoid replaying.
+        // Limitation: new lines written during a heavy eviction burst (a chatty
+        // module overflowing the 64KiB cap between two polls) may be skipped in
+        // the live tail — use the one-shot snapshot (no ?follow) for crash investigation.
+        if (current.length < lastLen) lastLen = current.length;
+        for (let i = lastLen; i < current.length; i++) {
+          const line = current[i];
+          if (line !== undefined) controller.enqueue(encoder.encode(line));
+        }
+        lastLen = current.length;
+      }, 500);
+    },
+    cancel() {
+      // Stop polling when the consumer disconnects.
+      if (timer) clearInterval(timer);
+    },
+  });
+  return new Response(stream, {
+    status: 200,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+  });
+}
+
 /**
  * POST /api/modules/:short/upgrade — async.
  *

package/src/api-modules.ts

@@ -42,8 +42,13 @@ import { FIRST_PARTY_FALLBACKS, KNOWN_MODULES } from "./service-spec.ts";
 // still required) and the latter for vault/scribe/runner (post-FALLBACK
 // retirement, hub#310). The local helper hides the split from the rest of
 // this file.
-import { type UiSubUnit, type UiSubUnitStatus, readManifest, readManifestLenient } from "./services-manifest.ts";
-import type { ModuleState, Supervisor } from "./supervisor.ts";
+import {
+  type UiSubUnit,
+  type UiSubUnitStatus,
+  readManifest,
+  readManifestLenient,
+} from "./services-manifest.ts";
+import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts";
 
 /**
  * Resolve a curated module to the display + install bootstrap data the
@@ -174,6 +179,16 @@ interface ModuleWireShape {
   latest_version: string | null;
   supervisor_status: ModuleState["status"] | null;
   pid: number | null;
+  /**
+   * Structured supervisor start-failure detail (§6.5 / §6.4), when the
+   * supervisor recorded one for this module — a preflight `MissingDependencyError`
+   * or the alive-but-never-bound shape (hub#487). Mirrors the services.json
+   * `lastStartError` the detached path persists, so `parachute status` and the
+   * SPA keep the SAME friendly missing-dependency surface (#188) whether a
+   * module was started via the supervisor or the detached path. Null when the
+   * module started cleanly (or the hub is in pidfile/CLI mode with no supervisor).
+   */
+  supervisor_start_error: ModuleStartError | null;
   /**
    * The path on disk where the module is installed, if known. Surfaces
    * the BUN_INSTALL or bun-link install location for operator debug —
@@ -477,6 +492,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       latest_version: latestByShort.get(short) ?? null,
       supervisor_status: state?.status ?? null,
       pid: state?.pid ?? null,
+      supervisor_start_error: state?.startError ?? null,
       install_dir: installed?.installDir ?? null,
       uis: toUisWireShape(installed?.uis),
       management_url: managementUrlByShort.get(short) ?? null,

package/src/cli.ts

@@ -454,7 +454,11 @@ async function main(argv: string[]): Promise<number> {
         console.log(statusHelp());
         return 0;
       }
-      return await status();
+      // Pass an empty `supervisor` block so `status` takes the Phase 3c
+      // dual-dispatch: on a box with a hub unit installed it reads the platform
+      // manager + the running supervisor; on a legacy detached box it falls back
+      // to the pidfile readout (design §6.4). Tests drive the seams directly.
+      return await status({ supervisor: {} });
 
     case "expose": {
       const hubExtract = extractHubOrigin(rest);
@@ -624,7 +628,13 @@ async function main(argv: string[]): Promise<number> {
         console.error(`parachute start: ${hubExtract.error}`);
         return 1;
       }
-      const startOpts = hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {};
+      // `supervisor: {}` opts into the Phase 3b dual-dispatch: on a box with a
+      // hub unit installed, drive the running supervisor; on a legacy detached
+      // box (no unit), fall through to the unchanged detached path (design §3.3).
+      const startOpts = {
+        supervisor: {},
+        ...(hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {}),
+      };
       return await start(hubExtract.rest[0], startOpts);
     }
 
@@ -633,7 +643,7 @@ async function main(argv: string[]): Promise<number> {
         console.log(stopHelp());
         return 0;
       }
-      return await stop(rest[0]);
+      return await stop(rest[0], { supervisor: {} });
     }
 
     case "restart": {
@@ -641,7 +651,7 @@ async function main(argv: string[]): Promise<number> {
         console.log(restartHelp());
         return 0;
       }
-      return await restart(rest[0]);
+      return await restart(rest[0], { supervisor: {} });
     }
 
     case "upgrade": {