Refactor CLI command schema and strict flag validation

Author: thymikee

src/cli.ts

@@ -1,4 +1,4 @@
-import { parseArgs, usage } from './utils/args.ts';
+import { parseArgs, toDaemonFlags, usage } from './utils/args.ts';
 import { asAppError, AppError } from './utils/errors.ts';
 import { formatSnapshotText, printHumanError, printJson } from './utils/output.ts';
 import { readVersion } from './utils/version.ts';
@@ -10,6 +10,9 @@ import path from 'node:path';
 
 export async function runCli(argv: string[]): Promise<void> {
   const parsed = parseArgs(argv);
+  for (const warning of parsed.warnings) {
+    process.stderr.write(`Warning: ${warning}\n`);
+  }
 
   if (parsed.flags.version) {
     process.stdout.write(`${readVersion()}\n`);
@@ -22,6 +25,7 @@ export async function runCli(argv: string[]): Promise<void> {
   }
 
   const { command, positionals, flags } = parsed;
+  const daemonFlags = toDaemonFlags(flags);
   const sessionName = flags.session ?? process.env.AGENT_DEVICE_SESSION ?? 'default';
   const logTailStopper = flags.verbose && !flags.json ? startDaemonLogTail() : null;
   try {
@@ -34,7 +38,7 @@ export async function runCli(argv: string[]): Promise<void> {
         session: sessionName,
         command: 'session_list',
         positionals: [],
-        flags: {},
+        flags: daemonFlags,
       });
       if (!response.ok) throw new AppError(response.error.code as any, response.error.message);
       if (flags.json) printJson({ success: true, data: response.data ?? {} });
@@ -47,7 +51,7 @@ export async function runCli(argv: string[]): Promise<void> {
       session: sessionName,
       command: command!,
       positionals,
-      flags,
+      flags: daemonFlags,
     });
 
     if (response.ok) {

src/core/capabilities.ts

@@ -50,3 +50,7 @@ export function isCommandSupportedOnDevice(command: string, device: DeviceInfo):
   const kind = (device.kind ?? 'unknown') as keyof KindMatrix;
   return byPlatform[kind] === true;
 }
+
+export function listCapabilityCommands(): string[] {
+  return Object.keys(COMMAND_CAPABILITY_MATRIX).sort();
+}

src/core/dispatch.ts

@@ -17,35 +17,9 @@ import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
 import { snapshotAx } from '../platforms/ios/ax-snapshot.ts';
 import { setIosSetting } from '../platforms/ios/index.ts';
 import type { RawSnapshotNode } from '../utils/snapshot.ts';
+import type { DaemonFlags } from '../utils/command-schema.ts';
 
-export type CommandFlags = {
-  session?: string;
-  platform?: 'ios' | 'android';
-  device?: string;
-  udid?: string;
-  serial?: string;
-  out?: string;
-  activity?: string;
-  verbose?: boolean;
-  snapshotInteractiveOnly?: boolean;
-  snapshotCompact?: boolean;
-  snapshotDepth?: number;
-  snapshotScope?: string;
-  snapshotRaw?: boolean;
-  snapshotBackend?: 'ax' | 'xctest';
-  saveScript?: boolean;
-  relaunch?: boolean;
-  noRecord?: boolean;
-  appsFilter?: 'launchable' | 'user-installed' | 'all';
-  appsMetadata?: boolean;
-  count?: number;
-  intervalMs?: number;
-  holdMs?: number;
-  jitterPx?: number;
-  pauseMs?: number;
-  pattern?: 'one-way' | 'ping-pong';
-  replayUpdate?: boolean;
-};
+export type CommandFlags = DaemonFlags;
 
 export async function resolveTargetDevice(flags: CommandFlags): Promise<DeviceInfo> {
   const selector = {

src/utils/__tests__/args.test.ts

@@ -1,6 +1,9 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { parseArgs, usage } from '../args.ts';
+import { AppError } from '../errors.ts';
+import { getCliCommandNames } from '../command-schema.ts';
+import { listCapabilityCommands } from '../../core/capabilities.ts';
 
 test('parseArgs recognizes --relaunch', () => {
   const parsed = parseArgs(['open', 'settings', '--relaunch']);
@@ -61,6 +64,71 @@ test('parseArgs rejects invalid swipe pattern', () => {
 
 test('usage includes --relaunch flag', () => {
   assert.match(usage(), /--relaunch/);
+  assert.match(usage(), /pinch <scale> \[x\] \[y\]/);
+  assert.match(usage(), /--metadata/);
+});
+
+test('every capability command has a parser schema entry', () => {
+  const schemaCommands = new Set(getCliCommandNames());
+  for (const command of listCapabilityCommands()) {
+    assert.equal(schemaCommands.has(command), true, `Missing schema for command: ${command}`);
+  }
+});
+
+test('compat mode warns and strips unsupported pilot-command flags', () => {
+  const parsed = parseArgs(['press', '10', '20', '--depth', '2'], { strictFlags: false });
+  assert.equal(parsed.command, 'press');
+  assert.equal(parsed.flags.snapshotDepth, undefined);
+  assert.equal(parsed.warnings.length, 1);
+  assert.match(parsed.warnings[0], /not supported for command press/);
+});
+
+test('strict mode rejects unsupported pilot-command flags', () => {
+  assert.throws(
+    () => parseArgs(['press', '10', '20', '--depth', '2'], { strictFlags: true }),
+    (error) =>
+      error instanceof AppError &&
+      error.code === 'INVALID_ARGS' &&
+      error.message.includes('not supported for command press'),
+  );
+});
+
+test('snapshot command accepts command-specific flags', () => {
+  const parsed = parseArgs(['snapshot', '-i', '-c', '--depth', '3', '-s', 'Login'], { strictFlags: true });
+  assert.equal(parsed.command, 'snapshot');
+  assert.equal(parsed.flags.snapshotInteractiveOnly, true);
+  assert.equal(parsed.flags.snapshotCompact, true);
+  assert.equal(parsed.flags.snapshotDepth, 3);
+  assert.equal(parsed.flags.snapshotScope, 'Login');
+});
+
+test('unknown short flags are rejected', () => {
+  assert.throws(
+    () => parseArgs(['press', '10', '20', '-x'], { strictFlags: true }),
+    (error) => error instanceof AppError && error.code === 'INVALID_ARGS' && error.message === 'Unknown flag: -x',
+  );
+});
+
+test('all commands participate in strict command-flag validation', () => {
+  assert.throws(
+    () => parseArgs(['open', 'Settings', '--depth', '1'], { strictFlags: true }),
+    (error) =>
+      error instanceof AppError &&
+      error.code === 'INVALID_ARGS' &&
+      error.message.includes('not supported for command open'),
+  );
+});
+
+test('invalid enum/range errors are deterministic', () => {
+  assert.throws(
+    () => parseArgs(['snapshot', '--backend', 'foo'], { strictFlags: true }),
+    (error) =>
+      error instanceof AppError && error.code === 'INVALID_ARGS' && error.message === 'Invalid backend: foo',
+  );
+  assert.throws(
+    () => parseArgs(['snapshot', '--depth', '-1'], { strictFlags: true }),
+    (error) => error instanceof AppError && error.code === 'INVALID_ARGS' && error.message === 'Invalid depth: -1',
+  );
 });
 
 test('usage includes swipe and press series options', () => {