@proagentstore/cli 0.4.14 → 0.4.15

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

@@ -0,0 +1,143 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+/**
+ * Read-only code inspection for the coding runtime — the "eyes" the Co-pilot/Chat use
+ * to GROUND their answers in the real repo (read a file, `git diff`, list the tree)
+ * WITHOUT driving the live CLI. All access is confined to the session's workDir.
+ *
+ * Two pure, separately-tested primitives carry the safety:
+ *   - resolveInside(): rejects any path escaping the repo root (../, absolute, sibling
+ *     prefix, symlink escape).
+ *   - gitArgv(): maps a fixed command enum to a fixed argv — no user string ever
+ *     becomes a git token except a resolveInside-validated path after a literal `--`.
+ */
+/** Resolve `rel` under `root`, refusing anything that escapes it. Pure (no fs) EXCEPT the
+ *  optional symlink check, which is what defends against a symlink inside the repo pointing
+ *  at e.g. ~/.ssh. Throws on any escape. */
+export function resolveInside(root, rel, opts = {}) {
+    const rootAbs = resolve(root);
+    const abs = resolve(rootAbs, rel);
+    // `resolve` collapses `..`, so a traversal or absolute escape lands outside rootAbs.
+    // The explicit `+ sep` blocks a sibling-prefix attack (/repo vs /repo-secrets).
+    if (abs !== rootAbs && !abs.startsWith(rootAbs + sep)) {
+        throw new InspectError(`path escapes the repo: ${rel}`);
+    }
+    if (opts.checkSymlink && existsSync(abs)) {
+        // A symlink inside the repo could still point outside it — resolve the real path and
+        // re-check the same invariant.
+        const real = realpathSync(abs);
+        const realRoot = realpathSync(rootAbs);
+        if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+            throw new InspectError(`path resolves (via symlink) outside the repo: ${rel}`);
+        }
+    }
+    return abs;
+}
+/** Map a whitelisted command enum to a fixed git argv. `path` (already validated by the
+ *  caller via resolveInside) is only ever appended after a literal `--` separator. */
+export function gitArgv(cmd, opts = {}) {
+    const clampN = Math.max(1, Math.min(200, Math.floor(opts.n ?? 20)));
+    switch (cmd) {
+        case "status":
+            return ["status", "--short"];
+        case "diff":
+            return opts.relPath ? ["diff", "--", opts.relPath] : ["diff"];
+        case "diff-stat":
+            return ["diff", "--stat"];
+        case "log":
+            return ["log", "--oneline", "-n", String(clampN)];
+        case "ls-files":
+            return ["ls-files"];
+        default:
+            throw new InspectError(`unsupported git command: ${cmd}`);
+    }
+}
+export class InspectError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "InspectError";
+    }
+}
+const DEFAULT_MAX_FILE_BYTES = 64 * 1024;
+const HARD_MAX_FILE_BYTES = 128 * 1024;
+/** Read a text file inside the repo. Rejects traversal, oversize, and binary files. */
+export function readRepoFile(workDir, relPath, maxBytes) {
+    const abs = resolveInside(workDir, relPath, { checkSymlink: true });
+    const st = statSync(abs);
+    if (!st.isFile())
+        throw new InspectError(`not a regular file: ${relPath}`);
+    const cap = Math.min(maxBytes ?? DEFAULT_MAX_FILE_BYTES, HARD_MAX_FILE_BYTES);
+    const buf = readFileSync(abs);
+    // Binary sniff: a NUL byte in the first 8KB → don't feed bytes to the model.
+    const head = buf.subarray(0, 8192);
+    if (head.includes(0))
+        return { path: relPath, size: st.size, truncated: false, binary: true };
+    const truncated = buf.length > cap;
+    return { path: relPath, size: st.size, truncated, content: buf.subarray(0, cap).toString("utf-8") };
+}
+/** Run a whitelisted read-only git command in the repo. Never uses a shell. */
+export function runRepoGit(workDir, cmd, opts = {}) {
+    if (!existsSync(resolve(workDir, ".git")))
+        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 });
+    let out = "";
+    try {
+        out = execFileSync("git", argv, { cwd: workDir, encoding: "utf-8", timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
+    }
+    catch (e) {
+        // git exits non-zero for benign cases (e.g. `diff` on nothing) — surface stdout if present.
+        const err = e;
+        out = err.stdout ?? "";
+        if (!out)
+            throw new InspectError(err.message || `git ${cmd} failed`);
+    }
+    const cap = opts.maxBytes ?? 64 * 1024;
+    const truncated = out.length > cap;
+    return { cmd, output: truncated ? out.slice(0, cap) : out, truncated };
+}
+const IGNORE_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".turbo", "coverage", ".wrangler"]);
+/** Bounded recursive file tree (names/type/size only — no contents). */
+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 entryCap = Math.max(1, Math.min(1000, maxEntries));
+    const entries = [];
+    const queue = [{ dir: start, depth: 0 }];
+    let truncated = false;
+    while (queue.length) {
+        const { dir, depth } = queue.shift();
+        let items;
+        try {
+            items = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const it of items) {
+            if (it.name.startsWith(".") || IGNORE_DIRS.has(it.name))
+                continue;
+            if (entries.length >= entryCap) {
+                truncated = true;
+                return { root: relPath, entries, truncated };
+            }
+            const abs = resolve(dir, it.name);
+            const rel = relative(workDir, abs);
+            if (it.isDirectory()) {
+                entries.push({ path: rel, type: "dir" });
+                if (depth + 1 < depthCap)
+                    queue.push({ dir: abs, depth: depth + 1 });
+            }
+            else if (it.isFile()) {
+                let size;
+                try {
+                    size = statSync(abs).size;
+                }
+                catch { }
+                entries.push({ path: rel, type: "file", size });
+            }
+        }
+    }
+    return { root: relPath, entries, truncated };
+}

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

@@ -1,6 +1,7 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { defaultStatePath, HeadlessSession } from "./headless.js";
+import { InspectError, readRepoFile, repoTree, runRepoGit } from "./inspect.js";
 import { ensureRepo, sanitizeSessionName } from "./tmux.js";
 /** Hard cap on a pane returned to the brain/console (matches the worker MAX_PANE_CHARS). */
 const MAX_PANE = 64 * 1024;
@@ -18,9 +19,39 @@ export class CodingRuntime {
     constructor(reposBaseDir = join(homedir(), ".config", "proagentstore", "repos")) {
         this.reposBaseDir = reposBaseDir;
     }
-    /** Capabilities advertised to PAGS at registration. */
+    /** Capabilities advertised to PAGS at registration. `coding.inspect` signals the
+     *  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"];
+        return ["coding.sessions", "coding.stream", "human.takeover", "coding.inspect"];
+    }
+    /**
+     * Resolve the workDir for a read-only inspection. Prefer the tracked session's real
+     * workDir (authoritative even for managed clone dirs); fall back to an explicit path
+     * (the cloud passes the D1 `repo.workdir` when the session map is empty after a runner
+     * restart). Expands a leading `~` the same way start() does.
+     */
+    resolveWorkDir(input) {
+        if (input.sessionId) {
+            const s = this.sessions.get(input.sessionId);
+            if (s)
+                return s.config.workDir;
+        }
+        if (input.workDir)
+            return resolve(input.workDir.replace(/^~(?=$|\/)/, homedir()));
+        throw new InspectError("no session or workDir to inspect");
+    }
+    /** Read one file inside the session's repo (traversal-guarded, size-capped). */
+    readFile(input) {
+        return readRepoFile(this.resolveWorkDir(input), input.path, input.maxBytes);
+    }
+    /** 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 });
+    }
+    /** 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);
     }
     static taskTypes() {
         return ["coding.session"];

package/dist/browser-runner/server.js

@@ -222,6 +222,35 @@ async function route(runner, req, res) {
         }
         return json(res, 200, { killed, sessions: targets });
     }
+    // ── Read-only code inspection (the Co-pilot/Chat's "eyes" — no CLI driving) ──
+    // Confined to the session's workDir by inspect.ts; errors surface as 400.
+    if (req.method === "POST" && path === "/coding/read-file") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.readFile(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 {
+            return json(res, 200, runner.coding.git(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    if (req.method === "POST" && path === "/coding/tree") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.tree(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
     if (req.method === "POST" && path === "/coding/event") {
         // Brain progress events — recorded by PAGS, ignored locally. Accept + ack.
         return json(res, 200, { ok: true });

package/package.json

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