experimental-a2 0.3.0 → 0.5.0

package/src/cli.ts

@@ -0,0 +1,1046 @@
+import { open as nodeOpen, readFile as nodeReadFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import {
+  DEVTOOLS_PROTOCOL_VERSION,
+  DEVTOOLS_SESSION_PAGE_LIMIT,
+  devtoolsSessionRevision,
+  parseDevtoolsCapture,
+  verifyDevtoolsCapture,
+  type DevtoolsCapture,
+  type DevtoolsContractsResponse,
+  type DevtoolsSessionDetail,
+  type DevtoolsSessionPage,
+  type DevtoolsSessionsResponse,
+} from './devtools.ts'
+
+export const DEVTOOLS_CLI_EXIT_ERROR = 1 as const
+export const DEVTOOLS_CLI_EXIT_CHECK_FAILED = 2 as const
+
+type OutputFormat = 'human' | 'json' | 'ndjson'
+type Command = 'contracts' | 'sessions' | 'show' | 'export' | 'check' | 'verify'
+
+export type DevtoolsCliOptions = {
+  fetch?: typeof globalThis.fetch
+  env?: Readonly<Record<string, string | undefined>>
+  cwd?: string
+  stdout?: (text: string) => void
+  stderr?: (text: string) => void
+  readFile?: (path: string) => Promise<Uint8Array>
+  writeFile?: (
+    path: string,
+    data: Uint8Array,
+    options: { flag: 'w' | 'wx'; mode: number },
+  ) => Promise<void>
+}
+
+type ParsedArguments = {
+  command: Command | null
+  help: boolean
+  url: string | undefined
+  format: OutputFormat
+  contract: string | undefined
+  session: string | undefined
+  cursor: string | undefined
+  limit: number | undefined
+  output: string | undefined
+  force: boolean
+  bearerEnv: string | undefined
+  headerEnvs: string[]
+  settled: boolean
+  noDeadLetters: boolean
+  noCaughtFailures: boolean
+  maxRedispatches: number | undefined
+  positionals: string[]
+}
+
+type CheckSummary = {
+  ok: boolean
+  contract: string
+  sessionId: string
+  revision: string
+  eventCount: number
+  snapshotCount: number
+  pendingCount: number
+  deadLetterCount: number
+  caughtFailureCount: number
+  redispatchCount: number
+  failures: string[]
+}
+
+class CliFailure extends Error {
+  readonly exitCode: number
+
+  constructor(message: string, exitCode: number = DEVTOOLS_CLI_EXIT_ERROR) {
+    super(message)
+    this.name = 'CliFailure'
+    this.exitCode = exitCode
+  }
+}
+
+class IntegrityFailure extends CliFailure {
+  constructor(message: string) {
+    super(message, DEVTOOLS_CLI_EXIT_CHECK_FAILED)
+    this.name = 'IntegrityFailure'
+  }
+}
+
+const USAGE = `Usage: a2 devtools <command> [options]
+
+Commands:
+  contracts                    List mounted contracts
+  sessions --contract NAME     List a contract's sessions
+  show --contract NAME --session ID
+                               Show one durable session
+  export --contract NAME --session ID [--output FILE]
+                               Save an integrity-protected .a2log capture
+  check --contract NAME --session ID [assertions]
+                               Verify a live session capture
+  verify FILE                  Verify a saved .a2log capture
+
+Connection:
+  --url URL                    Mounted devtools URL (or A2_DEVTOOLS_URL)
+  --bearer-env ENV             Read a bearer token from ENV
+  --header-env HEADER=ENV      Read a request header from ENV; repeatable
+
+Output:
+  --format human|json|ndjson   Human output is the default
+  --output FILE, -o FILE       Export destination
+  --force                      Allow export to replace FILE
+
+Check assertions:
+  --settled                    Require no pending events
+  --no-dead-letters            Require no dead-lettered events
+  --no-caught-failures         Require no caught handler failures
+  --max-redispatches N         Limit dispatches after each event's first claim
+`
+
+const commandNames = new Set<Command>([
+  'contracts',
+  'sessions',
+  'show',
+  'export',
+  'check',
+  'verify',
+])
+
+const fail = (message: string): never => {
+  throw new CliFailure(message)
+}
+
+const nextValue = (
+  argv: readonly string[],
+  index: number,
+  option: string,
+): { value: string; next: number } => {
+  const token = argv[index]!
+  const equals = token.indexOf('=')
+  if (equals !== -1) {
+    const value = token.slice(equals + 1)
+    if (value.length === 0) fail(`${option} requires a value`)
+    return { value, next: index }
+  }
+  const value = argv[index + 1]
+  if (value === undefined || value.startsWith('-')) {
+    fail(`${option} requires a value`)
+  }
+  return { value: value!, next: index + 1 }
+}
+
+const nonNegativeInteger = (value: string, option: string): number => {
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    fail(`${option} must be a non-negative integer`)
+  }
+  return parsed
+}
+
+const positiveInteger = (value: string, option: string): number => {
+  const parsed = nonNegativeInteger(value, option)
+  if (parsed === 0) fail(`${option} must be a positive integer`)
+  return parsed
+}
+
+const parseArguments = (argv: readonly string[]): ParsedArguments => {
+  if (argv[0] !== 'devtools') {
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+      return {
+        command: null,
+        help: true,
+        url: undefined,
+        format: 'human',
+        contract: undefined,
+        session: undefined,
+        cursor: undefined,
+        limit: undefined,
+        output: undefined,
+        force: false,
+        bearerEnv: undefined,
+        headerEnvs: [],
+        settled: false,
+        noDeadLetters: false,
+        noCaughtFailures: false,
+        maxRedispatches: undefined,
+        positionals: [],
+      }
+    }
+    fail("expected the 'devtools' command namespace")
+  }
+
+  const parsed: ParsedArguments = {
+    command: null,
+    help: false,
+    url: undefined,
+    format: 'human',
+    contract: undefined,
+    session: undefined,
+    cursor: undefined,
+    limit: undefined,
+    output: undefined,
+    force: false,
+    bearerEnv: undefined,
+    headerEnvs: [],
+    settled: false,
+    noDeadLetters: false,
+    noCaughtFailures: false,
+    maxRedispatches: undefined,
+    positionals: [],
+  }
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const token = argv[index]!
+    if (token === '--help' || token === '-h' || token === 'help') {
+      parsed.help = true
+      continue
+    }
+    if (
+      token === '--token' ||
+      token.startsWith('--token=') ||
+      token === '--bearer' ||
+      token.startsWith('--bearer=') ||
+      token === '--header' ||
+      token.startsWith('--header=')
+    ) {
+      fail(
+        'literal credential flags are not supported; use A2_DEVTOOLS_TOKEN, --bearer-env, or --header-env',
+      )
+    }
+    if (token === '--force') {
+      parsed.force = true
+      continue
+    }
+    if (token === '--settled') {
+      parsed.settled = true
+      continue
+    }
+    if (token === '--no-dead-letters') {
+      parsed.noDeadLetters = true
+      continue
+    }
+    if (token === '--no-caught-failures') {
+      parsed.noCaughtFailures = true
+      continue
+    }
+
+    const option = token.split('=', 1)[0]!
+    if (
+      option === '--url' ||
+      option === '--format' ||
+      option === '--contract' ||
+      option === '--session' ||
+      option === '--cursor' ||
+      option === '--limit' ||
+      option === '--output' ||
+      option === '-o' ||
+      option === '--bearer-env' ||
+      option === '--header-env' ||
+      option === '--max-redispatches'
+    ) {
+      const result = nextValue(argv, index, option)
+      index = result.next
+      switch (option) {
+        case '--url':
+          parsed.url = result.value
+          break
+        case '--format':
+          if (
+            result.value !== 'human' &&
+            result.value !== 'json' &&
+            result.value !== 'ndjson'
+          ) {
+            fail('--format must be human, json, or ndjson')
+          }
+          parsed.format = result.value as OutputFormat
+          break
+        case '--contract':
+          parsed.contract = result.value
+          break
+        case '--session':
+          parsed.session = result.value
+          break
+        case '--cursor':
+          parsed.cursor = result.value
+          break
+        case '--limit':
+          parsed.limit = positiveInteger(result.value, '--limit')
+          break
+        case '--output':
+        case '-o':
+          parsed.output = result.value
+          break
+        case '--bearer-env':
+          parsed.bearerEnv = result.value
+          break
+        case '--header-env':
+          parsed.headerEnvs.push(result.value)
+          break
+        case '--max-redispatches':
+          parsed.maxRedispatches = nonNegativeInteger(
+            result.value,
+            '--max-redispatches',
+          )
+          break
+      }
+      continue
+    }
+    if (token.startsWith('-')) fail(`unknown option '${token}'`)
+    if (parsed.command === null && commandNames.has(token as Command)) {
+      parsed.command = token as Command
+      continue
+    }
+    if (parsed.command === null) fail(`unknown devtools command '${token}'`)
+    parsed.positionals.push(token)
+  }
+  return parsed
+}
+
+const required = (value: string | undefined, option: string): string => {
+  if (value === undefined) fail(`${option} is required`)
+  return value!
+}
+
+const assertCommandArguments = (args: ParsedArguments): void => {
+  if (args.command === null) return
+  if (args.command === 'verify') {
+    if (args.positionals.length !== 1) {
+      fail('verify requires exactly one capture file')
+    }
+    return
+  }
+  if (args.positionals.length > 0) {
+    fail(`unexpected argument '${args.positionals[0]}'`)
+  }
+  if (args.command !== 'contracts') {
+    required(args.contract, '--contract')
+  }
+  if (
+    args.command === 'show' ||
+    args.command === 'export' ||
+    args.command === 'check'
+  ) {
+    required(args.session, '--session')
+  }
+}
+
+const baseUrl = (value: string): URL => {
+  const url = (() => {
+    try {
+      return new URL(value)
+    } catch {
+      return fail('--url must be an absolute HTTP(S) URL')
+    }
+  })()
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    fail('--url must use HTTP or HTTPS')
+  }
+  if (url.username || url.password) {
+    fail('credentials must not be embedded in --url')
+  }
+  if (url.search || url.hash) {
+    fail('--url must not contain a query string or fragment')
+  }
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/`
+  return url
+}
+
+const environmentName = (value: string, option: string): string => {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    fail(`${option} must reference a valid environment variable name`)
+  }
+  return value
+}
+
+const requestHeaders = (
+  args: ParsedArguments,
+  env: Readonly<Record<string, string | undefined>>,
+  accept: string,
+): Headers => {
+  const headers = new Headers({ accept })
+  const bearerName =
+    args.bearerEnv === undefined
+      ? 'A2_DEVTOOLS_TOKEN'
+      : environmentName(args.bearerEnv, '--bearer-env')
+  const bearer = env[bearerName]
+  if (args.bearerEnv !== undefined && !bearer) {
+    fail(`environment variable '${bearerName}' is not set`)
+  }
+  if (bearer) headers.set('authorization', `Bearer ${bearer}`)
+
+  for (const mapping of args.headerEnvs) {
+    const equals = mapping.indexOf('=')
+    if (equals < 1 || equals === mapping.length - 1) {
+      fail('--header-env must use HEADER=ENV')
+    }
+    const name = mapping.slice(0, equals)
+    const envName = environmentName(mapping.slice(equals + 1), '--header-env')
+    const value = env[envName]
+    if (!value) fail(`environment variable '${envName}' is not set`)
+    if (headers.has(name)) fail(`request header '${name}' was configured twice`)
+    try {
+      headers.set(name, value!)
+    } catch {
+      fail(`--header-env contains an invalid header name or value`)
+    }
+  }
+  return headers
+}
+
+const resourceUrl = (
+  base: URL,
+  resource: string,
+  params: Readonly<Record<string, string | number | undefined>>,
+): URL => {
+  const url = new URL(`_a2/${resource}`, base)
+  for (const [name, value] of Object.entries(params)) {
+    if (value !== undefined) url.searchParams.set(name, String(value))
+  }
+  return url
+}
+
+const terminalText = (value: string): string =>
+  [...value]
+    .map((character) => {
+      const codePoint = character.codePointAt(0)!
+      const isControl =
+        codePoint <= 0x1f ||
+        (codePoint >= 0x7f && codePoint <= 0x9f) ||
+        codePoint === 0x2028 ||
+        codePoint === 0x2029
+      if (!isControl) return character
+      if (character === '\n') return '\\n'
+      if (character === '\r') return '\\r'
+      if (character === '\t') return '\\t'
+      return codePoint <= 0xff
+        ? `\\x${codePoint.toString(16).padStart(2, '0')}`
+        : `\\u${codePoint.toString(16).padStart(4, '0')}`
+    })
+    .join('')
+
+const fetchResponse = async (
+  fetcher: typeof globalThis.fetch,
+  url: URL,
+  headers: Headers,
+  resource: string,
+): Promise<Response> => {
+  let response: Response
+  try {
+    response = await fetcher(url, {
+      method: 'GET',
+      headers,
+      redirect: 'manual',
+    })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new CliFailure(`could not fetch ${resource}: ${message}`)
+  }
+  if (!response.ok) {
+    let text = ''
+    try {
+      text = await response.text()
+    } catch {
+      // The status remains useful when an error response has an unreadable body.
+    }
+    const detail = terminalText(text.trim().slice(0, 300))
+    throw new CliFailure(
+      `${resource} returned ${response.status}${detail ? `: ${detail}` : ''}`,
+    )
+  }
+  return response
+}
+
+const responseText = async (
+  fetcher: typeof globalThis.fetch,
+  url: URL,
+  headers: Headers,
+  resource: string,
+): Promise<string> =>
+  (await fetchResponse(fetcher, url, headers, resource)).text()
+
+const responseBytes = async (
+  fetcher: typeof globalThis.fetch,
+  url: URL,
+  headers: Headers,
+  resource: string,
+): Promise<Uint8Array> =>
+  new Uint8Array(
+    await (await fetchResponse(fetcher, url, headers, resource)).arrayBuffer(),
+  )
+
+const objectValue = (value: unknown): Record<string, unknown> | null =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+
+const parseJson = (text: string, resource: string): unknown => {
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    throw new CliFailure(`${resource} did not return valid JSON`)
+  }
+}
+
+const assertProtocol = (
+  value: Record<string, unknown>,
+  resource: string,
+): void => {
+  if (value['protocolVersion'] !== DEVTOOLS_PROTOCOL_VERSION) {
+    throw new CliFailure(`${resource} returned an unsupported protocol version`)
+  }
+}
+
+const hasContractName = (value: unknown): boolean => {
+  const object = objectValue(value)
+  return typeof object?.['name'] === 'string' && object['name'].length > 0
+}
+
+const contractsResponse = (value: unknown): DevtoolsContractsResponse => {
+  const object = objectValue(value)
+  if (!object) throw new CliFailure('contracts returned an invalid response')
+  assertProtocol(object, 'contracts')
+  if (
+    !Array.isArray(object['contracts']) ||
+    !object['contracts'].every(hasContractName)
+  ) {
+    throw new CliFailure('contracts returned an invalid response')
+  }
+  return object as DevtoolsContractsResponse
+}
+
+const sessionsResponse = (value: unknown): DevtoolsSessionsResponse => {
+  const object = objectValue(value)
+  if (!object) throw new CliFailure('sessions returned an invalid response')
+  assertProtocol(object, 'sessions')
+  if (
+    !Array.isArray(object['sessions']) ||
+    (object['cursor'] !== null && typeof object['cursor'] !== 'string')
+  ) {
+    throw new CliFailure('sessions returned an invalid response')
+  }
+  return object as DevtoolsSessionsResponse
+}
+
+const sessionResponse = (value: unknown): DevtoolsSessionDetail => {
+  const object = objectValue(value)
+  if (!object) throw new CliFailure('session returned an invalid response')
+  assertProtocol(object, 'session')
+  if (
+    typeof object['contract'] !== 'string' ||
+    typeof object['sessionId'] !== 'string' ||
+    typeof object['revision'] !== 'string' ||
+    !Array.isArray(object['events']) ||
+    !Array.isArray(object['snapshots'])
+  ) {
+    throw new CliFailure('session returned an invalid response')
+  }
+  return object as DevtoolsSessionDetail
+}
+
+const sessionPageResponse = (value: unknown): DevtoolsSessionPage => {
+  const object = objectValue(value)
+  if (!object) throw new CliFailure('session returned an invalid response')
+  assertProtocol(object, 'session')
+  if (
+    typeof object['contract'] !== 'string' ||
+    typeof object['sessionId'] !== 'string' ||
+    !Number.isSafeInteger(object['throughIndex']) ||
+    (object['throughIndex'] as number) < 0 ||
+    (object['cursor'] !== null && typeof object['cursor'] !== 'string') ||
+    !Array.isArray(object['events']) ||
+    !Array.isArray(object['snapshots'])
+  ) {
+    throw new CliFailure('session returned an invalid response')
+  }
+  return object as DevtoolsSessionPage
+}
+
+const readSessionDetail = async (
+  fetcher: typeof globalThis.fetch,
+  base: URL,
+  headers: Headers,
+  contract: string,
+  session: string,
+): Promise<DevtoolsSessionDetail> => {
+  const events: DevtoolsSessionDetail['events'] = []
+  let snapshots: DevtoolsSessionDetail['snapshots'] = []
+  let cursor: string | undefined
+  let throughIndex: number | undefined
+  const seenCursors = new Set<string>()
+  for (;;) {
+    // oxlint-disable-next-line no-await-in-loop -- each HTTP request advances one frozen session page
+    const text = await responseText(
+      fetcher,
+      resourceUrl(base, 'session', {
+        contract,
+        session,
+        limit: DEVTOOLS_SESSION_PAGE_LIMIT,
+        cursor,
+      }),
+      headers,
+      'session',
+    )
+    const parsed = parseJson(text, 'session')
+    const object = objectValue(parsed)
+    if (object && typeof object['revision'] === 'string') {
+      if (events.length > 0) {
+        throw new CliFailure('session changed response shape between pages')
+      }
+      return sessionResponse(parsed)
+    }
+    const page = sessionPageResponse(parsed)
+    if (page.contract !== contract || page.sessionId !== session) {
+      throw new CliFailure('session page returned a different identity')
+    }
+    if (throughIndex === undefined) {
+      throughIndex = page.throughIndex
+      snapshots = page.snapshots
+    } else if (
+      page.throughIndex !== throughIndex ||
+      page.snapshots.length > 0
+    ) {
+      throw new CliFailure('session page changed its frozen frontier')
+    }
+    for (const event of page.events) {
+      if (event.index !== events.length + 1 || event.index > throughIndex) {
+        throw new CliFailure('session event pages are not contiguous')
+      }
+      events.push(event)
+    }
+    if (page.cursor === null) break
+    if (
+      page.events.length === 0 ||
+      events.length === throughIndex ||
+      seenCursors.has(page.cursor)
+    ) {
+      throw new CliFailure('session cursor did not advance')
+    }
+    seenCursors.add(page.cursor)
+    cursor = page.cursor
+  }
+  if (throughIndex !== events.length) {
+    throw new CliFailure('session ended before its frozen frontier')
+  }
+  return {
+    protocolVersion: DEVTOOLS_PROTOCOL_VERSION,
+    contract,
+    sessionId: session,
+    revision: await devtoolsSessionRevision({ events, snapshots }),
+    events,
+    snapshots,
+  }
+}
+
+const jsonText = (value: unknown): string =>
+  `${JSON.stringify(value, null, 2)}\n`
+
+const ndjsonText = (values: readonly unknown[]): string =>
+  values.map((value) => JSON.stringify(value)).join('\n') +
+  (values.length === 0 ? '' : '\n')
+
+const humanContracts = (response: DevtoolsContractsResponse): string =>
+  response.contracts.length === 0
+    ? 'No contracts.\n'
+    : `${response.contracts.map((contract) => terminalText(contract.name)).join('\n')}\n`
+
+const humanSessions = (response: DevtoolsSessionsResponse): string => {
+  if (response.sessions.length === 0) return 'No sessions.\n'
+  const rows = response.sessions.map((session) =>
+    [
+      terminalText(session.sessionId),
+      session.eventCount,
+      session.pendingCount,
+      session.failedCount,
+      session.attemptCount,
+      session.failureCount,
+      terminalText(session.updatedAt),
+    ].join('\t'),
+  )
+  return (
+    [
+      'SESSION\tEVENTS\tPENDING\tDEAD\tATTEMPTS\tFAILURES\tUPDATED',
+      ...rows,
+    ].join('\n') + '\n'
+  )
+}
+
+const humanSession = (detail: DevtoolsSessionDetail): string => {
+  const rows = detail.events.map((event) => {
+    const status = event.failedAt
+      ? 'dead-lettered'
+      : event.processedAt
+        ? 'completed'
+        : 'pending'
+    return `${event.index}\t${status}\t${terminalText(event.type)}\t${terminalText(event.id)}`
+  })
+  const heading = `${terminalText(detail.contract)}/${terminalText(detail.sessionId)}: ${detail.events.length} events, ${detail.snapshots.length} snapshots\n`
+  return rows.length === 0
+    ? heading
+    : `${heading}INDEX\tSTATUS\tTYPE\tID\n${rows.join('\n')}\n`
+}
+
+const emitResponse = (
+  format: OutputFormat,
+  value: unknown,
+  ndjson: readonly unknown[],
+  human: string,
+  stdout: (text: string) => void,
+): void => {
+  if (format === 'json') stdout(jsonText(value))
+  else if (format === 'ndjson') stdout(ndjsonText(ndjson))
+  else stdout(human)
+}
+
+const parseAndVerifyCapture = async (
+  bytes: Uint8Array,
+): Promise<DevtoolsCapture> => {
+  let text: string
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch {
+    throw new IntegrityFailure('capture is not valid UTF-8')
+  }
+  try {
+    const capture = parseDevtoolsCapture(text)
+    await verifyDevtoolsCapture(capture)
+    return capture
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new IntegrityFailure(message)
+  }
+}
+
+const captureSummary = (capture: DevtoolsCapture): CheckSummary => {
+  let pendingCount = 0
+  let deadLetterCount = 0
+  let caughtFailureCount = 0
+  let redispatchCount = 0
+  for (const event of capture.events) {
+    if (event.processedAt === null && event.failedAt === null) pendingCount += 1
+    if (event.failedAt !== null) deadLetterCount += 1
+    if (
+      !Number.isSafeInteger(event.failureCount) ||
+      event.failureCount < 0 ||
+      !Number.isSafeInteger(event.attemptCount) ||
+      event.attemptCount < 0
+    ) {
+      throw new IntegrityFailure(
+        `event #${event.index} has invalid attempt or failure counts`,
+      )
+    }
+    caughtFailureCount += event.failureCount
+    redispatchCount += Math.max(0, event.attemptCount - 1)
+  }
+  return {
+    ok: true,
+    contract: capture.contract,
+    sessionId: capture.sessionId,
+    revision: capture.revision,
+    eventCount: capture.events.length,
+    snapshotCount: capture.snapshots.length,
+    pendingCount,
+    deadLetterCount,
+    caughtFailureCount,
+    redispatchCount,
+    failures: [],
+  }
+}
+
+const checkSummary = (
+  capture: DevtoolsCapture,
+  args: ParsedArguments,
+): CheckSummary => {
+  const summary = captureSummary(capture)
+  if (capture.contract !== args.contract) {
+    summary.failures.push(
+      `capture contract '${capture.contract}' does not match '${args.contract}'`,
+    )
+  }
+  if (capture.sessionId !== args.session) {
+    summary.failures.push(
+      `capture session '${capture.sessionId}' does not match '${args.session}'`,
+    )
+  }
+  if (args.settled && summary.pendingCount > 0) {
+    summary.failures.push(`${summary.pendingCount} event(s) are pending`)
+  }
+  if (args.noDeadLetters && summary.deadLetterCount > 0) {
+    summary.failures.push(
+      `${summary.deadLetterCount} event(s) are dead-lettered`,
+    )
+  }
+  if (args.noCaughtFailures && summary.caughtFailureCount > 0) {
+    summary.failures.push(
+      `${summary.caughtFailureCount} caught handler failure(s) were recorded`,
+    )
+  }
+  if (
+    args.maxRedispatches !== undefined &&
+    summary.redispatchCount > args.maxRedispatches
+  ) {
+    summary.failures.push(
+      `${summary.redispatchCount} redispatch(es) exceed the limit of ${args.maxRedispatches}`,
+    )
+  }
+  summary.ok = summary.failures.length === 0
+  return summary
+}
+
+const assertCaptureIdentity = (
+  capture: DevtoolsCapture,
+  contract: string,
+  sessionId: string,
+): void => {
+  if (capture.contract !== contract) {
+    throw new IntegrityFailure(
+      `capture contract '${capture.contract}' does not match '${contract}'`,
+    )
+  }
+  if (capture.sessionId !== sessionId) {
+    throw new IntegrityFailure(
+      `capture session '${capture.sessionId}' does not match '${sessionId}'`,
+    )
+  }
+}
+
+const humanCheck = (summary: CheckSummary, verb: string): string =>
+  `${verb} ${terminalText(summary.contract)}/${terminalText(summary.sessionId)}: ${summary.eventCount} events, ${summary.snapshotCount} snapshots, ${summary.pendingCount} pending, ${summary.deadLetterCount} dead-lettered, ${summary.caughtFailureCount} caught failures, ${summary.redispatchCount} redispatches\n`
+
+const defaultCaptureName = (contract: string, sessionId: string): string => {
+  const safe = `${contract}-${sessionId}`
+    .replaceAll(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 160)
+  return `${safe || 'a2-session'}.a2log`
+}
+
+const errorCode = (error: unknown): string | undefined => {
+  const object = objectValue(error)
+  return typeof object?.['code'] === 'string' ? object['code'] : undefined
+}
+
+const writeCaptureFile = async (
+  path: string,
+  data: Uint8Array,
+  options: { flag: 'w' | 'wx'; mode: number },
+): Promise<void> => {
+  const file = await nodeOpen(path, options.flag, options.mode)
+  try {
+    await file.chmod(options.mode)
+    await file.writeFile(data)
+  } finally {
+    await file.close()
+  }
+}
+
+/** Run the `a2 devtools` command namespace and return its process exit code. */
+export async function runCli(
+  argv: readonly string[],
+  options: DevtoolsCliOptions = {},
+): Promise<number> {
+  const stdout =
+    options.stdout ?? ((text: string) => process.stdout.write(text))
+  const stderr =
+    options.stderr ?? ((text: string) => process.stderr.write(text))
+  const env = options.env ?? process.env
+  const fetcher = options.fetch ?? globalThis.fetch
+  const cwd = options.cwd ?? process.cwd()
+  const readFile = options.readFile ?? nodeReadFile
+  const writeFile = options.writeFile ?? writeCaptureFile
+
+  try {
+    const args = parseArguments(argv)
+    if (args.help || args.command === null) {
+      stdout(USAGE)
+      return 0
+    }
+    assertCommandArguments(args)
+
+    if (args.command === 'verify') {
+      const path = resolve(cwd, args.positionals[0]!)
+      let bytes: Uint8Array
+      try {
+        bytes = await readFile(path)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        throw new CliFailure(`could not read '${path}': ${message}`)
+      }
+      const summary = captureSummary(await parseAndVerifyCapture(bytes))
+      emitResponse(
+        args.format,
+        summary,
+        [summary],
+        humanCheck(summary, 'Verified'),
+        stdout,
+      )
+      return 0
+    }
+
+    const configuredUrl = args.url ?? env['A2_DEVTOOLS_URL']
+    if (!configuredUrl) {
+      fail('--url or A2_DEVTOOLS_URL is required')
+    }
+    const base = baseUrl(configuredUrl!)
+    const headers = requestHeaders(args, env, 'application/json')
+
+    if (args.command === 'contracts') {
+      const text = await responseText(
+        fetcher,
+        resourceUrl(base, 'contracts', {}),
+        headers,
+        'contracts',
+      )
+      const response = contractsResponse(parseJson(text, 'contracts'))
+      emitResponse(
+        args.format,
+        response,
+        response.contracts,
+        humanContracts(response),
+        stdout,
+      )
+      return 0
+    }
+
+    const contract = required(args.contract, '--contract')
+    if (args.command === 'sessions') {
+      const text = await responseText(
+        fetcher,
+        resourceUrl(base, 'sessions', {
+          contract,
+          cursor: args.cursor,
+          limit: args.limit,
+        }),
+        headers,
+        'sessions',
+      )
+      const response = sessionsResponse(parseJson(text, 'sessions'))
+      emitResponse(
+        args.format,
+        response,
+        response.sessions,
+        humanSessions(response),
+        stdout,
+      )
+      return 0
+    }
+
+    const session = required(args.session, '--session')
+    if (args.command === 'show') {
+      const detail = await readSessionDetail(
+        fetcher,
+        base,
+        headers,
+        contract,
+        session,
+      )
+      emitResponse(
+        args.format,
+        detail,
+        [
+          {
+            kind: 'session',
+            protocolVersion: detail.protocolVersion,
+            contract: detail.contract,
+            sessionId: detail.sessionId,
+            revision: detail.revision,
+          },
+          ...detail.events.map((event) => ({ ...event, kind: 'event' })),
+          ...detail.snapshots.map((snapshot) => ({
+            ...snapshot,
+            kind: 'snapshot',
+          })),
+        ],
+        humanSession(detail),
+        stdout,
+      )
+      return 0
+    }
+
+    const exportHeaders = requestHeaders(args, env, 'application/x-ndjson')
+    const captureBytes = await responseBytes(
+      fetcher,
+      resourceUrl(base, 'export', { contract, session }),
+      exportHeaders,
+      'export',
+    )
+    const capture = await parseAndVerifyCapture(captureBytes)
+
+    if (args.command === 'check') {
+      const summary = checkSummary(capture, args)
+      emitResponse(
+        args.format,
+        summary,
+        [summary],
+        humanCheck(summary, summary.ok ? 'Checked' : 'Check failed for'),
+        stdout,
+      )
+      if (!summary.ok) {
+        for (const failure of summary.failures) {
+          stderr(`a2 devtools: ${terminalText(failure)}\n`)
+        }
+        return DEVTOOLS_CLI_EXIT_CHECK_FAILED
+      }
+      return 0
+    }
+
+    assertCaptureIdentity(capture, contract, session)
+
+    const output = resolve(
+      cwd,
+      args.output ?? defaultCaptureName(contract, session),
+    )
+    try {
+      await writeFile(output, captureBytes, {
+        flag: args.force ? 'w' : 'wx',
+        mode: 0o600,
+      })
+    } catch (error) {
+      if (errorCode(error) === 'EEXIST') {
+        throw new CliFailure(
+          `'${output}' already exists; pass --force to replace it`,
+        )
+      }
+      const message = error instanceof Error ? error.message : String(error)
+      throw new CliFailure(`could not write '${output}': ${message}`)
+    }
+    const result = {
+      path: output,
+      contract: capture.contract,
+      sessionId: capture.sessionId,
+      eventCount: capture.events.length,
+      snapshotCount: capture.snapshots.length,
+      sha256: capture.footer.sha256,
+    }
+    emitResponse(
+      args.format,
+      result,
+      [result],
+      `Exported ${terminalText(capture.contract)}/${terminalText(capture.sessionId)}: ${capture.events.length} events, ${capture.snapshots.length} snapshots -> ${terminalText(output)}\n`,
+      stdout,
+    )
+    return 0
+  } catch (error) {
+    const failure =
+      error instanceof CliFailure
+        ? error
+        : new CliFailure(error instanceof Error ? error.message : String(error))
+    stderr(`a2 devtools: ${terminalText(failure.message)}\n`)
+    return failure.exitCode
+  }
+}