@openparachute/vault 0.1.0 → 0.2.0

package/src/cli.ts

@@ -38,10 +38,38 @@ import {
   ENV_PATH,
   LOG_PATH,
   ERR_PATH,
+  GLOBAL_CONFIG_PATH,
 } from "./config.ts";
 import type { VaultConfig } from "./config.ts";
+import { VAULTS_DIR } from "./config.ts";
 import { installAgent, uninstallAgent, isAgentLoaded, restartAgent } from "./launchd.ts";
-import { installSystemdService, restartSystemdService, isSystemdAvailable, isServiceActive } from "./systemd.ts";
+import {
+  runBackup,
+  readLastBackup,
+  nextRunEstimate,
+  updateBackupConfig,
+  expandTilde,
+  checkDestinationWritable,
+  tierTally,
+} from "./backup.ts";
+import {
+  installBackupAgent,
+  uninstallBackupAgent,
+  isBackupAgentLoaded,
+  BACKUP_PLIST_PATH,
+} from "./backup-launchd.ts";
+import { defaultBackupConfig } from "./config.ts";
+import type { BackupSchedule } from "./config.ts";
+import { installSystemdService, uninstallSystemdService, restartSystemdService, isSystemdAvailable, isServiceActive } from "./systemd.ts";
+import { checkHealth, waitForHealthy, tailFile } from "./health.ts";
+import type { HealthResult } from "./health.ts";
+import {
+  WRAPPER_PATH,
+  SERVER_PATH_FILE,
+  readServerPathPointer,
+  removeDaemonWrapper,
+  resolveServerPath,
+} from "./daemon.ts";
 import { confirm, ask, askPassword, choose } from "./prompt.ts";
 import { generateToken, createToken, listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
@@ -129,6 +157,18 @@ switch (command) {
   case "restart":
     await cmdRestart();
     break;
+  case "uninstall":
+    await cmdUninstall(cmdArgs);
+    break;
+  case "doctor":
+    await cmdDoctor();
+    break;
+  case "url":
+    cmdUrl();
+    break;
+  case "backup":
+    await cmdBackup(cmdArgs);
+    break;
   case "import":
     await cmdImport(cmdArgs);
     break;
@@ -170,10 +210,30 @@ async function cmdInit() {
     console.log(`Found ${vaults.length} existing vault(s)`);
   }
 
-  // 2. Write global config
+  // 2. Write global config. Set default_vault to the lone existing vault
+  // when unset or stale — this keeps unscoped routes (/mcp, /api/*) working
+  // for users who bootstrapped with `vault create <name>` before running init.
   const globalConfig = readGlobalConfig();
-  if (!globalConfig.default_vault) {
-    globalConfig.default_vault = "default";
+  const allVaults = listVaults();
+  const needsDefault = !globalConfig.default_vault
+    || !allVaults.includes(globalConfig.default_vault);
+  if (needsDefault) {
+    if (allVaults.length === 1) {
+      globalConfig.default_vault = allVaults[0];
+    } else if (allVaults.includes("default")) {
+      globalConfig.default_vault = "default";
+    } else if (allVaults.length > 0) {
+      // Multi-vault, no safe fallback — don't guess. Operator must set it.
+      console.log(
+        `  No default_vault set and multiple vaults exist. Unscoped routes (/mcp) will error until you set one.`,
+      );
+      console.log(
+        `  Fix:  echo 'default_vault: <name>' >> ${CONFIG_DIR}/config.yaml`,
+      );
+    } else {
+      // We created "default" above (vaults.length === 0 branch).
+      globalConfig.default_vault = "default";
+    }
   }
   writeGlobalConfig(globalConfig);
 
@@ -209,17 +269,24 @@ async function cmdInit() {
     await promptForOwnerPassword("Set an owner password for OAuth consent?");
   }
 
-  // 6. Install daemon (platform-aware)
+  // 6. Install daemon (platform-aware). Idempotent — safe to re-run after
+  // a folder move; this refreshes ~/.parachute/server-path and bounces the
+  // daemon so the new location takes effect immediately.
   console.log("Installing daemon...");
+  let serverPath: string | null = null;
   if (isMac) {
-    await installAgent();
+    ({ serverPath } = await installAgent());
   } else if (isLinux && isSystemdAvailable()) {
-    await installSystemdService();
+    ({ serverPath } = await installSystemdService());
   } else {
     console.log("  Auto-start not available on this platform.");
     console.log("  Run manually: bun src/server.ts");
     console.log("  Or use Docker: docker compose up -d");
   }
+  if (serverPath) {
+    console.log(`  Server path:  ${serverPath}`);
+    console.log(`  Wrapper:      ~/.parachute/start.sh`);
+  }
   console.log(`  Listening on http://0.0.0.0:${globalConfig.port || DEFAULT_PORT}`);
 
   // 7. Install MCP for Claude Code (with token for auth)
@@ -490,6 +557,13 @@ function cmdCreate(args: string[]) {
     console.error("Vault name must contain only letters, numbers, hyphens, and underscores.");
     process.exit(1);
   }
+  if (name === "list") {
+    // Reserved — /vaults/list is the public discovery endpoint. Allowing a
+    // vault with this name would let its routes (/vaults/list/mcp, etc.) be
+    // shadowed by the discovery handler.
+    console.error(`"list" is a reserved vault name.`);
+    process.exit(1);
+  }
 
   const existing = readVaultConfig(name);
   if (existing) {
@@ -498,12 +572,31 @@ function cmdCreate(args: string[]) {
   }
 
   ensureConfigDirSync();
+  const wasFirst = listVaults().length === 0;
   const key = createVault(name);
 
+  // If this is the only vault now, make it the default so unscoped routes
+  // (/mcp, /api/*, /oauth/*) target it. Avoids the "single vault named
+  // 'journal' but /mcp returns 404" surprise.
+  const globalConfig = readGlobalConfig();
+  const needsDefault = !globalConfig.default_vault
+    || !listVaults().includes(globalConfig.default_vault);
+  let defaultNote: string | null = null;
+  if (needsDefault) {
+    globalConfig.default_vault = name;
+    writeGlobalConfig(globalConfig);
+    defaultNote = wasFirst
+      ? `Set as default vault (unscoped routes will target "${name}")`
+      : `Set as default vault (previous default was missing)`;
+  }
+
   console.log(`Vault "${name}" created.`);
   console.log(`  Path: ${vaultDir(name)}`);
   console.log(`  API token: ${key}`);
   console.log(`  Save this — it will not be shown again.`);
+  if (defaultNote) {
+    console.log(`  ${defaultNote}`);
+  }
   console.log();
   console.log(`To add MCP to Claude: parachute vault mcp-install ${name}`);
 }
@@ -552,6 +645,24 @@ function cmdRemove(args: string[]) {
 
   rmSync(vaultDir(name), { recursive: true, force: true });
   console.log(`Vault "${name}" removed.`);
+
+  // Keep default_vault in sync. If the removed vault was the default, either
+  // promote the remaining vault (if exactly one) or clear the setting.
+  const globalConfig = readGlobalConfig();
+  if (globalConfig.default_vault === name) {
+    const remaining = listVaults();
+    if (remaining.length === 1) {
+      globalConfig.default_vault = remaining[0];
+      writeGlobalConfig(globalConfig);
+      console.log(`  Default vault is now "${remaining[0]}".`);
+    } else {
+      delete globalConfig.default_vault;
+      writeGlobalConfig(globalConfig);
+      if (remaining.length > 1) {
+        console.log(`  Cleared default_vault — set one with: editor ${CONFIG_DIR}/config.yaml`);
+      }
+    }
+  }
 }
 
 async function cmdConfig(args: string[]) {
@@ -771,6 +882,9 @@ async function cmdLogs() {
 }
 
 async function cmdRestart() {
+  loadEnvFile();
+  const port = readGlobalConfig().port || DEFAULT_PORT;
+
   console.log("Restarting daemon...");
   if (process.platform === "darwin") {
     await restartAgent();
@@ -780,30 +894,48 @@ async function cmdRestart() {
     console.error("No daemon manager available. Restart manually or use Docker.");
     process.exit(1);
   }
-  console.log("Done.");
+
+  process.stdout.write("Waiting for /health ");
+  // Dot-progress only to interactive terminals so piped output stays clean.
+  const interval = process.stdout.isTTY
+    ? setInterval(() => process.stdout.write("."), 500)
+    : null;
+  const health = await waitForHealthy(port, { totalMs: 10_000 });
+  if (interval) clearInterval(interval);
+  process.stdout.write("\n");
+
+  if (health.status === "healthy") {
+    console.log(`Vault is healthy at http://127.0.0.1:${port} (${health.latencyMs}ms)`);
+    return;
+  }
+
+  console.error(`Vault did not come up within 10s — status: ${health.status}${health.error ? ` (${health.error})` : ""}`);
+  printErrLogTail(20);
+  process.exit(1);
 }
 
 async function cmdStatus() {
   loadEnvFile();
-  let loaded: boolean;
+  const globalConfig = readGlobalConfig();
+  const port = globalConfig.port || DEFAULT_PORT;
+  const vaults = listVaults();
+
+  // Three distinct states:
+  //   loaded — launchd/systemd believes the agent is running
+  //   health — what the HTTP server at <port> actually responds with
+  let loaded: boolean | "n/a";
   if (process.platform === "darwin") {
     loaded = await isAgentLoaded();
   } else if (isSystemdAvailable()) {
     loaded = await isServiceActive();
   } else {
-    // Check if server responds on the port
-    try {
-      const resp = await fetch(`http://127.0.0.1:${readGlobalConfig().port || DEFAULT_PORT}/health`);
-      loaded = resp.ok;
-    } catch { loaded = false; }
+    loaded = "n/a"; // no daemon manager on this platform
   }
-  const vaults = listVaults();
-  const globalConfig = readGlobalConfig();
+  const health = await checkHealth(port);
 
   console.log("Parachute Vault\n");
-
-  // Server
-  console.log(`  Server:   ${loaded ? "running" : "stopped"} on port ${globalConfig.port}`);
+  console.log(`  Daemon:   ${renderLoaded(loaded)}`);
+  console.log(`  Server:   ${renderHealth(health, port)}`);
   console.log(`  Config:   ${CONFIG_DIR}`);
 
   // Vaults
@@ -825,17 +957,766 @@ async function cmdStatus() {
     console.log(`  Triggers:   none configured`);
   }
 
-  // Quick health check if daemon is running
-  if (loaded) {
-    try {
-      const resp = await fetch(`http://127.0.0.1:${globalConfig.port}/health`);
-      if (resp.ok) {
-        console.log(`\n  Health:   ok`);
+  // If loaded but not healthy, surface the recent error log. This is the
+  // "daemon is running but wedged" case that bit us when start.sh pointed
+  // at a moved repo — launchctl said it was loaded, the port was closed,
+  // and the cause was sitting in vault.err.
+  if (loaded === true && health.status !== "healthy") {
+    printErrLogTail(20);
+  }
+}
+
+function renderLoaded(loaded: boolean | "n/a"): string {
+  if (loaded === "n/a") return "(no daemon manager on this platform)";
+  if (!loaded) return "not loaded";
+  // Keep the manager name honest per-platform so Linux users don't see
+  // "launchctl" in their status output.
+  const manager = process.platform === "darwin" ? "launchctl" : "systemd";
+  return `loaded (${manager})`;
+}
+
+function renderHealth(h: HealthResult, port: number): string {
+  switch (h.status) {
+    case "healthy":
+      return `healthy — http://127.0.0.1:${port} (${h.latencyMs}ms)`;
+    case "unhealthy":
+      return `responding but unhealthy — HTTP ${h.statusCode} on port ${port}`;
+    case "not-listening":
+      return `not listening — nothing bound to port ${port}`;
+    case "error":
+      return `unreachable — ${h.error ?? "unknown error"}`;
+  }
+}
+
+function printErrLogTail(n: number) {
+  const tail = tailFile(ERR_PATH, n);
+  console.log(`\n  Recent errors from ${ERR_PATH}:`);
+  if (tail === null) {
+    console.log(`    (no log file at ${ERR_PATH})`);
+    return;
+  }
+  if (tail === "") {
+    console.log(`    (log file is empty)`);
+    return;
+  }
+  for (const line of tail.split("\n")) {
+    console.log(`    ${line}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Uninstall / Doctor / URL
+// ---------------------------------------------------------------------------
+
+async function cmdUninstall(argsList: string[]) {
+  const wipe = argsList.includes("--wipe");
+  const skipPrompts = argsList.includes("--yes") || argsList.includes("-y");
+
+  console.log("Parachute Vault uninstall\n");
+  console.log("This removes the daemon registration and wrapper script.");
+  if (wipe) {
+    console.log("`--wipe` will ALSO remove vaults, .env, config.yaml, and daemon logs.\n");
+  } else {
+    console.log("User data (~/.parachute/vaults, ~/.parachute/.env) is left alone.\n");
+  }
+
+  // Scripted `--yes --wipe` bypasses both interactive confirms. That's the
+  // intended contract for unattended uninstalls, but it should not be
+  // silent — print a single audit line so logs show when a destructive
+  // wipe ran and which paths it targeted. Non-interactive callers won't
+  // miss this; interactive users already see the prompts.
+  if (skipPrompts && wipe) {
+    const ts = new Date().toISOString();
+    const targets = [VAULTS_DIR, ENV_PATH, GLOBAL_CONFIG_PATH, LOG_PATH, ERR_PATH].join(", ");
+    console.log(`[${ts}] scripted destructive wipe: ${targets}`);
+  }
+
+  if (!skipPrompts) {
+    const ok = await confirm("Proceed?");
+    if (!ok) {
+      console.log("Cancelled.");
+      return;
+    }
+  }
+
+  // 1. Stop and remove the daemon registration.
+  if (process.platform === "darwin") {
+    console.log("Removing launchd agent...");
+    await uninstallAgent();
+    // Scheduled backup agent lives in a separate plist — uninstall it too,
+    // otherwise `uninstall` leaves the backup job firing forever on an
+    // install whose daemon has been removed.
+    await uninstallBackupAgent();
+  } else if (isSystemdAvailable()) {
+    console.log("Removing systemd service...");
+    await uninstallSystemdService();
+  } else {
+    console.log("No daemon manager on this platform — skipping service removal.");
+  }
+
+  // 2. Remove wrapper + pointer file (shared across platforms).
+  console.log("Removing wrapper and server-path pointer...");
+  await removeDaemonWrapper();
+
+  // 3. Clear the MCP entry in ~/.claude.json so Claude Code doesn't keep
+  // retrying a dead server every session. If ~/.claude.json doesn't exist
+  // or has no matching entry, this is a silent no-op.
+  console.log("Removing MCP entry from ~/.claude.json...");
+  removeMcpConfig();
+
+  // 4. Optionally wipe user data. The second confirm below defaults to
+  // NO so a distracted Enter-presser can't lose their vault. `--yes`
+  // explicitly opts into the destructive path for scripted uninstalls.
+  if (wipe) {
+    // Inventory what's actually on disk. Paths that don't exist are a
+    // silent no-op on removal, but we also skip listing them so the
+    // "would be removed" summary doesn't lie to the user.
+    const vaultsExist = existsSync(VAULTS_DIR);
+    const envExists = existsSync(ENV_PATH);
+    const configExists = existsSync(GLOBAL_CONFIG_PATH);
+    const logExists = existsSync(LOG_PATH);
+    const errExists = existsSync(ERR_PATH);
+
+    const anyExist = vaultsExist || envExists || configExists || logExists || errExists;
+    if (!anyExist) {
+      console.log("No user data to remove.");
+    } else {
+      console.log("\nUser data that would be removed:");
+      if (vaultsExist) console.log(`  ${VAULTS_DIR} (SQLite vaults)`);
+      if (envExists) console.log(`  ${ENV_PATH} (.env config + secrets)`);
+      if (configExists) console.log(`  ${GLOBAL_CONFIG_PATH} (global config)`);
+      if (logExists) console.log(`  ${LOG_PATH} (daemon log)`);
+      if (errExists) console.log(`  ${ERR_PATH} (daemon error log)`);
+
+      // Default to NO on the wipe confirm — this is the "don't lose a
+      // vault to muscle memory" guard. `--yes` is an explicit opt-in to
+      // the whole destructive path.
+      let doWipe = skipPrompts;
+      if (!skipPrompts) {
+        doWipe = await confirm("Delete this data? (cannot be undone)", false);
+      }
+      if (doWipe) {
+        if (vaultsExist) rmSync(VAULTS_DIR, { recursive: true, force: true });
+        if (envExists) rmSync(ENV_PATH, { force: true });
+        if (configExists) rmSync(GLOBAL_CONFIG_PATH, { force: true });
+        if (logExists) rmSync(LOG_PATH, { force: true });
+        if (errExists) rmSync(ERR_PATH, { force: true });
+        console.log("User data removed.");
+      } else {
+        console.log("Kept user data.");
+      }
+    }
+  }
+
+  console.log("\nDone. To reinstall: `parachute vault init`.");
+}
+
+interface DoctorCheck {
+  name: string;
+  status: "pass" | "warn" | "fail";
+  detail?: string;
+  fix?: string;
+}
+
+async function cmdDoctor() {
+  const checks: DoctorCheck[] = [];
+
+  // Pointer file. The stale-path failure mode shows up here first.
+  if (!existsSync(SERVER_PATH_FILE)) {
+    checks.push({
+      name: "server-path pointer",
+      status: "fail",
+      detail: `missing: ${SERVER_PATH_FILE}`,
+      fix: "Run `parachute vault init` to create it.",
+    });
+  } else {
+    const pointed = readServerPathPointer();
+    if (!pointed) {
+      checks.push({
+        name: "server-path pointer",
+        status: "fail",
+        detail: `empty: ${SERVER_PATH_FILE}`,
+        fix: "Run `parachute vault init` to rewrite it.",
+      });
+    } else if (!existsSync(pointed)) {
+      checks.push({
+        name: "server.ts at pointer target",
+        status: "fail",
+        detail: `points to ${pointed}, which does not exist`,
+        fix: "Run `parachute vault init` from the current repo location.",
+      });
+    } else {
+      checks.push({
+        name: "server-path pointer",
+        status: "pass",
+        detail: `→ ${pointed}`,
+      });
+    }
+  }
+
+  // Wrapper script. Independent of the pointer — a missing wrapper means
+  // launchd/systemd has nothing to exec.
+  if (!existsSync(WRAPPER_PATH)) {
+    checks.push({
+      name: "wrapper script",
+      status: "fail",
+      detail: `missing: ${WRAPPER_PATH}`,
+      fix: "Run `parachute vault init`.",
+    });
+  } else {
+    checks.push({ name: "wrapper script", status: "pass", detail: WRAPPER_PATH });
+  }
+
+  // Daemon registration.
+  if (process.platform === "darwin") {
+    const loaded = await isAgentLoaded();
+    checks.push({
+      name: "launchd agent",
+      status: loaded ? "pass" : "warn",
+      detail: loaded ? "loaded" : "not loaded",
+      fix: loaded ? undefined : "Run `parachute vault init` or `parachute vault restart`.",
+    });
+  } else if (isSystemdAvailable()) {
+    const active = await isServiceActive();
+    checks.push({
+      name: "systemd service",
+      status: active ? "pass" : "warn",
+      detail: active ? "active" : "not active",
+      fix: active ? undefined : "Run `parachute vault init` or `parachute vault restart`.",
+    });
+  }
+
+  // bun on PATH. Not strictly required for an already-installed vault
+  // (start.sh embeds an absolute bun path at init time), but missing `bun`
+  // is the #1 failure mode for first-time OSS users, so surface it clearly.
+  const bunOnPath = Bun.which("bun");
+  if (bunOnPath) {
+    checks.push({ name: "bun on PATH", status: "pass", detail: bunOnPath });
+  } else {
+    checks.push({
+      name: "bun on PATH",
+      status: "warn",
+      detail: "`bun` not resolvable via PATH",
+      fix: "Install Bun: curl -fsSL https://bun.sh/install | bash (then restart your shell).",
+    });
+  }
+
+  // MCP entry in ~/.claude.json. Split into three separate checks so the
+  // user can see exactly which condition fails: "entry present", "port
+  // matches vault", "daemon reachable over MCP URL". A common failure is
+  // "entry exists but port is stale" after the user changed PORT without
+  // re-running `mcp-install`.
+  const port = resolveVaultPort();
+  const mcpEntry = readMcpEntry();
+  if (!mcpEntry.found) {
+    checks.push({
+      name: "MCP entry in ~/.claude.json",
+      status: "warn",
+      detail: mcpEntry.reason,
+      fix: "Run `parachute vault mcp-install` to register the vault with Claude.",
+    });
+  } else {
+    checks.push({
+      name: "MCP entry in ~/.claude.json",
+      status: "pass",
+      detail: mcpEntry.url,
+    });
+
+    // Port match. Fall back to a warn if the URL has no parseable port
+    // (malformed entry) rather than a hard fail — we can still tell the
+    // user what we saw.
+    if (mcpEntry.port === port) {
+      checks.push({
+        name: "MCP URL port matches vault",
+        status: "pass",
+        detail: `port ${port}`,
+      });
+    } else {
+      checks.push({
+        name: "MCP URL port matches vault",
+        status: "warn",
+        detail: `MCP URL port ${mcpEntry.port ?? "(unparseable)"} ≠ vault port ${port}`,
+        fix: "Re-run `parachute vault mcp-install` to refresh the MCP URL.",
+      });
+    }
+
+    // Reachability probe. We do NOT require the daemon to be up for doctor
+    // to pass: a user who ran `vault status` already knows the daemon is
+    // off. This line is just a bonus telltale. Treat any HTTP response
+    // (even 401/404) as "reachable" — we're testing TCP+HTTP, not auth.
+    const reach = await probeMcpUrl(mcpEntry.url);
+    if (reach.ok) {
+      checks.push({
+        name: "MCP URL reachable",
+        status: "pass",
+        detail: reach.detail,
+      });
+    } else {
+      checks.push({
+        name: "MCP URL reachable",
+        status: "warn",
+        detail: reach.detail,
+        fix: "Start the daemon: `parachute vault restart` (or `init` if not yet installed).",
+      });
+    }
+  }
+
+  // Port collision. If something's holding the vault's configured port
+  // that ISN'T our daemon, the server will fail to bind on restart — a
+  // silent-until-crash-loop failure we want to catch at doctor time.
+  const collision = await checkPortCollision(port);
+  switch (collision.status) {
+    case "free":
+      checks.push({
+        name: `port ${port} availability`,
+        status: "pass",
+        detail: "no listener (ready to bind)",
+      });
+      break;
+    case "ours":
+      checks.push({
+        name: `port ${port} availability`,
+        status: "pass",
+        detail: `held by our daemon (pid ${collision.pids.join(", ")})`,
+      });
+      break;
+    case "foreign":
+      checks.push({
+        name: `port ${port} availability`,
+        status: "warn",
+        detail: `port in use by non-vault process: ${collision.detail}`,
+        fix: "Stop the conflicting process, or set a different PORT in ~/.parachute/.env and re-run `parachute vault init`.",
+      });
+      break;
+    case "unknown":
+      // Tool unavailable (no lsof / ss). Silent: we prefer a missing check
+      // over a spurious warning on minimal Linux images.
+      break;
+  }
+
+  // Backup — only verify when the user has asked for automatic backups.
+  // Manual mode is the default; showing a "not loaded" check when the user
+  // explicitly didn't configure scheduled backups is noise, not a finding.
+  const backupCfg = readGlobalConfig().backup;
+  if (backupCfg && backupCfg.schedule !== "manual") {
+    // 1. Agent loaded? (macOS only — systemd path for backup lands in a
+    // follow-up PR; on Linux we silently skip this half of the check.)
+    if (process.platform === "darwin") {
+      const loaded = await isBackupAgentLoaded();
+      checks.push({
+        name: "backup agent",
+        status: loaded ? "pass" : "warn",
+        detail: loaded ? `loaded (schedule: ${backupCfg.schedule})` : `not loaded (schedule: ${backupCfg.schedule})`,
+        fix: loaded ? undefined : `Re-run \`parachute vault backup --schedule ${backupCfg.schedule}\` to reinstall the agent.`,
+      });
+    }
+
+    // 2. Destination writability. A backup agent that fires into a path that
+    // doesn't exist (or is read-only) is the worst failure mode — silent
+    // until the user needs the backup, then "I have no backups." We try to
+    // mkdir the configured path and tap it for write access.
+    if (backupCfg.destinations.length === 0) {
+      checks.push({
+        name: "backup destinations",
+        status: "warn",
+        detail: "schedule is active but no destinations configured",
+        fix: "Edit ~/.parachute/config.yaml and add at least one destination under `backup.destinations`.",
+      });
+    } else {
+      for (const dest of backupCfg.destinations) {
+        const res = checkDestinationWritable(dest);
+        checks.push({
+          name: `backup destination (${dest.kind})`,
+          status: res.ok ? "pass" : "warn",
+          detail: res.ok ? res.path : `${res.path}: ${res.error}`,
+          fix: res.ok ? undefined : "Ensure the path exists and is writable, or update it in ~/.parachute/config.yaml.",
+        });
       }
+    }
+  }
+
+
+  // Render.
+  const icons = { pass: " ✓", warn: " !", fail: " ✗" } as const;
+  console.log("Parachute Vault — doctor\n");
+  for (const c of checks) {
+    const icon = icons[c.status];
+    console.log(`  ${icon} ${c.name}${c.detail ? `  (${c.detail})` : ""}`);
+    if (c.fix) console.log(`       fix: ${c.fix}`);
+  }
+
+  const hasFailure = checks.some((c) => c.status === "fail");
+  const hasWarn = checks.some((c) => c.status === "warn");
+  console.log();
+  if (hasFailure) {
+    console.log("doctor: problems found (exit 1). See `parachute vault status` for runtime details.");
+    process.exit(1);
+  } else if (hasWarn) {
+    console.log("doctor: warnings only. `parachute vault status` has live runtime detail.");
+  } else {
+    console.log("doctor: all checks passed. For live runtime state: `parachute vault status`.");
+  }
+}
+
+function cmdUrl() {
+  // Intentionally minimal — scripts parse this, so print only the URL.
+  console.log(`http://127.0.0.1:${resolveVaultPort()}`);
+}
+
+/**
+ * Resolve the vault's port the way `status`, `restart`, `url`, and `doctor`
+ * all need to agree on: env override (~/.parachute/.env) wins, then
+ * config.yaml, then DEFAULT_PORT. Sources .env as a side effect so callers
+ * running this before any env read still see PORT.
+ */
+function resolveVaultPort(): number {
+  loadEnvFile();
+  const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
+  return envPort ?? readGlobalConfig().port ?? DEFAULT_PORT;
+}
+
+// ---------------------------------------------------------------------------
+// Doctor helpers — MCP entry / port collision
+// ---------------------------------------------------------------------------
+
+type McpEntryLookup =
+  | { found: false; reason: string }
+  | { found: true; url: string; port: number | null };
+
+/**
+ * Read `~/.claude.json` and return the shape of the `parachute-vault` MCP
+ * entry if present. The entry is always an HTTP MCP pointing at the local
+ * daemon — `{ type: "http", url: "http://127.0.0.1:<port>/vaults/<name>/mcp" }`
+ * — so we parse the URL's port for the port-match check.
+ *
+ * Invariant: the check is NON-fatal. A missing ~/.claude.json is a warn,
+ * not a fail: plenty of users install the vault first and wire it to
+ * Claude later. We just make the "is it wired up?" state legible.
+ */
+function readMcpEntry(): McpEntryLookup {
+  const claudeJsonPath = resolve(homedir(), ".claude.json");
+  if (!existsSync(claudeJsonPath)) {
+    return { found: false, reason: `${claudeJsonPath} does not exist` };
+  }
+  let config: any;
+  try {
+    config = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+  } catch (err: any) {
+    return {
+      found: false,
+      reason: `${claudeJsonPath} is not valid JSON: ${String(err?.message ?? err)}`,
+    };
+  }
+  const entry = config?.mcpServers?.["parachute-vault"];
+  if (!entry) {
+    return {
+      found: false,
+      reason: `no mcpServers["parachute-vault"] entry in ${claudeJsonPath}`,
+    };
+  }
+  // The entry is always a URL-bearing HTTP MCP. Non-URL shapes are
+  // unexpected (Claude Code would ignore them anyway) but we surface the
+  // raw shape so the user can see what's there.
+  const url = typeof entry.url === "string" ? entry.url : null;
+  if (!url) {
+    return {
+      found: false,
+      reason: `mcpServers["parachute-vault"] has no \`url\` field (got ${JSON.stringify(entry).slice(0, 80)})`,
+    };
+  }
+  let entryPort: number | null = null;
+  try {
+    const parsed = new URL(url);
+    entryPort = parsed.port ? Number(parsed.port) : null;
+  } catch {
+    entryPort = null;
+  }
+  return { found: true, url, port: entryPort };
+}
+
+/**
+ * HEAD-probe the MCP URL to tell "entry present but daemon unreachable"
+ * apart from "entry present and daemon happily responding." Any HTTP
+ * response — including auth failures — counts as reachable: the check is
+ * about TCP + HTTP liveness, not correctness of the user's token.
+ *
+ * 2s timeout keeps `doctor` snappy when the daemon is down.
+ */
+async function probeMcpUrl(url: string): Promise<{ ok: boolean; detail: string }> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 2000);
+  try {
+    const resp = await fetch(url, { method: "HEAD", signal: controller.signal });
+    return { ok: true, detail: `HTTP ${resp.status}` };
+  } catch (err: any) {
+    const msg = String(err?.message ?? err);
+    if (
+      /ECONNREFUSED|ConnectionRefused|Unable to connect|refused/i.test(msg) ||
+      err?.code === "ECONNREFUSED"
+    ) {
+      return { ok: false, detail: `connection refused (daemon not running?)` };
+    }
+    if (err?.name === "AbortError" || /aborted|timeout/i.test(msg)) {
+      return { ok: false, detail: `timeout after 2000ms` };
+    }
+    return { ok: false, detail: msg };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+type PortCollision =
+  | { status: "free" }
+  | { status: "ours"; pids: number[] }
+  | { status: "foreign"; pids: number[]; detail: string }
+  | { status: "unknown" }; // no probe tool available
+
+/**
+ * Probe which process (if any) holds a TCP LISTEN socket on `port`.
+ *
+ * macOS: lsof is ubiquitous; we prefer it.
+ * Linux: lsof is common but not guaranteed. Fall back to `ss -tlnp`. If
+ *        neither exists, return "unknown" rather than a misleading "free."
+ *
+ * To decide whether the holder is "ours," we pull `ps -o command= -p <pid>`
+ * for each listening PID and look for a marker unique to our daemon —
+ * either the wrapper path or the pointer-file's server.ts path. This is
+ * heuristic but good enough to avoid warning when the vault is just
+ * running normally.
+ */
+async function checkPortCollision(port: number): Promise<PortCollision> {
+  const pids = await listListeningPids(port);
+  if (pids === null) return { status: "unknown" };
+  if (pids.length === 0) return { status: "free" };
+
+  // Build the set of path fragments that mark a process as ours. We check
+  // multiple signals because `doctor` may be running from a different
+  // PARACHUTE_HOME than the live daemon (tempdirs, Docker, developer
+  // machines): the wrapper path alone isn't enough. The pointer target and
+  // the currently-resolved server.ts path cover the common deployments.
+  const marks: string[] = [WRAPPER_PATH, resolveServerPath()];
+  const pointed = readServerPathPointer();
+  if (pointed) marks.push(pointed);
+
+  const descriptions: string[] = [];
+  let allOurs = true;
+  for (const pid of pids) {
+    const cmdline = await describeProcess(pid);
+    descriptions.push(`pid ${pid}: ${cmdline ?? "(unknown)"}`);
+    const mine = cmdline !== null && marks.some((m) => cmdline.includes(m));
+    if (!mine) allOurs = false;
+  }
+  if (allOurs) return { status: "ours", pids };
+  return { status: "foreign", pids, detail: descriptions.join("; ") };
+}
+
+/**
+ * Return PIDs holding a TCP LISTEN socket on `port`, or null if we can't
+ * tell (no probe tool). Empty array means no listener.
+ */
+async function listListeningPids(port: number): Promise<number[] | null> {
+  // Prefer lsof — same invocation works on macOS and Linux where present.
+  if (Bun.which("lsof")) {
+    try {
+      const r = await Bun.$`lsof -nP -iTCP:${port} -sTCP:LISTEN -Fp`.quiet().nothrow();
+      // lsof exits 1 with no output when nothing matches; that's "free," not
+      // an error. We distinguish by inspecting stdout rather than exitCode.
+      const out = r.stdout.toString();
+      const pids = [...out.matchAll(/^p(\d+)/gm)].map((m) => Number(m[1]));
+      return [...new Set(pids)];
     } catch {
-      console.log(`\n  Health:   daemon loaded but not responding`);
+      // Fall through to ss if lsof itself blew up unexpectedly.
     }
   }
+  if (Bun.which("ss")) {
+    try {
+      const r = await Bun.$`ss -tlnpH sport = :${port}`.quiet().nothrow();
+      const out = r.stdout.toString();
+      // `users:(("bun",pid=12345,fd=7))` — we pull every pid=NNNN.
+      const pids = [...out.matchAll(/pid=(\d+)/g)].map((m) => Number(m[1]));
+      if (pids.length > 0) return [...new Set(pids)];
+      // No users field but a listener row present? Treat as foreign with no
+      // attributable PID. Parsing the local address is overkill for a warn.
+      if (/LISTEN/.test(out)) return [-1];
+      return [];
+    } catch {}
+  }
+  return null;
+}
+
+/**
+ * Fetch a one-line description of a process by PID. Returns null if the
+ * PID is gone or ps is missing. Used only to classify a listener as ours
+ * vs foreign, so "good enough" beats "precisely parsed."
+ */
+async function describeProcess(pid: number): Promise<string | null> {
+  if (pid < 0) return null;
+  try {
+    const r = await Bun.$`ps -o command= -p ${pid}`.quiet().nothrow();
+    if (r.exitCode !== 0) return null;
+    return r.stdout.toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Backup — parachute vault backup [--schedule <freq> | status]
+// ---------------------------------------------------------------------------
+
+async function cmdBackup(args: string[]) {
+  // Subcommand: `status`
+  if (args[0] === "status") {
+    await cmdBackupStatus();
+    return;
+  }
+
+  // Flag: `--schedule <freq>`
+  const schedFlag = args.indexOf("--schedule");
+  if (schedFlag !== -1) {
+    const raw = args[schedFlag + 1];
+    if (!raw) {
+      console.error("Usage: parachute vault backup --schedule <hourly|daily|weekly|manual>");
+      process.exit(1);
+    }
+    if (raw !== "hourly" && raw !== "daily" && raw !== "weekly" && raw !== "manual") {
+      console.error(`Invalid schedule: ${raw}. Must be one of: hourly, daily, weekly, manual.`);
+      process.exit(1);
+    }
+    await cmdBackupSchedule(raw);
+    return;
+  }
+
+  // Default: one-shot backup.
+  await cmdBackupRun();
+}
+
+async function cmdBackupRun() {
+  const cfg = readGlobalConfig().backup ?? defaultBackupConfig();
+  if (cfg.destinations.length === 0) {
+    console.error("No backup destinations configured. Edit ~/.parachute/config.yaml:");
+    console.error("  backup:");
+    console.error("    destinations:");
+    console.error("      - kind: local");
+    console.error(`        path: ~/Library/Mobile Documents/com~apple~CloudDocs/parachute-backups`);
+    process.exit(1);
+  }
+
+  console.log("Running backup...");
+  const result = await runBackup({ backup: cfg });
+  const bytes = result.bytes;
+  const kb = Math.round(bytes / 1024);
+  console.log(`  Snapshot: ${result.contents.dbSnapshots.length} DB(s), ${result.contents.configFiles.length} config file(s), ${kb} KB`);
+
+  let ok = 0;
+  for (const r of result.destinations) {
+    if (r.error) {
+      console.error(`  ${r.destination.kind} — FAILED: ${r.error}`);
+      continue;
+    }
+    ok++;
+    const prunedStr = r.pruned > 0 ? ` (pruned ${r.pruned} older)` : "";
+    console.log(`  ${r.destination.kind} → ${r.writtenPath}${prunedStr}`);
+  }
+  if (ok === 0) {
+    process.exit(1);
+  }
+}
+
+async function cmdBackupSchedule(schedule: BackupSchedule) {
+  const cfg = updateBackupConfig({ schedule });
+
+  if (process.platform !== "darwin") {
+    console.log(`Schedule set to: ${schedule}`);
+    console.log("Note: scheduled backups are only registered on macOS in this MVP.");
+    console.log("Linux systemd-timer support is a follow-up PR.");
+    return;
+  }
+
+  if (schedule === "manual") {
+    await uninstallBackupAgent();
+    console.log("Schedule: manual — backup agent removed.");
+    console.log("Run `parachute vault backup` to trigger a backup on demand.");
+    return;
+  }
+
+  if (cfg.destinations.length === 0) {
+    console.log(`Schedule set to: ${schedule}`);
+    console.log();
+    console.log("WARNING: no destinations configured — scheduled runs will fail.");
+    console.log("Edit ~/.parachute/config.yaml and add at least one destination under `backup.destinations`.");
+  }
+
+  await installBackupAgent(schedule);
+  console.log(`Schedule: ${schedule} — backup agent installed.`);
+  console.log(`  Plist:    ${BACKUP_PLIST_PATH}`);
+  console.log(`  Next run: ${describeNextRun(schedule)}`);
+}
+
+async function cmdBackupStatus() {
+  const cfg = readGlobalConfig().backup ?? defaultBackupConfig();
+  const last = readLastBackup();
+
+  console.log("Parachute Vault — backup\n");
+  console.log(`  Schedule:   ${cfg.schedule}`);
+  // Tiered retention is always rendered as a one-line summary; per-tier
+  // counts from real destinations go under each destination below.
+  const r = cfg.retention;
+  const yearlyStr = r.yearly === null ? "∞" : String(r.yearly);
+  console.log(`  Retention:  ${r.daily} daily / ${r.weekly} weekly / ${r.monthly} monthly / ${yearlyStr} yearly`);
+
+  if (cfg.destinations.length === 0) {
+    console.log(`  Destinations: (none)`);
+  } else {
+    console.log(`  Destinations:`);
+    for (const d of cfg.destinations) {
+      if (d.kind === "local") {
+        const path = expandTilde(d.path);
+        console.log(`    - local: ${path}`);
+        // Per-destination tier breakdown — counts the snapshots on disk and
+        // each tier's individual contribution to the keep set. A snapshot
+        // can satisfy multiple tiers, so per-tier counts may sum to > total.
+        const t = tierTally(path, cfg.retention);
+        if (t.total > 0) {
+          console.log(`        on-disk: ${t.total} snapshot(s) — ${t.daily}d / ${t.weekly}w / ${t.monthly}mo / ${t.yearly}y`);
+        }
+      }
+    }
+  }
+
+  if (process.platform === "darwin") {
+    const loaded = await isBackupAgentLoaded();
+    console.log(`  Agent:      ${loaded ? "loaded (launchctl)" : "not loaded"}`);
+  }
+
+  if (last) {
+    console.log();
+    console.log(`  Last run:   ${last.timestamp}`);
+    console.log(`    Size:     ${Math.round(last.bytes / 1024)} KB`);
+    for (const d of last.destinations) {
+      if (d.error) {
+        console.log(`    FAILED:   ${d.error}`);
+      } else if (d.path) {
+        console.log(`    Wrote:    ${d.path}`);
+      }
+    }
+  } else {
+    console.log();
+    console.log("  Last run:   (never)");
+  }
+
+  if (cfg.schedule !== "manual") {
+    console.log();
+    console.log(`  Next run:   ${describeNextRun(cfg.schedule)}`);
+  }
+}
+
+function describeNextRun(schedule: BackupSchedule): string {
+  const est = nextRunEstimate(schedule, new Date());
+  if (!est) return "(manual — on demand only)";
+  // Render in local time so the user's sense of "around 3am" matches what
+  // launchd will actually do.
+  return est.toLocaleString();
 }
 
 // ---------------------------------------------------------------------------
@@ -930,7 +1811,7 @@ async function cmdImport(args: string[]) {
 
   for (const note of notes) {
     // Skip if a note with this path already exists
-    const existing = store.getNoteByPath(note.path);
+    const existing = await store.getNoteByPath(note.path);
     if (existing) {
       skipped++;
       continue;
@@ -939,7 +1820,7 @@ async function cmdImport(args: string[]) {
     // Build metadata from frontmatter (excluding tags, already extracted)
     const metadata = Object.keys(note.frontmatter).length > 0 ? note.frontmatter : undefined;
 
-    store.createNoteRaw(note.content, {
+    await store.createNoteRaw(note.content, {
       path: note.path,
       tags: note.tags.length > 0 ? note.tags : undefined,
       metadata: metadata as Record<string, unknown>,
@@ -952,7 +1833,7 @@ async function cmdImport(args: string[]) {
   if (skipped > 0) console.log(`Skipped ${skipped} notes (path already exists)`);
 
   if (imported > 0) {
-    const linkResult = store.syncAllWikilinks();
+    const linkResult = await store.syncAllWikilinks();
     console.log(`Resolved ${linkResult.totalAdded} wikilinks across ${linkResult.synced} notes.`);
   }
 }
@@ -992,7 +1873,7 @@ async function cmdExport(args: string[]) {
   const { getVaultStore } = await import("./vault-store.ts");
 
   const store = getVaultStore(vaultName);
-  const notes = store.queryNotes({ limit: 100000, sort: "asc" });
+  const notes = await store.queryNotes({ limit: 100000, sort: "asc" });
 
   console.log(`Exporting ${notes.length} notes from vault "${vaultName}" to ${fullPath}`);
   mkdir(fullPath, { recursive: true });
@@ -1087,8 +1968,14 @@ function usage() {
 Parachute Vault — self-hosted knowledge graph
 
 Setup:
-  parachute vault init                     Set up everything (one command)
+  parachute vault init                     Set up everything (one command, idempotent)
   parachute vault status                   Check what's running
+  parachute vault doctor                   Diagnose install/config issues
+  parachute vault uninstall [--wipe] [--yes]
+                                           Remove daemon + MCP entry; --wipe also removes vaults, .env,
+                                           config.yaml, and daemon logs (vault.log, vault.err).
+                                           --yes skips prompts (DANGEROUS with --wipe: no confirmation).
+  parachute vault url                      Print the local server URL (for scripts)
 
 Vaults:
   parachute vault create <name>            Create a new vault
@@ -1118,6 +2005,11 @@ Config:
   parachute vault config set <key> <val>   Set a config value
   parachute vault config unset <key>       Remove a config value
 
+Backup:
+  parachute vault backup                        One-shot backup to configured destinations
+  parachute vault backup --schedule <freq>      hourly | daily | weekly | manual (macOS launchd)
+  parachute vault backup status                 Show schedule, last run, destinations, next run
+
 Import/Export:
   parachute vault import <path>            Import an Obsidian vault
   parachute vault import <path> --dry-run  Preview import without writing