akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/sources/providers/git-stash.js

@@ -1,13 +1,16 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { akmAdapter } from "../../core/adapter/adapters/akm-adapter.js";
+import { stashDirNames } from "../../core/asset/asset-placement.js";
 import { resolveStashDir } from "../../core/common.js";
-import { getSources, loadConfig } from "../../core/config/config.js";
+import { getSources, loadConfig, resolveConfiguredSources } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
-import { sanitizeCommitMessage } from "../../core/write-source.js";
+import { sanitizeCommitMessage } from "../../core/git-message.js";
+import { lockContentRootFor } from "../../integrations/lockfile.js";
 import { runGit } from "./git-install.js";
 import { getCachePaths, parseGitRepoUrl } from "./git-provider.js";
 /**
@@ -22,15 +25,46 @@ import { getCachePaths, parseGitRepoUrl } from "./git-provider.js";
 export function isGitBackedStash(stashDir) {
     return fs.existsSync(path.join(stashDir, ".git"));
 }
+/** Return repo-relative dirty/staged paths without changing the index. */
+export function listGitChangedPaths(repoDir) {
+    const result = runGit(["-C", repoDir, "status", "--porcelain", "-z", "--untracked-files=all"]);
+    if (result.status !== 0)
+        return [];
+    const records = result.stdout.split("\0");
+    const paths = [];
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        if (!record)
+            continue;
+        const status = record.slice(0, 2);
+        paths.push(record.slice(3));
+        if (status.includes("R") || status.includes("C")) {
+            const previousPath = records[++i];
+            if (previousPath)
+                paths.push(previousPath);
+        }
+    }
+    return paths;
+}
+export class GitStashPushError extends Error {
+    commit;
+    constructor(message, commit) {
+        super(message);
+        this.name = "GitStashPushError";
+        this.commit = commit;
+    }
+}
+const GIT_PUSH_TIMEOUT_MS = 120_000;
+const ZERO_OID = "0000000000000000000000000000000000000000";
 /**
- * Resolve the writable-override flag for an end-of-run / `akm sync` commit on
- * the primary stash. Returns `true` when the root config explicitly marks the
- * primary stash writable, otherwise `undefined` (leave the per-stash default
- * untouched). Extracted so `akm sync`, `akm improve`'s end-of-run sync, and the
- * CLI body all derive this identically instead of re-copying the expression.
+ * Resolve the writable flag for an end-of-run / `akm sync` commit from the
+ * configured default bundle.
  */
 export function resolveWritableOverride(config) {
-    return config.writable === true ? true : undefined;
+    const source = resolveConfiguredSources(config).find((entry) => entry.name === config.defaultBundle);
+    if (!source)
+        return undefined;
+    return (source.writable ?? source.type === "filesystem") ? true : undefined;
 }
 /**
  * Commit (and optionally push) local changes in a git-backed stash.
@@ -49,7 +83,7 @@ export function resolveWritableOverride(config) {
  * primary stash dir (e.g. `akm improve`'s end-of-run sync, whose pre-commit
  * gate validates that exact directory) pass it here so the gate and the commit
  * operate on the SAME directory instead of independently calling
- * `resolveStashDir({ readOnly: true })`. When absent, behaviour is unchanged.
+ * `resolveStashDir()`. When absent, behaviour is unchanged.
  */
 export function saveGitStash(name, message, writableOverride, options) {
     // `push: false` (from `akm sync --no-push`) commits but never pushes, even
@@ -62,8 +96,13 @@ export function saveGitStash(name, message, writableOverride, options) {
     // Empty result falls back to the timestamped default.
     const sanitized = message ? sanitizeCommitMessage(message) : "";
     const commitMessage = sanitized || `akm save ${timestamp}`;
+    const transactionId = options?.transactionId;
+    if (transactionId !== undefined && !/^[A-Za-z0-9._-]{1,128}$/.test(transactionId)) {
+        throw new Error("Invalid Git transaction identifier.");
+    }
     let repoDir;
     let writable = false;
+    let managedContentRoot;
     if (name) {
         const config = loadConfig();
         const stash = findGitStashByTarget(getSources(config), name);
@@ -72,17 +111,28 @@ export function saveGitStash(name, message, writableOverride, options) {
         if (stash.type !== "git") {
             throw new UsageError(`Stash "${name}" is not a git stash (type: ${stash.type})`);
         }
-        if (!stash.url)
-            throw new UsageError(`Stash "${name}" has no URL configured`);
-        const repo = parseGitRepoUrl(stash.url);
-        repoDir = getCachePaths(repo.canonicalUrl).repoDir;
+        const lockedRoot = lockContentRootFor(stash.name, stash.type);
+        if (lockedRoot) {
+            const topLevel = runGit(["-C", lockedRoot, "rev-parse", "--show-toplevel"]);
+            if (topLevel.status !== 0 || !topLevel.stdout.trim()) {
+                throw new UsageError(`Managed Git stash "${name}" is not a checkout at ${lockedRoot}`);
+            }
+            repoDir = path.resolve(topLevel.stdout.trim());
+            managedContentRoot = path.resolve(lockedRoot);
+        }
+        else {
+            if (!stash.url)
+                throw new UsageError(`Stash "${name}" has no URL configured`);
+            const repo = parseGitRepoUrl(stash.url);
+            repoDir = getCachePaths(repo.canonicalUrl).repoDir;
+        }
         writable = stash.writable === true;
     }
     else {
         // Honour an explicit primary-stash dir override (keeps the improve gate and
         // the commit on the same directory); otherwise resolve the default.
-        repoDir = options?.repoDir ?? resolveStashDir({ readOnly: true });
-        // Allow caller to override writable for the primary stash (e.g. from root config.writable)
+        repoDir = options?.repoDir ?? resolveStashDir();
+        // Allow the caller to pass the configured default bundle's writability.
         if (writableOverride !== undefined) {
             writable = writableOverride;
         }
@@ -91,12 +141,11 @@ export function saveGitStash(name, message, writableOverride, options) {
     if (!isGitBackedStash(repoDir)) {
         return { committed: false, pushed: false, skipped: true, reason: "not a git repository", output: "" };
     }
-    // Nothing to commit?
     const statusResult = runGit(["-C", repoDir, "status", "--porcelain"]);
     if (statusResult.error || statusResult.status !== 0) {
         throw new Error(`git status failed: ${statusResult.error?.message || statusResult.stderr?.trim() || "unknown error"}`);
     }
-    if (!statusResult.stdout.trim()) {
+    if (!statusResult.stdout.trim() && options?.paths === undefined) {
         return { committed: false, pushed: false, skipped: false, output: "nothing to commit, working tree clean" };
     }
     // Scoped staging (#476 + the auto-sync incident): NEVER refuse akm's commit
@@ -107,103 +156,383 @@ export function saveGitStash(name, message, writableOverride, options) {
     //
     // Precedence:
     //   1. Explicit modified-file list (`options.paths`) — stage exactly those.
-    //   2. Managed pathspecs (TYPE_DIRS values + `.akm`) that exist on disk —
-    //      stages everything akm owns and, by construction, never stages non-akm
-    //      WIP. This preserves the #476 protection WITHOUT refusing.
-    //   3. Last-resort `git add -A` — ONLY when neither an explicit list nor any
-    //      managed pathspec can be resolved. This is the maintainer-approved
-    //      "or all files if we cannot determine the exact file list" fallback and
-    //      is the one (rare) path that could include unrelated non-akm files.
-    if (!stageScopedChanges(repoDir, options?.paths)) {
-        throw new Error(`git add failed while staging akm changes in ${repoDir}`);
-    }
-    // Nothing actually staged → don't create an empty commit. This happens when
-    // only non-akm files were dirty (precedence 2 staged nothing).
-    const stagedResult = runGit(["-C", repoDir, "diff", "--cached", "--quiet"]);
-    if (stagedResult.status === 0) {
+    //   2. A lock-backed content root, or managed adapter pathspecs for an
+    //      ordinary stash. Both stay below AKM's resolved content boundary.
+    //   3. No resolvable managed path — no commit. Broad staging is never safe
+    //      because it can absorb unrelated work already present in the index.
+    const managedRelativeRoot = managedContentRoot
+        ? path.relative(repoDir, managedContentRoot).replaceAll(path.sep, "/")
+        : "";
+    const changedPaths = listGitChangedPaths(repoDir);
+    const requestedPaths = normalizeExactPaths(repoDir, options?.paths ??
+        (managedRelativeRoot && managedRelativeRoot !== ".." && !managedRelativeRoot.startsWith("../")
+            ? changedPaths.filter((changedPath) => changedPath === managedRelativeRoot || changedPath.startsWith(`${managedRelativeRoot}/`))
+            : managedFallbackPaths(repoDir, changedPaths)));
+    if (requestedPaths.length === 0) {
         return { committed: false, pushed: false, skipped: false, output: "nothing to commit" };
     }
-    // Commit — supply fallback identity so fresh environments without
-    // user.name/user.email configured can always commit to the default stash.
-    const commitResult = runGit([
-        "-C",
-        repoDir,
-        "-c",
-        "user.name=akm",
-        "-c",
-        "user.email=akm@local",
-        "commit",
-        "-m",
-        commitMessage,
-    ]);
-    if (commitResult.status !== 0) {
-        throw new Error(`git commit failed: ${commitResult.stderr?.trim() || "unknown error"}`);
+    assertNoIgnoredExactPaths(repoDir, requestedPaths);
+    const baseHead = readOptionalHead(repoDir);
+    if (options?.expectedBaseHead !== undefined && (baseHead ?? null) !== options.expectedBaseHead) {
+        throw new Error(`Git target advanced before its exact-path commit could be created.`);
     }
-    // Push only when there is a remote AND the stash is marked writable
     const remoteResult = runGit(["-C", repoDir, "remote"]);
     if (remoteResult.status !== 0) {
         throw new Error(`git remote failed: ${remoteResult.stderr?.trim() || "unknown error"}`);
     }
     const hasRemote = remoteResult.stdout.trim().length > 0;
-    if (!hasRemote || !writable || !allowPush) {
-        return { committed: true, pushed: false, skipped: false, output: commitResult.stdout.trim() };
+    const pushTarget = hasRemote && writable && allowPush ? readActualUpstream(repoDir, baseHead) : undefined;
+    const exactCommit = createExactPathCommit(repoDir, {
+        baseHead,
+        commitMessage,
+        paths: requestedPaths,
+        transactionId,
+        expectedSnapshots: options?.expectedSnapshots,
+    });
+    if (!exactCommit) {
+        return { committed: false, pushed: false, skipped: false, output: "nothing to commit" };
     }
-    const pushResult = runGit(["-C", repoDir, "push"], { timeout: 120_000 });
+    if (!pushTarget) {
+        return {
+            committed: true,
+            pushed: false,
+            skipped: false,
+            output: `commit ${exactCommit}`,
+            commit: exactCommit,
+        };
+    }
+    const pushResult = runGit([
+        "-C",
+        repoDir,
+        "push",
+        `--force-with-lease=${pushTarget.mergeRef}:${pushTarget.upstreamHead}`,
+        pushTarget.remote,
+        `${exactCommit}:${pushTarget.mergeRef}`,
+    ], { timeout: GIT_PUSH_TIMEOUT_MS });
     if (pushResult.status !== 0) {
-        throw new Error(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`);
+        throw new GitStashPushError(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`, exactCommit);
     }
     return {
         committed: true,
         pushed: true,
         skipped: false,
-        output: (commitResult.stdout + pushResult.stdout).trim() || "changes committed and pushed",
+        output: pushResult.stdout.trim() || "changes committed and pushed",
+        commit: exactCommit,
     };
 }
-/**
- * Stage akm's changes in `repoDir` using the scoped-staging precedence
- * documented at the call site (#476). Returns `false` only when a `git add`
- * subprocess fails; returns `true` otherwise (including when nothing matched —
- * the caller then detects "nothing staged" via `git diff --cached --quiet`).
- *
- * @param paths Optional explicit repo-relative paths akm wrote this run. When
- *   provided and non-empty, exactly those are staged (chunked to stay under
- *   argv length limits). Otherwise we fall back to the managed pathspecs, and
- *   finally to `git add -A` only if no managed pathspec exists on disk.
- */
-function stageScopedChanges(repoDir, paths) {
-    // Precedence 1: explicit modified-file list.
-    const explicit = (paths ?? []).filter((p) => typeof p === "string" && p.length > 0);
-    if (explicit.length > 0) {
-        return addPathspecsChunked(repoDir, explicit);
-    }
-    // Precedence 2: managed pathspecs that exist on disk (TYPE_DIRS + `.akm`).
-    const managed = [...Object.values(TYPE_DIRS), ".akm"].filter((dir) => fs.existsSync(path.join(repoDir, dir)));
-    if (managed.length > 0) {
-        return addPathspecsChunked(repoDir, managed);
-    }
-    // Precedence 3 (last resort): nothing akm-managed resolved on disk. Stage
-    // everything. This is the ONLY branch that can include unrelated non-akm
-    // files — it is the explicit, maintainer-approved "or all files if we cannot
-    // determine the exact file list" fallback and should be rare/never in
-    // practice (a git-backed stash always has at least one managed subtree once
-    // akm has written to it).
-    const addAll = runGit(["-C", repoDir, "add", "-A"]);
-    return addAll.status === 0;
+function managedFallbackPaths(repoDir, changedPaths) {
+    const ownedDirs = akmAdapter.directoryList?.({ id: "akm", adapter: "akm", root: repoDir, writable: false }) ?? stashDirNames();
+    const prefixes = [...ownedDirs, ".akm"];
+    return changedPaths.filter((changedPath) => prefixes.some((prefix) => changedPath === prefix || changedPath.startsWith(`${prefix}/`)));
 }
-/**
- * Run `git add -- <pathspec>...` in chunks so a very large path list never
- * exceeds the OS argv-length limit. Each chunk must succeed.
- */
-function addPathspecsChunked(repoDir, pathspecs) {
+function normalizeExactPaths(repoDir, paths) {
+    const normalized = [...new Set(paths.map((value) => value.replaceAll(path.sep, "/")))];
+    for (const filePath of normalized) {
+        const absolute = path.resolve(repoDir, filePath);
+        const relative = path.relative(repoDir, absolute).replaceAll(path.sep, "/");
+        if (!filePath ||
+            filePath.includes("\0") ||
+            path.isAbsolute(filePath) ||
+            relative !== filePath ||
+            relative === ".." ||
+            relative.startsWith("../")) {
+            throw new Error(`Unsafe exact Git path: ${filePath || "<empty>"}`);
+        }
+    }
+    return normalized;
+}
+function runExactPathChunks(repoDir, command, paths, options = {}) {
     const CHUNK = 500;
-    for (let i = 0; i < pathspecs.length; i += CHUNK) {
-        const chunk = pathspecs.slice(i, i + CHUNK);
-        const result = runGit(["-C", repoDir, "add", "--", ...chunk]);
+    const results = [];
+    for (let i = 0; i < paths.length; i += CHUNK) {
+        results.push(runGit(["--literal-pathspecs", "-C", repoDir, ...command, "--", ...paths.slice(i, i + CHUNK)], {
+            env: options.env,
+        }));
+    }
+    return results;
+}
+export function listIgnoredExactPaths(repoDir, paths) {
+    if (paths.length === 0)
+        return [];
+    const input = `${paths.join("\0")}\0`;
+    const result = runGit(["-C", repoDir, "check-ignore", "-z", "--stdin"], { input });
+    if (result.status === 1)
+        return [];
+    if (result.status !== 0) {
+        throw new Error(`git check-ignore failed: ${result.stderr.trim() || "unknown error"}`);
+    }
+    return result.stdout.split("\0").filter(Boolean);
+}
+export function assertNoIgnoredExactPaths(repoDir, paths) {
+    const ignored = listIgnoredExactPaths(repoDir, normalizeExactPaths(repoDir, paths));
+    if (ignored.length > 0) {
+        throw new UsageError(`Exact Git publication path is ignored: ${ignored[0]}. Update .gitignore or choose a tracked destination before writing.`);
+    }
+}
+/** Reject exact staged/unstaged paths before an AKM filesystem mutation. */
+export function assertGitExactPathsClean(repoDir, paths) {
+    const normalized = normalizeExactPaths(repoDir, paths);
+    assertNoIgnoredExactPaths(repoDir, normalized);
+    for (const result of runExactPathChunks(repoDir, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], normalized)) {
+        if (result.status !== 0) {
+            throw new Error(`git status failed: ${result.stderr.trim() || "unknown error"}`);
+        }
+        if (result.stdout.length > 0) {
+            const record = result.stdout.split("\0").find(Boolean) ?? "";
+            throw new UsageError(`Exact Git operation path has staged or unstaged work: ${record.slice(3)}. Commit, stash, or discard that path before retrying.`);
+        }
+    }
+}
+function readOptionalHead(repoDir) {
+    const result = runGit(["-C", repoDir, "rev-parse", "--verify", "HEAD"]);
+    return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : undefined;
+}
+function readBranchRef(repoDir) {
+    const result = runGit(["-C", repoDir, "symbolic-ref", "--quiet", "HEAD"]);
+    if (result.status !== 0 || !result.stdout.trim()) {
+        throw new UsageError(`Writable Git target at ${repoDir} is detached from a branch.`);
+    }
+    return result.stdout.trim();
+}
+function readActualUpstream(repoDir, baseHead) {
+    if (!baseHead)
+        throw new UsageError(`Writable Git target at ${repoDir} has no commit to publish.`);
+    const branchRef = readBranchRef(repoDir);
+    const branch = branchRef.replace(/^refs\/heads\//, "");
+    const remote = runGit(["-C", repoDir, "config", "--get", `branch.${branch}.remote`]);
+    const merge = runGit(["-C", repoDir, "config", "--get", `branch.${branch}.merge`]);
+    const upstream = runGit(["-C", repoDir, "rev-parse", "--verify", "@{u}"]);
+    if (remote.status !== 0 || merge.status !== 0 || upstream.status !== 0) {
+        throw new UsageError(`Writable Git target at ${repoDir} has no configured upstream branch.`);
+    }
+    const upstreamHead = upstream.stdout.trim();
+    if (!upstreamHead || upstreamHead !== baseHead) {
+        throw new UsageError(`Writable Git target at ${repoDir} is not synchronized with its actual upstream.`);
+    }
+    return { remote: remote.stdout.trim(), mergeRef: merge.stdout.trim(), upstreamHead };
+}
+function readIndexEntries(repoDir, paths) {
+    const entries = new Map(paths.map((filePath) => [filePath, []]));
+    for (const result of runExactPathChunks(repoDir, ["ls-files", "--stage", "-z"], paths)) {
         if (result.status !== 0)
+            throw new Error(`Cannot inspect Git index: ${result.stderr.trim() || "unknown error"}`);
+        for (const record of result.stdout.split("\0")) {
+            if (!record)
+                continue;
+            const tab = record.indexOf("\t");
+            const match = record.slice(0, tab).match(/^(\d+) ([0-9a-f]+) (\d+)$/);
+            if (tab < 0 || !match)
+                throw new Error(`Cannot parse Git index entry.`);
+            const filePath = record.slice(tab + 1);
+            entries.get(filePath)?.push({ mode: match[1], oid: match[2], stage: Number(match[3]) });
+        }
+    }
+    return entries;
+}
+function readTreeStates(repoDir, treeish, paths) {
+    const states = new Map(paths.map((filePath) => [filePath, null]));
+    if (!treeish)
+        return states;
+    for (const result of runExactPathChunks(repoDir, ["ls-tree", "-z", treeish], paths)) {
+        if (result.status !== 0)
+            throw new Error(`Cannot inspect Git tree: ${result.stderr.trim() || "unknown error"}`);
+        for (const record of result.stdout.split("\0")) {
+            if (!record)
+                continue;
+            const tab = record.indexOf("\t");
+            const match = record.slice(0, tab).match(/^(\d+) blob ([0-9a-f]+)$/);
+            if (tab < 0 || !match)
+                throw new Error(`Exact Git path is not a blob.`);
+            const mode = match[1];
+            if (mode !== "100644" && mode !== "100755" && mode !== "120000") {
+                throw new Error(`Unsupported Git mode ${mode}.`);
+            }
+            states.set(record.slice(tab + 1), { mode, oid: match[2] });
+        }
+    }
+    return states;
+}
+function assertIndexMatchesBase(paths, indexEntries, baseStates) {
+    if (indexMatchesTree(paths, indexEntries, baseStates))
+        return;
+    const dirtyPath = paths.find((filePath) => {
+        const entries = indexEntries.get(filePath) ?? [];
+        const base = baseStates.get(filePath) ?? null;
+        return !(base === null
+            ? entries.length === 0
+            : entries.length === 1 &&
+                entries[0]?.stage === 0 &&
+                entries[0]?.mode === base.mode &&
+                entries[0]?.oid === base.oid);
+    });
+    throw new UsageError(`Exact Git operation path has staged work: ${dirtyPath ?? paths[0]}. Commit, stash, or discard that path before retrying.`);
+}
+function indexMatchesTree(paths, indexEntries, treeStates) {
+    for (const filePath of paths) {
+        const entries = indexEntries.get(filePath) ?? [];
+        const state = treeStates.get(filePath) ?? null;
+        if (!(state === null
+            ? entries.length === 0
+            : entries.length === 1 &&
+                entries[0]?.stage === 0 &&
+                entries[0]?.mode === state.mode &&
+                entries[0]?.oid === state.oid)) {
             return false;
+        }
     }
     return true;
 }
+/** Repair only the stale base index left by a crash after an exact commit CAS. */
+export function reconcileGitExactPathIndex(repoDir, baseCommit, commit, paths) {
+    const normalized = normalizeExactPaths(repoDir, paths);
+    const current = readIndexEntries(repoDir, normalized);
+    const committedStates = readTreeStates(repoDir, commit, normalized);
+    if (indexMatchesTree(normalized, current, committedStates))
+        return;
+    const baseStates = readTreeStates(repoDir, baseCommit, normalized);
+    if (!indexMatchesTree(normalized, current, baseStates)) {
+        throw new UsageError(`Exact Git operation path has staged work after transaction recovery. Commit, stash, or discard it before retrying.`);
+    }
+    for (const result of runExactPathChunks(repoDir, ["reset", "--quiet", commit], normalized)) {
+        if (result.status !== 0)
+            throw new Error(`git index cleanup failed during exact transaction recovery`);
+    }
+}
+function captureWorktreeState(repoDir, filePath) {
+    const absolutePath = path.join(repoDir, filePath);
+    let stat;
+    try {
+        stat = fs.lstatSync(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let mode;
+    let result;
+    if (stat.isSymbolicLink()) {
+        mode = "120000";
+        result = runGit(["-C", repoDir, "hash-object", "--stdin"], { input: fs.readlinkSync(absolutePath) });
+    }
+    else if (stat.isFile()) {
+        mode = stat.mode & 0o111 ? "100755" : "100644";
+        result = runGit(["-C", repoDir, "hash-object", `--path=${filePath}`, "--", absolutePath]);
+    }
+    else {
+        throw new Error(`Exact Git publication path is not a file: ${filePath}`);
+    }
+    if (result.status !== 0 || !result.stdout.trim()) {
+        throw new Error(`Cannot hash exact Git publication path: ${filePath}`);
+    }
+    return { oid: result.stdout.trim(), mode };
+}
+function samePathState(left, right) {
+    return left === null ? right === null : right !== null && left.oid === right.oid && left.mode === right.mode;
+}
+function assertWorktreeMatchesExpected(repoDir, paths, expected) {
+    for (const filePath of paths) {
+        if (!samePathState(captureWorktreeState(repoDir, filePath), expected.get(filePath) ?? null)) {
+            throw new Error(`Exact Git publication path changed while committing: ${filePath}`);
+        }
+    }
+}
+function sameIndexEntries(left, right) {
+    return JSON.stringify([...left]) === JSON.stringify([...right]);
+}
+function resetRealIndexPaths(repoDir, commit, paths, initial) {
+    const current = readIndexEntries(repoDir, paths);
+    if (!sameIndexEntries(initial, current))
+        return;
+    for (const result of runExactPathChunks(repoDir, ["reset", "--quiet", commit], paths)) {
+        if (result.status !== 0)
+            throw new Error(`git index cleanup failed after exact commit`);
+    }
+}
+function createExactPathCommit(repoDir, options) {
+    const branchRef = readBranchRef(repoDir);
+    const baseStates = readTreeStates(repoDir, options.baseHead, options.paths);
+    const initialIndex = readIndexEntries(repoDir, options.paths);
+    assertIndexMatchesBase(options.paths, initialIndex, baseStates);
+    const expected = new Map();
+    for (const filePath of options.paths) {
+        expected.set(filePath, options.expectedSnapshots && Object.hasOwn(options.expectedSnapshots, filePath)
+            ? (options.expectedSnapshots[filePath] ?? null)
+            : captureWorktreeState(repoDir, filePath));
+    }
+    const gitIndex = runGit(["-C", repoDir, "rev-parse", "--git-path", "index"]);
+    if (gitIndex.status !== 0 || !gitIndex.stdout.trim())
+        throw new Error(`Cannot resolve Git index path.`);
+    const realIndexPath = path.resolve(repoDir, gitIndex.stdout.trim());
+    const temporaryIndex = `${realIndexPath}.akm-${process.pid}-${randomBytes(6).toString("hex")}`;
+    const env = { GIT_INDEX_FILE: temporaryIndex };
+    try {
+        const seeded = options.baseHead
+            ? runGit(["-C", repoDir, "read-tree", options.baseHead], { env })
+            : runGit(["-C", repoDir, "read-tree", "--empty"], { env });
+        if (seeded.status !== 0)
+            throw new Error(`Cannot seed temporary Git index: ${seeded.stderr.trim()}`);
+        const stagePaths = options.paths.filter((filePath) => (expected.get(filePath) ?? null) !== null || (baseStates.get(filePath) ?? null) !== null);
+        for (const result of runExactPathChunks(repoDir, ["add", "-A"], stagePaths, { env })) {
+            if (result.status !== 0)
+                throw new Error(`Cannot stage exact Git paths: ${result.stderr.trim()}`);
+        }
+        const tree = runGit(["-C", repoDir, "write-tree"], { env });
+        if (tree.status !== 0 || !tree.stdout.trim())
+            throw new Error(`Cannot write exact Git tree.`);
+        const treeOid = tree.stdout.trim();
+        const committedStates = readTreeStates(repoDir, treeOid, options.paths);
+        for (const filePath of options.paths) {
+            if (!samePathState(committedStates.get(filePath) ?? null, expected.get(filePath) ?? null)) {
+                throw new Error(`Exact Git publication path changed while committing: ${filePath}`);
+            }
+        }
+        assertWorktreeMatchesExpected(repoDir, options.paths, expected);
+        const baseTreeResult = options.baseHead
+            ? runGit(["-C", repoDir, "rev-parse", `${options.baseHead}^{tree}`])
+            : undefined;
+        if (baseTreeResult && (baseTreeResult.status !== 0 || !baseTreeResult.stdout.trim())) {
+            throw new Error(`Cannot inspect base Git tree.`);
+        }
+        const baseTree = baseTreeResult?.stdout.trim() ?? "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+        if (treeOid === baseTree)
+            return null;
+        const body = options.transactionId
+            ? `${options.commitMessage}\n\nAKM-Transaction: ${options.transactionId}\n`
+            : `${options.commitMessage}\n`;
+        const commit = runGit([
+            "-C",
+            repoDir,
+            "-c",
+            "user.name=akm",
+            "-c",
+            "user.email=akm@local",
+            "commit-tree",
+            treeOid,
+            ...(options.baseHead ? ["-p", options.baseHead] : []),
+        ], { input: body });
+        if (commit.status !== 0 || !commit.stdout.trim()) {
+            throw new Error(`git commit-tree failed: ${commit.stderr.trim() || "unknown error"}`);
+        }
+        const commitOid = commit.stdout.trim();
+        const currentBranch = readBranchRef(repoDir);
+        const currentHead = readOptionalHead(repoDir);
+        if (currentBranch !== branchRef || currentHead !== options.baseHead) {
+            throw new Error(`Git target changed before its exact commit could be attached.`);
+        }
+        assertWorktreeMatchesExpected(repoDir, options.paths, expected);
+        const update = runGit(["-C", repoDir, "update-ref", branchRef, commitOid, options.baseHead ?? ZERO_OID]);
+        if (update.status !== 0) {
+            throw new Error(`Git target advanced before its exact commit could be attached.`);
+        }
+        resetRealIndexPaths(repoDir, commitOid, options.paths, initialIndex);
+        return commitOid;
+    }
+    finally {
+        fs.rmSync(temporaryIndex, { force: true });
+        fs.rmSync(`${temporaryIndex}.lock`, { force: true });
+    }
+}
 function findGitStashByTarget(stashes, target) {
     return stashes.find((stash) => matchesGitStashTarget(stash, target));
 }

package/dist/sources/providers/git.js

@@ -8,6 +8,6 @@
 //
 // Re-exported here so every consumer (and every `spyOn(gitProvider, …)` test)
 // keeps importing from a single module namespace.
-export { classifyCloneFailure, cloneRepo, syncRegistryGitRef } from "./git-install.js";
+export { classifyCloneFailure, cloneRepo, inspectGitUpstream, runGit, syncExistingWritableCheckout, } from "./git-install.js";
 export { ensureGitMirror, GitSourceProvider, getCachePaths, parseGitRepoUrl, syncMirroredRepo, } from "./git-provider.js";
-export { isGitBackedStash, resolveWritableOverride, saveGitStash, } from "./git-stash.js";
+export { GitStashPushError, isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "./git-stash.js";