@openparachute/hub 0.3.0-rc.1

package/src/commands/lifecycle.ts

@@ -0,0 +1,324 @@
+import { existsSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { readEnvFileValues } from "../env-file.ts";
+import { readExposeState } from "../expose-state.ts";
+import { readHubPort } from "../hub-control.ts";
+import { HUB_ORIGIN_ENV, deriveHubOrigin } from "../hub-origin.ts";
+import {
+  type AliveFn,
+  clearPid,
+  defaultAlive,
+  ensureLogPath,
+  logPath as logPathFor,
+  processState,
+  readPid,
+  writePid,
+} from "../process-state.ts";
+import { getSpec, knownServices, shortNameForManifest } from "../service-spec.ts";
+import { type ServiceEntry, readManifest } from "../services-manifest.ts";
+
+/**
+ * Tiny seam over `Bun.spawn` for lifecycle tests. The real spawner opens the
+ * log file, appends stdout+stderr to it, and `unref()`s the child so parent
+ * exit doesn't bring it down.
+ *
+ * `env`, when provided, is merged into the child's environment on top of the
+ * parent's — today's only caller is `start`, which injects
+ * PARACHUTE_HUB_ORIGIN so vault's OAuth issuer matches the hub URL.
+ */
+export interface Spawner {
+  spawn(cmd: readonly string[], logFile: string, env?: Record<string, string>): number;
+}
+
+export const defaultSpawner: Spawner = {
+  spawn(cmd, logFile, env) {
+    const fd = openSync(logFile, "a");
+    const proc = Bun.spawn([...cmd], {
+      stdio: ["ignore", fd, fd],
+      env: env ? { ...process.env, ...env } : undefined,
+    });
+    proc.unref();
+    return proc.pid;
+  },
+};
+
+export type KillFn = (pid: number, signal: NodeJS.Signals | number) => void;
+export type SleepFn = (ms: number) => Promise<void>;
+
+export const defaultKill: KillFn = (pid, signal) => {
+  process.kill(pid, signal);
+};
+
+export const defaultSleep: SleepFn = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export interface LifecycleOpts {
+  spawner?: Spawner;
+  kill?: KillFn;
+  alive?: AliveFn;
+  sleep?: SleepFn;
+  now?: () => number;
+  manifestPath?: string;
+  configDir?: string;
+  log?: (line: string) => void;
+  /** How long stop waits for SIGTERM before escalating to SIGKILL. */
+  killWaitMs?: number;
+  /** Poll interval while waiting for SIGTERM to land. */
+  pollIntervalMs?: number;
+  /**
+   * Override the hub origin passed to services as PARACHUTE_HUB_ORIGIN. If
+   * unset, `start` derives it from `expose-state.json` (when exposed) or
+   * the hub.port file (local dev). Undefined → no env var is set at all,
+   * and the service advertises its own default issuer.
+   */
+  hubOrigin?: string;
+}
+
+interface Resolved {
+  spawner: Spawner;
+  kill: KillFn;
+  alive: AliveFn;
+  sleep: SleepFn;
+  now: () => number;
+  manifestPath: string;
+  configDir: string;
+  log: (line: string) => void;
+  killWaitMs: number;
+  pollIntervalMs: number;
+  hubOrigin: string | undefined;
+}
+
+function resolve(opts: LifecycleOpts): Resolved {
+  const configDir = opts.configDir ?? CONFIG_DIR;
+  return {
+    spawner: opts.spawner ?? defaultSpawner,
+    kill: opts.kill ?? defaultKill,
+    alive: opts.alive ?? defaultAlive,
+    sleep: opts.sleep ?? defaultSleep,
+    now: opts.now ?? Date.now,
+    manifestPath: opts.manifestPath ?? SERVICES_MANIFEST_PATH,
+    configDir,
+    log: opts.log ?? ((line) => console.log(line)),
+    killWaitMs: opts.killWaitMs ?? 10_000,
+    pollIntervalMs: opts.pollIntervalMs ?? 200,
+    hubOrigin: resolveHubOrigin(opts.hubOrigin, configDir),
+  };
+}
+
+/**
+ * Source of truth order for `PARACHUTE_HUB_ORIGIN`:
+ *   1. explicit override (flag / opt)
+ *   2. live exposure's hubOrigin / canonicalFqdn (what clients actually see)
+ *   3. hub.port when the hub is running locally (local-dev loopback)
+ *   4. undefined — don't set the env, let the service self-advertise
+ */
+function resolveHubOrigin(override: string | undefined, configDir: string): string | undefined {
+  if (override) return deriveHubOrigin({ override });
+  const state = readExposeState(join(configDir, "expose-state.json"));
+  if (state?.hubOrigin) return state.hubOrigin;
+  const exposeFqdn = state?.canonicalFqdn;
+  return deriveHubOrigin({ exposeFqdn, hubPort: readHubPort(configDir) });
+}
+
+/**
+ * Services selected by the `[svc]` positional. `undefined` targets every
+ * installed service (looked up via the manifest). Unknown names get a
+ * friendly error up front rather than a confusing spawn failure downstream.
+ */
+function resolveTargets(
+  svc: string | undefined,
+  manifestPath: string,
+): { targets: Array<{ short: string; entry: ServiceEntry }> } | { error: string } {
+  const manifest = readManifest(manifestPath);
+  if (manifest.services.length === 0) {
+    return { error: "No services installed yet. Try: parachute install vault" };
+  }
+
+  if (svc !== undefined) {
+    const spec = getSpec(svc);
+    if (!spec) {
+      return {
+        error: `unknown service "${svc}". known: ${knownServices().join(", ")}`,
+      };
+    }
+    const entry = manifest.services.find((s) => s.name === spec.manifestName);
+    if (!entry) {
+      return {
+        error: `${svc} isn't installed. Run \`parachute install ${svc}\` first.`,
+      };
+    }
+    return { targets: [{ short: svc, entry }] };
+  }
+
+  const targets: Array<{ short: string; entry: ServiceEntry }> = [];
+  for (const entry of manifest.services) {
+    const short = shortNameForManifest(entry.name);
+    if (!short) continue;
+    targets.push({ short, entry });
+  }
+  if (targets.length === 0) {
+    return { error: "No manageable services in services.json." };
+  }
+  return { targets };
+}
+
+export async function start(svc: string | undefined, opts: LifecycleOpts = {}): Promise<number> {
+  const r = resolve(opts);
+  const picked = resolveTargets(svc, r.manifestPath);
+  if ("error" in picked) {
+    r.log(picked.error);
+    return 1;
+  }
+
+  let failures = 0;
+  for (const { short, entry } of picked.targets) {
+    const state = processState(short, r.configDir, r.alive);
+    if (state.status === "running") {
+      r.log(`${short} already running (pid ${state.pid}).`);
+      continue;
+    }
+    if (state.pid !== undefined) {
+      // Stale PID file for a dead process — clear it before we spawn fresh.
+      clearPid(short, r.configDir);
+    }
+
+    const spec = getSpec(short);
+    const cmd = spec?.startCmd?.(entry);
+    if (!cmd || cmd.length === 0) {
+      r.log(`${short}: lifecycle not yet supported for this service.`);
+      failures++;
+      continue;
+    }
+
+    const logFile = ensureLogPath(short, r.configDir);
+    // Merge `<configDir>/<short>/.env` into the spawn env so service-specific
+    // values (auto-wired SCRIBE_AUTH_TOKEN/SCRIBE_URL on vault, GROQ/OPENAI
+    // API keys on scribe written by the install prompt) reach the daemon.
+    // Vault still loads its own .env at runtime (it has its own start.sh
+    // wrapper for launchd / systemd) — this is idempotent there. Hub-origin
+    // override wins on collision; that's the live-exposure source of truth.
+    const fileEnv = readEnvFileValues(join(r.configDir, short, ".env"));
+    const env: Record<string, string> = { ...fileEnv };
+    if (r.hubOrigin) env[HUB_ORIGIN_ENV] = r.hubOrigin;
+    const envForSpawn = Object.keys(env).length > 0 ? env : undefined;
+    try {
+      const pid = r.spawner.spawn(cmd, logFile, envForSpawn);
+      writePid(short, pid, r.configDir);
+      r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
+      if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
+    } catch (err) {
+      failures++;
+      const msg = err instanceof Error ? err.message : String(err);
+      r.log(`✗ ${short} failed to start: ${msg}`);
+    }
+  }
+  return failures === 0 ? 0 : 1;
+}
+
+export async function stop(svc: string | undefined, opts: LifecycleOpts = {}): Promise<number> {
+  const r = resolve(opts);
+  const picked = resolveTargets(svc, r.manifestPath);
+  if ("error" in picked) {
+    r.log(picked.error);
+    return 1;
+  }
+
+  let failures = 0;
+  for (const { short } of picked.targets) {
+    const pid = readPid(short, r.configDir);
+    if (pid === undefined) {
+      r.log(`${short} wasn't running.`);
+      continue;
+    }
+    if (!r.alive(pid)) {
+      clearPid(short, r.configDir);
+      r.log(`${short} wasn't running (cleaned stale pid file).`);
+      continue;
+    }
+
+    try {
+      r.kill(pid, "SIGTERM");
+    } catch (err) {
+      failures++;
+      r.log(`✗ ${short}: SIGTERM failed: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+
+    const deadline = r.now() + r.killWaitMs;
+    while (r.now() < deadline && r.alive(pid)) {
+      await r.sleep(r.pollIntervalMs);
+    }
+
+    if (r.alive(pid)) {
+      r.log(`${short} didn't exit after ${r.killWaitMs}ms; sending SIGKILL.`);
+      try {
+        r.kill(pid, "SIGKILL");
+      } catch (err) {
+        failures++;
+        r.log(`✗ ${short}: SIGKILL failed: ${err instanceof Error ? err.message : String(err)}`);
+        continue;
+      }
+    }
+
+    clearPid(short, r.configDir);
+    r.log(`✓ ${short} stopped.`);
+  }
+  return failures === 0 ? 0 : 1;
+}
+
+export async function restart(svc: string | undefined, opts: LifecycleOpts = {}): Promise<number> {
+  const stopCode = await stop(svc, opts);
+  if (stopCode !== 0) return stopCode;
+  return await start(svc, opts);
+}
+
+export interface LogsOpts {
+  configDir?: string;
+  log?: (line: string) => void;
+  /** Tail stream — if omitted, uses `tail -n <lines> -f <file>` via spawn. */
+  tailSpawner?: Spawner;
+  /** Number of trailing lines to print (default 200). */
+  lines?: number;
+  follow?: boolean;
+}
+
+export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
+  const configDir = opts.configDir ?? CONFIG_DIR;
+  const log = opts.log ?? ((line) => console.log(line));
+  const lines = opts.lines ?? 200;
+  const follow = opts.follow ?? false;
+
+  const spec = getSpec(svc);
+  if (!spec) {
+    log(`unknown service "${svc}". known: ${knownServices().join(", ")}`);
+    return 1;
+  }
+
+  const path = logPathFor(svc, configDir);
+  if (!existsSync(path)) {
+    log(`no logs yet for ${svc}. \`parachute start ${svc}\` to begin.`);
+    return 0;
+  }
+
+  if (follow) {
+    const spawner = opts.tailSpawner ?? {
+      spawn(cmd) {
+        const proc = Bun.spawn([...cmd], { stdio: ["ignore", "inherit", "inherit"] });
+        return proc.pid;
+      },
+    };
+    spawner.spawn(["tail", "-n", String(lines), "-f", path], path);
+    // tail runs until user Ctrl-C; block this process until it exits.
+    // When called from the real CLI, process.exit wraps us; in tests a
+    // stub spawner returns immediately and we fall through.
+    return 0;
+  }
+
+  // Non-follow path: read last N lines synchronously for a clean one-shot.
+  const content = await Bun.file(path).text();
+  const trimmed = content.replace(/\n$/, "");
+  const allLines = trimmed === "" ? [] : trimmed.split("\n");
+  const tail = allLines.slice(-lines);
+  for (const line of tail) log(line);
+  return 0;
+}

package/src/commands/migrate.ts

@@ -0,0 +1,253 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { CONFIG_DIR } from "../config.ts";
+import { knownServices } from "../service-spec.ts";
+
+/**
+ * `parachute migrate` — sweep unrecognized entries at the ecosystem root
+ * (`~/.parachute/`) into a dated archive directory so pre-restructure cruft
+ * doesn't confuse beta installs.
+ *
+ * Archive, never delete: moved under `.archive-<YYYY-MM-DD>/` so anything
+ * swept is recoverable. Dotfiles and the recognized top-level entries
+ * (service dirs, services.json, expose-state.json, well-known/) are left
+ * alone. Content *inside* service dirs is owned by that service's own
+ * migration.
+ */
+
+export const ARCHIVE_PREFIX = ".archive-";
+
+/**
+ * Top-level names we keep in place. Service dirs derive from
+ * `knownServices()` so adding a service doesn't require touching migrate;
+ * `hub` is added explicitly since it's an internal-only lifecycle dir not
+ * in SERVICE_SPECS.
+ *
+ * `lens` is kept across the Notes→Lens→Notes rename round-trip
+ * (Apr 19 → Apr 22): users who installed during the brief Lens window
+ * have `~/.parachute/lens/` dirs that shouldn't get swept into
+ * `.archive-*` on upgrade. Safe to remove once launch users have all
+ * had a chance to re-install under the restored name.
+ */
+export function safelistEntries(): Set<string> {
+  return new Set<string>([
+    ...knownServices(),
+    "lens",
+    "hub",
+    "services.json",
+    "expose-state.json",
+    "well-known",
+  ]);
+}
+
+/**
+ * Friendly labels for entries we've seen in the wild. Matched by exact name
+ * or (for sqlite companion files) by prefix. Purely cosmetic — drives the
+ * annotation column in the plan printout.
+ */
+const KNOWN_CRUFT: Array<{ match: (name: string) => boolean; label: string }> = [
+  {
+    match: (n) => n === "daily.db" || n.startsWith("daily.db-"),
+    label: "legacy parachute-daily state",
+  },
+  { match: (n) => n === "server.yaml", label: "legacy server config" },
+  { match: (n) => n === "channel.log" || n === "channel.err", label: "legacy channel logs" },
+  { match: (n) => n === "channel.start.sh", label: "legacy channel launcher" },
+  { match: (n) => n === "logs", label: "vestigial top-level logs dir" },
+  {
+    match: (n) => n === "tokens.db" || n.startsWith("tokens.db-"),
+    label: "legacy top-level tokens db",
+  },
+];
+
+function annotationFor(name: string): string | undefined {
+  for (const rule of KNOWN_CRUFT) if (rule.match(name)) return rule.label;
+  return undefined;
+}
+
+export interface ArchiveItem {
+  name: string;
+  absPath: string;
+  kind: "file" | "dir";
+  bytes: number;
+  annotation?: string;
+}
+
+export interface ArchivePlan {
+  archiveDirName: string;
+  archiveDir: string;
+  items: ArchiveItem[];
+  totalBytes: number;
+}
+
+function sizeOf(path: string): number {
+  const st = statSync(path);
+  if (!st.isDirectory()) return st.size;
+  let total = 0;
+  for (const entry of readdirSync(path, { withFileTypes: true })) {
+    total += sizeOf(join(path, entry.name));
+  }
+  return total;
+}
+
+function archiveDirName(now: Date): string {
+  return `${ARCHIVE_PREFIX}${now.toISOString().slice(0, 10)}`;
+}
+
+/**
+ * Inspect the ecosystem root and build a plan. Pure-ish: reads filesystem
+ * but never mutates. Returns zero-length items when nothing is archivable.
+ *
+ * Rule: skip anything starting with "." (dotfiles are the user's — `.env`,
+ * `.DS_Store`, prior `.archive-*` dirs, etc.) and anything in the safelist.
+ */
+export function planArchive(configDir: string, now: Date): ArchivePlan {
+  const dirName = archiveDirName(now);
+  const archiveDir = join(configDir, dirName);
+  const plan: ArchivePlan = {
+    archiveDirName: dirName,
+    archiveDir,
+    items: [],
+    totalBytes: 0,
+  };
+  if (!existsSync(configDir)) return plan;
+
+  const safelist = safelistEntries();
+  const entries = readdirSync(configDir, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (safelist.has(entry.name)) continue;
+    const abs = join(configDir, entry.name);
+    // Dirent.isDirectory() follows symlinks on macOS/Linux — so a link
+    // pointing at an external tree would get sized via sizeOf() (bogus
+    // byte count, and potentially a slow walk through /mnt/... or similar).
+    // Classify the link itself as a zero-byte "file"; renameSync moves the
+    // link, not the target, which is the behavior we want.
+    if (entry.isSymbolicLink()) {
+      plan.items.push({
+        name: entry.name,
+        absPath: abs,
+        kind: "file",
+        bytes: 0,
+        annotation: annotationFor(entry.name),
+      });
+      continue;
+    }
+    const bytes = sizeOf(abs);
+    plan.items.push({
+      name: entry.name,
+      absPath: abs,
+      kind: entry.isDirectory() ? "dir" : "file",
+      bytes,
+      annotation: annotationFor(entry.name),
+    });
+    plan.totalBytes += bytes;
+  }
+  return plan;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB"];
+  let v = bytes / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i += 1;
+  }
+  return `${v.toFixed(1)} ${units[i]}`;
+}
+
+function formatPlan(plan: ArchivePlan): string[] {
+  const lines: string[] = [];
+  lines.push(
+    `Will archive: ${plan.items.length} item${plan.items.length === 1 ? "" : "s"} (${formatBytes(plan.totalBytes)}) → ${plan.archiveDirName}/`,
+  );
+  for (const item of plan.items) {
+    const kindMark = item.kind === "dir" ? "/" : "";
+    const note = item.annotation ? `  — ${item.annotation}` : "";
+    lines.push(`  ${item.name}${kindMark}  (${formatBytes(item.bytes)})${note}`);
+  }
+  return lines;
+}
+
+/**
+ * Pick a destination name inside the archive dir. If a prior sweep the same
+ * day already archived the same name, suffix with `.dup-<epoch-ms>` so we
+ * never clobber. Rare in practice.
+ */
+function resolveDest(archiveDir: string, name: string, now: Date): string {
+  const target = join(archiveDir, name);
+  if (!existsSync(target)) return target;
+  return join(archiveDir, `${name}.dup-${now.getTime()}`);
+}
+
+export async function defaultPrompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(question);
+  rl.close();
+  return answer;
+}
+
+export interface MigrateOpts {
+  configDir?: string;
+  now?: () => Date;
+  log?: (line: string) => void;
+  prompt?: (question: string) => Promise<string>;
+  dryRun?: boolean;
+  yes?: boolean;
+}
+
+export async function migrate(opts: MigrateOpts = {}): Promise<number> {
+  const configDir = opts.configDir ?? CONFIG_DIR;
+  const now = (opts.now ?? (() => new Date()))();
+  const log = opts.log ?? ((line) => console.log(line));
+  const prompt = opts.prompt ?? defaultPrompt;
+  const dryRun = opts.dryRun ?? false;
+  const yes = opts.yes ?? false;
+
+  const plan = planArchive(configDir, now);
+  if (plan.items.length === 0) {
+    log(`Nothing to archive. ${configDir} is already clean.`);
+    return 0;
+  }
+
+  for (const line of formatPlan(plan)) log(line);
+
+  if (dryRun) {
+    log("(dry-run — no changes made)");
+    return 0;
+  }
+
+  if (!yes) {
+    const answer = (await prompt("Proceed? [y/N] ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      log("Aborted.");
+      return 1;
+    }
+  }
+
+  mkdirSync(plan.archiveDir, { recursive: true });
+  for (const item of plan.items) {
+    const dest = resolveDest(plan.archiveDir, item.name, now);
+    renameSync(item.absPath, dest);
+  }
+  log(
+    `✓ Archived ${plan.items.length} item${plan.items.length === 1 ? "" : "s"} to ${plan.archiveDirName}/`,
+  );
+  return 0;
+}
+
+/**
+ * One-line notice for contexts where migrate is *not* what the user
+ * asked for (e.g., after `parachute install`). Returns undefined when
+ * there's nothing archivable so callers can branch on truthy/falsy.
+ */
+export function migrateNotice(configDir: string, now: Date): string | undefined {
+  const plan = planArchive(configDir, now);
+  if (plan.items.length === 0) return undefined;
+  return `parachute migrate: ${plan.items.length} unrecognized entr${plan.items.length === 1 ? "y" : "ies"} at ecosystem root — run 'parachute migrate' to archive.`;
+}