@zgeoff/atc 2.11.0 → 2.13.0

package/src/shared/collect-principals.ts

@@ -0,0 +1,51 @@
+import { isRecord } from './report';
+
+interface PrincipalsConfig {
+  // The targets each principal may use, by principal; null when the config
+  // has no `principals` key.
+  readonly principals: ReadonlyMap<string, readonly string[]> | null;
+  readonly errors: readonly string[];
+}
+
+/**
+ * Reads the `principals` map: each principal's id to the names of the
+ * targets it may use. No `principals` key is null. Otherwise the config
+ * fails closed: a malformed map grants nothing to anyone, and a malformed
+ * entry grants nothing to its principal. Each problem is an error.
+ */
+export function collectPrincipals(raw: unknown): PrincipalsConfig {
+  if (raw === undefined) {
+    return { principals: null, errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return {
+      principals: new Map(),
+      errors: ['principals must be an object of principal ids, so no principal gets a target'],
+    };
+  }
+
+  const principals = new Map<string, readonly string[]>();
+
+  const errors: string[] = [];
+
+  for (const [id, entry] of Object.entries(raw)) {
+    const targets = isRecord(entry) ? entry['targets'] : undefined;
+
+    if (
+      id === '' ||
+      !Array.isArray(targets) ||
+      !targets.every((target) => typeof target === 'string' && target !== '')
+    ) {
+      errors.push(
+        `principal ${JSON.stringify(id)} must be an object whose targets is an array of target names, so it gets no target`,
+      );
+
+      continue;
+    }
+
+    principals.set(id, targets);
+  }
+
+  return { principals, errors };
+}

package/src/shared/collect-targets.ts

@@ -0,0 +1,144 @@
+import { formatJSONKind } from './format-json-kind';
+import { isRecord } from './report';
+
+/**
+ * A named place sessions run: the execution provider kind that serves it,
+ * and the options that kind takes.
+ */
+export interface TargetConfig {
+  readonly id: string;
+  readonly provider: string;
+  readonly options: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A config problem that leaves a target, or every target, unusable: the
+ * config file as a whole, the `targets` map, one entry of it, or
+ * `defaultTarget`.
+ */
+export type TargetConfigError = TargetSectionError | ConfigFileError;
+
+interface TargetSectionError {
+  readonly scope: 'targets' | 'target' | 'defaultTarget';
+
+  // The entry the problem is in; present only for an entry's problem.
+  readonly target?: string;
+  readonly problem: string;
+}
+
+/**
+ * A config file that exists but cannot be used, so no target in it can be
+ * trusted: `config_malformed` when its text is not JSON or its root is not
+ * an object, `config_unreadable` when reading it fails for any reason but
+ * its absence. `detail` holds the parse message, the root's kind, or the
+ * read's error code.
+ */
+interface ConfigFileError {
+  readonly scope: 'config';
+  readonly problem: 'config_malformed' | 'config_unreadable';
+  readonly path: string;
+  readonly detail: string;
+}
+
+interface TargetsConfig {
+  // Every well-formed entry, in config order.
+  readonly targets: readonly TargetConfig[];
+
+  // The target a spawn without a target runs on, or null when the config
+  // gives none it can use.
+  readonly defaultTarget: string | null;
+  readonly errors: readonly TargetConfigError[];
+}
+
+// The target a config holds when it sets no targets of its own: the
+// daemon's own machine.
+const LOCAL_TARGET: TargetConfig = { id: 'local', provider: 'local-pty', options: {} };
+
+/**
+ * Reads the `targets` map and `defaultTarget`. No `targets` key holds the
+ * one implicit `local` target as the default. Otherwise the config fails
+ * closed: a malformed map holds no targets, a malformed entry is left out,
+ * and a `defaultTarget` that is not a string or matches no well-formed
+ * entry leaves no default. Each problem is an error, so a spawn that
+ * resolves through it fails with that error instead of running on `local`.
+ * Without `defaultTarget`, the default is the `local` entry when the map
+ * holds a well-formed one, and none otherwise.
+ */
+export function collectTargets(rawTargets: unknown, rawDefault: unknown): TargetsConfig {
+  if (rawTargets === undefined && rawDefault === undefined) {
+    return { targets: [LOCAL_TARGET], defaultTarget: 'local', errors: [] };
+  }
+
+  const collected = collectTargetEntries(rawTargets);
+
+  const ids = new Set(collected.targets.map((target) => target.id));
+
+  if (rawDefault === undefined) {
+    return {
+      targets: collected.targets,
+      defaultTarget: ids.has('local') ? 'local' : null,
+      errors: collected.errors,
+    };
+  }
+
+  if (typeof rawDefault === 'string' && ids.has(rawDefault)) {
+    return { targets: collected.targets, defaultTarget: rawDefault, errors: collected.errors };
+  }
+
+  // The problem gives the value's kind, never the value: a wrongly typed
+  // defaultTarget can hold anything the file holds.
+  const problem =
+    typeof rawDefault === 'string'
+      ? 'defaultTarget: matches no well-formed target in targets'
+      : `defaultTarget: expected a string, got ${formatJSONKind(rawDefault)}`;
+
+  return {
+    targets: collected.targets,
+    defaultTarget: null,
+    errors: [...collected.errors, { scope: 'defaultTarget', problem }],
+  };
+}
+
+interface TargetEntries {
+  readonly targets: readonly TargetConfig[];
+  readonly errors: readonly TargetSectionError[];
+}
+
+function collectTargetEntries(raw: unknown): TargetEntries {
+  // A defaultTarget without a targets map names one of the implicit targets.
+  if (raw === undefined) {
+    return { targets: [LOCAL_TARGET], errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw) || Object.keys(raw).length === 0) {
+    return {
+      targets: [],
+      errors: [
+        { scope: 'targets', problem: 'targets must be a non-empty object of named targets' },
+      ],
+    };
+  }
+
+  const targets: TargetConfig[] = [];
+  const errors: TargetSectionError[] = [];
+
+  for (const [id, entry] of Object.entries(raw)) {
+    const provider = isRecord(entry) ? entry['provider'] : undefined;
+
+    if (id === '' || !isRecord(entry) || typeof provider !== 'string' || provider === '') {
+      errors.push({
+        scope: 'target',
+        target: id,
+        problem: `target ${JSON.stringify(id)} must be an object with a non-empty string provider`,
+      });
+
+      continue;
+    }
+
+    const { provider: _, ...options } = entry;
+
+    targets.push({ id, provider, options });
+  }
+
+  return { targets, errors };
+}

package/src/shared/config.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { buildOptionalString } from './build-optional-string';
 import { buildOptionalStringArray } from './build-optional-string-array';
@@ -8,6 +8,11 @@ import { collectGateways } from './collect-gateways';
 import type { GatewayConfig } from './collect-gateways';
 import { collectHooks } from './collect-hooks';
 import type { HooksConfig } from './collect-hooks';
+import { collectPrincipals } from './collect-principals';
+import { collectTargets } from './collect-targets';
+import type { TargetConfig, TargetConfigError } from './collect-targets';
+import { formatJSONKind } from './format-json-kind';
+import { isRecord } from './report';
 import { resolveHomeDir } from './resolve-home-dir';
 
 export interface Config {
@@ -21,6 +26,20 @@ export interface Config {
   gateways: GatewayConfig[];
   hooks: HooksConfig;
   leader: LeaderKey;
+
+  // Where sessions run, and the one a spawn without a target runs on: null
+  // when the config gives none it can use.
+  targets: readonly TargetConfig[];
+  defaultTarget: string | null;
+
+  // The target config problems that leave a target, or every target,
+  // unusable.
+  targetErrors: readonly TargetConfigError[];
+
+  // The targets each principal may use: null when the config has no
+  // principals, which leaves every principal the implicit local target.
+  principals: ReadonlyMap<string, readonly string[]> | null;
+  principalErrors: readonly string[];
 }
 
 /**
@@ -47,6 +66,11 @@ const DEFAULTS: Config = {
   gateways: [],
   hooks: {},
   leader: { code: 0, label: '^Space' },
+  targets: [{ id: 'local', provider: 'local-pty', options: {} }],
+  defaultTarget: 'local',
+  targetErrors: [],
+  principals: null,
+  principalErrors: [],
 };
 
 const configDir = join(resolveHomeDir(), '.config', 'atc');
@@ -80,38 +104,132 @@ const CONFIG_SCHEMA = z.object({
   gateways: z.unknown().optional(),
   hooks: z.unknown().optional(),
   leader: buildOptionalString(),
+  targets: z.unknown().optional(),
+  defaultTarget: z.unknown().optional(),
+  principals: z.unknown().optional(),
 });
 
-export function loadConfig(): Config {
-  mkdirSync(configDir, { recursive: true });
-  mkdirSync(stateDir, { recursive: true });
+/**
+ * Reads and parses config.json. Only an absent file means every default,
+ * the implicit `local` target included, and a first run writes those
+ * defaults out. A file that exists but cannot be read or parsed loads as
+ * unusable: every default but the targets, which it leaves empty with the
+ * problem as the one target error, so nothing runs until the file is fixed.
+ * Never throws.
+ */
+export function loadConfig(file: string = configFile): Config {
+  // Every atc process writes under the state directory; a failure here
+  // comes back from the first write into it.
+  try {
+    mkdirSync(stateDir, { recursive: true });
+  } catch {}
+
+  let text: string;
+
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (error) {
+    const code: unknown = error instanceof Error ? Reflect.get(error, 'code') : undefined;
+
+    if (code !== 'ENOENT') {
+      const detail = typeof code === 'string' ? code : 'the file could not be read';
 
-  const file = configFile;
+      return buildUnusableConfig('config_unreadable', file, detail);
+    }
 
-  if (!existsSync(file)) {
-    writeFileSync(file, `${JSON.stringify(DEFAULTS, null, 2)}\n`);
+    tryWriteDefaultConfig(file);
 
     return { ...DEFAULTS };
   }
 
+  let raw: unknown;
+
   try {
-    return parseConfig(JSON.parse(readFileSync(file, 'utf8')));
+    raw = JSON.parse(text);
   } catch {
-    return { ...DEFAULTS };
+    // The parser's own message can quote the file's text, so the detail is
+    // a fixed phrase instead.
+    return buildUnusableConfig('config_malformed', file, 'the file is not valid JSON');
   }
+
+  return parseConfig(raw, file);
+}
+
+/**
+ * A config for a file that exists but cannot be used: every default but the
+ * targets, which are empty, with no default target and the file's problem
+ * as the one target error, and the principals, which get no target, since
+ * the file's own principals cannot be read.
+ */
+function buildUnusableConfig(
+  problem: 'config_malformed' | 'config_unreadable',
+  path: string,
+  detail: string,
+): Config {
+  return {
+    ...DEFAULTS,
+    targets: [],
+    defaultTarget: null,
+    targetErrors: [{ scope: 'config', problem, path, detail }],
+    principals: new Map(),
+  };
+}
+
+/**
+ * Writes the first-run config, never over a file that appeared since the
+ * read. A failure leaves the defaults in effect for this run, so it is not
+ * an error.
+ */
+function tryWriteDefaultConfig(file: string): void {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, renderDefaultConfig(), { flag: 'wx' });
+  } catch {}
+}
+
+/**
+ * The config.json text a first run writes. It leaves out the targets and
+ * principals, so the file holds the one implicit `local` target and no
+ * principals until the user sets their own, and the errors a parse
+ * reports, which belong to no file.
+ */
+export function renderDefaultConfig(): string {
+  const {
+    targets: _targets,
+    defaultTarget: _default,
+    targetErrors: _errors,
+    principals: _principals,
+    principalErrors: _principalErrors,
+    ...written
+  } = DEFAULTS;
+
+  return `${JSON.stringify(written, null, 2)}\n`;
 }
 
 /**
  * Parses a user-written config.json's already-decoded JSON value into a
  * Config, applying every default a malformed or absent field falls back to.
- * Total: no shape of `raw` throws, so a hand-edited config never stops atc
- * starting.
+ * A root that is not an object leaves the config unusable, with no targets,
+ * and `file` is the path its error holds. Total: no shape of `raw` throws,
+ * so a hand-edited config never stops atc starting.
  */
-export function parseConfig(raw: unknown): Config {
+export function parseConfig(raw: unknown, file: string = configFile): Config {
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return buildUnusableConfig(
+      'config_malformed',
+      file,
+      `the root is ${formatJSONKind(raw)}, not an object`,
+    );
+  }
+
   const parsed = CONFIG_SCHEMA.safeParse(raw);
 
   if (!parsed.success) {
-    return { ...DEFAULTS };
+    return buildUnusableConfig(
+      'config_malformed',
+      file,
+      'the file does not match the config schema',
+    );
   }
 
   const claudeBin = parsed.data.claudeBin ?? DEFAULTS.claudeBin;
@@ -123,6 +241,8 @@ export function parseConfig(raw: unknown): Config {
   const dirs = { roots: collectDirRoots(parsed.data.dirs) };
   const gateways = collectGateways(parsed.data.gateways, claudeBin, claudeArgs);
   const hooks = collectHooks(parsed.data.hooks);
+  const targets = collectTargets(parsed.data.targets, parsed.data.defaultTarget);
+  const principals = collectPrincipals(parsed.data.principals);
 
   const leader =
     (parsed.data.leader === undefined ? null : decodeLeader(parsed.data.leader)) ?? DEFAULTS.leader;
@@ -138,6 +258,11 @@ export function parseConfig(raw: unknown): Config {
     gateways,
     hooks,
     leader,
+    targets: targets.targets,
+    defaultTarget: targets.defaultTarget,
+    targetErrors: targets.errors,
+    principals: principals.principals,
+    principalErrors: principals.errors,
   };
 }
 

package/src/shared/daemon-id.ts

@@ -0,0 +1,8 @@
+import type { Tagged } from 'type-fest';
+
+/**
+ * The id a daemon holds for its whole life, minted once into its state
+ * store. It names the daemon in `daemon.hello`, in every session locator,
+ * and in the ownership row of each session the daemon persists.
+ */
+export type DaemonID = Tagged<string, 'DaemonID'>;

package/src/shared/format-json-kind.ts

@@ -0,0 +1,21 @@
+/**
+ * The kind of a decoded JSON value, as an error detail: "null", "an array",
+ * "an object", "a string", "a number", or "a boolean". It never includes
+ * the value itself, so a config diagnostic built from it holds nothing the
+ * file holds.
+ */
+export function formatJSONKind(raw: unknown): string {
+  if (raw === null) {
+    return 'null';
+  }
+
+  if (Array.isArray(raw)) {
+    return 'an array';
+  }
+
+  if (typeof raw === 'object') {
+    return 'an object';
+  }
+
+  return `a ${typeof raw}`;
+}

package/src/shared/open-bridge-socket.ts

@@ -0,0 +1,86 @@
+/**
+ * One line-framed connection to a session bridge, from inside a remote
+ * session: each line the bridge writes arrives whole, and each line written
+ * here goes out in order, across as many socket writes as it takes.
+ */
+export interface BridgeSocket {
+  readonly writeLine: (value: Readonly<Record<string, unknown>>) => void;
+  readonly end: () => void;
+
+  // Settles once the connection has closed, from either side.
+  readonly closed: Promise<void>;
+}
+
+/**
+ * Connects to the session bridge at a unix socket path. Rejects when
+ * nothing listens there.
+ */
+export async function openBridgeSocket(
+  path: string,
+  onLine: (line: Readonly<Record<string, unknown>>) => void,
+): Promise<BridgeSocket> {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+
+  const closed = Promise.withResolvers<void>();
+  let pending = '';
+
+  let unsent = new Uint8Array(0);
+
+  const socket = await Bun.connect({
+    unix: path,
+    socket: {
+      data(_socket, buf) {
+        const lines = `${pending}${decoder.decode(buf, { stream: true })}`.split('\n');
+
+        pending = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const parsed = parseLine(line);
+
+          if (parsed !== null) {
+            onLine(parsed);
+          }
+        }
+      },
+      drain(s) {
+        unsent = unsent.subarray(s.write(unsent));
+      },
+      close() {
+        closed.resolve();
+      },
+      error() {
+        closed.resolve();
+      },
+    },
+  });
+
+  return {
+    writeLine: (value) => {
+      const bytes = encoder.encode(`${JSON.stringify(value)}\n`);
+
+      const joined = new Uint8Array(unsent.length + bytes.length);
+
+      joined.set(unsent, 0);
+      joined.set(bytes, unsent.length);
+
+      unsent = joined.subarray(socket.write(joined));
+    },
+    end: () => {
+      socket.end();
+    },
+    closed: closed.promise,
+  };
+}
+
+function parseLine(line: string): Readonly<Record<string, unknown>> | null {
+  try {
+    const parsed: unknown = JSON.parse(line);
+
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+      ? Object.fromEntries(Object.entries(parsed))
+      : null;
+  } catch {
+    return null;
+  }
+}

package/src/shared/send-bridge-request.ts

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+import { openBridgeSocket } from './open-bridge-socket';
+
+/**
+ * Sends one request to the session bridge at a unix socket path and
+ * returns its answer line, or null when nothing listens there, the
+ * connection closes first, or no answer arrives in time. Never throws.
+ */
+export async function sendBridgeRequest(
+  path: string,
+  op: string,
+  args: Readonly<Record<string, unknown>>,
+  timeoutMs: number,
+): Promise<Readonly<Record<string, unknown>> | null> {
+  const id = randomUUID();
+  const answered = Promise.withResolvers<Readonly<Record<string, unknown>> | null>();
+
+  try {
+    const socket = await openBridgeSocket(path, (line) => {
+      if (line['id'] === id) {
+        answered.resolve(line);
+      }
+    });
+
+    void (async () => {
+      await socket.closed;
+
+      answered.resolve(null);
+    })();
+
+    const timer = setTimeout(() => {
+      answered.resolve(null);
+    }, timeoutMs);
+
+    socket.writeLine({ ...args, v: 1, id, op });
+
+    const answer = await answered.promise;
+
+    clearTimeout(timer);
+
+    socket.end();
+
+    return answer;
+  } catch {
+    return null;
+  }
+}

package/src/shared/sort-json-keys.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns a JSON value with every object's keys in sorted order, at every
+ * depth, so two values that differ only in key order serialize the same.
+ */
+export function sortJSONKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJSONKeys(item));
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value)
+        .toSorted(([a], [b]) => a.localeCompare(b))
+        .map(([key, item]) => [key, sortJSONKeys(item)]),
+    );
+  }
+
+  return value;
+}

package/src/shared/to-daemon-id.ts

@@ -0,0 +1,11 @@
+import type { DaemonID } from './daemon-id';
+
+/**
+ * Trusts a string as a daemon id. This is the one point in the codebase
+ * where a plain string becomes a `DaemonID`, and it adds no runtime check:
+ * the caller asserts the string is the id a daemon minted for itself.
+ */
+export function toDaemonID(id: string): DaemonID {
+  // oxlint-disable-next-line no-unsafe-type-assertion -- the one point where a string is trusted as a DaemonID
+  return id as DaemonID;
+}

package/src/statusline.ts

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { statusFile } from './shared/config';
 import { isRecord, sendReport } from './shared/report';
+import { sendBridgeRequest } from './shared/send-bridge-request';
 
 /**
  * Runs as the statusLine command injected into wrangled sessions. Chains the
@@ -60,6 +61,19 @@ export async function runStatusline(): Promise<void> {
     }
   } catch {}
 
+  const segment =
+    process.env['ATC_BRIDGE'] === '1' && sock !== undefined && sock !== ''
+      ? await readOwnSegment(sock)
+      : readFleetSegment();
+
+  const line = [chained, segment].filter((part) => part !== '').join(' \u001B[90m▏\u001B[0m ');
+
+  console.log(line);
+  process.exit(0);
+}
+
+// The fleet segment, from the status file the daemon writes beside it.
+function readFleetSegment(): string {
   let segment = '';
 
   try {
@@ -90,10 +104,27 @@ export async function runStatusline(): Promise<void> {
     }
   } catch {}
 
-  const line = [chained, segment].filter((part) => part !== '').join(' \u001B[90m▏\u001B[0m ');
+  return segment;
+}
 
-  console.log(line);
-  process.exit(0);
+// Inside a remote host the status file is out of reach, and the session
+// bridge returns the session's own state alone, never the rest of the fleet.
+async function readOwnSegment(sock: string): Promise<string> {
+  const status = await sendBridgeRequest(sock, 'status.read', {}, 500);
+
+  if (status === null || status['ok'] !== true) {
+    return '';
+  }
+
+  if (status['state'] === 'needs_you') {
+    return '\u001B[1;31m● needs you\u001B[0m';
+  }
+
+  if (status['state'] === 'done') {
+    return '\u001B[32m✓ done\u001B[0m';
+  }
+
+  return status['state'] === 'running' ? '\u001B[36m◐ running\u001B[0m' : '';
 }
 
 // A user statusline that is atc's own injected command would chain into