@openparachute/hub 0.3.0-rc.1 → 0.5.1

package/src/__tests__/lifecycle.test.ts

@@ -1,8 +1,16 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { logs, restart, start, stop } from "../commands/lifecycle.ts";
+import {
+  defaultAlive,
+  defaultKill,
+  defaultSpawner,
+  logs,
+  restart,
+  start,
+  stop,
+} from "../commands/lifecycle.ts";
 import { writeHubPort } from "../hub-control.ts";
 import { ensureLogPath, logPath, readPid, writePid } from "../process-state.ts";
 import { upsertService } from "../services-manifest.ts";
@@ -48,12 +56,62 @@ function seedNotes(manifestPath: string): void {
   );
 }
 
+interface ThirdPartySeed {
+  installDir: string;
+  manifestName?: string;
+  startCmd?: readonly string[];
+  port?: number;
+}
+
+/**
+ * Seed a third-party services.json row + write a `.parachute/module.json` at
+ * `installDir`. Mirrors what `parachute install /tmp/foo` produces in
+ * production: row carries `installDir`, lifecycle resolves spec from the
+ * filesystem.
+ */
+function seedThirdParty(
+  manifestPath: string,
+  configDirRoot: string,
+  name: string,
+  opts: ThirdPartySeed,
+): string {
+  const installDir = opts.installDir;
+  mkdirSync(join(installDir, ".parachute"), { recursive: true });
+  const manifest = {
+    name,
+    manifestName: opts.manifestName ?? name,
+    kind: "api" as const,
+    port: opts.port ?? 1944,
+    paths: [`/${name}`],
+    health: `/${name}/health`,
+    ...(opts.startCmd ? { startCmd: opts.startCmd } : {}),
+  };
+  writeFileSync(join(installDir, ".parachute", "module.json"), JSON.stringify(manifest));
+  upsertService(
+    {
+      name: opts.manifestName ?? name,
+      port: opts.port ?? 1944,
+      paths: [`/${name}`],
+      health: `/${name}/health`,
+      version: "0.0.1",
+      installDir,
+    },
+    manifestPath,
+  );
+  return configDirRoot;
+}
+
 interface SpawnerStub {
-  spawn: (cmd: readonly string[], logFile: string, env?: Record<string, string>) => number;
+  spawn: (
+    cmd: readonly string[],
+    logFile: string,
+    opts?: { env?: Record<string, string>; cwd?: string },
+  ) => number;
   calls: Array<{
     cmd: readonly string[];
     logFile: string;
     env?: Record<string, string>;
+    cwd?: string;
   }>;
 }
 
@@ -62,12 +120,13 @@ function makeSpawner(pidSequence: number[]): SpawnerStub {
     cmd: readonly string[];
     logFile: string;
     env?: Record<string, string>;
+    cwd?: string;
   }> = [];
   let i = 0;
   return {
     calls,
-    spawn(cmd, logFile, env) {
-      calls.push({ cmd: [...cmd], logFile, env });
+    spawn(cmd, logFile, opts) {
+      calls.push({ cmd: [...cmd], logFile, env: opts?.env, cwd: opts?.cwd });
       return pidSequence[i++] ?? 99999;
     },
   };
@@ -428,6 +487,168 @@ describe("parachute start", () => {
       h.cleanup();
     }
   });
+
+  test("third-party module starts via installDir module.json with cwd", async () => {
+    // hub#83: services.json rows that carry installDir resolve their spec
+    // from `<installDir>/.parachute/module.json` at lifecycle time. Spawn
+    // gets cwd=installDir so manifest-declared relative paths work.
+    const h = makeHarness();
+    try {
+      const installDir = join(h.configDir, "_pkg-agent");
+      seedThirdParty(h.manifestPath, h.configDir, "agent", {
+        installDir,
+        startCmd: ["bun", "web/server/src/server.ts"],
+        port: 1944,
+      });
+      const spawner = makeSpawner([8080]);
+      const code = await start("agent", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(spawner.calls).toHaveLength(1);
+      expect(spawner.calls[0]?.cmd).toEqual(["bun", "web/server/src/server.ts"]);
+      expect(spawner.calls[0]?.cwd).toBe(installDir);
+      expect(readPid("agent", h.configDir)).toBe(8080);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start: installDir-less third-party row surfaces an actionable error", async () => {
+    // A services.json row whose name isn't first-party AND has no installDir
+    // can't yield a startCmd. Pre-fix this hit the generic "unknown service"
+    // path (misleading — the row exists, just with stale shape). Post-fix
+    // resolveTargets returns the entry with spec=undefined and start prints
+    // an actionable message that points at the real fix (re-install or
+    // upgrade-the-module).
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "mystery",
+          port: 1944,
+          paths: ["/mystery"],
+          health: "/mystery/health",
+          version: "0.0.1",
+        },
+        h.manifestPath,
+      );
+      const lines: string[] = [];
+      const code = await start("mystery", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      const out = lines.join("\n");
+      expect(out).toMatch(/services\.json entry has no installDir/);
+      expect(out).toMatch(/parachute install <path-to-mystery>/);
+      expect(out).not.toMatch(/unknown service/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start: name absent from services.json still errors as unknown service", async () => {
+    // The genuinely-unknown path: no first-party fallback, no row in
+    // services.json. Distinguish from the above (row exists but lacks
+    // installDir) so the error message is right-shaped for each.
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const lines: string[] = [];
+      const code = await start("ghost", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(lines.join("\n")).toMatch(/unknown service "ghost"/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start (no svc) sweeps both first-party and third-party rows", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const installDir = join(h.configDir, "_pkg-agent");
+      seedThirdParty(h.manifestPath, h.configDir, "agent", {
+        installDir,
+        startCmd: ["bun", "server.ts"],
+        port: 1944,
+      });
+      const spawner = makeSpawner([4242, 8080]);
+      const code = await start(undefined, {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(spawner.calls).toHaveLength(2);
+      const cmds = spawner.calls.map((c) => c.cmd);
+      expect(cmds).toContainEqual(["parachute-vault", "serve"]);
+      expect(cmds).toContainEqual(["bun", "server.ts"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("third-party with malformed module.json fails clearly", async () => {
+    const h = makeHarness();
+    try {
+      const installDir = join(h.configDir, "_pkg-broken");
+      mkdirSync(join(installDir, ".parachute"), { recursive: true });
+      writeFileSync(join(installDir, ".parachute", "module.json"), "{ not valid json");
+      upsertService(
+        {
+          name: "broken",
+          port: 1944,
+          paths: ["/broken"],
+          health: "/broken/health",
+          version: "0.0.1",
+          installDir,
+        },
+        h.manifestPath,
+      );
+      const lines: string[] = [];
+      const code = await start("broken", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(lines.join("\n")).toMatch(/broken: invalid module\.json/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("third-party with no startCmd in module.json reports lifecycle-unsupported", async () => {
+    const h = makeHarness();
+    try {
+      const installDir = join(h.configDir, "_pkg-noop");
+      seedThirdParty(h.manifestPath, h.configDir, "noop", {
+        installDir,
+        port: 1945,
+      });
+      const lines: string[] = [];
+      const code = await start("noop", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(lines.join("\n")).toMatch(/lifecycle not yet supported/);
+    } finally {
+      h.cleanup();
+    }
+  });
 });
 
 describe("parachute stop", () => {
@@ -527,6 +748,45 @@ describe("parachute stop", () => {
       h.cleanup();
     }
   });
+
+  test("third-party row without installDir: stops via pidfile", async () => {
+    // Graceful-degradation path: an installed-but-stale third-party row
+    // (no installDir field — pre-installDir-contract self-registration)
+    // should still be stoppable. stop only needs the short name to find
+    // the pidfile; spec resolution isn't on the critical path for stop.
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "mystery",
+          port: 1944,
+          paths: ["/mystery"],
+          health: "/mystery/health",
+          version: "0.0.1",
+        },
+        h.manifestPath,
+      );
+      writePid("mystery", 4242, h.configDir);
+      const killed: Array<[number, string | number]> = [];
+      let aliveCall = 0;
+      const code = await stop("mystery", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        kill: (pid, sig) => killed.push([pid, sig]),
+        alive: () => {
+          aliveCall++;
+          return aliveCall === 1;
+        },
+        sleep: async () => {},
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(killed).toEqual([[4242, "SIGTERM"]]);
+      expect(readPid("mystery", h.configDir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
 });
 
 describe("parachute restart", () => {
@@ -605,4 +865,355 @@ describe("parachute logs", () => {
       h.cleanup();
     }
   });
+
+  test("third-party module name with installDir is recognised", async () => {
+    const h = makeHarness();
+    try {
+      const installDir = join(h.configDir, "_pkg-agent");
+      seedThirdParty(h.manifestPath, h.configDir, "agent", {
+        installDir,
+        startCmd: ["bun", "server.ts"],
+      });
+      const p = ensureLogPath("agent", h.configDir);
+      writeFileSync(p, "agent line 1\nagent line 2\n");
+      const lines: string[] = [];
+      const code = await logs("agent", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      expect(lines).toEqual(["agent line 1", "agent line 2"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("third-party row without installDir: tails by short name", async () => {
+    // Graceful-degradation path: log file is keyed by short name, written by
+    // start. installDir is irrelevant for tailing — the entry just needs to
+    // exist in services.json.
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "mystery",
+          port: 1944,
+          paths: ["/mystery"],
+          health: "/mystery/health",
+          version: "0.0.1",
+        },
+        h.manifestPath,
+      );
+      const p = ensureLogPath("mystery", h.configDir);
+      writeFileSync(p, "mystery line 1\nmystery line 2\n");
+      const lines: string[] = [];
+      const code = await logs("mystery", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      expect(lines).toEqual(["mystery line 1", "mystery line 2"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("process-group lifecycle (hub#88)", () => {
+  // Spawn a wrapper that forks a long-running grandchild (sleep), wait for
+  // both to come up, then check that the wrapper PID equals its PGID — the
+  // post-fix invariant that makes group-kill safe. Without `detached: true`
+  // the child inherits the test runner's PGID and group-kill would target
+  // the wrong tree.
+  test("defaultSpawner puts child in its own process group", async () => {
+    const h = makeHarness();
+    try {
+      const logFile = ensureLogPath("test", h.configDir);
+      const pid = defaultSpawner.spawn(["sh", "-c", "sleep 2 & wait"], logFile);
+      try {
+        // Resolve the child's PGID via ps; the kernel reports it as a
+        // numeric column. PGID == PID means our setsid-equivalent worked.
+        const ps = Bun.spawnSync(["ps", "-o", "pgid=", "-p", String(pid)]);
+        const pgid = Number.parseInt(ps.stdout.toString().trim(), 10);
+        expect(pgid).toBe(pid);
+      } finally {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {}
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // The smoking-gun scenario from #88: a wrapper (sh) forks a grandchild
+  // (sleep) that keeps a resource — here, just stays alive. SIGKILL on the
+  // wrapper PID alone leaves the grandchild running. With detached spawn +
+  // group-kill, both go down. We assert by checking the grandchild's PID
+  // is no longer kill-able after `defaultKill`.
+  test("defaultKill takes down the wrapper and its grandchildren together", async () => {
+    const h = makeHarness();
+    try {
+      const logFile = ensureLogPath("test", h.configDir);
+      // Wrapper sh forks `sleep 30 & echo $!` so we capture the grandchild
+      // PID via the log file, then `wait` so the wrapper sticks around as
+      // a parent (mirrors `pnpm exec tsx`'s shape).
+      const wrapperPid = defaultSpawner.spawn(
+        ["sh", "-c", "sleep 30 & echo $! >&2; wait"],
+        logFile,
+      );
+      // Give the grandchild time to start and the log line to flush.
+      await new Promise((r) => setTimeout(r, 200));
+      const log = await Bun.file(logFile).text();
+      const grandchildPid = Number.parseInt(log.trim().split("\n").pop() ?? "", 10);
+      expect(grandchildPid).toBeGreaterThan(0);
+      expect(grandchildPid).not.toBe(wrapperPid);
+      // Both should be alive before kill.
+      expect(() => process.kill(grandchildPid, 0)).not.toThrow();
+
+      defaultKill(wrapperPid, "SIGKILL");
+
+      // Reap + wait for the grandchild to exit; on macOS the kernel may
+      // take a tick to deliver the signal.
+      await new Promise((r) => setTimeout(r, 200));
+      let grandchildStillAlive = true;
+      try {
+        process.kill(grandchildPid, 0);
+      } catch {
+        grandchildStillAlive = false;
+      }
+      expect(grandchildStillAlive).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // defaultAlive's post-fix semantics: returns true while any group member
+  // is alive (the wrapper stays in the group as long as it's running),
+  // false after the group drains.
+  test("defaultAlive reports group liveness for detached children", async () => {
+    const h = makeHarness();
+    try {
+      const logFile = ensureLogPath("test", h.configDir);
+      const pid = defaultSpawner.spawn(["sh", "-c", "sleep 2"], logFile);
+      try {
+        expect(defaultAlive(pid)).toBe(true);
+      } finally {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {}
+      }
+      // Wait for the kill to drain the group, then re-check.
+      await new Promise((r) => setTimeout(r, 100));
+      expect(defaultAlive(pid)).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // Legacy pidfile compatibility: a pre-detached pidfile holds a positive
+  // PID whose pgid is the parent shell, not the pid itself. defaultAlive
+  // must fall back to a bare-pid check so the next `stop` actually runs;
+  // defaultKill must fall back to a bare-pid signal so it can be reaped.
+  test("defaultAlive + defaultKill fall back to bare-pid for legacy (non-detached) processes", async () => {
+    // Spawn a non-detached child to simulate a legacy pidfile (pre-fix
+    // start). It shares the test runner's pgid, so kill(-pid, 0) will
+    // ESRCH and we should fall back.
+    const proc = Bun.spawn(["sh", "-c", "sleep 5"], { stdio: ["ignore", "ignore", "ignore"] });
+    const pid = proc.pid;
+    try {
+      expect(defaultAlive(pid)).toBe(true);
+      defaultKill(pid, "SIGKILL");
+      await new Promise((r) => setTimeout(r, 100));
+      expect(defaultAlive(pid)).toBe(false);
+    } finally {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {}
+    }
+  });
+});
+
+/**
+ * `parachute start|stop|restart hub` — the bug Aaron filed as hub#166. Hub
+ * isn't a row in services.json, so the generic services-manifest path
+ * surfaced "unknown service: hub". The fix dispatches `svc === "hub"`
+ * straight to hub-control.ts. These tests inject `ensureRunning`/`stop`
+ * stubs so we don't actually fork bun.
+ */
+describe("parachute start|stop|restart hub", () => {
+  test("start hub: dispatches to ensureHubRunning, propagates configDir + issuer", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const ensureCalls: Array<{ configDir?: string; issuer?: string }> = [];
+      const code = await start("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hubOrigin: "https://hub.example.com",
+        hub: {
+          ensureRunning: async (opts) => {
+            ensureCalls.push({ configDir: opts.configDir, issuer: opts.issuer });
+            return { pid: 4711, port: 1939, started: true };
+          },
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(ensureCalls).toHaveLength(1);
+      expect(ensureCalls[0]).toEqual({
+        configDir: h.configDir,
+        issuer: "https://hub.example.com",
+      });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start hub: reports already-running cleanly when ensureHubRunning returns started=false", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const code = await start("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hub: {
+          ensureRunning: async () => ({ pid: 8888, port: 1939, started: false }),
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(log.join("\n")).toMatch(/hub already running \(pid 8888\) on port 1939/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start hub: surfaces ensureHubRunning errors as exit 1", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const code = await start("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hub: {
+          ensureRunning: async () => {
+            throw new Error("hub: port 1939 unavailable");
+          },
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(1);
+      expect(log.join("\n")).toMatch(/hub failed to start.*port 1939 unavailable/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("stop hub: dispatches to stopHub, true → '✓ hub stopped'", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const stopCalls: Array<{ configDir?: string }> = [];
+      const code = await stop("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hub: {
+          stop: async (opts) => {
+            stopCalls.push({ configDir: opts.configDir });
+            return true;
+          },
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(stopCalls).toHaveLength(1);
+      expect(stopCalls[0]?.configDir).toBe(h.configDir);
+      expect(log.join("\n")).toMatch(/✓ hub stopped/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("stop hub: false → 'wasn't running' (still exit 0)", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const code = await stop("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hub: { stop: async () => false },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(log.join("\n")).toMatch(/hub wasn't running/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("restart hub: chains stop then start through the same hub seam", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const order: string[] = [];
+      const code = await restart("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hub: {
+          stop: async () => {
+            order.push("stop");
+            return true;
+          },
+          ensureRunning: async () => {
+            order.push("start");
+            return { pid: 5151, port: 1939, started: true };
+          },
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(order).toEqual(["stop", "start"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("logs hub: doesn't reject 'hub' as an unknown service", async () => {
+    const h = makeHarness();
+    try {
+      // No log file yet — exercise the "no logs yet" branch, which still
+      // returns 0. Goal of this test is just the unknown-service guard.
+      const log: string[] = [];
+      const code = await logs("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(log.join("\n")).toMatch(/no logs yet for hub/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("logs hub: prints the tail when a log file exists", async () => {
+    const h = makeHarness();
+    try {
+      const path = ensureLogPath("hub", h.configDir);
+      writeFileSync(path, "hub line one\nhub line two\n");
+      const log: string[] = [];
+      const code = await logs("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(log).toEqual(["hub line one", "hub line two"]);
+    } finally {
+      h.cleanup();
+    }
+  });
 });