@zgeoff/atc 3.3.1 → 3.4.1

package/src/test-utils/start-mcp-stdio.ts

@@ -0,0 +1,190 @@
+import { join } from 'node:path';
+import { isRecord } from '../shared/report';
+import { registerTestCleanup } from './register-test-cleanup';
+
+const CLI_PATH = join(import.meta.dir, '..', 'cli.ts');
+
+interface MCPStdioOptions {
+  // The home the server runs with, as its `HOME` and `XDG_RUNTIME_DIR`.
+  readonly home: string;
+
+  // The session id the server sees itself running inside; absent means a
+  // server started outside any session.
+  readonly callerSessionID?: string;
+
+  // A command that stands in for `atc mcp`; absent means this checkout's
+  // `atc mcp`.
+  readonly command?: readonly string[];
+}
+
+/**
+ * One tool call's result as the server returned it: `isError` as sent,
+ * `structured` as its `structuredContent`, and the text of its only content
+ * item.
+ */
+interface MCPToolResult {
+  readonly isError: unknown;
+  readonly text: string;
+  readonly structured: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * `atc mcp` from this checkout, run as a subprocess over stdio, with an
+ * `initialize` already answered, so the daemon the server boots or joins is
+ * up. `sendRequest` sends one JSON-RPC request under the next id and
+ * resolves with its whole response. `sendToolCall` sends `tools/call` and
+ * resolves with the result, rejecting when the response holds no result, the
+ * result holds anything but one text item, or its structured content is not
+ * an object. `spawnSession` spawns through `atc_session_spawn` and resolves
+ * with the new session's id. A request still unanswered when the server's
+ * stdout ends rejects. When `initialize` fails, the server is stopped
+ * before the start rejects. The server stops once the current test
+ * finishes, so it must run inside a test; disposal stops it sooner and waits
+ * for it to exit, and a second disposal waits for the same exit. The daemon
+ * stays up for the home to stop.
+ */
+export async function startMCPStdio(options: MCPStdioOptions) {
+  const proc = Bun.spawn([...(options.command ?? [process.execPath, CLI_PATH, 'mcp'])], {
+    env: {
+      ...process.env,
+      HOME: options.home,
+      XDG_RUNTIME_DIR: options.home,
+      PATH: '/usr/sbin:/usr/bin:/bin',
+      ATC_SESSION_ID: options.callerSessionID ?? '',
+      ATC_TAP_GRACE_MS: '0',
+    },
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+
+  const stopServer = registerTestCleanup(async (): Promise<void> => {
+    void proc.stdin.end();
+    proc.kill();
+
+    await proc.exited;
+  });
+
+  const pending = new Map<number, PromiseWithResolvers<Readonly<Record<string, unknown>>>>();
+
+  void readResponses(proc.stdout, pending);
+  let nextID = 0;
+
+  const sendRequest = (
+    method: string,
+    params?: Readonly<Record<string, unknown>>,
+  ): Promise<Readonly<Record<string, unknown>>> => {
+    nextID += 1;
+
+    const id = nextID;
+    const response = Promise.withResolvers<Readonly<Record<string, unknown>>>();
+
+    pending.set(id, response);
+
+    void proc.stdin.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) })}\n`,
+    );
+
+    void proc.stdin.flush();
+
+    return response.promise;
+  };
+
+  const sendToolCall = async (
+    name: string,
+    args: Readonly<Record<string, unknown>>,
+  ): Promise<MCPToolResult> => {
+    const response = await sendRequest('tools/call', { name, arguments: args });
+
+    return toToolResult(response);
+  };
+
+  const server = {
+    sendRequest,
+    sendToolCall,
+    async spawnSession(args: Readonly<Record<string, unknown>>): Promise<string> {
+      const spawned = await sendToolCall('atc_session_spawn', args);
+
+      const id = spawned.structured?.['id'];
+
+      if (typeof id !== 'string') {
+        throw new TypeError(`spawn returned no session id: ${spawned.text}`);
+      }
+
+      return id;
+    },
+    [Symbol.asyncDispose]: stopServer,
+  };
+
+  // A failed initialize stops the server here, before the start rejects.
+  await sendRequest('initialize', {
+    protocolVersion: '2025-06-18',
+    capabilities: {},
+    clientInfo: { name: 'atc-test' },
+  }).catch(async (error: unknown) => {
+    await stopServer();
+
+    throw error;
+  });
+
+  return server;
+}
+
+/**
+ * Reads the server's stdout as JSON-RPC lines and resolves the pending
+ * request each response's id matches. Once stdout ends, or holds a line that
+ * is not JSON, every request not yet resolved rejects.
+ */
+async function readResponses(
+  stdout: Readonly<ReadableStream<Uint8Array>>,
+  pending: ReadonlyMap<number, PromiseWithResolvers<Readonly<Record<string, unknown>>>>,
+): Promise<void> {
+  const decoder = new TextDecoder('utf-8');
+
+  let buffer = '';
+
+  try {
+    for await (const chunk of stdout) {
+      buffer += decoder.decode(chunk, { stream: true });
+
+      const lines = buffer.split('\n');
+
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines.filter((candidate) => candidate.trim() !== '')) {
+        const parsed: unknown = JSON.parse(line);
+        const id = isRecord(parsed) ? parsed['id'] : undefined;
+        const waiting = typeof id === 'number' ? pending.get(id) : undefined;
+
+        if (isRecord(parsed) && waiting !== undefined) {
+          waiting.resolve(parsed);
+        }
+      }
+    }
+  } catch {
+    // A line that is not JSON ends the reading; the requests still pending
+    // reject below.
+  } finally {
+    for (const [id, waiting] of pending) {
+      waiting.reject(new Error(`atc mcp stopped answering before request ${id}`));
+    }
+  }
+}
+
+function toToolResult(response: Readonly<Record<string, unknown>>): MCPToolResult {
+  const result = response['result'];
+  const content = isRecord(result) ? result['content'] : undefined;
+  const item: unknown = Array.isArray(content) && content.length === 1 ? content[0] : undefined;
+  const structured = isRecord(result) ? result['structuredContent'] : undefined;
+
+  if (
+    !isRecord(result) ||
+    !isRecord(item) ||
+    typeof item['text'] !== 'string' ||
+    (structured !== undefined && !isRecord(structured))
+  ) {
+    throw new TypeError(`tool call returned an unexpected result: ${JSON.stringify(response)}`);
+  }
+
+  return { isError: result['isError'], text: item['text'], structured };
+}

package/src/test-utils/start-output-capture.ts

@@ -0,0 +1,20 @@
+/**
+ * Reads the stream in the background and keeps every chunk it has read, as
+ * text, in arrival order, until the stream ends. `read` returns all the text
+ * read so far, so a test can wait on output from a process that never
+ * exits.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- reading a stream locks and drains it
+export function startOutputCapture(stream: ReadableStream<Uint8Array>) {
+  let text = '';
+
+  const decoder = new TextDecoder();
+
+  void (async () => {
+    for await (const chunk of stream) {
+      text += decoder.decode(chunk, { stream: true });
+    }
+  })();
+
+  return { read: () => text };
+}

package/src/test-utils/start-stub-answering-listener.ts

@@ -0,0 +1,65 @@
+import { createServer } from 'node:net';
+import type { Socket } from 'node:net';
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubAnsweringListener {
+  // The server's side of each connection it accepted, in order.
+  readonly peers: readonly Socket[];
+
+  // The first read each connection sent, decoded, in arrival order.
+  readonly lines: readonly string[];
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+/**
+ * A stand-in for a daemon socket that answers a handshake: it listens on
+ * the unix socket path, records each connection it accepts and the first
+ * read each one sends, answers that read with the line `answer`, and
+ * leaves every later byte unread on the connection. Resolves once it
+ * listens. Once the current test finishes, it destroys every connection it
+ * accepted and closes, so it must run inside a test; disposal does so
+ * sooner and resolves once the server has closed, and a second stop does
+ * nothing.
+ */
+export async function startStubAnsweringListener(path: string): Promise<StubAnsweringListener> {
+  const peers: Socket[] = [];
+  const lines: string[] = [];
+
+  const server = createServer((peer) => {
+    peers.push(peer);
+
+    peer.once('data', (data) => {
+      peer.pause();
+      lines.push(data.toString());
+      peer.write('answer\n');
+    });
+  });
+
+  const listening = Promise.withResolvers<void>();
+
+  server.listen(path, () => {
+    listening.resolve();
+  });
+
+  await listening.promise;
+
+  const stop = registerTestCleanup(async () => {
+    for (const peer of peers) {
+      peer.destroy();
+    }
+
+    const closed = Promise.withResolvers<void>();
+
+    server.close(() => {
+      closed.resolve();
+    });
+
+    await closed.promise;
+  });
+
+  return {
+    peers,
+    lines,
+    [Symbol.asyncDispose]: stop,
+  };
+}

package/src/test-utils/start-stub-closing-listener.ts

@@ -0,0 +1,31 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubClosingListener {
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a daemon that hangs up: it listens on the unix socket path
+ * and ends every connection as soon as it opens, reading nothing. It stops
+ * once the current test finishes, so it must run inside a test; disposal
+ * stops it sooner, and a second stop does nothing.
+ */
+export function startStubClosingListener(path: string): StubClosingListener {
+  const server = Bun.listen({
+    unix: path,
+    socket: {
+      open(socket) {
+        socket.end();
+      },
+      data() {},
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    [Symbol.dispose]: stop,
+  };
+}

package/src/test-utils/start-stub-dropping-daemon.ts

@@ -0,0 +1,105 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+import {
+  MAX_CHUNK,
+  MAX_LINE,
+  PROTOCOL_V,
+  decodeMessage,
+  encodeMessage,
+} from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface DroppingDaemonOptions {
+  // The features the first handshake announces.
+  readonly features: readonly DaemonFeature[];
+
+  // The features every later handshake announces, as a daemon restarted on
+  // another build would; the first handshake's features when absent.
+  readonly retryFeatures?: readonly DaemonFeature[];
+}
+
+/**
+ * A daemon on a unix socket whose connection drops mid-request: it answers
+ * each handshake as a daemon does, announcing the features the options give, ends the connection
+ * that carries the first request of any other method without answering it,
+ * and answers every later one with a session `s-1`. `keys` records the
+ * idempotency key each of those requests carried, `undefined` for one that
+ * carried none. `reads` counts the reads it has taken from every connection,
+ * so a test can wait until one piece of a split write has arrived. It stops
+ * once the current test finishes, so it must run inside a test; `stop` or
+ * disposal stops it sooner, and a second stop does nothing.
+ */
+export function startStubDroppingDaemon(socketPath: string, options: DroppingDaemonOptions) {
+  const keys: unknown[] = [];
+  let hellos = 0;
+  let reads = 0;
+
+  const server = Bun.listen<{ buffer: string }>({
+    unix: socketPath,
+    socket: {
+      open(socket) {
+        socket.data = { buffer: '' };
+      },
+      data(socket, buf) {
+        reads += 1;
+
+        const lines = `${socket.data.buffer}${buf.toString()}`.split('\n');
+
+        socket.data.buffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const decoded = decodeMessage(line);
+
+          if (decoded.kind !== 'request') {
+            continue;
+          }
+
+          if (decoded.msg.m === 'daemon.hello') {
+            hellos += 1;
+
+            const announced =
+              hellos === 1 ? options.features : (options.retryFeatures ?? options.features);
+
+            socket.write(
+              encodeMessage({
+                v: PROTOCOL_V,
+                id: decoded.msg.id,
+                ok: {
+                  daemon: 'atc/dropping-build',
+                  limits: { maxLine: MAX_LINE, maxChunk: MAX_CHUNK },
+                  lastUsedAgent: 'claude',
+                  features: announced,
+                },
+              }),
+            );
+
+            continue;
+          }
+
+          keys.push(decoded.msg.p?.['idempotencyKey']);
+
+          if (keys.length === 1) {
+            socket.end();
+            continue;
+          }
+
+          socket.write(
+            encodeMessage({ v: PROTOCOL_V, id: decoded.msg.id, ok: { session: { id: 's-1' } } }),
+          );
+        }
+      },
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    keys,
+    get reads() {
+      return reads;
+    },
+    stop,
+    [Symbol.dispose]: stop,
+  };
+}

package/src/test-utils/start-stub-impd-info.ts

@@ -0,0 +1,38 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+/**
+ * An impd stand-in on a real HTTP port of the loopback address. Every call
+ * is answered with HTTP 200 and the body impd's RPC sends for system info,
+ * `{ json: info }`, so a client reads `info.features` as impd's features;
+ * the test sets `info.features` to what impd should report. `paths` holds
+ * the request path of each call, in order. The server stops once the
+ * current test finishes, so it must run inside a test; disposal stops it
+ * sooner, the asynchronous form resolving once it has stopped, and a second
+ * stop does nothing.
+ */
+export function startStubImpdInfo() {
+  const paths: string[] = [];
+  const info: { features: unknown } = { features: undefined };
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    fetch: (request) => {
+      paths.push(new URL(request.url).pathname);
+
+      return Response.json({ json: info });
+    },
+  });
+
+  const stop = registerTestCleanup(() => server.stop(true));
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}`,
+    paths,
+    info,
+    [Symbol.dispose]: () => {
+      void stop();
+    },
+    [Symbol.asyncDispose]: stop,
+  };
+}

package/src/test-utils/start-stub-impd.ts

@@ -0,0 +1,143 @@
+import type { ServerWebSocket } from 'bun';
+import { isRecord } from '../shared/report';
+import { registerTestCleanup } from './register-test-cleanup';
+
+// What the stand-in does with an exec open: refuse it as a start whose
+// broker is not ready, start it and count its stdin bytes as `wc -c` does,
+// or start it and exit 2 at once without reading stdin.
+type StubExecReply = 'refuse' | 'count' | 'exit-early';
+
+/**
+ * Starts an impd stand-in on a real HTTP port. It records the authorization
+ * header of each call and WebSocket upgrade, and the path and input of each
+ * RPC call. It answers a call with the answer the caller set for its path in
+ * `answers`, or else as system info, and answers a tunnel listen as
+ * listening, keeping that control socket in `controls` so a caller can
+ * announce a guest connection on it. It records each exec open message in
+ * `execOpens` and answers it as `exec.reply` says, a refusal as a start
+ * whose broker is not ready by default. It takes no WebSocket message over
+ * 2 MiB, as impd refuses one over its own limit. The server stops, dropping
+ * every open connection at once, when the current test finishes, so it must
+ * run inside a test; disposal stops it sooner, and a second stop does
+ * nothing.
+ */
+export function startStubImpd() {
+  const authorizations: (string | null)[] = [];
+  const calls: { path: string; input: unknown }[] = [];
+
+  const answers = new Map<string, { status: number; json: unknown }>();
+
+  const controls: ServerWebSocket[] = [];
+  const execOpens: unknown[] = [];
+  const exec: { reply: StubExecReply } = { reply: 'refuse' };
+
+  const counted = new WeakMap<ServerWebSocket, number>();
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    fetch: async (request, bunServer) => {
+      authorizations.push(request.headers.get('authorization'));
+
+      const path = new URL(request.url).pathname;
+
+      const isUpgraded = (path === '/tunnel' || path === '/exec') && bunServer.upgrade(request);
+      const text = isUpgraded ? '' : await request.text();
+      const body: unknown = text === '' ? null : JSON.parse(text);
+
+      if (!isUpgraded) {
+        calls.push({ path, input: isRecord(body) ? body['json'] : undefined });
+      }
+
+      const answer = answers.get(path) ?? {
+        status: 200,
+        json: { features: { sessionOffsets: true, leases: true } },
+      };
+
+      return isUpgraded
+        ? undefined
+        : Response.json({ json: answer.json }, { status: answer.status });
+    },
+    websocket: {
+      maxPayloadLength: 2 * 1024 * 1024,
+      message: (socket, message) => {
+        const seen = counted.get(socket);
+
+        if (typeof message !== 'string') {
+          if (seen !== undefined) {
+            counted.set(socket, seen + message.byteLength - 1);
+          }
+
+          return;
+        }
+
+        const parsed: unknown = JSON.parse(message);
+
+        if (!isRecord(parsed)) {
+          return;
+        }
+
+        if (parsed['type'] === 'stdin_eof' && seen !== undefined) {
+          const count = new TextEncoder().encode(`${String(seen)}\n`);
+
+          socket.send(new Uint8Array([1, ...count]));
+          socket.send(JSON.stringify({ type: 'exit', code: 0, signal: null }));
+
+          return;
+        }
+
+        if (parsed['type'] === 'start' || parsed['type'] === 'attach') {
+          execOpens.push(parsed);
+
+          if (exec.reply === 'refuse') {
+            socket.send(
+              JSON.stringify({
+                type: 'error',
+                code: 'PRECONDITION_FAILED',
+                message: 'the broker is not ready',
+                data: { reason: 'broker_not_ready', detail: 'the broker CA did not install' },
+              }),
+            );
+
+            return;
+          }
+
+          socket.send(JSON.stringify({ type: 'started', pid: 7 }));
+
+          if (exec.reply === 'count') {
+            counted.set(socket, 0);
+
+            return;
+          }
+
+          socket.send(JSON.stringify({ type: 'exit', code: 2, signal: null }));
+
+          return;
+        }
+
+        if (parsed['type'] === 'listen') {
+          controls.push(socket);
+
+          socket.send(
+            JSON.stringify({ type: 'listening', listener: 'l1', path: '/tmp/r.sock', port: null }),
+          );
+        }
+      },
+    },
+  });
+
+  const stop = registerTestCleanup(() => server.stop(true));
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}`,
+    authorizations,
+    calls,
+    answers,
+    controls,
+    execOpens,
+    exec,
+    [Symbol.dispose]: () => {
+      void stop();
+    },
+  };
+}