@openparachute/hub 0.3.0-rc.1

package/src/notes-serve.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env bun
+
+/**
+ * Tiny static-file server for the @openparachute/notes PWA bundle.
+ *
+ * Notes is a SPA — no backend of its own. `parachute start notes` invokes
+ * this shim with the installed `dist/` path so the PWA is served at a
+ * known port and can be reverse-proxied by `parachute expose` alongside
+ * the other services.
+ *
+ * Invoked as:
+ *   bun <this-file> --port <n> [--dist <path>] [--mount <prefix>]
+ *
+ * `--mount` (default `/notes`) is the path prefix the reverse proxy hands
+ * us. We strip it before resolving against `dist/` so a request for
+ * `/notes/sw.js` reads `{dist}/sw.js` rather than the nonexistent
+ * `{dist}/notes/sw.js`. Without the strip, the SW + .webmanifest both
+ * SPA-fall-back to index.html with content-type text/html, and the PWA
+ * install prompt never fires. Pass `--mount ""` (or `--mount /`) when the
+ * bundle is served at the origin root.
+ *
+ * If --dist is omitted, we resolve @openparachute/notes's dist directory
+ * via Bun.resolveSync. If that fails (package not installed globally, or
+ * package doesn't ship dist/), exit 1 with a clear error.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+interface Args {
+  port: number;
+  dist?: string;
+  mount: string;
+}
+
+function parseArgs(argv: string[]): Args {
+  let port = 5173;
+  let dist: string | undefined;
+  let mount = "/notes";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--port") {
+      const v = argv[++i];
+      if (!v) throw new Error("--port requires a value");
+      const n = Number.parseInt(v, 10);
+      if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+        throw new Error(`--port must be 1..65535, got "${v}"`);
+      }
+      port = n;
+    } else if (a === "--dist") {
+      const v = argv[++i];
+      if (!v) throw new Error("--dist requires a value");
+      dist = resolve(v);
+    } else if (a === "--mount") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error("--mount requires a value");
+      mount = normalizeMount(v);
+    } else {
+      throw new Error(`unknown argument: ${a}`);
+    }
+  }
+  return { port, dist, mount };
+}
+
+export function normalizeMount(raw: string): string {
+  if (raw === "" || raw === "/") return "";
+  return raw.replace(/\/+$/, "");
+}
+
+function resolveNotesDist(): string {
+  const pkgPath = Bun.resolveSync("@openparachute/notes/package.json", process.cwd());
+  const root = dirname(pkgPath);
+  const dist = join(root, "dist");
+  if (!existsSync(dist)) {
+    throw new Error(
+      `@openparachute/notes is installed but has no dist/ directory at ${dist}. The package may not ship a prebuilt bundle — ask the notes maintainer to add a prepublishOnly build step.`,
+    );
+  }
+  return dist;
+}
+
+function mimeFor(path: string): string | undefined {
+  // Bun.file infers MIME from extension but doesn't know .webmanifest;
+  // without this the PWA install prompt sees text/html and bails.
+  if (path.endsWith(".webmanifest")) return "application/manifest+json";
+  return undefined;
+}
+
+export function notesFetch(dist: string, mount: string): (req: Request) => Response {
+  const indexHtml = join(dist, "index.html");
+  const spaShell = () =>
+    new Response(Bun.file(indexHtml), {
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+
+  return (req) => {
+    const url = new URL(req.url);
+    let pathname = url.pathname;
+    if (mount && (pathname === mount || pathname.startsWith(`${mount}/`))) {
+      pathname = pathname.slice(mount.length) || "/";
+    }
+    if (pathname === "/" || pathname.endsWith("/")) {
+      return spaShell();
+    }
+    const filePath = join(dist, decodeURIComponent(pathname));
+    if (!filePath.startsWith(dist)) {
+      return new Response("forbidden", { status: 403 });
+    }
+    if (existsSync(filePath)) {
+      const file = Bun.file(filePath);
+      const mime = mimeFor(filePath);
+      return new Response(file, mime ? { headers: { "content-type": mime } } : undefined);
+    }
+    return spaShell();
+  };
+}
+
+if (import.meta.main) {
+  const { port, dist: distArg, mount } = parseArgs(process.argv.slice(2));
+
+  let dist: string;
+  try {
+    dist = distArg ?? resolveNotesDist();
+  } catch (err) {
+    console.error(`parachute-notes-serve: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  Bun.serve({
+    port,
+    fetch: notesFetch(dist, mount),
+  });
+
+  console.log(`notes static-serve listening on :${port} (dist=${dist}, mount=${mount || "/"})`);
+}

package/src/port-assign.ts

@@ -0,0 +1,125 @@
+import { parseEnvFile, upsertEnvLine, writeEnvFile } from "./env-file.ts";
+import { CANONICAL_PORT_MAX, CANONICAL_PORT_MIN, PORT_RESERVATIONS } from "./service-spec.ts";
+
+/**
+ * The CLI is the port authority for Parachute services. At install time it
+ * picks a port for each service, writes `PORT=<port>` into the service's
+ * `~/.parachute/<svc>/.env`, and reflects the chosen port in services.json.
+ * Services keep a compiled-in fallback (e.g. vault → 1940) so a stand-alone
+ * `bun run` still works, but the CLI's PORT env var wins on installs it
+ * manages.
+ *
+ * Why up-front assignment instead of detect-on-collision-at-boot:
+ *   - Two services racing to bind the same port produces an opaque "address in
+ *     use" deep inside one of them. Assigning at install lets the CLI keep
+ *     a single coherent picture of who owns what.
+ *   - The hub's reverse-proxy targets are computed from services.json. If a
+ *     service silently falls back to a different port at runtime, the hub
+ *     proxies to a dead port and the user sees a 502 with no explanation.
+ *   - Re-installs stay idempotent: the existing `PORT=` in .env wins, so a
+ *     user who edited their port keeps it across upgrades.
+ */
+
+export type AssignmentSource = "canonical" | "fallback-in-range" | "fallback-out-of-range";
+
+export interface PortAssignment {
+  readonly port: number;
+  readonly source: AssignmentSource;
+  /** Set when the canonical slot wasn't available — caller logs it. */
+  readonly warning?: string;
+}
+
+/**
+ * Pure: pick a port given the canonical default and the set of ports we
+ * already know to be taken.
+ *
+ *   1. Prefer canonical (the slot the service expects, e.g. vault → 1940).
+ *   2. On collision, walk the unassigned canonical reservations (1944..1949
+ *      today) — keeps the install inside the Parachute range so other
+ *      software doesn't accidentally land on the same port.
+ *   3. Range exhausted: walk past CANONICAL_PORT_MAX. The warning lets the
+ *      caller surface it; the install still proceeds.
+ *
+ * Third-party services (no canonical slot) skip step 1 and start at step 2.
+ */
+export function assignPort(
+  canonical: number | undefined,
+  occupied: Iterable<number>,
+): PortAssignment {
+  const taken = new Set(occupied);
+
+  if (canonical !== undefined && !taken.has(canonical)) {
+    return { port: canonical, source: "canonical" };
+  }
+
+  for (const reservation of PORT_RESERVATIONS) {
+    if (reservation.status !== "reserved") continue;
+    if (taken.has(reservation.port)) continue;
+    const warning =
+      canonical !== undefined
+        ? `canonical port ${canonical} is in use; assigned ${reservation.port} from the unassigned Parachute range.`
+        : `assigned port ${reservation.port} from the unassigned Parachute range (no canonical slot for this service).`;
+    return { port: reservation.port, source: "fallback-in-range", warning };
+  }
+
+  let p = CANONICAL_PORT_MAX + 1;
+  while (taken.has(p) && p < 65536) p++;
+  return {
+    port: p,
+    source: "fallback-out-of-range",
+    warning: `Parachute canonical range (${CANONICAL_PORT_MIN}–${CANONICAL_PORT_MAX}) is full; assigned ${p} outside the range — may conflict with other software.`,
+  };
+}
+
+export interface AssignServicePortOpts {
+  /** Path to the service's `.env` file. */
+  readonly envPath: string;
+  /** Canonical default for this service, or undefined for third-party. */
+  readonly canonical?: number;
+  /** Ports we already know to be taken. */
+  readonly occupied: Iterable<number>;
+}
+
+export interface AssignServicePortResult {
+  readonly port: number;
+  /** "preserved" when an existing PORT in .env was kept; otherwise the
+   *  source from `assignPort`. */
+  readonly source: "preserved" | AssignmentSource;
+  /** True when we wrote PORT into .env on this call. */
+  readonly written: boolean;
+  /** Warning to surface to the user, if any. */
+  readonly warning?: string;
+}
+
+/**
+ * Reconcile a service's PORT with its `.env`. Idempotent:
+ *   - If PORT is already set in .env, preserve it (`source: "preserved"`).
+ *     Re-installs and user-edited ports survive across upgrades.
+ *   - Otherwise call `assignPort` and write `PORT=<port>` into .env.
+ *
+ * Reads only the value of PORT from .env; everything else is round-tripped
+ * untouched via `parseEnvFile` / `upsertEnvLine` / `writeEnvFile`.
+ */
+export function assignServicePort(opts: AssignServicePortOpts): AssignServicePortResult {
+  const env = parseEnvFile(opts.envPath);
+  const existing = env.values.PORT;
+  if (existing !== undefined && /^[1-9]\d{0,4}$/.test(existing)) {
+    const port = Number(existing);
+    if (port > 0 && port < 65536) {
+      return { port, source: "preserved", written: false };
+    }
+  }
+
+  const assignment = assignPort(opts.canonical, opts.occupied);
+  const nextLines = upsertEnvLine(env.lines, "PORT", String(assignment.port));
+  writeEnvFile(opts.envPath, nextLines);
+  const result: AssignServicePortResult = {
+    port: assignment.port,
+    source: assignment.source,
+    written: true,
+  };
+  if (assignment.warning) {
+    return { ...result, warning: assignment.warning };
+  }
+  return result;
+}

package/src/process-state.ts

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR } from "./config.ts";
+
+/**
+ * Per-service state lives under `<configDir>/<svc>/...`. `svc` is the
+ * short name (`vault`, `notes`, `scribe`, `channel`) so paths stay tidy —
+ * `~/.parachute/vault/run/vault.pid` rather than `parachute-vault/run/…`.
+ *
+ * The single source of truth for whether a service is running is
+ * `pid file present` + `process.kill(pid, 0)` succeeds. A stale PID file
+ * (process died without cleanup) reads as stopped; writers of the PID
+ * file own removing it on clean shutdown.
+ */
+
+export function serviceDir(svc: string, configDir: string = CONFIG_DIR): string {
+  return join(configDir, svc);
+}
+
+export function runDir(svc: string, configDir: string = CONFIG_DIR): string {
+  return join(serviceDir(svc, configDir), "run");
+}
+
+export function logsDir(svc: string, configDir: string = CONFIG_DIR): string {
+  return join(serviceDir(svc, configDir), "logs");
+}
+
+export function pidPath(svc: string, configDir: string = CONFIG_DIR): string {
+  return join(runDir(svc, configDir), `${svc}.pid`);
+}
+
+export function logPath(svc: string, configDir: string = CONFIG_DIR): string {
+  return join(logsDir(svc, configDir), `${svc}.log`);
+}
+
+export function readPid(svc: string, configDir: string = CONFIG_DIR): number | undefined {
+  const p = pidPath(svc, configDir);
+  if (!existsSync(p)) return undefined;
+  const raw = readFileSync(p, "utf8").trim();
+  const n = Number.parseInt(raw, 10);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
+export function writePid(svc: string, pid: number, configDir: string = CONFIG_DIR): void {
+  const p = pidPath(svc, configDir);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, `${pid}\n`);
+}
+
+export function clearPid(svc: string, configDir: string = CONFIG_DIR): void {
+  const p = pidPath(svc, configDir);
+  if (existsSync(p)) rmSync(p, { force: true });
+}
+
+export function ensureLogPath(svc: string, configDir: string = CONFIG_DIR): string {
+  const p = logPath(svc, configDir);
+  mkdirSync(dirname(p), { recursive: true });
+  return p;
+}
+
+export type AliveFn = (pid: number) => boolean;
+
+export const defaultAlive: AliveFn = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Three-state rather than two so we don't lie about services we can't see:
+ *
+ * - `running` — PID file present, `kill(pid, 0)` succeeds.
+ * - `stopped` — PID file present, process gone (stale pidfile, or cleanly shut down).
+ * - `unknown` — no PID file. Service may be externally managed (user ran
+ *   `parachute-vault serve` directly, or legacy launchd-era). Don't claim stopped.
+ */
+export interface ProcessState {
+  status: "running" | "stopped" | "unknown";
+  pid?: number;
+  /** mtime of the PID file — a stand-in for "process start time". */
+  startedAt?: Date;
+}
+
+export function processState(
+  svc: string,
+  configDir: string = CONFIG_DIR,
+  alive: AliveFn = defaultAlive,
+): ProcessState {
+  const pid = readPid(svc, configDir);
+  if (pid === undefined) return { status: "unknown" };
+  if (!alive(pid)) return { status: "stopped", pid };
+  const p = pidPath(svc, configDir);
+  const startedAt = existsSync(p) ? statSync(p).mtime : undefined;
+  return { status: "running", pid, startedAt };
+}
+
+/** Human-friendly uptime like "2h 13m" / "4d 6h" / "45s". */
+export function formatUptime(startedAt: Date, now: Date = new Date()): string {
+  const ms = Math.max(0, now.getTime() - startedAt.getTime());
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}

package/src/scribe-config.ts

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseEnvFile, upsertEnvLine, writeEnvFile } from "./env-file.ts";
+
+/**
+ * Reads / merges scribe's transcription provider into
+ * `<configDir>/scribe/config.json` and writes the corresponding API key (when
+ * the chosen provider needs one) into `<configDir>/scribe/.env`.
+ *
+ * Both files are merged in place so we never clobber unrelated keys — auto-wire
+ * already owns `auth.required_token` in the same config, and operators
+ * sometimes hand-edit other top-level blocks.
+ */
+
+/**
+ * Transcription providers scribe ships with today (per `parachute-scribe`
+ * 0.x README). Source-of-truth is intentionally hand-maintained on the CLI
+ * side: the install prompt needs a curated, ordered list with platform
+ * caveats for each option, which scribe's runtime registry doesn't surface.
+ *
+ * Drift caught by the test that asserts the keys here match scribe's
+ * `availableProviders().transcription`.
+ */
+export const SCRIBE_PROVIDERS = [
+  {
+    key: "parakeet-mlx",
+    label: "parakeet-mlx",
+    blurb: "local, Apple Silicon, fastest — requires `parakeet-mlx` binary on PATH",
+    apiKeyEnv: undefined,
+  },
+  {
+    key: "onnx-asr",
+    label: "onnx-asr",
+    blurb: "local, cross-platform (Sherpa-ONNX)",
+    apiKeyEnv: undefined,
+  },
+  {
+    key: "whisper",
+    label: "whisper",
+    blurb:
+      "local, any platform — requires `whisper-ctranslate2` (`pip install whisper-ctranslate2`)",
+    apiKeyEnv: undefined,
+  },
+  {
+    key: "groq",
+    label: "groq",
+    blurb: "cloud, generous free tier, very fast",
+    apiKeyEnv: "GROQ_API_KEY",
+  },
+  {
+    key: "openai",
+    label: "openai",
+    blurb: "cloud, paid, reference Whisper API",
+    apiKeyEnv: "OPENAI_API_KEY",
+  },
+] as const;
+
+export type ScribeProviderKey = (typeof SCRIBE_PROVIDERS)[number]["key"];
+
+/** Default provider scribe falls back to when the config doesn't pick one. */
+export const SCRIBE_DEFAULT_PROVIDER: ScribeProviderKey = "parakeet-mlx";
+
+export function isKnownScribeProvider(value: string): value is ScribeProviderKey {
+  return SCRIBE_PROVIDERS.some((p) => p.key === value);
+}
+
+export function apiKeyEnvFor(provider: ScribeProviderKey): string | undefined {
+  return SCRIBE_PROVIDERS.find((p) => p.key === provider)?.apiKeyEnv;
+}
+
+export function scribeConfigPath(configDir: string): string {
+  return join(configDir, "scribe", "config.json");
+}
+
+export function scribeEnvPath(configDir: string): string {
+  return join(configDir, "scribe", ".env");
+}
+
+export interface ScribeProviderState {
+  provider: string | undefined;
+  /** True when the file exists; false on a fresh install. */
+  configExists: boolean;
+}
+
+export function readScribeProviderState(configDir: string): ScribeProviderState {
+  const path = scribeConfigPath(configDir);
+  if (!existsSync(path)) return { provider: undefined, configExists: false };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const provider =
+      parsed && typeof parsed === "object" && !Array.isArray(parsed) && parsed.transcribe
+        ? typeof parsed.transcribe.provider === "string"
+          ? parsed.transcribe.provider
+          : undefined
+        : undefined;
+    return { provider, configExists: true };
+  } catch {
+    // Malformed JSON — treat as empty so the writer can repair it. The auth
+    // block belongs to auto-wire; if it's broken, downstream auto-wire will
+    // overwrite when it next runs anyway.
+    return { provider: undefined, configExists: true };
+  }
+}
+
+/**
+ * Merge `transcribe.provider = <provider>` into the scribe config.json,
+ * preserving any other top-level keys (notably `auth.required_token` written
+ * by auto-wire).
+ */
+export function writeScribeProvider(configDir: string, provider: ScribeProviderKey): void {
+  const path = scribeConfigPath(configDir);
+  mkdirSync(dirname(path), { recursive: true });
+  let current: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        current = parsed as Record<string, unknown>;
+      }
+    } catch {
+      // Malformed → overwrite, same convention as auto-wire's writeScribeConfig.
+    }
+  }
+  const existingTranscribe =
+    typeof current.transcribe === "object" &&
+    current.transcribe !== null &&
+    !Array.isArray(current.transcribe)
+      ? (current.transcribe as Record<string, unknown>)
+      : {};
+  const next = {
+    ...current,
+    transcribe: { ...existingTranscribe, provider },
+  };
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/**
+ * Idempotent upsert of a single `KEY=value` into `<configDir>/scribe/.env`.
+ * Used for the API-key prompt result. Other lines (auto-wire keys, manual
+ * operator edits) are preserved.
+ */
+export function writeScribeApiKey(configDir: string, envKey: string, value: string): void {
+  const path = scribeEnvPath(configDir);
+  const parsed = parseEnvFile(path);
+  const lines = upsertEnvLine(parsed.lines, envKey, value);
+  writeEnvFile(path, lines);
+}