@openparachute/hub 0.5.2 → 0.5.9-rc.6

package/src/commands/lifecycle.ts

@@ -136,6 +136,24 @@ export interface LifecycleOpts {
   killWaitMs?: number;
   /** Poll interval while waiting for SIGTERM to land. */
   pollIntervalMs?: number;
+  /**
+   * How long `start` sleeps before re-checking `alive(pid)` to catch the
+   * spawn-then-immediately-die failure shape (hub#194: notes-serve crashed
+   * 50ms in on Bun.resolveSync, but `start` reported success because the
+   * spawn returned a pid). 250ms is the default in production — long
+   * enough to catch real silent-crashes (resolve failures, port
+   * collisions, missing args) without making `parachute start` feel
+   * laggy.
+   *
+   * Defaulting policy: if `alive` is not overridden, the settle defaults
+   * to 0 (skipped). Stub spawners hand back fake pids that the real
+   * `defaultAlive` would mark as dead, which would make every existing
+   * stub-spawner test fail spuriously. Tests that want to exercise the
+   * settle path inject both `alive` and `startSettleMs` explicitly.
+   * Production paths use the real `defaultAlive` and get the real 250ms
+   * settle.
+   */
+  startSettleMs?: number;
   /**
    * Override the hub origin passed to services as PARACHUTE_HUB_ORIGIN. If
    * unset, `start` derives it from `expose-state.json` (when exposed) or
@@ -168,6 +186,7 @@ interface Resolved {
   log: (line: string) => void;
   killWaitMs: number;
   pollIntervalMs: number;
+  startSettleMs: number;
   hubOrigin: string | undefined;
   ensureHub: (opts: EnsureHubOpts) => Promise<EnsureHubResult>;
   stopHubFn: (opts: StopHubOpts) => Promise<boolean>;
@@ -186,6 +205,14 @@ function resolve(opts: LifecycleOpts): Resolved {
     log: opts.log ?? ((line) => console.log(line)),
     killWaitMs: opts.killWaitMs ?? 10_000,
     pollIntervalMs: opts.pollIntervalMs ?? 200,
+    // See `LifecycleOpts.startSettleMs` doc. Production (no spawner
+    // override, no alive override) gets the 250ms settle. Tests that
+    // inject a stub spawner without a stub alive get 0 — `defaultAlive`
+    // against a fake pid would always report dead and break unrelated
+    // tests. Tests that want to exercise the settle path explicitly
+    // override `alive`, which re-enables the default 250ms.
+    startSettleMs:
+      opts.startSettleMs ?? (opts.spawner === undefined || opts.alive !== undefined ? 250 : 0),
     hubOrigin: resolveHubOrigin(opts.hubOrigin, configDir),
     ensureHub: opts.hub?.ensureRunning ?? ensureHubRunning,
     stopHubFn: opts.hub?.stop ?? stopHub,
@@ -371,16 +398,38 @@ export async function start(svc: string | undefined, opts: LifecycleOpts = {}):
     if (entry.installDir) spawnerOpts.cwd = entry.installDir;
     const passOpts =
       spawnerOpts.env !== undefined || spawnerOpts.cwd !== undefined ? spawnerOpts : undefined;
+    let pid: number;
     try {
-      const pid = r.spawner.spawn(cmd, logFile, passOpts);
-      writePid(short, pid, r.configDir);
-      r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
-      if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
+      pid = r.spawner.spawn(cmd, logFile, passOpts);
     } catch (err) {
       failures++;
       const msg = err instanceof Error ? err.message : String(err);
       r.log(`✗ ${short} failed to start: ${msg}`);
+      continue;
+    }
+    writePid(short, pid, r.configDir);
+
+    // Settle-poll for spawn-then-immediately-die (hub#194). A spawn returning
+    // a pid only proves the kernel forked the process; the child may exit
+    // microseconds later if its main code path throws before listening
+    // (e.g. notes-serve's Bun.resolveSync failing for bun-linked installs).
+    // Without this poll, we'd report success and the operator would chase
+    // a phantom 502.
+    if (r.startSettleMs > 0) {
+      await r.sleep(r.startSettleMs);
+      if (!r.alive(pid)) {
+        clearPid(short, r.configDir);
+        failures++;
+        r.log(
+          `✗ ${short} failed to start: spawned pid ${pid} but the process exited within ${r.startSettleMs}ms.`,
+        );
+        r.log(`  Tail the log for details: tail -50 ${logFile}`);
+        continue;
+      }
     }
+
+    r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
+    if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
   }
   return failures === 0 ? 0 : 1;
 }

package/src/commands/status.ts

@@ -1,7 +1,14 @@
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_SVC, readHubPort } from "../hub-control.ts";
+import {
+  type DetectInstallSourceDeps,
+  detectHubInstallSource,
+  detectInstallSource,
+  formatInstallSourceLabel,
+  isStale,
+} from "../install-source.ts";
 import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
-import { getSpec, shortNameForManifest } from "../service-spec.ts";
+import { canonicalPortForManifest, getSpec, shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
 
 export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
@@ -14,6 +21,19 @@ export interface StatusOpts {
   configDir?: string;
   alive?: AliveFn;
   now?: () => Date;
+  /**
+   * Test seam for install-source detection. Production reads the filesystem
+   * + shells out to git; tests inject stubs so each case (npm / bun-linked /
+   * unknown / stale) is exercised deterministically without depending on
+   * the operator's actual bun globals.
+   */
+  installSourceDeps?: DetectInstallSourceDeps;
+  /**
+   * Directory containing the running hub source. Defaults to `import.meta.dir`
+   * (the directory of this file). Tests override so the hub row's install
+   * source classification doesn't depend on the test runner's location.
+   */
+  hubSrcDir?: string;
 }
 
 export interface ProbeResult {
@@ -71,9 +91,25 @@ interface StatusRow {
   uptimeLabel: string;
   healthLabel: string;
   latencyLabel: string;
+  sourceLabel: string;
   url: string | undefined;
   healthy: boolean;
   skipped: boolean;
+  /**
+   * Canonical-port drift warning. Set when the entry has a known canonical
+   * port (first-party / known short) AND the actual port differs. Surfaced
+   * as a continuation line under the row so operators see a silent miswire
+   * (e.g. parachute-hub#195: scribe + agent both at 1944) without us
+   * hard-erroring on a deliberate operator port change.
+   */
+  driftWarning?: string;
+  /**
+   * Version-drift indicator (hub#243). Set when a bun-linked service's
+   * `services.json.version` lags the live `package.json` version at its
+   * checkout. Surfaced as a continuation line so operators can spot a
+   * stale-after-rebuild row without comparing columns by eye.
+   */
+  staleNote?: string;
 }
 
 /**
@@ -90,7 +126,13 @@ function urlForEntry(entry: ServiceEntry, short: string | undefined): string | u
   return `http://127.0.0.1:${entry.port}${first}`;
 }
 
-function hubRow(configDir: string, alive: AliveFn, nowDate: Date): StatusRow | undefined {
+function hubRow(
+  configDir: string,
+  alive: AliveFn,
+  nowDate: Date,
+  hubSrcDir: string,
+  installSourceDeps: DetectInstallSourceDeps,
+): StatusRow | undefined {
   const proc = processState(HUB_SVC, configDir, alive);
   if (proc.status === "unknown") return undefined;
   const port = readHubPort(configDir);
@@ -99,15 +141,17 @@ function hubRow(configDir: string, alive: AliveFn, nowDate: Date): StatusRow | u
   const pidLabel = proc.status === "running" && proc.pid !== undefined ? String(proc.pid) : "-";
   const uptimeLabel =
     proc.status === "running" && proc.startedAt ? formatUptime(proc.startedAt, nowDate) : "-";
+  const source = detectHubInstallSource(hubSrcDir, installSourceDeps);
   return {
     service: "parachute-hub (internal)",
     port: portLabel,
-    version: "-",
+    version: source.livePackageVersion ?? "-",
     processLabel,
     pidLabel,
     uptimeLabel,
     healthLabel: "-",
     latencyLabel: "-",
+    sourceLabel: formatInstallSourceLabel(source),
     url: port !== undefined ? `http://127.0.0.1:${port}` : undefined,
     healthy: true,
     skipped: true,
@@ -122,6 +166,8 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
   const configDir = opts.configDir ?? CONFIG_DIR;
   const alive = opts.alive ?? defaultAlive;
   const now = opts.now ?? (() => new Date());
+  const installSourceDeps = opts.installSourceDeps ?? {};
+  const hubSrcDir = opts.hubSrcDir ?? import.meta.dir;
 
   const manifest = readManifest(manifestPath);
   if (manifest.services.length === 0) {
@@ -157,6 +203,30 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
 
       const url = urlForEntry(entry, short);
 
+      // Canonical-port drift detection (hub#195). Only fires for known
+      // first-party services where we have a canonical assignment. Third-party
+      // rows have no canonical to compare against. Warning is informational —
+      // operators may have moved a service off canonical deliberately.
+      // Note: multi-vault instance rows (`parachute-vault-<instance>`) don't
+      // match a canonical manifest name, so drift warnings don't fire for
+      // them. Intentional — see `canonicalPortForManifest` for the rationale.
+      const canonical = canonicalPortForManifest(entry.name);
+      const driftWarning =
+        canonical !== undefined && canonical !== entry.port
+          ? `canonical port is ${canonical}`
+          : undefined;
+
+      // Install-source detection (hub#243). One filesystem walk + maybe one
+      // `git rev-parse` per row. Failures degrade silently to `unknown` —
+      // status output should never error out on a missing checkout dir.
+      const detectArgs: { entryName: string; installDir?: string } = { entryName: entry.name };
+      if (entry.installDir !== undefined) detectArgs.installDir = entry.installDir;
+      const source = detectInstallSource(detectArgs, installSourceDeps);
+      const sourceLabel = formatInstallSourceLabel(source);
+      const staleNote = isStale(entry.version, source)
+        ? `STALE: services.json cached ${entry.version}; live package.json ${source.livePackageVersion}`
+        : undefined;
+
       // Only skip probe when we know the process is dead (PID file was
       // present but kill(pid, 0) failed). "unknown" status (no PID file)
       // still probes — externally-managed services should report health.
@@ -170,9 +240,12 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           uptimeLabel,
           healthLabel: "-",
           latencyLabel: "-",
+          sourceLabel,
           url,
           healthy: false,
           skipped: true,
+          driftWarning,
+          staleNote,
         };
       }
 
@@ -191,19 +264,32 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
         uptimeLabel,
         healthLabel,
         latencyLabel: `${p.latencyMs}ms`,
+        sourceLabel,
         url,
         healthy: p.healthy,
         skipped: false,
+        driftWarning,
+        staleNote,
       };
     }),
   );
 
   // Hub is an internal service — not in services.json, but users notice
   // when it's dead. Only show it if we've seen it run.
-  const hub = hubRow(configDir, alive, nowDate);
+  const hub = hubRow(configDir, alive, nowDate, hubSrcDir, installSourceDeps);
   if (hub) rows.push(hub);
 
-  const header = ["SERVICE", "PORT", "VERSION", "PROCESS", "PID", "UPTIME", "HEALTH", "LATENCY"];
+  const header = [
+    "SERVICE",
+    "PORT",
+    "VERSION",
+    "PROCESS",
+    "PID",
+    "UPTIME",
+    "HEALTH",
+    "LATENCY",
+    "SOURCE",
+  ];
   const textRows = rows.map((r) => [
     r.service,
     r.port,
@@ -213,14 +299,17 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     r.uptimeLabel,
     r.healthLabel,
     r.latencyLabel,
+    r.sourceLabel,
   ]);
   const widths = header.map((_, i) =>
     Math.max(header[i]?.length ?? 0, ...textRows.map((r) => r[i]?.length ?? 0)),
   );
   print(formatRow(header, widths));
-  // URL stays on a continuation line rather than a column. URLs are long
-  // (vault's MCP path runs ~40 chars), and a ninth column would push the
-  // table past 80 cols on every install. The "  → " prefix groups visually
+  // URL, drift, and stale notes stay on continuation lines rather than
+  // columns. URLs are long (vault's MCP path runs ~40 chars); SOURCE labels
+  // can be long for bun-linked rows. Spreading them across columns would
+  // push the table well past 80 cols on every install — continuation lines
+  // keep the table scannable. The "  → " / "  ! " prefixes group visually
   // with the row above without misleading the table widths.
   for (let i = 0; i < textRows.length; i++) {
     const cells = textRows[i];
@@ -228,6 +317,8 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     if (!cells || !row) continue;
     print(formatRow(cells, widths));
     if (row.url) print(`  → ${row.url}`);
+    if (row.driftWarning) print(`  ! ${row.driftWarning}`);
+    if (row.staleNote) print(`  ! ${row.staleNote}`);
   }
 
   /**

package/src/csrf.ts

@@ -19,9 +19,12 @@
  * pre-login and post-login forms, and it works no matter how many tabs the
  * operator has open.
  *
- * The cookie is HttpOnly (the form doesn't need JS to read it; the server
- * embeds the value at render time), SameSite=Lax (matches the session
- * cookie), Secure, and Path=/ (covers every admin form, OAuth or otherwise).
+ * The cookie is HttpOnly: consumers receive the token value via either the
+ * server-rendered HTML form (cookie + embedded value, classic double-submit)
+ * or via the JSON body of `/api/me` (cookie alongside body — same pattern,
+ * just JSON instead of HTML). Neither path needs JS to read the cookie
+ * directly. SameSite=Lax (matches the session cookie), Secure, and Path=/
+ * (covers every admin form, OAuth flow, and `/api/me` consumer).
  *
  * Token entropy: 32 random bytes, base64url-encoded — same shape as session
  * IDs. No HMAC needed: the value is opaque to the client and only ever

package/src/help.ts

@@ -44,9 +44,9 @@ Services:
 What it does:
   1. bun add -g @openparachute/<service>[@<tag>]
   2. run any service-specific init (e.g. \`parachute-vault init\`)
-  3. assign a canonical port (1939–1949) and write \`PORT=<port>\` into
-     \`~/.parachute/<service>/.env\`. Idempotent — an existing PORT wins, so
-     re-installs and operator-edited ports survive across upgrades.
+  3. assign a canonical port (1939–1949) and reflect it in
+     \`~/.parachute/services.json\` — the single source of truth at boot
+     (services follow a 4-tier resolvePort ladder; services.json wins).
   4. verify the service registered itself in ~/.parachute/services.json
   5. for scribe in a TTY: prompt for transcription provider + API key
      (or take \`--scribe-provider\` / \`--scribe-key\`)
@@ -124,7 +124,7 @@ Examples:
 }
 
 export function statusHelp(): string {
-  return `parachute status — show installed services, process state, and health
+  return `parachute status — show installed services, process state, health, install source
 
 Usage:
   parachute status
@@ -133,22 +133,28 @@ What it does:
   Reads ~/.parachute/services.json. For each registered service:
     - checks PID file at ~/.parachute/<svc>/run/<svc>.pid → running/stopped
     - probes http://localhost:<port><health> (skipped for known-stopped processes)
+    - classifies the install source as bun-linked (local checkout) or npm
 
   Stopped services show "-" for health and don't count toward the exit
   code — they're an expected state after fresh install before \`parachute
   start\`. Running or externally-managed services that fail health checks
   do exit 1.
 
+  A "STALE: services.json cached … live package.json …" continuation line
+  appears under a row when a bun-linked service has been rebuilt but the
+  manifest's cached version hasn't caught up — re-install (\`parachute
+  install <pkg>\`) refreshes the row.
+
 Exit codes:
   0   all probed services healthy (or none running)
   1   one or more probed services unhealthy
 
 Example:
   $ parachute status
-  SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY
-  parachute-vault  1940  0.2.4    running  12345  2h 13m  ok      2ms
+  SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY  SOURCE
+  parachute-vault  1940  0.2.4    running  12345  2h 13m  ok      2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
-  parachute-notes  1942  0.0.1    stopped  -      -       -       -
+  parachute-notes  1942  0.0.1    stopped  -      -       -       -        npm (0.3.15-rc.1)
     → http://127.0.0.1:1942/notes
 `;
 }

package/src/hub-db.ts

@@ -130,6 +130,69 @@ const MIGRATIONS: readonly Migration[] = [
       CREATE INDEX tokens_family ON tokens (family_id) WHERE family_id IS NOT NULL;
     `,
   },
+  {
+    version: 6,
+    sql: `
+      -- Token registry generalization (closes hub#212 Phase 1). Until v6 the
+      -- tokens table only held OAuth refresh tokens; v6 generalizes it to a
+      -- single registry across every issued JWT class (refresh, access,
+      -- operator, mint-token). Three structural changes:
+      --
+      --   1. user_id becomes NULLABLE. OAuth-issued rows still set it to the
+      --      caller's user (canonical identity field). CLI-minted /
+      --      operator-minted rows leave user_id NULL and put the operator/
+      --      service name in the new \`subject\` column.
+      --   2. Three new columns: \`permissions\` (JSON, custom claim per
+      --      auth-architecture-shape.md §11.3), \`created_via\` (provenance
+      --      tag: oauth_refresh / cli_mint / operator_mint), \`subject\`
+      --      (non-user identity for service / operator mints).
+      --   3. Existing rows backfill \`created_via='oauth_refresh'\` because
+      --      the table was OAuth-refresh-only before v6.
+      --
+      -- SQLite has no ALTER COLUMN to drop NOT NULL, so we use the
+      -- recreate-and-rename pattern. Inside the migration transaction the
+      -- whole swap is atomic; concurrent reads (there are none — hub is
+      -- single-writer) wouldn't see a half-state. FKs from tokens → users
+      -- stay enforced for non-NULL user_id values; nothing references
+      -- tokens, so the drop is safe.
+      CREATE TABLE tokens_new (
+        jti TEXT PRIMARY KEY,
+        user_id TEXT REFERENCES users(id),
+        client_id TEXT NOT NULL,
+        scopes TEXT NOT NULL,
+        refresh_token_hash TEXT,
+        family_id TEXT,
+        expires_at TEXT NOT NULL,
+        revoked_at TEXT,
+        created_at TEXT NOT NULL,
+        permissions TEXT,
+        created_via TEXT NOT NULL DEFAULT 'oauth_refresh',
+        subject TEXT
+      );
+      INSERT INTO tokens_new (
+        jti, user_id, client_id, scopes, refresh_token_hash, family_id,
+        expires_at, revoked_at, created_at,
+        permissions, created_via, subject
+      )
+      SELECT
+        jti, user_id, client_id, scopes, refresh_token_hash, family_id,
+        expires_at, revoked_at, created_at,
+        NULL, 'oauth_refresh', NULL
+      FROM tokens;
+      DROP TABLE tokens;
+      ALTER TABLE tokens_new RENAME TO tokens;
+      -- Recreate indexes (DROP TABLE took them with it).
+      CREATE INDEX tokens_user ON tokens (user_id) WHERE user_id IS NOT NULL;
+      CREATE INDEX tokens_active_refresh ON tokens (refresh_token_hash)
+        WHERE refresh_token_hash IS NOT NULL AND revoked_at IS NULL;
+      CREATE INDEX tokens_family ON tokens (family_id) WHERE family_id IS NOT NULL;
+      -- New: revocation list endpoint queries on (revoked_at, expires_at).
+      CREATE INDEX tokens_revoked ON tokens (revoked_at)
+        WHERE revoked_at IS NOT NULL;
+      -- Subject lookup for non-user mints (operator name, service name).
+      CREATE INDEX tokens_subject ON tokens (subject) WHERE subject IS NOT NULL;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {