@zgeoff/atc 3.4.0 → 3.4.1

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

@@ -0,0 +1,47 @@
+import type { Socket } from 'bun';
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubRecordingListener {
+  // Resolves with the server's side of the first connection it accepts.
+  readonly accepted: Promise<Socket>;
+
+  // What each read took from any connection, decoded, in arrival order.
+  readonly received: readonly string[];
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a peer that a test writes through: it listens on the unix
+ * socket path, hands the test the server's side of the first connection it
+ * accepts, records what each read takes from any connection, and sends
+ * nothing of its own. It stops, dropping every connection it holds, once
+ * the current test finishes, so it must run inside a test; disposal stops it
+ * sooner, and a second stop does nothing.
+ */
+export function startStubRecordingListener(path: string): StubRecordingListener {
+  const accepted = Promise.withResolvers<Socket>();
+  const received: string[] = [];
+
+  const server = Bun.listen({
+    unix: path,
+    socket: {
+      open(socket) {
+        accepted.resolve(socket);
+      },
+      data(_socket, data) {
+        received.push(data.toString());
+      },
+      error() {},
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    accepted: accepted.promise,
+    received,
+    [Symbol.dispose]: stop,
+  };
+}

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

@@ -1,3 +1,5 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
 interface StubRefusingListener {
   readonly port: number;
 
@@ -11,7 +13,8 @@ interface StubRefusingListener {
  * A stand-in for a daemon's TCP listener refusing a connection whose first
  * line is not a handshake: on a loopback port, it records what each read
  * takes from a connection and ends that connection, answering nothing.
- * Disposal stops it; hold the result with `using`.
+ * 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 startStubRefusingListener(): StubRefusingListener {
   const received: string[] = [];
@@ -28,11 +31,13 @@ export function startStubRefusingListener(): StubRefusingListener {
     },
   });
 
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
   return {
     port: server.port,
     received,
-    [Symbol.dispose]: () => {
-      server.stop(true);
-    },
+    [Symbol.dispose]: stop,
   };
 }

package/src/test-utils/start-stub-reporter-socket.ts

@@ -1,3 +1,4 @@
+import { registerTestCleanup } from './register-test-cleanup';
 import { waitFor } from './wait-for';
 
 interface StubReporterSocket {
@@ -19,8 +20,9 @@ interface StubReporterSocket {
  * hook and report commands send. It never writes back, and leaves each
  * connection for the sender to close. `waitForLine` resolves with the first
  * line once one has arrived, and rejects naming the socket when none arrives
- * within `timeoutMs`, 5 seconds by default. Disposal stops the listener; hold the
- * result with `using` or `await using`.
+ * within `timeoutMs`, 5 seconds by default. The listener 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 startStubReporterSocket(path: string): StubReporterSocket {
   const lines: string[] = [];
@@ -45,9 +47,9 @@ export function startStubReporterSocket(path: string): StubReporterSocket {
     },
   });
 
-  const stop = () => {
+  const stop = registerTestCleanup(() => {
     server.stop(true);
-  };
+  });
 
   return {
     lines,

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

@@ -1,5 +1,6 @@
 import { LineDecoder } from '../protocol/line-decoder';
 import { PROTOCOL_V, decodeMessage, encodeMessage } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
 
 /**
  * A daemon stand-in on a unix socket path that speaks the real wire format
@@ -7,8 +8,8 @@ import { PROTOCOL_V, decodeMessage, encodeMessage } from '../protocol/protocol';
  * result, answers each other request with the next reply the test pushes
  * onto `lists`, and withholds the answer to any request that finds `lists`
  * empty. `methods` holds the method of each request it took, in order.
- * Disposal stops the listener; hold the result with `using` or
- * `await using`.
+ * The listener 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 startStubRestoreDaemon(socketPath: string) {
   const lists: Readonly<Record<string, unknown>>[] = [];
@@ -41,9 +42,9 @@ export function startStubRestoreDaemon(socketPath: string) {
     },
   });
 
-  const stop = () => {
+  const stop = registerTestCleanup(() => {
     server.stop(true);
-  };
+  });
 
   return {
     lists,

package/src/test-utils/start-stub-session-bridge.ts

@@ -1,4 +1,5 @@
 import { isRecord } from '../shared/report';
+import { registerTestCleanup } from './register-test-cleanup';
 
 type BridgeRequest = Readonly<Record<string, unknown>>;
 
@@ -26,8 +27,9 @@ interface StubSessionBridge {
  * `tap.open` request with `ok` under the request's id as the real bridge
  * does once it attaches the tap, and hands every other request to the
  * responder, writing back each line it returns. A line that is not a JSON
- * object reaches the responder as an empty request. Disposal stops the
- * listener; hold the result with `using` or `await using`.
+ * object reaches the responder as an empty request. The listener 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 startStubSessionBridge(path: string, respond: BridgeResponder): StubSessionBridge {
   const requests: BridgeRequest[] = [];
@@ -69,9 +71,9 @@ export function startStubSessionBridge(path: string, respond: BridgeResponder):
     },
   });
 
-  const stop = () => {
+  const stop = registerTestCleanup(() => {
     server.stop(true);
-  };
+  });
 
   return {
     requests,

package/src/test-utils/start-stub-silent-server.ts

@@ -1,9 +1,12 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
 /**
  * An HTTP stand-in for an upstream that hangs: it listens on a real port of
  * the loopback address, takes every request, and never answers one. `paths`
- * holds the request path of each request it took, in order. Disposal stops
- * the server and drops the connections it holds; the asynchronous form
- * resolves once it has stopped.
+ * holds the request path of each request it took, in order. The server
+ * stops, dropping the connections it holds, 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 startStubSilentServer() {
   const paths: string[] = [];
@@ -22,12 +25,14 @@ export function startStubSilentServer() {
     },
   });
 
+  const stop = registerTestCleanup(() => server.stop(true));
+
   return {
     url: `http://127.0.0.1:${String(server.port)}/`,
     paths,
     [Symbol.dispose]: () => {
-      void server.stop(true);
+      void stop();
     },
-    [Symbol.asyncDispose]: () => server.stop(true),
+    [Symbol.asyncDispose]: stop,
   };
 }

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

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { registerTestCleanup } from './register-test-cleanup';
 
 /**
  * Starts a daemon composed with a fixture source, in a process of its own
@@ -8,7 +9,8 @@ import { join } from 'node:path';
  * `ATC_TEST_SOURCES` picks its sources, the fixture one unless it holds
  * `none`; `ATC_TEST_FIXTURE_URL` holds the repository the fixture source
  * lists, and `ATC_TEST_SOURCE_LOG` a file it appends each listing to.
- * Disposal stops the process; hold the result with `await using`.
+ * The process stops once the current test finishes, so it must run inside
+ * a test; disposal stops it sooner, and a second stop does nothing.
  */
 export async function startStubSourceDaemon(env: Readonly<Record<string, string | undefined>>) {
   const daemon = Bun.spawn([process.execPath, join(import.meta.dir, 'run-source-daemon.ts')], {
@@ -17,11 +19,11 @@ export async function startStubSourceDaemon(env: Readonly<Record<string, string
     stderr: 'ignore',
   });
 
-  const stop = async () => {
+  const stop = registerTestCleanup(async () => {
     daemon.kill();
 
     await daemon.exited;
-  };
+  });
 
   const reader = daemon.stdout.getReader();
 

package/src/test-utils/start-stub-stalled-client.ts

@@ -0,0 +1,61 @@
+import { createConnection } from 'node:net';
+import { PROTOCOL_V, encodeMessage } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubStalledClient {
+  // Each chunk the client has read off its connection, in order.
+  readonly chunks: readonly unknown[];
+
+  // How many bytes have arrived on the connection and wait unread.
+  readonly countUnreadBytes: () => number;
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a daemon client that stops reading: it connects to the
+ * daemon's unix socket, sends a `daemon.hello` with no auth as `client`,
+ * reads the first chunk the daemon sends, and then holds its next read on
+ * a promise that never resolves, so whatever the daemon sends it after
+ * that backs up. Resolves once that first chunk arrives. The connection is
+ * destroyed once the current test finishes, so it must run inside a test;
+ * disposal destroys it sooner, and a second stop does nothing.
+ */
+export async function startStubStalledClient(
+  socketPath: string,
+  client: string,
+): Promise<StubStalledClient> {
+  const held = Promise.withResolvers<void>();
+  const first = Promise.withResolvers<void>();
+  const chunks: unknown[] = [];
+  const socket = createConnection(socketPath);
+
+  const stop = registerTestCleanup(() => {
+    socket.destroy();
+  });
+
+  socket.write(
+    encodeMessage({
+      v: PROTOCOL_V,
+      id: 1,
+      m: 'daemon.hello',
+      p: { client, auth: { scheme: 'none' } },
+    }),
+  );
+
+  void (async () => {
+    for await (const chunk of socket) {
+      chunks.push(chunk);
+      first.resolve();
+
+      await held.promise;
+    }
+  })();
+
+  await first.promise;
+
+  return {
+    chunks,
+    countUnreadBytes: () => socket.readableLength,
+    [Symbol.dispose]: stop,
+  };
+}

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

@@ -1,5 +1,6 @@
 import { createServer } from 'node:net';
 import type { Socket } from 'node:net';
+import { registerTestCleanup } from './register-test-cleanup';
 
 interface StubStalledListener {
   readonly [Symbol.dispose]: () => void;
@@ -9,8 +10,9 @@ interface StubStalledListener {
  * A stand-in for a peer that stops reading: it listens on the unix socket
  * path and accepts every connection but never reads from it, so what the
  * kernel does not buffer stays queued on the sender's side. Resolves once
- * it listens. Disposal destroys every connection it accepted and stops it;
- * hold the result with `using`.
+ * it listens. Once the current test finishes, it destroys every connection
+ * it accepted and stops, so it must run inside a test; disposal does so
+ * sooner, and a second stop does nothing.
  */
 export async function startStubStalledListener(path: string): Promise<StubStalledListener> {
   const peers = new Set<Socket>();
@@ -28,13 +30,15 @@ export async function startStubStalledListener(path: string): Promise<StubStalle
 
   await listening.promise;
 
-  return {
-    [Symbol.dispose]: () => {
-      for (const peer of peers) {
-        peer.destroy();
-      }
+  const stop = registerTestCleanup(() => {
+    for (const peer of peers) {
+      peer.destroy();
+    }
+
+    server.close();
+  });
 
-      server.close();
-    },
+  return {
+    [Symbol.dispose]: stop,
   };
 }

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { PROTOCOL_V } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
 
 interface StubTCPDaemon {
   readonly port: number;
@@ -23,7 +24,9 @@ const REQUEST = z.object({ id: z.number(), m: z.string() });
  * newline-delimited protocol requests and answers each with an ok that holds
  * the request's method, recording every method in `seen`. It sends no
  * handshake of its own and checks no token. `reads` counts the reads it has
- * taken from every connection. Disposal stops it.
+ * taken from every connection. 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 startStubTCPDaemon(): StubTCPDaemon {
   const seen: string[] = [];
@@ -57,14 +60,16 @@ export function startStubTCPDaemon(): StubTCPDaemon {
     },
   });
 
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
   return {
     port: server.port,
     seen,
     get reads() {
       return reads;
     },
-    [Symbol.dispose]: () => {
-      server.stop(true);
-    },
+    [Symbol.dispose]: stop,
   };
 }

package/src/test-utils/start-stub-telemetry-collector.ts

@@ -1,9 +1,13 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
 /**
  * A stand-in for better-auth's telemetry endpoint on a real HTTP port of the
  * loopback address. A process whose `BETTER_AUTH_TELEMETRY_ENDPOINT` holds
  * `url` sends its telemetry here. Every request is answered with HTTP 204,
- * and `received` holds the URL of each request, in order. Disposal stops the
- * server and resolves once it has stopped.
+ * and `received` holds the URL of each request, in order. The server stops
+ * once the current test finishes, so it must run inside a test; disposal
+ * stops it sooner and resolves once it has stopped, and a second stop does
+ * nothing.
  */
 export function startStubTelemetryCollector() {
   const received: string[] = [];
@@ -18,9 +22,11 @@ export function startStubTelemetryCollector() {
     },
   });
 
+  const stop = registerTestCleanup(() => server.stop(true));
+
   return {
     url: `http://127.0.0.1:${String(server.port)}/`,
     received,
-    [Symbol.asyncDispose]: () => server.stop(true),
+    [Symbol.asyncDispose]: stop,
   };
 }

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

@@ -0,0 +1,41 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubUnansweringListener {
+  readonly port: number;
+
+  // What each read took from any connection, decoded, in arrival order.
+  readonly received: readonly string[];
+
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a daemon that accepts a connection and never answers it:
+ * on a loopback port, it records what each read takes from a connection,
+ * sends nothing back, and keeps the connection open. It stops, dropping
+ * every connection it holds, once the current test finishes, so it must run
+ * inside a test; disposal stops it sooner, and a second stop does nothing.
+ */
+export function startStubUnansweringListener(): StubUnansweringListener {
+  const received: string[] = [];
+
+  const server = Bun.listen({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: {
+      data(_socket, data) {
+        received.push(data.toString());
+      },
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    port: server.port,
+    received,
+    [Symbol.dispose]: stop,
+  };
+}

package/src/test-utils/start-stub-unanswering-unix-listener.ts

@@ -0,0 +1,38 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubUnansweringUnixListener {
+  // What each read took from any connection, decoded, in arrival order.
+  readonly received: readonly string[];
+
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a daemon socket that takes a connection and never answers
+ * it: it listens on the unix socket path, records what each read takes from
+ * a connection, sends nothing back, and keeps the connection open. It
+ * stops, dropping every connection it holds, once the current test
+ * finishes, so it must run inside a test; disposal stops it sooner, and a
+ * second stop does nothing.
+ */
+export function startStubUnansweringUnixListener(path: string): StubUnansweringUnixListener {
+  const received: string[] = [];
+
+  const server = Bun.listen({
+    unix: path,
+    socket: {
+      data(_socket, data) {
+        received.push(data.toString());
+      },
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    received,
+    [Symbol.dispose]: stop,
+  };
+}

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

@@ -4,6 +4,7 @@ import { DaemonClient } from '../client/daemon-client';
 import { startDaemon } from '../daemon/daemon';
 import type { DaemonHandle, DaemonOptions } from '../daemon/daemon';
 import type { EventMsg } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
 import { setupTempDir } from './setup-temp-dir';
 
 /**
@@ -60,12 +61,21 @@ const BUILD = 'atc/test-build';
  * connection. `stop` closes every client and stops the daemon; `restart`
  * does the same, then boots on the same paths and state with the options
  * given or the last ones, and opens a new main client. Disposal stops what
- * is running and removes the directory; hold the result with `await using`.
+ * is running and removes the directory. 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. A first boot that fails runs it
+ * before the start rejects.
  */
 export async function startTestDaemon(config: TestDaemonConfig = {}) {
-  await using stack = new AsyncDisposableStack();
+  const tmp = setupTempDir(config.prefix ?? 'atc-test-daemon-');
 
-  const tmp = stack.use(setupTempDir(config.prefix ?? 'atc-test-daemon-'));
+  // Registered after the directory, so it releases first: the daemon stops
+  // before its directory is removed.
+  const stack = new AsyncDisposableStack();
+
+  const dispose = registerTestCleanup(() => stack.disposeAsync());
+
+  stack.use(tmp);
 
   const paths: TestDaemonPaths = {
     dir: tmp.dir,
@@ -141,9 +151,13 @@ export async function startTestDaemon(config: TestDaemonConfig = {}) {
     return { daemon, client };
   };
 
-  let current = await boot();
+  // A boot that fails stops what it started and removes the directory
+  // before the start rejects.
+  let current = await boot().catch(async (error: unknown) => {
+    await dispose();
 
-  const owned = stack.move();
+    throw error;
+  });
 
   return {
     ...paths,
@@ -210,6 +224,6 @@ export async function startTestDaemon(config: TestDaemonConfig = {}) {
 
       current = await boot();
     },
-    [Symbol.asyncDispose]: () => owned.disposeAsync(),
+    [Symbol.asyncDispose]: dispose,
   };
 }

package/src/test-utils/start-tui-harness.ts

@@ -6,6 +6,7 @@ import { buildStubTUIClaude } from './build-stub-tui-claude';
 import { buildStubTUIGrok } from './build-stub-tui-grok';
 import { createStubBin } from './create-stub-bin';
 import { mergeDeep } from './merge-deep';
+import { registerTestCleanup } from './register-test-cleanup';
 import { setupTempDir } from './setup-temp-dir';
 import { waitFor } from './wait-for';
 
@@ -37,15 +38,24 @@ interface TUIHarnessOptions {
  * transports the fixture repositories need, with the fields given laid over
  * them. `env` is the environment the client runs with, so a daemon started
  * with it serves the client. A wait made before the client draws anything
- * gets `bootMs` for that first byte. Disposal stops the client and the daemon in
- * the home and removes it; hold the result with `await using`.
+ * gets `bootMs` for that first byte. Disposal stops the client and the
+ * daemon in the home and removes it. 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 startTUIHarness(options: TUIHarnessOptions = {}) {
-  using setup = new DisposableStack();
+  const tmp = setupTempDir('atc-tui-');
+
+  // Registered after the home, so it releases first: the client and its
+  // daemon stop before their home is removed.
+  const owned = new AsyncDisposableStack();
+
+  const dispose = registerTestCleanup(() => owned.disposeAsync());
+
+  owned.use(tmp);
 
   // The client boots with this home as its cwd and lists it first in the
   // picker, so the path is resolved the way the client reports it.
-  const tmp = setup.use(setupTempDir('atc-tui-'));
   const home = realpathSync(tmp.dir);
   const configPath = join(home, '.config', 'atc', 'config.json');
   const clientLogPath = join(home, 'client.log');
@@ -97,9 +107,6 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
   // the interaction budget.
   let firstOutputAt: number | null = null;
 
-  const owned = new AsyncDisposableStack();
-
-  owned.use(setup.move());
   owned.defer(() => stopClientAndDaemon(home, pty, firstOutputAt === null));
 
   return {
@@ -218,7 +225,7 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
       );
     },
 
-    [Symbol.asyncDispose]: () => owned.disposeAsync(),
+    [Symbol.asyncDispose]: dispose,
   };
 }
 

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

@@ -1,4 +1,5 @@
 import { OutboundQueue } from '../protocol/outbound-queue';
+import { registerTestCleanup } from './register-test-cleanup';
 import { waitFor } from './wait-for';
 
 interface SocketLines {
@@ -16,15 +17,26 @@ interface SocketLines {
 interface SocketLinesOptions {
   // How many unsent bytes the connection holds before it refuses a write.
   readonly queueBytes?: number;
+
+  // The clock a line wait reads its deadline from; the wall clock when absent.
+  readonly now?: () => number;
+
+  // Waits out the interval between a line wait's polls; a real sleep when
+  // absent.
+  readonly wait?: (ms: number) => Promise<void>;
 }
 
 /**
  * Connects to a unix socket and collects every complete newline-terminated
  * line it sends, buffering a partial line across reads. `write` sends the
  * whole of what it is given, the rest going out as the socket drains,
- * and throws instead when the unsent bytes already fill the queue. `waitForLine` polls until the collected count reaches
- * `count` and returns the lines, throwing when `timeoutMs` passes first or
- * the connection closes short of the count. Disposal ends the connection.
+ * and throws instead when the unsent bytes already fill the queue.
+ * `waitForLine` polls until the collected count reaches `count` and returns
+ * the lines, throwing when `timeoutMs` passes first or the connection
+ * closes short of the count; a stub clock passed as `now` and `wait` steps
+ * that timeout without waiting it out. The connection ends once the current
+ * test finishes, so it must run inside a test; disposal ends it sooner, and
+ * a second end does nothing.
  */
 export async function subscribeToSocketLines(
   path: string,
@@ -60,6 +72,10 @@ export async function subscribeToSocketLines(
     },
   });
 
+  const stop = registerTestCleanup(() => {
+    socket.end();
+  });
+
   // The default leaves room for the largest payload a test sends in one
   // piece.
   queue = new OutboundQueue(socket, options.queueBytes ?? 8 * 1024 * 1024);
@@ -93,13 +109,17 @@ export async function subscribeToSocketLines(
             requireLines(count);
           }
         },
-        { timeoutMs },
+        {
+          timeoutMs,
+          now: options.now ?? Date.now,
+          wait: options.wait ?? Bun.sleep,
+        },
       );
 
       return requireLines(count);
     },
     [Symbol.asyncDispose]: () => {
-      socket.end();
+      stop();
 
       return Promise.resolve();
     },