@zgeoff/atc 3.3.1 → 3.4.1

package/src/run-bridge-tap.ts

@@ -29,6 +29,24 @@ const SEEN_LIMIT = 10_000;
 // opened the tap.
 type TapEnd = 'closed' | 'refused' | 'lost' | 'unreachable';
 
+// Where the tap prints and how it exits: stdout, stderr, and the process by
+// default.
+interface BridgeTapIO {
+  readonly writeStdout: (text: string) => Promise<unknown>;
+  readonly printError: (line: string) => void;
+  readonly exit: (code: number) => void;
+}
+
+const PROCESS_IO: BridgeTapIO = {
+  writeStdout: (text) => Bun.write(Bun.stdout, text),
+  printError: (line) => {
+    console.error(line);
+  },
+  exit: (code) => {
+    process.exit(code);
+  },
+};
+
 /**
  * Streams the session's inbox to stdout from inside a remote host, through
  * the session bridge at the given socket. It prints each message once as
@@ -40,21 +58,29 @@ type TapEnd = 'closed' | 'refused' | 'lost' | 'unreachable';
  * outbox still holds. Exits 0 once the inbox closes and 1 when the bridge
  * refuses the tap.
  */
-export async function runBridgeTap(socketPath: string, outbox: string): Promise<void> {
+export async function runBridgeTap(
+  socketPath: string,
+  outbox: string,
+  io: BridgeTapIO = PROCESS_IO,
+): Promise<void> {
   const seen = new Set<string>();
 
   let wait = FIRST_RETRY_MS;
 
   for (;;) {
-    const end = await runTapConnection(socketPath, outbox, seen);
+    const end = await runTapConnection(socketPath, outbox, seen, io);
 
     if (end === 'closed') {
-      process.exit(0);
+      io.exit(0);
+
+      return;
     }
 
     if (end === 'refused') {
-      console.error('atc tap: the session bridge refused the tap');
-      process.exit(1);
+      io.printError('atc tap: the session bridge refused the tap');
+      io.exit(1);
+
+      return;
     }
 
     if (end === 'lost') {
@@ -73,6 +99,7 @@ async function runTapConnection(
 
   // oxlint-disable-next-line prefer-readonly-parameter-types -- the ids the tap printed, which every connection adds to
   seen: Set<string>,
+  io: BridgeTapIO,
 ): Promise<TapEnd> {
   const ended = Promise.withResolvers<TapEnd>();
   let opened = false;
@@ -139,9 +166,11 @@ async function runTapConnection(
         const printed = `${JSON.stringify({ id: message.message, from: message.from, text: message.text, sentAt: message.sentAt })}\n`;
 
         try {
-          await Bun.write(Bun.stdout, printed);
+          await io.writeStdout(printed);
         } catch {
-          process.exit(1);
+          io.exit(1);
+
+          return;
         }
 
         updateSeenIDs(seen, message.message);

package/src/run-config-migrate.ts

@@ -1,19 +1,43 @@
 import { copyFileSync, readFileSync, writeFileSync } from 'node:fs';
 import { buildMigratedConfig } from './build-migrated-config';
 
+// Where the command's output goes, the console by default: text printed as
+// it is, and lines printed to stdout or stderr.
+interface ConfigMigrateIO {
+  readonly printText: (text: string) => void;
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+}
+
+const CONSOLE_IO: ConfigMigrateIO = {
+  printText: (text) => {
+    process.stdout.write(text);
+  },
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+};
+
 /**
  * Runs `atc config migrate`: prints the config.json rewritten around
  * `agents`, or with `write` copies the file to a timestamped backup beside it
  * and rewrites it in place. Returns the exit code. Notes and problems go to
  * stderr and name keys and paths, never values.
  */
-export function runConfigMigrate(file: string, write: boolean): number {
+export function runConfigMigrate(
+  file: string,
+  write: boolean,
+  io: ConfigMigrateIO = CONSOLE_IO,
+): number {
   let text: string;
 
   try {
     text = readFileSync(file, 'utf8');
   } catch {
-    console.error(`atc config migrate: ${file} cannot be read`);
+    io.printError(`atc config migrate: ${file} cannot be read`);
 
     return 1;
   }
@@ -23,7 +47,7 @@ export function runConfigMigrate(file: string, write: boolean): number {
   try {
     raw = JSON.parse(text);
   } catch {
-    console.error(`atc config migrate: ${file} is not valid JSON`);
+    io.printError(`atc config migrate: ${file} is not valid JSON`);
 
     return 1;
   }
@@ -31,23 +55,23 @@ export function runConfigMigrate(file: string, write: boolean): number {
   const result = buildMigratedConfig(raw);
 
   if (result.kind === 'unusable') {
-    console.error(`atc config migrate: ${file}: ${result.detail}`);
+    io.printError(`atc config migrate: ${file}: ${result.detail}`);
 
     return 1;
   }
 
   if (result.kind === 'current') {
-    console.log('config.json already uses agents; nothing to migrate');
+    io.print('config.json already uses agents; nothing to migrate');
 
     return 0;
   }
 
   for (const note of result.notes) {
-    console.error(note);
+    io.printError(note);
   }
 
   if (!write) {
-    process.stdout.write(result.text);
+    io.printText(result.text);
 
     return 0;
   }
@@ -57,7 +81,7 @@ export function runConfigMigrate(file: string, write: boolean): number {
   try {
     copyFileSync(file, backup);
   } catch {
-    console.error(`atc config migrate: ${backup} cannot be written; ${file} is unchanged`);
+    io.printError(`atc config migrate: ${backup} cannot be written; ${file} is unchanged`);
 
     return 1;
   }
@@ -65,13 +89,13 @@ export function runConfigMigrate(file: string, write: boolean): number {
   try {
     writeFileSync(file, result.text);
   } catch {
-    console.error(`atc config migrate: ${file} cannot be written; the backup is at ${backup}`);
+    io.printError(`atc config migrate: ${file} cannot be written; the backup is at ${backup}`);
 
     return 1;
   }
 
-  console.log(`backup: ${backup}`);
-  console.log(`wrote: ${file}`);
+  io.print(`backup: ${backup}`);
+  io.print(`wrote: ${file}`);
 
   return 0;
 }

package/src/run-gateway-cli.ts

@@ -0,0 +1,327 @@
+import { join } from 'node:path';
+import { defineCommand, renderUsage, runCommand } from 'citty';
+import pkg from '../package.json';
+import type { runClients } from './clients';
+import { collectRedirectURIs } from './collect-redirect-uris';
+import { parseGatewayStateDir } from './parse-gateway-state-dir';
+import { parsePort } from './parse-port';
+import type { runGateway } from './run-gateway';
+
+// What the command line reaches outside itself, the process's own by
+// default: the subcommands it hands a parsed command to, the console, and
+// the exit.
+interface GatewayCLIIO {
+  readonly runGateway: (...args: Readonly<Parameters<typeof runGateway>>) => Promise<void>;
+  readonly runClients: (...args: Readonly<Parameters<typeof runClients>>) => Promise<void>;
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+  readonly exit: (code: number) => void;
+}
+
+const PROCESS_IO: GatewayCLIIO = {
+  runGateway: async (...args) => {
+    const gateway = await import('./run-gateway');
+
+    await gateway.runGateway(...args);
+  },
+  runClients: async (...args) => {
+    const clients = await import('./clients');
+
+    await clients.runClients(...args);
+  },
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+  exit: (code) => {
+    process.exit(code);
+  },
+};
+
+// 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']),
+};
+
+/**
+ * Runs the `atc-gateway` command line: reads the state directory from the
+ * whole of it, since the argument parser hands a subcommand only the
+ * arguments after its name, then parses the rest and runs the subcommand
+ * it names. A state directory that cannot be read prints the reason and
+ * exits 1 before any subcommand runs. `--help` anywhere prints the usage of
+ * the command it follows and exits 0, `--version` alone prints the version,
+ * and a command line the parser refuses prints that command's usage and
+ * the reason, then exits 1.
+ */
+export async function runGatewayCLI(
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+  io: GatewayCLIIO = PROCESS_IO,
+): Promise<void> {
+  const parsed = parseGatewayStateDir(argv, env, GATEWAY_FLAGS);
+
+  if (!parsed.ok) {
+    io.printError(`atc-gateway: ${parsed.message}`);
+    io.exit(1);
+
+    return;
+  }
+
+  const gateway = buildGatewayCommand(parsed.stateDir, io);
+  const renderNamedUsage = pickUsage(gateway.usages, argv);
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    const usage = await renderNamedUsage();
+
+    io.print(`${usage}\n`);
+    io.exit(0);
+
+    return;
+  }
+
+  if (argv.length === 1 && argv[0] === '--version') {
+    io.print(pkg.version);
+
+    return;
+  }
+
+  try {
+    await runCommand(gateway.command, { rawArgs: [...argv] });
+  } catch (error) {
+    if (isUsageError(error)) {
+      const usage = await renderNamedUsage();
+
+      io.print(`${usage}\n`);
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+
+    io.printError(message);
+    io.exit(1);
+  }
+}
+
+/**
+ * The usage renderer of the deepest command the command line names: each
+ * word past the flags and their values, joined to the ones before it, while
+ * the joined name has a usage.
+ */
+function pickUsage(
+  usages: Readonly<Record<string, () => Promise<string>>>,
+  argv: readonly string[],
+): () => Promise<string> {
+  let name = '';
+  let index = 0;
+
+  while (index < argv.length) {
+    const token = argv[index] ?? '';
+
+    index += 1;
+
+    if (token.startsWith('-')) {
+      // A value flag without `=` takes the next token as its value.
+      if (!token.includes('=') && GATEWAY_FLAGS.values.has(token.replace(/^-+/u, ''))) {
+        index += 1;
+      }
+
+      continue;
+    }
+
+    const longer = name === '' ? token : `${name} ${token}`;
+
+    if (usages[longer] === undefined) {
+      break;
+    }
+
+    name = longer;
+  }
+
+  return usages[name] ?? usages[''] ?? (() => Promise.resolve(''));
+}
+
+// The codes citty gives the errors it throws for a command line it refuses;
+// citty exports no error class to test against.
+const USAGE_ERROR_CODES: ReadonlySet<string> = new Set([
+  'EARG',
+  'E_UNKNOWN_COMMAND',
+  'E_NO_COMMAND',
+]);
+
+function isUsageError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    typeof error.code === 'string' &&
+    USAGE_ERROR_CODES.has(error.code)
+  );
+}
+
+// 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;
+
+const NO_STATE_DIR = 'atc-gateway: give --state-dir or set ATC_GATEWAY_STATE_DIR';
+
+const ROOT_META = {
+  name: 'atc-gateway',
+  version: pkg.version,
+  description: 'Serve the atc MCP tools over HTTP for the daemons a registry lists',
+};
+
+const CLIENTS_META = {
+  name: 'clients',
+  description: 'List, add, or remove the clients that may connect to the gateway',
+};
+
+/**
+ * The `atc-gateway` command tree, which serves the MCP tools over HTTP for
+ * the daemons a registry lists and manages the clients that may connect to
+ * it, and the usage of each command in it, keyed by the subcommand names
+ * that lead to it. Every subcommand takes the state directory read from
+ * the whole command line, or exits 1 without one.
+ */
+function buildGatewayCommand(stateDir: string | null, io: GatewayCLIIO) {
+  const 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) {
+        io.printError(`atc-gateway: ${port.message}`);
+        io.exit(1);
+
+        return;
+      }
+
+      if (stateDir === null) {
+        io.printError(NO_STATE_DIR);
+        io.exit(1);
+
+        return;
+      }
+
+      await io.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,
+      });
+    },
+  });
+
+  const list = defineCommand({
+    meta: { name: 'list', description: 'List the clients', hidden: true },
+    args: STATE_DIR_ARG,
+    async run() {
+      if (stateDir === null) {
+        io.printError(NO_STATE_DIR);
+        io.exit(1);
+
+        return;
+      }
+
+      await io.runClients(
+        { kind: 'list' },
+        { dbPath: join(stateDir, 'mcp-auth.db'), command: 'atc-gateway clients' },
+      );
+    },
+  });
+
+  const 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) {
+        io.printError(NO_STATE_DIR);
+        io.exit(1);
+
+        return;
+      }
+
+      await io.runClients(
+        { kind: 'add', name: ctx.args.name, redirectURIs: collectRedirectURIs(ctx.rawArgs) },
+        { dbPath: join(stateDir, 'mcp-auth.db'), command: 'atc-gateway clients' },
+      );
+    },
+  });
+
+  const 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) {
+        io.printError(NO_STATE_DIR);
+        io.exit(1);
+
+        return;
+      }
+
+      await io.runClients(
+        { kind: 'remove', clientID: ctx.args.id },
+        { dbPath: join(stateDir, 'mcp-auth.db'), command: 'atc-gateway clients' },
+      );
+    },
+  });
+
+  const clients = defineCommand({
+    meta: CLIENTS_META,
+    args: STATE_DIR_ARG,
+    default: 'list',
+    subCommands: { list, add, remove },
+  });
+
+  const command = defineCommand({
+    meta: ROOT_META,
+
+    // 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, clients },
+  });
+
+  // Usage names a command after its parent, so each renders under a parent
+  // holding only that parent's name.
+  return {
+    command,
+    usages: {
+      '': () => renderUsage(command),
+      serve: () => renderUsage(serve, { meta: ROOT_META }),
+      clients: () => renderUsage(clients, { meta: ROOT_META }),
+      'clients list': () => renderUsage(list, { meta: CLIENTS_META }),
+      'clients add': () => renderUsage(add, { meta: CLIENTS_META }),
+      'clients remove': () => renderUsage(remove, { meta: CLIENTS_META }),
+    },
+  };
+}

package/src/run-gateway.ts

@@ -14,6 +14,35 @@ interface GatewayFlags {
   readonly stateDir: string;
 }
 
+// What the gateway reaches outside itself, the process's own by default:
+// the environment its daemon tokens come from, the console, the exit, and
+// the signal listeners that stop it.
+interface GatewayIO {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  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: GatewayIO = {
+  env: process.env,
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+  exit: (code) => {
+    process.exit(code);
+  },
+  registerSignal: (signal, listener) => {
+    process.on(signal, () => {
+      void listener();
+    });
+  },
+};
+
 /**
  * Runs `atc-gateway` in the foreground: serves the MCP tools over HTTP for
  * the daemons the registry lists, routing every call to one of them over
@@ -23,15 +52,21 @@ interface GatewayFlags {
  * registry that fails to load, or a server that fails to start, prints the
  * reason and exits 1.
  */
-export async function runGateway(build: string, flags: GatewayFlags): Promise<void> {
-  const loaded = loadGatewayRegistry(flags.registryPath, process.env);
+export async function runGateway(
+  build: string,
+  flags: GatewayFlags,
+  io: GatewayIO = PROCESS_IO,
+): Promise<void> {
+  const loaded = loadGatewayRegistry(flags.registryPath, io.env);
 
   if (!loaded.ok) {
     for (const error of loaded.errors) {
-      console.error(`atc-gateway: ${error}`);
+      io.printError(`atc-gateway: ${error}`);
     }
 
-    process.exit(1);
+    io.exit(1);
+
+    return;
   }
 
   mkdirSync(flags.stateDir, { recursive: true });
@@ -59,35 +94,33 @@ export async function runGateway(build: string, flags: GatewayFlags): Promise<vo
       // The line carries a client's name, so control and format characters
       // are dropped before it reaches the log.
       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);
       },
     });
   } catch (error) {
     await gateway.stop();
 
-    console.error(`atc-gateway: ${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
-  }
+    io.printError(`atc-gateway: ${error instanceof Error ? error.message : String(error)}`);
+    io.exit(1);
 
-  console.log(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
+    return;
+  }
 
+  // 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 gateway.stop();
 
-    process.exit(0);
+    io.exit(0);
   };
 
-  process.on('SIGINT', () => {
-    void stopServing();
-  });
-
-  process.on('SIGTERM', () => {
-    void stopServing();
-  });
+  io.registerSignal('SIGINT', stopServing);
+  io.registerSignal('SIGTERM', stopServing);
+  io.print(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
 }

package/src/shared/build-atc-command.ts

@@ -4,10 +4,14 @@ import { isCompiledBinary } from './is-compiled-binary';
 /**
  * The argv that runs this build of atc with `args`: the compiled binary is
  * its own entry, and a source run is bun with the CLI entrypoint ahead of
- * the arguments.
+ * the arguments. `compiled` tells the two apart, and defaults to how this
+ * process runs.
  */
-export function buildATCCommand(args: readonly string[]): string[] {
-  return isCompiledBinary()
+export function buildATCCommand(
+  args: readonly string[],
+  compiled: boolean = isCompiledBinary(),
+): string[] {
+  return compiled
     ? [process.execPath, ...args]
     : [process.execPath, join(import.meta.dir, '..', 'cli.ts'), ...args];
 }

package/src/shared/bun-sqlite-driver.ts

@@ -16,6 +16,12 @@ export class BunSqliteDriver implements Driver {
 
   private releaseTurn: () => void = () => {};
 
+  /**
+   * How many acquires are waiting for an earlier caller to release the
+   * connection.
+   */
+  waiting = 0;
+
   constructor(sqlite: Database) {
     this.connection = buildConnection(sqlite);
   }
@@ -32,8 +38,12 @@ export class BunSqliteDriver implements Driver {
       release = resolve;
     });
 
+    this.waiting += 1;
+
     await previous;
 
+    this.waiting -= 1;
+
     if (release !== undefined) {
       this.releaseTurn = release;
     }