@openparachute/hub 0.3.0-rc.1

package/src/commands/scribe-provider-interactive.ts

@@ -0,0 +1,269 @@
+import { createInterface } from "node:readline/promises";
+import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
+import {
+  SCRIBE_DEFAULT_PROVIDER,
+  SCRIBE_PROVIDERS,
+  type ScribeProviderKey,
+  apiKeyEnvFor,
+  isKnownScribeProvider,
+  readScribeProviderState,
+  writeScribeApiKey,
+  writeScribeProvider,
+} from "../scribe-config.ts";
+import { restart as lifecycleRestart } from "./lifecycle.ts";
+
+/**
+ * Owns the post-install scribe setup: pick a transcription provider, capture
+ * an API key when needed, persist both, and restart scribe if it's already
+ * running so the new wiring takes effect immediately.
+ *
+ * Routing (in order):
+ *   1. `preselectProvider` (the `--scribe-provider <name>` flag) — validate,
+ *      use directly, no prompt.
+ *   2. Existing config has a non-default provider → assume the user already
+ *      chose; skip silently.
+ *   3. Interactive TTY → numbered-list prompt, then API-key prompt for the
+ *      cloud providers that need one.
+ *   4. Anything else (non-TTY, no flag) → leave the file untouched. The CLI
+ *      footer points at `scribe.config.json` so scripts that need a non-
+ *      default provider can write it themselves.
+ *
+ * Errors don't fail the install: a flaky restart or a config write that loses
+ * a race shouldn't undo a successful `bun add`. The user gets a clear log
+ * line and can re-run by hand.
+ */
+
+export type InteractiveAvailability =
+  | { kind: "available"; prompt: (q: string) => Promise<string> }
+  | { kind: "not-tty" };
+
+function defaultAvailability(): InteractiveAvailability {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return { kind: "not-tty" };
+  return {
+    kind: "available",
+    prompt: async (question: string) => {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        return await rl.question(question);
+      } finally {
+        rl.close();
+      }
+    },
+  };
+}
+
+export interface SetupScribeProviderOpts {
+  configDir: string;
+  log?: (line: string) => void;
+  /**
+   * Pre-chosen provider from `--scribe-provider <name>` (or programmatic
+   * caller). Bypasses the picker entirely and the existing-config check —
+   * passing the flag is itself an explicit choice.
+   */
+  preselectProvider?: string;
+  /**
+   * Pre-supplied API key from `--scribe-key <key>`. Only consulted for
+   * providers that need one (groq / openai). Ignored for local providers.
+   */
+  preselectKey?: string;
+  /**
+   * Interactive availability + prompt seam. Tests inject `{ kind: "available",
+   * prompt: ... }` to drive the picker without a real TTY; production lets the
+   * default sense `process.stdin.isTTY`.
+   */
+  availability?: InteractiveAvailability;
+  /** Restart-vault test seam, mirroring auto-wire's. */
+  alive?: AliveFn;
+  restartService?: (short: string) => Promise<number>;
+}
+
+export interface SetupScribeProviderResult {
+  /** True when this call wrote a new provider into config.json. */
+  configured: boolean;
+  /** Provider value present in scribe's config.json after this call. */
+  provider: string | undefined;
+  /** True when this call wrote a new API key into scribe/.env. */
+  wroteApiKey: boolean;
+  /** True when scribe was running and this call issued a restart. */
+  restartedScribe: boolean;
+  /** When non-empty, why the prompt was skipped (for telemetry / tests). */
+  skippedReason?: "preselected" | "already-configured" | "non-interactive";
+}
+
+export async function setupScribeProvider(
+  opts: SetupScribeProviderOpts,
+): Promise<SetupScribeProviderResult> {
+  const log = opts.log ?? (() => {});
+  const availability = opts.availability ?? defaultAvailability();
+  const alive = opts.alive ?? defaultAlive;
+  const restartService =
+    opts.restartService ??
+    ((short: string) => lifecycleRestart(short, { configDir: opts.configDir, log }));
+
+  const initial = readScribeProviderState(opts.configDir);
+
+  // 1. Flag-driven path: --scribe-provider wins outright.
+  if (opts.preselectProvider) {
+    if (!isKnownScribeProvider(opts.preselectProvider)) {
+      log(
+        `⚠ unknown --scribe-provider "${opts.preselectProvider}". Known: ${SCRIBE_PROVIDERS.map((p) => p.key).join(", ")}. Leaving config unchanged.`,
+      );
+      return {
+        configured: false,
+        provider: initial.provider,
+        wroteApiKey: false,
+        restartedScribe: false,
+        skippedReason: "preselected",
+      };
+    }
+    return await applyProviderChoice(opts.preselectProvider, opts.preselectKey, "preselected", {
+      configDir: opts.configDir,
+      log,
+      alive,
+      restartService,
+    });
+  }
+
+  // 2. Detect-and-skip: a previous run (or the operator) has set a non-default
+  //    provider. Leave it alone.
+  if (initial.provider !== undefined && initial.provider !== SCRIBE_DEFAULT_PROVIDER) {
+    log(
+      `Scribe transcription provider already set to "${initial.provider}" — leaving as-is. Edit ${opts.configDir}/scribe/config.json to change.`,
+    );
+    return {
+      configured: false,
+      provider: initial.provider,
+      wroteApiKey: false,
+      restartedScribe: false,
+      skippedReason: "already-configured",
+    };
+  }
+
+  // 3. Non-interactive (no TTY, no flag): don't prompt, don't write. The
+  //    install footer tells the user where to look later.
+  if (availability.kind !== "available") {
+    return {
+      configured: false,
+      provider: initial.provider,
+      wroteApiKey: false,
+      restartedScribe: false,
+      skippedReason: "non-interactive",
+    };
+  }
+
+  // 4. Prompt loop.
+  const picked = await pickProvider(availability.prompt, log);
+  if (!picked) {
+    log(
+      "No transcription provider chosen — leaving scribe at its built-in default (parakeet-mlx).",
+    );
+    return {
+      configured: false,
+      provider: initial.provider,
+      wroteApiKey: false,
+      restartedScribe: false,
+    };
+  }
+
+  let apiKey: string | undefined;
+  const envKey = apiKeyEnvFor(picked);
+  if (envKey) {
+    apiKey = (await availability.prompt(`Paste your ${envKey} (or blank to skip): `)).trim();
+    if (apiKey === "") {
+      log(
+        `Skipped ${envKey} entry. Set it later via \`echo '${envKey}=<value>' >> ${opts.configDir}/scribe/.env\` then \`parachute restart scribe\`.`,
+      );
+      apiKey = undefined;
+    }
+  }
+
+  return await applyProviderChoice(picked, apiKey, undefined, {
+    configDir: opts.configDir,
+    log,
+    alive,
+    restartService,
+  });
+}
+
+interface ApplyDeps {
+  configDir: string;
+  log: (line: string) => void;
+  alive: AliveFn;
+  restartService: (short: string) => Promise<number>;
+}
+
+async function applyProviderChoice(
+  provider: ScribeProviderKey,
+  apiKey: string | undefined,
+  skippedReason: SetupScribeProviderResult["skippedReason"],
+  deps: ApplyDeps,
+): Promise<SetupScribeProviderResult> {
+  writeScribeProvider(deps.configDir, provider);
+  let wroteApiKey = false;
+  const envKey = apiKeyEnvFor(provider);
+  if (envKey && apiKey && apiKey.length > 0) {
+    writeScribeApiKey(deps.configDir, envKey, apiKey);
+    wroteApiKey = true;
+  }
+
+  if (envKey && apiKey) {
+    deps.log(
+      `Set scribe transcription provider to "${provider}" and saved ${envKey} to ${deps.configDir}/scribe/.env.`,
+    );
+  } else if (envKey) {
+    deps.log(
+      `Set scribe transcription provider to "${provider}". Add ${envKey} to ${deps.configDir}/scribe/.env before transcribing.`,
+    );
+  } else {
+    deps.log(`Set scribe transcription provider to "${provider}".`);
+  }
+
+  let restartedScribe = false;
+  if (processState("scribe", deps.configDir, deps.alive).status === "running") {
+    deps.log("Restarting scribe to pick up the new transcription provider…");
+    const code = await deps.restartService("scribe");
+    if (code === 0) {
+      restartedScribe = true;
+    } else {
+      deps.log(
+        "⚠ scribe restart failed. Run manually once the issue is resolved: parachute restart scribe",
+      );
+    }
+  }
+
+  const result: SetupScribeProviderResult = {
+    configured: true,
+    provider,
+    wroteApiKey,
+    restartedScribe,
+  };
+  if (skippedReason) result.skippedReason = skippedReason;
+  return result;
+}
+
+async function pickProvider(
+  prompt: (q: string) => Promise<string>,
+  log: (line: string) => void,
+): Promise<ScribeProviderKey | undefined> {
+  log("");
+  log("Which transcription provider would you like to use?");
+  for (let i = 0; i < SCRIBE_PROVIDERS.length; i++) {
+    const p = SCRIBE_PROVIDERS[i];
+    if (!p) continue;
+    log(`  [${i + 1}] ${p.label.padEnd(13)} ${p.blurb}`);
+  }
+  log(`  [s] skip — leave at default (${SCRIBE_DEFAULT_PROVIDER})`);
+
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const raw = (await prompt("> ")).trim().toLowerCase();
+    if (raw === "" || raw === "s" || raw === "skip") return undefined;
+    const asNumber = Number.parseInt(raw, 10);
+    if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= SCRIBE_PROVIDERS.length) {
+      return SCRIBE_PROVIDERS[asNumber - 1]?.key;
+    }
+    if (isKnownScribeProvider(raw)) return raw;
+    log(`Sorry — expected 1..${SCRIBE_PROVIDERS.length}, a name, or s (got "${raw}"). Try again.`);
+  }
+  log("Too many invalid entries; skipping.");
+  return undefined;
+}

package/src/commands/status.ts

@@ -0,0 +1,238 @@
+import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { HUB_SVC, readHubPort } from "../hub-control.ts";
+import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
+import { getSpec, shortNameForManifest } from "../service-spec.ts";
+import { type ServiceEntry, readManifest } from "../services-manifest.ts";
+
+export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface StatusOpts {
+  manifestPath?: string;
+  fetchImpl?: FetchFn;
+  print?: (line: string) => void;
+  timeoutMs?: number;
+  configDir?: string;
+  alive?: AliveFn;
+  now?: () => Date;
+}
+
+export interface ProbeResult {
+  entry: ServiceEntry;
+  healthy: boolean;
+  statusCode?: number;
+  error?: string;
+  latencyMs: number;
+}
+
+export async function probe(
+  entry: ServiceEntry,
+  fetchImpl: FetchFn,
+  timeoutMs: number,
+): Promise<ProbeResult> {
+  const url = `http://localhost:${entry.port}${entry.health}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const start = performance.now();
+  try {
+    const res = await fetchImpl(url, { signal: controller.signal });
+    const latencyMs = Math.round(performance.now() - start);
+    return {
+      entry,
+      healthy: res.ok,
+      statusCode: res.status,
+      latencyMs,
+    };
+  } catch (err) {
+    const latencyMs = Math.round(performance.now() - start);
+    return {
+      entry,
+      healthy: false,
+      error: err instanceof Error ? err.message : String(err),
+      latencyMs,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function formatRow(cells: string[], widths: number[]): string {
+  return cells
+    .map((c, i) => c.padEnd(widths[i] ?? 0, " "))
+    .join("  ")
+    .trimEnd();
+}
+
+interface StatusRow {
+  service: string;
+  port: string;
+  version: string;
+  processLabel: string;
+  pidLabel: string;
+  uptimeLabel: string;
+  healthLabel: string;
+  latencyLabel: string;
+  url: string | undefined;
+  healthy: boolean;
+  skipped: boolean;
+}
+
+/**
+ * Canonical reachable URL for a row. Spec-driven where possible (vault appends
+ * `/mcp`, scribe is at the root, …). Unknown services fall back to bare
+ * `http://127.0.0.1:<port>` plus the first declared path so third-party
+ * services still get a useful pointer rather than an empty cell.
+ */
+function urlForEntry(entry: ServiceEntry, short: string | undefined): string | undefined {
+  const spec = short ? getSpec(short) : undefined;
+  const fromSpec = spec?.urlForEntry?.(entry);
+  if (fromSpec) return fromSpec;
+  const first = entry.paths[0]?.replace(/\/+$/, "") ?? "";
+  return `http://127.0.0.1:${entry.port}${first}`;
+}
+
+function hubRow(configDir: string, alive: AliveFn, nowDate: Date): StatusRow | undefined {
+  const proc = processState(HUB_SVC, configDir, alive);
+  if (proc.status === "unknown") return undefined;
+  const port = readHubPort(configDir);
+  const portLabel = port !== undefined ? String(port) : "-";
+  const processLabel = proc.status === "running" ? "running" : "stopped";
+  const pidLabel = proc.status === "running" && proc.pid !== undefined ? String(proc.pid) : "-";
+  const uptimeLabel =
+    proc.status === "running" && proc.startedAt ? formatUptime(proc.startedAt, nowDate) : "-";
+  return {
+    service: "parachute-hub (internal)",
+    port: portLabel,
+    version: "-",
+    processLabel,
+    pidLabel,
+    uptimeLabel,
+    healthLabel: "-",
+    latencyLabel: "-",
+    url: port !== undefined ? `http://127.0.0.1:${port}` : undefined,
+    healthy: true,
+    skipped: true,
+  };
+}
+
+export async function status(opts: StatusOpts = {}): Promise<number> {
+  const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const print = opts.print ?? ((line) => console.log(line));
+  const timeoutMs = opts.timeoutMs ?? 1500;
+  const configDir = opts.configDir ?? CONFIG_DIR;
+  const alive = opts.alive ?? defaultAlive;
+  const now = opts.now ?? (() => new Date());
+
+  const manifest = readManifest(manifestPath);
+  if (manifest.services.length === 0) {
+    print("No services installed yet.");
+    print("Try: parachute install vault");
+    return 0;
+  }
+
+  const nowDate = now();
+
+  /**
+   * Per-row resolution: look up the short name so we can read PID state,
+   * skip the health probe when the process is known-stopped (ECONNREFUSED
+   * noise isn't informative), and report it as running/stopped + uptime.
+   *
+   * Third-party services we don't know about fall back to probing and show
+   * "-" for process columns.
+   */
+  const rows: StatusRow[] = await Promise.all(
+    manifest.services.map(async (entry) => {
+      const short = shortNameForManifest(entry.name);
+      const proc = short ? processState(short, configDir, alive) : undefined;
+
+      const processLabel =
+        proc?.status === "running" ? "running" : proc?.status === "stopped" ? "stopped" : "-";
+      const pidLabel =
+        proc?.status === "running" && proc.pid !== undefined ? String(proc.pid) : "-";
+      const uptimeLabel =
+        proc?.status === "running" && proc.startedAt ? formatUptime(proc.startedAt, nowDate) : "-";
+
+      const url = urlForEntry(entry, short);
+
+      // 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.
+      if (proc?.status === "stopped") {
+        return {
+          service: entry.name,
+          port: String(entry.port),
+          version: entry.version,
+          processLabel,
+          pidLabel,
+          uptimeLabel,
+          healthLabel: "-",
+          latencyLabel: "-",
+          url,
+          healthy: false,
+          skipped: true,
+        };
+      }
+
+      const p = await probe(entry, fetchImpl, timeoutMs);
+      const healthLabel = p.healthy
+        ? "ok"
+        : p.statusCode !== undefined
+          ? `http ${p.statusCode}`
+          : (p.error ?? "down");
+      return {
+        service: entry.name,
+        port: String(entry.port),
+        version: entry.version,
+        processLabel,
+        pidLabel,
+        uptimeLabel,
+        healthLabel,
+        latencyLabel: `${p.latencyMs}ms`,
+        url,
+        healthy: p.healthy,
+        skipped: false,
+      };
+    }),
+  );
+
+  // 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);
+  if (hub) rows.push(hub);
+
+  const header = ["SERVICE", "PORT", "VERSION", "PROCESS", "PID", "UPTIME", "HEALTH", "LATENCY"];
+  const textRows = rows.map((r) => [
+    r.service,
+    r.port,
+    r.version,
+    r.processLabel,
+    r.pidLabel,
+    r.uptimeLabel,
+    r.healthLabel,
+    r.latencyLabel,
+  ]);
+  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
+  // with the row above without misleading the table widths.
+  for (let i = 0; i < textRows.length; i++) {
+    const cells = textRows[i];
+    const row = rows[i];
+    if (!cells || !row) continue;
+    print(formatRow(cells, widths));
+    if (row.url) print(`  → ${row.url}`);
+  }
+
+  /**
+   * Overall exit: non-zero if any *probed* service is unhealthy. A stopped
+   * service is expected ("I haven't started it yet"), not a failure — users
+   * want `parachute status` to return 0 after a fresh install before they
+   * `parachute start`. Health regressions among running services still 1.
+   */
+  const anyUnhealthy = rows.some((r) => !r.skipped && !r.healthy);
+  return anyUnhealthy ? 1 : 0;
+}

package/src/commands/vault-tokens-create-interactive.ts

@@ -0,0 +1,137 @@
+/**
+ * `parachute vault tokens create` (no narrowing flags, in a TTY) — guided
+ * token creation. Same command with any of `--scope` / `--read` /
+ * `--permission`, or running under a non-TTY, bypasses this module and passes
+ * through to `parachute-vault tokens create` unchanged.
+ *
+ * Two prompts:
+ *
+ *   1. Scope — read / write / admin / cancel. Default is `read` on Enter:
+ *      the two-factor reasoning is (a) a read-only token is the least
+ *      dangerous thing to mint by mistake, and (b) most callers of this
+ *      command interactively are plumbing in a new read-only consumer
+ *      (hooks, dashboards, n8n triggers). Users who actually want admin can
+ *      type "3" in ~1 second.
+ *
+ *   2. Label — free-form string, blank skips the prompt entirely (vault's
+ *      own `--label` default of "default" then applies). Skipped outright
+ *      if the user already supplied `--label …` on the command line.
+ *
+ * The resolved flags are appended to the original argv and forwarded to
+ * `parachute-vault tokens create` via an inherit-stdio subprocess so the
+ * generated token and its usage block print directly to the user's terminal.
+ *
+ * Shape mirrors `expose-interactive.ts`: every side-effectful edge is an
+ * injectable seam so the full prompt tree is testable without spawning.
+ */
+
+import { createInterface } from "node:readline/promises";
+
+export type InteractiveRunner = (cmd: readonly string[]) => Promise<number>;
+
+const defaultInteractiveRunner: InteractiveRunner = async (cmd) => {
+  const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+  return await proc.exited;
+};
+
+async function defaultPrompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+export interface VaultTokensCreateInteractiveOpts {
+  /**
+   * Original argv after `vault tokens create`. Flags the user already
+   * supplied (`--vault <name>`, `--expires <dur>`, `--label <x>`) are
+   * forwarded verbatim to `parachute-vault`; only the scope dimension is
+   * resolved interactively.
+   */
+  args: readonly string[];
+  prompt?: (question: string) => Promise<string>;
+  interactiveRunner?: InteractiveRunner;
+  log?: (line: string) => void;
+}
+
+interface Resolved {
+  args: readonly string[];
+  prompt: (question: string) => Promise<string>;
+  interactiveRunner: InteractiveRunner;
+  log: (line: string) => void;
+}
+
+function resolve(opts: VaultTokensCreateInteractiveOpts): Resolved {
+  return {
+    args: opts.args,
+    prompt: opts.prompt ?? defaultPrompt,
+    interactiveRunner: opts.interactiveRunner ?? defaultInteractiveRunner,
+    log: opts.log ?? ((line) => console.log(line)),
+  };
+}
+
+type ScopeChoice = "read" | "write" | "admin" | "cancel";
+
+async function promptScope(r: Resolved): Promise<ScopeChoice> {
+  r.log("Scope for this token?");
+  r.log("  [1] read   — query-only (safer default)");
+  r.log("  [2] write  — read + create/update");
+  r.log("  [3] admin  — full access (token + config management)");
+  r.log("  [4] cancel");
+  while (true) {
+    const raw = (await r.prompt("Choice [1]: ")).trim().toLowerCase();
+    if (raw === "" || raw === "1" || raw === "read") return "read";
+    if (raw === "2" || raw === "write") return "write";
+    if (raw === "3" || raw === "admin") return "admin";
+    if (raw === "4" || raw === "cancel" || raw === "q") return "cancel";
+    r.log(`(didn't understand "${raw}" — please pick 1, 2, 3, or 4)`);
+  }
+}
+
+async function promptLabel(r: Resolved): Promise<string | undefined> {
+  r.log("");
+  const raw = (await r.prompt('Label for this token (e.g. "n8n-sync", blank to skip): ')).trim();
+  return raw === "" ? undefined : raw;
+}
+
+/**
+ * Map the scope choice to the CLI flag sequence vault expects. We pass the
+ * canonical form for each level so anyone inspecting the spawned argv can
+ * see exactly what got minted — `--read` reads clearer than `--scope
+ * vault:read` for the common case, and `vault:write`/`vault:admin` are the
+ * canonical OAuth-style scope names for the other two.
+ */
+function scopeFlagsFor(choice: "read" | "write" | "admin"): string[] {
+  if (choice === "read") return ["--read"];
+  if (choice === "write") return ["--scope", "vault:write"];
+  return ["--scope", "vault:admin"];
+}
+
+export async function runVaultTokensCreateInteractive(
+  opts: VaultTokensCreateInteractiveOpts,
+): Promise<number> {
+  const r = resolve(opts);
+
+  const scope = await promptScope(r);
+  if (scope === "cancel") {
+    r.log("Cancelled — no token created.");
+    return 0;
+  }
+
+  const hasLabelFlag = r.args.includes("--label");
+  const label = hasLabelFlag ? undefined : await promptLabel(r);
+
+  const forwarded: string[] = [
+    "parachute-vault",
+    "tokens",
+    "create",
+    ...r.args,
+    ...scopeFlagsFor(scope),
+  ];
+  if (label !== undefined) forwarded.push("--label", label);
+
+  r.log("");
+  return await r.interactiveRunner(forwarded);
+}

package/src/commands/vault.ts

@@ -0,0 +1,17 @@
+export async function dispatchVault(args: readonly string[]): Promise<number> {
+  try {
+    const proc = Bun.spawn(["parachute-vault", ...args], {
+      stdio: ["inherit", "inherit", "inherit"],
+    });
+    return await proc.exited;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.toLowerCase().includes("enoent") || msg.toLowerCase().includes("not found")) {
+      console.error("parachute-vault not found on PATH.");
+      console.error("Install it with: parachute install vault");
+      return 127;
+    }
+    console.error(`failed to run parachute-vault: ${msg}`);
+    return 1;
+  }
+}

package/src/config.ts

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Root config directory. Honors `$PARACHUTE_HOME` to match the convention
+ * used by `parachute-vault` — both sides must resolve the same path for the
+ * shared `services.json` to round-trip.
+ */
+export function configDir(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.PARACHUTE_HOME;
+  if (override && override.length > 0) return override;
+  return join(homedir(), ".parachute");
+}
+
+export const CONFIG_DIR = configDir();
+export const SERVICES_MANIFEST_PATH = join(CONFIG_DIR, "services.json");