@zgeoff/atc 3.3.1 → 3.4.1

package/src/gateway.ts

@@ -1,183 +1,6 @@
-import { join } from 'node:path';
-import { defineCommand, runMain } from 'citty';
-import pkg from '../package.json';
-import { collectRedirectURIs } from './collect-redirect-uris';
-import { parseGatewayStateDir } from './parse-gateway-state-dir';
-import { parsePort } from './parse-port';
-
-// The flag every subcommand takes for the directory holding `gateway.db` and
-// `mcp-auth.db`.
-const STATE_DIR_ARG = {
-  'state-dir': {
-    type: 'string',
-    description: 'Directory for gateway.db and mcp-auth.db (default $ATC_GATEWAY_STATE_DIR)',
-  },
-} as const;
-
-// Every flag a subcommand declares, so a flag in any position, or one no
-// subcommand declares, is caught before a subcommand runs.
-const GATEWAY_FLAGS = {
-  values: new Set(['host', 'port', 'public-url', 'registry', 'redirect-uri', 'state-dir']),
-  switches: new Set(['help', 'h', 'version']),
-};
-
-// The state directory comes from the whole command line, since the argument
-// parser hands a subcommand only the arguments after its name.
-const parsedStateDir = parseGatewayStateDir(process.argv.slice(2), process.env, GATEWAY_FLAGS);
-
-if (!parsedStateDir.ok) {
-  console.error(`atc-gateway: ${parsedStateDir.message}`);
-  process.exit(1);
-}
-
-const stateDir = parsedStateDir.stateDir;
-const NO_STATE_DIR = 'atc-gateway: give --state-dir or set ATC_GATEWAY_STATE_DIR';
+import { runGatewayCLI } from './run-gateway-cli';
 
 // atc-gateway entry: serves the MCP tools over HTTP for the daemons a
 // registry lists, and manages the clients that may connect to it. It loads
 // nothing that starts a daemon or a session on this machine.
-const main = defineCommand({
-  meta: {
-    name: 'atc-gateway',
-    version: pkg.version,
-    description: 'Serve the atc MCP tools over HTTP for the daemons a registry lists',
-  },
-
-  // Declared at every level, so the argument parser reads `--state-dir <dir>`
-  // before a subcommand as a flag and its value, not as a subcommand name.
-  args: STATE_DIR_ARG,
-  subCommands: {
-    serve: () =>
-      defineCommand({
-        meta: { name: 'serve', description: 'Serve MCP over HTTP behind OAuth' },
-        args: {
-          host: { type: 'string', description: 'Address to bind (default 127.0.0.1)' },
-          port: { type: 'string', description: 'Port to listen on (default 8414)' },
-          'public-url': {
-            type: 'string',
-            required: true,
-            description: 'Origin clients reach the gateway at, such as https://mcp.example.com',
-          },
-          registry: { type: 'string', required: true, description: 'The registry JSON file' },
-          ...STATE_DIR_ARG,
-        },
-        async run(ctx) {
-          const port = ctx.args.port === undefined ? null : parsePort(ctx.args.port);
-
-          if (port !== null && !port.ok) {
-            console.error(`atc-gateway: ${port.message}`);
-            process.exit(1);
-          }
-
-          if (stateDir === null) {
-            console.error(NO_STATE_DIR);
-            process.exit(1);
-          }
-
-          const gateway = await import('./run-gateway');
-
-          await gateway.runGateway(`atc-gateway/${pkg.version}`, {
-            host: ctx.args.host ?? '127.0.0.1',
-            port: port === null ? 8414 : port.port,
-            publicURL: ctx.args['public-url'],
-            registryPath: ctx.args.registry,
-            stateDir,
-          });
-        },
-      }),
-    clients: () =>
-      defineCommand({
-        meta: {
-          name: 'clients',
-          description: 'List, add, or remove the clients that may connect to the gateway',
-        },
-        args: STATE_DIR_ARG,
-        default: 'list',
-        subCommands: {
-          list: () =>
-            defineCommand({
-              meta: { name: 'list', description: 'List the clients', hidden: true },
-              args: STATE_DIR_ARG,
-              async run() {
-                if (stateDir === null) {
-                  console.error(NO_STATE_DIR);
-                  process.exit(1);
-                }
-
-                const clients = await import('./clients');
-
-                await clients.runClients(
-                  { kind: 'list' },
-                  {
-                    dbPath: join(stateDir, 'mcp-auth.db'),
-                    command: 'atc-gateway clients',
-                  },
-                );
-              },
-            }),
-          add: () =>
-            defineCommand({
-              meta: { name: 'add', description: 'Add a client and print its client ID' },
-              args: {
-                name: { type: 'positional', required: true, description: 'The client name' },
-                'redirect-uri': {
-                  type: 'string',
-                  required: true,
-                  description: 'A redirect URI the client returns to; repeat for more',
-                },
-                ...STATE_DIR_ARG,
-              },
-              async run(ctx) {
-                if (stateDir === null) {
-                  console.error(NO_STATE_DIR);
-                  process.exit(1);
-                }
-
-                const clients = await import('./clients');
-
-                await clients.runClients(
-                  {
-                    kind: 'add',
-                    name: ctx.args.name,
-                    redirectURIs: collectRedirectURIs(ctx.rawArgs),
-                  },
-                  {
-                    dbPath: join(stateDir, 'mcp-auth.db'),
-                    command: 'atc-gateway clients',
-                  },
-                );
-              },
-            }),
-          remove: () =>
-            defineCommand({
-              meta: {
-                name: 'remove',
-                description: 'Remove a client and revoke every grant it holds',
-              },
-              args: {
-                id: { type: 'positional', required: true, description: 'The client ID' },
-                ...STATE_DIR_ARG,
-              },
-              async run(ctx) {
-                if (stateDir === null) {
-                  console.error(NO_STATE_DIR);
-                  process.exit(1);
-                }
-
-                const clients = await import('./clients');
-
-                await clients.runClients(
-                  { kind: 'remove', clientID: ctx.args.id },
-                  {
-                    dbPath: join(stateDir, 'mcp-auth.db'),
-                    command: 'atc-gateway clients',
-                  },
-                );
-              },
-            }),
-        },
-      }),
-  },
-});
-
-await runMain(main);
+await runGatewayCLI(process.argv.slice(2), process.env);

package/src/grants.ts

@@ -1,33 +1,58 @@
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { collectGrants } from './mcp/collect-grants';
 import { openMCPAuth } from './mcp/open-mcp-auth';
 import { revokeGrant } from './mcp/revoke-grant';
-import { mcpAuthDBFile, stateDir } from './shared/config';
+import { mcpAuthDBFile } from './shared/config';
+
+// Where the command's lines and its exit code go: the console and the
+// process by default.
+interface GrantsIO {
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+  readonly setExitCode: (code: number) => void;
+}
+
+const PROCESS_IO: GrantsIO = {
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+  setExitCode: (code) => {
+    process.exitCode = code;
+  },
+};
 
 /**
  * Runs `atc grants`: lists the grants clients of `atc mcp --http` hold, or
  * revokes one. A revoked grant's tokens stop working at once, and its client
  * has to go through approval again. It opens the authorization server's
- * database directly, so it works whether or not the server is running.
+ * database at `dbPath` directly, so it works whether or not the server is
+ * running. Revoking a grant that does not exist sets exit code 1.
  */
-export async function runGrants(revoke: string | null): Promise<void> {
-  mkdirSync(stateDir, { recursive: true });
+export async function runGrants(
+  revoke: string | null,
+  dbPath: string = mcpAuthDBFile,
+  io: GrantsIO = PROCESS_IO,
+): Promise<void> {
+  mkdirSync(dirname(dbPath), { recursive: true });
 
-  const store = await openMCPAuth({ dbPath: mcpAuthDBFile, origin: null });
+  const store = await openMCPAuth({ dbPath, origin: null });
 
   try {
     if (revoke !== null) {
       const revoked = await revokeGrant(store.db, revoke);
 
       if (!revoked) {
-        console.error(`atc grants: no grant has the ID '${revoke}'`);
-
-        process.exitCode = 1;
+        io.printError(`atc grants: no grant has the ID '${revoke}'`);
+        io.setExitCode(1);
 
         return;
       }
 
-      console.log(`Revoked grant ${revoke}`);
+      io.print(`Revoked grant ${revoke}`);
 
       return;
     }
@@ -35,13 +60,13 @@ export async function runGrants(revoke: string | null): Promise<void> {
     const grants = await collectGrants(store.db);
 
     if (grants.length === 0) {
-      console.log('No grants.');
+      io.print('No grants.');
 
       return;
     }
 
     for (const grant of grants) {
-      console.log(
+      io.print(
         `${grant.grantID}  ${grant.clientName}  ${grant.scopes.join(',')}  last used ${grant.lastUsedAt ?? 'never'}`,
       );
     }

package/src/hook-report.ts

@@ -1,6 +1,20 @@
 import { normalizeHookEventName } from './agents/normalize-hook-event';
 import { isRecord, sendReport } from './shared/report';
 
+// Where the reporter reads its event and how it exits: stdin and the
+// process by default.
+interface HookReportIO {
+  readonly readStdin: () => Promise<string>;
+  readonly exit: (code: number) => void;
+}
+
+const PROCESS_IO: HookReportIO = {
+  readStdin: () => new Response(Bun.stdin.stream()).text(),
+  exit: (code) => {
+    process.exit(code);
+  },
+};
+
 /**
  * Runs as a hook inside wrangled sessions. Reads the hook event from stdin
  * (Claude snake_case keys or Grok camelCase keys) and forwards a PascalCase
@@ -9,12 +23,12 @@ import { isRecord, sendReport } from './shared/report';
  * session's own. Always exits 0 so it never blocks the session it reports
  * on.
  */
-export async function runHookReport(agent: string): Promise<void> {
+export async function runHookReport(agent: string, io: HookReportIO = PROCESS_IO): Promise<void> {
   const sock = process.env['ATC_SOCKET'];
   const atcId = process.env['ATC_SESSION_ID'];
 
   if (sock !== undefined && sock !== '' && atcId !== undefined && atcId !== '') {
-    const raw = await new Response(Bun.stdin.stream()).text();
+    const raw = await io.readStdin();
 
     let payload: Record<string, unknown> = {};
 
@@ -33,5 +47,5 @@ export async function runHookReport(agent: string): Promise<void> {
     await sendReport(sock, line, 2000);
   }
 
-  process.exit(0);
+  io.exit(0);
 }

package/src/mcp/read-report-texts.ts

@@ -1,4 +1,6 @@
 import { isRecord } from '../shared/report';
+import { systemClock } from '../shared/system-clock';
+import type { Clock } from '../shared/system-clock';
 import type { FleetCaller } from './types';
 
 // The most report text one events page carries, in UTF-8 bytes: as much as
@@ -26,33 +28,34 @@ type ReportRead = Readonly<Record<string, unknown>>;
  * deadline: it then holds the cursor of the last event it keeps and `more`
  * true, so the next read starts at that report. Every other field of the
  * page, such as a gateway's `unavailable` and `truncated`, passes through
- * unchanged.
+ * unchanged. The deadline runs on `clock`, the wall clock by default.
  */
 export async function readReportTexts(
   caller: FleetCaller,
   page: Readonly<Record<string, unknown>>,
   deadlineMs: number = REPORT_READ_DEADLINE_MS,
+  clock: Clock = systemClock,
 ): Promise<Readonly<Record<string, unknown>>> {
   const raw: unknown = page['events'];
   const events = Array.isArray(raw) ? raw.filter((event) => isRecord(event)) : [];
-  const endsAt = Date.now() + deadlineMs;
+  const endsAt = clock.now() + deadlineMs;
   const timeout = Promise.withResolvers<ReportRead>();
 
-  const timer = setTimeout(() => {
+  const cancel = clock.schedule(() => {
     timeout.resolve({
       textError: `timeout: the report text did not arrive within ${deadlineMs} ms`,
     });
   }, deadlineMs);
 
-  const read = await readPageReports(caller, page, events, endsAt, timeout.promise);
+  const read = await readPageReports(caller, page, events, endsAt, timeout.promise, clock);
 
-  clearTimeout(timer);
+  cancel();
 
   return read;
 }
 
 // The page with its reports read, one at a time, until the budget or the
-// deadline at `endsAt` stops it. A read still out when `timeout` settles
+// deadline at `endsAt` on `clock` stops it. A read still out when `timeout` settles
 // gives way to the timeout it settles with.
 async function readPageReports(
   caller: FleetCaller,
@@ -60,6 +63,7 @@ async function readPageReports(
   events: readonly Readonly<Record<string, unknown>>[],
   endsAt: number,
   timeout: Readonly<Promise<ReportRead>>,
+  clock: Clock,
 ): Promise<Readonly<Record<string, unknown>>> {
   const kept: Readonly<Record<string, unknown>>[] = [];
   let used = 0;
@@ -72,7 +76,7 @@ async function readPageReports(
 
     const last = kept.at(-1);
 
-    if (last !== undefined && Date.now() >= endsAt) {
+    if (last !== undefined && clock.now() >= endsAt) {
       return { ...page, events: kept, cursor: last['cursor'], more: true };
     }
 

package/src/mcp/start-mcp-http-server.ts

@@ -38,6 +38,10 @@ interface MCPHTTPServerOptions {
 
   // Serves `/healthz` and `/readyz` for an orchestrator's probes.
   readonly probes?: boolean;
+
+  // The time pending approvals and the limit on approval starts run on, in
+  // epoch milliseconds; the wall clock when unset.
+  readonly now?: () => number;
 }
 
 /**
@@ -171,7 +175,7 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
       origin,
       resource: `${origin}/mcp`,
       store,
-      approvals: new ApprovalState(600_000, () => Date.now()),
+      approvals: new ApprovalState(600_000, options.now ?? (() => Date.now())),
       printApproval: options.printApproval,
     },
   };

package/src/mcp-http-server.ts

@@ -1,11 +1,14 @@
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { bootDaemonClient } from './client/boot-daemon';
+import type { DaemonBoot, DaemonPaths } from './client/boot-daemon';
 import { DaemonClient } from './client/daemon-client';
 import { collectClients } from './mcp/collect-clients';
 import { openMCPAuth } from './mcp/open-mcp-auth';
 import { ReconnectingCaller } from './mcp/reconnecting-caller';
 import { startMCPHTTPServer } from './mcp/start-mcp-http-server';
-import { mcpAuthDBFile, stateDir } from './shared/config';
+import type { MCPHTTPConfig } from './shared/collect-mcp-http-config';
+import { mcpAuthDBFile } from './shared/config';
 import { loadMCPHTTPConfig } from './shared/load-mcp-http-config';
 
 interface MCPHTTPFlags {
@@ -15,6 +18,41 @@ interface MCPHTTPFlags {
   readonly waitForDaemon: boolean;
 }
 
+// What the server reaches outside itself, the process's own by default: its
+// config, the authorization database, the files that locate the daemon it
+// boots or waits for (null for the process's own, the only ones at which it
+// starts a daemon), the console, the exit, and the signal listeners that
+// stop it.
+interface MCPHTTPServerIO {
+  readonly loadConfig: () => MCPHTTPConfig;
+  readonly dbPath: string;
+  readonly daemonPaths: DaemonPaths | null;
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+  readonly exit: (code: number) => void;
+  readonly registerSignal: (signal: 'SIGINT' | 'SIGTERM', listener: () => Promise<void>) => void;
+}
+
+const PROCESS_IO: MCPHTTPServerIO = {
+  loadConfig: loadMCPHTTPConfig,
+  dbPath: mcpAuthDBFile,
+  daemonPaths: null,
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+  exit: (code) => {
+    process.exit(code);
+  },
+  registerSignal: (signal, listener) => {
+    process.on(signal, () => {
+      void listener();
+    });
+  },
+};
+
 // How long `--wait-for-daemon` waits before it exits. A service manager's
 // restart covers a daemon that takes longer.
 const DAEMON_WAIT_MS = 30_000;
@@ -25,19 +63,41 @@ const DAEMON_WAIT_MS = 30_000;
  * serves MCP over HTTP until Ctrl-C. Approval codes print here, so the
  * terminal running it is where the operator approves a client.
  */
-export async function runMCPHTTPServer(build: string, flags: MCPHTTPFlags): Promise<void> {
-  const config = loadMCPHTTPConfig();
-  const bootOptions = flags.waitForDaemon ? { waitForDaemonMs: DAEMON_WAIT_MS } : {};
-
-  const boot = await bootDaemonClient(bootOptions).catch((error: unknown) => {
-    console.error(`atc mcp --http: ${error instanceof Error ? error.message : String(error)}`);
-
-    return process.exit(1);
-  });
+export async function runMCPHTTPServer(
+  build: string,
+  flags: MCPHTTPFlags,
+  io: MCPHTTPServerIO = PROCESS_IO,
+): Promise<void> {
+  const config = io.loadConfig();
+
+  const waitOptions = flags.waitForDaemon
+    ? {
+        waitForDaemonMs: DAEMON_WAIT_MS,
+        onWaitForDaemon: () => {
+          io.printError(
+            `atc mcp --http: no daemon answers yet; waiting up to ${DAEMON_WAIT_MS / 1000}s for one, without starting it`,
+          );
+        },
+      }
+    : {};
+
+  const bootOptions =
+    io.daemonPaths === null ? waitOptions : { ...waitOptions, paths: io.daemonPaths };
+
+  let boot: DaemonBoot;
+
+  try {
+    boot = await bootDaemonClient(bootOptions);
+  } catch (error) {
+    io.printError(`atc mcp --http: ${error instanceof Error ? error.message : String(error)}`);
+    io.exit(1);
+
+    return;
+  }
 
   boot.client.stop();
 
-  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(dirname(io.dbPath), { recursive: true });
 
   const caller = new ReconnectingCaller(boot.socketPath, build, (path) => DaemonClient.open(path));
 
@@ -48,45 +108,41 @@ export async function runMCPHTTPServer(build: string, flags: MCPHTTPFlags): Prom
     port: flags.port ?? config.port,
     publicURL: flags.publicURL ?? config.publicURL,
     allowedHosts: config.allowedHosts,
-    dbPath: mcpAuthDBFile,
+    dbPath: io.dbPath,
 
     // The line carries a client's name, so control and format characters
     // are dropped before it reaches the operator's terminal.
     printApproval: (line) => {
-      console.log(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
+      io.print(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
     },
 
     // Request lines go to stderr, so stdout keeps the approval lines alone.
     printRequest: (line) => {
-      console.error(line);
+      io.printError(line);
     },
   });
 
-  console.log(`atc mcp --http: serving ${server.origin}/mcp, listening on ${server.listening}`);
+  // The handlers go in before the serving line, so a signal sent once the
+  // line appears always finds them.
+  const stopServing = async () => {
+    await server.stop();
+    await caller.stop();
+
+    io.exit(0);
+  };
 
-  const admin = await openMCPAuth({ dbPath: mcpAuthDBFile, origin: null });
+  io.registerSignal('SIGINT', stopServing);
+  io.registerSignal('SIGTERM', stopServing);
+  io.print(`atc mcp --http: serving ${server.origin}/mcp, listening on ${server.listening}`);
+
+  const admin = await openMCPAuth({ dbPath: io.dbPath, origin: null });
   const clients = await collectClients(admin.db);
 
   await admin.close();
 
   if (clients.length === 0) {
-    console.log(
+    io.print(
       'No clients can connect yet. Add one with: atc clients add <name> --redirect-uri <uri>',
     );
   }
-
-  const stopServing = async () => {
-    await server.stop();
-    await caller.stop();
-
-    process.exit(0);
-  };
-
-  process.on('SIGINT', () => {
-    void stopServing();
-  });
-
-  process.on('SIGTERM', () => {
-    void stopServing();
-  });
 }

package/src/report.ts

@@ -16,6 +16,20 @@ interface ReportOptions {
   readonly turn: string;
 }
 
+// Where the reporter reads its text and how it exits: stdin and the process
+// by default.
+interface ReportIO {
+  readonly readStdin: () => Promise<string>;
+  readonly exit: (code: number) => void;
+}
+
+const PROCESS_IO: ReportIO = {
+  readStdin: () => new Response(Bun.stdin.stream()).text(),
+  exit: (code) => {
+    process.exit(code);
+  },
+};
+
 /**
  * Runs inside wrangled sessions: reads stdin verbatim and forwards it to the
  * atc socket as a Report envelope of the given kind. An `answered` report
@@ -26,7 +40,11 @@ interface ReportOptions {
  * given. Inside a remote host it goes to the session bridge instead. Always
  * exits 0 so it never blocks the session it reports on.
  */
-export async function runReport(kind: string, options: ReportOptions): Promise<void> {
+export async function runReport(
+  kind: string,
+  options: ReportOptions,
+  io: ReportIO = PROCESS_IO,
+): Promise<void> {
   try {
     const sock = process.env['ATC_SOCKET'];
     const atcId = process.env['ATC_SESSION_ID'];
@@ -38,7 +56,7 @@ export async function runReport(kind: string, options: ReportOptions): Promise<v
       atcId !== '' &&
       REPORT_KINDS.some((known) => known === kind)
     ) {
-      const stdin = await new Response(Bun.stdin.stream()).text();
+      const stdin = await io.readStdin();
 
       const payload = buildReportPayload(kind, options, stdin);
 
@@ -52,7 +70,7 @@ export async function runReport(kind: string, options: ReportOptions): Promise<v
     }
   } catch {}
 
-  process.exit(0);
+  io.exit(0);
 }
 
 // Inside a remote host, a report goes to the session bridge under an id of