@arnilo/prism-coding-agent 0.0.7 → 0.0.10

package/dist/git-exec.js

@@ -0,0 +1,257 @@
+/**
+ * Typed Git executable runner.
+ *
+ * Always uses argument arrays (never a shell), a noninteractive pager-safe
+ * environment, and finite stdout/stderr retention. Hosts may inject a custom
+ * runner (for example a sandbox `execFile` adapter) without changing tool code.
+ */
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { isAbsolute } from "node:path";
+import { DEFAULT_GIT_TIMEOUT_MS, DEFAULT_MAX_GIT_OUTPUT_BYTES, HARD_GIT_TIMEOUT_MS, HARD_MAX_GIT_OUTPUT_BYTES, validateCodingLimit, } from "./limits.js";
+export class GitError extends Error {
+    code = "ERR_PRISM_GIT";
+    exitCode;
+    constructor(message, exitCode = null) {
+        super(message);
+        this.name = "GitError";
+        this.exitCode = exitCode;
+    }
+}
+/** Noninteractive, pager-safe, credential-prompt-free baseline for Git child processes. */
+export const SAFE_GIT_ENV = Object.freeze({
+    PATH: "/usr/bin:/bin",
+    LANG: "C",
+    LC_ALL: "C",
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_OPTIONAL_LOCKS: "0",
+    GIT_PAGER: "cat",
+    PAGER: "cat",
+    GCM_INTERACTIVE: "never",
+    GIT_CONFIG_NOSYSTEM: "1",
+});
+/** Config flags prepended to every git invocation to disable hooks/external helpers. */
+export const SAFE_GIT_CONFIG_ARGS = Object.freeze([
+    "-c",
+    "core.hooksPath=/dev/null",
+    "-c",
+    "core.pager=cat",
+    "-c",
+    "sequence.editor=true",
+    "-c",
+    "credential.helper=",
+    "-c",
+    "advice.detachedHead=false",
+]);
+export async function assertAbsoluteGit(path) {
+    if (!isAbsolute(path)) {
+        throw new GitError("gitPath must be an absolute executable path");
+    }
+    try {
+        await access(path, fsConstants.X_OK);
+    }
+    catch {
+        throw new GitError(`git executable is missing or not executable: ${path}`);
+    }
+    return path;
+}
+function mergeEnv(extra) {
+    return { ...SAFE_GIT_ENV, ...(extra ?? {}) };
+}
+/** Local spawn-based Git runner. Never invokes a shell. */
+export async function runGitCli(request) {
+    if (request.signal?.aborted) {
+        throw new GitError("Git operation aborted before start");
+    }
+    for (const arg of request.args) {
+        if (typeof arg !== "string" || arg.includes("\0")) {
+            throw new GitError("Git args must be strings without NUL");
+        }
+    }
+    const maxOutputBytes = validateCodingLimit("maxOutputBytes", request.maxOutputBytes ?? DEFAULT_MAX_GIT_OUTPUT_BYTES, HARD_MAX_GIT_OUTPUT_BYTES);
+    const timeoutMs = validateCodingLimit("timeoutMs", request.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS, HARD_GIT_TIMEOUT_MS);
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let timedOut = false;
+        let aborted = false;
+        let outputBytes = 0;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let child;
+        let timer;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            request.signal?.removeEventListener("abort", onAbort);
+        };
+        const killTree = () => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        };
+        const finalize = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve({
+                exitCode,
+                stdout: Buffer.concat(stdoutChunks),
+                stderr: Buffer.concat(stderrChunks),
+                timedOut,
+                aborted,
+                outputBytes,
+            });
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onAbort = () => {
+            aborted = true;
+            killTree();
+        };
+        try {
+            child = spawn(request.gitPath, [...SAFE_GIT_CONFIG_ARGS, ...request.args], {
+                cwd: request.cwd,
+                env: mergeEnv(request.env),
+                stdio: ["pipe", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            reject(new GitError(message));
+            return;
+        }
+        const track = (chunk, target) => {
+            outputBytes += chunk.length;
+            if (outputBytes > maxOutputBytes) {
+                killTree();
+                fail(new GitError(`Git output exceeded ${maxOutputBytes} byte limit`));
+                return;
+            }
+            target.push(chunk);
+        };
+        child.stdout.on("data", (chunk) => track(chunk, stdoutChunks));
+        child.stderr.on("data", (chunk) => track(chunk, stderrChunks));
+        child.on("error", (error) => fail(new GitError(error.message)));
+        child.on("close", (code) => finalize(code));
+        if (request.stdin !== undefined) {
+            const payload = typeof request.stdin === "string" ? Buffer.from(request.stdin) : request.stdin;
+            child.stdin.end(payload);
+        }
+        else {
+            child.stdin.end();
+        }
+        timer = setTimeout(() => {
+            timedOut = true;
+            killTree();
+        }, timeoutMs);
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Resolve a bound Git runner from an absolute git path, custom runner, or sandbox execFile.
+ */
+export async function createBoundGitRunner(options) {
+    const gitPath = await assertAbsoluteGit(options?.gitPath ?? "/usr/bin/git");
+    const maxOutputBytes = options?.maxOutputBytes;
+    const timeoutMs = options?.timeoutMs;
+    if (options?.runner) {
+        const custom = options.runner;
+        return {
+            gitPath,
+            exec: (request) => custom({
+                ...request,
+                gitPath,
+                maxOutputBytes: request.maxOutputBytes ?? maxOutputBytes,
+                timeoutMs: request.timeoutMs ?? timeoutMs,
+            }),
+        };
+    }
+    if (options?.execFile) {
+        const execFile = options.execFile;
+        return {
+            gitPath,
+            exec: async (request) => {
+                if (request.signal?.aborted)
+                    throw new GitError("Git operation aborted before start");
+                const chunks = [];
+                let outputBytes = 0;
+                const limit = validateCodingLimit("maxOutputBytes", request.maxOutputBytes ?? maxOutputBytes ?? DEFAULT_MAX_GIT_OUTPUT_BYTES, HARD_MAX_GIT_OUTPUT_BYTES);
+                const args = [...SAFE_GIT_CONFIG_ARGS, ...request.args];
+                try {
+                    const { exitCode } = await execFile({
+                        file: gitPath,
+                        args,
+                        cwd: request.cwd,
+                        env: mergeEnv(request.env),
+                        signal: request.signal,
+                        timeout: request.timeoutMs ?? timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
+                        onData: (data) => {
+                            outputBytes += data.length;
+                            if (outputBytes > limit) {
+                                throw new GitError(`Git output exceeded ${limit} byte limit`);
+                            }
+                            chunks.push(data);
+                        },
+                    });
+                    return {
+                        exitCode,
+                        stdout: Buffer.concat(chunks),
+                        stderr: Buffer.alloc(0),
+                        timedOut: false,
+                        aborted: false,
+                        outputBytes,
+                    };
+                }
+                catch (error) {
+                    if (error instanceof GitError)
+                        throw error;
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new GitError(message);
+                }
+            },
+        };
+    }
+    return {
+        gitPath,
+        exec: (request) => runGitCli({
+            ...request,
+            gitPath,
+            maxOutputBytes: request.maxOutputBytes ?? maxOutputBytes,
+            timeoutMs: request.timeoutMs ?? timeoutMs,
+        }),
+    };
+}
+export function gitText(result, stream = "stdout") {
+    return (stream === "stdout" ? result.stdout : result.stderr).toString("utf8");
+}
+export async function gitRequireOk(runner, request, label) {
+    const result = await runner.exec(request);
+    if (result.timedOut)
+        throw new GitError(`${label} timed out`, result.exitCode);
+    if (result.aborted)
+        throw new GitError(`${label} aborted`, result.exitCode);
+    if (result.exitCode !== 0) {
+        const err = gitText(result, "stderr").trim() || gitText(result).trim() || `exit ${result.exitCode}`;
+        throw new GitError(`${label} failed: ${err}`, result.exitCode);
+    }
+    return result;
+}
+//# sourceMappingURL=git-exec.js.map

package/dist/git-status.d.ts

@@ -0,0 +1,30 @@
+export type GitStatusEntryKind = "ordinary" | "rename" | "copy" | "unmerged" | "untracked" | "ignored";
+export interface GitStatusBranch {
+    readonly oid: string | null;
+    readonly head: string | null;
+    readonly detached: boolean;
+    readonly upstream: string | null;
+    readonly ahead: number | null;
+    readonly behind: number | null;
+    readonly initial: boolean;
+}
+export interface GitStatusEntry {
+    readonly kind: GitStatusEntryKind;
+    readonly xy: string;
+    readonly path: string;
+    readonly origPath?: string;
+    readonly score?: string;
+}
+export interface GitStatusResult {
+    readonly branch: GitStatusBranch;
+    readonly entries: readonly GitStatusEntry[];
+    readonly dirty: boolean;
+    readonly truncated: boolean;
+}
+/**
+ * Parse porcelain v2 NUL-delimited status. `maxEntries` truncates retained
+ * entries without failing; callers surface truncation in tool metadata.
+ */
+export declare function parsePorcelainV2(stdout: Buffer, options?: {
+    maxEntries?: number;
+}): GitStatusResult;

package/dist/git-status.js

@@ -0,0 +1,146 @@
+/**
+ * Parse `git status --porcelain=v2 -z --branch` output into structured records.
+ *
+ * Paths remain repository-relative as emitted by Git. Leading-dash and control
+ * characters are preserved as data; callers must pass paths after `--`.
+ */
+import { GitError } from "./git-exec.js";
+function splitNulRecords(buffer) {
+    const text = buffer.toString("utf8");
+    if (text.length === 0)
+        return [];
+    const parts = text.split("\0");
+    if (parts.length > 0 && parts[parts.length - 1] === "")
+        parts.pop();
+    return parts;
+}
+function parseAheadBehind(token) {
+    if (!token)
+        return { ahead: null, behind: null };
+    // Format: +<ahead> -<behind>
+    const match = /^\+(\d+) -(\d+)$/.exec(token);
+    if (!match)
+        return { ahead: null, behind: null };
+    return { ahead: Number(match[1]), behind: Number(match[2]) };
+}
+/**
+ * Parse porcelain v2 NUL-delimited status. `maxEntries` truncates retained
+ * entries without failing; callers surface truncation in tool metadata.
+ */
+export function parsePorcelainV2(stdout, options) {
+    const records = splitNulRecords(stdout);
+    const branch = {
+        oid: null,
+        head: null,
+        detached: false,
+        upstream: null,
+        ahead: null,
+        behind: null,
+        initial: false,
+    };
+    const entries = [];
+    const maxEntries = options?.maxEntries;
+    let truncated = false;
+    let i = 0;
+    while (i < records.length) {
+        const record = records[i];
+        i++;
+        if (record.startsWith("# ")) {
+            const body = record.slice(2);
+            if (body.startsWith("branch.oid ")) {
+                const oid = body.slice("branch.oid ".length);
+                if (oid === "(initial)") {
+                    branch.initial = true;
+                    branch.oid = null;
+                }
+                else {
+                    branch.oid = oid;
+                }
+            }
+            else if (body.startsWith("branch.head ")) {
+                const head = body.slice("branch.head ".length);
+                if (head === "(detached)") {
+                    branch.detached = true;
+                    branch.head = null;
+                }
+                else {
+                    branch.head = head;
+                }
+            }
+            else if (body.startsWith("branch.upstream ")) {
+                branch.upstream = body.slice("branch.upstream ".length);
+            }
+            else if (body.startsWith("branch.ab ")) {
+                const ab = parseAheadBehind(body.slice("branch.ab ".length));
+                branch.ahead = ab.ahead;
+                branch.behind = ab.behind;
+            }
+            continue;
+        }
+        if (maxEntries !== undefined && entries.length >= maxEntries) {
+            truncated = true;
+            continue;
+        }
+        if (record.startsWith("? ")) {
+            entries.push({ kind: "untracked", xy: "??", path: record.slice(2) });
+            continue;
+        }
+        if (record.startsWith("! ")) {
+            entries.push({ kind: "ignored", xy: "!!", path: record.slice(2) });
+            continue;
+        }
+        if (record.startsWith("1 ")) {
+            // 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+            const parts = record.split(" ");
+            if (parts.length < 9)
+                throw new GitError(`malformed ordinary status record: ${record}`);
+            const xy = parts[1];
+            const path = parts.slice(8).join(" ");
+            entries.push({ kind: "ordinary", xy, path });
+            continue;
+        }
+        if (record.startsWith("2 ")) {
+            // 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path>\0<origPath>
+            const parts = record.split(" ");
+            if (parts.length < 10)
+                throw new GitError(`malformed rename/copy status record: ${record}`);
+            const xy = parts[1];
+            const scoreToken = parts[8];
+            const path = parts.slice(9).join(" ");
+            const origPath = records[i];
+            if (origPath === undefined)
+                throw new GitError("rename/copy status missing origPath");
+            i++;
+            const kind = scoreToken.startsWith("C") ? "copy" : "rename";
+            entries.push({ kind, xy, path, origPath, score: scoreToken });
+            continue;
+        }
+        if (record.startsWith("u ")) {
+            // u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+            const parts = record.split(" ");
+            if (parts.length < 11)
+                throw new GitError(`malformed unmerged status record: ${record}`);
+            const xy = parts[1];
+            const path = parts.slice(10).join(" ");
+            entries.push({ kind: "unmerged", xy, path });
+            continue;
+        }
+        throw new GitError(`unrecognized porcelain v2 record: ${record.slice(0, 80)}`);
+    }
+    const dirty = entries.some((entry) => entry.kind !== "ignored");
+    return {
+        branch: {
+            oid: branch.oid,
+            head: branch.head,
+            detached: branch.detached,
+            upstream: branch.upstream,
+            ahead: branch.ahead,
+            behind: branch.behind,
+            initial: branch.initial,
+        },
+        entries,
+        dirty,
+        truncated,
+    };
+}
+//# sourceMappingURL=git-status.js.map

package/dist/git-tools.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Structured Git tool factories and aggregator.
+ *
+ * Tools cover status, diff, branch, worktree, apply, commit, and PR handoff.
+ * Shell is never used internally; all Git invocations go through typed arg arrays.
+ */
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import { type ArtifactWriter, type CreateGitOperationsOptions, type GitOperations } from "./git.js";
+import { type CodingCheckToolOptions, type NamedCheckDefinition } from "./checks.js";
+export interface GitToolsOptions {
+    readonly executionPolicy?: ExecutionPolicy;
+    readonly gitPath?: string;
+    readonly execFile?: CreateGitOperationsOptions["execFile"];
+    readonly runner?: CreateGitOperationsOptions["runner"];
+    readonly artifactWriter?: ArtifactWriter;
+    readonly commitIdentity?: CreateGitOperationsOptions["commitIdentity"];
+    readonly limits?: CreateGitOperationsOptions;
+    readonly operations?: GitOperations;
+    /** Optional named checks included by `createGitTools` when provided. */
+    readonly checks?: Readonly<Record<string, NamedCheckDefinition>>;
+    readonly checkOptions?: Omit<CodingCheckToolOptions, "checks" | "executionPolicy">;
+}
+export declare function createGitStatusTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
+export declare function createGitDiffTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
+export declare function createGitBranchTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
+export declare function createGitWorktreeTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
+export declare function createGitApplyTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
+export declare function createGitCommitTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
+export declare function createGitPrHandoffTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
+/**
+ * Structured Git tool set. Optionally appends `coding_check` when `checks` are declared.
+ * Not included in `createCodingTools()` — hosts opt in explicitly.
+ */
+export declare function createGitTools(cwd: string, options?: GitToolsOptions): readonly ToolDefinition[];