@openparachute/hub 0.3.0-rc.1

package/src/env-file.ts

@@ -0,0 +1,76 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Minimal `.env` round-tripping for files we own.
+ *
+ * Used by:
+ *   - auto-wire (writing SCRIBE_AUTH_TOKEN / SCRIBE_URL into vault .env)
+ *   - scribe provider setup (writing GROQ_API_KEY etc. into scribe .env)
+ *   - lifecycle.start (reading scribe .env values into the spawn env so the
+ *     process actually sees the keys it was configured with)
+ *
+ * Scope intentionally narrow:
+ *   - `KEY=value` lines (`=` is the first character, value is everything after)
+ *   - one-level surrounding quotes are stripped on read (single or double)
+ *   - everything else (comments, multiline, exports, escape sequences) is
+ *     preserved as-is on round-trip but not parsed as values
+ */
+
+export interface ParsedEnv {
+  /** Raw file lines preserved for round-trip writes (no trailing blank). */
+  lines: string[];
+  /** Parsed `KEY → value` pairs (quoted values returned unquoted). */
+  values: Record<string, string>;
+}
+
+export function parseEnvFileText(content: string): ParsedEnv {
+  const raw = content.length === 0 ? [] : content.split("\n");
+  // Drop a trailing empty string from a file that ends in "\n" so we don't
+  // double up newlines when we round-trip.
+  if (raw.length > 0 && raw[raw.length - 1] === "") raw.pop();
+  const values: Record<string, string> = {};
+  for (const line of raw) {
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq);
+    let value = line.slice(eq + 1);
+    if (
+      value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return { lines: raw, values };
+}
+
+export function parseEnvFile(path: string): ParsedEnv {
+  if (!existsSync(path)) return { lines: [], values: {} };
+  return parseEnvFileText(readFileSync(path, "utf8"));
+}
+
+export function readEnvFileValues(path: string): Record<string, string> {
+  return parseEnvFile(path).values;
+}
+
+export function upsertEnvLine(lines: string[], key: string, value: string): string[] {
+  const next = [...lines];
+  const prefix = `${key}=`;
+  const idx = next.findIndex((line) => line.startsWith(prefix));
+  if (idx >= 0) {
+    next[idx] = `${key}=${value}`;
+  } else {
+    next.push(`${key}=${value}`);
+  }
+  return next;
+}
+
+export function writeEnvFile(path: string, lines: readonly string[]): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${lines.join("\n")}\n`);
+  renameSync(tmp, path);
+}

package/src/expose-last-provider.ts

@@ -0,0 +1,71 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR } from "./config.ts";
+
+export const EXPOSE_LAST_PROVIDER_PATH = join(CONFIG_DIR, "expose-last-provider.json");
+
+export type ExposeProvider = "tailscale" | "cloudflare";
+
+export interface ExposeLastProvider {
+  version: 1;
+  provider: ExposeProvider;
+  /** ISO-8601 timestamp of the last selection — debugging only. */
+  writtenAt: string;
+}
+
+/**
+ * Persisted cross-invocation preference — remembers which provider the user
+ * picked last in the interactive flow so we can default to it next time.
+ *
+ * Unlike the live state files (`expose-state.json`, `cloudflared-state.json`)
+ * this is just a preference hint, so missing or corrupt content is not fatal:
+ * we return `undefined` and the caller falls back to its default. A stale file
+ * is never load-bearing — the worst case is a one-keystroke re-pick.
+ */
+export function readLastProvider(
+  path: string = EXPOSE_LAST_PROVIDER_PATH,
+): ExposeLastProvider | undefined {
+  if (!existsSync(path)) return undefined;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (!raw || typeof raw !== "object") return undefined;
+  const r = raw as Record<string, unknown>;
+  if (r.version !== 1) return undefined;
+  if (r.provider !== "tailscale" && r.provider !== "cloudflare") return undefined;
+  if (typeof r.writtenAt !== "string" || r.writtenAt.length === 0) return undefined;
+  return { version: 1, provider: r.provider, writtenAt: r.writtenAt };
+}
+
+export function writeLastProvider(
+  provider: ExposeProvider,
+  opts: { path?: string; now?: () => Date } = {},
+): void {
+  const path = opts.path ?? EXPOSE_LAST_PROVIDER_PATH;
+  const now = opts.now ?? (() => new Date());
+  if (!existsSync(dirname(path))) {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const record: ExposeLastProvider = {
+    version: 1,
+    provider,
+    writtenAt: now().toISOString(),
+  };
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+export function clearLastProvider(path: string = EXPOSE_LAST_PROVIDER_PATH): void {
+  if (existsSync(path)) unlinkSync(path);
+}

package/src/expose-state.ts

@@ -0,0 +1,125 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR } from "./config.ts";
+import type { ServeEntry } from "./tailscale/commands.ts";
+
+export const EXPOSE_STATE_PATH = join(CONFIG_DIR, "expose-state.json");
+
+export type ExposeMode = "path" | "subdomain";
+export type ExposeLayer = "tailnet" | "public";
+
+export interface ExposeState {
+  version: 1;
+  layer: ExposeLayer;
+  mode: ExposeMode;
+  canonicalFqdn: string;
+  port: number;
+  funnel: boolean;
+  entries: ServeEntry[];
+  /**
+   * Hub origin emitted when this exposure was brought up — the URL OAuth
+   * clients will see as the issuer. `parachute start vault` reads it to set
+   * PARACHUTE_HUB_ORIGIN so vault's OAuth metadata matches reality. Optional
+   * for pre-Phase-0 state files; writers always populate it.
+   */
+  hubOrigin?: string;
+}
+
+export class ExposeStateError extends Error {
+  override name = "ExposeStateError";
+}
+
+function validate(raw: unknown, path: string): ExposeState {
+  if (!raw || typeof raw !== "object") {
+    throw new ExposeStateError(`${path}: root must be an object`);
+  }
+  const r = raw as Record<string, unknown>;
+  if (r.version !== 1) {
+    throw new ExposeStateError(`${path}: unsupported version ${String(r.version)}`);
+  }
+  if (r.layer !== "tailnet" && r.layer !== "public") {
+    throw new ExposeStateError(`${path}: layer must be "tailnet" or "public"`);
+  }
+  if (r.mode !== "path" && r.mode !== "subdomain") {
+    throw new ExposeStateError(`${path}: mode must be "path" or "subdomain"`);
+  }
+  if (typeof r.canonicalFqdn !== "string" || r.canonicalFqdn.length === 0) {
+    throw new ExposeStateError(`${path}: canonicalFqdn must be a non-empty string`);
+  }
+  if (typeof r.port !== "number" || !Number.isInteger(r.port)) {
+    throw new ExposeStateError(`${path}: port must be an integer`);
+  }
+  if (typeof r.funnel !== "boolean") {
+    throw new ExposeStateError(`${path}: funnel must be a boolean`);
+  }
+  if (!Array.isArray(r.entries)) {
+    throw new ExposeStateError(`${path}: entries must be an array`);
+  }
+  if (r.hubOrigin !== undefined && typeof r.hubOrigin !== "string") {
+    throw new ExposeStateError(`${path}: hubOrigin must be a string if present`);
+  }
+  const entries: ServeEntry[] = r.entries.map((e, i) => {
+    if (!e || typeof e !== "object") {
+      throw new ExposeStateError(`${path} entries[${i}]: expected object`);
+    }
+    const entry = e as Record<string, unknown>;
+    const kind = entry.kind;
+    if (kind !== "proxy" && kind !== "file") {
+      throw new ExposeStateError(`${path} entries[${i}]: kind must be "proxy" or "file"`);
+    }
+    if (typeof entry.mount !== "string" || !entry.mount.startsWith("/")) {
+      throw new ExposeStateError(`${path} entries[${i}]: mount must start with "/"`);
+    }
+    if (typeof entry.target !== "string" || entry.target.length === 0) {
+      throw new ExposeStateError(`${path} entries[${i}]: target must be non-empty string`);
+    }
+    if (typeof entry.service !== "string" || entry.service.length === 0) {
+      throw new ExposeStateError(`${path} entries[${i}]: service must be non-empty string`);
+    }
+    return { kind, mount: entry.mount, target: entry.target, service: entry.service };
+  });
+  const state: ExposeState = {
+    version: 1,
+    layer: r.layer,
+    mode: r.mode,
+    canonicalFqdn: r.canonicalFqdn,
+    port: r.port,
+    funnel: r.funnel,
+    entries,
+  };
+  if (typeof r.hubOrigin === "string") state.hubOrigin = r.hubOrigin;
+  return state;
+}
+
+export function readExposeState(path: string = EXPOSE_STATE_PATH): ExposeState | undefined {
+  if (!existsSync(path)) return undefined;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new ExposeStateError(
+      `failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return validate(raw, path);
+}
+
+export function writeExposeState(state: ExposeState, path: string = EXPOSE_STATE_PATH): void {
+  if (!existsSync(dirname(path))) {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+export function clearExposeState(path: string = EXPOSE_STATE_PATH): void {
+  if (existsSync(path)) unlinkSync(path);
+}

package/src/help.ts

@@ -0,0 +1,279 @@
+import pkg from "../package.json" with { type: "json" };
+import { knownServices } from "./service-spec.ts";
+
+export function topLevelHelp(): string {
+  const services = knownServices().join(" | ");
+  return `parachute ${pkg.version} — top-level CLI for the Parachute ecosystem
+
+Usage:
+  parachute install <service>       install and register a service
+                                    services: ${services}
+  parachute status                  show installed services, process state, health
+  parachute start   [service]       start all services (or one) in the background
+  parachute stop    [service]       stop all services (or one) — SIGTERM then SIGKILL
+  parachute restart [service]       stop + start
+  parachute logs <service> [-f]     print service logs; -f to tail
+  parachute expose tailnet [off]    HTTPS across your tailnet
+  parachute expose public  [off]    HTTPS on the public internet (Funnel)
+  parachute migrate [--dry-run]     archive legacy files at ecosystem root
+  parachute auth <cmd>              identity (set password, manage 2FA)
+  parachute vault <args...>         vault-specific ops (tokens, 2fa, config, init,
+                                    etc.) — forwards to parachute-vault.
+                                    For lifecycle, use \`parachute start|stop|restart|logs vault\`.
+
+Flags:
+  --help, -h                        show this help (also per-subcommand: \`parachute <cmd> --help\`)
+  --version, -v                     print version
+`;
+}
+
+export function installHelp(): string {
+  return `parachute install — install and register a Parachute service
+
+Usage:
+  parachute install <service> [--tag <name>] [--no-start]
+  parachute install all       [--tag <name>] [--no-start]
+  parachute install scribe    [--scribe-provider <name>] [--scribe-key <key>]
+
+Services:
+  ${knownServices().join(", ")}
+  all                               install every known service in turn
+
+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.
+  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\`)
+  6. start the service in the background (idempotent — no-op if already up)
+
+Flags:
+  --tag <name>              npm dist-tag or exact version to install
+                            (e.g. \`--tag rc\` → \`bun add -g @openparachute/vault@rc\`)
+                            Skipped if the package is already \`bun link\`-ed locally.
+  --no-start                skip the post-install daemon start. For piped / CI
+                            installs that own their own process model.
+  --scribe-provider <name>  set scribe's transcription provider non-interactively.
+                            Known: parakeet-mlx (default), onnx-asr, whisper, groq, openai.
+                            Skips the interactive picker.
+  --scribe-key <key>        set the API key for the chosen provider non-interactively.
+                            Stored in ~/.parachute/scribe/.env. Only meaningful for
+                            cloud providers (groq → GROQ_API_KEY, openai → OPENAI_API_KEY).
+
+Examples:
+  parachute install vault                                   # installs, runs init, starts vault
+  parachute install notes                                   # installs and starts notes
+  parachute install scribe                                  # installs, prompts for provider, starts scribe
+  parachute install scribe --scribe-provider groq --scribe-key gsk_…
+                                                            # non-interactive scribe setup
+  parachute install vault --tag rc                          # pin to rc dist-tag
+  parachute install all --tag rc                            # bootstrap whole ecosystem to rc
+  parachute install vault --no-start                        # install without auto-starting (CI)
+
+Aliases:
+  lens → notes                      # accepted for one release cycle after
+                                    # the brief Lens rebrand was reverted on
+                                    # 2026-04-22; prints a rename notice.
+`;
+}
+
+export function statusHelp(): string {
+  return `parachute status — show installed services, process state, and health
+
+Usage:
+  parachute status
+
+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)
+
+  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.
+
+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
+    → http://127.0.0.1:1940/vault/default/mcp
+  parachute-notes  1942  0.0.1    stopped  -      -       -       -
+    → http://127.0.0.1:1942/notes
+`;
+}
+
+export function exposeHelp(): string {
+  return `parachute expose — route your services behind HTTPS on a network layer
+
+Usage:
+  parachute expose tailnet [off]
+  parachute expose public  [off]
+  parachute expose public  --cloudflare --domain <hostname>
+  parachute expose public  off --cloudflare
+
+Interactive:
+  Run in a terminal with no flags, \`parachute expose public\` walks you
+  through provider selection (Tailscale Funnel vs. Cloudflare Tunnel),
+  offers to install missing dependencies on macOS, and prompts for the
+  Cloudflare hostname when needed. Piped / non-TTY invocations keep the
+  scripted behavior: default to Tailscale, flags override.
+
+Layers:
+  tailnet    HTTPS across your tailnet (tailscale serve)
+  public     HTTPS on the public internet
+             - default: Tailscale Funnel (no domain needed, *.ts.net URL)
+             - --cloudflare + --domain: named Cloudflare tunnel on your own
+               domain (stable URL, free, no bandwidth caps)
+
+Tailscale and Cloudflare modes share no state. Either can be up without the
+other. Inside each mode, switching on/off is idempotent.
+
+Flags:
+  --hub-origin <url>    override the OAuth issuer URL advertised to clients
+                        (default: https://<fqdn> when exposed, else http://127.0.0.1:<hub-port>)
+  --cloudflare          use a named Cloudflare tunnel for the public layer
+                        (requires --domain)
+  --domain <hostname>   fully-qualified hostname to route through the tunnel
+                        (e.g. vault.example.com). The apex must be a zone on
+                        your Cloudflare account.
+
+Examples:
+  parachute expose tailnet                                 # tailnet HTTPS
+  parachute expose public                                  # Funnel: *.ts.net URL
+  parachute expose public off                              # stop the Funnel
+  parachute expose public --cloudflare --domain vault.example.com
+                                                           # stable URL via cloudflared
+  parachute expose public off --cloudflare                 # stop the cloudflared tunnel
+
+Tailscale Funnel constraints:
+  - HTTPS only on ports 443 / 8443 / 10000 per node. We pin to 443 and
+    path-route (vault at /vault/…, notes at /notes, …) so this cap never
+    becomes a constraint no matter how many services you install.
+  - Bandwidth caps on Tailscale's free tier — see https://tailscale.com/kb/1223/funnel.
+  - Subdomain-per-service needs the Tailscale Services feature (not yet).
+
+Cloudflare tunnel requirements (--cloudflare):
+  - \`cloudflared\` installed (macOS: \`brew install cloudflared\`).
+  - \`cloudflared tunnel login\` run once (browser flow) — drops a cert at
+    ~/.cloudflared/cert.pem.
+  - Apex of --domain is a Cloudflare zone on that account. Add at
+    https://dash.cloudflare.com → Add site (any registrar works).
+  - Only vault is currently routed. Multi-service ingress via Cloudflare is
+    deferred; use Funnel if you need hub + vault + notes on one exposure.
+`;
+}
+
+export function startHelp(): string {
+  return `parachute start — spawn services in the background
+
+Usage:
+  parachute start                   start every installed service
+  parachute start <service>         start just that one
+
+What it does:
+  For each target service, spawns its start command detached, redirects
+  stdout+stderr to ~/.parachute/<service>/logs/<service>.log, and records
+  the child PID at ~/.parachute/<service>/run/<service>.pid.
+
+  Idempotent: if the service is already running, no-op.
+  If a stale PID file exists (process died without cleanup), it's cleared
+  and the service starts fresh.
+
+Flags:
+  --hub-origin <url>    override PARACHUTE_HUB_ORIGIN passed to services
+                        (default: current expose-state hub origin, else loopback)
+
+Examples:
+  parachute start                   bring everything up
+  parachute start vault             just vault
+  parachute logs vault              watch what just started
+
+Start commands by service:
+  vault     parachute-vault serve
+  scribe    parachute-scribe serve
+  channel   parachute-channel daemon
+  notes     bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]>
+`;
+}
+
+export function stopHelp(): string {
+  return `parachute stop — stop running services cleanly
+
+Usage:
+  parachute stop                    stop every installed service
+  parachute stop <service>          stop just that one
+
+What it does:
+  Sends SIGTERM, waits up to 10s for a clean exit, then escalates to
+  SIGKILL if the process is still alive. Removes the PID file on success.
+
+  No-op if the service wasn't running.
+
+Examples:
+  parachute stop                    stop everything before sleep
+  parachute stop vault              just vault
+`;
+}
+
+export function restartHelp(): string {
+  return `parachute restart — stop then start
+
+Usage:
+  parachute restart                 restart every installed service
+  parachute restart <service>       restart just that one
+
+What it does:
+  Equivalent to \`parachute stop <svc> && parachute start <svc>\`.
+`;
+}
+
+export function logsHelp(): string {
+  return `parachute logs — print service logs
+
+Usage:
+  parachute logs <service>          print the last 200 lines
+  parachute logs <service> -f       tail the log (like \`tail -f\`)
+
+Log file:
+  ~/.parachute/<service>/logs/<service>.log
+
+If no log file exists yet, prints a hint to \`parachute start <service>\`.
+`;
+}
+
+export function migrateHelp(): string {
+  return `parachute migrate — archive legacy files at the ecosystem root
+
+Usage:
+  parachute migrate [--dry-run] [--yes]
+
+What it does:
+  Scans ~/.parachute/ for files and directories that don't belong to the
+  post-restructure layout. Recognized entries — per-service dirs
+  (vault/, notes/, scribe/, channel/, hub/; legacy lens/ also kept),
+  services.json,
+  expose-state.json, well-known/ — stay in place. Anything else (plus
+  known legacy cruft like daily.db, server.yaml) is moved under
+  ~/.parachute/.archive-<YYYY-MM-DD>/, never deleted.
+
+  Dotfiles at the root (.env, .DS_Store, prior .archive-* dirs) are left
+  alone.
+
+Flags:
+  --dry-run     print the plan; make no changes
+  --yes, -y     skip the confirmation prompt
+
+Examples:
+  parachute migrate --dry-run       see what would move, without touching anything
+  parachute migrate                 interactive sweep (prompts before acting)
+  parachute migrate --yes           sweep without prompting
+`;
+}