@zgeoff/atc 3.2.0 → 3.3.0

package/src/test-utils/setup-mcp-http.ts

@@ -0,0 +1,126 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { DaemonClient } from '../client/daemon-client';
+import { startDaemon } from '../daemon/daemon';
+import type { DaemonHandle } from '../daemon/daemon';
+import { openMCPAuth } from '../mcp/open-mcp-auth';
+import { ReconnectingCaller } from '../mcp/reconnecting-caller';
+import { startMCPHTTPServer } from '../mcp/start-mcp-http-server';
+import { setupTempDir } from './setup-temp-dir';
+
+const SLEEP_ADAPTER: AgentAdapter = {
+  id: 'claude',
+  headlessRunner: null,
+  screenDetector: null,
+  takesMessages: false,
+  planSpawn: () => ({ bin: 'sleep', args: ['30'] }),
+  normalizeHook: () => ({ kind: 'heartbeat' }),
+  loadName: () => Promise.resolve(null),
+  canResume: () => true,
+  buildResumeCommand: () => null,
+};
+
+interface MCPHTTPSetupOptions {
+  // How long a rotated refresh token still answers with its successor.
+  readonly refreshReuseSeconds?: number;
+
+  // Further Host header values the server accepts.
+  readonly allowedHosts?: readonly string[];
+}
+
+/**
+ * A real daemon in a temp directory and `atc mcp --http` in front of it on a
+ * free port, with every approval line and request line the server prints
+ * collected. The authorization server's database sits where atc keeps it
+ * under `home`, so a CLI run with that home opens the same file. `store` is
+ * the authorization server's database opened a second time the way
+ * `atc clients` and `atc grants` open it, and `addClient` adds a client
+ * through it and returns the client id. `restartDaemon` stops the daemon and
+ * starts a fresh one on the same socket and database, the way an operator
+ * restarts it, with the principals it is given; `countDaemonClients` reads how many connections the current
+ * daemon holds open. Hold the result with `await using`.
+ */
+export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
+  const tmp = setupTempDir('atc-mcp-http-');
+  const socketPath = join(tmp.dir, 'daemon.sock');
+  const stateDir = join(tmp.dir, '.local', 'state', 'atc');
+
+  mkdirSync(stateDir, { recursive: true });
+
+  const dbPath = join(stateDir, 'mcp-auth.db');
+  const approvals: string[] = [];
+  const requests: string[] = [];
+
+  const startTestDaemon = (principals: ReadonlyMap<string, readonly string[]> | null = null) =>
+    startDaemon({
+      socketPath,
+      reporterSocketPath: join(tmp.dir, 'reporter.sock'),
+      build: 'atc/test-build',
+      adapter: SLEEP_ADAPTER,
+      dbPath: join(tmp.dir, 'state.db'),
+      statusPath: join(tmp.dir, 'status.json'),
+      principals,
+    });
+
+  let daemon: DaemonHandle = await startTestDaemon();
+
+  const caller = new ReconnectingCaller(socketPath, 'atc/test-build', (path) =>
+    DaemonClient.open(path),
+  );
+
+  const server = await startMCPHTTPServer({
+    caller,
+    build: 'atc/test-build',
+    host: '127.0.0.1',
+    port: 0,
+    publicURL: null,
+    allowedHosts: options.allowedHosts ?? [],
+    dbPath,
+    printApproval: (line) => {
+      approvals.push(line);
+    },
+    printRequest: (line) => {
+      requests.push(line);
+    },
+    ...(options.refreshReuseSeconds === undefined
+      ? {}
+      : { refreshReuseSeconds: options.refreshReuseSeconds }),
+  });
+
+  const store = await openMCPAuth({ dbPath, origin: null });
+
+  return {
+    home: tmp.dir,
+    url: server.url,
+    origin: server.origin,
+    dbPath,
+    approvals,
+    requests,
+    caller,
+    store,
+    async addClient(name: string, redirectURIs: readonly string[]): Promise<string> {
+      const created = await store.auth.api.createFixedClient({
+        body: { name, redirectURIs: [...redirectURIs] },
+      });
+
+      return created.clientID;
+    },
+    countDaemonClients() {
+      return daemon.countClients();
+    },
+    async restartDaemon(principals: ReadonlyMap<string, readonly string[]> | null = null) {
+      await daemon.stop();
+
+      daemon = await startTestDaemon(principals);
+    },
+    async [Symbol.asyncDispose]() {
+      await server.stop();
+      await store.close();
+      await caller.stop();
+      await daemon.stop();
+
+      tmp[Symbol.dispose]();
+    },
+  };
+}

package/src/test-utils/setup-temp-dir.ts

@@ -0,0 +1,33 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface TempDir {
+  readonly dir: string;
+  readonly [Symbol.dispose]: () => void;
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+/**
+ * Creates a disposable directory under the system temp root, named by the
+ * prefix. Disposal removes the tree; hold the result with `using` in a
+ * synchronous test and `await using` in an asynchronous one, so the
+ * directory outlives exactly the test that made it.
+ */
+export function setupTempDir(prefix: string): TempDir {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+
+  const remove = () => {
+    rmSync(dir, { recursive: true, force: true });
+  };
+
+  return {
+    dir,
+    [Symbol.dispose]: remove,
+    [Symbol.asyncDispose]: () => {
+      remove();
+
+      return Promise.resolve();
+    },
+  };
+}

package/src/test-utils/spawn-named-session.ts

@@ -0,0 +1,27 @@
+import { isRecord } from '../shared/report';
+
+type SendRequest = (
+  m: string,
+  p?: Readonly<Record<string, unknown>>,
+) => Promise<Readonly<Record<string, unknown>>>;
+
+/**
+ * Sends one session.spawn request at 80x24 through the given request sender
+ * and returns the new session's id. Throws when the answer carries no
+ * session descriptor with a string id.
+ */
+export async function spawnNamedSession(
+  send: SendRequest,
+  name: string,
+  cwd: string,
+): Promise<string> {
+  const ok = await send('session.spawn', { cwd, name, cols: 80, rows: 24 });
+
+  const spawned = ok['session'];
+
+  if (!isRecord(spawned) || typeof spawned['id'] !== 'string') {
+    throw new Error('no session in spawn answer');
+  }
+
+  return spawned['id'];
+}

package/src/test-utils/start-cut-proxy.ts

@@ -0,0 +1,175 @@
+import type { Socket } from 'bun';
+
+interface CutProxyOptions {
+  // The address the proxy forwards to.
+  readonly target: { readonly hostname: string; readonly port: number };
+
+  // The request method whose response the proxy loses, and how many times.
+  readonly method: string;
+  readonly cuts: number;
+
+  // `close` ends both sides where the response would pass; `hold`
+  // swallows it and every later byte from the target, leaving the
+  // connection open; `drop` ends both sides in place of forwarding the
+  // request, so the target never sees it.
+  readonly mode: 'close' | 'hold' | 'drop';
+}
+
+export interface CutProxy {
+  readonly port: number;
+
+  // How many requests of the method the proxy has seen.
+  readonly countRequests: () => number;
+  readonly stop: () => void;
+}
+
+// One proxied connection: the target side once it is connected, what the
+// client sent before it was, the client's unfinished line, and whether
+// the target's next answer is lost or every answer from now on is.
+interface ProxyLink {
+  upstream: Socket | null;
+  readonly pending: Uint8Array[];
+  readonly decoder: TextDecoder;
+  lineBuffer: string;
+  cutting: boolean;
+  held: boolean;
+}
+
+/**
+ * A TCP proxy on a loopback port that forwards an NDJSON protocol
+ * connection byte for byte, except that for the first `cuts` requests of
+ * the method it loses the target's next answer after the request reached
+ * the target: the request runs, and the client never sees its response.
+ */
+export function startCutProxy(options: CutProxyOptions): CutProxy {
+  let cutsLeft = options.cuts;
+  let requests = 0;
+
+  const links = new Set<Socket<ProxyLink>>();
+
+  const server = Bun.listen<ProxyLink>({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: {
+      open(client) {
+        client.data = {
+          upstream: null,
+          pending: [],
+          decoder: new TextDecoder(),
+          lineBuffer: '',
+          cutting: false,
+          held: false,
+        };
+
+        links.add(client);
+        void openUpstream(client, options);
+      },
+      data(client, buf) {
+        client.data.lineBuffer += client.data.decoder.decode(buf, { stream: true });
+
+        const lines = client.data.lineBuffer.split('\n');
+
+        client.data.lineBuffer = lines.pop() ?? '';
+
+        let dropped = false;
+
+        for (const line of lines) {
+          if (!line.includes(`"m":"${options.method}"`)) {
+            continue;
+          }
+
+          requests++;
+
+          if (cutsLeft > 0) {
+            cutsLeft--;
+            client.data.cutting = options.mode !== 'drop';
+            dropped = options.mode === 'drop';
+          }
+        }
+
+        // A dropped request ends the link with nothing of its chunk
+        // forwarded.
+        if (dropped) {
+          client.end();
+          client.data.upstream?.end();
+
+          return;
+        }
+
+        if (client.data.upstream === null) {
+          client.data.pending.push(new Uint8Array(buf));
+        } else {
+          client.data.upstream.write(buf);
+        }
+      },
+      close(client) {
+        links.delete(client);
+        client.data.upstream?.end();
+      },
+      error() {},
+    },
+  });
+
+  return {
+    port: server.port,
+    countRequests: () => requests,
+    stop() {
+      for (const client of links) {
+        client.end();
+        client.data.upstream?.end();
+      }
+
+      server.stop(true);
+    },
+  };
+}
+
+// Connects the client's link to the target, forwarding what the client
+// sent meanwhile, and ends the client when the target cannot be reached.
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a socket is a live handle the proxy writes to
+async function openUpstream(client: Socket<ProxyLink>, options: CutProxyOptions): Promise<void> {
+  try {
+    const upstream = await Bun.connect({
+      hostname: options.target.hostname,
+      port: options.target.port,
+      socket: {
+        data(_upstream, buf) {
+          if (client.data.held) {
+            return;
+          }
+
+          if (!client.data.cutting) {
+            client.write(buf);
+
+            return;
+          }
+
+          client.data.cutting = false;
+
+          if (options.mode === 'hold') {
+            client.data.held = true;
+
+            return;
+          }
+
+          client.end();
+          client.data.upstream?.end();
+        },
+        close() {
+          if (!client.data.held) {
+            client.end();
+          }
+        },
+        error() {},
+      },
+    });
+
+    client.data.upstream = upstream;
+
+    for (const chunk of client.data.pending.splice(0)) {
+      upstream.write(chunk);
+    }
+  } catch {
+    client.end();
+  }
+}

package/src/test-utils/start-git-http-server.ts

@@ -0,0 +1,102 @@
+interface GitHTTPServer {
+  // The base URL a repository under the root is served at, ending in `/`.
+  readonly url: string;
+
+  // Every Authorization header a request carried, in arrival order.
+  readonly authorizations: string[];
+  readonly stop: () => Promise<void>;
+}
+
+/**
+ * Serves the bare repositories under a directory over smart HTTP through
+ * `git http-backend` on a loopback port, and refuses every request that
+ * carries no basic auth, so a client only clones by authenticating. The
+ * backend runs with the environment it is given. With a delay, each
+ * authenticated request waits that long before it is served, which makes a
+ * clone through it slow.
+ */
+export function startGitHTTPServer(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  options: { readonly delayMs?: number } = {},
+): GitHTTPServer {
+  const authorizations: string[] = [];
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    async fetch(request) {
+      const authorization = request.headers.get('authorization');
+
+      if (authorization === null) {
+        return new Response('auth required', {
+          status: 401,
+          headers: { 'www-authenticate': 'Basic realm="atc"' },
+        });
+      }
+
+      authorizations.push(authorization);
+
+      if (options.delayMs !== undefined) {
+        await Bun.sleep(options.delayMs);
+      }
+
+      const url = new URL(request.url);
+
+      const body = await request.arrayBuffer();
+
+      const backend = Bun.spawn(['git', 'http-backend'], {
+        env: {
+          ...env,
+          GIT_PROJECT_ROOT: root,
+          GIT_HTTP_EXPORT_ALL: '1',
+          REQUEST_METHOD: request.method,
+          PATH_INFO: url.pathname,
+          QUERY_STRING: url.search.slice(1),
+          CONTENT_TYPE: request.headers.get('content-type') ?? '',
+          HTTP_CONTENT_ENCODING: request.headers.get('content-encoding') ?? '',
+          HTTP_GIT_PROTOCOL: request.headers.get('git-protocol') ?? '',
+          REMOTE_USER: 'atc',
+          REMOTE_ADDR: '127.0.0.1',
+        },
+        stdin: new Uint8Array(body),
+        stdout: 'pipe',
+        stderr: 'ignore',
+      });
+
+      const raw = await new Response(backend.stdout).arrayBuffer();
+
+      return toCGIResponse(Buffer.from(raw));
+    },
+  });
+
+  return {
+    url: `http://127.0.0.1:${server.port}/`,
+    authorizations,
+    stop: () => server.stop(true),
+  };
+}
+
+// A CGI answer is a header block, a blank line, and the body; a `Status`
+// header sets the response status.
+function toCGIResponse(output: Buffer): Response {
+  const split = output.indexOf('\r\n\r\n');
+
+  const headers = new Headers();
+
+  let status = 200;
+
+  for (const line of output.subarray(0, split).toString('latin1').split('\r\n')) {
+    const colon = line.indexOf(':');
+    const name = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim();
+
+    if (name.toLowerCase() === 'status') {
+      status = Number(value.split(' ')[0]);
+    } else {
+      headers.append(name, value);
+    }
+  }
+
+  return new Response(output.subarray(split + 4), { status, headers });
+}

package/src/test-utils/start-legacy-daemon.ts

@@ -0,0 +1,111 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+import {
+  MAX_CHUNK,
+  MAX_LINE,
+  PROTOCOL_V,
+  decodeMessage,
+  encodeMessage,
+} from '../protocol/protocol';
+
+interface ReceivedRequest {
+  readonly m: string;
+  readonly p: Readonly<Record<string, unknown>> | undefined;
+}
+
+interface LegacyDaemonOptions {
+  readonly features?: readonly DaemonFeature[];
+
+  // The protocol version the daemon speaks; a hello on any other version is
+  // refused with `protocol_mismatch`, as a real daemon refuses it.
+  readonly protocol?: number;
+
+  readonly replies?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
+
+/**
+ * An older atc daemon listening on a unix socket and speaking the current
+ * protocol version, or the one `protocol` holds. Its `daemon.hello` announces `features` when the options
+ * hold that list, and announces none without it, as a daemon from before
+ * features did. It answers `daemon.hello`, `daemon.ping`, and each method in
+ * `replies` with that method's reply, and refuses every other method with
+ * `unknown_method`. Every request it receives is recorded in `requests`. Stop
+ * it with `stop`.
+ */
+export function startLegacyDaemon(socketPath: string, options: LegacyDaemonOptions = {}) {
+  const answers: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {
+    'daemon.hello': {
+      daemon: 'atc/legacy-build',
+      limits: { maxLine: MAX_LINE, maxChunk: MAX_CHUNK },
+      lastUsedAgent: 'claude',
+      ...(options.features === undefined ? {} : { features: options.features }),
+    },
+    'daemon.ping': {},
+    ...options.replies,
+  };
+
+  const protocol = options.protocol ?? PROTOCOL_V;
+  const requests: ReceivedRequest[] = [];
+
+  const server = Bun.listen<{ buffer: string }>({
+    unix: socketPath,
+    socket: {
+      open(socket) {
+        socket.data = { buffer: '' };
+      },
+      data(socket, chunk) {
+        const lines = `${socket.data.buffer}${chunk.toString()}`.split('\n');
+
+        socket.data.buffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const decoded = decodeMessage(line);
+
+          if (decoded.kind !== 'request') {
+            continue;
+          }
+
+          const req = decoded.msg;
+
+          requests.push({ m: req.m, p: req.p });
+
+          if (req.m === 'daemon.hello' && req.v !== protocol) {
+            const client = req.p?.['client'];
+
+            socket.write(
+              encodeMessage({
+                v: protocol,
+                id: req.id,
+                err: {
+                  code: 'protocol_mismatch',
+                  msg: `${String(client)} speaks protocol v${req.v}, daemon atc/legacy-build speaks v${protocol}; restart the daemon so both run the same build`,
+                },
+              }),
+            );
+
+            continue;
+          }
+
+          const answer = answers[req.m];
+
+          const reply =
+            answer === undefined
+              ? {
+                  v: protocol,
+                  id: req.id,
+                  err: { code: 'unknown_method' as const, msg: `unknown method '${req.m}'` },
+                }
+              : { v: protocol, id: req.id, ok: answer };
+
+          socket.write(encodeMessage(reply));
+        }
+      },
+    },
+  });
+
+  return {
+    requests,
+    stop() {
+      server.stop(true);
+    },
+  };
+}

package/src/test-utils/subscribe-to-socket-lines.ts

@@ -0,0 +1,60 @@
+import { waitFor } from './wait-for';
+
+interface SocketLines {
+  readonly lines: string[];
+  readonly write: (data: string) => void;
+  readonly waitForLine: (count?: number, timeoutMs?: number) => Promise<string[]>;
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+/**
+ * Connects to a unix socket and collects every complete newline-terminated
+ * line it sends, buffering a partial line across reads. `waitForLine` polls
+ * until the collected count reaches `count` and returns the lines, throwing
+ * when `timeoutMs` passes first; disposal ends the connection.
+ */
+export async function subscribeToSocketLines(path: string): Promise<SocketLines> {
+  const lines: string[] = [];
+  let buffer = '';
+
+  const socket = await Bun.connect({
+    unix: path,
+    socket: {
+      data(_s, buf) {
+        buffer += buf.toString();
+
+        const parts = buffer.split('\n');
+
+        buffer = parts.pop() ?? '';
+
+        lines.push(...parts.filter((part) => part.trim() !== ''));
+      },
+      close() {},
+      error() {},
+    },
+  });
+
+  return {
+    lines,
+    write(data: string) {
+      socket.write(data);
+    },
+    waitForLine(count = 1, timeoutMs = 5000) {
+      return waitFor(
+        () => {
+          if (lines.length < count) {
+            throw new Error(`timed out waiting for ${count} lines; got ${JSON.stringify(lines)}`);
+          }
+
+          return lines;
+        },
+        { timeoutMs },
+      );
+    },
+    [Symbol.asyncDispose]: () => {
+      socket.end();
+
+      return Promise.resolve();
+    },
+  };
+}

package/src/test-utils/update-env.ts

@@ -0,0 +1,19 @@
+import { envOriginals } from './env-originals';
+
+/**
+ * Overrides an environment variable for the rest of the running test, or
+ * unsets it when the value is `undefined`. The value it held before the
+ * test's first override of it is recorded once, and the preload puts it back
+ * after the test.
+ */
+export function updateEnv(key: string, value: string | undefined): void {
+  if (!envOriginals.has(key)) {
+    envOriginals.set(key, process.env[key]);
+  }
+
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+}

package/src/test-utils/wait-for.ts

@@ -0,0 +1,38 @@
+interface WaitForOptions {
+  /**
+   * Milliseconds between retries.
+   */
+  readonly intervalMs?: number;
+
+  /**
+   * Milliseconds before the wait gives up.
+   */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Retries the attempt until it stops throwing or rejecting, resolving with
+ * its value — so assertion-style checks read exactly as they would in a
+ * straight-line test body. Once the deadline passes, the attempt's final
+ * failure is rethrown as the wait's rejection.
+ */
+export async function waitFor<T>(
+  attempt: () => Promise<T> | T,
+  options: Readonly<WaitForOptions> = {},
+): Promise<T> {
+  const intervalMs = options.intervalMs ?? 20;
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (Date.now() >= deadline) {
+        throw error;
+      }
+    }
+
+    await Bun.sleep(intervalMs);
+  }
+}