@openparachute/hub 0.5.13-rc.11 → 0.5.13-rc.12

package/README.md

@@ -2,7 +2,7 @@
 
 `@openparachute/hub` — the local hub for the [Parachute](https://parachute.computer) ecosystem. The `parachute` binary is one of its surfaces.
 
-The hub coordinates the modules running on your machine: it installs them, runs them as background processes, exposes them over Tailscale, serves the discovery document at `/.well-known/parachute.json`, and (soon) issues OAuth tokens. Each module (vault, notes, scribe, channel, …) stays a standalone package; the hub stitches them together.
+The hub coordinates the modules running on your machine: it installs them, runs them as background processes, exposes them over Tailscale, serves the discovery document at `/.well-known/parachute.json`, and (soon) issues OAuth tokens. Each module (vault, app, scribe, …) stays a standalone package; the hub stitches them together.
 
 > Previously published as `@openparachute/cli`. Renamed 2026-04-26 to better reflect the role — see [parachute-patterns/hub-as-issuer](https://github.com/ParachuteComputer/parachute-patterns/blob/main/patterns/hub-as-issuer.md). The `parachute` binary name is unchanged.
 
@@ -160,16 +160,19 @@ Parachute services reserve a block of loopback ports in the canonical range **19
 | 1939 | parachute-hub (internal proxy + static) |
 | 1940 | parachute-vault    |
 | 1941 | parachute-channel  |
-| 1942 | parachute-notes    |
+| 1942 | parachute-notes *(deprecating — see [notes#154](https://github.com/ParachuteComputer/parachute-notes/issues/154); folds into parachute-app at 1946)* |
 | 1943 | parachute-scribe   |
-| 1944–1949 | *unassigned (CLI fallback range)* |
+| 1944 | *parachute-agent (retired 2026-05-20; slot held — see [`parachute-agent/DEPRECATED.md`](https://github.com/ParachuteComputer/parachute-agent/blob/main/DEPRECATED.md))* |
+| 1945 | parachute-runner *(shipped; exploration-tier, not committed-core)* |
+| 1946 | parachute-app *(committed core; UI host, ships Notes as canonical first app)* |
+| 1947–1949 | *unassigned (CLI fallback range)* |
 
 The hub pins 1939 — no fallback. If something else is on 1939 when you run `parachute expose`, the command fails with a pointer to `lsof -iTCP:1939` rather than walking up into another service's slot.
 
 **The CLI is the port authority.** `parachute install <svc>` picks the port at install time and writes `PORT=<port>` into `~/.parachute/<svc>/.env`; lifecycle.start merges that .env into the spawn env so the next daemon boot binds the port the CLI assigned. The algorithm:
 
 1. Prefer the canonical slot (e.g. vault → 1940).
-2. On collision, walk the unassigned range (1944–1949).
+2. On collision, walk the unassigned range (1947–1949).
 3. Range exhausted: assign past 1949 with a warning.
 
 Idempotent: an existing `PORT=` in `~/.parachute/<svc>/.env` wins, so re-installs and operator-edited ports survive across upgrades. Services keep their compiled-in fallbacks (vault → 1940 etc.) so a stand-alone `bun run` still works without a CLI-managed .env.

package/package.json

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

package/src/__tests__/api-modules.test.ts

@@ -149,8 +149,10 @@ describe("GET /api/modules", () => {
 
   test("200 + curated list on fresh container (empty services.json)", async () => {
     // The v0.6 hot path: brand-new Render container, no services.json
-    // yet. UI must render "install vault / notes / scribe / runner"
-    // cards even though nothing's installed.
+    // yet. UI must render "install vault / app / notes / scribe / runner"
+    // cards even though nothing's installed. hub#323 inserted `app` between
+    // `vault` and `notes` — app auto-bootstraps notes-ui as a sub-unit;
+    // `notes` (notes-daemon) stays curated for back-compat install paths.
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
     const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
       db: h.db,
@@ -168,8 +170,8 @@ describe("GET /api/modules", () => {
       }>;
       supervisor_available: boolean;
     };
-    // Curated order is preserved: vault → notes → scribe → runner.
-    expect(body.modules.map((m) => m.short)).toEqual(["vault", "notes", "scribe", "runner"]);
+    // Curated order is preserved: vault → app → notes → scribe → runner.
+    expect(body.modules.map((m) => m.short)).toEqual(["vault", "app", "notes", "scribe", "runner"]);
     expect(body.modules.every((m) => m.available)).toBe(true);
     expect(body.modules.every((m) => !m.installed)).toBe(true);
     expect(body.modules.every((m) => m.latest_version === "0.9.9")).toBe(true);
@@ -177,6 +179,37 @@ describe("GET /api/modules", () => {
     expect(body.supervisor_available).toBe(false);
   });
 
+  test("app row carries package + display props from KNOWN_MODULES (#323)", async () => {
+    // hub#323 added app to CURATED_MODULES + KNOWN_MODULES so the admin SPA
+    // install catalog + setup-wizard install tile surface it. Spot-check the
+    // wire shape resolves app-specific fields (package, displayName, tagline)
+    // from KNOWN_MODULES rather than a stale default — same shape as the
+    // runner row test below.
+    const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => "0.2.0",
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      modules: Array<{
+        short: string;
+        package: string;
+        display_name: string;
+        tagline: string;
+        available: boolean;
+      }>;
+    };
+    const app = body.modules.find((m) => m.short === "app");
+    expect(app).toBeDefined();
+    expect(app?.package).toBe("@openparachute/app");
+    expect(app?.display_name).toBe("App");
+    expect(app?.tagline).toContain("auto-installs Notes");
+    expect(app?.available).toBe(true);
+  });
+
   test("runner row carries package + display props from FIRST_PARTY_FALLBACKS (#305)", async () => {
     // hub#305 added runner to CURATED_MODULES + FIRST_PARTY_FALLBACKS so
     // the admin SPA install catalog surfaces it. Spot-check the wire

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

@@ -68,8 +68,13 @@ describe("assignPort (pure)", () => {
   });
 
   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.
     const result = assignPort(undefined, [1944, 1945]);
-    expect(result.port).toBe(1946);
+    expect(result.port).toBe(1947);
     expect(result.source).toBe("fallback-in-range");
   });
 });

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

@@ -1712,7 +1712,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
   });
   afterEach(() => h.cleanup());
 
-  test("done screen renders Install Notes + Install Scribe tiles when neither is installed", async () => {
+  test("done screen renders Install App + Install Scribe tiles when neither is installed", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -1747,10 +1747,21 @@ describe("done screen install tiles (hub#272 Item B)", () => {
       );
       const html = await res.text();
       expect(html).toContain("What's next?");
-      expect(html).toContain("Install Notes");
+      // hub#323: App replaces Notes as the first install tile. App auto-bootstraps
+      // Notes (parachute-app §17 Phase 2.1) so operators don't need to install
+      // notes-daemon directly; the tagline telegraphs that Notes comes with App.
+      expect(html).toContain("Install App");
       expect(html).toContain("Install Scribe");
-      expect(html).toContain('action="/admin/setup/install/notes"');
+      expect(html).toContain('action="/admin/setup/install/app"');
       expect(html).toContain('action="/admin/setup/install/scribe"');
+      // App tile sits first in the render order — verified by both tiles
+      // appearing AND app's index in the rendered HTML preceding scribe's.
+      expect(html.indexOf("Install App")).toBeLessThan(html.indexOf("Install Scribe"));
+      // Notes is no longer a wizard tile; notes-daemon still installable
+      // via /api/modules/notes/install for back-compat, but the wizard
+      // doesn't surface it.
+      expect(html).not.toContain("Install Notes");
+      expect(html).not.toContain('action="/admin/setup/install/notes"');
     } finally {
       db.close();
     }
@@ -1770,12 +1781,15 @@ describe("done screen install tiles (hub#272 Item B)", () => {
               paths: ["/vault/default"],
               health: "/health",
             },
+            // hub#323: app replaces notes as the wizard's first install tile.
+            // Seeding services.json with `parachute-app` exercises the
+            // already-installed render path on the wizard's first tile.
             {
-              name: "parachute-notes",
-              version: "0.1.0",
-              port: 1942,
-              paths: ["/notes"],
-              health: "/notes/health",
+              name: "parachute-app",
+              version: "0.2.0",
+              port: 1946,
+              paths: ["/app", "/.parachute"],
+              health: "/app/healthz",
             },
           ],
         },
@@ -1804,7 +1818,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
     }
   });
 
-  test("done screen renders op-poll panel when ?op_notes=<id> matches a registry op", async () => {
+  test("done screen renders op-poll panel when ?op_app=<id> matches a registry op", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -1824,12 +1838,15 @@ describe("done screen install tiles (hub#272 Item B)", () => {
       );
       setSetting(db, "setup_expose_mode", "localhost");
       const reg = getDefaultOperationsRegistry();
-      const op = reg.create("install", "notes");
-      reg.update(op.id, { status: "running" }, "running bun add -g @openparachute/notes@latest");
+      // hub#323: op-poll panel rides on the `app` tile now (app is the wizard's
+      // first install tile post-Notes-as-app-migration). Same shape as the
+      // pre-#324 `op_notes=<id>` flow.
+      const op = reg.create("install", "app");
+      reg.update(op.id, { status: "running" }, "running bun add -g @openparachute/app@latest");
       const { createSession } = await import("../sessions.ts");
       const session = createSession(db, { userId: user.id });
       const res = handleSetupGet(
-        req(`/admin/setup?just_finished=1&op_notes=${op.id}`, {
+        req(`/admin/setup?just_finished=1&op_app=${op.id}`, {
           headers: { cookie: `${SESSION_COOKIE_NAME}=${session.id}` },
         }),
         {

package/src/__tests__/setup.test.ts

@@ -123,6 +123,7 @@ describe("setup", () => {
         { name: "parachute-scribe", port: 1943 },
         { name: "parachute-channel", port: 1941 },
         { name: "parachute-runner", port: 1945 },
+        { name: "parachute-app", port: 1946 },
       ];
       for (const s of seeds) {
         upsertService(

package/src/api-modules.ts

@@ -77,12 +77,14 @@ export const API_MODULES_REQUIRED_SCOPE = "parachute:host:auth";
 
 /**
  * Curated module short-names for v0.6 Render self-host. Marketplace is
- * Phase 2 — until then, the admin UI offers exactly these four. Order
- * is the recommended install order (vault → notes → scribe → runner;
- * runner comes last because it depends on a working vault + scribe to
- * be useful, and operators usually wire those up first).
+ * Phase 2 — until then, the admin UI offers exactly these. Order is the
+ * recommended install order (vault → app → notes → scribe → runner;
+ * app auto-bootstraps notes-ui on first boot — `notes` here is the
+ * notes-daemon back-compat install path retained for operators still on
+ * the pre-app architecture; scribe + runner come last because they
+ * depend on a working vault + app to be useful).
  */
-export const CURATED_MODULES = ["vault", "notes", "scribe", "runner"] as const;
+export const CURATED_MODULES = ["vault", "app", "notes", "scribe", "runner"] as const;
 export type CuratedModuleShort = (typeof CURATED_MODULES)[number];
 
 export interface ApiModulesDeps {

package/src/commands/setup.ts

@@ -151,8 +151,10 @@ function surveyServices(manifestPath: string): ServiceChoice[] {
 
 const BLURBS: Record<string, string> = {
   vault: "knowledge graph (MCP) — your owner-authenticated note + tag store",
-  notes: "Notes PWA — web/mobile UI on top of vault",
+  app: "Parachute UI host — auto-installs Notes on first boot (recommended over notes-daemon)",
+  notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `app`)",
   scribe: "audio transcription for dictation + recordings",
+  runner: "vault-as-job-substrate — scheduled claude -p against vault job notes",
   channel: "(exploratory — may retire) notification fan-out across modules",
 };
 

package/src/service-spec.ts

@@ -64,7 +64,11 @@ export const PORT_RESERVATIONS: readonly PortReservation[] = [
   { port: 1943, name: "parachute-scribe", status: "assigned" },
   { port: 1944, name: "unassigned", status: "reserved" },
   { port: 1945, name: "unassigned", status: "reserved" },
-  { port: 1946, name: "unassigned", status: "reserved" },
+  // hub#323: parachute-app's canonical slot. Status `assigned` keeps the
+  // fallback-port walker (`assignPort` in port-assign.ts) from handing this
+  // port out to a colliding third-party module. The matching KNOWN_MODULES
+  // row carries the canonicalPort + paths for status/expose surfaces.
+  { port: 1946, name: "parachute-app", status: "assigned" },
   { port: 1947, name: "unassigned", status: "reserved" },
   { port: 1948, name: "unassigned", status: "reserved" },
   { port: 1949, name: "unassigned", status: "reserved" },
@@ -484,6 +488,37 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
       hasAuth: true,
     },
   },
+  app: {
+    short: "app",
+    package: "@openparachute/app",
+    manifestName: "parachute-app",
+    canonicalPort: 1946,
+    displayName: "App",
+    // Tagline telegraphs the auto-bootstrap so wizard + admin-SPA copy explain
+    // the architecture: installing `app` brings Notes (and other UIs) along
+    // via the Phase 2.1 bootstrap-default-apps step. The notes-daemon path
+    // still exists as a back-compat install (CURATED_MODULES still lists
+    // `notes`) but `app` is the recommended first install post-vault.
+    tagline: "Host module for Parachute UIs — auto-installs Notes on first boot.",
+    // Frontend posture: app's primary surface is serving sub-app UIs under
+    // `/app/<name>/` mounted under one origin (design doc §12). Hub's
+    // exposure-default + supervisor-defaults follow the frontend lane.
+    kind: "frontend",
+    canonicalPaths: ["/app", "/.parachute"],
+    canonicalHealth: "/app/healthz",
+    canonicalStripPrefix: false,
+    extras: {
+      // Backward-compat startCmd — same rationale as scribe / vault / runner
+      // above. Post-self-register, lifecycle reads module.json's startCmd via
+      // `composeKnownModuleSpec` and that path wins.
+      startCmd: () => ["parachute-app", "serve"],
+      // App's admin + per-UI surfaces gate behind hub-issued JWTs (design
+      // doc §6 same-hub auto-trust + scope `app:admin`). Surfaces in
+      // `parachute status` as auth-required by default, same posture as vault
+      // + runner.
+      hasAuth: true,
+    },
+  },
 };
 
 /**

package/src/setup-wizard.ts

@@ -1522,7 +1522,11 @@ const INSTALL_TILE_PROPS: ReadonlyArray<{
   displayName: string;
   tagline: string;
 }> = [
-  { short: "notes", displayName: "Notes", tagline: "Notes PWA backed by your vault." },
+  {
+    short: "app",
+    displayName: "App",
+    tagline: "Host module for Parachute UIs — auto-installs Notes on first boot.",
+  },
   {
     short: "scribe",
     displayName: "Scribe",