@openparachute/vault 0.5.0-rc.1 → 0.5.0-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.5.0-rc.1",
+  "version": "0.5.0-rc.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/export-watch.test.ts

@@ -35,6 +35,7 @@ import {
   runGitCommitCycle,
   shouldCommit,
 } from "./export-watch.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 
 const CLI = path.resolve(import.meta.dir, "cli.ts");
 
@@ -504,6 +505,28 @@ describe("runGitCommitCycle", () => {
     });
     expect(result.message).toBe("note: Inbox/DonorMeeting");
   });
+
+  test("git missing → throws GitNotInstalledError (sync surfaces friendly error, not raw spawn crash)", async () => {
+    // vault#415 — the sync/commit path must surface the actionable
+    // git-not-installed message (which the manager threads into
+    // status.last_error) instead of crashing with a raw "Executable not
+    // found in $PATH". Force the preflight to see no git via the `which`
+    // seam; no real spawn should be reached.
+    fs.writeFileSync(path.join(dir, "Note.md"), "# n\n");
+    await expect(
+      runGitCommitCycle({
+        repoDir: dir,
+        template: DEFAULT_COMMIT_TEMPLATE,
+        notesChanged: 1,
+        vaultName: "default",
+        firstNoteTitle: "Note",
+        push: false,
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+    // The commit cycle bailed at the preflight — no commit landed.
+    expect(gitLogOneline(dir)).toHaveLength(1); // only the seed
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/export-watch.ts

@@ -13,6 +13,8 @@
  * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
  */
 
+import { ensureGitAvailable } from "./git-preflight.ts";
+
 // ---------------------------------------------------------------------------
 // Commit message templating
 // ---------------------------------------------------------------------------
@@ -269,11 +271,23 @@ export async function runGitCommitCycle(opts: {
   push: boolean;
   /** Override for tests — defaults to `new Date().toISOString()`. */
   now?: () => string;
+  /**
+   * Override the git-presence probe (test seam — defaults to `Bun.which`).
+   * Inject a fn returning `null` to exercise the git-not-installed path.
+   */
+  which?: (cmd: string) => string | null;
 }): Promise<{
   committed: boolean;
   message?: string;
   push?: { attempted: true; ok: boolean; error?: string };
 }> {
+  // Preflight: every step below shells `git`. On a git-less server the first
+  // `Bun.spawn(["git", ...])` would throw a raw "Executable not found" error;
+  // surface the friendly, actionable GitNotInstalledError so callers can
+  // thread it into mirror status (`last_error`) instead of crashing the
+  // watch loop with an opaque message.
+  ensureGitAvailable(opts.which);
+
   const now = opts.now ?? (() => new Date().toISOString());
 
   const add = await gitAddAll(opts.repoDir);

package/src/git-preflight.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Tests for the shared git-availability preflight (vault#415).
+ *
+ * Found live: importing a repo on a git-less Amazon Linux EC2 box failed
+ * with a raw `Executable not found in $PATH: "git"` 500. The preflight gives
+ * every git entry point a fast, friendly, actionable failure instead.
+ */
+
+import { describe, test, expect } from "bun:test";
+import {
+  GitNotInstalledError,
+  ensureGitAvailable,
+  isGitNotFoundSpawnError,
+} from "./git-preflight.ts";
+
+describe("ensureGitAvailable", () => {
+  test("throws GitNotInstalledError when which returns null", () => {
+    expect(() => ensureGitAvailable(() => null)).toThrow(GitNotInstalledError);
+  });
+
+  test("does not throw when which resolves git", () => {
+    expect(() => ensureGitAvailable(() => "/usr/bin/git")).not.toThrow();
+  });
+
+  test("defaults to Bun.which (git is present in this test env)", () => {
+    // The test host has git; the default-arg path resolves it cleanly.
+    expect(() => ensureGitAvailable()).not.toThrow();
+  });
+});
+
+describe("GitNotInstalledError message", () => {
+  test("is OS-agnostic-but-helpful — names dnf, apt-get, and brew", () => {
+    const msg = new GitNotInstalledError().message;
+    expect(msg).toContain("git is required for this operation");
+    expect(msg).toContain("sudo dnf install git");
+    expect(msg).toContain("sudo apt-get install -y git");
+    expect(msg).toContain("brew install git");
+  });
+
+  test("carries the GitNotInstalledError name (instanceof + name both work)", () => {
+    const err = new GitNotInstalledError();
+    expect(err).toBeInstanceOf(GitNotInstalledError);
+    expect(err.name).toBe("GitNotInstalledError");
+  });
+});
+
+describe("isGitNotFoundSpawnError", () => {
+  test("matches Bun's executable-not-found message for git", () => {
+    expect(
+      isGitNotFoundSpawnError(
+        new Error('Executable not found in $PATH: "git"'),
+      ),
+    ).toBe(true);
+  });
+
+  test("matches an ENOENT spawn error mentioning git", () => {
+    const err = new Error("spawn git ENOENT") as Error & { code?: string };
+    err.code = "ENOENT";
+    expect(isGitNotFoundSpawnError(err)).toBe(true);
+  });
+
+  test("does not match an unrelated error", () => {
+    expect(isGitNotFoundSpawnError(new Error("network unreachable"))).toBe(false);
+  });
+
+  test("does not match a non-Error value", () => {
+    expect(isGitNotFoundSpawnError("git missing")).toBe(false);
+    expect(isGitNotFoundSpawnError(null)).toBe(false);
+  });
+});

package/src/git-preflight.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared git-availability preflight.
+ *
+ * Every git-using entry point in vault (mirror import, mirror sync/commit/
+ * push, internal-mirror bootstrap) shells out to the `git` binary via
+ * `Bun.spawn(["git", ...])`. On a server where `git` isn't installed (a
+ * fresh Amazon Linux / minimal Docker image, etc.) Bun throws a raw
+ * `Executable not found in $PATH: "git"` error, which the import route only
+ * caught in its generic `internal` 500 branch — surfacing an unhelpful,
+ * un-actionable error to the operator.
+ *
+ * This module centralizes the preflight so every git entry point fails
+ * fast with a clear, actionable message that tells the operator HOW to
+ * fix it (install git via their distro's package manager).
+ *
+ * Found live on the gitcoin-parachute EC2 deploy (Amazon Linux, no git).
+ * See vault#415-era fix.
+ */
+
+/**
+ * Thrown when `git` is required for an operation but isn't on PATH. Carries
+ * an OS-agnostic-but-helpful message with the common install commands so the
+ * operator can act without leaving the error surface.
+ */
+export class GitNotInstalledError extends Error {
+  constructor() {
+    super(
+      "git is required for this operation but was not found on the server. " +
+        "Install git and retry — e.g. `sudo dnf install git` (Amazon Linux / Fedora), " +
+        "`sudo apt-get install -y git` (Debian / Ubuntu), or `brew install git` (macOS).",
+    );
+    this.name = "GitNotInstalledError";
+  }
+}
+
+/**
+ * Throw `GitNotInstalledError` if `git` isn't resolvable on PATH.
+ *
+ * `which` is a TEST SEAM (default `Bun.which`) so tests can force the
+ * git-missing branch without uninstalling git from the test host. Production
+ * callers pass nothing and get the real `Bun.which`.
+ */
+export function ensureGitAvailable(
+  which: (cmd: string) => string | null = Bun.which,
+): void {
+  if (which("git") === null) {
+    throw new GitNotInstalledError();
+  }
+}
+
+/**
+ * Heuristic: does this error look like the "git executable not found" failure
+ * Bun throws when it can't resolve the binary? Used as a belt-and-suspenders
+ * catch around `Bun.spawn(["git", ...])` so a spawn that slips past the
+ * preflight (race where git is removed between check and spawn, or a code path
+ * that didn't preflight) still surfaces the friendly error instead of the raw
+ * `Executable not found in $PATH: "git"` string.
+ */
+export function isGitNotFoundSpawnError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  // Bun: `Executable not found in $PATH: "git"`.
+  // Node/posix: ENOENT spawn errors mention the missing file.
+  return (
+    (msg.includes("Executable not found") && msg.includes("git")) ||
+    ((err as { code?: string }).code === "ENOENT" && msg.includes("git"))
+  );
+}

package/src/mirror-config.test.ts

@@ -23,6 +23,7 @@ import {
   validateExternalPath,
   validateMirrorConfigShape,
 } from "./mirror-config.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 
 function tmp(prefix: string): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -496,6 +497,19 @@ describe("validateExternalPath", () => {
     expect(r.ok).toBe(true);
     if (r.ok) expect(r.resolved_path).toBe(dir);
   });
+
+  test("git not installed → throws GitNotInstalledError (route maps to 503)", async () => {
+    // vault#415 nit — the isGitRepo() check shells `git`. On a git-less
+    // server, throw the friendly error (handleMirrorPut maps it to 503
+    // git_not_installed) instead of a raw "Executable not found" crash.
+    // Force the preflight via the `which` seam; a real, valid git repo is
+    // used so the ONLY failure source is the preflight.
+    dir = tmp("mirror-validate-nogit-installed-");
+    initRepo(dir);
+    await expect(validateExternalPath(dir, () => null)).rejects.toBeInstanceOf(
+      GitNotInstalledError,
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/mirror-config.ts

@@ -45,6 +45,7 @@ import { homedir } from "os";
 
 import { DEFAULT_COMMIT_TEMPLATE, isGitRepo } from "./export-watch.ts";
 import { readCredentials, type MirrorCredentials } from "./mirror-credentials.ts";
+import { ensureGitAvailable } from "./git-preflight.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -888,7 +889,17 @@ export type PathValidation = PathValidationOk | PathValidationError;
  */
 export async function validateExternalPath(
   externalPath: string,
+  // Test seam for the git-presence preflight (default `Bun.which`). Inject a
+  // fn returning `null` to exercise the git-not-installed path.
+  which?: (cmd: string) => string | null,
 ): Promise<PathValidation> {
+  // Preflight: the git-repo check below shells `git`. On a git-less server,
+  // throw the friendly, actionable GitNotInstalledError (which handleMirrorPut
+  // maps to a 503 `git_not_installed`, consistent with the import route)
+  // instead of letting `isGitRepo`'s `Bun.spawn` throw a raw
+  // "Executable not found in $PATH: \"git\"".
+  ensureGitAvailable(which);
+
   if (!existsSync(externalPath)) {
     return {
       ok: false,

package/src/mirror-import.test.ts

@@ -30,8 +30,10 @@ import {
   _resetImportInFlightForTest,
   authedCloneUrl,
   cloneAndImport,
+  defaultGitSpawn,
   type GitSpawn,
 } from "./mirror-import.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 import {
   emptyCredentials,
   mirrorCredentialsPath,
@@ -295,6 +297,10 @@ describe("cloneAndImport — success", () => {
     expect(result.notes_imported).toBe(2); // alpha + beta
     expect(result.notes_deleted).toBeUndefined();
     expect(result.warnings).toEqual([]);
+    // vault#416: cloneAndImport stays focused on content — sync-enabling is
+    // the route's job. The worker always returns sync_enabled: false.
+    expect(result.sync_enabled).toBe(false);
+    expect(result.sync_warning).toBeUndefined();
 
     const restored = await store.getNote("n-alpha");
     expect(restored).toBeTruthy();
@@ -548,3 +554,107 @@ describe("cloneAndImport — failures", () => {
     rmSync(notAnExport, { recursive: true, force: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// cloneAndImport — git not installed (vault#415 — live bug on a git-less EC2)
+// ---------------------------------------------------------------------------
+
+describe("cloneAndImport — git not installed", () => {
+  let assetsDir: string;
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    assetsDir = tmp("import-assets-nogit-");
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  afterEach(() => {
+    if (assetsDir) rmSync(assetsDir, { recursive: true, force: true });
+  });
+
+  test("git missing → GitNotInstalledError, fails fast (no spawn, no tempdir)", async () => {
+    const workDirRoot = tmp("import-workroot-nogit-");
+    let spawnCalled = false;
+    const spyingSpawn: GitSpawn = async () => {
+      spawnCalled = true;
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    await expect(
+      cloneAndImport({
+        vaultName: "default",
+        remoteUrl: "https://github.com/owner/repo.git",
+        auth: { kind: "none" },
+        mode: "merge",
+        store,
+        assetsDir,
+        spawn: spyingSpawn,
+        workDirRoot,
+        // Force the preflight to see no git on PATH.
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+
+    // Fails fast: the spawner is never reached and no tempdir is created.
+    expect(spawnCalled).toBe(false);
+    const { readdirSync } = await import("node:fs");
+    const entries = readdirSync(workDirRoot);
+    expect(entries.filter((e) => e.startsWith("parachute-import-"))).toEqual([]);
+    rmSync(workDirRoot, { recursive: true, force: true });
+  });
+
+  test("git missing → does not lay an in-flight marker (clean retry after install)", async () => {
+    await expect(
+      cloneAndImport({
+        vaultName: "default",
+        remoteUrl: "https://github.com/owner/repo.git",
+        auth: { kind: "none" },
+        mode: "merge",
+        store,
+        assetsDir,
+        spawn: async () => ({ exitCode: 0, stderr: "", timedOut: false }),
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+    // The preflight runs BEFORE the concurrency marker, so a failed call
+    // leaves no stale in-flight entry blocking the post-install retry.
+    expect(_isImportInFlight("default")).toBe(false);
+  });
+
+  test("git present (injected which) → normal import path still works", async () => {
+    const fixtureDir = await buildExportFixture();
+    try {
+      const result = await cloneAndImport({
+        vaultName: "default",
+        remoteUrl: "https://github.com/owner/repo.git",
+        auth: { kind: "none" },
+        mode: "merge",
+        store,
+        assetsDir,
+        spawn: spawnCloneSuccess(fixtureDir),
+        which: () => "/usr/bin/git",
+      });
+      expect(result.notes_imported).toBe(2);
+    } finally {
+      rmSync(fixtureDir, { recursive: true, force: true });
+    }
+  });
+
+  test("GitNotInstalledError message is actionable (names install commands)", () => {
+    const msg = new GitNotInstalledError().message;
+    expect(msg).toContain("git is required");
+    expect(msg).toContain("dnf install git");
+    expect(msg).toContain("apt-get install");
+    expect(msg).toContain("brew install git");
+  });
+
+  test("defaultGitSpawn rethrows a git-not-found spawn error as GitNotInstalledError", async () => {
+    // Belt-and-suspenders: spawn a non-existent binary to trigger Bun's
+    // "Executable not found" throw, and confirm the friendly rethrow.
+    // (We can't uninstall git, so spawn an impossible command name.)
+    await expect(
+      defaultGitSpawn(["definitely-not-a-real-binary-xyzzy-git"], {
+        timeoutMs: 5_000,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+  });
+});

package/src/mirror-import.ts

@@ -73,6 +73,11 @@ import {
 } from "../core/src/portable-md.ts";
 import type { SqliteStore } from "../core/src/store.ts";
 import { redactRemoteUrl, readCredentials } from "./mirror-credentials.ts";
+import {
+  GitNotInstalledError,
+  ensureGitAvailable,
+  isGitNotFoundSpawnError,
+} from "./git-preflight.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -125,6 +130,11 @@ export interface ImportOpts {
   importer?: typeof importPortableVault;
   /** Override the clone timeout (default 60s; test seam to shorten). */
   cloneTimeoutMs?: number;
+  /**
+   * Override the git-presence probe (test seam — defaults to `Bun.which`).
+   * Inject a fn returning `null` to exercise the git-not-installed path.
+   */
+  which?: (cmd: string) => string | null;
 }
 
 /**
@@ -144,6 +154,29 @@ export interface ImportResult {
    * etc.). The HTTP handler returns these so the operator can audit.
    */
   warnings: string[];
+  /**
+   * vault#416 — whether sync (mirror push-back to the imported repo) ended
+   * up enabled as part of this import. Default-on UX: the import request
+   * carries `enable_sync` (default true), and the route turns the imported
+   * repo into a configured, credential-backed, auto-pushing mirror after a
+   * successful import. `true` when sync is now wired (or was already wired
+   * to this same remote); `false` when sync was opted out, couldn't be
+   * enabled (no push-capable credentials), was skipped to avoid clobbering
+   * a different existing mirror, or threw during setup (import already
+   * succeeded — never lost to a sync error).
+   *
+   * `cloneAndImport` itself never sets these — the field is populated by the
+   * route (`handleMirrorImport`) after a successful import. `importResultFromStats`
+   * defaults `sync_enabled` to false; the route overwrites it.
+   */
+  sync_enabled: boolean;
+  /**
+   * Human-readable reason sync wasn't enabled (no creds / conflicting
+   * existing mirror / setup error). Only set when `sync_enabled` is false
+   * AND the caller asked for sync (`enable_sync !== false`). Absent when
+   * sync succeeded or the operator opted out.
+   */
+  sync_warning?: string;
 }
 
 /**
@@ -315,19 +348,32 @@ export function authedCloneUrl(
  * exit code + stderr text + timeout flag.
  */
 export const defaultGitSpawn: GitSpawn = async (argv, options) => {
-  const proc = Bun.spawn(argv, {
-    cwd: options.cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-    env: {
-      ...process.env,
-      GIT_TERMINAL_PROMPT: "0",
-      // Kill any system credential helper from intercepting — we want
-      // the clone to use ONLY the URL-embedded credential, not whatever's
-      // in keychain. Same shape as the ls-remote probe.
-      GIT_ASKPASS: "/bin/echo",
-    },
-  });
+  let proc;
+  try {
+    proc = Bun.spawn(argv, {
+      cwd: options.cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        // Kill any system credential helper from intercepting — we want
+        // the clone to use ONLY the URL-embedded credential, not whatever's
+        // in keychain. Same shape as the ls-remote probe.
+        GIT_ASKPASS: "/bin/echo",
+      },
+    });
+  } catch (err) {
+    // Belt-and-suspenders: `cloneAndImport` preflights via
+    // `ensureGitAvailable`, but if a git-missing spawn still slips through
+    // (race, or a future caller that skipped the preflight) rethrow it as
+    // the friendly error rather than leaking Bun's raw
+    // `Executable not found in $PATH: "git"`.
+    if (isGitNotFoundSpawnError(err)) {
+      throw new GitNotInstalledError();
+    }
+    throw err;
+  }
   let timedOut = false;
   const timer = setTimeout(() => {
     timedOut = true;
@@ -365,6 +411,14 @@ export const defaultGitSpawn: GitSpawn = async (argv, options) => {
  * Always cleans up the temp dir.
  */
 export async function cloneAndImport(opts: ImportOpts): Promise<ImportResult> {
+  // Fail fast + clean when git isn't installed — BEFORE the concurrency
+  // marker, tempdir creation, or any spawn. The route maps the resulting
+  // GitNotInstalledError to a friendly 503 (git_not_installed). Without
+  // this, the first `Bun.spawn(["git", ...])` threw a raw
+  // `Executable not found in $PATH: "git"` that only the generic 500 branch
+  // caught — the unhelpful failure mode found live on the gitcoin EC2 box.
+  ensureGitAvailable(opts.which);
+
   if (inFlight.has(opts.vaultName)) {
     throw new ImportConflictError(opts.vaultName);
   }
@@ -469,6 +523,10 @@ function importResultFromStats(
     tags_imported: stats.schemas_restored,
     attachments_imported: stats.attachments_restored,
     warnings,
+    // Default false; the route flips it true after wiring sync. Keeping the
+    // default here means a caller that bypasses the route (CLI, tests of
+    // cloneAndImport directly) gets a well-typed, conservative result.
+    sync_enabled: false,
   };
   if (mode === "replace") {
     result.notes_deleted = stats.notes_wiped;

package/src/mirror-manager.test.ts

@@ -215,6 +215,21 @@ describe("bootstrapInternalMirror", () => {
       expect(isGitRepoSync(dir)).toBe(true);
     }
   });
+
+  test("git missing → ok:false with actionable error (status surfaces it, no raw crash)", async () => {
+    // vault#415 — a git-less server can't bootstrap a mirror. The error
+    // channel carries the friendly message that MirrorManager.start threads
+    // into status.last_error, instead of a raw "Executable not found" crash.
+    dir = path.join(tmp("mirror-boot-nogit-"), "mirror");
+    const r = await bootstrapInternalMirror(dir, () => null);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("git is required");
+      expect(r.error).toContain("dnf install git");
+    }
+    // Failed fast at the preflight — the dir was never created.
+    expect(fs.existsSync(dir)).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -378,6 +393,42 @@ describe("MirrorManager.start — lifecycle matrix", () => {
     fs.rmSync(external, { recursive: true, force: true });
   });
 
+  test("external + git not installed → enabled:false with friendly error, never spawns/exports", async () => {
+    // vault#415 nit — the external branch's isGitRepo() check shells `git`
+    // with no preflight; on a git-less server it would throw a raw
+    // "Executable not found in $PATH: \"git\"" and crash start(). The
+    // top-of-start() preflight (forced via the `which` seam) lands the
+    // friendly, actionable message in last_error for the external location.
+    home = tmp("mgr-ext-nogit-installed-");
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+    // Use a real, valid external git repo so the ONLY thing that can fail is
+    // the git-presence preflight — proving the preflight (not the path/repo
+    // checks) produced the disabled state.
+    const external = tmp("mgr-ext-nogit-target-");
+    initRepo(external);
+    seedCommit(external);
+    const deps = makeFakeDeps({
+      parachuteHome: home,
+      initialConfig: {
+        ...defaultMirrorConfig(),
+        enabled: true,
+        location: "external",
+        external_path: external,
+        sync_mode: "events",
+      },
+    });
+    const mgr = new MirrorManager(deps);
+    // Force the preflight to see no git on PATH.
+    const status = await mgr.start(() => null);
+    expect(status.enabled).toBe(false);
+    expect(status.last_error).toContain("git is required");
+    expect(status.last_error).toContain("dnf install git");
+    // Never reached export — the preflight bailed before any git work.
+    expect(deps.exportCalls).toHaveLength(0);
+    await mgr.stop();
+    fs.rmSync(external, { recursive: true, force: true });
+  });
+
   test("internal bootstrap refuses to clobber pre-existing non-git data", async () => {
     home = tmp("mgr-int-clobber-");
     const mirrorPath = path.join(home, "vault", "data", "default", "mirror");