@zgeoff/atc 3.2.0 → 3.3.0

package/src/test-utils/get-agent-entry.ts

@@ -0,0 +1,17 @@
+import type { AgentEntry } from '../shared/collect-agents';
+import type { Config } from '../shared/config';
+
+/**
+ * The registry entry a parsed config holds under an agent id. A test that
+ * builds an adapter from a config reads the entry through this, so a config
+ * that lacks the agent fails the test with the id named.
+ */
+export function getAgentEntry(config: Pick<Config, 'agents'>, id: string): AgentEntry {
+  const entry = config.agents.find((candidate) => candidate.id === id);
+
+  if (entry === undefined) {
+    throw new Error(`the config holds no agent '${id}'`);
+  }
+
+  return entry;
+}

package/src/test-utils/get-gateway-config.ts

@@ -0,0 +1,18 @@
+import type { GatewayConfig } from '../shared/collect-gateways';
+import type { Config } from '../shared/config';
+import { getAgentEntry } from './get-agent-entry';
+
+/**
+ * The gateway a parsed config holds under an agent id: a Claude entry with a
+ * base URL. Throws when the config holds no such agent or the entry has no
+ * base URL.
+ */
+export function getGatewayConfig(config: Pick<Config, 'agents'>, id: string): GatewayConfig {
+  const entry = getAgentEntry(config, id);
+
+  if (entry.baseURL === undefined) {
+    throw new Error(`the agent '${id}' has no baseURL`);
+  }
+
+  return { ...entry, baseURL: entry.baseURL };
+}

package/src/test-utils/isolate-home.ts

@@ -0,0 +1,60 @@
+import { afterEach } from 'bun:test';
+import { join, normalize } from 'node:path';
+import { removeEnvOverrides } from './remove-env-overrides';
+
+// Holds every test run to the isolated home the package test scripts set
+// up before Bun starts, marked by ATC_TEST_HOME. A bare `bun test` stops
+// here: Bun hands a spawned child the environment it started with, not one
+// a preload changed, so only a home set before Bun starts reaches every
+// subprocess a test runs. A run under a marker whose paths do not match it
+// stops too. Both exit before any test imports atc. Once the home holds,
+// every environment variable a test overrides through the shared helper is
+// put back after that test, so the test home's own values return too.
+const marker = process.env['ATC_TEST_HOME'];
+
+if (marker === undefined) {
+  stopRun('a bare `bun test` runs against your real home; run `bun run test` instead');
+}
+
+assertTestHome(marker);
+
+afterEach(() => {
+  removeEnvOverrides();
+});
+
+// An inherited marker is trusted only when every isolated variable already
+// points under it and no enclosing session's variables remain; a stale or
+// hand-set marker stops the run before any test imports atc. An inherited
+// CLAUDE_CONFIG_DIR would move the Claude config folder out of the home.
+function assertTestHome(root: string): void {
+  const expected: Readonly<Record<string, string>> = {
+    HOME: join(root, 'home'),
+    XDG_RUNTIME_DIR: join(root, 'runtime'),
+    XDG_CONFIG_HOME: join(root, 'home', '.config'),
+    XDG_DATA_HOME: join(root, 'home', '.local', 'share'),
+    XDG_STATE_HOME: join(root, 'home', '.local', 'state'),
+    XDG_CACHE_HOME: join(root, 'home', '.cache'),
+    GROK_HOME: join(root, 'home', '.grok'),
+    CODEX_HOME: join(root, 'home', '.codex'),
+  };
+
+  const mismatched = Object.entries(expected)
+    .filter(([name, path]) => normalize(process.env[name] ?? '') !== path)
+    .map(([name]) => name);
+
+  const leftover = ['ATC_SESSION_ID', 'ATC_SOCKET', 'CLAUDE_CONFIG_DIR'].filter(
+    (name) => name in process.env,
+  );
+
+  if (mismatched.length > 0 || leftover.length > 0) {
+    stopRun(
+      `ATC_TEST_HOME is set to ${root} but ${[...mismatched, ...leftover].join(', ')} ` +
+        'does not match the test home it marks; unset ATC_TEST_HOME and run `bun run test`',
+    );
+  }
+}
+
+function stopRun(message: string): never {
+  console.error(`test home: ${message}`);
+  process.exit(2);
+}

package/src/test-utils/read-json-record.ts

@@ -0,0 +1,20 @@
+import { isRecord } from '../shared/report';
+
+interface JSONBody {
+  readonly json: () => Promise<unknown>;
+}
+
+/**
+ * Reads a response body as a JSON object, for tests asserting on an HTTP
+ * endpoint's payload. Throws when the body is any other JSON value, so a
+ * malformed response fails the test instead of passing it vacuously.
+ */
+export async function readJSONRecord(response: JSONBody): Promise<Record<string, unknown>> {
+  const body: unknown = await response.json();
+
+  if (!isRecord(body) || Array.isArray(body)) {
+    throw new TypeError('response body is not a JSON object');
+  }
+
+  return body;
+}

package/src/test-utils/remove-env-overrides.ts

@@ -0,0 +1,18 @@
+import { envOriginals } from './env-originals';
+
+/**
+ * Puts every overridden environment variable back to the value it held before
+ * its first override, unsetting one that was unset, and forgets the recorded
+ * values.
+ */
+export function removeEnvOverrides(): void {
+  for (const [key, value] of envOriginals) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+
+  envOriginals.clear();
+}

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

@@ -0,0 +1,38 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PROTOCOL_V } from '../protocol/protocol';
+import { startLegacyDaemon } from './start-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.
+ */
+function main() {
+  const socketPath = process.argv.at(2);
+  const stateDir = process.argv.at(3);
+
+  if (socketPath === undefined || stateDir === undefined) {
+    throw new Error('usage: run-legacy-daemon.ts <socket path> <state dir>');
+  }
+
+  startLegacyDaemon(socketPath, { protocol: PROTOCOL_V + 1 });
+
+  writeFileSync(
+    join(stateDir, 'daemon.json'),
+    JSON.stringify({
+      pid: process.pid,
+      socketPath,
+      reporterSocketPath: `${socketPath}.reporter`,
+      eventsSocketPath: null,
+      listenPort: null,
+    }),
+  );
+
+  console.log('up');
+}
+
+main();

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

@@ -0,0 +1,51 @@
+import { join } from 'node:path';
+import { startDaemon } from '../daemon/daemon';
+
+/**
+ * Runs a daemon with a TCP listener on a kernel-chosen loopback port, its
+ * state under `ATC_TEST_DIR` and its token file at `gateway-token` there.
+ * The listener logs through its own stderr writer, delays no handshake, and
+ * logs every refusal on a line of its own. It prints the port it bound once
+ * it listens, and SIGTERM stops it.
+ */
+async function main() {
+  const dir = process.env['ATC_TEST_DIR'] ?? '';
+
+  const handle = await startDaemon({
+    socketPath: join(dir, 'daemon.sock'),
+    reporterSocketPath: join(dir, 'reporter.sock'),
+    build: 'atc/test-build',
+    adapter: {
+      id: 'claude',
+      screenDetector: null,
+      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: {
+      host: '127.0.0.1',
+      port: 0,
+      tokenFile: join(dir, 'gateway-token'),
+      failureDelayMs: 0,
+      refusalLogIntervalMs: 0,
+    },
+  });
+
+  process.stdout.write(`${String(handle.listenPort)}\n`);
+
+  process.on('SIGTERM', () => {
+    void (async () => {
+      await handle.stop();
+
+      process.exit(0);
+    })();
+  });
+}
+
+await main();

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

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+
+interface MCPAuthorizationServer {
+  readonly url: string;
+  readonly origin: string;
+  readonly approvals: readonly string[];
+}
+
+interface MCPAuthorizationRequest {
+  readonly clientID: string;
+  readonly redirectURI: string;
+
+  // The scope the client requests.
+  readonly scope: string;
+
+  // The scopes the operator leaves ticked on the consent page.
+  readonly ticked: readonly string[];
+}
+
+interface MCPAuthorization {
+  // Where the consent page sent the browser back to.
+  readonly callback: URL;
+  readonly code: string;
+  readonly verifier: string;
+}
+
+/**
+ * Drives one authorization through a running MCP HTTP server the way a
+ * 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.
+ */
+export async function runMCPAuthorization(
+  server: MCPAuthorizationServer,
+  request: MCPAuthorizationRequest,
+): Promise<MCPAuthorization> {
+  const verifier = `test-verifier-${crypto.randomUUID()}`;
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+
+  const authorize = new URL(`${server.url}/oauth2/authorize`);
+
+  authorize.search = new URLSearchParams({
+    response_type: 'code',
+    client_id: request.clientID,
+    redirect_uri: request.redirectURI,
+    scope: request.scope,
+    state: 'state-1',
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    resource: `${server.origin}/mcp`,
+  }).toString();
+
+  const authorized = await fetch(authorize, { redirect: 'manual' });
+
+  const login = new URL(authorized.headers.get('location') ?? '/', server.url);
+
+  if (login.pathname !== '/login') {
+    throw new Error(`authorization did not reach the login page: ${login.href}`);
+  }
+
+  const approvalCode = /code (?<code>\w{4}-\w{4})/.exec(server.approvals.at(-1) ?? '')?.groups?.[
+    'code'
+  ];
+
+  if (approvalCode === undefined) {
+    throw new Error('the server printed no approval code');
+  }
+
+  const signedIn = await fetch(`${server.url}/login`, {
+    method: 'POST',
+    redirect: 'manual',
+    headers: { origin: server.url, 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ oauth_query: login.search.slice(1), code: approvalCode }),
+  });
+
+  const consent = new URL(signedIn.headers.get('location') ?? '/', server.url);
+
+  const cookie = signedIn.headers
+    .getSetCookie()
+    .map((line) => line.split(';')[0])
+    .join('; ');
+
+  if (consent.pathname !== '/consent') {
+    throw new Error(`the approval code did not reach the consent page: ${consent.href}`);
+  }
+
+  const form = new URLSearchParams({ oauth_query: consent.search.slice(1), decision: 'approve' });
+
+  for (const scope of request.ticked) {
+    form.append('scope', scope);
+  }
+
+  const consented = await fetch(`${server.url}/consent`, {
+    method: 'POST',
+    redirect: 'manual',
+    headers: { origin: server.url, cookie, 'content-type': 'application/x-www-form-urlencoded' },
+    body: form,
+  });
+
+  const location = consented.headers.get('location');
+
+  if (location === null) {
+    throw new Error(`consent did not redirect: ${consented.status} ${await consented.text()}`);
+  }
+
+  const callback = new URL(location);
+
+  const code = callback.searchParams.get('code');
+
+  if (code === null) {
+    throw new Error(`the consent redirect holds no authorization code: ${location}`);
+  }
+
+  return { callback, code, verifier };
+}

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

@@ -0,0 +1,110 @@
+import { appendFileSync } from 'node:fs';
+import { buildAgentAdapters } from '../agents/build-agent-adapters';
+import { startClaudeHeadlessRun } from '../agents/start-claude-headless-run';
+import { buildExecutionTargets } from '../daemon/build-execution-targets';
+import { startDaemon } from '../daemon/daemon';
+import { collectZoxideDirs } from '../shared/collect-zoxide-dirs';
+import {
+  daemonPidFile,
+  daemonSocketPath,
+  dbFile,
+  eventsSocketPath,
+  loadConfig,
+  socketPath,
+} from '../shared/config';
+import { getBuild } from '../shared/get-build';
+import { resolveHomeDir } from '../shared/resolve-home-dir';
+import { buildSources } from '../sources/build-sources';
+import { collectBuiltinSources } from '../sources/collect-builtin-sources';
+import type { SourceProvider } from '../sources/types';
+
+/**
+ * Runs a daemon for the e2e suite, composed as `atc daemon` composes its
+ * own from the config, the home, and the runtime directory, but with the
+ * sources `ATC_TEST_SOURCES` selects: `fixture` offers the built-in sources
+ * and then a source of git repositories that lists the one repository at
+ * `ATC_TEST_FIXTURE_URL`, and `none` offers no sources, as a daemon from
+ * before sources does. The fixture source reads `pick upstream` as that
+ * repository and `in <scope>` as a scope to list, and appends each listing
+ * it serves to `ATC_TEST_SOURCE_LOG` when that is set. It prints `up` once it listens, and SIGTERM stops
+ * it.
+ */
+async function main() {
+  const config = loadConfig();
+  const adapters = buildAgentAdapters(config, startClaudeHeadlessRun);
+
+  const builtin = buildSources(
+    collectBuiltinSources({
+      roots: config.dirs.roots,
+      githubOwner: config.workspaces.githubOwner,
+      ghBin: 'gh',
+      homeDir: resolveHomeDir(),
+      collectZoxideDirs,
+    }),
+    config.workspaces.sources,
+  ).sources;
+
+  const fixtureURL = process.env['ATC_TEST_FIXTURE_URL'] ?? '';
+  const listLog = process.env['ATC_TEST_SOURCE_LOG'];
+
+  const fixture: SourceProvider = {
+    id: 'fixture',
+    label: 'fixture repository',
+    kind: 'git',
+    list: (query, request) => {
+      if (listLog !== undefined) {
+        appendFileSync(
+          listLog,
+          `${JSON.stringify({ scope: query.scope ?? null, target: request.target })}\n`,
+        );
+      }
+
+      const label = query.scope === undefined ? 'upstream' : `${query.scope}/upstream`;
+
+      return Promise.resolve({
+        candidates: [{ label, detail: 'fixture', pick: { kind: 'git', url: fixtureURL } }],
+        scope: query.scope ?? null,
+      });
+    },
+    interpret: (input) => {
+      const text = input.trim();
+
+      if (text === 'pick upstream') {
+        return Promise.resolve({ kind: 'git', url: fixtureURL });
+      }
+
+      if (text.startsWith('in ')) {
+        return Promise.resolve({ kind: 'browse', scope: text.slice(3) });
+      }
+
+      return Promise.resolve({ kind: 'none' });
+    },
+  };
+
+  const handle = await startDaemon({
+    socketPath: daemonSocketPath,
+    reporterSocketPath: socketPath,
+    eventsSocketPath,
+    build: getBuild(),
+    adapters,
+    defaultAgent: config.defaultAgent,
+    dbPath: dbFile,
+    pidPath: daemonPidFile,
+    targets: buildExecutionTargets(config.targets).targets,
+    defaultTarget: config.defaultTarget,
+    sources: process.env['ATC_TEST_SOURCES'] === 'none' ? [] : [...builtin, fixture],
+    gitTransports: config.workspaces.gitTransports,
+  });
+
+  process.stdout.write('up\n');
+
+  process.on('SIGTERM', () => {
+    void (async () => {
+      await handle.stop();
+
+      process.exit(0);
+    })();
+  });
+}
+
+await main();

package/src/test-utils/setup-fake-systemd.ts

@@ -0,0 +1,125 @@
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface FakeSystemd {
+  // The directory that holds the fake `systemctl` and `systemd-run`, to put
+  // first on the PATH of every process that could reach a real one.
+  readonly binDir: string;
+
+  // The directory `ATC_PROC_ROOT` points at, where `placeInUnit` writes.
+  readonly procRoot: string;
+
+  // The arguments of every `systemctl` call, one line per call.
+  readonly readSystemctlCalls: () => string[];
+
+  // The arguments of every `systemd-run` call, one line per call.
+  readonly readSystemdRunCalls: () => string[];
+
+  // Makes `systemctl show -p MainPID` print this pid.
+  readonly writeMainPID: (pid: number) => void;
+
+  // Places the pid in a user service of the given name, as the cgroup of a
+  // daemon run by a user manager reads.
+  readonly placeInUnit: (pid: number, unit: string) => void;
+
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * Writes a fake `systemctl` and `systemd-run` that touch no service
+ * manager. Without a MainPID, `systemctl show -p MainPID` prints a pid no
+ * process holds, so no daemon is ever a unit's main process. With
+ * `writeMainPID`, `systemctl restart` stops that pid with SIGTERM and starts
+ * `atcCommand daemon` in the background. `systemd-run` runs the command after
+ * `--` in the background with only the `--setenv` variables, as a transient
+ * unit sees them, and appends its output to the `StandardOutput=append:`
+ * file. Every call is logged.
+ */
+export function setupFakeSystemd(atcCommand: readonly string[]): FakeSystemd {
+  const root = mkdtempSync(join(tmpdir(), 'atc-fake-systemd-'));
+  const binDir = join(root, 'bin');
+  const procRoot = join(root, 'proc');
+  const atcLine = atcCommand.map((part) => `"${part}"`).join(' ');
+
+  mkdirSync(binDir);
+  mkdirSync(procRoot);
+
+  writeFileSync(
+    join(binDir, 'systemctl'),
+    `#!/usr/bin/env bash
+echo "$*" >> "${root}/systemctl.log"
+case "$*" in
+  *"show -p MainPID"*)
+    if [ -f "${root}/mainpid" ]; then cat "${root}/mainpid"; else echo 999999; fi
+    ;;
+  *"show -p ExecStart"*)
+    echo "{ path=/fake/bin/atc ; argv[]=/fake/bin/atc daemon ; }"
+    ;;
+  *"restart "*)
+    if [ -f "${root}/mainpid" ]; then
+      pid="$(cat "${root}/mainpid")"
+      kill "$pid" 2>/dev/null
+      for _ in $(seq 100); do kill -0 "$pid" 2>/dev/null || break; sleep 0.1; done
+      ${atcLine} daemon > /dev/null 2>&1 < /dev/null &
+    fi
+    ;;
+esac
+exit 0
+`,
+  );
+
+  writeFileSync(
+    join(binDir, 'systemd-run'),
+    `#!/usr/bin/env bash
+echo "$*" >> "${root}/systemd-run.log"
+envargs=()
+log=/dev/null
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --setenv=*) envargs+=("\${1#--setenv=}"); shift ;;
+    --property=StandardOutput=append:*) log="\${1#--property=StandardOutput=append:}"; shift ;;
+    --unit) shift 2 ;;
+    --) shift; break ;;
+    *) shift ;;
+  esac
+done
+env -i "\${envargs[@]}" "$@" >> "$log" 2>&1 < /dev/null &
+exit 0
+`,
+  );
+
+  chmodSync(join(binDir, 'systemctl'), 0o755);
+  chmodSync(join(binDir, 'systemd-run'), 0o755);
+
+  const readLines = (name: string) => {
+    try {
+      return readFileSync(join(root, name), 'utf8')
+        .split('\n')
+        .filter((line) => line !== '');
+    } catch {
+      return [];
+    }
+  };
+
+  return {
+    binDir,
+    procRoot,
+    readSystemctlCalls: () => readLines('systemctl.log'),
+    readSystemdRunCalls: () => readLines('systemd-run.log'),
+    writeMainPID: (pid) => {
+      writeFileSync(join(root, 'mainpid'), String(pid));
+    },
+    placeInUnit: (pid, unit) => {
+      mkdirSync(join(procRoot, String(pid)), { recursive: true });
+
+      writeFileSync(
+        join(procRoot, String(pid), 'cgroup'),
+        `0::/user.slice/user-${process.getuid?.() ?? 0}.slice/user@${process.getuid?.() ?? 0}.service/app.slice/${unit}\n`,
+      );
+    },
+    [Symbol.dispose]: () => {
+      rmSync(root, { recursive: true, force: true });
+    },
+  };
+}