@openparachute/hub 0.5.13-rc.45 → 0.5.13-rc.46

package/package.json

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

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

@@ -8,6 +8,7 @@ import {
   type UiSubUnit,
   findService,
   readManifest,
+  readManifestLenient,
   removeService,
   upsertService,
   writeManifest,
@@ -1395,3 +1396,95 @@ describe("retired-module row de-dupe (hub#334)", () => {
     }
   });
 });
+
+describe("readManifestLenient — skips bad entries instead of throwing (hub#406)", () => {
+  test("returns the healthy entries when one row has port=0 (the rc.4 app bug)", () => {
+    // Reproduces what hub saw 2026-05-26: a fresh deploy installed
+    // @openparachute/app@0.2.0-rc.4 which wrote a row with name="app"
+    // (wrong) + port=0 (wrong). Strict readManifest threw on the bad
+    // entry — every request to every service 500'd, not just app.
+    // Lenient reader skips the bad row + keeps routing healthy ones.
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            { name: "parachute-vault", port: 1940, paths: ["/vault/default"], health: "/vault/default/health", version: "0.4.8-rc.10" },
+            { name: "parachute-app", port: 1946, paths: ["/app"], health: "/app/healthz", version: "0.2.0-rc.13" },
+            { name: "app", port: 0, paths: ["/app"], health: "/app/healthz", version: "0.2.0-rc.4" },
+          ],
+        }),
+      );
+      const warnings: string[] = [];
+      const log = { warn: (m: string) => warnings.push(m) };
+      const m = readManifestLenient(path, log);
+      const names = m.services.map((s) => s.name).sort();
+      expect(names).toEqual(["parachute-app", "parachute-vault"]);
+      expect(warnings.some((w) => w.includes("port") && w.includes("integer"))).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("returns empty services when the file is malformed JSON, logs the parse error", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(path, "{not valid json");
+      const warnings: string[] = [];
+      const m = readManifestLenient(path, { warn: (msg) => warnings.push(msg) });
+      expect(m.services).toEqual([]);
+      expect(warnings.some((w) => w.includes("failed to parse"))).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("returns empty services when the file is missing", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      // path not yet written
+      const m = readManifestLenient(path, { warn: () => {} });
+      expect(m.services).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("drops duplicate-port entries with a warning instead of throwing", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            { name: "first", port: 1940, paths: ["/x"], health: "/x/health", version: "1.0.0" },
+            { name: "second", port: 1940, paths: ["/y"], health: "/y/health", version: "1.0.0" },
+          ],
+        }),
+      );
+      const warnings: string[] = [];
+      const m = readManifestLenient(path, { warn: (msg) => warnings.push(msg) });
+      expect(m.services).toHaveLength(1);
+      expect(m.services[0]?.name).toBe("first");
+      expect(warnings.some((w) => w.includes("duplicate-port"))).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("strict readManifest still throws on the same bad entry (contract preserved)", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [{ name: "app", port: 0, paths: ["/app"], health: "/app/healthz", version: "0.2.0-rc.4" }],
+        }),
+      );
+      expect(() => readManifest(path)).toThrow(ServicesManifestError);
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/setup-wizard.test.ts

@@ -30,6 +30,7 @@ import { writeManifest } from "../services-manifest.ts";
 import { SESSION_COOKIE_NAME } from "../sessions.ts";
 import {
   deriveWizardState,
+  detectAutoExposeMode,
   handleSetupAccountPost,
   handleSetupExposePost,
   handleSetupGet,
@@ -172,6 +173,62 @@ describe("deriveWizardState", () => {
     }
   });
 
+  test("auto-skips expose step when RENDER_EXTERNAL_URL is set (hub#406 follow-up)", async () => {
+    // Aaron's UX concern: on Render the "How will this hub be reached?"
+    // step asks the operator to pick between localhost / tailnet /
+    // public-with-custom-domain — none of which describe the actual
+    // setup. The platform owns the public URL via RENDER_EXTERNAL_URL.
+    // deriveWizardState now auto-seeds `setup_expose_mode = "public"`
+    // when that env var is present, so the wizard skips straight to
+    // the done screen instead of surfacing an irrelevant choice.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.1.0",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      // Simulate Render env. detectAutoExposeMode reads RENDER_EXTERNAL_URL.
+      const renderEnv = { RENDER_EXTERNAL_URL: "https://parachute-hub.onrender.com" };
+      const s = deriveWizardState({ db, manifestPath: h.manifestPath, env: renderEnv });
+      expect(s.step).toBe("done");
+      expect(s.hasExposeMode).toBe(true);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("does NOT auto-skip expose when RENDER_EXTERNAL_URL is unset (local install path)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            { name: "parachute-vault", version: "0.1.0", port: 1940, paths: ["/vault/default"], health: "/health" },
+          ],
+        },
+        h.manifestPath,
+      );
+      const s = deriveWizardState({ db, manifestPath: h.manifestPath, env: {} });
+      // Local install path — the operator still gets to choose
+      expect(s.step).toBe("expose");
+      expect(s.hasExposeMode).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
   test("done step once admin + vault + expose mode all exist", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
@@ -2944,3 +3001,31 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
     }
   });
 });
+
+describe("detectAutoExposeMode — Render env detection edge cases (hub#407 nit)", () => {
+  test("returns 'public' for a real https Render URL", () => {
+    expect(detectAutoExposeMode({ RENDER_EXTERNAL_URL: "https://parachute-hub.onrender.com" })).toBe("public");
+  });
+
+  test("returns 'public' for an http:// URL (defensive — if Render ever emits one)", () => {
+    expect(detectAutoExposeMode({ RENDER_EXTERNAL_URL: "http://local.test:1939" })).toBe("public");
+  });
+
+  test("returns undefined when RENDER_EXTERNAL_URL is absent", () => {
+    expect(detectAutoExposeMode({})).toBeUndefined();
+  });
+
+  test("returns undefined when RENDER_EXTERNAL_URL is empty", () => {
+    expect(detectAutoExposeMode({ RENDER_EXTERNAL_URL: "" })).toBeUndefined();
+  });
+
+  test("returns undefined for a non-http scheme (httpx://, ftp://, etc.)", () => {
+    expect(detectAutoExposeMode({ RENDER_EXTERNAL_URL: "httpx://foo.example" })).toBeUndefined();
+    expect(detectAutoExposeMode({ RENDER_EXTERNAL_URL: "ftp://foo.example" })).toBeUndefined();
+    expect(detectAutoExposeMode({ RENDER_EXTERNAL_URL: "javascript:alert(1)" })).toBeUndefined();
+  });
+
+  test("returns undefined when value is non-string (defensive)", () => {
+    expect(detectAutoExposeMode({ RENDER_EXTERNAL_URL: undefined })).toBeUndefined();
+  });
+});

package/src/hub-server.ts

@@ -177,7 +177,7 @@ import {
   effectivePublicExposure,
   shortNameForManifest,
 } from "./service-spec.ts";
-import { type ServiceEntry, readManifest } from "./services-manifest.ts";
+import { type ServiceEntry, readManifest, readManifestLenient } from "./services-manifest.ts";
 import { findActiveSession } from "./sessions.ts";
 import {
   type SetupWizardDeps,
@@ -582,16 +582,19 @@ export function findServiceUpstream(
  * Returns `undefined` when no service claims the pathname; caller 404s.
  */
 async function proxyToService(req: Request, manifestPath: string): Promise<Response | undefined> {
-  let services: readonly ServiceEntry[];
-  try {
-    services = readManifest(manifestPath).services;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `service routing failed: ${msg}` }), {
-      status: 500,
-      headers: { "content-type": "application/json" },
-    });
-  }
+  // Lenient read on the hot-path — a single malformed services.json
+  // entry (e.g. a module installed at a buggy version that wrote
+  // `port: 0`) used to cascade into 500s for every route on this hub
+  // because the strict throw bailed BEFORE we could dispatch to the
+  // healthy entries. `readManifestLenient` skips + logs bad rows so
+  // unrelated services keep working. The strict `readManifest` is
+  // still used by write paths + admin surfaces that want errors
+  // surfaced immediately. See hub#406.
+  //
+  // The default `log` is `console`, which under Render's container
+  // routing surfaces in the Logs panel — operators see the warning
+  // about the skipped entry.
+  const services = readManifestLenient(manifestPath).services;
   const url = new URL(req.url);
   const match = findServiceUpstream(services, url.pathname);
   if (!match) return undefined;

package/src/services-manifest.ts

@@ -405,6 +405,88 @@ function validateManifest(raw: unknown, where: string): ServicesManifest {
   return { services: entries };
 }
 
+/**
+ * Lenient counterpart to `readManifest` — used by hub's hot-path service
+ * routing (`proxyToService`). The strict `readManifest` throws when ANY
+ * entry fails validation; an entire bad row (e.g. an installed module
+ * that wrote `port: 0` to its services.json row before the module's
+ * own selfRegister gained validation) takes down ALL routing because
+ * the routing call site catches the throw and returns 500.
+ *
+ * This lenient reader:
+ *   - parses the file the same way (JSON parse + cleanup passes)
+ *   - validates each entry independently
+ *   - skips entries that fail validation, logging a warning per skip
+ *   - returns the validated remainder
+ *
+ * The trade-off: strict callers (admin SPA write paths, init flows,
+ * tests) keep the throw — they want bugs surfaced immediately. The
+ * routing path uses this so a single bad row doesn't cascade into
+ * "the whole hub appears broken to users." Operators see the rest
+ * of their services keep working + a warning in the logs pointing at
+ * the offending entry.
+ *
+ * Caught 2026-05-26 (hub#406) when @openparachute/app@0.2.0-rc.4 wrote
+ * a row with `name: "app"` (instead of `parachute-app`) + `port: 0`
+ * (instead of bound port). Hub's routing throw on services.json read
+ * meant every request to every service 500'd — not just app — because
+ * one row's bad shape took out the whole manifest read.
+ *
+ * One behavioral difference from strict `readManifest`: this function
+ * does NOT write cleanup mutations back to disk. The bad row persists
+ * on disk until a write-path call (upsertService, etc.) exercises the
+ * strict path. That's intentional — a hot-path read should not mutate
+ * state — but worth knowing: a fix upstream (e.g. app@rc.13 overwriting
+ * the bad row on its next selfRegister) is what finally clears it.
+ */
+export function readManifestLenient(
+  path: string = SERVICES_MANIFEST_PATH,
+  log: { warn?: (msg: string) => void } = console,
+): ServicesManifest {
+  if (!existsSync(path)) return { services: [] };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    log.warn?.(
+      `[services-manifest] failed to parse ${path}: ${err instanceof Error ? err.message : String(err)} — treating as empty`,
+    );
+    return { services: [] };
+  }
+  const afterRetired = dropRetiredModuleRows(raw, path);
+  const cleaned = dropLegacyShortNameRows(afterRetired.raw, path);
+  // `typeof null === "object"` in JS, so the `!cleaned.raw` part of this
+  // guard is load-bearing for the null case — not a typo or redundancy.
+  if (!cleaned.raw || typeof cleaned.raw !== "object") return { services: [] };
+  const services = (cleaned.raw as Record<string, unknown>).services;
+  if (!Array.isArray(services)) return { services: [] };
+  const valid: ServiceEntry[] = [];
+  for (let i = 0; i < services.length; i++) {
+    try {
+      valid.push(validateEntry(services[i], `${path} services[${i}]`));
+    } catch (err) {
+      log.warn?.(
+        `[services-manifest] skipping bad entry: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  // Best-effort duplicate-port detection — log + drop the duplicate
+  // rather than throw.
+  const seenPorts = new Set<number>();
+  const dedup: ServiceEntry[] = [];
+  for (const e of valid) {
+    if (seenPorts.has(e.port)) {
+      log.warn?.(
+        `[services-manifest] dropping duplicate-port entry: name=${JSON.stringify(e.name)} port=${e.port}`,
+      );
+      continue;
+    }
+    seenPorts.add(e.port);
+    dedup.push(e);
+  }
+  return { services: dedup };
+}
+
 export function readManifest(path: string = SERVICES_MANIFEST_PATH): ServicesManifest {
   if (!existsSync(path)) return { services: [] };
   let raw: unknown;

package/src/setup-wizard.ts

@@ -141,12 +141,21 @@ export const FIRST_VAULT_SHORT: CuratedModuleShort = "vault";
 
 /**
  * Read DB + services.json to decide which step the wizard should render.
- * Pure, idempotent — re-running the wizard after partial setup picks up
- * where it left off.
+ * Idempotent — re-running after partial setup picks up where it left
+ * off. Mostly read-only, with one specific write: on Render (or any
+ * platform `detectAutoExposeMode` recognizes), the first call auto-
+ * seeds `setup_expose_mode = "public"` so the wizard skips the expose
+ * step. Subsequent calls find the setting present and are read-only.
  */
 export function deriveWizardState(deps: {
   db: Database;
   manifestPath: string;
+  /**
+   * Optional env-override. When undefined, falls through to `process.env`.
+   * Used by tests + by handleSetupGet which threads through the full
+   * SetupWizardDeps.env.
+   */
+  env?: Record<string, string | undefined>;
 }): DerivedWizardState {
   const hasAdmin = userCount(deps.db) > 0;
   // The wizard's first-vault provisioning uses the curated `vault` short,
@@ -156,7 +165,19 @@ export function deriveWizardState(deps: {
   const hasVault = vaultEntry !== undefined;
   // Expose-mode is the operator's "how will this hub be reached?" answer
   // (hub#268 Item 2). Stored as a hub_setting; the wizard's expose step
-  // sets it; absence means we should still ask.
+  // sets it; absence means we should still ask. EXCEPT — if we're
+  // running on a platform where the answer is pre-determined (e.g.
+  // Render exposes the service at $RENDER_EXTERNAL_URL automatically),
+  // auto-seed `setup_expose_mode = "public"` so the wizard skips the
+  // expose step entirely. The operator landed here through a deploy
+  // path that already answered the question; asking again wastes a
+  // click and surfaces irrelevant options (localhost, tailnet).
+  if (
+    getSetting(deps.db, "setup_expose_mode") === undefined &&
+    detectAutoExposeMode(deps.env ?? process.env) === "public"
+  ) {
+    setSetting(deps.db, "setup_expose_mode", "public");
+  }
   const hasExposeMode = getSetting(deps.db, "setup_expose_mode") !== undefined;
   let step: WizardStep;
   // Note: `"account"` is a visual-only step in the progress header —
@@ -200,6 +221,43 @@ export interface SetupWizardDeps {
   registry?: OperationsRegistry;
   /** Test seam: stub `bun add` / `bun remove` runner. */
   run?: (cmd: readonly string[]) => Promise<number>;
+  /**
+   * Test seam: override the process env that `detectAutoExposeMode`
+   * consults. Production omits this and the helper reads `process.env`
+   * directly. Setting in tests lets the auto-skip branch be exercised
+   * without mutating the real process env.
+   */
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * Returns `"public"` when the runtime env indicates the hub is deployed
+ * on a platform where the "how will this hub be reached?" answer is
+ * pre-determined by the platform. Today: Render (sets RENDER_EXTERNAL_URL
+ * for any web service). Returns `undefined` otherwise — the wizard's
+ * expose step asks the operator.
+ *
+ * Why this matters: on Render, none of the three radio options
+ * (localhost, tailnet, public-with-custom-domain) match the actual
+ * setup. The hub is reached at `*.onrender.com` automatically. Asking
+ * the operator wastes a click and surfaces three options that don't
+ * speak to their situation. Auto-pinning `public` skips the step.
+ *
+ * Add more platforms here when we encounter them — e.g. Fly.io
+ * (FLY_APP_NAME), Railway (RAILWAY_ENVIRONMENT), etc. Each only auto-
+ * detects when the platform clearly owns the public URL.
+ */
+export function detectAutoExposeMode(env: Record<string, string | undefined>): "public" | undefined {
+  // Render always sets `RENDER_EXTERNAL_URL` to a real `https://` URL on
+  // any web service. `startsWith("https://")` is the precise shape; we
+  // also accept `http://` as a defensive fallback in case Render ever
+  // changes the scheme on some plan tier. Anything else (empty, weird,
+  // not a URL) → don't auto-skip; let the operator choose.
+  const url = env.RENDER_EXTERNAL_URL;
+  if (typeof url === "string" && (url.startsWith("https://") || url.startsWith("http://"))) {
+    return "public";
+  }
+  return undefined;
 }
 
 // --- rendering -----------------------------------------------------------