@proagentstore/cli 0.4.57 → 0.4.59

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

@@ -1,7 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { InspectError } from "./inspect.js";
+import { InspectError, networkGitEnv } from "./inspect.js";
 /**
  * May this string become a git token?
  *
@@ -32,11 +32,18 @@ export function gitWriteArgv(cmd, opts = {}) {
             // discard work.
             return ["checkout", opts.branch.trim(), "--"];
         }
+        case "fast-forward":
+            // No caller-supplied token at all: the branch is whatever HEAD is (checked against the
+            // declared one BEFORE this runs), the remote is the upstream git records for it. `--ff-only`
+            // is the whole contract — git aborts, touching nothing, when the histories have diverged.
+            // `--no-rebase` so a `pull.rebase=true` config on the owner's machine cannot turn the
+            // abort into a rebase of their local commits.
+            return ["pull", "--ff-only", "--no-rebase"];
         default:
             throw new InspectError(`unsupported git write command: ${cmd}`);
     }
 }
-function git(workDir, argv) {
+function git(workDir, argv, opts = {}) {
     // 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
@@ -44,11 +51,22 @@ function git(workDir, argv) {
     return execFileSync("git", argv, {
         cwd: workDir,
         encoding: "utf-8",
-        timeout: 15_000,
+        timeout: opts.timeout ?? 15_000,
         maxBuffer: 1024 * 1024,
         stdio: ["ignore", "pipe", "pipe"],
+        env: opts.env,
     }).toString();
 }
+/** git's diagnosis is the FIRST `fatal:`/`error:` line of stderr; the tail is boilerplate. */
+function gitFailureLine(e) {
+    const err = e;
+    const lines = String(err.stderr || err.message || "")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const line = lines.find((l) => /^(fatal|error):/i.test(l)) ?? lines[0] ?? "git failed";
+    return line.replace(/^(fatal|error):\s*/i, "").slice(0, 200);
+}
 /** The current branch, or the short SHA when detached, or null when even that fails. */
 function currentBranch(workDir) {
     try {
@@ -134,3 +152,109 @@ export function switchRepoBranch(workDir, branch) {
     }
     return { ok: after === to, changed: after === to, from, to, branch: after, dirty: dirtyAfter };
 }
+/**
+ * Bring a CLEAN checkout up to its upstream, or refuse and change nothing (#802).
+ *
+ * Every precondition is checked HERE, at the hands, not only in the cloud — the same rule
+ * `switchRepoBranch` follows and for the same reason: the cloud's picture of the tree is a read
+ * taken moments earlier over a relay, and the write has to be safe against the tree as it IS.
+ *
+ *   dirty        refused. A fast-forward that touches a file with uncommitted edits is aborted by
+ *                git anyway, but one that does not touch it silently succeeds and leaves the diff
+ *                sitting on a base it was not written against. Refusing is the only answer that
+ *                cannot change what somebody's uncommitted work means.
+ *   off-branch   refused when `branch` is given and HEAD is elsewhere. The declared branch is the
+ *                one the cloud judged stale; pulling whatever the checkout happens to be on would
+ *                be acting on a verdict about a different ref.
+ *   detached     refused — there is no branch for a pull to advance.
+ *   no-upstream  refused — `git pull` with no tracking information is a prompt, and a guess about
+ *                which remote was meant is exactly the decision this module must never make.
+ *   diverged     NOT a precondition: `--ff-only` is the check, and git makes it atomically against
+ *                the real history. It surfaces as `error`, with the tree untouched.
+ *
+ * Never creates a branch, never sets an upstream, never stashes.
+ */
+export function fastForwardRepo(workDir, opts = {}) {
+    const want = typeof opts.branch === "string" && opts.branch.trim() ? opts.branch.trim() : null;
+    if (want !== null && !isSwitchableBranchName(want))
+        throw new InspectError(`unusable branch name: ${String(opts.branch)}`);
+    const base = { ok: false, changed: false, branch: null, upstream: null, from: null, to: null, commits: null, dirty: false };
+    if (!existsSync(resolve(workDir, ".git")))
+        return { ...base, refused: "not-a-repo" };
+    let abbrev;
+    try {
+        abbrev = git(workDir, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    }
+    catch {
+        return { ...base, refused: "unknown-head" };
+    }
+    if (!abbrev)
+        return { ...base, refused: "unknown-head" };
+    if (abbrev === "HEAD")
+        return { ...base, refused: "detached" };
+    const branch = abbrev;
+    let dirty;
+    try {
+        dirty = isDirty(workDir);
+    }
+    catch (e) {
+        return { ...base, branch, error: gitFailureLine(e) };
+    }
+    if (dirty)
+        return { ...base, branch, dirty: true, refused: "dirty" };
+    if (want !== null && branch !== want)
+        return { ...base, branch, refused: "off-branch" };
+    let upstream;
+    try {
+        upstream = git(workDir, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]).trim();
+    }
+    catch {
+        return { ...base, branch, refused: "no-upstream" };
+    }
+    if (!upstream)
+        return { ...base, branch, refused: "no-upstream" };
+    let from;
+    try {
+        from = git(workDir, ["rev-parse", "HEAD"]).trim() || null;
+    }
+    catch {
+        from = null;
+    }
+    try {
+        // The one network call in this file: the no-prompt environment `inspect.ts` uses for
+        // fetches, and a timeout above the runner's fetch cap, because a pull IS a fetch first.
+        git(workDir, gitWriteArgv("fast-forward"), { timeout: 30_000, env: networkGitEnv() });
+    }
+    catch (e) {
+        // `--ff-only` refused, the network failed, or auth was needed and (correctly) not prompted
+        // for. In every case git left the tree as it was; the sentence says which.
+        return { ...base, branch, upstream, from, to: from, error: gitFailureLine(e) };
+    }
+    // CONFIRM, do not assume — read HEAD back and count what arrived from git, not from the
+    // exit code.
+    let to;
+    try {
+        to = git(workDir, ["rev-parse", "HEAD"]).trim() || null;
+    }
+    catch {
+        to = null;
+    }
+    let commits = null;
+    if (from && to) {
+        try {
+            const n = Number.parseInt(git(workDir, ["rev-list", "--count", `${from}..${to}`]).trim(), 10);
+            commits = Number.isFinite(n) ? n : null;
+        }
+        catch {
+            commits = null;
+        }
+    }
+    let dirtyAfter;
+    try {
+        dirtyAfter = isDirty(workDir);
+    }
+    catch {
+        dirtyAfter = null;
+    }
+    return { ok: to !== null, changed: Boolean(from && to && from !== to), branch, upstream, from, to, commits, dirty: dirtyAfter };
+}

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

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 /**
@@ -72,6 +72,49 @@ export function authenticatedCloneUrl(cloneUrl, token, username) {
     const user = encodeURIComponent(username || "x-access-token");
     return cloneUrl.replace(/^https:\/\//i, `https://${user}:${encodeURIComponent(token)}@`);
 }
+/**
+ * Parse a GitHub SSH welcome banner into an identity name.
+ *
+ * GitHub writes to stderr on a successful `ssh -T git@github.com`:
+ *   `Hi <name>! You've successfully authenticated, but GitHub does not provide shell access.`
+ *
+ * For a deploy key the name is `<org>/<repo>`. For a user account it is the login.
+ * This function is PURE so it can be unit-tested without a network.
+ */
+export function parseSshIdentity(raw) {
+    // The banner arrives on stderr; strip ANSI color/style sequences (`ESC[...m`) that some SSH
+    // versions prepend. The ESC byte is expressed via String.fromCharCode rather than as a literal
+    // in a regex pattern, because Biome's noControlCharactersInRegex rule rejects control characters
+    // in regex literals (same rule that transcript-lines.ts and tmux.ts suppress with biome-ignore).
+    const ESC = String.fromCharCode(27);
+    const clean = raw.split(ESC).join("").replace(/\[[0-9;]*m/g, "").trim();
+    const m = clean.match(/^Hi\s+([^!]+)!/m);
+    return m ? m[1].trim() : null;
+}
+/**
+ * Ask the machine what git identity SSH presents for `host`.
+ *
+ * Uses `BatchMode=yes` so it never prompts for a passphrase, and `ConnectTimeout=5` so a
+ * firewall that drops packets (rather than refusing) does not stall the diagnostics response.
+ * `StrictHostKeyChecking=accept-new` avoids an interactive prompt on first connection.
+ *
+ * Never throws — every failure is an identity of `null`, because this is a transparency probe
+ * and a network hiccup must not make the diagnostics endpoint useless.
+ */
+export function probeGitSshIdentity(host) {
+    // `ssh -T` exits non-zero (1) even on success — GitHub's welcome message deliberately closes
+    // the connection without a shell. `spawnSync` is used rather than `execFileSync` so a non-zero
+    // exit does not throw; the content of stderr is what matters, not the exit code.
+    const result = spawnSync("ssh", ["-T", "-o", "BatchMode=yes", "-o", "StrictHostKeyChecking=accept-new", "-o", "ConnectTimeout=5", `git@${host}`], {
+        encoding: "utf-8",
+        timeout: 10_000,
+    });
+    // stderr carries the welcome message; stdout is empty for a normal `ssh -T`.
+    const raw = String(result.stderr ?? "").slice(0, 500);
+    const identity = parseSshIdentity(raw);
+    const isDeployKey = identity === null ? null : identity.includes("/");
+    return { checked: true, host, identity, isDeployKey, raw };
+}
 /**
  * Ensure a repo is present at `dir`, cloning it from `cloneUrl` if not. Idempotent
  * — an existing checkout is left alone (no clobber). For private repos the cloud

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

@@ -2,8 +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, repoSearch, repoTree, runRepoGit } from "./inspect.js";
-import { switchRepoBranch } from "./repo-write.js";
+import { InspectError, readGitRemoteOrigin, readRepoFile, repoSearch, repoSync, repoTree, runRepoGit } from "./inspect.js";
+import { fastForwardRepo, switchRepoBranch } from "./repo-write.js";
 import { checkWorkdir, ensureRepo, sanitizeSessionName } from "./repo.js";
 import { asTurnAuthor } from "./turn-author.js";
 /** Hard cap on a pane returned to the brain/console (matches the worker MAX_PANE_CHARS). */
@@ -54,17 +54,33 @@ export class CodingRuntime {
     }
     /** Run a whitelisted read-only git command in the session's repo. */
     git(input) {
-        return runRepoGit(this.resolveWorkDir(input), input.cmd, { path: input.path, n: input.n });
+        return runRepoGit(this.resolveWorkDir(input), input.cmd, { path: input.path, n: input.n, ref: input.ref });
     }
     /**
-     * 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.
+     * Where the checkout stands against its upstream — fetch (cached), then count ahead/behind
+     * (#785). Never pulls. The one endpoint here that reaches the NETWORK, which is why it carries
+     * its own cache and its own no-prompt environment (`inspect.ts`).
+     */
+    sync(input) {
+        return repoSync(this.resolveWorkDir(input), { branch: input.branch, forceFetch: input.forceFetch });
+    }
+    /**
+     * The writes the platform may make in a checkout by itself — put it back on a branch it
+     * declared (#322), or fast-forward it to its upstream (#802) — 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);
+        const workDir = this.resolveWorkDir(input);
+        if (input.cmd === "switch-branch") {
+            if (typeof input.branch !== "string")
+                throw new InspectError("switch-branch needs a branch");
+            return switchRepoBranch(workDir, input.branch);
+        }
+        // The second verb (#802): bring a clean checkout that is ON `branch` up to its upstream.
+        if (input.cmd === "fast-forward")
+            return fastForwardRepo(workDir, { branch: input.branch });
+        throw new InspectError(`unsupported git write command: ${String(input.cmd)}`);
     }
     /**
      * Find something in the repo — by file CONTENT or by file NAME (#508).
@@ -158,6 +174,8 @@ export class CodingRuntime {
             // exactly the question asked about a session that just stopped.
             authResolved: session.authResolved,
             engineRuntime: session.engineRuntime,
+            engineMode: session.engineMode,
+            engineModeWarning: session.engineModeWarning,
             // Reported on EVERY capture, including one where the session is not alive: "how did the
             // last turn end" is exactly the question asked about a session that just stopped, and
             // the omitted-when-null shape keeps "not measured" distinguishable from a verdict.
@@ -252,6 +270,8 @@ export class CodingRuntime {
             takeover: this.takeovers.has(sessionId),
             authResolved: s.authResolved,
             engineRuntime: s.engineRuntime,
+            engineMode: s.engineMode,
+            engineModeWarning: s.engineModeWarning,
             ghGuard: s.ghGuard,
         }));
     }

package/dist/browser-runner/server.js

@@ -1,6 +1,8 @@
 import { createServer, } from "node:http";
 import { URL } from "node:url";
 import { LocalRunner, RunnerInputError } from "./runner.js";
+import { probeGitSshIdentity } from "./coding/repo.js";
+import { listGithubOrgs, listGithubRepos, searchGithubRepos, getGithubRepoDetail, getGithubCredentialScope } from "./coding/github-browse.js";
 export function createRunnerServer(runner) {
     return createServer(async (req, res) => {
         try {
@@ -176,6 +178,95 @@ async function route(runner, req, res) {
         // use tmux, have their own /tmux/* endpoints and are unaffected.
         return json(res, 200, { tracked: runner.coding.diagnostics() });
     }
+    if ((req.method === "GET" || req.method === "POST") && path === "/coding/git-identity") {
+        // Report the SSH identity this machine presents to github.com (#684). Called by
+        // `coding_diagnostics` to surface deploy-key vs user-account mismatches without a
+        // failed clone. Never throws on the runner side — a network hiccup returns identity:null.
+        const b = req.method === "POST" ? await readJson(req).catch(() => ({})) : {};
+        const host = String(b.host || "github.com");
+        return json(res, 200, probeGitSshIdentity(host));
+    }
+    // ── GitHub credential scope (#688) ────────────────────────────────────────
+    // Read-only: reports the authenticated gh login + org memberships. Surfaces
+    // which account and organisations the runner's credentials can reach, before
+    // any browse operation begins. Never writes, never mutates anything on GitHub.
+    if ((req.method === "GET" || req.method === "POST") && path === "/coding/github-credentials") {
+        return json(res, 200, getGithubCredentialScope());
+    }
+    // ── GitHub org + repo enumeration (#685) ──────────────────────────────────
+    // Read-only: lists orgs and repos reachable by the machine's `gh` credentials.
+    // Never writes, never mutates anything on GitHub.
+    if ((req.method === "GET" || req.method === "POST") && path === "/coding/github-orgs") {
+        return json(res, 200, listGithubOrgs());
+    }
+    if ((req.method === "GET" || req.method === "POST") && path === "/coding/github-repos") {
+        const b = req.method === "POST"
+            ? await readJson(req).catch(() => ({}))
+            : {};
+        // Query params override body for GET callers (more REST-idiomatic).
+        const qOwner = url.searchParams.get("owner");
+        const qLimit = url.searchParams.get("limit");
+        const qSince = url.searchParams.get("since");
+        const qVis = url.searchParams.get("visibility");
+        const input = {
+            owner: qOwner ?? b.owner,
+            limit: qLimit ? Number(qLimit) : b.limit,
+            since: qSince ?? b.since,
+            visibility: (qVis === "public" || qVis === "private" || qVis === "all")
+                ? qVis
+                : b.visibility,
+        };
+        return json(res, 200, listGithubRepos(input));
+    }
+    // ── GitHub repository search (#686) ───────────────────────────────────────
+    // Read-only: searches repos reachable by the machine's `gh` credentials via
+    // GitHub's own search API. One API call per query (no per-repo fan-out).
+    // Results are cached in-process for 5 minutes to guard the 30 req/min quota.
+    if ((req.method === "GET" || req.method === "POST") && path === "/coding/github-search") {
+        const b = req.method === "POST"
+            ? await readJson(req).catch(() => ({}))
+            : {};
+        const qQuery = url.searchParams.get("query");
+        const qOwner = url.searchParams.get("owner");
+        const qLang = url.searchParams.get("language");
+        const qTopic = url.searchParams.get("topic");
+        const qPushedAfter = url.searchParams.get("pushedAfter");
+        const qOpenPrs = url.searchParams.get("openPrs");
+        const qLimit = url.searchParams.get("limit");
+        const qSort = url.searchParams.get("sort");
+        const bTyped = b;
+        const input = {
+            query: qQuery ?? bTyped.query,
+            owner: qOwner ?? bTyped.owner,
+            language: qLang ?? bTyped.language,
+            topic: qTopic ?? bTyped.topic,
+            pushedAfter: qPushedAfter ?? bTyped.pushedAfter,
+            openPrs: qOpenPrs !== null ? qOpenPrs === "true" : bTyped.openPrs,
+            limit: qLimit ? Number(qLimit) : bTyped.limit,
+            sort: (qSort === "stars" || qSort === "forks" || qSort === "updated")
+                ? qSort
+                : bTyped.sort,
+        };
+        return json(res, 200, searchGithubRepos(input));
+    }
+    // ── GitHub repository detail (#687) ──────────────────────────────────────
+    // Read-only: fetches issues, PRs, and branches for a given owner/repo slug
+    // via `gh api`. Results are cached in-process for 2 minutes.
+    if ((req.method === "GET" || req.method === "POST") && path === "/coding/github-repo-detail") {
+        const b = req.method === "POST"
+            ? await readJson(req).catch(() => ({}))
+            : {};
+        const bTyped = b;
+        const qRepo = url.searchParams.get("repo");
+        const qLimit = url.searchParams.get("limit");
+        const qState = url.searchParams.get("state");
+        const input = {
+            repo: qRepo ?? bTyped.repo ?? "",
+            limit: qLimit ? Number(qLimit) : bTyped.limit,
+            state: (qState === "all" || qState === "open") ? qState : bTyped.state,
+        };
+        return json(res, 200, getGithubRepoDetail(input));
+    }
     if (req.method === "POST" && path === "/coding/browse") {
         const { readdirSync, statSync } = await import("node:fs");
         const { resolve } = await import("node:path");
@@ -240,9 +331,23 @@ 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.
+    // Where the checkout stands against its upstream (#785): fetch (cached a minute), then count
+    // ahead/behind. Never pulls. A SEPARATE endpoint for the reason `/coding/search` is one: an
+    // older runner 404s it, which the cloud reads as "unverified" — never as "in sync".
+    if (req.method === "POST" && path === "/coding/sync") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.sync(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    // The ONE write surface (#322, #802). A standing policy may put a checkout back on the branch
+    // it declared, and a run may fast-forward a clean checkout to its upstream before it starts; it
+    // may not commit, discard, or push. An older runner 404s the endpoint (and a 0.4.58 runner
+    // 400s the `fast-forward` verb), 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 {

package/package.json

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