@proagentstore/cli 0.4.47 → 0.4.49

package/dist/browser-runner/coding/inspect.js

@@ -44,15 +44,29 @@ export function gitArgv(cmd, opts = {}) {
             // caller can learn a tree is dirty but never which branch it is dirty on, which is how
             // a delegated run pushed a PR branch and left the checkout parked there unnoticed
             // (#276). Additive: every existing consumer keeps the same file lines it always got.
-            return ["status", "--short", "--branch"];
+            //
+            // `path` reaches this one too (#508). Narrowing every command rather than four of the
+            // five is what lets the tool description say "it applies" with no caveat — and a
+            // caveat is what a model has to reason about and can get wrong.
+            return opts.relPath ? ["status", "--short", "--branch", "--", opts.relPath] : ["status", "--short", "--branch"];
+        // `path` used to reach exactly ONE of these five (#508). It is advertised on the tool as
+        // "Limit the command to one file or folder", `runRepoGit` resolves and validates it, and
+        // then four of the five branches dropped it on the floor — so
+        // `repo_git {cmd:"ls-files", path:"admin/lib/features/events"}` answered with every tracked
+        // file in the repository, truncated mid-list at 12KB. `git ls-files -- <path>` is the
+        // file-finder a Repo Coder has been missing, and the parameter to reach it was already in
+        // the schema and already validated; it was dropped one function later.
+        //
+        // Every one of these is git's own `--` pathspec discipline, unchanged: the validated path
+        // is appended after a literal separator and can never be read as a flag or a revision.
         case "diff":
             return opts.relPath ? ["diff", "--", opts.relPath] : ["diff"];
         case "diff-stat":
-            return ["diff", "--stat"];
+            return opts.relPath ? ["diff", "--stat", "--", opts.relPath] : ["diff", "--stat"];
         case "log":
-            return ["log", "--oneline", "-n", String(clampN)];
+            return opts.relPath ? ["log", "--oneline", "-n", String(clampN), "--", opts.relPath] : ["log", "--oneline", "-n", String(clampN)];
         case "ls-files":
-            return ["ls-files"];
+            return opts.relPath ? ["ls-files", "--", opts.relPath] : ["ls-files"];
         default:
             throw new InspectError(`unsupported git command: ${cmd}`);
     }
@@ -86,6 +100,12 @@ export function runRepoGit(workDir, cmd, opts = {}) {
         throw new InspectError("not a git repo");
     const relPath = opts.path ? relative(workDir, resolveInside(workDir, opts.path)) : undefined;
     const argv = gitArgv(cmd, { relPath, n: opts.n });
+    // Did the path the caller asked for actually reach git? Reported rather than assumed, because
+    // a runner is a SEPARATE release from the cloud that calls it: before #508 four of the five
+    // commands ignored `path` silently, and the answer — the whole repository — was indistinguishable
+    // from a correct one. An older runner omits this field entirely, which is what lets the cloud
+    // say "your machine ignored the filter" instead of relaying a wrong answer as a right one.
+    const pathApplied = relPath !== undefined && argv.includes(relPath);
     let out = "";
     try {
         out = execFileSync("git", argv, { cwd: workDir, encoding: "utf-8", timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
@@ -99,7 +119,7 @@ export function runRepoGit(workDir, cmd, opts = {}) {
     }
     const cap = opts.maxBytes ?? 64 * 1024;
     const truncated = out.length > cap;
-    return { cmd, output: truncated ? out.slice(0, cap) : out, truncated };
+    return { cmd, output: truncated ? out.slice(0, cap) : out, truncated, pathApplied };
 }
 /** Read the repo's `origin` remote URL — used to auto-associate a local checkout with its
  *  GitHub repo (so build status can query Actions). Fixed argv, no shell, no user input;
@@ -120,14 +140,125 @@ export function readGitRemoteOrigin(workDir) {
     }
 }
 const IGNORE_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".turbo", "coverage", ".wrangler"]);
-/** Bounded recursive file tree (names/type/size only — no contents). */
+/**
+ * Search the repo — the capability a Repo Coder never had (#508).
+ *
+ * Before this there was no grep, no filename match, no content match anywhere in the connector or
+ * the runner, so locating a file meant walking the tree by hand and guessing when it ran out.
+ *
+ * ── The bounds, and why each one is here rather than "cap the bytes at the end"
+ *
+ * A byte cap alone just moves the problem into the tool-result cap (#503): the model receives an
+ * arbitrary prefix of a list and no statement that a list was cut. Every bound below is COUNTED,
+ * so the result can say `50 of 812` and the model knows to narrow rather than conclude.
+ *
+ *   MAX_RESULTS   the whole answer, not per file — one number the caller can reason about.
+ *   PER_FILE      git's own `--max-count`, so a minified bundle cannot spend the whole budget.
+ *   MAX_LINE      a matching line from a generated file can be tens of KB on its own.
+ *   maxBuffer     git's stdout is read into memory before any of the above can apply.
+ *
+ * Worst case is ~50 × (path + 160) ≈ 11KB, comfortably inside the 12KB the connector allows and
+ * the 24,000 chars a tool result may carry.
+ *
+ * ── Fixed strings, not regexes
+ *
+ * `-F`. The job is "where does this identifier / filename appear", which is what a model supplies
+ * naturally, and a bare `foo(` — the obvious thing to search for in code — is an invalid regex.
+ * It also means no pattern the model invents can become a pathological match on the owner's own
+ * machine. Deliberate deviation from the argv sketched in #508, which used `-e` alone.
+ *
+ * ── The safety property is unchanged
+ *
+ * `path` is still resolveInside-validated and still appended after a literal `--`. The PATTERN is
+ * never a git token in `path` mode (the filter runs here, in JS) and in `content` mode it is the
+ * fixed operand of `-e`, which git cannot read as a flag whatever it contains.
+ */
+export const SEARCH_MAX_RESULTS = 50;
+const SEARCH_PER_FILE = 5;
+const SEARCH_MAX_LINE = 160;
+const SEARCH_MAX_PATTERN = 200;
+export function repoSearch(workDir, opts) {
+    if (!existsSync(resolve(workDir, ".git")))
+        throw new InspectError("not a git repo");
+    const pattern = (opts.pattern ?? "").trim();
+    if (!pattern)
+        throw new InspectError("a search `pattern` is required");
+    if (pattern.length > SEARCH_MAX_PATTERN)
+        throw new InspectError(`search pattern is too long (max ${SEARCH_MAX_PATTERN} characters)`);
+    const mode = opts.mode === "path" ? "path" : "content";
+    const limit = Math.max(1, Math.min(SEARCH_MAX_RESULTS, Math.floor(opts.maxResults ?? SEARCH_MAX_RESULTS)));
+    const relPath = opts.path ? relative(workDir, resolveInside(workDir, opts.path)) : undefined;
+    const argv = mode === "content"
+        ? ["grep", "-n", "-I", "-i", "-F", "--untracked", "--max-count", String(SEARCH_PER_FILE), "-e", pattern]
+        : // Tracked PLUS untracked-not-ignored: a file created ten minutes ago is exactly the one
+            // somebody is trying to find, and `ls-files` alone would deny it exists.
+            ["ls-files", "--cached", "--others", "--exclude-standard"];
+    // `.` rather than nothing: `git grep` run from a subdirectory would otherwise search the whole
+    // tree, and the caller asked for a folder.
+    if (relPath && relPath !== "")
+        argv.push("--", relPath);
+    let out;
+    try {
+        out = execFileSync("git", argv, { cwd: workDir, encoding: "utf-8", timeout: 15_000, maxBuffer: 4 * 1024 * 1024 });
+    }
+    catch (e) {
+        const err = e;
+        // `git grep` exits 1 for "no matches", which is an ANSWER, not a failure.
+        if (err.status === 1)
+            out = err.stdout ?? "";
+        else if (err.code === "ENOBUFS")
+            throw new InspectError(`too many matches for "${pattern}" to read safely — search a narrower path, or a longer/more specific pattern`);
+        else if (err.stdout)
+            out = err.stdout;
+        else
+            throw new InspectError(err.message || `git ${mode} search failed`);
+    }
+    const lines = out.split("\n").filter((l) => l !== "");
+    const all = mode === "content"
+        ? lines.map(parseGrepLine).filter((m) => m !== null)
+        : // The pattern never reaches git here — the filter is a plain case-insensitive substring
+            // over the path, which is what "find the file called X" actually means.
+            lines.filter((p) => p.toLowerCase().includes(pattern.toLowerCase())).map((p) => ({ path: p }));
+    return { mode, pattern, matches: all.slice(0, limit), shown: Math.min(all.length, limit), total: all.length, truncated: all.length > limit };
+}
+/** `path:line:text` — split on the FIRST two colons only, since code is full of them. */
+function parseGrepLine(line) {
+    const first = line.indexOf(":");
+    if (first <= 0)
+        return null;
+    const second = line.indexOf(":", first + 1);
+    if (second < 0)
+        return null;
+    const n = Number.parseInt(line.slice(first + 1, second), 10);
+    if (!Number.isFinite(n))
+        return null;
+    return { path: line.slice(0, first), line: n, text: line.slice(second + 1).trim().slice(0, SEARCH_MAX_LINE) };
+}
+/** The deepest `maxDepth` this will honour. Named because the TOOL has to say it (#508). */
+export const TREE_MAX_DEPTH = 4;
+/**
+ * Bounded recursive file tree (names/type/size only — no contents).
+ *
+ * Two caps stop it, and until #508 only ONE of them was reported. `truncated` was set by the
+ * ENTRY cap alone; a directory sitting at the depth boundary was emitted as an entry and its
+ * children simply not queued, so it rendered exactly like a directory with nothing in it.
+ *
+ * From the model's side "this folder is empty" and "this folder is deeper than I am allowed to
+ * look" were the same observation, and it cannot navigate on that: asked about a file seven
+ * segments down, it saw a leaf, decided the leaf WAS the file, and called `repo_read_file` on a
+ * directory — twice in the turn that produced this ticket. `deeper` is the per-entry fact that
+ * removes the ambiguity, and it is deliberately "contents not listed" rather than "has more
+ * inside": checking the latter costs a readdir per boundary directory, and the model's next move
+ * (call again with `path`) is the same either way.
+ */
 export function repoTree(workDir, relPath = ".", maxDepth = 3, maxEntries = 500) {
     const start = resolveInside(workDir, relPath, { checkSymlink: true });
-    const depthCap = Math.max(1, Math.min(4, maxDepth));
+    const depthCap = Math.max(1, Math.min(TREE_MAX_DEPTH, maxDepth));
     const entryCap = Math.max(1, Math.min(1000, maxEntries));
     const entries = [];
     const queue = [{ dir: start, depth: 0 }];
     let truncated = false;
+    let truncatedByDepth = false;
     while (queue.length) {
         const { dir, depth } = queue.shift();
         let items;
@@ -142,14 +273,17 @@ export function repoTree(workDir, relPath = ".", maxDepth = 3, maxEntries = 500)
                 continue;
             if (entries.length >= entryCap) {
                 truncated = true;
-                return { root: relPath, entries, truncated };
+                return { root: relPath, entries, truncated, truncatedByDepth, depthCap };
             }
             const abs = resolve(dir, it.name);
             const rel = relative(workDir, abs);
             if (it.isDirectory()) {
-                entries.push({ path: rel, type: "dir" });
-                if (depth + 1 < depthCap)
+                const walk = depth + 1 < depthCap;
+                entries.push(walk ? { path: rel, type: "dir" } : { path: rel, type: "dir", deeper: true });
+                if (walk)
                     queue.push({ dir: abs, depth: depth + 1 });
+                else
+                    truncatedByDepth = true;
             }
             else if (it.isFile()) {
                 let size;
@@ -161,5 +295,5 @@ export function repoTree(workDir, relPath = ".", maxDepth = 3, maxEntries = 500)
             }
         }
     }
-    return { root: relPath, entries, truncated };
+    return { root: relPath, entries, truncated, truncatedByDepth, depthCap };
 }

package/dist/browser-runner/coding/repo-write.js

@@ -0,0 +1,128 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { InspectError } from "./inspect.js";
+/**
+ * May this string become a git token?
+ *
+ * An allowlist, not a denylist: `execFile` means there is no shell to escape, but a name beginning
+ * `-` would still be read by git as an OPTION, which is the one injection this argv shape is open
+ * to. The rest is `git check-ref-format` reduced to the subset a real branch uses.
+ */
+export function isSwitchableBranchName(name) {
+    if (typeof name !== "string")
+        return false;
+    const n = name.trim();
+    if (!n || n.length > 200)
+        return false;
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(n))
+        return false; // no leading `-` or `.`, no spaces, no `~^:?*[\`
+    if (n.includes("..") || n.includes("//") || n.endsWith("/") || n.endsWith(".lock") || n.includes("@{"))
+        return false;
+    return true;
+}
+/** Map the enum to a fixed argv. The branch is the only caller-supplied token, and it is validated. */
+export function gitWriteArgv(cmd, opts = {}) {
+    switch (cmd) {
+        case "switch-branch": {
+            if (!isSwitchableBranchName(opts.branch))
+                throw new InspectError(`unusable branch name: ${String(opts.branch)}`);
+            // `--` terminates option parsing AND says "what follows is a ref, not a path", so a branch
+            // that shares a name with a file cannot turn this into a file checkout — which WOULD
+            // discard work.
+            return ["checkout", opts.branch.trim(), "--"];
+        }
+        default:
+            throw new InspectError(`unsupported git write command: ${cmd}`);
+    }
+}
+function git(workDir, argv) {
+    // stderr is PIPED rather than inherited: git narrates a checkout on stderr, and the runner's
+    // console is a user-facing log, not a place for `Switched to branch 'main'`. Piping it is also
+    // what makes `e.stderr` available, which is the only honest sentence to put on the card when git
+    // itself refuses.
+    return execFileSync("git", argv, {
+        cwd: workDir,
+        encoding: "utf-8",
+        timeout: 15_000,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    }).toString();
+}
+/** The current branch, or the short SHA when detached, or null when even that fails. */
+function currentBranch(workDir) {
+    try {
+        const name = git(workDir, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+        if (name && name !== "HEAD")
+            return name;
+        return git(workDir, ["rev-parse", "--short", "HEAD"]).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function isDirty(workDir) {
+    // `--porcelain` alone: untracked files COUNT as dirty here, because they are exactly the ones a
+    // checkout would carry across without git saying a word about it.
+    return git(workDir, ["status", "--porcelain"]).trim().length > 0;
+}
+/**
+ * Put the checkout back on `branch`, or refuse and change nothing.
+ *
+ * Never creates a branch, never fetches, never touches the remote: the target must already exist
+ * locally, because inventing one would be deciding what should be true rather than restoring what
+ * was declared. Every refusal path returns BEFORE any write.
+ *
+ * The repo test is `.git` at THIS path, not `git rev-parse --is-inside-work-tree` — the opposite of
+ * the choice #405 made for the read side, and deliberately so. `rev-parse` answers yes from a
+ * subdirectory, so a workdir that happens to sit inside a larger checkout (`~/dev/stores` is one)
+ * would have its ENCLOSING repo switched by a policy declared on something else. A write acts only
+ * on the repo the owner actually named; the cost is a refusal on a subdirectory workdir, which is
+ * visible on the card and safe.
+ */
+export function switchRepoBranch(workDir, branch) {
+    if (!isSwitchableBranchName(branch))
+        throw new InspectError(`unusable branch name: ${String(branch)}`);
+    const to = branch.trim();
+    const base = { ok: false, changed: false, from: null, to, branch: null, dirty: false };
+    if (!existsSync(resolve(workDir, ".git")))
+        return { ...base, refused: "not-a-repo" };
+    const from = currentBranch(workDir);
+    if (!from)
+        return { ...base, refused: "unknown-head" };
+    let dirty;
+    try {
+        dirty = isDirty(workDir);
+    }
+    catch (e) {
+        return { ...base, from, branch: from, error: e.message?.slice(0, 200) };
+    }
+    // THE PRECONDITION. Uncommitted work rides along through a checkout; refusing is the only
+    // answer that cannot move somebody's diff onto a branch they did not put it on.
+    if (dirty)
+        return { ...base, from, branch: from, dirty: true, refused: "dirty" };
+    if (from === to)
+        return { ok: true, changed: false, from, to, branch: from, dirty: false };
+    try {
+        git(workDir, ["rev-parse", "--verify", "--quiet", `refs/heads/${to}`]);
+    }
+    catch {
+        return { ...base, from, branch: from, refused: "unknown-branch" };
+    }
+    try {
+        git(workDir, gitWriteArgv("switch-branch", { branch: to }));
+    }
+    catch (e) {
+        const err = e;
+        return { ...base, from, branch: currentBranch(workDir), error: (err.stderr || err.message || "git checkout failed").slice(0, 200) };
+    }
+    // CONFIRM, do not assume. The exit code says the command ran; only reading HEAD back says where
+    // the checkout actually is, and that is the only thing the cloud is allowed to report as done.
+    const after = currentBranch(workDir);
+    let dirtyAfter = false;
+    try {
+        dirtyAfter = isDirty(workDir);
+    }
+    catch { }
+    return { ok: after === to, changed: after === to, from, to, branch: after, dirty: dirtyAfter };
+}

package/dist/browser-runner/coding/runtime.js

@@ -2,7 +2,8 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { RunnerInputError } from "../errors.js";
 import { defaultStatePath, HeadlessSession } from "./headless.js";
-import { InspectError, readGitRemoteOrigin, readRepoFile, repoTree, runRepoGit } from "./inspect.js";
+import { InspectError, readGitRemoteOrigin, readRepoFile, repoSearch, repoTree, runRepoGit } from "./inspect.js";
+import { switchRepoBranch } from "./repo-write.js";
 import { checkWorkdir, ensureRepo, sanitizeSessionName } from "./repo.js";
 /** Hard cap on a pane returned to the brain/console (matches the worker MAX_PANE_CHARS). */
 const MAX_PANE = 64 * 1024;
@@ -24,7 +25,11 @@ export class CodingRuntime {
      *  read-only code-inspection endpoints exist, so the cloud offers the grounding tools
      *  (older runners omit it → the cloud degrades to terminal-only). */
     static capabilities() {
-        return ["coding.sessions", "coding.stream", "human.takeover", "coding.inspect"];
+        // `coding.repo-write` announces the ONE write verb (#322). Advertised rather than probed, so
+        // a reader of the registration can see which machines can restore a branch invariant; the
+        // cloud still never trusts it, because an older runner simply 404s and the policy reports
+        // that it asked and was not answered.
+        return ["coding.sessions", "coding.stream", "human.takeover", "coding.inspect", "coding.repo-write"];
     }
     /**
      * Resolve the workDir for a read-only inspection. Prefer the tracked session's real
@@ -50,6 +55,26 @@ export class CodingRuntime {
     git(input) {
         return runRepoGit(this.resolveWorkDir(input), input.cmd, { path: input.path, n: input.n });
     }
+    /**
+     * The ONE write the platform may make in a checkout by itself (#322) — put it back on a branch
+     * it declared, or refuse. See `repo-write.ts`: fixed argv, clean tree required, nothing in the
+     * `checkout .`/`reset`/`clean`/`stash` family exists to be reached.
+     */
+    gitWrite(input) {
+        if (input.cmd !== "switch-branch")
+            throw new InspectError(`unsupported git write command: ${String(input.cmd)}`);
+        return switchRepoBranch(this.resolveWorkDir(input), input.branch);
+    }
+    /**
+     * Find something in the repo — by file CONTENT or by file NAME (#508).
+     *
+     * The one capability the read-only inspection surface never had. Without it, locating a file
+     * meant walking `tree` by hand, and a path deeper than the tree's four-level cap was not
+     * reachable in any number of calls that did not already know the answer.
+     */
+    search(input) {
+        return repoSearch(this.resolveWorkDir(input), input);
+    }
     /** Bounded recursive file tree of the session's repo (names/type/size only). */
     tree(input) {
         return repoTree(this.resolveWorkDir(input), input.path, input.maxDepth, input.maxEntries);

package/dist/browser-runner/server.js

@@ -214,6 +214,19 @@ async function route(runner, req, res) {
             return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
         }
     }
+    // Find a file by content or by name (#508). A SEPARATE endpoint rather than another `/coding/git`
+    // command on purpose: an older runner answers an unknown path with a 404, which the cloud reads
+    // unambiguously as "this machine is too old" — an unknown `cmd` would arrive as a 400 that reads
+    // identically to a real search failure.
+    if (req.method === "POST" && path === "/coding/search") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.search(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
     if (req.method === "POST" && path === "/coding/git") {
         const b = await readJson(req);
         try {
@@ -223,6 +236,18 @@ async function route(runner, req, res) {
             return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
         }
     }
+    // The ONE write surface (#322). A standing policy may put a checkout back on the branch it
+    // declared; it may not commit, discard, or touch a remote. An older runner 404s this, which the
+    // cloud reports as "asked, not confirmed" rather than as done.
+    if (req.method === "POST" && path === "/coding/git-write") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.gitWrite(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
     if (req.method === "POST" && path === "/coding/git-remote") {
         const b = await readJson(req);
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.47",
+  "version": "0.4.49",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",