@openparachute/hub 0.7.4-rc.16 → 0.7.4-rc.18

package/src/__tests__/doctor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type CheckResult, type DoctorDeps, doctor } from "../commands/doctor.ts";
@@ -462,3 +462,294 @@ describe("doctor — version drift (cosmetic; never FAIL)", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Canonical-port-drift detection + `doctor --fix` repair (#267 doctor sub-item)
+// ---------------------------------------------------------------------------
+
+/** Write a services.json with the given rows (verbatim — for drift fixtures). */
+function writeManifestRows(manifestPath: string, services: unknown[]): void {
+  writeFileSync(manifestPath, JSON.stringify({ services }, null, 2));
+}
+
+/** Read services.json back as parsed rows for post-fix assertions. */
+function readRows(manifestPath: string): Record<string, unknown>[] {
+  const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    services: Record<string, unknown>[];
+  };
+  return parsed.services;
+}
+
+/** Run `doctor --fix`, capturing printed lines + exit code. */
+async function runFix(
+  h: Harness,
+  over: Partial<DoctorDeps> = {},
+  flags: { yes?: boolean } = {},
+): Promise<{ code: number; lines: string[] }> {
+  const lines: string[] = [];
+  const code = await doctor({
+    configDir: h.configDir,
+    manifestPath: h.manifestPath,
+    print: (l) => lines.push(l),
+    fix: true,
+    yes: flags.yes ?? false,
+    deps: healthyDeps(over),
+  });
+  return { code, lines };
+}
+
+describe("doctor — canonical-port-drift detection (read-only)", () => {
+  test("a non-canonical port + a duplicate-port pair → port-drift WARNs naming the services", async () => {
+    const h = makeHarness();
+    try {
+      // scribe drifted off 1943 onto 1944; agent also squats 1944 (a collision).
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/h",
+          version: "1",
+        },
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+      ]);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      expect(pd?.status).toBe("warn");
+      // Names the drifted service AND the colliding pair.
+      expect(pd?.detail).toContain("scribe");
+      expect(pd?.detail).toContain("1944");
+      expect(pd?.detail).toContain("parachute-scribe + parachute-agent");
+      expect(pd?.fix).toBe("parachute doctor --fix");
+      // Drift is advisory — exit stays 0 (a WARN, not a FAIL). The duplicate
+      // rows also trip modules-alive (both can't bind 1944) but that's expected
+      // for this fixture; we only assert on port-drift here.
+      expect([0, 1]).toContain(code);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a clean file → port-drift PASSES with no drift", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      expect(pd?.status).toBe("pass");
+      expect(pd?.detail).toContain("canonical");
+      expect(code).toBe(0);
+      expectNoUnexpectedNonPass(checks, []);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a third-party service with NO canonical port is not flagged", async () => {
+    const h = makeHarness();
+    try {
+      // An unknown module on a non-1939–1949 port — no canonical to drift from.
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/h",
+          version: "1",
+        },
+        { name: "acme-thing", port: 5000, paths: ["/acme"], health: "/h", version: "1" },
+      ]);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      expect(pd?.status).toBe("pass");
+      expect(code).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a named multi-vault row sharing 1940 is NOT flagged (drift or duplicate)", async () => {
+    const h = makeHarness();
+    try {
+      // A legit multi-vault setup: the canonical vault row plus a second named
+      // vault instance, both on 1940 (the documented carve-out). Neither should
+      // be flagged as drifted (named vault rows have no canonical port) nor as a
+      // duplicate-port collision (all-vault-on-1940 is by design).
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/h",
+          version: "1",
+        },
+        {
+          name: "parachute-vault-work",
+          port: 1940,
+          paths: ["/vault/work"],
+          health: "/h",
+          version: "1",
+        },
+      ]);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      // PASS (clean) — neither flagged as drifted nor as a duplicate collision.
+      expect(pd?.status).toBe("pass");
+      expect(pd?.detail).toContain("canonical");
+      expect(code).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("doctor --fix — canonical-port repair (confirm-gated, idempotent, non-tty-safe)", () => {
+  test("--fix on a clean file → 'no drift', exit 0, file unchanged (idempotent)", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      const before = readFileSync(h.manifestPath, "utf8");
+      const { code, lines } = await runFix(h, { isInteractive: () => true }, { yes: true });
+      expect(code).toBe(0);
+      expect(lines.join("\n").toLowerCase()).toContain("nothing to fix");
+      expect(readFileSync(h.manifestPath, "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix on an absent services.json (fresh install) → 'nothing to fix', exit 0", async () => {
+    const h = makeHarness();
+    try {
+      // No services.json at all — the truly-fresh case. --fix must NOT report a
+      // corrupt-file error; it's the idempotent no-op path.
+      const { code, lines } = await runFix(h, { isInteractive: () => false }, { yes: false });
+      expect(code).toBe(0);
+      expect(lines.join("\n").toLowerCase()).toContain("nothing to fix");
+      expect(lines.join("\n").toLowerCase()).not.toContain("can't read");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix --yes rewrites the drifted port to canonical + preserves other fields", async () => {
+    const h = makeHarness();
+    try {
+      // scribe drifted onto 1944; carries an optional displayName/tagline that
+      // must survive the rewrite.
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-scribe",
+          port: 1944,
+          paths: ["/scribe"],
+          health: "/scribe/health",
+          version: "0.7.4",
+          displayName: "Scribe",
+          tagline: "Local audio transcription.",
+          stripPrefix: true,
+        },
+      ]);
+      const { code, lines } = await runFix(h, {}, { yes: true });
+      expect(code).toBe(0);
+      expect(lines.join("\n")).toContain("→ :1943");
+      const rows = readRows(h.manifestPath);
+      const scribe = rows.find((r) => r.name === "parachute-scribe");
+      expect(scribe?.port).toBe(1943);
+      // Optional + unknown fields preserved verbatim.
+      expect(scribe?.displayName).toBe("Scribe");
+      expect(scribe?.tagline).toBe("Local audio transcription.");
+      expect(scribe?.stripPrefix).toBe(true);
+
+      // Re-run → idempotent: now clean, exit 0, nothing to fix.
+      const again = await runFix(h, {}, { yes: true });
+      expect(again.code).toBe(0);
+      expect(again.lines.join("\n").toLowerCase()).toContain("nothing to fix");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix in a TTY without --yes prompts; 'y' applies the rewrite", async () => {
+    const h = makeHarness();
+    try {
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+      ]);
+      const { code } = await runFix(
+        h,
+        { isInteractive: () => true, readLine: async () => "y" },
+        { yes: false },
+      );
+      expect(code).toBe(0);
+      expect(readRows(h.manifestPath).find((r) => r.name === "parachute-scribe")?.port).toBe(1943);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix in a TTY answered 'n' → aborts, exit non-zero, file UNCHANGED", async () => {
+    const h = makeHarness();
+    try {
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+      ]);
+      const before = readFileSync(h.manifestPath, "utf8");
+      const { code, lines } = await runFix(
+        h,
+        { isInteractive: () => true, readLine: async () => "n" },
+        { yes: false },
+      );
+      expect(code).not.toBe(0);
+      expect(lines.join("\n").toLowerCase()).toContain("unchanged");
+      expect(readFileSync(h.manifestPath, "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix in a NON-TTY without --yes → bails, exit non-zero, file UNCHANGED", async () => {
+    const h = makeHarness();
+    try {
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+      ]);
+      const before = readFileSync(h.manifestPath, "utf8");
+      const { code, lines } = await runFix(h, { isInteractive: () => false }, { yes: false });
+      expect(code).not.toBe(0);
+      expect(lines.join("\n")).toContain("--yes");
+      // The load-bearing guarantee: no write happened.
+      expect(readFileSync(h.manifestPath, "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix reports a duplicate-port collision but does not auto-resolve it", async () => {
+    const h = makeHarness();
+    try {
+      // Two services collide on 1944; neither is on its canonical slot. The
+      // diff fixes the canonical drift; the collision is reported, not guessed.
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+      ]);
+      const { code, lines } = await runFix(h, {}, { yes: true });
+      const text = lines.join("\n");
+      expect(text.toLowerCase()).toContain("shared by");
+      expect(text).toContain("parachute-scribe + parachute-agent");
+      // scribe → 1943 and agent → 1941 are both off 1944, so after the rewrite
+      // they no longer collide; fix applied, exit 0.
+      expect(code).toBe(0);
+      const rows = readRows(h.manifestPath);
+      expect(rows.find((r) => r.name === "parachute-scribe")?.port).toBe(1943);
+      expect(rows.find((r) => r.name === "parachute-agent")?.port).toBe(1941);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/cli.ts

@@ -581,15 +581,26 @@ async function main(argv: string[]): Promise<number> {
         return 0;
       }
       const json = rest.includes("--json");
-      const unknown = rest.find((a) => a !== "--json");
+      const fix = rest.includes("--fix");
+      const yes = rest.includes("--yes") || rest.includes("-y");
+      const known = new Set(["--json", "--fix", "--yes", "-y"]);
+      const unknown = rest.find((a) => !known.has(a));
       if (unknown !== undefined) {
         console.error(`parachute doctor: unknown argument "${unknown}"`);
-        console.error("usage: parachute doctor [--json]");
+        console.error("usage: parachute doctor [--json] [--fix [--yes]]");
+        return 1;
+      }
+      if (json && fix) {
+        console.error("parachute doctor: --json and --fix are mutually exclusive");
+        return 1;
+      }
+      if (yes && !fix) {
+        console.error("parachute doctor: --yes has no effect without --fix");
         return 1;
       }
       const mod = await loadCommand("doctor", () => import("./commands/doctor.ts"));
       if (!mod) return 1;
-      return await mod.doctor({ json });
+      return await mod.doctor({ json, fix, yes });
     }
 
     case "expose": {

package/src/clients.ts

@@ -238,6 +238,135 @@ export function deleteClient(db: Database, clientId: string): boolean {
   })();
 }
 
+/**
+ * Default reaper age threshold: 30 days. A client registered more recently
+ * than this is NEVER reaped — it may be mid-first-OAuth-flow (registered →
+ * user is on the consent screen → no grant/token/code written yet). The
+ * threshold buys generous headroom over the worst-case human consent latency.
+ */
+export const DEFAULT_REAP_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** A client the reaper has proven dead. Carries enough to display a dry-run row. */
+export interface ReapableClient {
+  clientId: string;
+  clientName: string | null;
+  registeredAt: string;
+  status: ClientStatus;
+  /** Whole days since registration, floored. For the dry-run/`--json` display. */
+  ageDays: number;
+}
+
+export interface FindReapableOpts {
+  /** Reap only clients older than this many ms. Defaults to 30 days. */
+  olderThanMs?: number;
+  /** Injectable clock — all age + liveness comparisons use this. */
+  now?: () => Date;
+}
+
+/**
+ * Find OAuth clients that are PROVABLY DEAD and safe to garbage-collect.
+ *
+ * THE SAFETY GATE (maximally conservative — see hub#640). DCR churn (Notes /
+ * Claude mint a fresh `client_id` per reconnect) accumulates dead `clients`
+ * rows; this reaps them. But a reaper that deletes a LIVE client breaks a
+ * user's active connection, and we've been bitten by over-eager pruning
+ * before (a derived-key divergence wrongly pruned still-wanted grants). So a
+ * client is reapable IFF **ALL** of:
+ *
+ *   1. ZERO rows in `grants` — no standing consent. A grant means the user
+ *      approved this client; never touch it.
+ *   2. ZERO live tokens — no row in `tokens` with `expires_at > now AND
+ *      revoked_at IS NULL`. A live token means an active session.
+ *   3. ZERO live auth_codes — no row in `auth_codes` with `expires_at > now`.
+ *      A live code means an OAuth exchange is in flight RIGHT NOW.
+ *   4. `registered_at` older than `olderThanMs` (default 30d) — a freshly-
+ *      registered client may be mid-first-flow before any of the above rows
+ *      land.
+ *
+ * This reaps abandoned-never-consented `pending` DCR registrations and fully-
+ * dead (revoked/expired) clients, and NEVER a client with a live grant, live
+ * token, or in-flight code. Pure read — touches nothing. `reapClient` does the
+ * deletion.
+ *
+ * Implemented as a single `NOT EXISTS` SELECT so the gate is evaluated
+ * atomically per row against one consistent DB snapshot (no read-modify-write
+ * window where a token could land between the check and a later delete — the
+ * delete re-derives nothing; callers re-run the gate, see below).
+ */
+export function findReapableClients(db: Database, opts: FindReapableOpts = {}): ReapableClient[] {
+  const now = opts.now?.() ?? new Date();
+  const olderThanMs = opts.olderThanMs ?? DEFAULT_REAP_AGE_MS;
+  const nowIso = now.toISOString();
+  // Registered strictly before this cutoff to qualify on age (condition 4).
+  const cutoffIso = new Date(now.getTime() - olderThanMs).toISOString();
+
+  const rows = db
+    .query<Row, [string, string, string]>(
+      `SELECT c.* FROM clients c
+       WHERE c.registered_at < ?1
+         AND NOT EXISTS (SELECT 1 FROM grants g WHERE g.client_id = c.client_id)
+         AND NOT EXISTS (
+           SELECT 1 FROM tokens t
+           WHERE t.client_id = c.client_id
+             AND t.revoked_at IS NULL
+             AND t.expires_at > ?2
+         )
+         AND NOT EXISTS (
+           SELECT 1 FROM auth_codes a
+           WHERE a.client_id = c.client_id
+             AND a.expires_at > ?3
+         )
+       ORDER BY c.registered_at`,
+    )
+    .all(cutoffIso, nowIso, nowIso);
+
+  return rows.map((r) => {
+    const client = rowToClient(r);
+    const ageMs = now.getTime() - new Date(client.registeredAt).getTime();
+    return {
+      clientId: client.clientId,
+      clientName: client.clientName,
+      registeredAt: client.registeredAt,
+      status: client.status,
+      ageDays: Math.floor(ageMs / (24 * 60 * 60 * 1000)),
+    };
+  });
+}
+
+/**
+ * Garbage-collect a single PROVABLY-DEAD client. Wraps the `deleteClient`
+ * cascade (grants + auth_codes + client row) AND a `DELETE FROM tokens` for
+ * the same client_id, all in ONE transaction.
+ *
+ * Why also delete tokens here when `deleteClient` deliberately leaves them?
+ * `deleteClient` is the general deregistration path — it can run against a
+ * client that still has LIVE tokens (an operator force-removing an app mid-
+ * session), so it leaves the `tokens` rows to expire on their own (they carry
+ * no FK to `clients`). The reaper, by contrast, only ever runs on a client the
+ * gate has PROVEN has no live tokens — every remaining `tokens` row for it is
+ * already expired or revoked (dead). Deleting them completes the GC instead of
+ * leaving dead registry rows behind forever. Callers MUST pass only client_ids
+ * returned by `findReapableClients` (the safety gate); see the CLI's reap loop.
+ *
+ * TOCTOU note: `reapClient` does NOT re-check the gate — it trusts the caller's
+ * list. There is a theoretical window where a grant/token lands between the
+ * `findReapableClients` snapshot and this delete, reaping a client that just
+ * went live. On the single-operator hub this is cosmetically impossible: the
+ * OAuth flow that would create a grant runs synchronously on the same SQLite
+ * connection and never races a CLI invocation. Re-running `findReapableClients`
+ * immediately before each call would close the window at the cost of N extra
+ * round-trips; not worth it under the current trust model.
+ */
+export function reapClient(db: Database, clientId: string): boolean {
+  return db.transaction(() => {
+    // Dead token rows first — the gate proved none are live; this completes
+    // the GC (deleteClient leaves tokens alone for the general delete path).
+    db.prepare("DELETE FROM tokens WHERE client_id = ?").run(clientId);
+    // The cascade: auth_codes + grants (both dead per the gate) + the client.
+    return deleteClient(db, clientId);
+  })();
+}
+
 /**
  * Returns the registered redirect URI matching `candidate` exactly, or throws.
  * RFC 8252 + 6749 require exact-match for redirect URIs (no wildcards, no