refactor: absorb CLI parser into cli/parser/ — Phase 5

fallow-baselines/health.json

@@ -529,7 +529,7 @@
         "count": 1
       }
     },
-    "src/utils/args.ts": {
+    "src/cli/parser/args.ts": {
       "complexity_critical": {
         "count": 2
       },
@@ -707,7 +707,7 @@
     "src/replay/script-utils.ts:high impact",
     "src/daemon/handlers/session-open-target.ts:high impact",
     "src/utils/selector-is-predicates.ts:high impact",
-    "src/utils/args.ts:high impact",
+    "src/cli/parser/args.ts:high impact",
     "src/daemon/snapshot-presentation/tree.ts:high impact",
     "src/utils/rect-center.ts:high impact",
     "src/utils/process-identity.ts:high impact",

scripts/integration-progress-model.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { PUBLIC_COMMANDS } from '../src/command-catalog.ts';
 import { listCommandMetadata } from '../src/commands/command-metadata.ts';
-import { getFlagDefinitions } from '../src/utils/cli-flags.ts';
+import { getFlagDefinitions } from '../src/cli/parser/cli-flags.ts';
 
 const EMPTY_COVERAGE_METRIC = { pct: 0 };
 const EMPTY_STATEMENT_COVERAGE = { covered: 0, pct: 0, total: 0 };

src/__tests__/cli-grammar.test.ts

@@ -1,7 +1,7 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { readInputFromCli } from '../commands/cli-grammar.ts';
-import type { CliFlags } from '../utils/cli-flags.ts';
+import type { CliFlags } from '../cli/parser/cli-flags.ts';
 
 const BASE_FLAGS: CliFlags = {
   json: false,

src/bin.ts

@@ -32,7 +32,7 @@ function runVersionFastPath(argv: string[]): boolean {
 
 function runNoCommandFastPath(argv: string[]): boolean {
   if (argv.length !== 0) return false;
-  import('./utils/cli-help.ts')
+  import('./cli/parser/cli-help.ts')
     .then(({ buildUsageText }) => {
       process.stdout.write(`${buildUsageText()}\n`);
       process.exit(1);
@@ -45,7 +45,7 @@ function runHelpFastPath(argv: string[]): boolean {
   const helpTarget = resolveSimpleHelpTarget(argv);
   if (helpTarget === undefined) return false;
 
-  import('./utils/cli-help.ts')
+  import('./cli/parser/cli-help.ts')
     .then(({ buildCommandUsageText, buildUsageText }) => {
       if (helpTarget === null) {
         process.stdout.write(`${buildUsageText()}\n`);

src/cli.ts

@@ -1,4 +1,4 @@
-import { parseRawArgs, usage, usageForCommand } from './utils/args.ts';
+import { parseRawArgs, usage, usageForCommand } from './cli/parser/args.ts';
 import { asAppError, AppError, normalizeError } from './kernel/errors.ts';
 import { printHumanError, printJson } from './utils/output.ts';
 import { readVersion } from './utils/version.ts';
@@ -33,7 +33,7 @@ import {
   type RemoteConnectionRequestMetadata,
 } from './remote/remote-connection-state.ts';
 import { resolveRemoteAuthForCli } from './cli/auth-session.ts';
-import type { CliFlags, FlagKey } from './utils/cli-flags.ts';
+import type { CliFlags, FlagKey } from './cli/parser/cli-flags.ts';
 import type { SessionRuntimeHints } from './kernel/contracts.ts';
 
 type CliDeps = {

src/cli/auth-session.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { runCmd } from '../utils/exec.ts';
 import { AppError } from '../kernel/errors.ts';
-import type { CliFlags } from '../utils/cli-flags.ts';
+import type { CliFlags } from './parser/cli-flags.ts';
 import type { EnvMap } from '../utils/env-map.ts';
 import { readCloudJsonResponse } from './cloud-response.ts';
 

src/cli/batch-steps.ts

@@ -3,7 +3,7 @@ import { type SessionRuntimeHints } from '../kernel/contracts.ts';
 import { parseBatchStepRuntime } from '../batch-contract.ts';
 import { readInputFromCli } from '../commands/cli-grammar.ts';
 import { isCommandName, type CommandName } from '../commands/command-metadata.ts';
-import type { CliFlags } from '../utils/cli-flags.ts';
+import type { CliFlags } from './parser/cli-flags.ts';
 import { AppError } from '../kernel/errors.ts';
 import { isRecord } from '../utils/parsing.ts';
 

src/cli/cloud-connection-profile.ts

@@ -1,7 +1,7 @@
 import crypto from 'node:crypto';
 import type { RemoteConfigProfile } from '../remote/remote-config-schema.ts';
 import { AppError } from '../kernel/errors.ts';
-import type { CliFlags } from '../utils/cli-flags.ts';
+import type { CliFlags } from './parser/cli-flags.ts';
 import type { EnvMap } from '../utils/env-map.ts';
 import { resolveCloudAccessForConnect } from './auth-session.ts';
 import { readCloudJsonResponse } from './cloud-response.ts';

src/cli/commands/__tests__/generic.test.ts

@@ -2,7 +2,7 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { createAgentDeviceClient } from '../../../client.ts';
 import type { DaemonResponse } from '../../../kernel/contracts.ts';
-import type { CliFlags } from '../../../utils/cli-flags.ts';
+import type { CliFlags } from '../../parser/cli-flags.ts';
 import type { ClientBackedCliCommandName } from '../../../command-catalog.ts';
 import { runGenericClientBackedCommand } from '../generic.ts';
 

src/cli/commands/__tests__/screenshot.test.ts

@@ -2,7 +2,7 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { createAgentDeviceClient } from '../../../client.ts';
 import type { DaemonResponse } from '../../../kernel/contracts.ts';
-import type { CliFlags } from '../../../utils/cli-flags.ts';
+import type { CliFlags } from '../../parser/cli-flags.ts';
 import { screenshotCommand } from '../screenshot.ts';
 
 async function captureStdout(fn: () => Promise<unknown>): Promise<string> {

src/cli/commands/agent-cdp.ts

@@ -2,7 +2,7 @@ import { runCmdStreaming } from '../../utils/exec.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { isRemoteBridgeBackend } from './remote-bridge.ts';
 import type { SessionRuntimeHints } from '../../kernel/contracts.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 
 const AGENT_CDP_VERSION = '1.6.0';
 export const AGENT_CDP_PACKAGE = `agent-cdp@${AGENT_CDP_VERSION}`;

src/cli/commands/connection-runtime.ts

@@ -18,7 +18,7 @@ import { profileToCliFlags } from '../../utils/remote-config.ts';
 import type { BatchStep } from '../../client-types.ts';
 import { AppError } from '../../kernel/errors.ts';
 import type { LeaseBackend, SessionRuntimeHints } from '../../kernel/contracts.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import type { AgentDeviceClient, Lease } from '../../client.ts';
 import type { MetroPrepareKind } from '../../metro/client-metro.ts';
 import { INTERNAL_COMMANDS, PUBLIC_COMMANDS } from '../../command-catalog.ts';

src/cli/commands/connection.ts

@@ -25,7 +25,7 @@ import {
 } from './connection-runtime.ts';
 import { writeCommandOutput } from './shared.ts';
 import type { LeaseBackend } from '../../kernel/contracts.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import type { ClientCommandHandler } from './router-types.ts';
 
 export const connectCommand: ClientCommandHandler = async ({ positionals, flags, client }) => {

src/cli/commands/generic.ts

@@ -4,7 +4,7 @@ import { runCliCommandWithOutput } from '../../commands/cli-runner.ts';
 import type { CommandName } from '../../commands/command-metadata.ts';
 import type { CliOutput } from '../../commands/command-contract.ts';
 import type { ReplaySuiteResult } from '../../daemon/types.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import { readCommandMessage } from '../../utils/success-text.ts';
 import { isNonDefaultResponseLevel } from '../../kernel/contracts.ts';
 import { writeCommandOutput } from './shared.ts';

src/cli/commands/proxy.ts

@@ -4,7 +4,7 @@ import { buildDaemonHttpBaseUrl } from '../../daemon/http-contract.ts';
 import { ensureDaemon, resolveClientSettings } from '../../daemon-client-lifecycle.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { colorize, supportsColor } from '../../utils/output.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import { writeCommandOutput } from './shared.ts';
 import type { ClientCommandHandler } from './router-types.ts';
 

src/cli/commands/react-devtools.ts

@@ -5,7 +5,7 @@ import {
 } from '../../client-react-devtools-companion.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { isRemoteBridgeBackend } from './remote-bridge.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 
 const AGENT_REACT_DEVTOOLS_VERSION = '0.4.0';
 export const AGENT_REACT_DEVTOOLS_PACKAGE = `agent-react-devtools@${AGENT_REACT_DEVTOOLS_VERSION}`;

src/cli/commands/remote-bridge.ts

@@ -1,4 +1,4 @@
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 
 export function isRemoteBridgeBackend(leaseBackend: CliFlags['leaseBackend']): boolean {
   return leaseBackend === 'android-instance' || leaseBackend === 'ios-instance';

src/cli/commands/router-types.ts

@@ -1,4 +1,4 @@
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import type { AgentDeviceClient } from '../../client.ts';
 import type { CliCommandName } from '../../command-catalog.ts';
 

src/cli/commands/router.ts

@@ -1,4 +1,4 @@
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import type { AgentDeviceClient } from '../../client.ts';
 import {
   isClientBackedCliCommandName,

src/cli/commands/screenshot.ts

@@ -7,7 +7,7 @@ import type { AgentDeviceClient, CaptureScreenshotResult } from '../../client.ts
 import { createLocalArtifactAdapter } from '../../io.ts';
 import { createAgentDevice, localCommandPolicy } from '../../runtime.ts';
 import { runCliCommand } from '../../commands/cli-runner.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import { writeCommandOutput } from './shared.ts';
 import type { ClientCommandHandler } from './router-types.ts';
 

src/cli/commands/shared.ts

@@ -1,4 +1,4 @@
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import { printJson } from '../../utils/output.ts';
 
 export function writeCommandOutput(

src/cli/commands/web.ts

@@ -4,7 +4,7 @@ import {
   type AgentBrowserToolStatus,
 } from '../../platforms/web/agent-browser-tool.ts';
 import { AppError } from '../../kernel/errors.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../parser/cli-flags.ts';
 import { printJson } from '../../utils/output.ts';
 
 type PublicAgentBrowserToolStatus = Omit<AgentBrowserToolStatus, 'socketDir'>;

src/cli/generated-remote-config.ts

@@ -8,7 +8,7 @@ import type {
 } from '../remote/remote-config-schema.ts';
 import { AppError, asAppError } from '../kernel/errors.ts';
 import type { EnvMap } from '../utils/env-map.ts';
-import type { CliFlags } from '../utils/cli-flags.ts';
+import type { CliFlags } from './parser/cli-flags.ts';
 import { profileToCliFlags } from '../utils/remote-config.ts';
 
 const GENERATED_REMOTE_CONFIG_SECRET_KEYS = new Set(['daemonAuthToken', 'metroBearerToken']);

src/utils/args.ts → src/cli/parser/args.ts

@@ -1,5 +1,5 @@
-import { AppError } from '../kernel/errors.ts';
-import { mergeDefinedFlags } from './merge-flags.ts';
+import { AppError } from '../../kernel/errors.ts';
+import { mergeDefinedFlags } from '../../utils/merge-flags.ts';
 import {
   applyCommandDefaults,
   getCommandSchema,
@@ -8,9 +8,9 @@ import {
   type CliFlags,
   type FlagDefinition,
   type FlagKey,
-} from './command-schema.ts';
+} from '../../utils/command-schema.ts';
 import { buildCommandUsageText, buildUsageText } from './cli-help.ts';
-import { isFlagSupportedForCommand } from './cli-option-schema.ts';
+import { isFlagSupportedForCommand } from '../../utils/cli-option-schema.ts';
 
 type ParsedArgs = {
   command: string | null;

src/utils/cli-flags.ts → src/cli/parser/cli-flags.ts

@@ -1,9 +1,13 @@
-import { SESSION_SURFACES, type SessionSurface } from '../core/session-surface.ts';
-import type { RecordingExportQuality } from '../core/recording-export-quality.ts';
-import type { BackMode } from '../core/back-mode.ts';
-import type { ClickButton } from '../core/click-button.ts';
-import type { SwipePattern } from '../core/scroll-gesture.ts';
-import { PLATFORM_SELECTORS, type DeviceTarget, type PlatformSelector } from '../kernel/device.ts';
+import { SESSION_SURFACES, type SessionSurface } from '../../core/session-surface.ts';
+import type { RecordingExportQuality } from '../../core/recording-export-quality.ts';
+import type { BackMode } from '../../core/back-mode.ts';
+import type { ClickButton } from '../../core/click-button.ts';
+import type { SwipePattern } from '../../core/scroll-gesture.ts';
+import {
+  PLATFORM_SELECTORS,
+  type DeviceTarget,
+  type PlatformSelector,
+} from '../../kernel/device.ts';
 import {
   type DaemonInstallSource,
   type DaemonServerMode,
@@ -14,17 +18,17 @@ import {
   type ResponseLevel,
   type SessionRuntimeHints,
   type SessionIsolationMode,
-} from '../kernel/contracts.ts';
-import type { RemoteConfigMetroOptions } from '../remote/remote-config-schema.ts';
+} from '../../kernel/contracts.ts';
+import type { RemoteConfigMetroOptions } from '../../remote/remote-config-schema.ts';
 import {
   SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS,
   type ScreenshotRequestFlags,
-} from '../contracts/screenshot.ts';
-import { PERF_KIND_VALUES } from '../contracts/perf.ts';
+} from '../../contracts/screenshot.ts';
+import { PERF_KIND_VALUES } from '../../contracts/perf.ts';
 import {
   MAESTRO_COMPAT_TRACKER_URL,
   formatMaestroSupportedSubsetForCli,
-} from '../compat/maestro/support-matrix.ts';
+} from '../../compat/maestro/support-matrix.ts';
 
 export type CliFlags = RemoteConfigMetroOptions &
   ScreenshotRequestFlags & {

src/utils/cli-help.ts → src/cli/parser/cli-help.ts

@@ -1,4 +1,4 @@
-import { listCliCommandNames } from '../command-catalog.ts';
+import { listCliCommandNames } from '../../command-catalog.ts';
 import {
   getCliCommandSchema,
   getCommandSchema,
@@ -7,7 +7,7 @@ import {
   type CommandSchema,
   type FlagDefinition,
   type FlagKey,
-} from './command-schema.ts';
+} from '../../utils/command-schema.ts';
 
 const AGENT_WORKFLOWS = [
   {

src/cli/proxy-connection-profile.ts

@@ -1,7 +1,7 @@
 import crypto from 'node:crypto';
 import type { RemoteConfigProfile } from '../remote/remote-config-schema.ts';
 import { AppError } from '../kernel/errors.ts';
-import type { CliFlags } from '../utils/cli-flags.ts';
+import type { CliFlags } from './parser/cli-flags.ts';
 import type { EnvMap } from '../utils/env-map.ts';
 import { persistAndResolveGeneratedProfile } from './generated-remote-config.ts';
 import { resolveRequestedLeaseBackend } from './commands/connection-runtime.ts';

src/commands/capture/diff.ts

@@ -1,5 +1,5 @@
 import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
-import { SNAPSHOT_FLAGS } from '../../utils/cli-flags.ts';
+import { SNAPSHOT_FLAGS } from '../../cli/parser/cli-flags.ts';
 import { AppError } from '../../kernel/errors.ts';
 import {
   booleanField,

src/commands/capture/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../../cli/parser/cli-flags.ts';
 import {
   alertCliReader,
   alertDaemonWriter,

src/commands/capture/settings.ts

@@ -2,7 +2,7 @@ import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
 import type { SettingsUpdateOptions } from '../../client-types.ts';
 import { SETTINGS_USAGE_OVERRIDE } from '../../core/settings-contract.ts';
 import type { CommandSchemaOverride } from '../../utils/cli-command-schema-types.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../../cli/parser/cli-flags.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { readLocationCoordinate } from '../../utils/location-coordinates.ts';
 import { defineExecutableCommand } from '../command-contract.ts';

src/commands/capture/snapshot.ts

@@ -1,5 +1,5 @@
 import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
-import { SNAPSHOT_FLAGS } from '../../utils/cli-flags.ts';
+import { SNAPSHOT_FLAGS } from '../../cli/parser/cli-flags.ts';
 import { booleanField, integerField, stringField } from '../command-input.ts';
 import { defineExecutableCommand } from '../command-contract.ts';
 import { commonInputFromFlags, direct } from '../cli-grammar/common.ts';

src/commands/capture/wait.ts

@@ -1,7 +1,7 @@
 import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
 import type { WaitCommandOptions } from '../../client-types.ts';
 import { parseWaitPositionals } from '../../core/wait-positionals.ts';
-import { SELECTOR_SNAPSHOT_FLAGS, type CliFlags } from '../../utils/cli-flags.ts';
+import { SELECTOR_SNAPSHOT_FLAGS, type CliFlags } from '../../cli/parser/cli-flags.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { tryParseSelectorChain } from '../../utils/selectors-parse.ts';
 import {

src/commands/cli-grammar/common.ts

@@ -4,7 +4,7 @@ import type {
   InternalRequestOptions,
 } from '../../client-types.ts';
 import { splitSelectorFromArgs } from '../../utils/selectors-parse.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../../cli/parser/cli-flags.ts';
 import { AppError } from '../../kernel/errors.ts';
 import { compactRecord, type SelectorSnapshotInput } from '../command-input.ts';
 import type {

src/commands/cli-grammar/registry.ts

@@ -1,4 +1,4 @@
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../../cli/parser/cli-flags.ts';
 import type { CommandName } from '../command-metadata.ts';
 import { listCommandFamilyCliReaders } from '../family/registry.ts';
 

src/commands/cli-grammar/types.ts

@@ -1,6 +1,6 @@
 import type { InteractionTarget, InternalRequestOptions } from '../../client-types.ts';
 import type { CommandFlags } from '../../core/dispatch-context.ts';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../../cli/parser/cli-flags.ts';
 import type { ClickButton } from '../../core/click-button.ts';
 import type { DecodedFillTarget } from '../../core/interaction-positionals.ts';
 import type { WaitParsed } from '../../core/wait-positionals.ts';

src/commands/cli-runner.ts

@@ -3,7 +3,7 @@ import { formatCliOutput } from './cli-output.ts';
 import { readInputFromCli } from './cli-grammar.ts';
 import { runCommand, type CommandName } from './command-surface.ts';
 import type { CliOutput } from './command-contract.ts';
-import type { CliFlags } from '../utils/cli-flags.ts';
+import type { CliFlags } from '../cli/parser/cli-flags.ts';
 
 type CliRunOptions = {
   client: AgentDeviceClient;

src/commands/command-flags.ts

@@ -1,6 +1,6 @@
 import { buildFlags } from '../client-normalizers.ts';
 import type { CommandFlags } from '../core/dispatch-context.ts';
-import { getFlagDefinitions } from '../utils/cli-flags.ts';
+import { getFlagDefinitions } from '../cli/parser/cli-flags.ts';
 import type { InternalRequestOptions } from '../client-types.ts';
 import type { CommandMetadata } from './command-contract.ts';
 

src/commands/debugging/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../../cli/parser/cli-flags.ts';
 import { debugCliReader, debugCommandDefinition, debugCommandMetadata } from './index.ts';
 
 describe('debugging command interface', () => {

src/commands/interaction/gesture.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import type { CliFlags } from '../../utils/cli-flags.ts';
+import type { CliFlags } from '../../cli/parser/cli-flags.ts';
 import type { CommandInput } from '../cli-grammar/types.ts';
 import { gestureCliReaders, gestureDaemonWriters } from './gesture.ts';