@capybara-hq/testing 0.0.0-stage → 0.1.0-rc.1

package/dist/fake-e2b.js

@@ -0,0 +1,500 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+const ROOT_DIRS = ["/workspace", "/skills", "/tmp", "/opt/capybara"];
+const PATH_RE = /(^|[\s'"=:>(])(\/workspace|\/skills|\/tmp|\/opt\/capybara)(?=\/|$|[\s'";)|&])/g;
+const RUNUSER_SHIM = `#!/bin/sh
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -u|-g) shift 2 ;;
+    --) shift; break ;;
+    -*) shift ;;
+    *) break ;;
+  esac
+done
+exec "$@"
+`;
+const SETSID_SHIM = `#!/bin/sh
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -w|-f|-c|--wait|--fork|--ctty) shift ;;
+    *) break ;;
+  esac
+done
+exec "$@"
+`;
+/**
+ * `timeout` 垫片（命令包装用 `timeout -s KILL <秒> 命令…`）：PATH 里（跳过垫片目录）有 `gtimeout` / `timeout`
+ * （GNU coreutils）就用它；没有（如未装 coreutils 的 macOS）时用 perl 的小实现：自成进程组、到点按进程组
+ * SIGKILL（与 GNU timeout 一样连自己一起），否则返回命令的退出状态。只支持 `[-s 信号] 秒 命令…`，信号一律按 KILL。
+ */
+const TIMEOUT_SHIM = `#!/bin/sh
+self=$(cd "$(dirname "$0")" && pwd)
+IFS=:
+for d in $PATH; do
+  [ "$d" = "$self" ] && continue
+  for n in gtimeout timeout; do
+    if [ -x "$d/$n" ]; then unset IFS; exec "$d/$n" "$@"; fi
+  done
+done
+unset IFS
+[ "$1" = "-s" ] && shift 2
+exec perl -e 'my $s = shift; setpgrp(0, 0); my $p = fork(); die "fork failed" unless defined $p;
+if ($p == 0) { exec { $ARGV[0] } @ARGV; exit 127 }
+$SIG{ALRM} = sub { kill "KILL", -$$ }; alarm $s; waitpid($p, 0); my $st = $?; alarm 0;
+exit(($st & 127) ? 128 + ($st & 127) : $st >> 8);' "$@"
+`;
+function envelope(flags, msg) {
+    const json = Buffer.from(JSON.stringify(msg), "utf8");
+    const head = Buffer.alloc(5);
+    head.writeUInt8(flags, 0);
+    head.writeUInt32BE(json.byteLength, 1);
+    return Buffer.concat([head, json]);
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    return Buffer.concat(chunks);
+}
+function sendJson(res, status, body, headers = {}) {
+    if (body === undefined) {
+        res.writeHead(status, headers).end();
+        return;
+    }
+    res
+        .writeHead(status, { "content-type": "application/json", ...headers })
+        .end(JSON.stringify(body));
+}
+/** 起一个假 E2B。 */
+export async function startFakeE2B(opts = {}) {
+    const apiKey = opts.apiKey ?? `e2b_${randomBytes(16).toString("hex")}`;
+    const pageSize = opts.pageSize ?? 100;
+    const base = await mkdtemp(join(tmpdir(), "fake-e2b-"));
+    const shims = join(base, "bin");
+    await mkdir(shims, { recursive: true });
+    await writeFile(join(shims, "runuser"), RUNUSER_SHIM);
+    await writeFile(join(shims, "setsid"), SETSID_SHIM);
+    await writeFile(join(shims, "timeout"), TIMEOUT_SHIM);
+    await chmod(join(shims, "timeout"), 0o755);
+    await chmod(join(shims, "runuser"), 0o755);
+    await chmod(join(shims, "setsid"), 0o755);
+    const sandboxes = new Map();
+    const procs = new Map();
+    const calls = [];
+    const fails = [];
+    const reboots = new Map();
+    let withhold = false;
+    const tokenOf = (s) => (withhold ? null : s.envdAccessToken);
+    const hangs = [];
+    const hanging = new Set();
+    const matches = (m, call) => (m.method === undefined || m.method === call.method) &&
+        m.path.test(call.path) &&
+        (m.when === undefined || m.when(call));
+    const mapPath = (root, s) => s.replace(PATH_RE, (_m, pre, dir) => `${pre}${root}${dir}`);
+    /** 直接子进程（命令包装里的 `timeout` 自成一个进程组，按进程组杀会漏掉它）。 */
+    const childrenOf = (pid) => (spawnSync("pgrep", ["-P", String(pid)], { encoding: "utf8" }).stdout ?? "")
+        .split("\n")
+        .filter((l) => l !== "")
+        .map(Number);
+    /** 杀掉一个进程（Start 启动的）的进程组、它直接子进程的进程组，以及之前记下的子进程组（本机未必有 `pkill -s`）。 */
+    const killGroup = (p) => {
+        for (const g of [...p.groups, ...childrenOf(p.pid), p.pid]) {
+            try {
+                process.kill(-g, "SIGKILL");
+            }
+            catch {
+                // 已退出
+            }
+        }
+    };
+    const destroy = async (id) => {
+        const s = sandboxes.get(id);
+        sandboxes.delete(id);
+        for (const p of procs.get(id) ?? [])
+            killGroup(p);
+        procs.delete(id);
+        if (s)
+            await rm(s.root, { recursive: true, force: true });
+    };
+    const newSandbox = async (body) => {
+        const id = `i${randomBytes(9).toString("hex")}`;
+        const root = join(base, id);
+        for (const d of ROOT_DIRS)
+            await mkdir(join(root, d), { recursive: true });
+        const s = {
+            id,
+            templateID: String(body.templateID),
+            metadata: body.metadata ?? {},
+            state: "running",
+            timeout: typeof body.timeout === "number" ? body.timeout : 300,
+            autoPause: body.autoPause === true,
+            envdAccessToken: randomBytes(12).toString("hex"),
+            root,
+            ...(typeof body.allow_internet_access === "boolean" && {
+                allowInternetAccess: body.allow_internet_access,
+            }),
+            ...(body.network !== undefined && { network: body.network }),
+        };
+        sandboxes.set(id, s);
+        return s;
+    };
+    const notFound = (res, id) => sendJson(res, 404, {
+        code: 404,
+        message: `sandbox "${id}" doesn't exist or you don't have access to it`,
+    });
+    // ---------- 控制面 API ----------
+    const handleApi = async (req, res, method, path, query, body) => {
+        if (req.headers["x-api-key"] !== apiKey) {
+            sendJson(res, 401, {
+                code: 401,
+                message: "Invalid API key, it must start with 'e2b_' prefix",
+            });
+            return;
+        }
+        if (method === "POST" && path === "/v2/sandboxes") {
+            if (typeof body.templateID !== "string" || body.templateID === "") {
+                sendJson(res, 400, { code: 400, message: "templateID is required" });
+                return;
+            }
+            const s = await newSandbox(body);
+            sendJson(res, 201, {
+                sandboxID: s.id,
+                templateID: s.templateID,
+                clientID: "fake",
+                envdVersion: "0.4.2",
+                envdAccessToken: tokenOf(s),
+                domain: opts.domain ?? null,
+            });
+            return;
+        }
+        if (method === "GET" && path === "/v2/sandboxes") {
+            const want = new URLSearchParams(query.metadata ?? "");
+            const states = (query.state ?? "running,paused").split(",");
+            const all = [...sandboxes.values()].filter((s) => {
+                if (!states.includes(s.state))
+                    return false;
+                for (const [k, v] of want) {
+                    if (s.metadata[decodeURIComponent(k)] !== decodeURIComponent(v))
+                        return false;
+                }
+                return true;
+            });
+            const limit = Math.min(pageSize, Number(query.limit ?? pageSize) || pageSize);
+            const offset = Number(query.nextToken ?? 0) || 0;
+            const page = all.slice(offset, offset + limit);
+            const next = offset + limit < all.length ? String(offset + limit) : undefined;
+            sendJson(res, 200, page.map((s) => ({
+                sandboxID: s.id,
+                templateID: s.templateID,
+                metadata: s.metadata,
+                state: s.state,
+                cpuCount: 1,
+                memoryMB: 2048,
+                envdVersion: "0.4.2",
+                startedAt: new Date().toISOString(),
+                endAt: new Date().toISOString(),
+            })), next ? { "x-next-token": next } : {});
+            return;
+        }
+        let m = /^\/v2\/sandboxes\/([^/]+)\/connect$/.exec(path);
+        if (m && method === "POST") {
+            const s = sandboxes.get(m[1]);
+            if (!s)
+                return notFound(res, m[1]);
+            const resumed = s.state === "paused";
+            s.state = "running";
+            if (body.memory === false) {
+                // 冷启动（SDK 的 onResume: "reboot"）：内存里的进程全部结束，文件保留
+                for (const p of procs.get(s.id) ?? [])
+                    killGroup(p);
+                reboots.set(s.id, (reboots.get(s.id) ?? 0) + 1);
+            }
+            if (typeof body.timeout === "number" && body.timeout > s.timeout)
+                s.timeout = body.timeout;
+            sendJson(res, resumed ? 201 : 200, {
+                sandboxID: s.id,
+                templateID: s.templateID,
+                clientID: "fake",
+                envdVersion: "0.4.2",
+                envdAccessToken: tokenOf(s),
+                domain: opts.domain ?? null,
+            });
+            return;
+        }
+        m = /^\/sandboxes\/([^/]+)\/pause$/.exec(path);
+        if (m && method === "POST") {
+            const s = sandboxes.get(m[1]);
+            if (!s)
+                return notFound(res, m[1]);
+            if (s.state === "paused") {
+                sendJson(res, 409, { code: 409, message: "sandbox is already paused" });
+                return;
+            }
+            s.state = "paused";
+            sendJson(res, 204);
+            return;
+        }
+        m = /^\/sandboxes\/([^/]+)$/.exec(path);
+        if (m && method === "DELETE") {
+            if (!sandboxes.has(m[1]))
+                return notFound(res, m[1]);
+            await destroy(m[1]);
+            sendJson(res, 204);
+            return;
+        }
+        sendJson(res, 404, { code: 404, message: `no route ${method} ${path}` });
+    };
+    // ---------- envd ----------
+    const userOf = (req) => {
+        const a = req.headers.authorization;
+        if (!a?.startsWith("Basic "))
+            return undefined;
+        return Buffer.from(a.slice(6), "base64").toString("utf8").replace(/:.*$/, "");
+    };
+    const startProcess = (s, msg, res) => {
+        const p = msg.process ?? {};
+        const args = (p.args ?? []).map((a) => mapPath(s.root, a));
+        const env = {
+            ...process.env,
+            PATH: `${shims}:${process.env.PATH ?? "/usr/bin:/bin"}`,
+        };
+        for (const [k, v] of Object.entries(p.envs ?? {}))
+            env[k] = mapPath(s.root, v);
+        const cwd = p.cwd ? mapPath(s.root, p.cwd) : join(s.root, "workspace");
+        res.writeHead(200, { "content-type": "application/connect+json" });
+        let child;
+        try {
+            child = spawn(p.cmd ?? "/bin/sh", args, { cwd, env, detached: true, stdio: "pipe" });
+        }
+        catch (e) {
+            res.end(envelope(2, { error: { code: "internal", message: String(e) } }));
+            return;
+        }
+        child.on("error", (e) => {
+            if (!res.writableEnded)
+                res.end(envelope(2, { error: { code: "internal", message: e.message } }));
+        });
+        const pid = child.pid;
+        if (pid === undefined)
+            return;
+        const proc = { pid, args: [p.cmd ?? "", ...args], child, groups: new Set() };
+        const list = procs.get(s.id) ?? [];
+        list.push(proc);
+        procs.set(s.id, list);
+        child.stdin?.end();
+        const write = (msg) => {
+            if (!res.writableEnded && !res.destroyed)
+                res.write(envelope(0, msg));
+        };
+        write({ event: { start: { pid } } });
+        child.stdout?.on("data", (d) => write({ event: { data: { stdout: d.toString("base64") } } }));
+        child.stderr?.on("data", (d) => write({ event: { data: { stderr: d.toString("base64") } } }));
+        child.on("close", (code, signal) => {
+            const l = procs.get(s.id);
+            if (l)
+                procs.set(s.id, l.filter((x) => x !== proc));
+            const end = signal
+                ? { exitCode: -1, status: `signal: ${signal === "SIGKILL" ? "killed" : signal}` }
+                : { exited: true, status: `exit status ${code}` };
+            if (!signal && code !== 0)
+                end.exitCode = code;
+            write({ event: { end } });
+            if (!res.writableEnded && !res.destroyed)
+                res.end(envelope(2, {}));
+        });
+    };
+    const handleEnvd = async (req, res, id, path, query, raw, call) => {
+        const s = sandboxes.get(id);
+        if (s?.state !== "running") {
+            sendJson(res, 502, {
+                sandboxId: id,
+                message: s ? "The sandbox is paused" : "The sandbox was not found",
+                code: 502,
+            });
+            return;
+        }
+        if (req.headers["x-access-token"] !== s.envdAccessToken) {
+            sendJson(res, 401, { code: 401, message: "invalid access token" });
+            return;
+        }
+        if (path === "/files" && req.method === "POST") {
+            call.user = query.username;
+            const target = query.path;
+            if (!target?.startsWith("/")) {
+                sendJson(res, 400, { code: 400, message: "path is required" });
+                return;
+            }
+            const form = await new Response(raw, {
+                headers: { "content-type": String(req.headers["content-type"] ?? "") },
+            }).formData();
+            const file = form.get("file");
+            if (!(file instanceof Blob)) {
+                sendJson(res, 400, { code: 400, message: "missing file part" });
+                return;
+            }
+            const host = mapPath(s.root, target);
+            if (host === target) {
+                sendJson(res, 400, { code: 400, message: "path outside the fake sandbox roots" });
+                return;
+            }
+            await mkdir(dirname(host), { recursive: true });
+            await writeFile(host, Buffer.from(await file.arrayBuffer()));
+            sendJson(res, 200, [{ path: target, name: target.split("/").pop(), type: "file" }]);
+            return;
+        }
+        if (path === "/process.Process/Start" && req.method === "POST") {
+            call.user = userOf(req);
+            if (!call.user) {
+                sendJson(res, 401, { code: "unauthenticated", message: "missing user" });
+                return;
+            }
+            if (raw.byteLength < 5) {
+                sendJson(res, 400, { code: "invalid_argument", message: "missing envelope" });
+                return;
+            }
+            const msg = JSON.parse(raw.subarray(5, 5 + raw.readUInt32BE(1)).toString("utf8"));
+            call.body = msg;
+            startProcess(s, msg, res);
+            return;
+        }
+        if (path === "/process.Process/SendSignal" && req.method === "POST") {
+            const msg = JSON.parse(raw.toString("utf8") || "{}");
+            call.body = msg;
+            const pid = msg.process?.pid;
+            const p = (procs.get(s.id) ?? []).find((x) => x.pid === pid);
+            if (!p) {
+                sendJson(res, 404, { code: "not_found", message: `process with pid ${pid} not found` });
+                return;
+            }
+            // 与 envd 一样只给这个进程发信号（不是整个进程组）。先记下它的子进程组：它死后子进程被收养、
+            // 再也按父子关系找不到，删沙箱 / 冷启动时（真 E2B 结束沙箱里的一切）靠这份记录杀掉它们
+            for (const g of childrenOf(p.pid))
+                p.groups.add(g);
+            try {
+                process.kill(p.pid, "SIGKILL");
+            }
+            catch {
+                // 已退出
+            }
+            sendJson(res, 200, {});
+            return;
+        }
+        sendJson(res, 404, { code: "not_found", message: `no route ${req.method} ${path}` });
+    };
+    const server = createServer((req, res) => {
+        void (async () => {
+            const u = new URL(req.url ?? "/", "http://fake");
+            const method = req.method ?? "GET";
+            const query = Object.fromEntries(u.searchParams);
+            const raw = await readBody(req);
+            const sandboxId = req.headers["e2b-sandbox-id"];
+            const isEnvd = typeof sandboxId === "string";
+            let body = null;
+            const ct = String(req.headers["content-type"] ?? "");
+            if (ct.startsWith("application/json") && raw.byteLength > 0) {
+                try {
+                    body = JSON.parse(raw.toString("utf8"));
+                }
+                catch {
+                    body = null;
+                }
+            }
+            const call = {
+                method,
+                path: u.pathname,
+                query,
+                body,
+                ...(isEnvd && { sandboxId }),
+            };
+            if (u.pathname === "/process.Process/Start" && raw.byteLength >= 5) {
+                try {
+                    call.body = JSON.parse(raw.subarray(5, 5 + raw.readUInt32BE(1)).toString("utf8"));
+                }
+                catch {
+                    call.body = null;
+                }
+            }
+            calls.push(call);
+            const fi = fails.findIndex((f) => matches(f.match, call));
+            if (fi >= 0) {
+                const [f] = fails.splice(fi, 1);
+                if (f?.raw)
+                    res.writeHead(f.status, { "content-type": "text/plain" }).end(f.message);
+                else if (f)
+                    sendJson(res, f.status, { code: f.status, message: f.message });
+                return;
+            }
+            const hi = hangs.findIndex((h) => matches(h, call));
+            if (hi >= 0) {
+                hangs.splice(hi, 1);
+                hanging.add(res);
+                res.on("close", () => hanging.delete(res));
+                return;
+            }
+            if (isEnvd) {
+                await handleEnvd(req, res, sandboxId, u.pathname, query, raw, call);
+            }
+            else {
+                await handleApi(req, res, method, u.pathname, query, (body ?? {}));
+            }
+        })().catch((e) => {
+            if (!res.headersSent)
+                sendJson(res, 500, { code: 500, message: String(e) });
+            else
+                res.destroy();
+        });
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const url = `http://127.0.0.1:${server.address().port}`;
+    return {
+        url,
+        apiKey,
+        sandboxes,
+        calls,
+        failNext(match, status, message = `fake failure ${status}`, opts = {}) {
+            fails.push({ match, status, message, raw: opts.raw === true });
+        },
+        reboots,
+        get withholdAccessToken() {
+            return withhold;
+        },
+        set withholdAccessToken(v) {
+            withhold = v;
+        },
+        hangNext(match) {
+            hangs.push(match);
+        },
+        expire: destroy,
+        hostPath(id, sandboxPath) {
+            const s = sandboxes.get(id);
+            if (!s)
+                throw new Error(`no fake sandbox ${id}`);
+            return mapPath(s.root, sandboxPath);
+        },
+        running(id) {
+            return (procs.get(id) ?? []).map((p) => ({ pid: p.pid, args: p.args }));
+        },
+        alive(pid) {
+            try {
+                process.kill(-pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async close() {
+            for (const id of [...sandboxes.keys()])
+                await destroy(id);
+            for (const r of hanging)
+                r.destroy();
+            server.closeAllConnections();
+            await new Promise((r) => server.close(() => r()));
+            await rm(base, { recursive: true, force: true });
+        },
+    };
+}

package/dist/fake-git-server.d.ts

@@ -0,0 +1,57 @@
+/** One request the fake git server received. */
+export interface FakeGitRequest {
+    method: string;
+    /** Path and query, e.g. `/x.git/info/refs?service=git-upload-pack`. */
+    path: string;
+    /** The `Authorization` header. */
+    authorization?: string;
+}
+/** Entries that are not regular files, for tests of refused trees. */
+export interface FakeGitCommitOptions {
+    /** Default `main` (the bare repo's HEAD). */
+    branch?: string;
+    /** Symlink entries (mode 120000): path -> link target. */
+    symlinks?: Record<string, string>;
+    /** Submodule entries (gitlinks, mode 160000): path -> commit sha (need not exist). */
+    submodules?: Record<string, string>;
+    /**
+     * A tree-only DAG at the top-level directory `name`: T0 is the empty tree and each level holds
+     * `fanout` entries all pointing at the level below, `depth` levels deep (few objects, fanout^depth
+     * paths).
+     */
+    treeDag?: {
+        name: string;
+        fanout: number;
+        depth: number;
+    };
+    /** Also tags the commit (`annotated` creates a tag object; default lightweight). */
+    tag?: {
+        name: string;
+        annotated?: boolean;
+    };
+}
+export interface FakeGitServer {
+    /** `http://127.0.0.1:<port>/<repo>.git`. */
+    url(repo: string): string;
+    /**
+     * Commits exactly `files` (path -> UTF-8 content; the whole tree, not a diff) on `branch`, whose
+     * previous head (if any) is the parent; creates the repo on first use. Returns the commit sha.
+     */
+    commit(repo: string, files: Record<string, string>, opts?: FakeGitCommitOptions): Promise<string>;
+    /** Makes every request answer 302 to `location` (`null` restores it). */
+    setRedirect(location: string | null): void;
+    /** The requests received, in order. */
+    requests: FakeGitRequest[];
+    stop(): Promise<void>;
+}
+/**
+ * A fake git host: bare repos in a temp dir, served read-only by the system `git http-backend`
+ * (smart HTTP, as CGI) over a loopback http server. Repos allow fetching any reachable commit by sha
+ * (`uploadpack.allowReachableSHA1InWant`, as GitHub does). Needs `git` on PATH.
+ *
+ * Spawning git is what these tests spend their time on, and it slows down most under load, so the
+ * server spawns as little as it can while every answer still comes from git: a commit is one
+ * `git fast-import`, and a ref advertisement (`GET …/info/refs`) is answered by http-backend once per
+ * repo state, then repeated until the next commit to that repo.
+ */
+export declare function startFakeGitServer(): Promise<FakeGitServer>;