@zgeoff/atc 3.3.1 → 3.4.1

package/src/test-utils/build-mock-auth-profile.ts

@@ -0,0 +1,62 @@
+import { faker } from '@faker-js/faker';
+import type { AuthProfile } from '../shared/collect-auth-profiles';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The auth profile kinds that inject a header for a broker host.
+ */
+type HeaderAuthProfile = Extract<AuthProfile, { readonly host: string }>;
+
+/**
+ * The auth profile kind that signs in to GitHub.
+ */
+type GitHubAuthProfile = Extract<AuthProfile, { readonly kind: 'github' }>;
+
+type HeaderOverrides = MockOverrides<HeaderAuthProfile, keyof HeaderAuthProfile>;
+
+type GitHubOverrides = MockOverrides<GitHubAuthProfile, keyof GitHubAuthProfile> & {
+  readonly kind: 'github';
+};
+
+/**
+ * An auth profile of kind `custom` that sends its secret as a bearer token
+ * in a header, or, for an override of kind `github`, a GitHub profile.
+ * Either has no environment and no dependencies, and an arbitrary name and
+ * secret; a custom profile's host and header name are arbitrary too.
+ * Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockAuthProfile(overrides?: HeaderOverrides): HeaderAuthProfile;
+export function buildMockAuthProfile(overrides: GitHubOverrides): GitHubAuthProfile;
+
+export function buildMockAuthProfile(
+  overrides: HeaderOverrides | GitHubOverrides = {},
+): AuthProfile {
+  const name = faker.string.alpha({ length: 8, casing: 'lower' });
+  const secret = faker.string.alpha({ length: 8, casing: 'lower' });
+
+  return isGitHubOverrides(overrides)
+    ? mergeDeep<GitHubAuthProfile>(
+        { name, secret, kind: 'github', env: {}, dependencies: [] },
+        overrides,
+      )
+    : mergeDeep<HeaderAuthProfile>(
+        {
+          name,
+          secret,
+          kind: 'custom',
+          host: faker.internet.domainName(),
+          header: `x-${faker.string.alpha({ length: 6, casing: 'lower' })}-key`,
+          scheme: 'bearer',
+          env: {},
+          dependencies: [],
+        },
+        overrides,
+      );
+}
+
+function isGitHubOverrides(
+  overrides: HeaderOverrides | GitHubOverrides,
+): overrides is GitHubOverrides {
+  return overrides.kind === 'github';
+}

package/src/test-utils/build-mock-daemon-record.ts

@@ -0,0 +1,26 @@
+import { faker } from '@faker-js/faker';
+import type { DaemonRecord } from '../shared/find-daemon-record';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The record a daemon writes beside its state directory, for a daemon with
+ * no events socket and no TCP listener. The pid and the socket paths are
+ * arbitrary. Overrides replace the defaults field by field.
+ */
+export function buildMockDaemonRecord(
+  overrides: MockOverrides<DaemonRecord, keyof DaemonRecord> = {},
+): DaemonRecord {
+  const dir = faker.system.directoryPath();
+
+  return mergeDeep<DaemonRecord>(
+    {
+      pid: faker.number.int({ min: 2, max: 4_194_304 }),
+      socketPath: `${dir}/atc-daemon.sock`,
+      reporterSocketPath: `${dir}/atc.sock`,
+      eventsSocketPath: null,
+      listenPort: null,
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-execution-target.ts

@@ -0,0 +1,25 @@
+import { faker } from '@faker-js/faker';
+import type { ExecutionTarget } from '../daemon/build-execution-targets';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A local-pty execution target with an arbitrary id and identity, no
+ * options, and no provider, as a target of a kind this daemon lacks has.
+ * Overrides merge into fresh defaults at every depth; a provider override
+ * replaces the default whole.
+ */
+export function buildMockExecutionTarget(
+  overrides: MockOverrides<ExecutionTarget, keyof ExecutionTarget> = {},
+): ExecutionTarget {
+  return mergeDeep<ExecutionTarget>(
+    {
+      id: faker.word.noun(),
+      kind: 'local-pty',
+      options: {},
+      identity: `local-pty:${faker.string.uuid()}`,
+      provider: null,
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-fleet-entry.ts

@@ -0,0 +1,33 @@
+import { faker } from '@faker-js/faker';
+import { toAgentSessionID } from '../shared/to-agent-session-id';
+import { toSessionID } from '../shared/to-session-id';
+import type { FleetEntry } from '../store/fleet-entry';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The fields the defaults set; every other field is absent until an
+ * override gives it whole.
+ */
+type DefaultedKey = 'sessionID' | 'name' | 'cwd' | 'agentSessionID' | 'agent';
+
+/**
+ * A fleet row for a live Claude session on the local target: a fresh
+ * session id and a fresh agent session id, so it restores as resumable,
+ * with an arbitrary name and directory and every optional field absent.
+ * Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockFleetEntry(
+  overrides: MockOverrides<FleetEntry, DefaultedKey> = {},
+): FleetEntry {
+  return mergeDeep<FleetEntry, DefaultedKey>(
+    {
+      sessionID: toSessionID(faker.string.uuid()),
+      name: faker.word.noun(),
+      cwd: faker.system.directoryPath(),
+      agentSessionID: toAgentSessionID(faker.string.uuid()),
+      agent: 'claude',
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-gateway-config.ts

@@ -0,0 +1,32 @@
+import { faker } from '@faker-js/faker';
+import type { GatewayConfig } from '../shared/collect-gateways';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The fields the defaults set; every other field is absent until an
+ * override gives it whole.
+ */
+type DefaultedKey = 'id' | 'label' | 'mark' | 'bin' | 'args' | 'baseURL' | 'env';
+
+/**
+ * A Claude-compatible backend with no arguments, no environment, no helper
+ * command, no settings, and no auth. The id, label, mark, binary, and base
+ * URL are arbitrary. Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockGatewayConfig(
+  overrides: MockOverrides<GatewayConfig, DefaultedKey> = {},
+): GatewayConfig {
+  return mergeDeep<GatewayConfig, DefaultedKey>(
+    {
+      id: faker.string.alpha({ length: 8, casing: 'lower' }),
+      label: faker.company.name(),
+      mark: faker.string.alpha({ length: 1, casing: 'lower' }),
+      bin: faker.system.filePath(),
+      args: [],
+      baseURL: faker.internet.url(),
+      env: {},
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-imp-identity.ts

@@ -0,0 +1,18 @@
+import { faker } from '@faker-js/faker';
+import type { ImpIdentity } from '../daemon/imp-port';
+
+/**
+ * An impd token identity with an arbitrary name that manages the imps
+ * matching `atc-*` and may grant no secret. An override replaces the field
+ * it names.
+ */
+export function buildMockImpIdentity(overrides: Partial<ImpIdentity> = {}): ImpIdentity {
+  return {
+    kind: 'token',
+    name: faker.word.noun(),
+    scope: 'manage',
+    imps: ['atc-*'],
+    grantable: [],
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-imp-session-request.ts

@@ -0,0 +1,53 @@
+import { faker } from '@faker-js/faker';
+import type { ImpSessionRequest } from '../daemon/imp-port';
+
+/**
+ * The request that starts a process on an imp.
+ */
+type StartRequest = Extract<ImpSessionRequest, { readonly kind: 'start' }>;
+
+/**
+ * The request that attaches to a process already running on an imp.
+ */
+type AttachRequest = Extract<ImpSessionRequest, { readonly kind: 'attach' }>;
+
+type AttachOverrides = Partial<AttachRequest> & { readonly kind: 'attach' };
+
+/**
+ * A request that starts `true` on an imp with an empty environment, or, for
+ * an override of kind `attach`, one that attaches without waking the imp.
+ * Either carries no resume point and no requirements, and an arbitrary imp
+ * name, session name, and terminal size; a start's directory is arbitrary
+ * too. Each override replaces the default of its field.
+ */
+export function buildMockImpSessionRequest(overrides?: Partial<StartRequest>): StartRequest;
+export function buildMockImpSessionRequest(overrides: AttachOverrides): AttachRequest;
+
+export function buildMockImpSessionRequest(
+  overrides: Partial<StartRequest> | AttachOverrides = {},
+): ImpSessionRequest {
+  const name = `imp-${faker.string.alpha({ length: 6, casing: 'lower' })}`;
+  const session = faker.string.uuid();
+  const cols = faker.number.int({ min: 20, max: 300 });
+  const rows = faker.number.int({ min: 5, max: 100 });
+
+  return isAttachOverrides(overrides)
+    ? { name, session, cols, rows, wake: false, ...overrides }
+    : {
+        kind: 'start',
+        name,
+        session,
+        argv: ['true'],
+        env: {},
+        cwd: faker.system.directoryPath(),
+        cols,
+        rows,
+        ...overrides,
+      };
+}
+
+function isAttachOverrides(
+  overrides: Partial<StartRequest> | AttachOverrides,
+): overrides is AttachOverrides {
+  return overrides.kind === 'attach';
+}

package/src/test-utils/build-mock-key-binding-claim.ts

@@ -0,0 +1,34 @@
+import { faker } from '@faker-js/faker';
+import type { GatewayStore } from '../federation/gateway-store';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The binding a keyed request claims in the gateway store, before any
+ * outcome or send is recorded for it.
+ */
+type KeyBindingClaim = Parameters<GatewayStore['claimBinding']>[0];
+
+/**
+ * A claim of a keyed spawn by an arbitrary principal under an arbitrary
+ * key, bound to an arbitrary daemon that announced an arbitrary retention,
+ * with an arbitrary payload hash and claim id. Overrides replace the
+ * defaults field by field.
+ */
+export function buildMockKeyBindingClaim(
+  overrides: MockOverrides<KeyBindingClaim, keyof KeyBindingClaim> = {},
+): KeyBindingClaim {
+  return mergeDeep<KeyBindingClaim>(
+    {
+      principal: faker.string.alphanumeric(12),
+      operation: 'session.spawn',
+      key: faker.string.alphanumeric(16),
+      daemon: faker.string.alpha({ length: 8, casing: 'lower' }),
+      daemonID: faker.string.uuid(),
+      retentionMs: faker.number.int({ min: 1000, max: 86_400_000 }),
+      payloadHash: faker.string.hexadecimal({ length: 64, casing: 'lower', prefix: '' }),
+      claimID: faker.string.uuid(),
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-message-record.ts

@@ -0,0 +1,26 @@
+import { faker } from '@faker-js/faker';
+import { toMessageID } from '../shared/to-message-id';
+import { toSessionID } from '../shared/to-session-id';
+import type { MessageRecord } from '../store/message-record';
+
+type MessageRecordOverrides = {
+  readonly [K in keyof MessageRecord]?: MessageRecord[K] | undefined;
+};
+
+/**
+ * A message accepted for a session and not yet delivered: a fresh message
+ * id and a fresh atc id, an arbitrary sender, text, and send time, and no
+ * agent session id, delivery, answer, or turn. An override replaces the
+ * field it names, and an override of undefined leaves that field out.
+ */
+export function buildMockMessageRecord(overrides: MessageRecordOverrides = {}): MessageRecord {
+  return {
+    id: toMessageID(faker.string.uuid()),
+    atcID: toSessionID(faker.string.uuid()),
+    from: faker.person.firstName(),
+    text: faker.lorem.sentence(),
+    status: 'accepted',
+    sentAt: faker.date.past().getTime(),
+    ...Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined)),
+  };
+}

package/src/test-utils/build-mock-mirror-session.ts

@@ -0,0 +1,42 @@
+import { faker } from '@faker-js/faker';
+import type { MirrorSession } from '../client/to-mirror-session';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A client's mirror of a live, running Claude session in a local terminal
+ * on the `local` target: read, unpinned, not resumable, unable to eject,
+ * with no parent and the agent's default model. The id, name, directory,
+ * last message, and times are arbitrary. Overrides replace the defaults
+ * field by field.
+ */
+export function buildMockMirrorSession(
+  overrides: MockOverrides<MirrorSession, keyof MirrorSession> = {},
+): MirrorSession {
+  const cwd = faker.system.directoryPath();
+
+  return mergeDeep<MirrorSession>(
+    {
+      id: faker.string.uuid(),
+      name: faker.word.noun(),
+      cwd,
+      pinned: false,
+      lastAttachedAt: faker.date.recent().getTime(),
+      repoRoot: cwd,
+      state: 'running',
+      unread: false,
+      lastMsg: faker.lorem.sentence(),
+      createdAt: faker.date.past().getTime(),
+      kind: 'pty',
+      alive: true,
+      resumable: false,
+      canEject: false,
+      agent: 'claude',
+      parent: null,
+      target: 'local',
+      model: null,
+      harness: 'running',
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-registry-daemon.ts

@@ -0,0 +1,28 @@
+import { faker } from '@faker-js/faker';
+import type { RegistryDaemon } from '../federation/types';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A registry daemon with an arbitrary name, address, pinned daemon id,
+ * and token. Its incarnation is the first 8 characters of the
+ * daemon id in play, the override's when one is given, so a gateway id
+ * built from it routes back unless an override sets the incarnation too.
+ * Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockRegistryDaemon(
+  overrides: MockOverrides<RegistryDaemon, keyof RegistryDaemon> = {},
+): RegistryDaemon {
+  const daemonID = overrides.daemonID ?? faker.string.uuid();
+
+  return mergeDeep<RegistryDaemon>(
+    {
+      name: faker.string.alpha({ length: 8, casing: 'lower' }),
+      address: { host: faker.internet.ipv4(), port: faker.internet.port() },
+      daemonID,
+      incarnation: daemonID.slice(0, 8),
+      token: faker.string.hexadecimal({ length: 32, casing: 'lower', prefix: '' }),
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-session-descriptor.ts

@@ -0,0 +1,66 @@
+import { faker } from '@faker-js/faker';
+import type { SessionDescriptor } from '../daemon/sessions';
+import { toDaemonID } from '../shared/to-daemon-id';
+import { toSessionID } from '../shared/to-session-id';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * The fields the defaults set; every other field is absent until an
+ * override gives it whole.
+ */
+type DefaultedKey =
+  | 'id'
+  | 'name'
+  | 'cwd'
+  | 'state'
+  | 'unread'
+  | 'lastMsg'
+  | 'agent'
+  | 'pinned'
+  | 'lastAttachedAt'
+  | 'repoRoot'
+  | 'namedBy'
+  | 'createdAt'
+  | 'kind'
+  | 'alive'
+  | 'canEject'
+  | 'locator'
+  | 'lifecycle';
+
+/**
+ * The wire view of a live, running Claude session in a local terminal on
+ * the `local` target, as `session.list` and the session events carry it:
+ * read, unpinned, named by the user, with no parent, workspace, model, or
+ * agent session id. The id, name, directories, last message, times, and
+ * daemon id are arbitrary. Overrides merge into fresh defaults at every
+ * depth.
+ */
+export function buildMockSessionDescriptor(
+  overrides: MockOverrides<SessionDescriptor, DefaultedKey> = {},
+): SessionDescriptor {
+  const cwd = faker.system.directoryPath();
+
+  return mergeDeep<SessionDescriptor, DefaultedKey>(
+    {
+      id: toSessionID(faker.string.uuid()),
+      name: faker.word.noun(),
+      cwd,
+      state: 'running',
+      unread: false,
+      lastMsg: faker.lorem.sentence(),
+      agent: 'claude',
+      pinned: false,
+      lastAttachedAt: faker.date.recent().getTime(),
+      repoRoot: cwd,
+      namedBy: 'user',
+      createdAt: faker.date.past().getTime(),
+      kind: 'pty',
+      alive: true,
+      canEject: false,
+      locator: { daemonID: toDaemonID(faker.string.uuid()), targetID: 'local' },
+      lifecycle: { desired: 'run', vm: 'none', harness: 'running', attachment: 'local' },
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-session.ts

@@ -0,0 +1,43 @@
+import { faker } from '@faker-js/faker';
+import type { Session } from '../daemon/sessions';
+import { toSessionID } from '../shared/to-session-id';
+
+/**
+ * A session manager's record of an exited Claude session on the `local`
+ * target with no terminal: read, unpinned, auto-named, with no parent,
+ * withheld env, workspace, model, or agent session id, and its own host.
+ * The id, name, directories, and times are arbitrary. An override replaces
+ * the field it names.
+ */
+export function buildMockSession(overrides: Partial<Session> = {}): Session {
+  const id = overrides.id ?? toSessionID(faker.string.uuid());
+  const cwd = faker.system.directoryPath();
+
+  return {
+    id,
+    name: faker.word.noun(),
+    cwd,
+    kind: 'pty',
+    pty: null,
+    state: 'exited',
+    unread: false,
+    lastMsg: '',
+    agent: 'claude',
+    pinned: false,
+    lastAttachedAt: faker.date.recent().getTime(),
+    repoRoot: cwd,
+    namedBy: 'auto',
+    createdAt: faker.date.past().getTime(),
+    parent: null,
+    target: 'local',
+    targetIdentity: 'local-pty:test',
+    withheldEnv: [],
+    desired: 'run',
+    vm: 'none',
+    attachment: 'local',
+    suspended: false,
+    hostKey: id,
+    bridgeEpoch: 0,
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-sortable-session-view.ts

@@ -0,0 +1,20 @@
+import { faker } from '@faker-js/faker';
+import type { SortableSessionView } from '../protocol/sortable-session-view';
+
+/**
+ * The ordering fields of a running, unpinned, top-level session, as the
+ * session list sorts it. The id and both times are arbitrary.
+ */
+export function buildMockSortableSessionView(
+  overrides: Partial<SortableSessionView> = {},
+): SortableSessionView {
+  return {
+    id: faker.string.uuid(),
+    parent: null,
+    state: 'running',
+    pinned: false,
+    lastAttachedAt: faker.date.recent().getTime(),
+    createdAt: faker.date.past().getTime(),
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-stored-event.ts

@@ -0,0 +1,20 @@
+import { faker } from '@faker-js/faker';
+import { toSessionID } from '../shared/to-session-id';
+import type { StoredEvent } from '../store/state-store';
+
+/**
+ * A row of the event trail as the store reads it back: a `turn-done` event
+ * with an arbitrary row id, time, and fresh atc id, and no agent session
+ * id, detail, message, or label. Each override replaces the default of its field.
+ */
+export function buildMockStoredEvent(overrides: Partial<StoredEvent> = {}): StoredEvent {
+  return {
+    id: faker.number.int({ min: 1, max: 1_000_000 }),
+    at: faker.date.past().getTime(),
+    atcID: toSessionID(faker.string.uuid()),
+    agentSessionID: null,
+    kind: 'turn-done',
+    detail: null,
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-stored-row.ts

@@ -0,0 +1,23 @@
+import { faker } from '@faker-js/faker';
+import type { StoredRow } from '../read-stored-rows';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A fleet row a daemon has stored, for a live session with a fresh id, an
+ * arbitrary name, and no known agent session id. Overrides replace the
+ * defaults field by field.
+ */
+export function buildMockStoredRow(
+  overrides: MockOverrides<StoredRow, keyof StoredRow> = {},
+): StoredRow {
+  return mergeDeep<StoredRow>(
+    {
+      id: faker.string.uuid(),
+      name: faker.word.noun(),
+      exited: false,
+      agentSessionID: null,
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-stub-attention-adapter.ts

@@ -0,0 +1,22 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+
+/**
+ * An agent adapter for daemon tests whose hooks report attention: id
+ * `claude`, a spawn that runs `sleep 30`, sessions that take inbox
+ * messages, a `Notification` hook read as needing input and every other
+ * hook as a submitted prompt, and `claude --resume` as the resume command.
+ * It reads nothing from a hook's payload, so a payload's session id binds
+ * nothing. Every other member is the mock adapter's. An override replaces
+ * the member it names.
+ */
+export function buildStubAttentionAdapter(overrides: Partial<AgentAdapter> = {}): AgentAdapter {
+  return buildMockAgentAdapter({
+    takesMessages: true,
+    normalizeHook: (hook) => ({
+      kind: hook.event === 'Notification' ? 'needs-input' : 'prompt-submitted',
+    }),
+    buildResumeCommand: () => 'claude --resume',
+    ...overrides,
+  });
+}

package/src/test-utils/build-stub-bridge-context.ts

@@ -0,0 +1,20 @@
+import type { BridgeContext } from '../daemon/start-session-bridge';
+
+/**
+ * The daemon's side of a session bridge, for tests that drive one bridge
+ * without a daemon behind it: no live session, hook events that go nowhere,
+ * every report recorded, every tap attached, every ack for an unknown
+ * message, and detaches that do nothing. An override replaces the member it
+ * names.
+ */
+export function buildStubBridgeContext(overrides: Partial<BridgeContext> = {}): BridgeContext {
+  return {
+    findSession: () => {},
+    applyHookEvent: () => {},
+    applyReport: () => Promise.resolve(true),
+    attachTap: () => 'ok',
+    ackMessage: () => Promise.resolve('unknown'),
+    detachTap: () => {},
+    ...overrides,
+  };
+}