cli.ts

import { resolveRemoteRequestDiagnosticsPath } from '@agent-device/daemon-contracts/session-artifact-paths';
import { parseRawArgs, usage, usageForCommand } from './cli/parser/args.ts';
import { suggestCommandFor } from './cli/parser/command-suggestions.ts';
import {
  asAppError,
  AppError,
  normalizeError,
  type NormalizedError,
} from '@agent-device/kernel/errors';
import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution';
import { withCommandHost } from '@agent-device/host-kit/command';
import { captureHostEnvironment } from '@agent-device/host-kit/process';
import type { HostEnvironment } from '@agent-device/kernel/source-value';
import { exitAfterFlush } from './cli/process-exit.ts';
import { readVersion } from '@agent-device/host-kit/version';
import { pathToFileURL } from 'node:url';
import {
  createDaemonTransport,
  resolveRunTransport,
  sendToDaemon,
} from './daemon-client/daemon-client.ts';
import fs from 'node:fs';
import type { BatchStep } from '@agent-device/contracts/client';
import type { ReplayTestReporterRuntime } from './cli/replay-test/reporting.ts';
import {
  createCommandProgressState,
  createStderrCommandProgressSink,
  type CommandProgressState,
} from './commands/command-progress.ts';
import {
  createAgentDeviceClient,
  type AgentDeviceClientConfig,
  type AgentDeviceDaemonTransport,
} from './agent-device-client.ts';
import { tryRunClientBackedCommand } from './cli/commands/router.ts';
import { runAgentCdpCommand } from './cli/commands/agent-cdp.ts';
import { readCliBatchStepsJson } from './commands/batch/batch-steps.ts';
import {
  createRequestId,
  emitDiagnostic,
  flushDiagnosticsToSessionFile,
  getDiagnosticsMeta,
  registerDiagnosticSensitiveValue,
  withDiagnosticsScope,
} from '@agent-device/host-kit/diagnostics';
import { applyDefaultPlatformBinding, resolveBindingSettings } from './cli/session-binding.ts';
import { resolveCliOptions } from './cli/resolve-cli-options.ts';
import { maybeRunUpgradeNotifier } from './cli/update-check.ts';
import {
  resolveRemoteConnectionDefaults,
  type RemoteConnectionRequestMetadata,
} from '@agent-device/remote/remote-connection-state';
import { resolveRemoteAuthForCli } from './cli/auth-session.ts';
import type { FlagKey } from '@agent-device/command-registry/flag-types';
import type { CliFlags } from '@agent-device/contracts/command';
import type { SessionRuntimeHints } from '@agent-device/kernel/contracts';
import { isKnownCliCommandName } from '@agent-device/command-registry/catalog';

type CliDeps = {
  sendToDaemon: typeof sendToDaemon;
  /** Builds the transport that talks as a given host; injected deps leave it out. */
  transportForHost?: (host: HostEnvironment) => typeof sendToDaemon;
};

type CliDaemonTransport = typeof sendToDaemon;
type CliDaemonRequest = Parameters<CliDaemonTransport>[0];
type CliDaemonTransportOptions = Parameters<CliDaemonTransport>[1];
type ClientDaemonRequest = Parameters<AgentDeviceDaemonTransport>[0];

const DEFAULT_CLI_DEPS: CliDeps = {
  sendToDaemon,
  transportForHost: createDaemonTransport,
};

const printHumanError = (
  err: AppError | NormalizedError,
  options: { showDetails?: boolean } = {},
): Promise<void> =>
  import('./commands/output/error.ts').then(({ printHumanError: write }) => write(err, options));

const printJson = (
  result: { success: true; data?: unknown } | { success: false; error: NormalizedError },
): Promise<void> =>
  import('./commands/output/json.ts').then(({ printJson: write }) => write(result));

const METRO_RUNTIME_OVERRIDE_FLAG_KEYS = new Set<FlagKey>([
  'launchUrl',
  'kind',
  'metroBearerToken',
  'metroKind',
  'metroListenHost',
  'metroNoInstallDeps',
  'metroNoReuseExisting',
  'metroPreparePort',
  'metroProbeTimeoutMs',
  'metroProjectRoot',
  'metroProxyBaseUrl',
  'metroPublicBaseUrl',
  'metroRuntimeFile',
  'metroStartupTimeoutMs',
  'metroStatusHost',
]);

const REMOTE_MATERIALIZATION_DEFERRED_COMMANDS = new Set([
  'connect',
  'connection',
  'close',
  'daemon',
  'plugins',
  'device',
  'disconnect',
  'metro',
  'proxy',
  'session',
  'takeover',
]);

export async function runCli(
  argv: string[],
  deps: CliDeps = DEFAULT_CLI_DEPS,
  host: HostEnvironment = captureHostEnvironment(process),
): Promise<void> {
  await withCommandHost(
    { host, requestEnv: undefined },
    async () => await runCliOnHost(argv, deps, host),
  );
}

async function runCliOnHost(argv: string[], deps: CliDeps, host: HostEnvironment): Promise<void> {
  const requestId = createRequestId();
  const version = readVersion();
  const debugEnabled = isDebugRequested(argv);
  const jsonRequested = argv.includes('--json');
  // Best-effort session guess used only for pre-parse diagnostics scope.
  // After parse succeeds, request dispatch uses parsed flags/session resolution.
  const sessionGuess = guessSessionFromArgv(argv) ?? host.env.AGENT_DEVICE_SESSION ?? 'default';

  await withDiagnosticsScope(
    {
      session: sessionGuess,
      requestId,
      command: argv[0],
      debug: debugEnabled,
    },
    async () => {
      const { parsed, command, positionals } = await parseCliInputOrExit(argv, {
        host,
        version,
        jsonRequested,
        debugEnabled,
      });
      const debugOutputEnabled = isParsedDebugRequested(command, parsed.providedFlags);
      const ctx = await resolveRunContextOrExit(parsed, {
        host,
        command,
        positionals,
        requestId,
        debugOutputEnabled,
      });
      registerDaemonAuthDiagnosticValue(ctx.effectiveFlags);
      let logTailStopper: (() => void) | null = null;
      try {
        if (command === 'react-devtools') {
          await exitAfterFlush(await runReactDevtoolsCli(ctx));
          return;
        }
        if (command === 'web') {
          const { runWebCommand } = await import('./cli/commands/web.ts');
          await exitAfterFlush(
            await runWebCommand(positionals, {
              flags: ctx.effectiveFlags,
              stateDir: ctx.daemonPaths.baseDir,
            }),
          );
          return;
        }
        maybeRunUpgradeNotifier({
          command,
          currentVersion: version,
          stateDir: ctx.daemonPaths.baseDir,
          flags: ctx.effectiveFlags,
        });
        await resolveRemoteContext(ctx, deps);
        registerDaemonAuthDiagnosticValue(ctx.effectiveFlags);
        if (command === 'cdp') {
          await exitAfterFlush(
            await runAgentCdpCommand(positionals, {
              flags: ctx.effectiveFlags,
              runtime: ctx.resolvedRuntime,
              cwd: host.cwd,
              env: host.env,
            }),
          );
          return;
        }
        logTailStopper = maybeStartDaemonLogTail(ctx);
        const replayTestReporterRuntime = await createReplayReporterForTest(ctx);
        const commandProgress = createCommandProgressState();
        const client = createAgentDeviceClient(buildClientConfig(ctx), {
          host: ctx.host,
          transport: createCliDaemonTransport({
            command,
            flags: ctx.effectiveFlags,
            replayTestReporterRuntime,
            commandProgress,
            transport: resolveRunTransport(deps, host),
          }),
        });
        await dispatchCliCommand(ctx, client, replayTestReporterRuntime, commandProgress);
      } catch (error) {
        await handleRunCliFailure(error, ctx, logTailStopper);
      } finally {
        if (logTailStopper) logTailStopper();
      }
    },
  );
}

function registerDaemonAuthDiagnosticValue(flags: CliFlags): void {
  if (flags.daemonAuthToken) registerDiagnosticSensitiveValue(flags.daemonAuthToken);
}

type ParsedCliInput = {
  parsed: ReturnType<typeof resolveCliOptions>;
  command: string;
  positionals: string[];
};

async function parseCliInputOrExit(
  argv: string[],
  options: {
    host: HostEnvironment;
    version: string;
    jsonRequested: boolean;
    debugEnabled: boolean;
  },
): Promise<ParsedCliInput> {
  let parsed: ReturnType<typeof resolveCliOptions>;
  try {
    parsed = resolveCliOptions(argv, { cwd: options.host.cwd, env: options.host.env });
  } catch (error) {
    emitDiagnostic({
      level: 'error',
      phase: 'cli_parse_failed',
      data: {
        error: error instanceof Error ? error.message : String(error),
      },
    });
    const normalized = normalizeError(error, {
      diagnosticId: getDiagnosticsMeta().diagnosticId,
      logPath: flushDiagnosticsToSessionFile({ force: true })?.path,
    });
    if (options.jsonRequested) {
      await printJson({ success: false, error: normalized });
    } else {
      await printHumanError(normalized, { showDetails: options.debugEnabled });
    }
    return exitAfterFlush(1);
  }

  for (const warning of parsed.warnings) {
    process.stderr.write(`Warning: ${warning}\n`);
  }

  if (parsed.flags.version) {
    process.stdout.write(`${options.version}\n`);
    return exitAfterFlush(0);
  }

  const isHelpAlias = parsed.command === 'help';
  const isHelpFlag = parsed.flags.help;
  if (isHelpAlias || isHelpFlag) {
    if (isHelpAlias && parsed.positionals.length > 1) {
      await printHumanError(new AppError('INVALID_ARGS', 'help accepts at most one command.'));
      return exitAfterFlush(1);
    }
    const helpTarget = isHelpAlias ? parsed.positionals[0] : parsed.command;
    if (!helpTarget) {
      process.stdout.write(`${await usage()}\n`);
      return exitAfterFlush(0);
    }
    const commandHelp = await usageForCommand(helpTarget);
    if (commandHelp) {
      process.stdout.write(commandHelp);
      return exitAfterFlush(0);
    }
    await printHumanError(new AppError('INVALID_ARGS', formatUnknownHelpTargetMessage(helpTarget)));
    process.stdout.write(`${await usage()}\n`);
    return exitAfterFlush(1);
  }

  if (!parsed.command) {
    process.stdout.write(`${await usage()}\n`);
    return exitAfterFlush(1);
  }

  return { parsed, command: parsed.command, positionals: parsed.positionals };
}

type CliRunContext = {
  host: HostEnvironment;
  command: string;
  positionals: string[];
  requestId: string;
  debugOutputEnabled: boolean;
  binding: ReturnType<typeof resolveBindingSettings>;
  // Flags after platform binding but before connection-default merge; batch
  // step inheritance keys off this pre-merge view.
  flags: CliFlags;
  daemonPaths: ReturnType<typeof resolveDaemonPaths>;
  sessionName: string;
  connectionDefaults: ReturnType<typeof resolveActiveConnectionDefaults>;
  explicitFlagKeys: Set<FlagKey>;
  // Mutated in place by resolveRemoteContext (auth, materialization) so the
  // failure handler always sees the same state the throwing phase saw.
  effectiveFlags: CliFlags;
  resolvedRuntime: SessionRuntimeHints | undefined;
  connectionMetadata: RemoteConnectionRequestMetadata | undefined;
  parsedBatchSteps: BatchStep[] | undefined;
};

async function resolveRunContextOrExit(
  parsed: ReturnType<typeof resolveCliOptions>,
  base: {
    host: HostEnvironment;
    command: string;
    positionals: string[];
    requestId: string;
    debugOutputEnabled: boolean;
  },
): Promise<CliRunContext> {
  const explicitFlagKeys = new Set(parsed.providedFlags.map((entry) => entry.key));
  try {
    const binding = resolveBindingSettings({
      policyOverrides: parsed.flags,
      configuredPlatform: parsed.flags.platform,
      configuredSession: parsed.flags.session,
    });
    const flags = binding.lockPolicy
      ? { ...parsed.flags }
      : applyDefaultPlatformBinding(parsed.flags, {
          policyOverrides: parsed.flags,
          configuredPlatform: parsed.flags.platform,
          configuredSession: parsed.flags.session,
        });
    const daemonPaths = resolveDaemonPaths(flags.stateDir, {
      env: base.host.env,
      cwd: base.host.cwd,
    });
    const sessionName = flags.session ?? 'default';
    const connectionDefaults = resolveActiveConnectionDefaults({
      host: base.host,
      command: base.command,
      explicitFlagKeys,
      stateDir: daemonPaths.baseDir,
      session: sessionName,
      remoteConfig: flags.remoteConfig,
      hasResolvedSession: flags.session !== undefined,
    });
    const effectiveFlags = connectionDefaults
      ? mergeConnectionFlags(flags, connectionDefaults.flags, explicitFlagKeys)
      : flags;
    return {
      ...base,
      binding,
      flags,
      daemonPaths,
      sessionName,
      connectionDefaults,
      explicitFlagKeys,
      effectiveFlags,
      resolvedRuntime: connectionDefaults?.runtime,
      connectionMetadata: connectionDefaults?.connection,
      parsedBatchSteps: undefined,
    };
  } catch (error) {
    const appErr = asAppError(error);
    const normalized = normalizeError(appErr, {
      diagnosticId: getDiagnosticsMeta().diagnosticId,
      logPath: flushDiagnosticsToSessionFile({ force: true })?.path,
    });
    if (parsed.flags.json) {
      await printJson({ success: false, error: normalized });
    } else {
      await printHumanError(normalized, { showDetails: base.debugOutputEnabled });
    }
    return exitAfterFlush(1);
  }
}

async function runReactDevtoolsCli(ctx: CliRunContext): Promise<number> {
  const { runReactDevtoolsCommand } = await import('./cli/commands/react-devtools.ts');
  return await runReactDevtoolsCommand(ctx.positionals, {
    flags: ctx.effectiveFlags,
    stateDir: ctx.daemonPaths.baseDir,
    session: ctx.effectiveFlags.session ?? ctx.sessionName,
  });
}

async function resolveRemoteContext(ctx: CliRunContext, deps: CliDeps): Promise<void> {
  if (ctx.command === 'batch') {
    if (ctx.positionals.length > 0) {
      throw new AppError('INVALID_ARGS', 'batch does not accept positional arguments.');
    }
    ctx.parsedBatchSteps = readBatchSteps(ctx.flags);
  }

  if (shouldResolveRemoteAuth(ctx.command)) {
    const authResolution = await resolveRemoteAuthForCli({
      command: ctx.command,
      flags: ctx.effectiveFlags,
      stateDir: ctx.daemonPaths.baseDir,
      env: ctx.host.env,
    });
    ctx.effectiveFlags = authResolution.flags;
  }

  if (ctx.effectiveFlags.remoteConfig && shouldMaterializeRemoteConnection(ctx.command)) {
    const materializationClient = createAgentDeviceClient(buildClientConfig(ctx), {
      host: ctx.host,
      transport: createClientDaemonTransport(resolveRunTransport(deps, ctx.host)),
    });
    const { materializeRemoteConnectionForCommand } =
      await import('./cli/commands/connection-runtime.ts');
    const materialized = await materializeRemoteConnectionForCommand({
      command: ctx.command,
      flags: ctx.effectiveFlags,
      client: materializationClient,
      runtime: ctx.resolvedRuntime,
      positionals: ctx.positionals,
      batchSteps: ctx.parsedBatchSteps,
      forceRuntimePrepare: hasExplicitMetroRuntimeOverrides(ctx.explicitFlagKeys),
    });
    ctx.effectiveFlags = materialized.flags;
    ctx.resolvedRuntime = materialized.runtime;
    ctx.connectionMetadata = materialized.connection;
  }
  if (
    shouldWarnOpenMayMissRemoteRuntime({
      command: ctx.command,
      flags: ctx.effectiveFlags,
      runtime: ctx.resolvedRuntime,
      explicitFlagKeys: ctx.explicitFlagKeys,
      hadConnectionDefaults: Boolean(ctx.connectionDefaults),
    })
  ) {
    process.stderr.write(
      'Warning: open is using explicit remote daemon or tenant flags without saved Metro runtime hints. React Native apps may launch without bundle/runtime hints; prefer connect --remote-config <path> first or pass --remote-config <path> on this command.\n',
    );
  }
}

function buildClientConfig(ctx: CliRunContext): AgentDeviceClientConfig {
  const currentFlags = ctx.effectiveFlags;
  const connection = ctx.connectionMetadata;
  return {
    session: currentFlags.session,
    requestId: ctx.requestId,
    stateDir: currentFlags.stateDir,
    daemonBaseUrl: currentFlags.daemonBaseUrl,
    daemonAuthToken: currentFlags.daemonAuthToken,
    daemonTransport: currentFlags.daemonTransport,
    daemonServerMode: currentFlags.daemonServerMode,
    tenant: currentFlags.tenant,
    sessionIsolation: currentFlags.sessionIsolation,
    runId: currentFlags.runId,
    leaseId: currentFlags.leaseId,
    leaseBackend: currentFlags.leaseBackend,
    leaseProvider: connection?.leaseProvider,
    clientId: connection?.clientId,
    deviceKey: connection?.deviceKey,
    providerApp: currentFlags.providerApp,
    providerOsVersion: currentFlags.providerOsVersion,
    providerDeviceType: currentFlags.providerDeviceType,
    providerProject: currentFlags.providerProject,
    providerBuild: currentFlags.providerBuild,
    providerSessionName: currentFlags.providerSessionName,
    providerDeviceOrientation: currentFlags.providerDeviceOrientation,
    providerGeoLocation: currentFlags.providerGeoLocation,
    providerTimezone: currentFlags.providerTimezone,
    providerAppiumVersion: currentFlags.providerAppiumVersion,
    providerLanguage: currentFlags.providerLanguage,
    providerLocale: currentFlags.providerLocale,
    providerNetworkProfile: currentFlags.providerNetworkProfile,
    providerCustomNetwork: currentFlags.providerCustomNetwork,
    providerNoResignApp: currentFlags.providerNoResignApp,
    awsProjectArn: currentFlags.awsProjectArn,
    awsDeviceArn: currentFlags.awsDeviceArn,
    awsAppArn: currentFlags.awsAppArn,
    awsRegion: currentFlags.awsRegion,
    awsInteractionMode: currentFlags.awsInteractionMode,
    runtime: ctx.resolvedRuntime,
    lockPolicy: ctx.binding.lockPolicy,
    lockPlatform: ctx.binding.defaultPlatform,
    cwd: ctx.host.cwd,
    debug: ctx.debugOutputEnabled,
    cost: currentFlags.cost,
    responseLevel: currentFlags.responseLevel,
  };
}

function maybeStartDaemonLogTail(ctx: CliRunContext): (() => void) | null {
  const remoteDaemonBaseUrl = ctx.effectiveFlags.daemonBaseUrl;
  return ctx.debugOutputEnabled && !ctx.effectiveFlags.json && !remoteDaemonBaseUrl
    ? startDaemonLogTail(ctx.daemonPaths.logPath)
    : null;
}

async function createReplayReporterForTest(
  ctx: CliRunContext,
): Promise<ReplayTestReporterRuntime | undefined> {
  if (ctx.command !== 'test') return undefined;
  // Lazy: the replay test reporter is only needed by `test`, and its
  // static import would put the reporting runtime on every command's path.
  const { createReplayTestReporterRuntime } = await import('./cli/replay-test/reporting.ts');
  return createReplayTestReporterRuntime({
    debug: ctx.debugOutputEnabled,
    verbose: ctx.effectiveFlags.verbose,
    json: ctx.effectiveFlags.json,
    reporter: ctx.effectiveFlags.reporter,
    reportJunit: ctx.effectiveFlags.reportJunit,
  });
}

async function dispatchCliCommand(
  ctx: CliRunContext,
  client: ReturnType<typeof createAgentDeviceClient>,
  replayTestReporterRuntime: ReplayTestReporterRuntime | undefined,
  commandProgress: CommandProgressState,
): Promise<void> {
  const { command, positionals, effectiveFlags } = ctx;
  if (command === 'batch') {
    if (!ctx.parsedBatchSteps) {
      throw new AppError('INVALID_ARGS', 'batch requires --steps or --steps-file.');
    }
    const batchSteps = ctx.parsedBatchSteps.map((step, _index) => ({
      ...step,
      input:
        ctx.binding.lockPolicy && ctx.flags.platform === undefined
          ? { ...step.input }
          : applyDefaultPlatformBinding(step.input, {
              policyOverrides: effectiveFlags,
              configuredPlatform: effectiveFlags.platform,
              configuredSession: effectiveFlags.session,
              inheritedPlatform: effectiveFlags.platform,
            }),
    }));
    if (
      await tryRunClientBackedCommand({
        command,
        positionals,
        flags: { ...effectiveFlags, batchSteps },
        client,
        debug: ctx.debugOutputEnabled,
        replayTestReporterRuntime,
        commandProgress,
      })
    ) {
      return;
    }
  } else if (command === 'runtime') {
    throw new AppError(
      'INVALID_ARGS',
      'runtime command was removed. Use connect --remote-config <path> for remote runs, or metro prepare --remote-config <path> for inspection.',
    );
  } else if (
    await tryRunClientBackedCommand({
      command,
      positionals,
      flags: effectiveFlags,
      client,
      debug: ctx.debugOutputEnabled,
      replayTestReporterRuntime,
      commandProgress,
    })
  ) {
    return;
  }

  throw new AppError('INVALID_ARGS', formatUnhandledCommandMessage(command));
}

async function handleRunCliFailure(
  err: unknown,
  ctx: CliRunContext,
  logTailStopper: (() => void) | null,
): Promise<void> {
  const appErr = asAppError(err);
  const normalized = normalizeError(appErr, {
    diagnosticId: getDiagnosticsMeta().diagnosticId,
    logPath: flushDiagnosticsToSessionFile({ force: true })?.path,
  });
  if (ctx.command === 'close' && isDaemonStartupFailure(appErr)) {
    if (ctx.effectiveFlags.json) {
      await printJson({ success: true, data: { closed: 'session', source: 'no-daemon' } });
    }
    return;
  }
  if (ctx.effectiveFlags.json) {
    await printJson({
      success: false,
      error: normalized,
    });
  } else {
    await printHumanError(normalized, { showDetails: ctx.debugOutputEnabled });
    if (ctx.debugOutputEnabled) {
      printFailureLogTail(ctx, normalized);
    }
  }
  if (logTailStopper) logTailStopper();
  // #1596: a bare `process.exit()` right after these writes can drop them —
  // Node flushes stdout/stderr synchronously only to a file or TTY, and this
  // CLI is commonly piped by whatever is driving it. `exitAfterFlush` waits
  // for the writes above to actually reach the pipe first.
  await exitAfterFlush(1);
}

const DAEMON_LOG_TAIL_MAX_BYTES = 64_000;

/**
 * The evidence `--debug` puts inline in the caller's own log after a failure.
 *
 * For a LOCAL daemon that is the daemon log this process can read. For a REMOTE
 * one that file belongs to another machine (the same reason
 * `maybeStartDaemonLogTail` does not follow it), so the tail comes from the
 * request record fetched to this host instead — which is what makes a CI job's
 * transcript carry the evidence without a second round trip (#1801).
 */
function printFailureLogTail(ctx: CliRunContext, normalized: NormalizedError): void {
  if (!ctx.effectiveFlags.daemonBaseUrl) {
    printLogFileTail('daemon log', ctx.daemonPaths.logPath);
    return;
  }
  const record = normalized.diagnosticsRecord;
  if (!record) return;
  // Recomputed from the locator through the same helper that wrote the copy, so
  // the tail can only ever come from the fetched record (absent when the fetch
  // failed, since nothing was written).
  printLogFileTail(
    'remote diagnostics',
    resolveRemoteRequestDiagnosticsPath(ctx.daemonPaths.baseDir, record),
  );
}

function printLogFileTail(label: string, logPath: string): void {
  try {
    if (fs.existsSync(logPath)) {
      const content = fs.readFileSync(logPath, 'utf8');
      const lines = content.split('\n');
      let tail = lines.slice(Math.max(0, lines.length - 200)).join('\n');
      if (tail.length > DAEMON_LOG_TAIL_MAX_BYTES) {
        tail = tail.slice(tail.length - DAEMON_LOG_TAIL_MAX_BYTES);
      }
      if (tail.trim().length > 0) {
        process.stderr.write(`\n[${label}]\n${tail}\n`);
      }
    }
  } catch {}
}

function isDebugRequested(argv: string[]): boolean {
  try {
    const parsed = parseRawArgs(argv);
    return isParsedDebugRequested(parsed.command ?? '', parsed.providedFlags);
  } catch {
    return argv.includes('--debug') || argv.includes('-v') || argv.includes('--verbose');
  }
}

function formatUnknownHelpTargetMessage(helpTarget: string): string {
  const hint = suggestCommandFor(helpTarget);
  return hint
    ? `Unknown command: ${helpTarget}. Did you mean ${hint}?`
    : `Unknown command: ${helpTarget}`;
}

function formatUnhandledCommandMessage(command: string): string {
  if (isKnownCliCommandName(command)) {
    // Registered-but-unhandled means catalog/dispatch drift — make it visible
    // in telemetry too, not just the thrown message (from #1055).
    emitDiagnostic({
      level: 'error',
      phase: 'cli_known_command_unhandled',
      data: { command },
    });
    return `Command is registered but no CLI handler accepted it: ${command}`;
  }
  return `Unknown command: ${command}`;
}

function isParsedDebugRequested(
  command: string,
  providedFlags: Array<{ key: FlagKey; token: string }>,
): boolean {
  return providedFlags.some(
    (entry) =>
      entry.key === 'verbose' &&
      (entry.token === '--debug' || entry.token === '-v' || command !== 'test'),
  );
}

function readBatchSteps(flags: ReturnType<typeof resolveCliOptions>['flags']): BatchStep[] {
  let raw = '';
  if (flags.steps) {
    raw = flags.steps;
  } else if (flags.stepsFile) {
    try {
      raw = fs.readFileSync(flags.stepsFile, 'utf8');
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      throw new AppError(
        'INVALID_ARGS',
        `Failed to read --steps-file ${flags.stepsFile}: ${message}`,
      );
    }
  }
  return readCliBatchStepsJson(raw);
}

function isDaemonStartupFailure(error: AppError): boolean {
  if (error.code !== 'COMMAND_FAILED') return false;
  if (error.details?.kind === 'daemon_startup_failed') return true;
  if (!error.message.toLowerCase().includes('failed to start daemon')) return false;
  return typeof error.details?.infoPath === 'string' || typeof error.details?.lockPath === 'string';
}

function resolveActiveConnectionDefaults(options: {
  host: HostEnvironment;
  command: string;
  explicitFlagKeys: Set<FlagKey>;
  stateDir: string;
  session: string;
  remoteConfig?: string;
  hasResolvedSession: boolean;
}): {
  flags: Partial<CliFlags>;
  runtime?: SessionRuntimeHints;
  connection?: RemoteConnectionRequestMetadata;
} | null {
  if (
    options.command === 'connect' ||
    options.command === 'connection' ||
    options.command === 'daemon' ||
    options.command === 'plugins' ||
    options.command === 'proxy'
  ) {
    return null;
  }
  const defaults = resolveRemoteConnectionDefaults({
    stateDir: options.stateDir,
    session: options.session,
    remoteConfig: options.remoteConfig,
    cwd: options.host.cwd,
    env: options.host.env,
    allowActiveFallback:
      !options.explicitFlagKeys.has('session') &&
      (!options.remoteConfig || options.command === 'disconnect' || !options.hasResolvedSession),
    validateRemoteConfigHash: options.command !== 'disconnect',
  });
  return defaults;
}

function shouldMaterializeRemoteConnection(command: string): boolean {
  return !REMOTE_MATERIALIZATION_DEFERRED_COMMANDS.has(command);
}

function shouldResolveRemoteAuth(command: string): boolean {
  return (
    command !== 'auth' &&
    command !== 'connection' &&
    command !== 'daemon' &&
    command !== 'plugins' &&
    command !== 'device' &&
    command !== 'proxy'
  );
}

function shouldWarnOpenMayMissRemoteRuntime(options: {
  command: string;
  flags: CliFlags;
  runtime?: SessionRuntimeHints;
  explicitFlagKeys: Set<FlagKey>;
  hadConnectionDefaults: boolean;
}): boolean {
  if (options.command !== 'open') return false;
  if (options.runtime) return false;
  if (options.flags.bundleUrl || options.flags.metroHost || options.flags.metroPort) return false;
  if (options.flags.remoteConfig) return false;
  if (options.hadConnectionDefaults) return false;
  return hasExplicitRemoteScopeFlags(options.explicitFlagKeys);
}

function hasExplicitRemoteScopeFlags(explicitFlagKeys: Set<FlagKey>): boolean {
  return (
    explicitFlagKeys.has('daemonBaseUrl') ||
    explicitFlagKeys.has('daemonTransport') ||
    explicitFlagKeys.has('tenant') ||
    explicitFlagKeys.has('sessionIsolation') ||
    explicitFlagKeys.has('runId') ||
    explicitFlagKeys.has('leaseId') ||
    explicitFlagKeys.has('leaseBackend')
  );
}

function mergeConnectionFlags(
  flags: CliFlags,
  defaults: Partial<CliFlags>,
  explicitFlagKeys: Set<FlagKey>,
): CliFlags {
  const merged = { ...flags };
  for (const [key, value] of Object.entries(defaults) as Array<[FlagKey, unknown]>) {
    if (value === undefined) continue;
    if (explicitFlagKeys.has(key)) continue;
    (merged as Record<string, unknown>)[key] = value;
  }
  return merged;
}

function hasExplicitMetroRuntimeOverrides(explicitFlagKeys: Set<FlagKey>): boolean {
  for (const key of METRO_RUNTIME_OVERRIDE_FLAG_KEYS) {
    if (explicitFlagKeys.has(key)) {
      return true;
    }
  }
  return false;
}

type CliDaemonTransportSetup = {
  command: string;
  flags: CliFlags;
  replayTestReporterRuntime?: ReplayTestReporterRuntime;
  commandProgress: CommandProgressState;
  transport: CliDaemonTransport;
};

/**
 * A remote connection reads each daemon reply for the leases its request ended, and forgets the
 * stored lease when the reply names it.
 */
function createCliDaemonTransport(options: CliDaemonTransportSetup): AgentDeviceDaemonTransport {
  const send = createCliProgressTransport(options);
  if (!options.flags.remoteConfig) return send;
  return async (req, context) => {
    const response = await send(req, context);
    const { forgetEndedProxyLease } = await import('./cli/connection/ended-lease.ts');
    forgetEndedProxyLease(options.flags, response);
    return response;
  };
}

/**
 * The human CLI renders streamed progress itself: `test` hands its events to the
 * replay-test reporter, every other command streams `command` lines to stderr
 * through `commandProgress`, whose state the output formatters then read (a
 * doctor summary does not repeat checks progress already printed). `--json` opts
 * out of progress entirely, so it installs no sink.
 */
function createCliProgressTransport(options: CliDaemonTransportSetup): AgentDeviceDaemonTransport {
  const { command, flags, replayTestReporterRuntime, transport } = options;
  if (flags.json) return createClientDaemonTransport(transport);
  const onProgress =
    command === 'test' && replayTestReporterRuntime
      ? replayTestReporterRuntime.onProgress
      : createStderrCommandProgressSink(options.commandProgress);
  return async (req, context) => {
    const transportOptions = { ...context, onProgress };
    return await sendClientRequestToCliTransport(
      transport,
      {
        ...req,
        meta: {
          ...req.meta,
          requestProgress: command === 'test' ? 'replay-test' : 'command',
        },
      },
      transportOptions,
    );
  };
}

function createClientDaemonTransport(transport: CliDaemonTransport): AgentDeviceDaemonTransport {
  return async (req, context) => await sendClientRequestToCliTransport(transport, req, context);
}

async function sendClientRequestToCliTransport(
  transport: CliDaemonTransport,
  req: ClientDaemonRequest,
  options?: CliDaemonTransportOptions,
): ReturnType<CliDaemonTransport> {
  return await transport(req as CliDaemonRequest, options);
}

function guessSessionFromArgv(argv: string[]): string | null {
  for (let i = 0; i < argv.length; i += 1) {
    const token = argv[i]!;
    if (token.startsWith('--session=')) {
      const inline = token.slice('--session='.length).trim();
      return inline.length > 0 ? inline : null;
    }
    if (token === '--session') {
      const value = argv[i + 1]?.trim();
      if (value && !value.startsWith('-')) return value;
      return null;
    }
  }
  return null;
}

const isDirectRun = pathToFileURL(process.argv[1] ?? '').href === import.meta.url;
if (isDirectRun) {
  runCli(process.argv.slice(2)).catch(async (error) => {
    const appErr = asAppError(error);
    await printHumanError(normalizeError(appErr), { showDetails: true });
    await exitAfterFlush(1);
  });
}

function startDaemonLogTail(logPath: string): (() => void) | null {
  try {
    let offset = fs.existsSync(logPath) ? fs.statSync(logPath).size : 0;
    let stopped = false;
    const interval = setInterval(() => {
      if (stopped) return;
      if (!fs.existsSync(logPath)) return;
      try {
        const stats = fs.statSync(logPath);
        if (stats.size < offset) offset = 0;
        if (stats.size <= offset) return;
        const fd = fs.openSync(logPath, 'r');
        try {
          const buffer = Buffer.alloc(stats.size - offset);
          fs.readSync(fd, buffer, 0, buffer.length, offset);
          offset = stats.size;
          if (buffer.length > 0) {
            process.stdout.write(buffer.toString('utf8'));
          }
        } finally {
          fs.closeSync(fd);
        }
      } catch {
        // Best-effort tailing should not crash CLI flow.
      }
    }, 200);
    return () => {
      stopped = true;
      clearInterval(interval);
    };
  } catch {
    return null;
  }
}