@nathapp/nax-agent 0.1.0

package/dist/tools/git-commit.js

@@ -0,0 +1,220 @@
+/**
+ * Stage-and-commit, the one mutating git operation the implementer role needs.
+ *
+ * Separate from gitTool because buildGitArgv cannot express it: that builder
+ * terminates with `--` and pathspecs and refuses any element beginning with
+ * "-", so `commit -m <message>` is not representable in it. Splitting the tool
+ * also lets a stage be granted the read verbs without the write one.
+ *
+ * The message is an argv ELEMENT, never parsed. A message that looks like a
+ * flag is inert because it sits after `-m` in an argv array that never reaches
+ * a shell -- a test pins that position.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gitlinkSafeAdd, hasStagedChanges } from "#src/internal/git-add";
+import { gitWithTimeout } from "#src/internal/git-exec";
+import { gitIgnorePatternsOf } from "./protected-paths.js";
+export function buildCommitArgvs(input) {
+    const message = input.message;
+    if (typeof message !== "string" || message.trim() === "") {
+        return { error: "message must be a non-empty string" };
+    }
+    const paths = Array.isArray(input.paths) ? input.paths : [];
+    if (paths.length === 0)
+        return { error: "paths must name at least one file" };
+    const add = ["add", "--"];
+    for (const path of paths) {
+        if (typeof path !== "string")
+            return { error: "paths must be strings" };
+        if (path.startsWith("-"))
+            return { error: `path "${path}" may not begin with "-"` };
+        add.push(path);
+    }
+    return { add, commit: ["commit", "-m", message] };
+}
+/**
+ * Split `paths` into ones GitCommit may stage and ones it must refuse, per the
+ * caller-supplied `ignorePatterns` (nax passes `NAX_GITIGNORE_ENTRIES` -- the
+ * same SSOT `nax init`, `WorktreeManager`, and
+ * `scripts/check-nax-artifacts-untracked.ts` all enforce).
+ *
+ * A real run staged its own `.nax/scratchpad/*.md` files through this exact
+ * tool (no filter existed at all): the ignore-file reconcile in
+ * `src/execution/lifecycle/gitignore-reconcile.ts` closes this for `git add -A`
+ * and human adds, but is per-clone -- a fresh clone or CI has no local
+ * `.git/info/exclude` yet, so this tool needs its own, independent check.
+ *
+ * The `ignorePatterns` are gitignore PATTERNS (`**\/.nax/scratchpad/`), not
+ * literal paths -- hand-rolled substring/glob matching has bitten this repo
+ * before (see the comment in `src/worktree/manager.ts` on `/foo/runs/` wrongly
+ * "containing" `runs/`). Delegate to `git check-ignore` itself, exactly as
+ * `scripts/check-nax-artifacts-untracked.ts` delegates to `git ls-files` --
+ * both feed `NAX_GITIGNORE_ENTRIES` to git via a temp exclude file rather than
+ * re-implementing pattern matching. `--no-index` is required: a path GitCommit
+ * is being asked to stage for the first time is not yet in the index, and
+ * `check-ignore` without it can decline to answer for such a path.
+ *
+ * THREE-STATE, fail-closed (code review, post-Fix-3): `git check-ignore`
+ * exits 0 (ignored), 1 (not ignored) or 128 (fatal -- e.g. path outside the
+ * repo, or not a git repo at all). `gitWithTimeout` additionally collapses a
+ * hung subprocess to `exitCode: 1` with `timedOut: true` -- so `exitCode ===
+ * 1` ALONE is not "not ignored", it is ALSO what a timeout looks like. Reading
+ * it as "not ignored" without checking `timedOut` first put a nax-owned path
+ * straight into `kept` on any error or timeout: fail-OPEN, silently, exactly
+ * the class of bug this tool exists to prevent -- and under exactly the
+ * contention (parallel worktrees stressing git) most likely to produce one.
+ * A path that cannot be classified goes to neither `kept` nor `skipped`; it
+ * is reported by the caller, loudly, as its own category.
+ *
+ * One `check-ignore` subprocess per path (not batched into one call): batching
+ * would collapse this exact three-state distinction, since git's exit code for
+ * a multi-path invocation reflects "at least one path matched", not a per-path
+ * verdict, and a single fatal path (exit 128) would poison every other path in
+ * the batch as unknown even when they are perfectly answerable individually.
+ * Fine for the batch sizes a single commit call names.
+ */
+export async function partitionNaxOwnedPaths(root, paths, ignorePatterns) {
+    if (paths.length === 0)
+        return { kept: [], skipped: [], unknown: [] };
+    // Fail CLOSED on an absent policy (S1 spec port 6): `ToolRunContext.protectedPaths`
+    // is optional, so a runtime built without one hands us an empty list. Writing
+    // that list to the exclude file makes `check-ignore` exit 1 for EVERY path --
+    // which reads as "not ignored" and would put nax-owned run artifacts straight
+    // back into `kept`, silently, exactly the incident this tool exists to prevent.
+    // Refusing every path keeps the failure loud and puts it in the category the
+    // caller already reports.
+    if (ignorePatterns.length === 0) {
+        return {
+            kept: [],
+            skipped: [],
+            unknown: paths.map((path) => ({ path, reason: "no protected-paths ignore patterns were supplied" })),
+        };
+    }
+    const excludeDir = mkdtempSync(join(tmpdir(), "nax-commit-filter-"));
+    const excludeFile = join(excludeDir, "exclude");
+    try {
+        writeFileSync(excludeFile, `${ignorePatterns.join("\n")}\n`, "utf8");
+        const results = await Promise.all(paths.map(async (path) => {
+            // `check-ignore` has no `--exclude-from` of its own (unlike `ls-files`,
+            // which `scripts/check-nax-artifacts-untracked.ts` uses) -- pointing
+            // `core.excludesFile` at the temp file via `-c` is the documented way
+            // to feed it an arbitrary pattern list.
+            const { exitCode, timedOut, stderr } = await gitWithTimeout(["-c", `core.excludesFile=${excludeFile}`, "check-ignore", "--no-index", "-q", "--", path], root);
+            if (timedOut)
+                return { path, status: "unknown", reason: "git check-ignore timed out" };
+            if (exitCode === 0)
+                return { path, status: "ignored" };
+            if (exitCode === 1)
+                return { path, status: "not-ignored" };
+            const detail = stderr.trim();
+            return {
+                path,
+                status: "unknown",
+                reason: `git check-ignore exited ${exitCode}${detail ? `: ${detail}` : ""}`,
+            };
+        }));
+        const kept = [];
+        const skipped = [];
+        const unknown = [];
+        for (const result of results) {
+            if (result.status === "ignored")
+                skipped.push(result.path);
+            else if (result.status === "not-ignored")
+                kept.push(result.path);
+            else
+                unknown.push({ path: result.path, reason: result.reason });
+        }
+        return { kept, skipped, unknown };
+    }
+    finally {
+        rmSync(excludeDir, { recursive: true, force: true });
+    }
+}
+export const gitCommitTool = {
+    name: "GitCommit",
+    description: "Stage the named files and commit them. Supply the message as text and the files as an array; this is not a command line.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            message: { type: "string", description: "Commit message. May contain a blank line and a body." },
+            paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Files to stage, relative to the repository root",
+            },
+        },
+        required: ["message", "paths"],
+    },
+    scope: { pathFields: [], arrayPathFields: ["paths"] },
+    async run(input, ctx) {
+        // Fix 3: filter nax-owned artifacts out of the caller's paths BEFORE
+        // building argv, so they can never reach `git add`. Only attempted when
+        // every supplied path is a plain string -- otherwise buildCommitArgvs's
+        // own type validation below must see the original, unfiltered input so
+        // its error message stays accurate.
+        const rawPaths = Array.isArray(input.paths) ? input.paths : [];
+        let effectiveInput = input;
+        let skipped = [];
+        let unknown = [];
+        if (rawPaths.length > 0 && rawPaths.every((path) => typeof path === "string")) {
+            const partition = await partitionNaxOwnedPaths(ctx.root, rawPaths, gitIgnorePatternsOf(ctx));
+            skipped = partition.skipped;
+            unknown = partition.unknown;
+            // Fail CLOSED: an unresolved path is refused, exactly like a nax-owned
+            // one -- it never reaches `kept`, so it can never reach `git add`.
+            if (partition.kept.length === 0) {
+                const refusals = [];
+                if (skipped.length > 0) {
+                    refusals.push(`${skipped.length} nax-owned run artifact(s), not staged: ${skipped.join(", ")}`);
+                }
+                if (unknown.length > 0) {
+                    refusals.push(`${unknown.length} path(s) whose ignore status could not be determined, refused to stage them: ${unknown
+                        .map((u) => `${u.path} (${u.reason})`)
+                        .join("; ")}`);
+                }
+                return {
+                    content: `Nothing was staged -- every supplied path was refused: ${refusals.join("; ")}`,
+                    isError: true,
+                };
+            }
+            effectiveInput = { ...input, paths: partition.kept };
+        }
+        const built = buildCommitArgvs(effectiveInput);
+        if ("error" in built)
+            return { content: built.error, isError: true };
+        // Through gitlinkSafeAdd: a bare `git add` would run git inside any gitlink
+        // the paths cover, under that nested repo's own config (#2210).
+        const pathspecs = built.add.slice(built.add.indexOf("--") + 1);
+        const staged = await gitlinkSafeAdd(gitWithTimeout, ctx.root, { pathspecs, timeoutMs: 30_000 });
+        if (staged.exitCode !== 0) {
+            return { content: `git add failed: ${staged.stderr.trim() || `exit ${staged.exitCode}`}`, isError: true };
+        }
+        // The agent chooses the paths, so it can make the add a no-op; a commit with
+        // nothing staged would print status, which can recurse into a gitlink (#2210).
+        const hasStaged = await hasStagedChanges(gitWithTimeout, ctx.root, 30_000);
+        if (hasStaged !== true) {
+            const why = hasStaged === false ? "nothing is staged" : "could not tell whether anything is staged";
+            return { content: `git commit not run: ${why}`, isError: true };
+        }
+        const committed = await gitWithTimeout(built.commit, ctx.root, 30_000);
+        if (committed.exitCode !== 0) {
+            return {
+                content: `git commit failed: ${committed.stderr.trim() || `exit ${committed.exitCode}`}`,
+                isError: true,
+            };
+        }
+        const notes = [];
+        if (skipped.length > 0) {
+            notes.push(`[nax] Skipped ${skipped.length} nax-owned run artifact(s) -- not staged: ${skipped.join(", ")}`);
+        }
+        if (unknown.length > 0) {
+            notes.push(`[nax] REFUSED to stage ${unknown.length} path(s) with an unresolved ignore status (fail-closed): ${unknown
+                .map((u) => `${u.path} (${u.reason})`)
+                .join("; ")}`);
+        }
+        const skipNote = notes.length > 0 ? `\n\n${notes.join("\n")}` : "";
+        return { content: committed.stdout.trim().slice(0, ctx.maxBytes) + skipNote };
+    },
+};

package/dist/tools/git-flags/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Git global options nax refuses to let any caller introduce.
+ *
+ * A leaf module with NO imports, deliberately. `src/tools/git.ts` imports
+ * `@/utils/git`, so anything `src/utils/git.ts` reaches must not lead back to
+ * `src/tools/git.ts` — see check-import-cycles (baseline 0).
+ *
+ * `-c` is here because `-c core.pager=<cmd>` is arbitrary code execution.
+ */
+export declare const GIT_ESCAPE_FLAGS: readonly string[];

package/dist/tools/git-flags/index.js

@@ -0,0 +1,10 @@
+/**
+ * Git global options nax refuses to let any caller introduce.
+ *
+ * A leaf module with NO imports, deliberately. `src/tools/git.ts` imports
+ * `@/utils/git`, so anything `src/utils/git.ts` reaches must not lead back to
+ * `src/tools/git.ts` — see check-import-cycles (baseline 0).
+ *
+ * `-c` is here because `-c core.pager=<cmd>` is arbitrary code execution.
+ */
+export const GIT_ESCAPE_FLAGS = ["-C", "--git-dir", "--work-tree", "--exec-path", "-c"];

package/dist/tools/git.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Read-only git, for reviewers that need a real diff rather than one pushed
+ * into the prompt.
+ *
+ * This spawns a subprocess, which ADR-029 section 3 severed for Bash. The
+ * distinction, written down rather than assumed: git is a FIXED binary invoked
+ * with an argv nax constructs entirely, with no shell. The model supplies
+ * structure — a subcommand, refs, pathspecs — never a command string. Bash
+ * inverts that, which is why it needs a sandbox and a threat model instead of
+ * an allowlist.
+ *
+ * Reuses gitWithTimeout, which already provides the argv-array spawn, the
+ * explicit cwd, the SIGKILL timeout, and concurrent pipe draining — the last of
+ * which matters here because `git log -p` is exactly the output that fills a
+ * 64KB pipe buffer and deadlocks a naive implementation.
+ */
+import type { CodingTool } from "./registry.ts";
+/**
+ * Read-only verbs. Mutating verbs are not representable in the input type.
+ *
+ * Note what bounds these: the argv shape below, not the verb list. A read-only
+ * verb still spans the whole repository unless its scope is stated.
+ */
+export declare const GIT_READ_VERBS: readonly string[];
+/**
+ * Typed flag fields, and the verbs each one is valid on.
+ *
+ * nax emits every one of these flags itself: a boolean or a closed enum comes
+ * in, a fixed string goes out. The model never supplies flag text, so the
+ * property the header comment defends — the model supplies structure, nax
+ * constructs the argv — is unchanged by their existence. That is the whole
+ * reason they are typed fields rather than a passthrough list.
+ *
+ * They exist because `git diff --name-only --diff-filter=A` is step 1 of the
+ * adversarial reviewer's test-audit workflow and was not expressible at all:
+ * the only way to ask for it was to put the flags in `refs`/`paths`, where
+ * `looksLikeFlag` refuses them (#1818). A field is gated to the verbs it
+ * applies to so a wrong pairing is a nax error the model can act on, rather
+ * than a git usage error it has to interpret.
+ */
+export declare const GIT_DIFF_FILTERS: readonly string[];
+/**
+ * Commit bound applied to a `log` that does not supply its own.
+ *
+ * `log` was the one read verb with no bound on how much it returns: a pathspec
+ * selects WHICH commits to show, then each selected commit prints in full. With
+ * `nameOnly` that compounds, because `--name-only` lists every file in each
+ * matching commit rather than the path that selected it -- nax#2009 measured
+ * 79KB from 7 commits on a single-file pathspec, the largest call in a
+ * 267-call session.
+ *
+ * Applied ONLY to a `log` that names no `refs`. A ref range is a scope the
+ * caller already chose, and capping on top of it discards commits they asked
+ * for with no marker. A commit cap appends nothing, so the model cannot tell
+ * 12 commits from 200-capped-to-20. The reviewer prompt asks for a story's
+ * history as `log <ref>..HEAD --oneline`
+ * (`src/prompts/sections/protocol-region.ts`), and `--max-count` keeps the
+ * NEWEST n -- a default there would have silently dropped the initial
+ * implementation commits. An unscoped `log` walks the whole history of HEAD
+ * and is the shape with no bound at all.
+ */
+export declare const DEFAULT_LOG_MAX_COUNT = 20;
+/**
+ * Compact commit rendering for `log`.
+ *
+ * `format:` rather than `tformat:` or the bare form: it places the separator
+ * BETWEEN commits, so each --name-only file list stays grouped with the commit
+ * that produced it instead of being orphaned after a blank line. Observed
+ * against a real repo, `format:%h %ad %s --name-only` renders the file list on
+ * the line directly after its commit's header; `tformat:` (which is what a bare
+ * `--format=` means) leaves a blank line between the two.
+ *
+ * `--date=short` pairs with it: `%ad` renders in whatever form `--date`
+ * selects, and the default is the raw commit timestamp
+ * (`Thu Apr 7 15:13:13 2005 -0700`) -- more noise than the compact line is
+ * meant to carry. (`%ai`/`%as` would be the ISO-8601 spellings; neither is
+ * used here.)
+ */
+export declare const DEFAULT_LOG_FORMAT = "format:%h %ad %s";
+export { GIT_ESCAPE_FLAGS } from "#src/tools/git-flags/index";
+/**
+ * `defaultExcludes`: pathspecs appended to an unscoped call (the host's own
+ * state, nax#2007); none by default.
+ */
+export declare function buildGitArgv(input: Record<string, unknown>, defaultExcludes?: readonly string[]): string[] | {
+    error: string;
+};
+export declare const gitTool: CodingTool;