@zgeoff/atc 2.22.0 → 2.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -30,6 +30,7 @@
     "lint:fix": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error --fix",
     "test": "bash scripts/with-test-home.sh bun test",
     "test:binary": "bash scripts/with-test-home.sh bun test --timeout 20000 test/daemon-e2e.test.ts",
+    "test:gateway-binary": "bash scripts/with-test-home.sh bun test --timeout 20000 src/gateway.test.ts",
     "test:atc-bridge": "bash scripts/with-test-home.sh bash scripts/test-atc-bridge.sh",
     "test:isolation": "bash scripts/check-test-isolation.sh",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/src/cli.ts

@@ -101,8 +101,12 @@ const main = defineCommand({
               meta: { name: 'list', description: 'List the clients', hidden: true },
               async run() {
                 const clients = await import('./clients');
+                const config = await import('./shared/config');
 
-                await clients.runClients({ kind: 'list' });
+                await clients.runClients(
+                  { kind: 'list' },
+                  { dbPath: config.mcpAuthDBFile, command: 'atc clients' },
+                );
               },
             }),
           add: () =>
@@ -118,12 +122,16 @@ const main = defineCommand({
               },
               async run(ctx) {
                 const clients = await import('./clients');
-
-                await clients.runClients({
-                  kind: 'add',
-                  name: ctx.args.name,
-                  redirectURIs: collectRedirectURIs(ctx.rawArgs),
-                });
+                const config = await import('./shared/config');
+
+                await clients.runClients(
+                  {
+                    kind: 'add',
+                    name: ctx.args.name,
+                    redirectURIs: collectRedirectURIs(ctx.rawArgs),
+                  },
+                  { dbPath: config.mcpAuthDBFile, command: 'atc clients' },
+                );
               },
             }),
           remove: () =>
@@ -137,8 +145,12 @@ const main = defineCommand({
               },
               async run(ctx) {
                 const clients = await import('./clients');
+                const config = await import('./shared/config');
 
-                await clients.runClients({ kind: 'remove', clientID: ctx.args.id });
+                await clients.runClients(
+                  { kind: 'remove', clientID: ctx.args.id },
+                  { dbPath: config.mcpAuthDBFile, command: 'atc clients' },
+                );
               },
             }),
         },

package/src/clients.ts

@@ -1,9 +1,9 @@
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { collectClients } from './mcp/collect-clients';
 import { isAllowedRedirectURI } from './mcp/is-allowed-redirect-uri';
 import { openMCPAuth } from './mcp/open-mcp-auth';
 import { removeClient } from './mcp/remove-client';
-import { mcpAuthDBFile, stateDir } from './shared/config';
 import { normalizeClientName } from './shared/normalize-client-name';
 
 type ClientsAction =
@@ -11,30 +11,37 @@ type ClientsAction =
   | { readonly kind: 'add'; readonly name: string; readonly redirectURIs: readonly string[] }
   | { readonly kind: 'remove'; readonly clientID: string };
 
+// The authorization server's database, and the command that prefixes every
+// message, such as `atc clients`.
+interface ClientsTarget {
+  readonly dbPath: string;
+  readonly command: string;
+}
+
 /**
- * Runs `atc clients`: lists the clients that may connect to `atc mcp --http`,
- * adds one, or removes one along with every token and consent it holds. It
- * opens the authorization server's database directly, so it works whether or
- * not the server is running.
+ * Runs `atc clients` or `atc-gateway clients`: lists the clients that may
+ * connect to the MCP HTTP server, adds one, or removes one along with every
+ * token and consent it holds. It opens the authorization server's database
+ * directly, so it works whether or not the server is running.
  */
-export async function runClients(action: ClientsAction): Promise<void> {
+export async function runClients(action: ClientsAction, target: ClientsTarget): Promise<void> {
   if (action.kind === 'add') {
     const refused = action.redirectURIs.find((uri) => !isAllowedRedirectURI(uri));
 
     if (action.redirectURIs.length === 0 || refused !== undefined) {
       const message =
         refused === undefined
-          ? 'atc clients add: give at least one --redirect-uri'
-          : `atc clients add: '${refused}' is not a redirect URI atc accepts; use https, or http on a loopback host, with no fragment`;
+          ? `${target.command} add: give at least one --redirect-uri`
+          : `${target.command} add: '${refused}' is not a redirect URI atc accepts; use https, or http on a loopback host, with no fragment`;
 
       console.error(message);
       process.exit(1);
     }
   }
 
-  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(dirname(target.dbPath), { recursive: true });
 
-  const store = await openMCPAuth({ dbPath: mcpAuthDBFile, origin: null });
+  const store = await openMCPAuth({ dbPath: target.dbPath, origin: null });
 
   try {
     if (action.kind === 'add') {
@@ -53,7 +60,7 @@ export async function runClients(action: ClientsAction): Promise<void> {
       const removed = await removeClient(store.db, action.clientID);
 
       if (!removed) {
-        console.error(`atc clients remove: no client has the ID '${action.clientID}'`);
+        console.error(`${target.command} remove: no client has the ID '${action.clientID}'`);
 
         process.exitCode = 1;
 
@@ -68,7 +75,7 @@ export async function runClients(action: ClientsAction): Promise<void> {
     const clients = await collectClients(store.db);
 
     if (clients.length === 0) {
-      console.log('No clients. Add one with: atc clients add <name> --redirect-uri <uri>');
+      console.log(`No clients. Add one with: ${target.command} add <name> --redirect-uri <uri>`);
 
       return;
     }

package/src/gateway.ts

@@ -0,0 +1,183 @@
+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';
+
+// 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);

package/src/parse-gateway-state-dir.ts

@@ -0,0 +1,94 @@
+/**
+ * The flags `atc-gateway` accepts anywhere on its command line: those that
+ * take a value, and switches that take none. Names are written without
+ * their leading dashes.
+ */
+export interface GatewayFlags {
+  readonly values: ReadonlySet<string>;
+  readonly switches: ReadonlySet<string>;
+}
+
+type ParsedStateDir =
+  | { readonly ok: true; readonly stateDir: string | null }
+  | { readonly ok: false; readonly message: string };
+
+// A flag: one or two dashes, a name, and an optional `=<value>`. A lone `-`
+// is a positional.
+const FLAG_PATTERN = /^--?(?<name>[^=]+)(?:=(?<value>[\s\S]*))?$/;
+
+/**
+ * Finds the state directory in the whole `atc-gateway` command line, before,
+ * between, or after its subcommands, so no position can drop the flag.
+ * `--state-dir <dir>` and `--state-dir=<dir>` count; a value after `--` or
+ * held by another flag never does. Every `--state-dir` must give the same
+ * directory. The flag wins over `ATC_GATEWAY_STATE_DIR`, and with neither
+ * the result is null. A flag the gateway does not know, a switch given a
+ * value, and a flag whose value is missing or starts with `-` are refused,
+ * since reading them either way could pick the wrong directory.
+ */
+export function parseGatewayStateDir(
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+  flags: GatewayFlags,
+): ParsedStateDir {
+  const given: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i] ?? '';
+
+    if (token === '--') {
+      break;
+    }
+
+    const match = FLAG_PATTERN.exec(token);
+
+    if (match === null) {
+      continue;
+    }
+
+    const name = match.groups?.['name'] ?? '';
+    const inline = match.groups?.['value'];
+
+    if (flags.switches.has(name)) {
+      if (inline !== undefined) {
+        return { ok: false, message: `${token} takes no value` };
+      }
+
+      continue;
+    }
+
+    if (!flags.values.has(name)) {
+      return { ok: false, message: `unknown flag '${token}'` };
+    }
+
+    const value = inline ?? argv[i + 1];
+
+    if (inline === undefined) {
+      i++;
+    }
+
+    if (value === undefined || value === '' || (inline === undefined && value.startsWith('-'))) {
+      return { ok: false, message: `--${name} needs a value; write --${name}=<value>` };
+    }
+
+    if (name === 'state-dir') {
+      given.push(value);
+    }
+  }
+
+  const distinct = [...new Set(given)];
+
+  if (distinct.length > 1) {
+    return {
+      ok: false,
+      message: `--state-dir gives different directories: ${distinct.map((dir) => `'${dir}'`).join(', ')}`,
+    };
+  }
+
+  const fromEnv = env['ATC_GATEWAY_STATE_DIR'];
+
+  return {
+    ok: true,
+    stateDir: distinct[0] ?? (fromEnv === undefined || fromEnv === '' ? null : fromEnv),
+  };
+}

package/src/run-gateway.ts

@@ -0,0 +1,93 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DaemonClient } from './client/daemon-client';
+import { loadGatewayRegistry } from './federation/load-gateway-registry';
+import { openGatewayCaller } from './federation/open-gateway-caller';
+import { startMCPHTTPServer } from './mcp/start-mcp-http-server';
+import type { MCPHTTPServer } from './mcp/start-mcp-http-server';
+
+interface GatewayFlags {
+  readonly host: string;
+  readonly port: number;
+  readonly publicURL: string;
+  readonly registryPath: string;
+  readonly stateDir: string;
+}
+
+/**
+ * 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
+ * TCP, until SIGINT or SIGTERM. It never starts or reaches a local daemon.
+ * The keyed-request bindings (`gateway.db`) and the authorization server
+ * (`mcp-auth.db`) live in the state directory, the only place it writes. A
+ * 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);
+
+  if (!loaded.ok) {
+    for (const error of loaded.errors) {
+      console.error(`atc-gateway: ${error}`);
+    }
+
+    process.exit(1);
+  }
+
+  mkdirSync(flags.stateDir, { recursive: true });
+
+  const gateway = openGatewayCaller({
+    registry: loaded.registry,
+    build,
+    openChannel: (address) => DaemonClient.open({ hostname: address.host, port: address.port }),
+    gatewayDBPath: join(flags.stateDir, 'gateway.db'),
+  });
+
+  let server: MCPHTTPServer;
+
+  try {
+    server = await startMCPHTTPServer({
+      caller: gateway.caller,
+      build,
+      host: flags.host,
+      port: flags.port,
+      publicURL: flags.publicURL,
+      allowedHosts: [],
+      dbPath: join(flags.stateDir, 'mcp-auth.db'),
+      probes: true,
+
+      // 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, ''));
+      },
+
+      // Request lines go to stderr, so stdout keeps the approval lines alone.
+      printRequest: (line) => {
+        console.error(line);
+      },
+    });
+  } catch (error) {
+    await gateway.stop();
+
+    console.error(`atc-gateway: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+
+  console.log(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
+
+  const stopServing = async () => {
+    await server.stop();
+    await gateway.stop();
+
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => {
+    void stopServing();
+  });
+
+  process.on('SIGTERM', () => {
+    void stopServing();
+  });
+}