@open-cr-agent/vcs-local 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -0,0 +1,3 @@
+# @open-cr-agent/vcs-local
+
+The adapter for local Git changes (working tree, ranges and commits) of [Open-CR-Agent](https://github.com/jma49/Open-CR-Agent), the multi-agent code reviewer. Most users want [`@open-cr-agent/cli`](https://www.npmjs.com/package/@open-cr-agent/cli), which provides the `ocra` command and installs this package; see the [manual](https://ocra.majincheng.com). All `@open-cr-agent` packages are released together at one version. Apache-2.0.

package/dist/commits.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureCommits(root: string, shas: readonly string[], refspecs?: readonly string[], remote?: string): Promise<void>;
+//# sourceMappingURL=commits.d.ts.map

package/dist/commits.js

@@ -0,0 +1,42 @@
+import { git } from "./git.js";
+const FETCH_TIMEOUT_MS = 5 * 60_000;
+// Pull request commits are often missing from a local clone (shallow CI
+// checkouts, fork heads). Fetch them by SHA first, then through the extra
+// refspecs (for example pull/<n>/head), and name what is still missing.
+export async function ensureCommits(root, shas, refspecs = [], remote = "origin") {
+    // Anything but a commit id could be read by git fetch as an option.
+    const invalid = shas.filter((sha) => !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(sha));
+    if (invalid.length > 0)
+        throw new Error(`Not commit ids: ${invalid.join(", ")}`);
+    const missing = async () => {
+        const result = [];
+        for (const sha of shas) {
+            const out = await git(["cat-file", "-t", "--end-of-options", sha], {
+                cwd: root,
+                okExitCodes: [0, 1, 128],
+            });
+            if (out.trim() !== "commit")
+                result.push(sha);
+        }
+        return result;
+    };
+    let absent = await missing();
+    for (const attempt of [absent, refspecs]) {
+        if (absent.length === 0)
+            return;
+        if (attempt.length === 0)
+            continue;
+        // No credential prompt can block a non-interactive run.
+        await git(["fetch", "--quiet", "--no-tags", remote, ...attempt], {
+            cwd: root,
+            okExitCodes: [0, 1, 128],
+            timeoutMs: FETCH_TIMEOUT_MS,
+            env: { GIT_TERMINAL_PROMPT: "0" },
+        });
+        absent = await missing();
+    }
+    if (absent.length > 0) {
+        throw new Error(`Commits ${absent.join(", ")} are not in this repository and could not be fetched from ${remote}`);
+    }
+}
+//# sourceMappingURL=commits.js.map

package/dist/git.d.ts

@@ -0,0 +1,19 @@
+export interface GitOptions {
+    cwd: string;
+    input?: string;
+    okExitCodes?: readonly number[];
+    env?: Readonly<Record<string, string>>;
+    truncateAt?: number;
+    timeoutMs?: number;
+}
+export declare const GIT_TIMEOUT_MS: number;
+export declare class GitError extends Error {
+    readonly args: readonly string[];
+    readonly exitCode: number | undefined;
+    readonly stderr: string;
+    constructor(args: readonly string[], exitCode: number | undefined, stderr: string);
+}
+export declare function git(args: readonly string[], options: GitOptions): Promise<string>;
+export declare function isShallow(root: string): Promise<boolean>;
+export declare const SHALLOW_HINT = "the clone is shallow; fetch the full history (for example actions/checkout with fetch-depth: 0)";
+//# sourceMappingURL=git.d.ts.map

package/dist/git.js

@@ -0,0 +1,69 @@
+import { execFile } from "node:child_process";
+// Every git call ends: a fetch can wait on the network forever, and a diff
+// of a huge repository should fail rather than hang the review.
+export const GIT_TIMEOUT_MS = 10 * 60_000;
+export class GitError extends Error {
+    args;
+    exitCode;
+    stderr;
+    constructor(args, exitCode, stderr) {
+        super(`git ${args.join(" ")} failed (exit ${exitCode ?? "unknown"}): ${stderr.trim()}`);
+        this.args = args;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}
+const MAX_OUTPUT_BYTES = 512 * 1024 * 1024;
+const CLOSED_PIPE = new Set(["EPIPE", "ENOTCONN", "ECONNRESET"]);
+export function git(args, options) {
+    const okExitCodes = options.okExitCodes ?? [0];
+    return new Promise((resolve, reject) => {
+        const child = execFile("git", args, {
+            cwd: options.cwd,
+            encoding: "utf8",
+            maxBuffer: options.truncateAt ?? MAX_OUTPUT_BYTES,
+            timeout: options.timeoutMs ?? GIT_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+            env: { ...process.env, LC_ALL: "C", GIT_OPTIONAL_LOCKS: "0", ...options.env },
+        }, (error, stdout, stderr) => {
+            if (options.truncateAt !== undefined &&
+                error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+                resolve(stdout);
+                return;
+            }
+            if (error?.killed && error.signal === "SIGKILL") {
+                const seconds = Math.round((options.timeoutMs ?? GIT_TIMEOUT_MS) / 1000);
+                reject(new GitError(args, undefined, `timed out after ${seconds}s`));
+                return;
+            }
+            const exitCode = error ? (typeof error.code === "number" ? error.code : undefined) : 0;
+            if (exitCode !== undefined && okExitCodes.includes(exitCode))
+                resolve(stdout);
+            else
+                reject(new GitError(args, exitCode, stderr || String(error?.message ?? "")));
+        });
+        // git may exit before reading stdin; its exit code already reports the
+        // outcome, so a broken pipe on our side carries no information. Which
+        // error that is depends on timing and platform (EPIPE, or ENOTCONN on
+        // macOS when the pipe closed before the write).
+        child.stdin?.on("error", (error) => {
+            if (!CLOSED_PIPE.has(error.code ?? ""))
+                reject(error);
+        });
+        if (options.input === undefined)
+            child.stdin?.end();
+        else
+            child.stdin?.end(options.input);
+    });
+}
+// CI checkouts are shallow by default; commits beyond the cut-off look
+// unrelated to git, which surfaces as a failed merge-base.
+export async function isShallow(root) {
+    const out = await git(["rev-parse", "--is-shallow-repository"], {
+        cwd: root,
+        okExitCodes: [0, 128],
+    });
+    return out.trim() === "true";
+}
+export const SHALLOW_HINT = "the clone is shallow; fetch the full history (for example actions/checkout with fetch-depth: 0)";
+//# sourceMappingURL=git.js.map

package/dist/history.d.ts

@@ -0,0 +1,7 @@
+export type ChangedFiles = {
+    files: string[];
+} | {
+    reason: string;
+};
+export declare function filesChangedSince(root: string, from: string, to: string): Promise<ChangedFiles>;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.js

@@ -0,0 +1,44 @@
+import { GitError, git, isShallow, SHALLOW_HINT } from "./git.js";
+const SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+// The files that differ between two commits, when `to` descends from `from`.
+// After a force-push or rebase `from` is no longer an ancestor, and a commit
+// that was never fetched cannot be compared: both give a reason instead.
+export async function filesChangedSince(root, from, to) {
+    if (!SHA.test(from) || !SHA.test(to))
+        return { reason: "not a commit id" };
+    const short = from.slice(0, 7);
+    const type = await git(["cat-file", "-t", "--end-of-options", from], {
+        cwd: root,
+        okExitCodes: [0, 1, 128],
+    });
+    if (type.trim() !== "commit")
+        return { reason: `commit ${short} is not available` };
+    try {
+        await git(["merge-base", "--is-ancestor", from, to], { cwd: root });
+    }
+    catch (error) {
+        if (error instanceof GitError && error.exitCode === 1) {
+            if (await isShallow(root)) {
+                return { reason: `commit ${short} cannot be traced to the new head: ${SHALLOW_HINT}` };
+            }
+            return {
+                reason: `commit ${short} is not an ancestor of the new head (force-push or rebase)`,
+            };
+        }
+        throw error;
+    }
+    const out = await git([
+        "diff",
+        "--name-only",
+        "-z",
+        "--no-renames",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--no-relative",
+        from,
+        to,
+        "--",
+    ], { cwd: root });
+    return { files: out.split("\0").filter((p) => p !== "") };
+}
+//# sourceMappingURL=history.js.map

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { ensureCommits } from "./commits.js";
+export { GitError } from "./git.js";
+export * from "./history.js";
+export * from "./local-adapter.js";
+export * from "./plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,6 @@
+export { ensureCommits } from "./commits.js";
+export { GitError } from "./git.js";
+export * from "./history.js";
+export * from "./local-adapter.js";
+export * from "./plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/local-adapter.d.ts

@@ -0,0 +1,35 @@
+import { type ChangeRequest, type CodeMatch, type FileDiff, type PriorReview, type VcsAdapter } from "@open-cr-agent/core";
+export type LocalTarget = {
+    mode: "workspace";
+} | {
+    mode: "range";
+    from: string;
+    to: string;
+} | {
+    mode: "commit";
+    commit: string;
+};
+export interface LocalGitOptions {
+    cwd: string;
+    target: LocalTarget;
+}
+export declare const MAX_READ_BYTES: number;
+export declare class LocalGitAdapter implements VcsAdapter {
+    private readonly options;
+    readonly name = "local";
+    private resolved;
+    constructor(options: LocalGitOptions);
+    repositoryRoot(): Promise<string>;
+    getChangeRequest(): Promise<ChangeRequest>;
+    getDiff(): Promise<FileDiff[]>;
+    readFile(path: string): Promise<string | undefined>;
+    searchCode(literal: string): Promise<CodeMatch[]>;
+    remoteUrl(remote: string): Promise<string>;
+    getPriorReview(): Promise<PriorReview | undefined>;
+    publish(): Promise<{
+        warnings: string[];
+    }>;
+    private target;
+    private resolveTarget;
+}
+//# sourceMappingURL=local-adapter.d.ts.map

package/dist/local-adapter.js

@@ -0,0 +1,252 @@
+import { cp, lstat, mkdtemp, open, readFile, readlink, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { parseUnifiedDiff, } from "@open-cr-agent/core";
+import { GitError, git, isShallow, SHALLOW_HINT } from "./git.js";
+const WORKING_TREE = "working-tree";
+const SEARCH_RESULT_LIMIT = 100;
+const SEARCH_OUTPUT_BYTES = 4 * 1024 * 1024;
+// A run keeps every file it reads in memory; files beyond this are read in
+// part (larger ones are diffed as binary and not reviewed anyway).
+export const MAX_READ_BYTES = 2 * 1024 * 1024;
+// Explicit prefixes and flags keep the output parseable whatever the user's
+// diff configuration (noprefix, mnemonicPrefix, external drivers, relative).
+// Files over the threshold diff as binary, so one generated or vendored
+// monster cannot fill memory before selection excludes it.
+const DIFF_ARGS = [
+    "-c",
+    "core.quotepath=true",
+    "-c",
+    "core.bigFileThreshold=1m",
+    "diff",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--no-relative",
+    "--find-renames",
+    "--src-prefix=a/",
+    "--dst-prefix=b/",
+];
+export class LocalGitAdapter {
+    options;
+    name = "local";
+    resolved;
+    constructor(options) {
+        this.options = options;
+    }
+    async repositoryRoot() {
+        return (await this.target()).root;
+    }
+    async getChangeRequest() {
+        return (await this.target()).request;
+    }
+    async getDiff() {
+        const { root, base, head } = await this.target();
+        if (head !== undefined) {
+            return parseUnifiedDiff(await git([...DIFF_ARGS, base, head, "--"], { cwd: root }));
+        }
+        return parseUnifiedDiff(await workspaceDiff(root, base));
+    }
+    async readFile(path) {
+        const { root, head } = await this.target();
+        const inside = relativeInside(root, resolve(root, path));
+        if (inside === undefined)
+            return undefined;
+        if (head === undefined)
+            return readWorkingTreeFile(root, inside);
+        try {
+            return await git(["cat-file", "blob", `${head}:${inside.split(sep).join("/")}`], {
+                cwd: root,
+                truncateAt: MAX_READ_BYTES,
+            });
+        }
+        catch (error) {
+            if (error instanceof GitError && error.exitCode === 128)
+                return undefined;
+            throw error;
+        }
+    }
+    async searchCode(literal) {
+        const { root, head } = await this.target();
+        const args = ["grep", "-n", "-z", "-I", "--no-color", "--full-name", "-F", "-m", "20"];
+        if (head === undefined)
+            args.push("--untracked");
+        args.push("-e", literal);
+        if (head !== undefined)
+            args.push(head);
+        const out = await git([...args, "--"], {
+            cwd: root,
+            okExitCodes: [0, 1],
+            truncateAt: SEARCH_OUTPUT_BYTES,
+        });
+        const prefix = head === undefined ? "" : `${head}:`;
+        const lines = out.split("\n");
+        // Output cut at the byte cap ends inside a line.
+        if (!out.endsWith("\n"))
+            lines.pop();
+        return lines
+            .filter((line) => line !== "")
+            .slice(0, SEARCH_RESULT_LIMIT)
+            .map((line) => {
+            const [path = "", lineNumber = "0", ...text] = line.split("\0");
+            return { path: path.slice(prefix.length), line: Number(lineNumber), text: text.join("\0") };
+        });
+    }
+    async remoteUrl(remote) {
+        const { root } = await this.target();
+        return (await git(["remote", "get-url", "--end-of-options", remote], { cwd: root })).trim();
+    }
+    async getPriorReview() {
+        return undefined;
+    }
+    async publish() {
+        return { warnings: [] };
+    }
+    target() {
+        this.resolved ??= this.resolveTarget();
+        return this.resolved;
+    }
+    async resolveTarget() {
+        const root = (await git(["rev-parse", "--show-toplevel"], { cwd: this.options.cwd })).trim();
+        const target = this.options.target;
+        if (target.mode === "workspace") {
+            const base = (await tryVerifyCommit(root, "HEAD")) ?? (await emptyTree(root));
+            return {
+                root,
+                base,
+                head: undefined,
+                request: request(WORKING_TREE, "Working tree changes", "", base, WORKING_TREE),
+            };
+        }
+        if (target.mode === "range") {
+            const from = await verifyCommit(root, target.from);
+            const to = await verifyCommit(root, target.to);
+            const base = await mergeBase(root, from, to);
+            const subjects = await git(["log", "--format=- %s", `${base}..${to}`], { cwd: root });
+            const title = `Changes from ${target.from} to ${target.to}`;
+            return {
+                root,
+                base,
+                head: to,
+                request: request(`${base}..${to}`, title, subjects.trim(), base, to),
+            };
+        }
+        const head = await verifyCommit(root, target.commit);
+        const base = (await tryVerifyCommit(root, `${head}^`)) ?? (await emptyTree(root));
+        const message = (await git(["log", "-1", "--format=%B", head], { cwd: root })).trim();
+        const [title = "", ...body] = message.split("\n");
+        return {
+            root,
+            base,
+            head,
+            request: request(head, title, body.join("\n").trim(), base, head),
+        };
+    }
+}
+// Untracked files join the diff through intent-to-add entries in a throwaway
+// copy of the index: one git process for any number of files, and the
+// user's real index is never touched.
+async function workspaceDiff(root, base) {
+    const listing = await git(["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root });
+    const untracked = listing.split("\0").filter((p) => p !== "");
+    if (untracked.length === 0)
+        return git([...DIFF_ARGS, base, "--"], { cwd: root });
+    const dir = await mkdtemp(join(tmpdir(), "ocra-index-"));
+    try {
+        const index = join(dir, "index");
+        const realIndex = (await git(["rev-parse", "--git-path", "index"], { cwd: root })).trim();
+        // The copy keeps the index's timestamp: git compares it with entry
+        // timestamps to catch same-second, same-size edits ("racy git"), and a
+        // fresh timestamp would make it trust stale stat data and miss them.
+        await cp(resolve(root, realIndex), index, { preserveTimestamps: true }).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+        const env = { GIT_INDEX_FILE: index, GIT_LITERAL_PATHSPECS: "1" };
+        await git(["add", "--intent-to-add", "--pathspec-from-file=-", "--pathspec-file-nul"], {
+            cwd: root,
+            env,
+            input: untracked.join("\0"),
+        });
+        return await git([...DIFF_ARGS, base, "--"], { cwd: root, env });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+async function mergeBase(root, from, to) {
+    try {
+        return (await git(["merge-base", from, to], { cwd: root })).trim();
+    }
+    catch (error) {
+        if (error instanceof GitError && (await isShallow(root))) {
+            throw new Error(`Cannot find where ${from.slice(0, 7)} and ${to.slice(0, 7)} diverge: ${SHALLOW_HINT}`);
+        }
+        throw error;
+    }
+}
+function relativeInside(root, absolute) {
+    const inside = relative(root, absolute);
+    if (inside === "" || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
+        return undefined;
+    }
+    return inside;
+}
+// Reads what git would store, as range and commit mode do: a symlink reads as
+// its target path and a path through a symlinked directory does not exist.
+// Following links would let a committed `notes.txt -> .env` read a file the
+// core access policy refuses by name.
+async function readWorkingTreeFile(root, inside) {
+    try {
+        const parent = dirname(inside);
+        const realParent = await realpath(resolve(root, parent));
+        if (realParent !== resolve(await realpath(root), parent))
+            return undefined;
+        const path = join(realParent, basename(inside));
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            return await readlink(path, "utf8");
+        if (!stat.isFile())
+            return undefined;
+        if (stat.size <= MAX_READ_BYTES)
+            return await readFile(path, "utf8");
+        const handle = await open(path, "r");
+        try {
+            const buffer = Buffer.alloc(MAX_READ_BYTES);
+            const { bytesRead } = await handle.read(buffer, 0, MAX_READ_BYTES, 0);
+            return buffer.subarray(0, bytesRead).toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return undefined;
+        throw error;
+    }
+}
+function request(id, title, description, baseSha, headSha) {
+    return { id, title, description, baseSha, headSha };
+}
+async function verifyCommit(root, ref) {
+    const sha = await tryVerifyCommit(root, ref);
+    if (sha === undefined)
+        throw new Error(`Unknown commit: ${ref}`);
+    return sha;
+}
+// --end-of-options stops a user-supplied ref such as "--output=x" from being
+// read as an option.
+async function tryVerifyCommit(root, ref) {
+    const out = await git(["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`], {
+        cwd: root,
+        okExitCodes: [0, 1, 128],
+    });
+    const sha = out.trim();
+    return sha === "" ? undefined : sha;
+}
+async function emptyTree(root) {
+    return (await git(["hash-object", "-t", "tree", "--stdin"], { cwd: root, input: "" })).trim();
+}
+//# sourceMappingURL=local-adapter.js.map

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import type { OcraPlugin } from "@open-cr-agent/core";
+export declare const localGitPlugin: OcraPlugin;
+export declare function findRepositoryRoot(cwd: string): Promise<string>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { git } from "./git.js";
+import { LocalGitAdapter } from "./local-adapter.js";
+const optionsSchema = z.object({
+    cwd: z.string().min(1),
+    target: z.discriminatedUnion("mode", [
+        z.object({ mode: z.literal("workspace") }),
+        z.object({ mode: z.literal("range"), from: z.string().min(1), to: z.string().min(1) }),
+        z.object({ mode: z.literal("commit"), commit: z.string().min(1) }),
+    ]),
+});
+export const localGitPlugin = {
+    name: "vcs-local",
+    configure(ctx) {
+        ctx.registerVcs("local", (options) => new LocalGitAdapter(optionsSchema.parse(options)));
+    },
+};
+export async function findRepositoryRoot(cwd) {
+    return (await git(["rev-parse", "--show-toplevel"], { cwd })).trim();
+}
+//# sourceMappingURL=plugin.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@open-cr-agent/vcs-local",
+  "version": "0.1.0",
+  "description": "Local git adapter for Open-CR-Agent: working tree, ranges and commits",
+  "keywords": [
+    "code-review",
+    "git"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://ocra.majincheng.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jma49/Open-CR-Agent.git",
+    "directory": "packages/vcs-local"
+  },
+  "bugs": "https://github.com/jma49/Open-CR-Agent/issues",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "dependencies": {
+    "@open-cr-agent/core": "0.1.0",
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}