@staix/vault-mem 0.0.0-bootstrap.0 → 0.1.0

package/src/setup.ts

@@ -0,0 +1,214 @@
+import { closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { fileURLToPath } from "node:url";
+
+/** Hosts whose MCP configuration `vmem setup` can register; `all` covers every user-level host (not agy). */
+export const SETUP_TARGETS = ["claude", "codex", "kimi", "pi", "qwen", "jcode", "agy"] as const;
+export type SetupTarget = typeof SETUP_TARGETS[number];
+export type SetupMode = "dry-run" | "apply" | "undo";
+export const SERVER_NAME = "vmem";
+const MAX_HOST_CONFIG = 4 * 1024 * 1024;
+export interface McpEntry { command: string; args: string[] }
+interface HostFile { target: SetupTarget; file: string; format: "json" | "toml"; key: string }
+export interface SetupAction { target: SetupTarget; file: string; change: "add" | "replace" | "unchanged" | "restore" | "remove" | "refused" | "none"; reason?: string }
+export interface SetupReport { mode: SetupMode; applied: boolean; entry: McpEntry; actions: SetupAction[]; notes: string[] }
+interface Receipt { version: 1; target: SetupTarget; file: string; existed: boolean; keyExisted?: boolean; prior: unknown; priorToml?: string[]; installed: McpEntry }
+
+function hosts(env: NodeJS.ProcessEnv, cwd: string): Record<SetupTarget, HostFile> {
+  const home = env.HOME?.trim() || homedir();
+  const dir = (key: string, fallback: string) => {
+    const value = env[key]?.trim();
+    if (!value) return join(home, fallback);
+    if (!isAbsolute(value)) throw new Error(`setup: ${key} must be absolute`);
+    return resolve(value);
+  };
+  const claude = env.CLAUDE_CONFIG_DIR?.trim() ? join(dir("CLAUDE_CONFIG_DIR", ".claude"), ".claude.json") : join(home, ".claude.json");
+  return {
+    claude: { target: "claude", file: claude, format: "json", key: "mcpServers" },
+    codex: { target: "codex", file: join(dir("CODEX_HOME", ".codex"), "config.toml"), format: "toml", key: "mcp_servers" },
+    kimi: { target: "kimi", file: join(dir("KIMI_CODE_HOME", ".kimi-code"), "mcp.json"), format: "json", key: "mcpServers" },
+    pi: { target: "pi", file: join(dir("PI_CODING_AGENT_DIR", ".pi/agent"), "mcp.json"), format: "json", key: "mcpServers" },
+    qwen: { target: "qwen", file: join(dir("QWEN_HOME", ".qwen"), "settings.json"), format: "json", key: "mcpServers" },
+    jcode: { target: "jcode", file: join(dir("JCODE_HOME", ".jcode"), "mcp.json"), format: "json", key: "servers" },
+    agy: { target: "agy", file: join(resolve(cwd), ".agents", "mcp_config.json"), format: "json", key: "mcpServers" },
+  };
+}
+function readText(file: string): string | null {
+  let stat;
+  try { stat = lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+  if (!stat.isFile()) throw new Error(`${file}: expected a plain file (links are refused)`);
+  if (stat.size > MAX_HOST_CONFIG) throw new Error(`${file}: exceeds 4 MiB`);
+  return readFileSync(file, "utf8");
+}
+function atomicWrite(file: string, text: string | null): void {
+  if (text === null) { unlinkSync(file); return; }
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  let mode = 0o600;
+  try { mode = statSync(file).mode & 0o777; } catch { /* new file */ }
+  const temp = join(dirname(file), `.${SERVER_NAME}-setup-${randomUUID()}.tmp`);
+  const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, mode);
+  try { writeFileSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+  try { renameSync(temp, file); } catch (error) { try { unlinkSync(temp); } catch { /* best effort */ } throw error; }
+}
+const record = (value: unknown, label: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}: expected an object`);
+  return value as Record<string, unknown>;
+};
+
+// TOML: edit only the `[mcp_servers.vmem]` table (and its subtables) textually so unrelated bytes stay identical.
+const tomlHeader = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/;
+/** Every table owned by the entry (`[mcp_servers.vmem]` and any `[mcp_servers.vmem.*]`), wherever it appears. */
+function tomlSpans(lines: string[]): [number, number][] {
+  const own = (name: string) => {
+    const key = name.replace(/\s*\.\s*/g, ".").replace(/"vmem"/g, SERVER_NAME);
+    return key === `mcp_servers.${SERVER_NAME}` || key.startsWith(`mcp_servers.${SERVER_NAME}.`);
+  };
+  const spans: [number, number][] = [];
+  let start = -1;
+  for (let i = 0; i <= lines.length; i++) {
+    const header = i < lines.length ? tomlHeader.exec(lines[i]!) : null;
+    if (i < lines.length && !header) continue;
+    if (start >= 0) {
+      let stop = i;
+      while (stop > start && lines[stop - 1]!.trim() === "") stop--;
+      spans.push([start, stop]); start = -1;
+    }
+    if (header && own(header[1]!)) start = i;
+  }
+  return spans;
+}
+function tomlString(value: string): string { return JSON.stringify(value); }
+function readEntry(host: HostFile, text: string | null): unknown {
+  if (text === null) return undefined;
+  if (host.format === "toml") {
+    const doc = record(Bun.TOML.parse(text), host.file);
+    return doc.mcp_servers === undefined ? undefined : record(doc.mcp_servers, `${host.file} mcp_servers`)[SERVER_NAME];
+  }
+  let doc: unknown;
+  try { doc = JSON.parse(text); } catch { throw new Error(`${host.file}: not strict JSON; edit it by hand or fix it first`); }
+  const servers = record(doc, host.file)[host.key];
+  return servers === undefined ? undefined : record(servers, `${host.file} ${host.key}`)[SERVER_NAME];
+}
+function tomlBlock(text: string | null): string[] | undefined {
+  const lines = text ? text.split(/\r?\n/) : [], spans = tomlSpans(lines);
+  return spans.length ? spans.flatMap(([start, stop]) => lines.slice(start, stop)) : undefined;
+}
+/** Replace the vmem entry. TOML takes either an entry value or the exact prior block lines to restore. */
+function putEntry(host: HostFile, text: string | null, value: unknown, rawToml?: string[], keepKey = false): string | null {
+  if (host.format === "toml") {
+    const source = text ?? "", newline = source.includes("\r\n") ? "\r\n" : "\n";
+    const lines = source.length ? source.split(/\r?\n/) : [];
+    const spans = tomlSpans(lines);
+    let block: string[] = rawToml ?? [];
+    if (!rawToml && value !== undefined) {
+      const entry = record(value, "entry");
+      block = [`[mcp_servers.${SERVER_NAME}]`, ...Object.entries(entry).map(([key, v]) => `${key} = ${Array.isArray(v) ? `[${v.map(item => tomlString(String(item))).join(", ")}]` : typeof v === "string" ? tomlString(v) : JSON.stringify(v)}`)];
+    }
+    if (spans.length) {
+      // Remove every owned table (last first so indexes stay valid), then insert at the first one.
+      // A later removed table also takes the blank separator just above it; blank runs elsewhere are untouched.
+      for (const [start, stop] of [...spans].reverse()) {
+        let from = start;
+        if (start !== spans[0]![0]) while (from > 0 && lines[from - 1]!.trim() === "") from--;
+        lines.splice(from, stop - from);
+      }
+      lines.splice(spans[0]![0], 0, ...block);
+    } else if (block.length) {
+      while (lines.length && lines[lines.length - 1] === "") lines.pop();
+      if (lines.length) lines.push("");
+      lines.push(...block);
+    }
+    while (lines.length && lines[lines.length - 1] === "") lines.pop();
+    const out = lines.length ? lines.join(newline) + newline : "";
+    Bun.TOML.parse(out); // never publish a file the host cannot parse
+    return out;
+  }
+  const doc = text === null ? {} : record(JSON.parse(text), host.file);
+  const servers = { ...record(doc[host.key] ?? {}, `${host.file} ${host.key}`) };
+  if (value === undefined) delete servers[SERVER_NAME]; else servers[SERVER_NAME] = value;
+  if (Object.keys(servers).length || keepKey) doc[host.key] = servers; else delete doc[host.key];
+  const indent = text && /\n(\t| +)"/.exec(text)?.[1] || "  ";
+  return JSON.stringify(doc, null, indent) + "\n";
+}
+function hasKey(host: HostFile, text: string | null): boolean {
+  if (text === null) return false;
+  const doc = host.format === "toml" ? Bun.TOML.parse(text) as Record<string, unknown> : JSON.parse(text) as Record<string, unknown>;
+  return Object.hasOwn(doc, host.key);
+}
+/** One receipt per host configuration file, so host profiles sharing VMEM_HOME never share a receipt. */
+function receiptFile(home: string, target: SetupTarget, file: string): string {
+  return join(home, "setup", `${target}-${createHash("sha256").update(resolve(file)).digest("hex").slice(0, 16)}.json`);
+}
+function readReceipt(file: string): Receipt | undefined {
+  const text = readText(file);
+  if (text === null) return undefined;
+  const value = JSON.parse(text) as Receipt;
+  if (value?.version !== 1 || typeof value.file !== "string") throw new Error(`${file}: unreadable setup receipt`);
+  return value;
+}
+export function defaultEntry(): McpEntry {
+  return { command: process.execPath, args: ["--smol", fileURLToPath(new URL("../bin/vmem.js", import.meta.url)), "mcp"] };
+}
+/**
+ * Plan, apply or undo vmem MCP registration. Dry-run writes nothing. Apply is idempotent, edits only
+ * the `vmem` server entry and records the prior value. Undo restores that prior value only while the
+ * entry is still the one setup installed; a later user edit is left alone and reported as refused.
+ */
+export function runSetup(target: string, mode: SetupMode, options: { home: string; env?: NodeJS.ProcessEnv; cwd?: string; entry?: McpEntry }): SetupReport {
+  const env = options.env ?? process.env, entry = options.entry ?? defaultEntry();
+  if (target !== "all" && !(SETUP_TARGETS as readonly string[]).includes(target)) throw new Error(`setup: unknown target ${target}; use ${SETUP_TARGETS.join("|")}|all`);
+  if (!isAbsolute(entry.command) || entry.args.some(arg => arg.includes("\0"))) throw new Error("setup: MCP command must be absolute");
+  const table = hosts(env, options.cwd ?? process.cwd());
+  const targets = target === "all" ? SETUP_TARGETS.filter(t => t !== "agy") : [target as SetupTarget];
+  const report: SetupReport = { mode, applied: false, entry, actions: [], notes: [
+    "Registers the stdio server `vmem mcp`; restart the host session to load it.",
+    "No console plugin manifest is written: vmem ships no console plugin yet.",
+  ] };
+  if (target === "all") report.notes.push("`all` covers user-level hosts; run `vmem setup agy` inside a workspace for Antigravity.");
+  for (const name of targets) {
+    const host = table[name], receiptPath = receiptFile(options.home, name, host.file);
+    const action: SetupAction = { target: name, file: host.file, change: "none" };
+    report.actions.push(action);
+    try {
+      const text = readText(host.file), current = readEntry(host, text), receipt = readReceipt(receiptPath);
+      if (receipt && resolve(receipt.file) !== resolve(host.file)) throw new Error(`${receiptPath}: receipt belongs to ${receipt.file}, not ${host.file}`);
+      if (mode === "undo") {
+        if (!receipt) { action.change = "none"; action.reason = "no setup receipt"; continue; }
+        if (current !== undefined && !isDeepStrictEqual(current, receipt.installed)) { action.change = "refused"; action.reason = "vmem entry changed after setup; left as is"; continue; }
+        if (current === undefined) { action.change = "none"; action.reason = "vmem entry already absent; nothing restored"; unlinkSync(receiptPath); continue; }
+        action.change = receipt.prior === undefined || receipt.prior === null ? "remove" : "restore";
+        {
+          let next = current === undefined ? text : putEntry(host, text, receipt.prior ?? undefined, receipt.priorToml, receipt.keyExisted === true);
+          // A file setup created is removed again only when nothing else was added to it.
+          if (!receipt.existed && next !== null && readEntry(host, next) === undefined && isDeepStrictEqual(host.format === "toml" ? Bun.TOML.parse(next) : JSON.parse(next), {})) next = null;
+          if (next !== text && (next !== null || text !== null)) atomicWrite(host.file, next);
+          unlinkSync(receiptPath);
+        }
+        continue;
+      }
+      if (isDeepStrictEqual(current, entry)) { action.change = "unchanged"; continue; }
+      action.change = current === undefined ? "add" : "replace";
+      if (mode === "apply") {
+        const next = putEntry(host, text, entry);
+        // Keep the original prior value across repeated applies.
+        const prior: Receipt = receipt ?? { version: 1, target: name, file: host.file, existed: text !== null, keyExisted: hasKey(host, text), prior: current ?? null, ...(host.format === "toml" && current !== undefined ? { priorToml: tomlBlock(text) } : {}), installed: entry };
+        // The receipt is durable before the host file changes; a failed host write rolls the receipt back.
+        const previousReceipt = readText(receiptPath);
+        atomicWrite(receiptPath, JSON.stringify({ ...prior, installed: entry }, null, 2) + "\n");
+        try { atomicWrite(host.file, next); }
+        catch (error) {
+          try { atomicWrite(receiptPath, previousReceipt); }
+          catch { throw new Error(`${error instanceof Error ? error.message : "host write failed"}; host unchanged, stale receipt kept at ${receiptPath}`); }
+          throw error;
+        }
+      }
+    } catch (error) {
+      action.change = "refused"; action.reason = error instanceof Error ? error.message : "setup failed";
+    }
+  }
+  report.applied = mode !== "dry-run" && report.actions.some(a => !["none", "unchanged", "refused"].includes(a.change));
+  return report;
+}

package/src/source.ts

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { VaultSpec } from "./config.ts";
+export type SourceValue = string | string[];
+export type SourceReference = {kind:"path"|"memory"|"url";value:string};
+/** One string is one reference. Joined legacy strings are never silently split. */
+export function sourceReferences(value:unknown):SourceReference[]{
+  const values=typeof value==="string"?[value]:Array.isArray(value)&&value.length>0&&value.length<=32?value:null;
+  if(!values)throw new Error("source must be a string or a nonempty list of at most 32 strings");
+  return values.map(item=>{
+    if(typeof item!=="string"||!item.trim()||Buffer.byteLength(item)>512||/\p{Cc}/u.test(item))throw new Error("source entries must be nonempty bounded strings without controls");
+    const text=item.trim();
+    if(text.startsWith("mem:")){
+      if(!/^mem:[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(text))throw new Error("source memory id is invalid");
+      return {kind:"memory",value:text};
+    }
+    if(/^[a-zA-Z]:[\\/]/.test(text))throw new Error("source paths must be workspace-relative");
+    if(/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(text)){
+      if(/\s/.test(text))throw new Error("source URL must be one absolute URL");
+      try{const url=new URL(text);if(["http:","https:","ftp:"].includes(url.protocol)&&!url.hostname)throw new Error();}
+      catch{throw new Error("source URL is invalid");}
+      return {kind:"url",value:text};
+    }
+    const path=text.startsWith("work/")?text.slice(5):text;
+    if(!path||isAbsolute(path)||path.includes("\\")||path.split("/").some(part=>!part||part==="."||part===".."))throw new Error("source paths must be workspace-relative without traversal");
+    return {kind:"path",value:path};
+  });
+}
+export function normalizeSource(value:unknown):SourceValue{
+  const entries=sourceReferences(value).map(ref=>ref.value);
+  return typeof value==="string"?entries[0]!:entries;
+}
+/** A configured project registry locates its workspace; standalone registries use their directory. */
+export function sourceWorkspaceRoot(vault:VaultSpec):string|undefined{
+  if(!vault.registry)return undefined;
+  const fallback=resolve(dirname(vault.registry));let dir=fallback;
+  for(let depth=0;depth<32;depth++){
+    if(existsSync(join(dir,"workspace.config.yaml")))return dir;
+    const parent=dirname(dir);if(parent===dir)break;dir=parent;
+  }
+  return fallback;
+}
+export function missingSourceWarnings(value:unknown,root:string|undefined):string[]{
+  if(!root||value===undefined)return [];
+  const missing=new Set(sourceReferences(value).filter(ref=>ref.kind==="path"&&!existsSync(resolve(root,ref.value))).map(ref=>ref.value));
+  return [...missing].map(path=>`source path does not exist: ${path}`);
+}

package/src/sync.ts

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import type { SpawnSyncReturns } from "node:child_process";
+import { loadRegistry } from "./registry.ts";
+import { isDenied, memoryGitArgv, memoryGitEnv } from "./platform.ts";
+import type { WriteIssue } from "./write-types.ts";
+
+/** Paths sync may stage; everything else in the clone is left alone (and reported). */
+const STAGE_PREFIXES = ["notes/", "reports/"];
+const STAGE_FILES = ["log"];
+const GIT_TIMEOUT_MS = 60_000;
+export interface SyncResult {
+  ok: boolean;
+  applied: boolean;
+  preview?: boolean;
+  vault: string;
+  remote: { configured: string | null; origin: string | null; push?: string[]; matches: boolean };
+  branch: string | null;
+  /** Planned changed paths that will be staged and committed. */
+  paths: string[];
+  /** Changed paths outside notes/, reports/ and log: never staged. */
+  ignored: string[];
+  ahead: number;
+  behind: number;
+  fingerprint?: string;
+  commit?: string;
+  pushed?: boolean;
+  issues: WriteIssue[];
+}
+type Git = (args: string[], options?: { allowFail?: boolean }) => SpawnSyncReturns<string>;
+const issue = (code: string, message: string): WriteIssue => ({ code, severity: "error", message });
+/** Compare remotes after removing transport noise: scheme, credentials, trailing .git and slash. Host remotes compare case-insensitively without a trailing .git; local and file: paths keep their case and their .git suffix. */
+export function sameRemote(a: string, b: string): boolean {
+  const norm = (url: string) => {
+    let value = url.trim();
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+      try { const parsed = new URL(value); if (parsed.protocol === "file:") return decodeURIComponent(parsed.pathname).replace(/\/+$/, ""); value = `${parsed.hostname}${parsed.port && !["22", "443"].includes(parsed.port) ? `:${parsed.port}` : ""}${parsed.pathname}`; }
+      catch { return value; }
+    } else if (value.startsWith("/")) return value.replace(/\/+$/, ""); // local: `x` and `x.git` are different repositories
+    else if (/^[^/@:]+@[^:]+:/.test(value) || /^[^/:]+:[^/]/.test(value)) value = value.replace(/^[^@]+@/, "").replace(":", "/");
+    return value.replace(/\/+$/, "").replace(/\.git$/, "").toLowerCase();
+  };
+  return norm(a) === norm(b);
+}
+function gitIn(cwd: string, env: NodeJS.ProcessEnv): Git {
+  return (args, options = {}) => {
+    const argv = memoryGitArgv(["-C", cwd, ...args]);
+    const result = Bun.spawnSync(argv, { env: memoryGitEnv({ ...env, GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" }, { repositoryIsolation: true }), stdin: "ignore", stdout: "pipe", stderr: "pipe", timeout: GIT_TIMEOUT_MS });
+    const out = { status: result.exitCode, stdout: result.stdout.toString(), stderr: result.stderr.toString(), pid: result.pid, output: [], signal: null } as unknown as SpawnSyncReturns<string>;
+    if (!options.allowFail && result.exitCode !== 0) throw Object.assign(new Error(`git ${args[0]} failed: ${out.stderr.trim().split("\n").at(-1)?.slice(0, 300) ?? "error"}`), { git: true });
+    return out;
+  };
+}
+function planned(path: string): boolean { return STAGE_FILES.includes(path) || STAGE_PREFIXES.some(prefix => path.startsWith(prefix)); }
+/** Parse `status --porcelain=v1 -z` into changed paths (renames contribute both sides). */
+function changed(git: Git): string[] {
+  const parts = git(["status", "--porcelain=v1", "-z", "--untracked-files=all"]).stdout.split("\0").filter(Boolean), paths: string[] = [];
+  for (let i = 0; i < parts.length; i++) {
+    const entry = parts[i]!, code = entry.slice(0, 2);
+    paths.push(entry.slice(3));
+    if (code.includes("R") || code.includes("C")) paths.push(parts[++i]!);
+  }
+  return [...new Set(paths)].sort();
+}
+
+/**
+ * Explicit, never scheduled publication of one vault clone. Without `confirm` it fetches, checks the
+ * configured remote against `origin`, and previews what would be staged; nothing is committed or pushed.
+ * With `confirm` and the current fingerprint it stages only notes/, reports/ and log, commits, rebases on
+ * the upstream and pushes. Any failure (remote mismatch, divergence that cannot rebase, push refused,
+ * missing credentials) is reported with `ok: false`; it never reports success it did not observe.
+ */
+export function syncVault(home: string, request: { vault: string; confirm?: boolean; fingerprint?: string; message?: string }, options: { env?: NodeJS.ProcessEnv } = {}): SyncResult {
+  const config = loadRegistry(home), spec = config.vaults.find(v => v.id === request.vault);
+  const result: SyncResult = { ok: false, applied: false, vault: request.vault, remote: { configured: spec?.remote ?? null, origin: null, matches: false }, branch: null, paths: [], ignored: [], ahead: 0, behind: 0, issues: [] };
+  if (!spec) return { ...result, issues: [issue("V04", "unknown vault id")] };
+  if (!spec.remote) return { ...result, issues: [issue("SYNC", "vault has no configured remote; register it with --remote")] };
+  if (spec.write === "none") return { ...result, issues: [issue("POLICY", "vault write policy refuses sync")] };
+  const root = realpathSync(spec.path);
+  if (root !== spec.path) return { ...result, issues: [issue("V04", "registered vault path changed")] };
+  // Same rule as applyWrite: a denied vault root is never synced.
+  if (isDenied(root, config.denyPaths)) return { ...result, issues: [issue("V06", "vault path is denied; nothing was synced")] };
+  const git = gitIn(root, options.env ?? process.env);
+  try {
+    if (realpathSync(git(["rev-parse", "--show-toplevel"]).stdout.trim()) !== root) return { ...result, issues: [issue("SYNC", "vault path is not the root of its git repository")] };
+    const origin = git(["remote", "get-url", "origin"], { allowFail: true });
+    result.remote.origin = origin.status === 0 ? origin.stdout.trim() : null;
+    // Every effective fetch and push URL must be the configured remote; URL rewrites are refused outright
+    // because git does not report pushInsteadOf rewrites of an explicit pushurl.
+    const lines = (args: string[]) => { const out = git(args, { allowFail: true }); return out.status === 0 ? out.stdout.split("\n").map(line => line.trim()).filter(Boolean) : []; };
+    const fetchUrls = lines(["remote", "get-url", "--all", "origin"]), pushUrls = lines(["remote", "get-url", "--push", "--all", "origin"]);
+    const rewrites = lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]);
+    result.remote.push = pushUrls;
+    result.remote.matches = result.remote.origin !== null && rewrites.length === 0 && fetchUrls.length > 0 && pushUrls.length > 0 && [...fetchUrls, ...pushUrls].every(url => sameRemote(url, spec.remote!));
+    if (!result.remote.matches) return { ...result, issues: [issue("REMOTE", result.remote.origin === null ? "repository has no origin remote" : rewrites.length ? "git url insteadOf/pushInsteadOf rewrites are configured; refusing because the push destination cannot be verified" : "an origin fetch or push URL does not match the configured remote; nothing was fetched or pushed")] };
+    const branch = git(["symbolic-ref", "--quiet", "--short", "HEAD"], { allowFail: true });
+    if (branch.status !== 0) return { ...result, issues: [issue("SYNC", "detached HEAD; check out a branch first")] };
+    result.branch = branch.stdout.trim();
+    if (git(["rev-parse", "--verify", "--quiet", "REBASE_HEAD"], { allowFail: true }).status === 0 || git(["rev-parse", "--verify", "--quiet", "MERGE_HEAD"], { allowFail: true }).status === 0) return { ...result, issues: [issue("SYNC", "a rebase or merge is in progress; resolve it first")] };
+    const fetch = git(["fetch", "--quiet", "--no-tags", "origin", result.branch], { allowFail: true });
+    if (fetch.status !== 0) return { ...result, issues: [issue("FETCH", `fetch failed: ${fetch.stderr.trim().split("\n").at(-1)?.slice(0, 300) ?? "error"}`)] };
+    const upstream = `origin/${result.branch}`;
+    const hasUpstream = git(["rev-parse", "--verify", "--quiet", `refs/remotes/${upstream}`], { allowFail: true }).status === 0;
+    if (hasUpstream) {
+      const [behind, ahead] = git(["rev-list", "--left-right", "--count", `${upstream}...HEAD`]).stdout.trim().split(/\s+/).map(Number);
+      result.behind = behind ?? 0; result.ahead = ahead ?? 0;
+    }
+    const all = changed(git);
+    result.paths = all.filter(planned); result.ignored = all.filter(path => !planned(path));
+    // Denied files are never hashed, staged, committed or pushed: the whole sync refuses before any of that.
+    const denied = result.paths.filter(path => isDenied(join(root, path), config.denyPaths));
+    if (denied.length) return { ...result, paths: result.paths.filter(path => !denied.includes(path)), issues: [issue("V06", `${denied.length} changed path${denied.length === 1 ? " is" : "s are"} denied by policy; remove or revert ${denied.length === 1 ? "it" : "them"} before syncing`)] };
+    const head = git(["rev-parse", "HEAD"], { allowFail: true }).stdout.trim();
+    const remoteHead = hasUpstream ? git(["rev-parse", upstream]).stdout.trim() : null;
+    const contents = result.paths.map(path => [path, git(["hash-object", "--", path], { allowFail: true }).stdout.trim()]);
+    result.fingerprint = createHash("sha256").update(JSON.stringify({ vault: spec.id, remote: spec.remote, fetchUrls, pushUrls, branch: result.branch, head, remoteHead, contents })).digest("hex");
+    if (request.confirm !== true) return { ...result, ok: true, preview: true };
+    if (request.fingerprint !== result.fingerprint) return { ...result, issues: [issue("V09", "stale or missing preview fingerprint")] };
+    if (result.paths.length) {
+      git(["add", "--", ...result.paths]);
+      const message = request.message ?? `vmem sync: ${result.paths.length} path${result.paths.length === 1 ? "" : "s"}`;
+      git(["-c", "user.useConfigOnly=false", "commit", "--quiet", "--no-verify", "-m", message, "--", ...result.paths]);
+      result.commit = git(["rev-parse", "HEAD"]).stdout.trim();
+    }
+    if (hasUpstream && result.behind > 0) {
+      const rebase = git(["rebase", "--quiet", upstream], { allowFail: true });
+      if (rebase.status !== 0) {
+        git(["rebase", "--abort"], { allowFail: true });
+        return { ...result, applied: Boolean(result.commit), issues: [issue("DIVERGED", "local and remote histories conflict; the local commit was kept and nothing was pushed. Resolve with git, then sync again")] };
+      }
+    }
+    if (!result.commit && (!hasUpstream ? false : git(["rev-list", "--count", `${upstream}..HEAD`]).stdout.trim() === "0")) return { ...result, ok: true, applied: false, pushed: false };
+    if (lines(["remote", "get-url", "--push", "--all", "origin"]).some(url => !sameRemote(url, spec.remote!)) || lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]).length) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("REMOTE", "push destination changed before push; nothing was pushed")] };
+    const push = git(["push", "--quiet", "--porcelain", "origin", `HEAD:refs/heads/${result.branch}`], { allowFail: true });
+    if (push.status !== 0) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("PUSH", `push failed: ${push.stderr.trim().split("\n").at(-1)?.slice(0, 300) ?? "error"}; the local commit was kept`)] };
+    // Verify the remote really has our head before reporting success.
+    git(["fetch", "--quiet", "--no-tags", "origin", result.branch]);
+    const pushedHead = git(["rev-parse", upstream]).stdout.trim(), localHead = git(["rev-parse", "HEAD"]).stdout.trim();
+    if (pushedHead !== localHead) return { ...result, applied: true, pushed: false, issues: [issue("PUSH", "remote head does not match the pushed commit")] };
+    return { ...result, ok: true, applied: true, pushed: true, commit: localHead };
+  } catch (error) {
+    return { ...result, issues: [issue("SYNC", error instanceof Error ? error.message.slice(0, 400) : "git failed")] };
+  }
+}