@zgeoff/atc 3.3.1 → 3.4.1

package/src/test-utils/get-only-imp-name.ts

@@ -0,0 +1,19 @@
+import type { createStubImpPort } from './create-stub-imp-port';
+
+/**
+ * Returns the name of the one imp a stub imp port holds, and throws when
+ * it holds none or several, so a test that expects one spawn's imp never
+ * reads another's.
+ */
+export function getOnlyImpName(
+  port: Readonly<Pick<ReturnType<typeof createStubImpPort>, 'collectImpNames'>>,
+): string {
+  const names = port.collectImpNames();
+  const [name] = names;
+
+  if (names.length !== 1 || name === undefined) {
+    throw new Error(`expected one imp, found ${JSON.stringify(names)}`);
+  }
+
+  return name;
+}

package/src/test-utils/get-records.ts

@@ -0,0 +1,20 @@
+import { isRecord } from '../shared/report';
+
+/**
+ * Narrows one field of a record to an array of records, for tests reading a
+ * list out of a loosely typed protocol reply, such as the sessions of
+ * `session.list`. Throws when the field is not an array or holds anything
+ * but records, so a malformed reply fails the test instead of passing it.
+ */
+export function getRecords(
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+): Record<string, unknown>[] {
+  const inner = value[key];
+
+  if (!Array.isArray(inner) || !inner.every((item) => isRecord(item))) {
+    throw new TypeError(`${key} is not an array of records`);
+  }
+
+  return inner;
+}

package/src/test-utils/get-string.ts

@@ -0,0 +1,14 @@
+/**
+ * Narrows one field of a record to a string, for tests pulling an id or a
+ * command out of a loosely typed protocol reply. Throws rather than letting a
+ * malformed reply pass a test vacuously.
+ */
+export function getString(value: Readonly<Record<string, unknown>>, key: string): string {
+  const inner = value[key];
+
+  if (typeof inner !== 'string') {
+    throw new TypeError(`${key} is not a string`);
+  }
+
+  return inner;
+}

package/src/test-utils/keys.ts

@@ -0,0 +1,26 @@
+/**
+ * The control bytes and escape sequences tests type into a terminal, by
+ * name, so a test reads `KEYS.esc` where it would otherwise hold an opaque
+ * escape. `bel` is the one entry a terminal writes rather than reads: the
+ * byte that ends an OSC sequence on screen.
+ */
+export const KEYS = Object.freeze({
+  ctrlSpace: '\u0000',
+  ctrlA: '\u0001',
+  ctrlB: '\u0002',
+  ctrlC: '\u0003',
+  bel: '\u0007',
+  tab: '\u0009',
+  ctrlJ: '\u000A',
+  enter: '\u000D',
+  ctrlU: '\u0015',
+  esc: '\u001B',
+  ctrlRightBracket: '\u001D',
+  backspace: '\u007F',
+  up: '\u001B[A',
+  down: '\u001B[B',
+  right: '\u001B[C',
+  left: '\u001B[D',
+  pasteOpen: '\u001B[200~',
+  pasteClose: '\u001B[201~',
+});

package/src/test-utils/merge-deep.ts

@@ -0,0 +1,36 @@
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A copy of the defaults with each override laid over it: a plain object
+ * on both sides merges key by key at every depth, and any other value,
+ * arrays and class instances included, replaces the default whole. Neither
+ * argument changes. A mock factory passes its fresh defaults here, so a
+ * nested override keeps every default beside it. `K` holds the keys the
+ * defaults set; an override of any other key must be whole.
+ */
+export function mergeDeep<T extends object, K extends keyof T = keyof T>(
+  defaults: T,
+  overrides: MockOverrides<T, K>,
+): T {
+  // oxlint-disable-next-line no-unsafe-type-assertion -- merging a deep partial of T over a whole T yields a whole T
+  return mergeRecords(defaults, overrides) as T;
+}
+
+function mergeRecords(base: object, patch: object): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...base };
+
+  for (const [key, value] of Object.entries(patch)) {
+    const current = merged[key];
+
+    merged[key] =
+      isPlainObject(current) && isPlainObject(value) ? mergeRecords(current, value) : value;
+  }
+
+  return merged;
+}
+
+function isPlainObject(value: unknown): value is object {
+  return (
+    typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype
+  );
+}

package/src/test-utils/mock-overrides.ts

@@ -0,0 +1,13 @@
+import type { PartialDeep } from 'type-fest';
+
+/**
+ * The overrides a mock factory takes for a type whose defaults set the
+ * keys `K`: a field the defaults set takes a deep partial, merged into the
+ * default, and any other field takes a whole value, since there is no
+ * default to merge a partial one into.
+ */
+export type MockOverrides<T, K extends keyof T> = {
+  readonly [P in K]?: PartialDeep<T[P]>;
+} & {
+  readonly [P in Exclude<keyof T, K>]?: T[P];
+};

package/src/test-utils/open-repo-step.ts

@@ -0,0 +1,24 @@
+import { KEYS } from './keys';
+import type { TUIHarness } from './start-tui-harness';
+
+/**
+ * Opens the GitHub repository step of a Claude spawn from the home screen:
+ * the first agent, then a tab from the directory step to the next source.
+ * Resolves once the step's title is drawn, with the capture holding what
+ * the client drew since the tab.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a harness is a live handle
+export async function openRepoStep(tui: TUIHarness): Promise<void> {
+  tui.write('n');
+
+  await tui.waitFor('spawn: agent');
+
+  tui.write(KEYS.enter);
+
+  await tui.waitFor('spawn: directory');
+
+  tui.reset();
+  tui.write(KEYS.tab);
+
+  await tui.waitFor('spawn: GitHub repository');
+}

package/src/test-utils/read-query-plan.ts

@@ -0,0 +1,22 @@
+import { Database } from 'bun:sqlite';
+import type { SQLQueryBindings } from 'bun:sqlite';
+import type { CompiledQuery } from 'kysely';
+
+/**
+ * Reads the plan SQLite picks for one compiled query against the database
+ * at the path, bound to the query's own parameters, as the plan's detail
+ * lines joined by newlines. It opens the database read-only and closes it
+ * before returning, so the query never runs and nothing is written.
+ */
+export function readQueryPlan(dbPath: string, query: CompiledQuery): string {
+  using db = new Database(dbPath, { readonly: true });
+
+  // oxlint-disable-next-line no-unsafe-type-assertion -- kysely's sqlite compiler only ever binds bun:sqlite-legal values
+  const bindings = query.parameters as SQLQueryBindings[];
+
+  return db
+    .query<{ detail: string }, SQLQueryBindings[]>(`EXPLAIN QUERY PLAN ${query.sql}`)
+    .all(...bindings)
+    .map((row) => row.detail)
+    .join('\n');
+}

package/src/test-utils/register-test-cleanup.ts

@@ -0,0 +1,63 @@
+import { onTestFinished } from 'bun:test';
+
+// The releases the current test registered, in registration order; null
+// before its first registration and once its hook has started.
+let pending: (() => unknown)[] | null = null;
+
+/**
+ * Registers the release of a resource a test just acquired, to run once the
+ * current test finishes, and returns that release for the resource's own
+ * stop and dispose members. Every release a test registers runs from one
+ * hook, last registered first, as `using` declarations release, so a
+ * directory made before a process that lives in it is removed only after
+ * that process stops. A release that throws stops none of the others: the
+ * hook rethrows once every release has run, as an `AggregateError` when
+ * more than one threw. The returned release runs its callback once: every
+ * later call, from the hook or from the test, returns what the first call
+ * returned. Bun runs the hook after every `afterEach`, so a release works
+ * from the paths and handles it captured. Throws outside a test, where
+ * nothing would run the hook.
+ */
+export function registerTestCleanup<T>(release: () => T): () => T {
+  let released: { readonly value: T } | null = null;
+
+  const releaseOnce = (): T => {
+    released ??= { value: release() };
+
+    return released.value;
+  };
+
+  if (pending === null) {
+    onTestFinished(releasePending);
+
+    pending = [];
+  }
+
+  pending.push(releaseOnce);
+
+  return releaseOnce;
+}
+
+async function releasePending(): Promise<void> {
+  const releases = pending ?? [];
+
+  pending = null;
+
+  const errors: unknown[] = [];
+
+  for (const release of releases.toReversed()) {
+    try {
+      await release();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+
+  if (errors.length > 1) {
+    throw new AggregateError(errors, 'more than one test cleanup failed');
+  }
+}

package/src/test-utils/resolve-atc-command.ts

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+
+/**
+ * The command an end-to-end suite runs atc as: the compiled binary that
+ * `ATC_BIN` holds when a smoke run sets it, or else the source entry under
+ * the test's own bun, so one suite proves both. Read at each call, so a test
+ * that sets the variable sees its own value.
+ */
+export function resolveATCCommand(): string[] {
+  const bin = process.env['ATC_BIN'];
+
+  return bin === undefined ? [process.execPath, join(import.meta.dir, '..', 'cli.ts')] : [bin];
+}

package/src/test-utils/resolve-gateway-command.ts

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+
+/**
+ * The command a test runs `atc-gateway` as: the compiled binary at the given
+ * path, which a smoke run of a release build passes in through
+ * `ATC_GATEWAY_BIN`, or without one the source entry under the test's own
+ * bun, so one gateway suite proves both.
+ */
+export function resolveGatewayCommand(binary: string | undefined): readonly string[] {
+  return binary === undefined
+    ? [process.execPath, join(import.meta.dir, '..', 'gateway.ts')]
+    : [binary];
+}

package/src/test-utils/run-atc.ts

@@ -0,0 +1,56 @@
+interface ATCRun {
+  // The command atc runs as, such as the source entry under bun or a
+  // compiled binary.
+  readonly command: readonly string[];
+
+  readonly args: readonly string[];
+
+  // HOME and XDG_RUNTIME_DIR for the run, so it finds the daemon and the
+  // state of this home alone.
+  readonly home: string;
+
+  // Variables laid over the inherited environment; `undefined` removes one.
+  readonly env?: Readonly<Record<string, string | undefined>>;
+
+  readonly stdin?: string;
+  readonly cwd?: string;
+}
+
+interface ATCResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/**
+ * Runs one atc subcommand as its own process against a home and resolves
+ * once it exits, with its exit code and everything it printed. The process
+ * inherits the test's environment with HOME and XDG_RUNTIME_DIR pointed at
+ * the home, then the run's own variables over that.
+ */
+export async function runATC(run: Readonly<ATCRun>): Promise<ATCResult> {
+  const env = Object.fromEntries(
+    Object.entries({
+      ...process.env,
+      HOME: run.home,
+      XDG_RUNTIME_DIR: run.home,
+      ...run.env,
+    }).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+
+  const proc = Bun.spawn([...run.command, ...run.args], {
+    env,
+    ...(run.cwd === undefined ? {} : { cwd: run.cwd }),
+    stdin: run.stdin === undefined ? 'ignore' : new TextEncoder().encode(run.stdin),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { exitCode, stdout, stderr };
+}

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

@@ -1,15 +1,19 @@
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { PROTOCOL_V } from '../protocol/protocol';
-import { startLegacyDaemon } from './start-legacy-daemon';
+import { startStubLegacyDaemon } from './start-stub-legacy-daemon';
 
 /**
  * Runs a daemon of another protocol version as its own process, recorded in
  * the state directory the way a real daemon records itself, so a client
  * that finds it by its record can stop it. Arguments: the socket path to
  * listen on and the state directory. It refuses every handshake with
- * `protocol_mismatch`, prints `up` once it listens, and runs until it is
- * killed.
+ * `protocol_mismatch` and hosts one session, a child process that sleeps for
+ * a minute. Once it listens it prints `up` and the session's pid on one
+ * line, and it runs until it is killed. On SIGTERM or SIGINT it kills and
+ * reaps the session, then dies of the same signal, and it kills the session
+ * whenever it exits, so a caller that stops only the daemon leaves nothing
+ * behind.
  */
 function main() {
   const socketPath = process.argv.at(2);
@@ -19,7 +23,25 @@ function main() {
     throw new Error('usage: run-legacy-daemon.ts <socket path> <state dir>');
   }
 
-  startLegacyDaemon(socketPath, { protocol: PROTOCOL_V + 1 });
+  startStubLegacyDaemon(socketPath, { protocol: PROTOCOL_V + 1, owner: 'caller' });
+
+  const session = Bun.spawn(['sleep', '60']);
+
+  process.on('exit', () => {
+    session.kill('SIGKILL');
+  });
+
+  for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+    process.once(signal, () => {
+      void (async () => {
+        session.kill('SIGKILL');
+
+        await session.exited;
+
+        process.kill(process.pid, signal);
+      })();
+    });
+  }
 
   writeFileSync(
     join(stateDir, 'daemon.json'),
@@ -32,7 +54,7 @@ function main() {
     }),
   );
 
-  console.log('up');
+  console.log(`up ${session.pid}`);
 }
 
 main();

package/src/test-utils/run-listener-daemon.ts

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { startDaemon } from '../daemon/daemon';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
 
 /**
  * Runs a daemon with a TCP listener on a kernel-chosen loopback port, its
@@ -15,17 +16,11 @@ async function main() {
     socketPath: join(dir, 'daemon.sock'),
     reporterSocketPath: join(dir, 'reporter.sock'),
     build: 'atc/test-build',
-    adapter: {
-      id: 'claude',
-      screenDetector: null,
+    adapter: buildMockAgentAdapter({
       takesMessages: true,
-      headlessRunner: null,
-      planSpawn: () => ({ bin: 'sleep', args: ['30'] }),
       normalizeHook: () => ({ kind: 'prompt-submitted' }),
-      loadName: () => Promise.resolve(null),
-      canResume: () => true,
       buildResumeCommand: () => 'claude --resume',
-    },
+    }),
     dbPath: join(dir, 'state.db'),
     statusPath: join(dir, 'status.json'),
     listen: {
@@ -37,8 +32,6 @@ async function main() {
     },
   });
 
-  process.stdout.write(`${String(handle.listenPort)}\n`);
-
   process.on('SIGTERM', () => {
     void (async () => {
       await handle.stop();
@@ -46,6 +39,8 @@ async function main() {
       process.exit(0);
     })();
   });
+
+  process.stdout.write(`${String(handle.listenPort)}\n`);
 }
 
 await main();

package/src/test-utils/run-mcp-authorization.ts

@@ -18,6 +18,9 @@ interface MCPAuthorizationRequest {
 }
 
 interface MCPAuthorization {
+  // The consent page the approval code sent the browser to.
+  readonly consent: URL;
+
   // Where the consent page sent the browser back to.
   readonly callback: URL;
   readonly code: string;
@@ -29,9 +32,9 @@ interface MCPAuthorization {
  * browser and the operator do: opens the authorization request with PKCE,
  * types the approval code the server printed into the login page, and ticks
  * the given scopes on the consent page. Each request starts with no cookies,
- * as a fresh browser would. Returns where the browser landed and what a token
- * request needs, and throws when any step's response lacks the value the next
- * step depends on.
+ * as a fresh browser would. Returns the consent page it passed, where the
+ * browser landed, and what a token request needs, and throws when any step's
+ * response lacks the value the next step depends on.
  */
 export async function runMCPAuthorization(
   server: MCPAuthorizationServer,
@@ -114,5 +117,5 @@ export async function runMCPAuthorization(
     throw new Error(`the consent redirect holds no authorization code: ${location}`);
   }
 
-  return { callback, code, verifier };
+  return { consent, callback, code, verifier };
 }

package/src/test-utils/run-source-daemon.ts

@@ -96,8 +96,6 @@ async function main() {
     gitTransports: config.workspaces.gitTransports,
   });
 
-  process.stdout.write('up\n');
-
   process.on('SIGTERM', () => {
     void (async () => {
       await handle.stop();
@@ -105,6 +103,8 @@ async function main() {
       process.exit(0);
     })();
   });
+
+  process.stdout.write('up\n');
 }
 
 await main();

package/src/test-utils/seed-faker.ts

@@ -0,0 +1,7 @@
+import { faker } from '@faker-js/faker';
+
+// Seeds faker once for the whole run and fixes the date its relative dates
+// count from, so a failing run's factory values, dates included, come out
+// the same on the next run.
+faker.seed(48);
+faker.setDefaultRefDate(new Date('2026-01-01T00:00:00.000Z'));

package/src/test-utils/send-lines-before-handshake.ts

@@ -0,0 +1,35 @@
+// How many connections are open at once, so a flood stays within the
+// host's open-file limit.
+const BATCH = 100;
+
+/**
+ * Opens `count` TCP connections to the loopback port, each on its own,
+ * writes one line that is not a handshake on each, and resolves once the
+ * server has closed every one, as a daemon's listener closes a connection
+ * it refuses.
+ */
+export async function sendLinesBeforeHandshake(port: number, count: number): Promise<void> {
+  for (let start = 0; start < count; start += BATCH) {
+    await Promise.all(
+      Array.from({ length: Math.min(BATCH, count - start) }, async () => {
+        const closed = Promise.withResolvers<void>();
+
+        await Bun.connect({
+          hostname: '127.0.0.1',
+          port,
+          socket: {
+            open(socket) {
+              socket.write('not a handshake\n');
+            },
+            data() {},
+            close() {
+              closed.resolve();
+            },
+          },
+        });
+
+        await closed.promise;
+      }),
+    );
+  }
+}

package/src/test-utils/send-mcp-request.ts

@@ -0,0 +1,25 @@
+import { getRecord } from '../shared/get-record';
+import { readJSONRecord } from './read-json-record';
+
+/**
+ * Posts one JSON-RPC request to an MCP HTTP server's `/mcp` endpoint with
+ * the given access token as a bearer token, and returns the response's
+ * `result`. Throws when the body is not a JSON object with an object
+ * `result`, such as a JSON-RPC error.
+ */
+export async function sendMCPRequest(
+  url: string,
+  token: string,
+  method: string,
+  params: Readonly<Record<string, unknown>> = {},
+): Promise<Readonly<Record<string, unknown>>> {
+  const answered = await fetch(`${url}/mcp`, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+  });
+
+  const body = await readJSONRecord(answered);
+
+  return getRecord(body, 'result');
+}

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

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findPidFilePID } from '../shared/find-pid-file-pid';
+import { stopDaemonProcess } from '../stop-daemon-process';
+import { buildStubMCPClaude } from './build-stub-mcp-claude';
+import { buildStubMCPGrok } from './build-stub-mcp-grok';
+import { createStubBin } from './create-stub-bin';
+import { registerTestCleanup } from './register-test-cleanup';
+import { setupTempDir } from './setup-temp-dir';
+import { waitFor } from './wait-for';
+
+/**
+ * A temp home for running `atc mcp` against, with the stand-in `claude` and
+ * `grok` at `claudeBin` and `grokBin` and a config that registers them with
+ * no extra arguments. A server started with this home as its `HOME` and
+ * `XDG_RUNTIME_DIR` boots its daemon here. Each stand-in appends its pid,
+ * which is its process group as a session leader, to `stub-pids` in the
+ * home. Disposal stops the daemon, when one wrote its pid file here, and
+ * waits for it to exit; then it kills the daemon's process group and every
+ * group `stub-pids` records, such as a reporter a stopped session left
+ * behind, waits until each group is empty, and removes the home. That
+ * disposal runs once the current test finishes, so it must run inside a
+ * test; disposing sooner runs it then, and a second disposal does nothing.
+ */
+export function setupMCPHome() {
+  const tmp = setupTempDir('atc-mcp-');
+
+  // Registered after the home, so it releases first: the daemon and the
+  // stand-ins stop before the home that records them is removed.
+  const stack = new AsyncDisposableStack();
+
+  const dispose = registerTestCleanup(() => stack.disposeAsync());
+
+  stack.use(tmp);
+
+  const home = tmp.dir;
+
+  stack.defer(async () => {
+    const pid = findPidFilePID(join(home, 'atc-daemon.pid'));
+
+    if (pid !== null) {
+      await stopDaemonProcess(pid);
+    }
+
+    await killProcessGroups([...(pid === null ? [] : [pid]), ...readStubPIDs(home)]);
+  });
+
+  mkdirSync(join(home, '.config', 'atc'), { recursive: true });
+  mkdirSync(join(home, '.local', 'state', 'atc'), { recursive: true });
+
+  const claudeBin = createStubBin(home, 'fake-claude', buildStubMCPClaude());
+  const grokBin = createStubBin(home, 'fake-grok', buildStubMCPGrok());
+
+  writeFileSync(
+    join(home, '.config', 'atc', 'config.json'),
+    JSON.stringify({ claudeBin, claudeArgs: [], grokBin, grokArgs: [] }),
+  );
+
+  return {
+    home,
+    claudeBin,
+    grokBin,
+    [Symbol.asyncDispose]: dispose,
+  };
+}
+
+/**
+ * The pids the stand-ins recorded in the home, one per line; none when no
+ * stand-in ran.
+ */
+function readStubPIDs(home: string): number[] {
+  const path = join(home, 'stub-pids');
+
+  if (!existsSync(path)) {
+    return [];
+  }
+
+  return readFileSync(path, 'utf8')
+    .split('\n')
+    .filter((line) => line !== '')
+    .map(Number);
+}
+
+async function killProcessGroups(groups: readonly number[]): Promise<void> {
+  for (const group of groups) {
+    try {
+      process.kill(-group, 'SIGKILL');
+    } catch {
+      // The group is already empty.
+    }
+  }
+
+  await waitFor(() => {
+    const running = groups.filter((group) => isProcessGroupRunning(group));
+
+    if (running.length > 0) {
+      throw new Error(`process groups still running: ${running.join(', ')}`);
+    }
+  });
+}
+
+function isProcessGroupRunning(group: number): boolean {
+  try {
+    process.kill(-group, 0);
+
+    return true;
+  } catch (error) {
+    return !(error instanceof Error && Reflect.get(error, 'code') === 'ESRCH');
+  }
+}