@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/src/config.test.ts

@@ -169,6 +169,33 @@ describe("config", () => {
     expect(loaded!.transcription).toBeUndefined();
   });
 
+  test("round-trips per-vault auto_transcribe.enabled (true + false)", () => {
+    // The PATCH /api/vault handler persists the per-vault toggle via
+    // writeVaultConfig; confirm it survives a read-back — this is the exact
+    // field shouldAutoTranscribe reads per-vault (per-vault → global → true).
+    const base: VaultConfig = {
+      name: "testvault",
+      api_keys: [],
+      created_at: "2026-01-01T00:00:00.000Z",
+    };
+
+    writeVaultConfig({ ...base, auto_transcribe: { enabled: true } });
+    expect(readVaultConfig("testvault")!.auto_transcribe?.enabled).toBe(true);
+
+    writeVaultConfig({ ...base, auto_transcribe: { enabled: false } });
+    expect(readVaultConfig("testvault")!.auto_transcribe?.enabled).toBe(false);
+  });
+
+  test("vault config without auto_transcribe loads as undefined (falls back to global)", () => {
+    const config: VaultConfig = {
+      name: "testvault",
+      api_keys: [],
+      created_at: "2026-01-01T00:00:00.000Z",
+    };
+    writeVaultConfig(config);
+    expect(readVaultConfig("testvault")!.auto_transcribe).toBeUndefined();
+  });
+
   test("round-trips discovery: enabled|disabled", () => {
     // Default: absent means enabled (endpoint serves names).
     writeGlobalConfig({ port: 1940 });
@@ -213,6 +240,72 @@ describe("config", () => {
     expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
   });
 
+  // ----- vault#234: anchored api_keys field regexes ----------------------
+  // The api_keys field regexes (label/scope/key_hash/created_at/last_used_at)
+  // used to be unanchored, so a COMMENTED `# scope: read` line matched, and a
+  // value-less `scope: ` (trailing space) captured the NEXT field's token
+  // (`key_hash`). The writer never emits either shape — only hand-editing
+  // reaches these branches — but a malformed scope could silently mis-scope a
+  // key. The regexes are now line-anchored + horizontal-whitespace-bounded.
+
+  test("vault#234: commented `# scope:` line is ignored, scope falls back to default", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234"), { recursive: true });
+    // The only `scope:` line is commented out; the parser must NOT pick it up.
+    fs.writeFileSync(
+      path,
+      `name: mv234\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_cmt\n    label: commented\n    # scope: read\n    key_hash: sha256:cmt\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234");
+    const key = loaded!.api_keys.find((k) => k.id === "k_cmt");
+    expect(key).toBeDefined();
+    // Commented scope ignored → default "write", NOT "read".
+    expect(key!.scope).toBe("write");
+    expect(key!.key_hash).toBe("sha256:cmt");
+  });
+
+  test("vault#234: value-less `scope: ` (trailing space) does NOT capture the next field", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b"), { recursive: true });
+    // `scope: ` has a trailing space and no value; the OLD regex skipped the
+    // newline and captured `sha256:trailing` (the key_hash) as the scope.
+    fs.writeFileSync(
+      path,
+      `name: mv234b\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_trail\n    label: trailing\n    scope: \n    key_hash: sha256:trailing\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234b");
+    const key = loaded!.api_keys.find((k) => k.id === "k_trail");
+    expect(key).toBeDefined();
+    // The hash must NOT have been borrowed as the scope.
+    expect(key!.scope).not.toBe("sha256:trailing");
+    expect(key!.scope).toBe("write"); // default
+    // And the real key_hash is still parsed correctly.
+    expect(key!.key_hash).toBe("sha256:trailing");
+  });
+
+  test("vault#234: a valid `scope: read` still parses (positive control, both parsers)", () => {
+    const fs = require("fs");
+    // Vault-level parser.
+    const vpath = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c"), { recursive: true });
+    fs.writeFileSync(
+      vpath,
+      `name: mv234c\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_v\n    label: reader\n    scope: read\n    key_hash: sha256:v\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    expect(readVaultConfig("mv234c")!.api_keys.find((k) => k.id === "k_v")?.scope).toBe("read");
+
+    // Global parser, same grammar.
+    const gpath = join(process.env.PARACHUTE_HOME!, "vault", "config.yaml");
+    fs.writeFileSync(
+      gpath,
+      `port: 1940\napi_keys:\n  - id: k_g\n    label: reader\n    # scope: write\n    scope: read\n    key_hash: sha256:g\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    // The commented `# scope: write` is skipped; the real `scope: read` wins.
+    expect(readGlobalConfig().api_keys?.find((k) => k.id === "k_g")?.scope).toBe("read");
+  });
+
   test("writeEnvFile writes .env at 0600 (SCRIBE_AUTH_TOKEN secrecy)", () => {
     // Regression for vault#354 reviewer finding: the .env holds
     // SCRIBE_AUTH_TOKEN (the vault↔scribe loopback bearer). On a
@@ -250,6 +343,22 @@ describe("config", () => {
     writeGlobalConfig({ port: 1940, autostart: false });
     expect(readGlobalConfig().autostart).toBe(false);
   });
+
+  test("round-trips default_mirror: internal|off", () => {
+    // Absent: createVault falls back to the in-code default ("internal" —
+    // backup-on-by-default). The knob is only persisted when explicitly set.
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().default_mirror).toBeUndefined();
+
+    // Explicit internal — new vaults get the History-preset local git mirror.
+    writeGlobalConfig({ port: 1940, default_mirror: "internal" });
+    expect(readGlobalConfig().default_mirror).toBe("internal");
+
+    // Explicit off — the opt-out operators set on git-less / disk-constrained
+    // / cloud boxes so new vaults are created with no mirror config.
+    writeGlobalConfig({ port: 1940, default_mirror: "off" });
+    expect(readGlobalConfig().default_mirror).toBe("off");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -115,6 +115,17 @@ export function vaultConfigPath(name: string): string {
   return join(vaultDir(name), "vault.yaml");
 }
 
+/**
+ * Per-vault attachments directory: `<vaultDir>/assets`, or the `ASSETS_DIR`
+ * env override when set (single-assets-root deployments). Lives here next to
+ * the other path helpers — neutral ground that both `routes.ts` (upload/serve)
+ * and `usage.ts` (footprint dir-walk) import without a cycle. `routes.ts`
+ * re-exports it for the existing callers (mirror-deps, server, triggers, …).
+ */
+export function assetsDir(name: string): string {
+  return process.env.ASSETS_DIR ?? join(vaultDir(name), "assets");
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -172,6 +183,23 @@ export interface VaultConfig {
   transcription?: {
     context?: TriggerIncludeContext[];
   };
+  /**
+   * Per-vault auto-transcribe override (vault#353 follow-up). When set, this
+   * vault's value takes precedence over the server-wide
+   * `GlobalConfig.auto_transcribe.enabled`. Resolution at the decision point
+   * (`shouldAutoTranscribe`) is **per-vault → global → true**: a vault that
+   * sets `enabled` here uses it; a vault that leaves it unset falls back to
+   * the global toggle, which itself defaults ON.
+   *
+   * This is what makes scribe's "link to vault X" genuinely per-vault —
+   * `PATCH /vault/X/api/vault {auto_transcribe:{enabled:true}}` flips only
+   * vault X, never the whole server. URL + bearer are still resolved per-
+   * process (services.json / SCRIBE_AUTH_TOKEN); only the on/off toggle is
+   * per-vault.
+   */
+  auto_transcribe?: {
+    enabled?: boolean;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -229,6 +257,20 @@ export interface TriggerAction {
    * top-level `context` field (send=json). send=content ignores this.
    */
   include_context?: TriggerIncludeContext[];
+  /**
+   * Optional webhook auth. When `auth.bearer` is set, the trigger sends
+   * `Authorization: Bearer <bearer>` on the webhook POST — the JWT path that
+   * retires the shared `?secret=` query param. Back-compat: a webhook URL
+   * carrying its own `?secret=` still works; `auth` is purely additive.
+   * Runtime triggers (registered via the /api/triggers REST surface) are the
+   * primary users; config.yaml triggers may also carry it.
+   */
+  auth?: TriggerAuth;
+}
+
+export interface TriggerAuth {
+  /** Bearer token (typically a hub-issued JWT) for the webhook Authorization header. */
+  bearer?: string;
 }
 
 export interface TriggerConfig {
@@ -270,6 +312,19 @@ export interface GlobalConfig {
    * point their own supervisor at it.
    */
   autostart?: boolean;
+  /**
+   * Boot auto-create marker (2026-06-09 hub-module-boundary migration, the
+   * vault wave's `cmdRemove` improvement). Server boot auto-creates a
+   * `default` vault when `listVaults()` is empty — the Docker / hub-install
+   * first-run path. When the operator EXPLICITLY deletes their last vault
+   * via `parachute-vault remove`, that auto-create would silently resurrect
+   * a fresh `default` (with fresh credentials) on the next boot. `cmdRemove`
+   * writes `auto_create: false` when it removes the last vault; boot skips
+   * the auto-create while the marker is present. Fresh installs (no
+   * config.yaml at all) never carry the marker, so the Docker first-run
+   * behavior is preserved. See `bootAutoCreateAllowed`.
+   */
+  auto_create?: boolean;
   /** Backup configuration: schedule, retention, destinations. */
   backup?: BackupConfig;
   /**
@@ -280,6 +335,29 @@ export interface GlobalConfig {
    * resolved path. See `./mirror-config.ts`.
    */
   mirror?: MirrorConfigType;
+  /**
+   * Server-wide DEFAULT for newly created vaults' backup posture. Decides
+   * whether `createVault` writes the History-preset internal mirror
+   * (local git backup of the markdown projection) at create time.
+   *
+   *   - `"internal"` (default) — new vaults get a local git mirror enabled
+   *     out of the box (backup-on-by-default). The History preset:
+   *     `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+   *     auto_push:false}`. GitHub off-site backup remains an opt-in upgrade.
+   *   - `"off"` — new vaults are created with no mirror config (the historical
+   *     pre-default behavior). The escape hatch for git-less / disk-constrained
+   *     boxes and cloud deploys, where doubling disk per vault is unwanted.
+   *     Cloud / container deploys SHOULD set this to `off`.
+   *
+   * Create-time ONLY — this knob does NOT retroactively enable mirrors on
+   * already-created vaults (that would ~double disk across every existing
+   * vault). Existing-vault opt-in is a separate, deliberate follow-up.
+   *
+   * The container/cloud first-boot auto-create path in `server.ts` does NOT
+   * funnel through `createVault`, so it is unaffected by this knob and stays
+   * mirror-off regardless — matching the recommended cloud posture.
+   */
+  default_mirror?: "internal" | "off";
   /**
    * Auto-transcribe configuration for the vault↔scribe handoff (vault#353,
    * design 2026-05-21 Part 2). When `enabled: true` AND scribe is discoverable
@@ -396,6 +474,14 @@ function serializeVaultConfig(config: VaultConfig): string {
     lines.push(`audio_retention: ${config.audio_retention}`);
   }
 
+  // Per-vault auto-transcribe override. Serialized as a nested block so future
+  // fields can grow under it (mirrors the GlobalConfig shape). Only emitted
+  // when `enabled` is explicitly set — an unset vault falls back to global.
+  if (config.auto_transcribe?.enabled !== undefined) {
+    lines.push("auto_transcribe:");
+    lines.push(`  enabled: ${config.auto_transcribe.enabled}`);
+  }
+
   if (config.transcription?.context?.length) {
     lines.push("transcription:");
     lines.push("  context:");
@@ -484,14 +570,32 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   }
 
   // Parse api_keys
+  //
+  // Accepted grammar (vault#234): each `id:` block is the writer's output —
+  // one field per line, indented two spaces under the `- id:` list item:
+  //
+  //     - id: <id>
+  //       label: <label>            # free text to end of line
+  //       scope: <scope>            # single token (read|write|admin|…)
+  //       key_hash: <hash>          # single token
+  //       created_at: "<iso>"       # quoted or bare, no embedded newline
+  //       last_used_at: "<iso>"
+  //
+  // Each field regex is line-anchored (`^...`, `m` flag) so a COMMENTED line
+  // (`# scope: read`) never matches — the line must begin with optional
+  // leading whitespace then the bare key. The value matcher uses horizontal
+  // whitespace only (`[^\S\r\n]*`, never `\s*`) after the colon so a
+  // value-less field (`scope: ` with a trailing space) can't skip the newline
+  // and capture the NEXT field's value. A missing optional field falls back to
+  // its default rather than borrowing a neighbor's token.
   const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
   for (const block of keyBlocks) {
     const idMatch = block.match(/^(\S+)/);
-    const labelMatch = block.match(/label:\s*(.+)/);
-    const scopeMatch = block.match(/scope:\s*(\S+)/);
-    const hashMatch = block.match(/key_hash:\s*(\S+)/);
-    const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-    const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+    const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+    const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+    const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+    const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+    const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
 
     if (idMatch && hashMatch) {
       config.api_keys.push({
@@ -514,6 +618,22 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
     config.transcription = { context: transcriptionContext };
   }
 
+  // Parse the per-vault auto_transcribe block — currently single boolean
+  // `enabled`. Nested 2-space-indent block (mirrors the GlobalConfig parser)
+  // so future fields can grow under it without breaking the regex.
+  const autoTranscribeStart = yaml.match(/^auto_transcribe:\s*$/m);
+  if (autoTranscribeStart) {
+    const after = yaml.slice((autoTranscribeStart.index ?? 0) + autoTranscribeStart[0].length);
+    for (const line of after.split("\n")) {
+      if (line.match(/^\S/) && line.trim().length > 0) break; // next top-level key
+      const m = line.match(/^\s+enabled:\s*(true|false)/);
+      if (m) {
+        config.auto_transcribe = { enabled: m[1]! === "true" };
+        break;
+      }
+    }
+  }
+
   return config;
 }
 
@@ -1151,6 +1271,20 @@ export function migrateVaultInternalLayout(): void {
 // Global config
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether server boot may auto-create the first vault when none exist.
+ *
+ * Only the explicit `auto_create: false` marker (written by `cmdRemove`
+ * when it deletes the LAST vault) blocks the auto-create. A fresh install
+ * has no config.yaml — `readGlobalConfig()` returns defaults with
+ * `auto_create` unset — so Docker / hub-install first-run still
+ * auto-creates `default`. Pure + exported so the boot gate is testable
+ * without booting a server.
+ */
+export function bootAutoCreateAllowed(config: Pick<GlobalConfig, "auto_create">): boolean {
+  return config.auto_create !== false;
+}
+
 export function readGlobalConfig(): GlobalConfig {
   try {
     const gcPath = globalConfigPath();
@@ -1162,6 +1296,8 @@ export function readGlobalConfig(): GlobalConfig {
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
+      const autoCreateMatch = yaml.match(/^auto_create:\s*(true|false)/m);
+      const defaultMirrorMatch = yaml.match(/^default_mirror:\s*(internal|off)/m);
       // auto_transcribe block — currently single boolean `enabled` (vault#353).
       // Parsed as a nested 2-space-indent block so future fields can grow under
       // it without breaking the regex; only `enabled` is read for v0.6.
@@ -1190,6 +1326,12 @@ export function readGlobalConfig(): GlobalConfig {
       if (autostartMatch) {
         config.autostart = autostartMatch[1]! === "true";
       }
+      if (autoCreateMatch) {
+        config.auto_create = autoCreateMatch[1]! === "true";
+      }
+      if (defaultMirrorMatch) {
+        config.default_mirror = defaultMirrorMatch[1]! as "internal" | "off";
+      }
       if (autoTranscribeEnabled !== undefined) {
         config.auto_transcribe = { enabled: autoTranscribeEnabled };
       }
@@ -1212,16 +1354,19 @@ export function readGlobalConfig(): GlobalConfig {
       }
 
       // Parse global api_keys
+      // Same line-anchored grammar as the vault-level parser above (vault#234)
+      // — commented lines don't match; a value-less field can't capture the
+      // next field's token across the newline.
       const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
       if (keyBlocks.length > 0) {
         config.api_keys = [];
         for (const block of keyBlocks) {
           const idMatch = block.match(/^(\S+)/);
-          const labelMatch = block.match(/label:\s*(.+)/);
-          const scopeMatch = block.match(/scope:\s*(\S+)/);
-          const hashMatch = block.match(/key_hash:\s*(\S+)/);
-          const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-          const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+          const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+          const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+          const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+          const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+          const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
           if (idMatch && hashMatch) {
             config.api_keys.push({
               id: idMatch[1]!,
@@ -1259,6 +1404,8 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   if (config.default_vault) lines.push(`default_vault: ${config.default_vault}`);
   if (config.discovery) lines.push(`discovery: ${config.discovery}`);
   if (config.autostart !== undefined) lines.push(`autostart: ${config.autostart}`);
+  if (config.auto_create !== undefined) lines.push(`auto_create: ${config.auto_create}`);
+  if (config.default_mirror) lines.push(`default_mirror: ${config.default_mirror}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);
   }

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"))
+  );
+}