@openparachute/vault 0.6.0-rc.1 → 0.6.0

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

package/src/mirror-manager.ts

@@ -75,6 +75,7 @@ import {
   applyToGitRemote,
   readCredentials,
 } from "./mirror-credentials.ts";
+import { GitNotInstalledError, ensureGitAvailable } from "./git-preflight.ts";
 import type { HookRegistry } from "../core/src/hooks.ts";
 
 /**
@@ -230,7 +231,20 @@ export type BootstrapResult = BootstrapResultOk | BootstrapResultError;
  */
 export async function bootstrapInternalMirror(
   path: string,
+  // Test seam for the git-presence preflight (default `Bun.which`). Inject a
+  // fn returning `null` to exercise the git-not-installed bootstrap path.
+  which?: (cmd: string) => string | null,
 ): Promise<BootstrapResult> {
+  // Preflight: a git-less server can't bootstrap a mirror. Surface the
+  // friendly, actionable message into the bootstrap-error channel so the
+  // caller threads it into mirror status (`last_error`) rather than letting
+  // a raw `Executable not found in $PATH: "git"` crash out of the spawn.
+  try {
+    ensureGitAvailable(which);
+  } catch (err) {
+    return { ok: false, error: (err as Error).message };
+  }
+
   if (existsSync(path)) {
     let stat;
     try {
@@ -466,7 +480,11 @@ export class MirrorManager {
    * Returns the final status snapshot — useful for tests + the PUT
    * endpoint response.
    */
-  async start(): Promise<MirrorStatus> {
+  async start(
+    // Test seam for the git-presence preflight (default `Bun.which`). Inject
+    // a fn returning `null` to exercise the git-not-installed start path.
+    which?: (cmd: string) => string | null,
+  ): Promise<MirrorStatus> {
     this.startCount++;
     await this.stop({ preserveStatus: true });
 
@@ -501,6 +519,24 @@ export class MirrorManager {
     }
     this.status.mirror_path = path;
 
+    // Preflight git BEFORE branching on location. Both branches shell `git`
+    // (internal → bootstrapInternalMirror; external → isGitRepo). On a
+    // git-less server the external branch's `isGitRepo` would otherwise throw
+    // a raw "Executable not found in $PATH: \"git\"" and crash start();
+    // catching it here lands the friendly, actionable message in
+    // status.last_error (disabled) for either location, uniformly.
+    try {
+      ensureGitAvailable(which);
+    } catch (err) {
+      if (err instanceof GitNotInstalledError) {
+        this.status.enabled = false;
+        this.status.last_error = err.message;
+        console.warn(`[mirror] ${err.message}`);
+        return this.getStatus();
+      }
+      throw err;
+    }
+
     // Internal bootstrap. External path is the operator's responsibility —
     // they should have validated via the PUT endpoint before we hit boot.
     // We re-check `isGitRepo` defensively here either way; a missing/non-
@@ -641,9 +677,13 @@ export class MirrorManager {
    * the operator-intended config on disk; on the next vault boot it
    * applies cleanly.
    */
-  async reload(newConfig: MirrorConfig): Promise<MirrorStatus> {
+  async reload(
+    newConfig: MirrorConfig,
+    // Test seam forwarded to `start()` — see `start(which)`.
+    which?: (cmd: string) => string | null,
+  ): Promise<MirrorStatus> {
     this.deps.writeMirrorConfig(newConfig);
-    return this.start();
+    return this.start(which);
   }
 
   /**
@@ -887,14 +927,25 @@ export class MirrorManager {
     }
 
     const firstNoteTitle = await this.deps.firstChangedNoteTitle(sinceCursor);
-    const commitResult = await runGitCommitCycle({
-      repoDir: path,
-      template: this.currentConfig.commit_template,
-      notesChanged: totalChanged,
-      vaultName: this.deps.vaultName,
-      firstNoteTitle,
-      push: this.currentConfig.auto_push,
-    });
+    let commitResult: Awaited<ReturnType<typeof runGitCommitCycle>>;
+    try {
+      commitResult = await runGitCommitCycle({
+        repoDir: path,
+        template: this.currentConfig.commit_template,
+        notesChanged: totalChanged,
+        vaultName: this.deps.vaultName,
+        firstNoteTitle,
+        push: this.currentConfig.auto_push,
+      });
+    } catch (err) {
+      // git-not-installed (or any commit-cycle throw) lands in status as a
+      // friendly last_error rather than crashing the cycle. Matches the
+      // "errors reflected in last_error, never rethrown" contract above.
+      const msg = (err as Error).message ?? String(err);
+      this.status.last_error = `commit cycle failed: ${msg}`;
+      console.warn(`[mirror] ${this.status.last_error}`);
+      return;
+    }
 
     if (commitResult.committed) {
       // Resolve the new HEAD sha so the status displays the commit that
@@ -950,6 +1001,17 @@ export class MirrorManager {
     if (!this.status.enabled) return { fired: false, reason: "not_enabled" };
     if (!this.status.mirror_path) return { fired: false, reason: "no_mirror_path" };
     const path = this.status.mirror_path;
+    // Preflight: git-less server can't push. Surface the friendly message
+    // into last_push_error (the SPA renders it) rather than throwing a raw
+    // "Executable not found" out of the gitPush spawn.
+    try {
+      ensureGitAvailable();
+    } catch (err) {
+      const msg = (err as Error).message ?? String(err);
+      this.status.last_push_error = msg;
+      console.warn(`[mirror] push-now failed: ${msg}`);
+      return { fired: true, pushed: false, error: msg };
+    }
     const pushResult = await gitPush(path);
     const now = new Date().toISOString();
     // Refresh commits_unpushed either way — a no-op push still reflects