@openparachute/hub 0.5.1 → 0.5.7

package/src/__tests__/install.test.ts

@@ -264,9 +264,11 @@ describe("install", () => {
 
   test("CLI overrides a non-canonical port written by init when canonical is free", async () => {
     // Pre-#53 the CLI deferred to whatever port the service's init wrote
-    // (e.g. 5173, Vite's dev default for notes). With CLI-as-port-authority
-    // the canonical slot wins when free: the manifest is updated and the
-    // .env carries PORT=<canonical> so the next daemon boot binds it.
+    // (e.g. 5173, Vite's dev default for notes). With hub-as-port-authority
+    // the canonical slot wins when free: services.json is updated to the
+    // canonical port (post-hub#206 the install path no longer touches .env;
+    // services.json is the single source of truth at boot per the 4-tier
+    // resolvePort ladder in scribe/agent).
     const { path, configDir, cleanup } = makeTempPath();
     try {
       const logs: string[] = [];
@@ -1047,11 +1049,14 @@ describe("install", () => {
     }
   });
 
-  // CLI-as-port-authority (#53). Install assigns the service's port up front
-  // and writes `PORT=<port>` into `<configDir>/<svc>/.env`. lifecycle.start
-  // merges that .env into spawn env, so the next daemon boot binds the port
-  // the CLI picked.
-  test("install writes PORT=<canonical> to .env when the slot is free", async () => {
+  // Hub-as-port-authority (#53), services.json-is-authoritative (#206).
+  // Install picks the service's port up front and reflects it in
+  // services.json. Pre-#206 it also wrote `PORT=<port>` into the service's
+  // `.env`; post-#206 it doesn't — services.json is the single source of
+  // truth at boot per the 4-tier resolvePort ladder in scribe#41 / agent#146
+  // / agent#148, so the duplicate `.env` PORT was at best dead weight and
+  // at worst a source of drift on re-install.
+  test("install reflects canonical port in services.json without writing PORT to .env (hub#206)", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {
       const code = await install("vault", {
@@ -1064,34 +1069,38 @@ describe("install", () => {
         log: () => {},
       });
       expect(code).toBe(0);
-      const envText = readFileSync(join(configDir, "vault", ".env"), "utf8");
-      expect(envText).toContain("PORT=1940");
+      // services.json is authoritative — that's where the port lives.
+      const entry = findService("parachute-vault", path);
+      expect(entry?.port).toBe(1940);
+      // .env should NOT have a PORT line. The directory may not even
+      // exist (nothing in this test path writes to the service's config
+      // dir); if it does, the file shouldn't carry PORT.
+      const envPath = join(configDir, "vault", ".env");
+      if (existsSync(envPath)) {
+        expect(readFileSync(envPath, "utf8")).not.toMatch(/^PORT=/m);
+      }
     } finally {
       cleanup();
     }
   });
 
-  test("install preserves a pre-existing PORT in .env across re-installs", async () => {
+  test("install does NOT preserve a pre-existing PORT in .env across re-installs (hub#206)", async () => {
+    // Pre-#206 a stale `.env` PORT survived a re-install: an operator
+    // who edited services.json to fix a duplicate would get re-stamped
+    // by the .env on the next `parachute install`. Post-#206 services.json
+    // is authoritative; the install path leaves `.env` alone but
+    // services.json reflects the freshly-assigned port. The stale `.env`
+    // PORT is harmless because the boot-time resolvePort ladder reads
+    // services.json before falling through to the bare PORT env tier.
     const { path, configDir, cleanup } = makeTempPath();
     try {
-      // First install assigns canonical 1940.
-      await install("vault", {
-        runner: async () => 0,
-        manifestPath: path,
-        configDir,
-        startService: async () => 0,
-        isLinked: () => false,
-        portProbe: async () => false,
-        log: () => {},
-      });
-      // Hand-edit .env to use a custom port (operator override).
       const envPath = join(configDir, "vault", ".env");
-      const original = readFileSync(envPath, "utf8");
-      const edited = original.replace("PORT=1940", "PORT=1947");
-      const { writeFileSync } = await import("node:fs");
-      writeFileSync(envPath, edited);
+      const { mkdirSync, writeFileSync } = await import("node:fs");
+      mkdirSync(join(configDir, "vault"), { recursive: true });
+      // Pre-existing .env with an operator-edited (now-stale) PORT.
+      const before = "PORT=1947\nOTHER=keepme\n";
+      writeFileSync(envPath, before);
 
-      // Second install must preserve the operator's choice, not stomp it.
       await install("vault", {
         runner: async () => 0,
         manifestPath: path,
@@ -1101,13 +1110,20 @@ describe("install", () => {
         portProbe: async () => false,
         log: () => {},
       });
-      expect(readFileSync(envPath, "utf8")).toContain("PORT=1947");
+
+      // services.json gets the freshly-assigned canonical port (1940),
+      // NOT the stale 1947 from .env.
+      const entry = findService("parachute-vault", path);
+      expect(entry?.port).toBe(1940);
+      // .env is bit-for-bit untouched: the stale PORT stays, OTHER stays,
+      // and we did NOT rewrite the file with a new PORT line.
+      expect(readFileSync(envPath, "utf8")).toBe(before);
     } finally {
       cleanup();
     }
   });
 
-  test("install falls back inside the canonical range when the slot is occupied", async () => {
+  test("install falls back inside the canonical range when the slot is occupied (hub#206 — no .env write)", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {
       // Pretend something else is on 1940.
@@ -1133,11 +1149,14 @@ describe("install", () => {
       });
       expect(code).toBe(0);
       // First reservation slot is 1944.
-      const envText = readFileSync(join(configDir, "vault", ".env"), "utf8");
-      expect(envText).toContain("PORT=1944");
       const entry = findService("parachute-vault", path);
       expect(entry?.port).toBe(1944);
       expect(logs.join("\n")).toMatch(/canonical port 1940 is in use/);
+      // .env is not touched.
+      const envPath = join(configDir, "vault", ".env");
+      if (existsSync(envPath)) {
+        expect(readFileSync(envPath, "utf8")).not.toMatch(/^PORT=/m);
+      }
     } finally {
       cleanup();
     }

package/src/__tests__/lifecycle.test.ts

@@ -248,7 +248,11 @@ describe("parachute start", () => {
         configDir: h.configDir,
         manifestPath: h.manifestPath,
         spawner,
-        alive: () => false,
+        // Stale 4242 is dead; the freshly spawned 7777 is alive — the
+        // post-spawn settle (hub#194) calls alive(pid) on the new pid,
+        // so we differentiate per-pid rather than blanket-false.
+        alive: (pid) => pid === 7777,
+        sleep: async () => {},
         log: () => {},
       });
       expect(code).toBe(0);
@@ -629,6 +633,94 @@ describe("parachute start", () => {
     }
   });
 
+  test("hub#194: reports failure when child dies before the settle window", async () => {
+    // The bug: `parachute start notes` reported `✓ notes started (pid X)`
+    // but notes-serve crashed milliseconds later on a Bun.resolveSync
+    // failure, leaving tailnet `/notes/` 502'ing. Fix: after spawn, sleep
+    // ~250ms then re-check alive(pid). If dead, clear pidfile, log
+    // failure, return non-zero. This regression test pins the post-fix
+    // shape with a stub alive that always reports dead and a fast settle.
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const lines: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => false, // child dies immediately after spawn
+        sleep: async () => {}, // skip the real wait in tests
+        startSettleMs: 1, // any non-zero value engages the check
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(spawner.calls).toHaveLength(1);
+      // pidfile is cleared so a follow-up `start` doesn't report
+      // already-running against a corpse.
+      expect(readPid("vault", h.configDir)).toBeUndefined();
+      const out = lines.join("\n");
+      expect(out).toMatch(/✗ vault failed to start/);
+      expect(out).toMatch(/exited within 1ms/);
+      expect(out).toMatch(/Tail the log/);
+      expect(out).not.toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#194: settle path passes when child stays alive past the window", async () => {
+    // Companion to the above — verifies the success-path shape doesn't
+    // regress. Stub alive returns true so the post-spawn check passes,
+    // and we still see the `✓ ... started` line.
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const lines: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => true,
+        sleep: async () => {},
+        startSettleMs: 1,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      expect(readPid("vault", h.configDir)).toBe(4242);
+      expect(lines.join("\n")).toMatch(/✓ vault started \(pid 4242\)/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#194: settle skipped when startSettleMs is 0", async () => {
+    // Defense — don't regress the test-default policy. With a stub
+    // spawner and no `alive` override, the resolved settle is 0 (see
+    // resolve() in lifecycle.ts), so the post-spawn check is bypassed
+    // entirely and even an `alive: () => false` doesn't matter.
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        startSettleMs: 0,
+        // intentionally omit alive — defaultAlive against a fake pid
+        // would normally report dead, but startSettleMs: 0 skips the
+        // call entirely.
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(readPid("vault", h.configDir)).toBe(4242);
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("third-party with no startCmd in module.json reports lifecycle-unsupported", async () => {
     const h = makeHarness();
     try {
@@ -802,7 +894,10 @@ describe("parachute restart", () => {
         manifestPath: h.manifestPath,
         spawner,
         kill: (pid, sig) => killed.push([pid, sig]),
-        alive: () => false,
+        // Stale 4242 is dead (stop's stale-pid path skips the kill);
+        // freshly spawned 7777 is alive past the post-spawn settle
+        // (hub#194). Per-pid differentiation rather than blanket-false.
+        alive: (pid) => pid === 7777,
         sleep: async () => {},
         log: () => {},
       });

package/src/__tests__/module-manifest.test.ts

@@ -130,6 +130,19 @@ describe("validateModuleManifest", () => {
     const m = validateModuleManifest(VALID, "x");
     expect(m.managementUrl).toBeUndefined();
   });
+
+  test("stripPrefix accepts boolean true and false; rejects non-boolean", () => {
+    expect(validateModuleManifest({ ...VALID, stripPrefix: true }, "x").stripPrefix).toBe(true);
+    expect(validateModuleManifest({ ...VALID, stripPrefix: false }, "x").stripPrefix).toBe(false);
+    expect(() => validateModuleManifest({ ...VALID, stripPrefix: "yes" }, "x")).toThrow(
+      /stripPrefix/,
+    );
+  });
+
+  test("stripPrefix absent stays absent", () => {
+    const m = validateModuleManifest(VALID, "x");
+    expect(m.stripPrefix).toBeUndefined();
+  });
 });
 
 describe("readModuleManifest", () => {

package/src/__tests__/notes-serve.test.ts

@@ -1,8 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { normalizeMount, notesFetch } from "../notes-serve.ts";
+import {
+  normalizeMount,
+  notesDistCandidates,
+  notesFetch,
+  resolveNotesDistFrom,
+} from "../notes-serve.ts";
 
 interface Harness {
   dir: string;
@@ -133,3 +138,150 @@ describe("notesFetch with empty mount (root deployment)", () => {
     }
   });
 });
+
+describe("notesDistCandidates", () => {
+  test("returns cwd, then global node_modules, then global root", () => {
+    const cands = notesDistCandidates("/some/cwd", "/home/user");
+    expect(cands).toEqual([
+      "/some/cwd",
+      "/home/user/.bun/install/global/node_modules",
+      "/home/user/.bun/install/global",
+    ]);
+  });
+});
+
+/**
+ * `resolveNotesDistFrom` is the hub#194 fix — when the cwd-relative resolve
+ * fails (hub repo dir doesn't depend on @openparachute/notes), we walk down
+ * to bun's global install dirs before giving up. Tests use a stub
+ * `resolveSync` so we can drive the candidate order without writing real
+ * fixtures into `~/.bun/install/global`.
+ */
+describe("resolveNotesDistFrom (hub#194)", () => {
+  function makeFixture(): { home: string; cleanup: () => void; pkgRoot: string; dist: string } {
+    // realpathSync — on macOS `mkdtempSync` returns a /var/folders path
+    // that resolves to /private/var/folders; we want the resolved form so
+    // string comparisons against `Bun.resolveSync` output line up.
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "pcli-notes-resolve-")));
+    const home = join(root, "home");
+    const pkgRoot = join(home, ".bun/install/global/node_modules/@openparachute/notes");
+    mkdirSync(pkgRoot, { recursive: true });
+    const dist = join(pkgRoot, "dist");
+    mkdirSync(dist, { recursive: true });
+    writeFileSync(join(pkgRoot, "package.json"), '{"name":"@openparachute/notes"}');
+    return { home, pkgRoot, dist, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+  }
+
+  test("first-candidate (cwd) hit returns its dist immediately", () => {
+    const f = makeFixture();
+    try {
+      const calls: string[] = [];
+      const out = resolveNotesDistFrom({
+        cwd: "/cwd-with-notes",
+        home: f.home,
+        resolveSync: (specifier, base) => {
+          calls.push(base);
+          if (base === "/cwd-with-notes") {
+            return "/cwd-with-notes/node_modules/@openparachute/notes/package.json";
+          }
+          throw new Error(`unexpected base: ${base}`);
+        },
+        existsSync: (p) => p === "/cwd-with-notes/node_modules/@openparachute/notes/dist",
+      });
+      expect(out).toBe("/cwd-with-notes/node_modules/@openparachute/notes/dist");
+      // Only the cwd candidate should be probed — we short-circuit on hit.
+      expect(calls).toEqual(["/cwd-with-notes"]);
+    } finally {
+      f.cleanup();
+    }
+  });
+
+  test("falls through to global node_modules when cwd resolve fails (hub#194 root cause)", () => {
+    // The exact scenario from hub#194: hub repo's cwd has no dependency on
+    // notes, so the first candidate throws ResolveMessage. Bun does NOT
+    // auto-consult ~/.bun/install/global, so we have to try it explicitly.
+    const f = makeFixture();
+    try {
+      const calls: string[] = [];
+      const out = resolveNotesDistFrom({
+        cwd: "/hub-repo-cwd-without-notes",
+        home: f.home,
+        resolveSync: (specifier, base) => {
+          calls.push(base);
+          if (base === "/hub-repo-cwd-without-notes") {
+            throw new Error(`Cannot find module '${specifier}' from '${base}'`);
+          }
+          // Real Bun.resolveSync against the global node_modules dir
+          // resolves into the package's package.json.
+          return Bun.resolveSync(specifier, base);
+        },
+        // Use real existsSync — the fixture has dist/ on disk.
+      });
+      expect(out).toBe(f.dist);
+      // Both candidates probed, in order.
+      expect(calls[0]).toBe("/hub-repo-cwd-without-notes");
+      expect(calls[1]).toBe(join(f.home, ".bun/install/global/node_modules"));
+    } finally {
+      f.cleanup();
+    }
+  });
+
+  test("falls through past global node_modules to the older global root layout", () => {
+    // Defensive: older Bun versions used a flatter global layout. We probe
+    // both. This test forces the first two candidates to fail and pins
+    // that the third is reached.
+    const probed: string[] = [];
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd",
+        home: "/h",
+        resolveSync: (_specifier, base) => {
+          probed.push(base);
+          throw new Error(`Cannot find module from '${base}'`);
+        },
+      }),
+    ).toThrow(/Could not resolve @openparachute\/notes from any of/);
+    expect(probed).toEqual([
+      "/cwd",
+      "/h/.bun/install/global/node_modules",
+      "/h/.bun/install/global",
+    ]);
+  });
+
+  test("error message names every candidate that was tried", () => {
+    let caught: unknown;
+    try {
+      resolveNotesDistFrom({
+        cwd: "/probe-cwd",
+        home: "/probe-home",
+        resolveSync: (_specifier, base) => {
+          throw new Error(`Cannot find module from '${base}'`);
+        },
+      });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    const msg = (caught as Error).message;
+    expect(msg).toContain("/probe-cwd");
+    expect(msg).toContain("/probe-home/.bun/install/global/node_modules");
+    expect(msg).toContain("/probe-home/.bun/install/global");
+    // Hint operators at the actionable next step.
+    expect(msg).toMatch(/bun add -g @openparachute\/notes|parachute install notes/);
+  });
+
+  test("resolved package without dist/ throws a hard error (no fallthrough)", () => {
+    // If the package resolves but lacks a dist/ directory, that's a
+    // packaging issue — falling through to other candidates would just
+    // re-resolve the same package. Surface the problem with the resolved
+    // path so the operator can file the right issue against the package.
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd-with-notes",
+        home: "/h",
+        resolveSync: () => "/cwd-with-notes/node_modules/@openparachute/notes/package.json",
+        existsSync: () => false,
+      }),
+    ).toThrow(/has no dist\/ directory/);
+  });
+});