@openparachute/hub 0.7.7-rc.8 → 0.7.7-rc.9

package/package.json

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

package/src/__tests__/install.test.ts

@@ -1,8 +1,14 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { defaultStartLifecycleOpts, install } from "../commands/install.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  PARACHUTE_HUB_ROOT_REDIRECT_ENV,
+  getRootRedirect,
+  setRootRedirect,
+} from "../hub-settings.ts";
 import { findService, upsertService } from "../services-manifest.ts";
 
 function makeTempPath(): { path: string; configDir: string; cleanup: () => void } {
@@ -408,7 +414,7 @@ describe("install", () => {
   test("ADOPT-KILLS an attributable same-module orphan on the canonical port + reclaims it (#609)", async () => {
     // Wipe-recovery: `rm -rf ~/.parachute` + re-`init` leaves the supervised
     // vault child running on :1940. The fresh install must reclaim the canonical
-    // port (adopt-kill the attributable orphan) rather than port-walk to 1944.
+    // port (adopt-kill the attributable orphan) rather than port-walk to 1945.
     const { path, configDir, cleanup } = makeTempPath();
     try {
       const logs: string[] = [];
@@ -1636,9 +1642,10 @@ describe("install", () => {
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
-      // First reservation slot is 1944.
+      // First reservation slot is now 1945 — 1944 is parachute-app's
+      // canonical (assigned, non-walkable) slot as of hub-parity P5.
       const entry = findService("parachute-vault", path);
-      expect(entry?.port).toBe(1944);
+      expect(entry?.port).toBe(1945);
       expect(logs.join("\n")).toMatch(/canonical port 1940 is in use/);
       // .env is not touched.
       const envPath = join(configDir, "vault", ".env");
@@ -1940,7 +1947,8 @@ describe("install", () => {
       expect(startCalls).toEqual(["someapp"]);
       // Log lines speak in the canonical short name too. Port comes from
       // assignServicePort (third-party gets the first unassigned canonical
-      // slot, currently 1944), not the manifest's port hint.
+      // slot, currently 1945 — 1944 is parachute-app's canonical assigned
+      // slot as of hub-parity P5), not the manifest's port hint.
       const joined = logs.join("\n");
       expect(joined).toMatch(/Seeded services\.json entry for someapp/);
       expect(joined).toMatch(/someapp registered on port \d+/);
@@ -2316,3 +2324,177 @@ describe("hub#573 — install auto-start converges on supervised detection", ()
     expect(opts.log).toBe(log);
   });
 });
+
+// hub-parity P5 (2026-07-11): `parachute install app` defaults the hub's
+// bare `/` redirect to the app's front door — SET-IF-UNSET ONLY. Every test
+// here injects `rootRedirectDb` (a hub.db opened in the same disposable
+// tempdir `makeTempPath()` already isolates) so no real
+// `~/.parachute/hub.db` is ever touched — never drive this against the
+// operator's live install.
+describe("app-only root-redirect set-if-unset (hub-parity P5)", () => {
+  // The write gates on `resolveRootRedirectDetailed(db).source === "default"`,
+  // which consults `PARACHUTE_HUB_ROOT_REDIRECT`. Neutralize any ambient value
+  // (Aaron's box, CI) so the default-tier tests are deterministic; the
+  // env-set test below manages its own value inside its own body.
+  let savedEnv: string | undefined;
+  beforeEach(() => {
+    savedEnv = process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+  });
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    } else {
+      process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = savedEnv;
+    }
+  });
+
+  test("fresh install (no prior root_redirect) sets it to /app/", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        expect(getRootRedirect(db)).toBe("/app/");
+        expect(logs.join("\n")).toMatch(/front page.*now opens the app at \/app\//);
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a pre-set root_redirect is left alone — never clobbered", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        setRootRedirect(db, "/surface/reading-room");
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        // The operator's prior choice survives byte-for-byte.
+        expect(getRootRedirect(db)).toBe("/surface/reading-room");
+        // The set-if-unset write's OWN log line (distinct from the static
+        // postInstallFooter boilerplate, which always prints "now opens the
+        // app too, unless you've already..." regardless of whether the write
+        // fired) must NOT appear — the write itself was skipped.
+        expect(logs.join("\n")).not.toMatch(/now opens the app at \/app\//);
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("installing a different module never touches root_redirect", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      try {
+        const code = await install("notes", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: () => {},
+        });
+        expect(code).toBe(0);
+        expect(getRootRedirect(db)).toBeNull();
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("an ENV-configured redirect (no DB row) is left alone — never clobbered (N1)", async () => {
+    // Container deploys pin the landing page via PARACHUTE_HUB_ROOT_REDIRECT,
+    // not a DB row. Gating on `getRootRedirect(db) === null` (DB only) would
+    // miss this and write `/app/`, which — since the DB row wins over env on
+    // read — silently overrides their configured landing. The fix gates on
+    // `resolveRootRedirectDetailed(db).source === "default"`, which sees the
+    // env tier. So: env set → no DB row written.
+    const { path, configDir, cleanup } = makeTempPath();
+    const prevEnv = process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    try {
+      process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = "/surface/team-room";
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        // No DB row written — the env-configured landing survives.
+        expect(getRootRedirect(db)).toBeNull();
+        expect(logs.join("\n")).not.toMatch(/now opens the app at \/app\//);
+      } finally {
+        db.close();
+      }
+    } finally {
+      if (prevEnv === undefined) {
+        delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+      } else {
+        process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = prevEnv;
+      }
+      cleanup();
+    }
+  });
+
+  test("production gate: without rootRedirectDb + a tempdir manifestPath, the write is skipped (not attempted)", async () => {
+    // Mirrors the existing `guidanceProbeAllowed` discriminant elsewhere in
+    // install.ts: a test with a tempdir manifestPath and no explicit opt-in
+    // must never open the real ~/.parachute/hub.db. There's nothing to open
+    // here at all — the assertion is simply that install still completes
+    // cleanly with the DB-touching branch skipped.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const code = await install("app", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+});

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

@@ -149,6 +149,124 @@ describe("notesFetch with empty mount (root deployment)", () => {
   });
 });
 
+describe("notesFetch /health (2026-07-11, hub-parity P5)", () => {
+  test("GET /notes/health answers 2xx explicitly, not the SPA shell", async () => {
+    const h = makeHarness();
+    try {
+      const res = notesFetch(h.dir, "/notes")(req("/notes/health"));
+      expect(res.status).toBe(200);
+      // Explicit JSON, not the index.html SPA-shell fallback — proves the
+      // health path is a real handler, not an accident of the catch-all.
+      expect(res.headers.get("content-type")).toBe("application/json");
+      expect(await res.text()).not.toContain("notes spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /health answers 2xx at the mount root too (empty mount)", async () => {
+    const h = makeHarness();
+    try {
+      const res = notesFetch(h.dir, "")(req("/health"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/json");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("survives a missing dist/index.html — health doesn't depend on the SPA shell existing", async () => {
+    // A harness with NO index.html written — the SPA-shell fallback would
+    // throw/404 on this dist, but /health is answered before that code path
+    // is ever reached.
+    const dir = mkdtempSync(join(tmpdir(), "pcli-notes-serve-empty-"));
+    try {
+      const res = notesFetch(dir, "/app")(req("/app/health"));
+      expect(res.status).toBe(200);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// hub-parity P5 (2026-07-11): the shim generalized beyond notes to serve
+// @openparachute/parachute-app (mount `/app`, port 1944) via the same
+// FIRST_PARTY_FALLBACKS startCmd shape (`--package @openparachute/parachute-app`).
+// These tests re-run the load-bearing PWA regression (sw.js / manifest
+// content-type, SPA fallback, mount-strip) for a NON-notes package/mount to
+// prove the generalization didn't accidentally hardcode "notes" anywhere in
+// the serving path (only `resolveNotesDistFrom`'s package resolution is
+// notes-specific, and that's parameterized separately below).
+describe("notesFetch generalized for a non-notes package (hub-parity P5 — the app mount)", () => {
+  function makeAppHarness(): Harness {
+    const dir = mkdtempSync(join(tmpdir(), "pcli-app-serve-"));
+    writeFileSync(join(dir, "index.html"), "<html><body>app spa</body></html>");
+    writeFileSync(join(dir, "sw.js"), "self.addEventListener('install', () => {});");
+    writeFileSync(join(dir, "manifest.webmanifest"), '{"name":"Parachute","start_url":"/app/"}');
+    return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+  }
+
+  test("GET /app/sw.js serves the SW with JS content-type, not text/html", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/sw.js"));
+      expect(res.status).toBe(200);
+      const ct = res.headers.get("content-type") ?? "";
+      expect(ct).not.toContain("text/html");
+      expect(ct).toMatch(/javascript/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /app/manifest.webmanifest serves application/manifest+json", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/manifest.webmanifest"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/manifest+json");
+      expect(await res.text()).toContain('"name":"Parachute"');
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /app/ serves the SPA shell", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      expect(await res.text()).toContain("app spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /app/some/deep/route falls back to the SPA shell (client-side routing)", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/some/deep/route"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      expect(await res.text()).toContain("app spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /appendix/foo (mount-prefix collision) is not stripped", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/appendix/foo"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("notesDistCandidates", () => {
   test("returns cwd, then global node_modules, then global root", () => {
     const cands = notesDistCandidates("/some/cwd", "/home/user");
@@ -295,3 +413,101 @@ describe("resolveNotesDistFrom (hub#194)", () => {
     ).toThrow(/has no dist\/ directory/);
   });
 });
+
+/**
+ * `--package` generalization (hub-parity P5, 2026-07-11). `resolveNotesDistFrom`
+ * defaults `pkg` to `@openparachute/notes` (every test above omits it and
+ * still resolves notes — back-compat), but a caller like the `app`
+ * FIRST_PARTY_FALLBACKS entry passes a different package name. These tests
+ * pin the resolver against a real on-disk fixture for a NON-notes package,
+ * proving the specifier passed to `Bun.resolveSync` (and every error message)
+ * is the caller's `pkg`, not a hardcoded "notes" string.
+ */
+describe("resolveNotesDistFrom --package (hub-parity P5)", () => {
+  const APP_PKG = "@openparachute/parachute-app";
+
+  function makeAppFixture(): { home: string; cleanup: () => void; dist: string } {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "pcli-app-resolve-")));
+    const home = join(root, "home");
+    const pkgRoot = join(home, ".bun/install/global/node_modules", APP_PKG);
+    mkdirSync(pkgRoot, { recursive: true });
+    const dist = join(pkgRoot, "dist");
+    mkdirSync(dist, { recursive: true });
+    writeFileSync(join(pkgRoot, "package.json"), JSON.stringify({ name: APP_PKG }));
+    return { home, dist, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+  }
+
+  test("resolves a non-notes package's dist/ via the global node_modules fallback", () => {
+    const f = makeAppFixture();
+    try {
+      const out = resolveNotesDistFrom({
+        cwd: "/hub-repo-cwd-without-app",
+        home: f.home,
+        pkg: APP_PKG,
+        resolveSync: (specifier, base) => {
+          if (base === "/hub-repo-cwd-without-app") {
+            throw new Error(`Cannot find module '${specifier}' from '${base}'`);
+          }
+          return Bun.resolveSync(specifier, base);
+        },
+      });
+      expect(out).toBe(f.dist);
+    } finally {
+      f.cleanup();
+    }
+  });
+
+  test("default pkg (no --package) still resolves @openparachute/notes — back-compat", () => {
+    // Every earlier describe block already exercises this implicitly (none
+    // pass `pkg`); this test pins it explicitly against the specifier the
+    // resolver hands to `resolveSync`.
+    const specifiers: string[] = [];
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd",
+        home: "/h",
+        resolveSync: (specifier) => {
+          specifiers.push(specifier);
+          throw new Error("not found");
+        },
+      }),
+    ).toThrow();
+    expect(specifiers).toEqual([
+      "@openparachute/notes/package.json",
+      "@openparachute/notes/package.json",
+      "@openparachute/notes/package.json",
+    ]);
+  });
+
+  test("error message names the caller's package, not a hardcoded 'notes'", () => {
+    let caught: unknown;
+    try {
+      resolveNotesDistFrom({
+        cwd: "/probe-cwd",
+        home: "/probe-home",
+        pkg: APP_PKG,
+        resolveSync: () => {
+          throw new Error("nope");
+        },
+      });
+    } catch (err) {
+      caught = err;
+    }
+    const msg = (caught as Error).message;
+    expect(msg).toContain(`Could not resolve ${APP_PKG}`);
+    expect(msg).toContain(`bun add -g ${APP_PKG}`);
+    expect(msg).not.toContain("@openparachute/notes");
+  });
+
+  test("no-dist/ hard error names the caller's package", () => {
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd-with-app",
+        home: "/h",
+        pkg: APP_PKG,
+        resolveSync: () => "/cwd-with-app/node_modules/@openparachute/parachute-app/package.json",
+        existsSync: () => false,
+      }),
+    ).toThrow(new RegExp(`${APP_PKG.replace("/", "\\/")} resolved at .* has no dist/ directory`));
+  });
+});

package/src/__tests__/port-assign.test.ts

@@ -3,7 +3,26 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "no
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { assignPort, assignServicePort } from "../port-assign.ts";
-import { CANONICAL_PORT_MAX, CANONICAL_PORT_MIN } from "../service-spec.ts";
+import { CANONICAL_PORT_MAX, CANONICAL_PORT_MIN, PORT_RESERVATIONS } from "../service-spec.ts";
+
+describe("PORT_RESERVATIONS (registry shape)", () => {
+  test("every port in the canonical range appears exactly once", () => {
+    const ports = PORT_RESERVATIONS.map((r) => r.port);
+    expect(new Set(ports).size).toBe(ports.length);
+    expect(ports.slice().sort((a, b) => a - b)).toEqual(ports);
+    for (const p of ports) {
+      expect(p).toBeGreaterThanOrEqual(CANONICAL_PORT_MIN);
+      expect(p).toBeLessThanOrEqual(CANONICAL_PORT_MAX);
+    }
+  });
+
+  test("1944 (parachute-app, hub-parity P5) doesn't collide with any other reservation", () => {
+    const owners = PORT_RESERVATIONS.filter((r) => r.port === 1944);
+    expect(owners).toHaveLength(1);
+    expect(owners[0]?.name).toBe("parachute-app");
+    expect(owners[0]?.status).toBe("assigned");
+  });
+});
 
 function makeTempDir(): { dir: string; cleanup: () => void } {
   const dir = mkdtempSync(join(tmpdir(), "pcli-port-assign-"));
@@ -25,16 +44,20 @@ describe("assignPort (pure)", () => {
   });
 
   test("walks the unassigned reservation range when canonical is occupied", () => {
-    // 1940 is taken; canonical reserved range starts at 1944 → first hit.
+    // 1940 is taken. 1944 is now `parachute-app`'s canonical slot (hub-parity
+    // P5, status "assigned") so the walker skips it; the first RESERVED
+    // (walkable) slot is 1945.
     const result = assignPort(1940, [1940]);
-    expect(result.port).toBe(1944);
+    expect(result.port).toBe(1945);
     expect(result.source).toBe("fallback-in-range");
     expect(result.warning).toMatch(/canonical port 1940 is in use/);
-    expect(result.warning).toMatch(/1944/);
+    expect(result.warning).toMatch(/1945/);
   });
 
   test("skips reservations that are also occupied", () => {
-    // Canonical 1940 + the first three reserved slots are all in use.
+    // Canonical 1940 is in use. 1944 is assigned (parachute-app, skipped
+    // regardless of `occupied`); 1945 is reserved-but-occupied; 1946 is
+    // assigned (parachute-surface, skipped); 1947 is reserved-and-free.
     const result = assignPort(1940, [1940, 1944, 1945, 1946]);
     expect(result.port).toBe(1947);
     expect(result.source).toBe("fallback-in-range");
@@ -60,19 +83,21 @@ describe("assignPort (pure)", () => {
   });
 
   test("third-party (no canonical slot) jumps straight to the reservation range", () => {
+    // 1944 is assigned (parachute-app, hub-parity P5) so the walker skips it;
+    // the first RESERVED (walkable) slot is 1945.
     const result = assignPort(undefined, []);
-    expect(result.port).toBe(1944);
+    expect(result.port).toBe(1945);
     expect(result.source).toBe("fallback-in-range");
     expect(result.warning).toMatch(/no canonical slot/);
-    expect(result.warning).toMatch(/1944/);
+    expect(result.warning).toMatch(/1945/);
   });
 
   test("third-party with reservations occupied walks further in the range", () => {
-    // PORT_RESERVATIONS post-hub#323: 1944 reserved, 1945 reserved, 1946
-    // assigned (parachute-app — KNOWN_MODULES carries the canonical slot
-    // so the fallback walker doesn't hand it to a third party), 1947
-    // reserved. With 1944 + 1945 occupied, the walker skips the assigned
-    // 1946 slot and lands on the next reserved-and-free port — 1947.
+    // PORT_RESERVATIONS: 1944 assigned (parachute-app), 1945 reserved, 1946
+    // assigned (parachute-surface — both carry canonical slots so the
+    // fallback walker doesn't hand them to a third party), 1947 reserved.
+    // With 1944 + 1945 occupied, the walker skips the assigned 1946 slot and
+    // lands on the next reserved-and-free port — 1947.
     const result = assignPort(undefined, [1944, 1945]);
     expect(result.port).toBe(1947);
     expect(result.source).toBe("fallback-in-range");
@@ -145,7 +170,9 @@ describe("assignServicePort (hub#206 — services.json is authoritative)", () =>
         canonical: 1940,
         occupied: [1940],
       });
-      expect(result.port).toBe(1944);
+      // 1944 is parachute-app's assigned (non-walkable) slot as of
+      // hub-parity P5 — the first walkable reserved slot is 1945.
+      expect(result.port).toBe(1945);
       expect(result.source).toBe("fallback-in-range");
       expect(result.warning).toMatch(/canonical port 1940 is in use/);
       // .env stays bit-for-bit identical.
@@ -162,7 +189,9 @@ describe("assignServicePort (hub#206 — services.json is authoritative)", () =>
       const result = assignServicePort({
         occupied: [],
       });
-      expect(result.port).toBe(1944);
+      // 1944 is parachute-app's assigned (non-walkable) slot as of
+      // hub-parity P5 — the first walkable reserved slot is 1945.
+      expect(result.port).toBe(1945);
       expect(result.source).toBe("fallback-in-range");
       expect(existsSync(envPath)).toBe(false);
     } finally {