@openparachute/vault 0.1.0 → 0.2.0

package/src/health.ts

@@ -0,0 +1,115 @@
+/**
+ * Healthcheck + error-log helpers for the CLI.
+ *
+ * Used by `vault status`, `vault restart`, and `vault doctor` to distinguish
+ * three distinct failure modes that production wedged us on once already:
+ *
+ *   1. Launchd says the agent is loaded, but nothing is bound to the port.
+ *   2. Something is bound to the port, but /health doesn't return 200.
+ *   3. Everything is fine.
+ *
+ * The original CLI conflated these and reported "running" in cases where
+ * start.sh was failing and the daemon was respawning in a crash loop.
+ */
+
+import { readFileSync, existsSync } from "fs";
+
+export type HealthStatus =
+  | "healthy"         // port bound + /health 200
+  | "unhealthy"       // port bound but /health not 200
+  | "not-listening"   // port closed (nothing accepting connections)
+  | "error";          // other fetch failure
+
+export interface HealthResult {
+  status: HealthStatus;
+  statusCode?: number;
+  error?: string;
+  latencyMs?: number;
+}
+
+/**
+ * Probe http://127.0.0.1:<port>/health once. Short timeout so callers can
+ * poll without hanging. Treats ECONNREFUSED as "not listening" explicitly so
+ * the CLI can tell "daemon crashed" apart from "daemon running but wedged."
+ */
+export async function checkHealth(port: number, timeoutMs = 2000): Promise<HealthResult> {
+  const start = Date.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: controller.signal,
+    });
+    const latencyMs = Date.now() - start;
+    if (resp.ok) {
+      return { status: "healthy", statusCode: resp.status, latencyMs };
+    }
+    return { status: "unhealthy", statusCode: resp.status, latencyMs };
+  } catch (err: any) {
+    const latencyMs = Date.now() - start;
+    const msg = String(err?.message ?? err);
+    // Bun surfaces ECONNREFUSED as "Unable to connect" / error code
+    // "ConnectionRefused" depending on the version. Also catch DNS failures.
+    if (
+      /ECONNREFUSED|ConnectionRefused|Unable to connect|refused/i.test(msg) ||
+      err?.code === "ECONNREFUSED"
+    ) {
+      return { status: "not-listening", error: msg, latencyMs };
+    }
+    if (err?.name === "AbortError" || /aborted|timeout/i.test(msg)) {
+      return { status: "error", error: `timeout after ${timeoutMs}ms`, latencyMs };
+    }
+    return { status: "error", error: msg, latencyMs };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Poll /health until it returns healthy or the overall budget expires.
+ * Used by `vault restart` to turn a fire-and-forget launchctl bounce into a
+ * blocking operation with a clear success/failure signal.
+ */
+export async function waitForHealthy(
+  port: number,
+  opts: { totalMs?: number; intervalMs?: number; perProbeTimeoutMs?: number } = {},
+): Promise<HealthResult> {
+  const totalMs = opts.totalMs ?? 10_000;
+  const intervalMs = opts.intervalMs ?? 500;
+  const perProbeTimeoutMs = opts.perProbeTimeoutMs ?? 1_500;
+  const deadline = Date.now() + totalMs;
+
+  let last: HealthResult = { status: "error", error: "never probed" };
+  while (Date.now() < deadline) {
+    // Never let a single probe's timeout push us past the total budget —
+    // otherwise the worst case is totalMs + perProbeTimeoutMs, and the
+    // "10s" the user sees from the CLI wouldn't match reality.
+    const remainingBeforeProbe = deadline - Date.now();
+    const probeBudget = Math.min(perProbeTimeoutMs, remainingBeforeProbe);
+    if (probeBudget <= 0) break;
+    last = await checkHealth(port, probeBudget);
+    if (last.status === "healthy") return last;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await new Promise((r) => setTimeout(r, Math.min(intervalMs, remaining)));
+  }
+  return last;
+}
+
+/**
+ * Return the last `n` lines of a file. Safe on missing files (returns null
+ * so callers can render "no log file" rather than propagating ENOENT).
+ */
+export function tailFile(path: string, n: number): string | null {
+  if (!existsSync(path)) return null;
+  try {
+    const content = readFileSync(path, "utf8");
+    if (!content) return "";
+    const lines = content.split("\n");
+    // Drop trailing empty line from a terminating \n so the tail isn't blank.
+    if (lines[lines.length - 1] === "") lines.pop();
+    return lines.slice(-n).join("\n");
+  } catch (err) {
+    return null;
+  }
+}

package/src/launchd.test.ts

@@ -0,0 +1,91 @@
+import { describe, test, expect } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { $ } from "bun";
+import { generateWrapper, WRAPPER_PATH } from "./daemon.ts";
+import { generatePlist } from "./launchd.ts";
+
+describe("generateWrapper", () => {
+  // The incident that triggered this module: start.sh had the server path
+  // baked in and went stale when the repo moved. These tests assert the new
+  // contract — NO absolute server.ts path in the wrapper, pointer read at
+  // runtime, env override respected, and graceful failure when missing.
+
+  test("does not hardcode an absolute server.ts path", () => {
+    const wrapper = generateWrapper({
+      bunPath: "/Users/alice/.bun/bin/bun",
+      serverPathFile: "/Users/alice/.parachute/server-path",
+      envPath: "/Users/alice/.parachute/.env",
+    });
+    // No absolute path ending in server.ts — the whole point. Error messages
+    // may legitimately mention "server.ts" in text; we only forbid baked-in
+    // absolute paths that would go stale when the repo moves.
+    expect(wrapper).not.toMatch(/\/[^\s"]+\/server\.ts/);
+  });
+
+  test("reads the pointer file at boot, with PARACHUTE_VAULT_SERVER_PATH override", () => {
+    const wrapper = generateWrapper({
+      bunPath: "/bin/bun",
+      serverPathFile: "/x/.parachute/server-path",
+    });
+    // Env override precedes the pointer fallback.
+    expect(wrapper).toContain('SERVER_PATH="${PARACHUTE_VAULT_SERVER_PATH:-}"');
+    expect(wrapper).toContain('[ -f "/x/.parachute/server-path" ]');
+    expect(wrapper).toContain('cat "/x/.parachute/server-path"');
+  });
+
+  test("fails loudly (non-zero exit) when neither env nor pointer supplies a path", () => {
+    const wrapper = generateWrapper({ bunPath: "/bin/bun" });
+    expect(wrapper).toContain('if [ -z "$SERVER_PATH" ]; then');
+    expect(wrapper).toContain("exit 1");
+    // Actionable message — user needs to know what to run.
+    expect(wrapper).toMatch(/parachute vault init/);
+  });
+
+  test("fails loudly when pointer target no longer exists (moved repo)", () => {
+    const wrapper = generateWrapper({ bunPath: "/bin/bun" });
+    expect(wrapper).toContain('if [ ! -f "$SERVER_PATH" ]; then');
+    expect(wrapper).toMatch(/repo may have moved/);
+  });
+
+  test("sources .env at the configured path", () => {
+    const wrapper = generateWrapper({
+      bunPath: "/bin/bun",
+      envPath: "/custom/.env",
+    });
+    expect(wrapper).toContain('[ -f "/custom/.env" ]');
+    expect(wrapper).toContain('source "/custom/.env"');
+  });
+
+  test("execs bun with the resolved path (not a literal server path)", () => {
+    const wrapper = generateWrapper({ bunPath: "/Users/alice/.bun/bin/bun" });
+    // The exec line uses $SERVER_PATH (dereferenced at boot), not a literal.
+    expect(wrapper).toMatch(/exec "\/Users\/alice\/\.bun\/bin\/bun" "\$SERVER_PATH"/);
+  });
+
+  test("output is syntactically valid bash (bash -n passes)", async () => {
+    // Catch any shell-quoting regressions before they become crash-looping
+    // daemons in production. `bash -n` parses without executing.
+    const wrapper = generateWrapper({ bunPath: "/bin/bun" });
+    const dir = mkdtempSync(join(tmpdir(), "vault-wrapper-"));
+    const path = join(dir, "start.sh");
+    try {
+      writeFileSync(path, wrapper);
+      const result = await $`bash -n ${path}`.quiet().nothrow();
+      expect(result.exitCode).toBe(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("generatePlist", () => {
+  test("references the shared wrapper script, not server.ts directly", () => {
+    const plist = generatePlist();
+    // The plist launches /bin/bash with the wrapper — it must not name
+    // server.ts so the plist stays valid across repo moves.
+    expect(plist).toContain(`<string>${WRAPPER_PATH}</string>`);
+    expect(plist).not.toMatch(/server\.ts/);
+  });
+});

package/src/launchd.ts

@@ -1,42 +1,20 @@
 /**
  * macOS launchd agent management for the vault daemon.
  *
- * The plist runs a wrapper script that sources ~/.parachute/.env
- * before starting the server, so env vars (API keys, providers)
- * are available to the daemon.
+ * The plist runs `~/.parachute/start.sh` (the shared wrapper from
+ * daemon.ts). The wrapper reads the pointer file at every boot, so
+ * moving the repo only requires re-running `parachute vault init`.
  */
 
 import { homedir } from "os";
-import { join, resolve, dirname } from "path";
+import { join } from "path";
 import { writeFile, unlink } from "fs/promises";
 import { $ } from "bun";
-import { CONFIG_DIR, ENV_PATH, LOG_PATH, ERR_PATH } from "./config.ts";
+import { CONFIG_DIR, LOG_PATH, ERR_PATH } from "./config.ts";
+import { WRAPPER_PATH, writeDaemonWrapper } from "./daemon.ts";
 
 const LABEL = "computer.parachute.vault";
 const PLIST_PATH = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
-const WRAPPER_PATH = join(CONFIG_DIR, "start.sh");
-
-/**
- * Generate a shell wrapper that loads .env before starting the server.
- */
-function generateWrapper(serverPath: string, bunPath: string): string {
-  return `#!/bin/bash
-# Auto-generated by parachute vault init
-# Loads user PATH + ~/.parachute/.env then starts the vault server
-
-# Source user shell profile for PATH (needed for parakeet-mlx, ffmpeg, etc.)
-[ -f "$HOME/.zprofile" ] && source "$HOME/.zprofile" 2>/dev/null
-[ -f "$HOME/.zshrc" ] && source "$HOME/.zshrc" 2>/dev/null
-
-if [ -f "${ENV_PATH}" ]; then
-  set -a
-  source "${ENV_PATH}"
-  set +a
-fi
-
-exec "${bunPath}" "${serverPath}"
-`;
-}
 
 export function generatePlist(): string {
   return `<?xml version="1.0" encoding="UTF-8"?>
@@ -64,20 +42,37 @@ export function generatePlist(): string {
 </plist>`;
 }
 
-export async function installAgent(): Promise<void> {
+/**
+ * Install or re-install the launchd agent. Idempotent: if the agent is
+ * already loaded, it's unloaded first so the new wrapper + pointer take
+ * effect. This is what makes `parachute vault init` safe to re-run after
+ * a folder move — the incident that motivated this PR.
+ */
+export async function installAgent(): Promise<{ serverPath: string }> {
   if (process.platform !== "darwin") {
     throw new Error("launchd is only available on macOS. Use systemd on Linux.");
   }
-  const serverPath = resolve(dirname(import.meta.path), "server.ts");
-  const bunPath = Bun.which("bun") || join(homedir(), ".bun", "bin", "bun");
 
-  // Write the wrapper script
-  await writeFile(WRAPPER_PATH, generateWrapper(serverPath, bunPath), { mode: 0o755 });
+  const { serverPath } = await writeDaemonWrapper();
+  await writeFile(PLIST_PATH, generatePlist());
 
-  // Write and load the plist
-  const plist = generatePlist();
-  await writeFile(PLIST_PATH, plist);
-  await $`launchctl load ${PLIST_PATH}`.quiet();
+  // Bounce launchd so it picks up a refreshed wrapper + pointer. `load`
+  // alone fails with "Operation already in progress" if we're already
+  // registered, which used to silently leave stale config in place. If
+  // two `vault init` calls race, the second `load` may also see the
+  // service as still-loaded; swallow it so re-runs don't blow up.
+  try {
+    await $`launchctl unload ${PLIST_PATH}`.quiet();
+  } catch {
+    // Not loaded yet — fine.
+  }
+  try {
+    await $`launchctl load ${PLIST_PATH}`.quiet();
+  } catch {
+    // A concurrent init already reloaded it — fine.
+  }
+
+  return { serverPath };
 }
 
 export async function uninstallAgent(): Promise<void> {
@@ -87,9 +82,11 @@ export async function uninstallAgent(): Promise<void> {
   try {
     await unlink(PLIST_PATH);
   } catch {}
-  try {
-    await unlink(WRAPPER_PATH);
-  } catch {}
+  // Wrapper + pointer removal lives in daemon.ts so it's shared with the
+  // Linux uninstall path. Callers that want a fully-clean teardown must
+  // also call `removeDaemonWrapper()` — the CLI's `uninstall` command in
+  // PR 3 wires that up. Leaving them here programmatically would strand
+  // orphaned files in `~/.parachute/`.
 }
 
 export async function isAgentLoaded(): Promise<boolean> {

package/src/mcp-http.ts

@@ -95,7 +95,7 @@ async function handleMcp(
       };
     }
     try {
-      const result = tool.execute((args ?? {}) as Record<string, unknown>);
+      const result = await tool.execute((args ?? {}) as Record<string, unknown>);
       return {
         content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
       };

package/src/mcp-tools.ts

@@ -7,7 +7,7 @@
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
-import { readVaultConfig, writeVaultConfig, readGlobalConfig, listVaults as getVaultNames } from "./config.ts";
+import { readVaultConfig, writeVaultConfig, listVaults as getVaultNames, resolveDefaultVault } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
 
 /**
@@ -15,8 +15,7 @@ import { getVaultStore } from "./vault-store.ts";
  * Sent once at session init — not per tool.
  */
 export function getServerInstruction(vaultName?: string): string {
-  const globalConfig = readGlobalConfig();
-  const name = vaultName ?? globalConfig.default_vault ?? "default";
+  const name = vaultName ?? resolveDefaultVault() ?? "default";
   const config = readVaultConfig(name);
 
   const parts: string[] = [
@@ -35,9 +34,8 @@ export function getServerInstruction(vaultName?: string): string {
  * Each tool has an optional `vault` param that defaults to the default vault.
  */
 export function generateUnifiedMcpTools(): McpToolDef[] {
-  const globalConfig = readGlobalConfig();
-  const defaultVault = globalConfig.default_vault ?? "default";
   const vaultNames = getVaultNames();
+  const defaultVault = resolveDefaultVault() ?? "default";
   const multiVault = vaultNames.length > 1;
 
   // Get tool definitions from core (using default vault for schema)
@@ -66,7 +64,7 @@ export function generateUnifiedMcpTools(): McpToolDef[] {
       name: coreTool.name,
       description,
       inputSchema,
-      execute: (params) => {
+      execute: async (params) => {
         const vaultName = (params.vault as string) ?? defaultVault;
         const config = readVaultConfig(vaultName);
         if (!config) {
@@ -76,7 +74,7 @@ export function generateUnifiedMcpTools(): McpToolDef[] {
         const vaultTools = generateMcpTools(store);
         const tool = vaultTools.find((t) => t.name === coreTool.name)!;
         const { vault: _, ...rest } = params;
-        return tool.execute(rest);
+        return await tool.execute(rest);
       },
     };
   });
@@ -129,7 +127,7 @@ function overrideVaultInfo(tools: McpToolDef[], defaultVault: string): void {
   const vaultInfo = tools.find((t) => t.name === "vault-info");
   if (!vaultInfo) return;
 
-  vaultInfo.execute = (params) => {
+  vaultInfo.execute = async (params) => {
     const vaultName = (params.vault as string) ?? defaultVault;
     const config = readVaultConfig(vaultName);
     if (!config) throw new Error(`Vault "${vaultName}" not found`);
@@ -147,7 +145,7 @@ function overrideVaultInfo(tools: McpToolDef[], defaultVault: string): void {
 
     if (params.include_stats) {
       const store = getVaultStore(vaultName);
-      result.stats = store.getVaultStats();
+      result.stats = await store.getVaultStats();
     }
 
     return result;