@proagentstore/cli 0.4.47 → 0.4.48

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

@@ -3,6 +3,7 @@ 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 { 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,16 @@ 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);
+    }
     /** 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

@@ -223,6 +223,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.48",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",