@openparachute/vault 0.4.9-rc.8 → 0.4.9-rc.9

package/package.json

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

package/src/export-watch.test.ts

@@ -27,6 +27,7 @@ import {
   DEFAULT_COMMIT_TEMPLATE,
   gitAddAll,
   gitCommit,
+  gitPush,
   gitUnstageAll,
   isGitRepo,
   listStagedFiles,
@@ -315,6 +316,79 @@ describe("git-shell helpers", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// 2b. gitPush — first-push upstream tracking (Cut 4 of vault#392)
+//
+// A freshly-bootstrapped mirror has commits but no upstream branch.
+// Bare `git push` fails with "fatal: The current branch X has no upstream
+// branch." gitPush now detects the missing-upstream case and falls back
+// to `git push -u origin <branch>`. Subsequent pushes go bare.
+// ---------------------------------------------------------------------------
+
+describe("gitPush — upstream tracking", () => {
+  let workdir: string;
+  let remote: string;
+  beforeEach(() => {
+    workdir = makeTmp("vault-push-work-");
+    remote = makeTmp("vault-push-remote-");
+    // Bare repo as the "remote" — `git push` to it lands like any real remote.
+    Bun.spawnSync(["git", "init", "--bare", "-q", "-b", "main"], { cwd: remote });
+    initGitRepo(workdir);
+    Bun.spawnSync(["git", "remote", "add", "origin", remote], { cwd: workdir });
+    fs.writeFileSync(path.join(workdir, "seed.md"), "# seed\n");
+    Bun.spawnSync(["git", "add", "-A"], { cwd: workdir });
+    Bun.spawnSync(["git", "commit", "-q", "-m", "initial"], { cwd: workdir });
+  });
+  afterEach(() => {
+    fs.rmSync(workdir, { recursive: true, force: true });
+    fs.rmSync(remote, { recursive: true, force: true });
+  });
+
+  test("first push to a fresh remote establishes upstream tracking", async () => {
+    // Pre-Cut-4 this failed with "no upstream branch."
+    const result = await gitPush(workdir);
+    expect(result.ok).toBe(true);
+    // Verify upstream is now set so subsequent pushes can be bare.
+    const upstream = Bun.spawnSync(
+      ["git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+      { cwd: workdir, stdout: "pipe" },
+    );
+    expect(upstream.exitCode).toBe(0);
+    expect(
+      new TextDecoder().decode(upstream.stdout).trim(),
+    ).toBe("origin/main");
+  });
+
+  test("subsequent push (upstream already set) succeeds bare", async () => {
+    // First push wires the upstream.
+    await gitPush(workdir);
+    // Make another commit, push again — should succeed.
+    fs.writeFileSync(path.join(workdir, "n.md"), "# n\n");
+    Bun.spawnSync(["git", "add", "-A"], { cwd: workdir });
+    Bun.spawnSync(["git", "commit", "-q", "-m", "second"], { cwd: workdir });
+    const result = await gitPush(workdir);
+    expect(result.ok).toBe(true);
+  });
+
+  test("push with no remote configured surfaces the error (back-compat)", async () => {
+    // Same shape as the existing "no remote" test in runGitCommitCycle —
+    // the branch probe returns a branch but no upstream, gitPush falls
+    // back to `git push -u origin main`, which fails because there's no
+    // `origin` remote configured.
+    const localOnly = makeTmp("vault-push-noremote-");
+    initGitRepo(localOnly);
+    fs.writeFileSync(path.join(localOnly, "x.md"), "# x\n");
+    Bun.spawnSync(["git", "add", "-A"], { cwd: localOnly });
+    Bun.spawnSync(["git", "commit", "-q", "-m", "x"], { cwd: localOnly });
+    const result = await gitPush(localOnly);
+    expect(result.ok).toBe(false);
+    // Doesn't matter what the exact error is — just that it's non-fatal
+    // (gitPush returns rather than throws).
+    expect(typeof result.stderr).toBe("string");
+    fs.rmSync(localOnly, { recursive: true, force: true });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // 3. runGitCommitCycle — stage → decide → commit → push
 // ---------------------------------------------------------------------------

package/src/export-watch.ts

@@ -121,11 +121,72 @@ export async function gitCommit(
   return { ok: exitCode === 0, stderr: stderr.trim() };
 }
 
-/** Run `git push` in `repoDir`. Returns true on success. */
+/**
+ * Run `git push` in `repoDir`. Returns true on success.
+ *
+ * Handles the first-push case: a freshly-bootstrapped mirror has
+ * commits but no upstream tracking, and a bare `git push` fails with
+ * "fatal: The current branch X has no upstream branch." That's
+ * unrecoverable from the operator's POV — they'd have to drop to a
+ * shell and run `git push -u origin main`. The wiring here detects the
+ * missing-upstream case ahead of time and falls back to `git push -u
+ * origin <branch>` so the first push works and every subsequent push
+ * picks up the now-configured tracking.
+ *
+ * Vault#382 carried bare `git push`; this is the Cut 4 fix in the
+ * credentials-save round-trip work.
+ */
 export async function gitPush(
   repoDir: string,
 ): Promise<{ ok: boolean; stderr: string }> {
-  const proc = Bun.spawn(["git", "push"], {
+  // Resolve the current branch name. `git rev-parse --abbrev-ref HEAD`
+  // returns the branch on a checked-out branch (e.g. "main"); on a
+  // detached HEAD it returns "HEAD" — in that case we bail to bare push
+  // since `-u origin HEAD` doesn't mean anything useful.
+  let branch: string | null = null;
+  try {
+    const branchProc = Bun.spawn(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd: repoDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const branchCode = await branchProc.exited;
+    if (branchCode === 0) {
+      const out = new TextDecoder()
+        .decode(await new Response(branchProc.stdout).arrayBuffer())
+        .trim();
+      if (out.length > 0 && out !== "HEAD") branch = out;
+    }
+  } catch {
+    // Fall through to bare push.
+  }
+
+  // Probe for an existing upstream. `git rev-parse --abbrev-ref
+  // --symbolic-full-name @{u}` exits non-zero when no upstream is
+  // configured for the current branch. Exit 0 + a value → upstream
+  // exists; bare `git push` is fine.
+  let hasUpstream = false;
+  if (branch !== null) {
+    const upstreamProc = Bun.spawn(
+      ["git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+      {
+        cwd: repoDir,
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    );
+    const upstreamCode = await upstreamProc.exited;
+    hasUpstream = upstreamCode === 0;
+  }
+
+  // First-push path: `git push -u origin <branch>` to establish
+  // tracking. Subsequent calls take the bare path because hasUpstream
+  // will be true after this lands.
+  const cmd =
+    branch !== null && !hasUpstream
+      ? ["git", "push", "-u", "origin", branch]
+      : ["git", "push"];
+  const proc = Bun.spawn(cmd, {
     cwd: repoDir,
     stdout: "pipe",
     stderr: "pipe",
@@ -190,7 +251,14 @@ export function shouldCommit(stagedFiles: string[], notesChanged: number): {
 
 /**
  * Stage → decide → commit → optionally push. Logs status to stdout/stderr.
- * Returns whether a commit landed.
+ * Returns whether a commit landed and (when push was attempted) the
+ * push outcome — so callers can surface push status in their UIs
+ * without having to grep logs.
+ *
+ * Cut 5: the return shape now includes a `push` field with the outcome
+ * when push was attempted. Tokens are redacted from `push.error` via
+ * the userinfo + `gho_/ghp_/glpat-` regex so log + status surfaces are
+ * safe to display.
  */
 export async function runGitCommitCycle(opts: {
   repoDir: string;
@@ -201,7 +269,11 @@ export async function runGitCommitCycle(opts: {
   push: boolean;
   /** Override for tests — defaults to `new Date().toISOString()`. */
   now?: () => string;
-}): Promise<{ committed: boolean; message?: string }> {
+}): Promise<{
+  committed: boolean;
+  message?: string;
+  push?: { attempted: true; ok: boolean; error?: string };
+}> {
   const now = opts.now ?? (() => new Date().toISOString());
 
   const add = await gitAddAll(opts.repoDir);
@@ -245,11 +317,40 @@ export async function runGitCommitCycle(opts: {
     if (!pushResult.ok) {
       // Non-fatal — a network blip shouldn't kill a watch loop. Warn and
       // move on; the next successful commit's push will catch up history.
-      console.warn(`[git-commit] git push failed (non-fatal): ${pushResult.stderr}`);
-    } else {
-      console.log(`[git-commit] pushed`);
+      const redacted = redactToken(pushResult.stderr);
+      console.warn(`[git-commit] git push failed (non-fatal): ${redacted}`);
+      return {
+        committed: true,
+        message,
+        push: { attempted: true, ok: false, error: redacted },
+      };
     }
+    console.log(`[git-commit] pushed`);
+    return { committed: true, message, push: { attempted: true, ok: true } };
   }
 
   return { committed: true, message };
 }
+
+/**
+ * Redact tokens from a string that came back from `git push` /
+ * `git ls-remote` stderr. Same pattern as `redactRemoteUrl` for full
+ * URLs; also handles bare `gho_*`/`ghp_*`/`glpat-*` tokens that
+ * sometimes show up in git error messages.
+ *
+ * Best-effort — git's error format isn't a stable contract, so we
+ * scrub the obvious patterns and accept that a really unusual
+ * formatting could slip through. The credentials file is the
+ * authoritative store; logs are diagnostic.
+ */
+export function redactToken(text: string): string {
+  return text
+    // userinfo (https://user:token@host/…)
+    .replace(/https?:\/\/[^@\s]+@/g, "https://***@")
+    // bare GitHub OAuth tokens
+    .replace(/gho_[A-Za-z0-9_]{8,}/g, "gho_***")
+    // bare GitHub PATs
+    .replace(/ghp_[A-Za-z0-9_]{8,}/g, "ghp_***")
+    // bare GitLab PATs
+    .replace(/glpat-[A-Za-z0-9_-]{8,}/g, "glpat-***");
+}

package/src/mirror-config.test.ts

@@ -333,17 +333,76 @@ describe("validateMirrorConfigShape", () => {
     if (r.ok) expect(r.config.sync_mode).toBe("manual");
   });
 
-  test("rejects auto_push + internal location (validation rather than silent-fail)", () => {
-    // Pre-event-driven shape silently let push fail at runtime for
-    // internal mirrors. Now we reject the combination at config time so
-    // the operator sees the issue immediately.
-    const r = validateMirrorConfigShape({
-      enabled: true,
-      location: "internal",
-      auto_push: true,
-    });
+  test("rejects auto_push + internal location WHEN no credentials are configured", () => {
+    // Pre-credentials shape: auto_push + internal was rejected outright
+    // (internal mirror = no remote = push would silently fail). Once
+    // credentials are wired (PAT or GitHub OAuth), the credential save
+    // path sets `origin` on the internal repo too — so push IS
+    // meaningful. We keep the rejection only on the no-credentials path,
+    // with a clear error pointing the operator at the credential flow.
+    const r = validateMirrorConfigShape(
+      {
+        enabled: true,
+        location: "internal",
+        auto_push: true,
+      },
+      { readCredentials: () => null },
+    );
     expect(r.ok).toBe(false);
-    if (!r.ok) expect(r.field).toBe("auto_push");
+    if (!r.ok) {
+      expect(r.field).toBe("auto_push");
+      expect(r.error).toContain("credentials");
+    }
+  });
+
+  test("auto_push + internal IS accepted when PAT credentials are configured", () => {
+    // The three-stacking-gaps bug Aaron hit: History preset (internal
+    // location) + PAT saved → expected pushes to fire. validation was
+    // the first blocker. Now the combination passes when credentials
+    // are present.
+    const r = validateMirrorConfigShape(
+      {
+        enabled: true,
+        location: "internal",
+        auto_push: true,
+      },
+      {
+        readCredentials: () => ({
+          active_method: "pat",
+          github_oauth: null,
+          pat: {
+            token: "ghp_xxxxxxxxxxxxxxxx",
+            remote_url: "https://x-access-token:ghp_xxxxxxxxxxxxxxxx@github.com/a/b.git",
+            label: "test",
+          },
+        }),
+      },
+    );
+    expect(r.ok).toBe(true);
+  });
+
+  test("auto_push + internal IS accepted when github_oauth credentials are configured", () => {
+    const r = validateMirrorConfigShape(
+      {
+        enabled: true,
+        location: "internal",
+        auto_push: true,
+      },
+      {
+        readCredentials: () => ({
+          active_method: "github_oauth",
+          github_oauth: {
+            access_token: "gho_xxxxxxxxxxxx",
+            scope: "repo",
+            authorized_at: "2026-05-28T03:14:15.000Z",
+            user_login: "aaron",
+            user_id: 1,
+          },
+          pat: null,
+        }),
+      },
+    );
+    expect(r.ok).toBe(true);
   });
 
   test("auto_push + external location is fine", () => {

package/src/mirror-config.ts

@@ -23,6 +23,7 @@ import { existsSync, statSync } from "fs";
 import { join } from "path";
 
 import { DEFAULT_COMMIT_TEMPLATE, isGitRepo } from "./export-watch.ts";
+import { readCredentials, type MirrorCredentials } from "./mirror-credentials.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -372,12 +373,21 @@ export type ShapeValidation = ShapeValidationOk | ShapeValidationError;
  * `defaultMirrorConfig()`; rejects values that don't conform to the
  * declared types.
  *
- * Does NOT touch the filesystem — operators get a fast 400 on shape
- * errors before vault attempts any filesystem work. Filesystem-level
- * validation (path exists, is a git repo) lives in `validateExternalPath`.
+ * Mostly pure: the one filesystem touch is reading
+ * `.mirror-credentials.yaml` to decide whether `auto_push: true +
+ * location: internal` is acceptable (credentials carry a remote URL, so
+ * "internal mirrors have no remote" no longer holds). The credentials
+ * read is injectable via `opts.readCredentials` so tests stay hermetic;
+ * production callers omit it and pick up the canonical `readCredentials`
+ * from `./mirror-credentials.ts`.
+ *
+ * Filesystem-level validation of `external_path` (exists, is a git repo)
+ * still lives in `validateExternalPath` — that's I/O and stays out of
+ * this function.
  */
 export function validateMirrorConfigShape(
   input: unknown,
+  opts: { readCredentials?: () => MirrorCredentials | null } = {},
 ): ShapeValidation {
   if (input === null || typeof input !== "object") {
     return {
@@ -544,21 +554,60 @@ export function validateMirrorConfigShape(
     };
   }
 
-  // Cross-field rule: auto_push only makes sense for external mirrors —
-  // internal mirrors live under vault's data dir with no configured
-  // remote. Silent-fail on push was the pre-event-driven behavior; the
-  // backend now rejects the combination so the operator sees the issue
-  // at config time. The UI hides the auto_push checkbox when location
-  // is internal (vault#380's reviewer-flagged nit), so this only fires
-  // when an operator either edits config.yaml by hand or POSTs a bare
-  // JSON body with mismatched fields.
+  // Cross-field rule: auto_push + internal location was historically
+  // rejected outright — the assumption being "internal mirrors live under
+  // vault's data dir with no configured remote, so push would always
+  // fail." That assumption no longer holds once credentials are wired:
+  // the credential save path (handleAuthPat / handleAuthGithubSelectRepo)
+  // sets `origin` on the internal repo to the embedded-credential URL,
+  // so `git push` to GitHub/GitLab/etc. is meaningful even when the
+  // working tree lives under `~/.parachute/vault/data/<name>/mirror/`.
+  //
+  // New rule: auto_push + internal is rejected ONLY when no credentials
+  // are configured. If credentials ARE wired (PAT or GitHub OAuth),
+  // accept the combination — vault has a remote to push to. Operators
+  // hitting Aaron's three-stacking-gaps bug (History preset + PAT saved,
+  // pushes never fire) get unblocked.
+  //
+  // Asymmetry note (reviewer-flagged on vault#392): external + auto_push +
+  // no vault-stored credentials is INTENTIONALLY not rejected here.
+  // External mirrors are operator-managed paths — operators may have
+  // configured push credentials via system-level git config (SSH agent,
+  // ~/.git-credentials, GH_TOKEN env, `gh auth login`), none of which
+  // vault can detect by reading `.mirror-credentials.yaml`. Rejecting on
+  // "vault doesn't see credentials" would refuse legitimate
+  // operator-managed setups. Push failures on missing credentials surface
+  // via the non-fatal warning path in gitPush — operators see them in
+  // `last_push_error` rather than being blocked at save time. Internal
+  // location is different: internal mirrors live under vault's data
+  // dir, so vault IS the only thing that can wire a remote, which is
+  // why the gate below requires vault-stored credentials specifically.
   if (out.enabled && out.auto_push && out.location === "internal") {
-    return {
-      ok: false,
-      field: "auto_push",
-      error:
-        "`auto_push: true` requires `location: external` (internal mirrors live under the vault data directory and have no configured remote). Switch the location, or set auto_push to false.",
-    };
+    const readCreds = opts.readCredentials ?? readCredentials;
+    let creds: MirrorCredentials | null = null;
+    try {
+      creds = readCreds();
+    } catch {
+      // If the credentials file is unreadable we conservatively fail
+      // closed — same outcome as "no credentials." Better to surface the
+      // actionable "configure credentials first" error than to accept a
+      // config that won't actually push.
+      creds = null;
+    }
+    const hasCredentials = !!(
+      creds &&
+      creds.active_method &&
+      ((creds.active_method === "pat" && creds.pat) ||
+        (creds.active_method === "github_oauth" && creds.github_oauth))
+    );
+    if (!hasCredentials) {
+      return {
+        ok: false,
+        field: "auto_push",
+        error:
+          "Configure git credentials before enabling auto-push on an internal mirror — vault has no remote to push to without them. Connect GitHub or paste a Personal Access Token in the Git remote section, or set auto_push to false.",
+      };
+    }
   }
 
   return { ok: true, config: out };

package/src/mirror-manager.test.ts

@@ -855,3 +855,107 @@ describe("MirrorManager — event-driven (sync_mode: events)", () => {
     await mgr.stop();
   });
 });
+
+// ---------------------------------------------------------------------------
+// MirrorManager.pushNow — Cut 6 of vault#392 (credentials → push round-trip)
+//
+// Live `git push` against a local bare repo as the "remote." Tests the
+// status mutations (last_push_at, last_push_sha, last_push_error,
+// commits_unpushed) the SPA renders.
+// ---------------------------------------------------------------------------
+
+describe("MirrorManager.pushNow — push observability", () => {
+  let home: string;
+  let remote: string;
+
+  afterEach(async () => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+    if (remote) fs.rmSync(remote, { recursive: true, force: true });
+  });
+
+  test("returns not_enabled when mirror is disabled", async () => {
+    home = tmp("mgr-pushnow-disabled-");
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+    const deps = makeFakeDeps({
+      parachuteHome: home,
+      initialConfig: { ...defaultMirrorConfig(), enabled: false },
+    });
+    const mgr = new MirrorManager(deps);
+    await mgr.start();
+    const r = await mgr.pushNow();
+    expect(r.fired).toBe(false);
+    if (r.fired === false) expect(r.reason).toBe("not_enabled");
+  });
+
+  test("first push wires upstream and sets last_push_at + last_push_sha", async () => {
+    // Spin up an enabled internal mirror; wire a local bare repo as
+    // origin; verify pushNow lands the seed commit and updates status.
+    home = tmp("mgr-pushnow-first-");
+    remote = tmp("mgr-pushnow-remote-");
+    Bun.spawnSync(["git", "init", "--bare", "-q", "-b", "main"], { cwd: remote });
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+    const deps = makeFakeDeps({
+      parachuteHome: home,
+      initialConfig: {
+        ...defaultMirrorConfig(),
+        enabled: true,
+        location: "internal",
+        sync_mode: "manual",
+        auto_commit: false,
+      },
+    });
+    const mgr = new MirrorManager(deps);
+    const status = await mgr.start();
+    expect(status.enabled).toBe(true);
+    // Wire origin to the bare repo. The internal-mirror's first commit
+    // (`initial mirror bootstrap`) is sitting on HEAD waiting to push.
+    Bun.spawnSync(["git", "remote", "add", "origin", remote], { cwd: status.mirror_path! });
+
+    const result = await mgr.pushNow();
+    expect(result.fired).toBe(true);
+    if (result.fired) {
+      expect(result.pushed).toBe(true);
+      expect(typeof result.sha).toBe("string");
+    }
+    const after = mgr.getStatus();
+    expect(after.last_push_at).not.toBeNull();
+    expect(after.last_push_sha).not.toBeNull();
+    expect(after.last_push_error).toBeNull();
+    expect(after.commits_unpushed).toBe(0);
+    await mgr.stop();
+  });
+
+  test("push failure surfaces redacted error in last_push_error", async () => {
+    // Wire origin to a non-existent host. Push fails; status reflects
+    // the failure without leaking any potentially-sensitive URL parts.
+    home = tmp("mgr-pushnow-fail-");
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+    const deps = makeFakeDeps({
+      parachuteHome: home,
+      initialConfig: {
+        ...defaultMirrorConfig(),
+        enabled: true,
+        location: "internal",
+        sync_mode: "manual",
+        auto_commit: false,
+      },
+    });
+    const mgr = new MirrorManager(deps);
+    const status = await mgr.start();
+    Bun.spawnSync(
+      ["git", "remote", "add", "origin", "https://x-access-token:ghp_fake1234567890abcdef@nonexistent.parachute.test/a/b.git"],
+      { cwd: status.mirror_path! },
+    );
+    const result = await mgr.pushNow();
+    expect(result.fired).toBe(true);
+    if (result.fired) expect(result.pushed).toBe(false);
+    const after = mgr.getStatus();
+    expect(after.last_push_error).not.toBeNull();
+    // Redacted — no token leak.
+    expect(after.last_push_error).not.toContain("ghp_fake1234567890");
+    // Last successful push timestamp is unchanged (still null on a
+    // never-succeeded mirror).
+    expect(after.last_push_at).toBeNull();
+    await mgr.stop();
+  }, 30_000);
+});