Tighten parser positional handling and ref flag validation

Author: thymikee

src/daemon/handlers/__tests__/interaction.test.ts

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { unsupportedRefSnapshotFlags } from '../interaction.ts';
+
+test('unsupportedRefSnapshotFlags returns unsupported snapshot flags for @ref flows', () => {
+  const unsupported = unsupportedRefSnapshotFlags({
+    snapshotDepth: 2,
+    snapshotScope: 'Login',
+    snapshotRaw: true,
+    snapshotBackend: 'ax',
+  });
+  assert.deepEqual(unsupported, ['--depth', '--scope', '--raw', '--backend']);
+});
+
+test('unsupportedRefSnapshotFlags returns empty when no ref-unsupported flags are present', () => {
+  const unsupported = unsupportedRefSnapshotFlags({
+    platform: 'ios',
+    session: 'default',
+    verbose: true,
+  });
+  assert.deepEqual(unsupported, []);
+});

src/daemon/handlers/interaction.ts

@@ -41,6 +41,16 @@ export async function handleInteractionCommands(params: {
     }
     const refInput = req.positionals?.[0] ?? '';
     if (refInput.startsWith('@')) {
+      const unsupported = unsupportedRefSnapshotFlags(req.flags);
+      if (unsupported.length > 0) {
+        return {
+          ok: false,
+          error: {
+            code: 'INVALID_ARGS',
+            message: `click @ref does not support ${unsupported.join(', ')}.`,
+          },
+        };
+      }
       if (!session.snapshot) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
       }
@@ -126,6 +136,16 @@ export async function handleInteractionCommands(params: {
   if (command === 'fill') {
     const session = sessionStore.get(sessionName);
     if (req.positionals?.[0]?.startsWith('@')) {
+      const unsupported = unsupportedRefSnapshotFlags(req.flags);
+      if (unsupported.length > 0) {
+        return {
+          ok: false,
+          error: {
+            code: 'INVALID_ARGS',
+            message: `fill @ref does not support ${unsupported.join(', ')}.`,
+          },
+        };
+      }
       if (!session?.snapshot) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
       }
@@ -258,6 +278,16 @@ export async function handleInteractionCommands(params: {
     }
     const refInput = req.positionals?.[1] ?? '';
     if (refInput.startsWith('@')) {
+      const unsupported = unsupportedRefSnapshotFlags(req.flags);
+      if (unsupported.length > 0) {
+        return {
+          ok: false,
+          error: {
+            code: 'INVALID_ARGS',
+            message: `get @ref does not support ${unsupported.join(', ')}.`,
+          },
+        };
+      }
       if (!session.snapshot) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
       }
@@ -511,3 +541,19 @@ async function captureSnapshotForSession(
   sessionStore.set(session.name, session);
   return session.snapshot;
 }
+
+const REF_UNSUPPORTED_FLAG_MAP: ReadonlyArray<[keyof CommandFlags, string]> = [
+  ['snapshotDepth', '--depth'],
+  ['snapshotScope', '--scope'],
+  ['snapshotRaw', '--raw'],
+  ['snapshotBackend', '--backend'],
+];
+
+export function unsupportedRefSnapshotFlags(flags: CommandFlags | undefined): string[] {
+  if (!flags) return [];
+  const unsupported: string[] = [];
+  for (const [key, label] of REF_UNSUPPORTED_FLAG_MAP) {
+    if (flags[key] !== undefined) unsupported.push(label);
+  }
+  return unsupported;
+}

src/utils/__tests__/args.test.ts

@@ -2,7 +2,7 @@ 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 { getCliCommandNames, getSchemaCapabilityKeys } from '../command-schema.ts';
 import { listCapabilityCommands } from '../../core/capabilities.ts';
 
 test('parseArgs recognizes --relaunch', () => {
@@ -25,6 +25,10 @@ test('every capability command has a parser schema entry', () => {
   }
 });
 
+test('schema capability mappings match capability source-of-truth', () => {
+  assert.deepEqual(getSchemaCapabilityKeys(), listCapabilityCommands());
+});
+
 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');
@@ -59,6 +63,16 @@ test('unknown short flags are rejected', () => {
   );
 });
 
+test('negative numeric positionals are accepted without -- separator', () => {
+  const typed = parseArgs(['type', '-123'], { strictFlags: true });
+  assert.equal(typed.command, 'type');
+  assert.deepEqual(typed.positionals, ['-123']);
+
+  const pressed = parseArgs(['press', '-10', '20'], { strictFlags: true });
+  assert.equal(pressed.command, 'press');
+  assert.deepEqual(pressed.positionals, ['-10', '20']);
+});
+
 test('all commands participate in strict command-flag validation', () => {
   assert.throws(
     () => parseArgs(['open', 'Settings', '--depth', '1'], { strictFlags: true }),

src/utils/args.ts

@@ -29,6 +29,7 @@ type ParsedFlagRecord = {
 export function parseArgs(argv: string[], options?: ParseArgsOptions): ParsedArgs {
   const strictFlags = options?.strictFlags ?? isStrictFlagModeEnabled(process.env.AGENT_DEVICE_STRICT_FLAGS);
   const flags: CliFlags = { json: false, help: false, version: false };
+  let command: string | null = null;
   const positionals: string[] = [];
   const warnings: string[] = [];
   const providedFlags: ParsedFlagRecord[] = [];
@@ -41,19 +42,26 @@ export function parseArgs(argv: string[], options?: ParseArgsOptions): ParsedArg
       continue;
     }
     if (!parseFlags) {
-      positionals.push(arg);
+      if (!command) command = arg;
+      else positionals.push(arg);
       continue;
     }
     const isLongFlag = arg.startsWith('--');
     const isShortFlag = arg.startsWith('-') && arg.length > 1;
     if (!isLongFlag && !isShortFlag) {
-      positionals.push(arg);
+      if (!command) command = arg;
+      else positionals.push(arg);
       continue;
     }
 
     const [token, inlineValue] = isLongFlag ? splitLongFlag(arg) : [arg, undefined];
     const definition = getFlagDefinition(token);
     if (!definition) {
+      if (shouldTreatUnknownDashTokenAsPositional(command, positionals, arg)) {
+        if (!command) command = arg;
+        else positionals.push(arg);
+        continue;
+      }
       throw new AppError('INVALID_ARGS', `Unknown flag: ${token}`);
     }
 
@@ -63,7 +71,6 @@ export function parseArgs(argv: string[], options?: ParseArgsOptions): ParsedArg
     providedFlags.push({ key: definition.key, token });
   }
 
-  const command = positionals.shift() ?? null;
   const commandSchema = getCommandSchema(command);
   const allowedFlagKeys = new Set<FlagKey>([
     ...GLOBAL_FLAG_KEYS,
@@ -165,6 +172,24 @@ function looksLikeFlagToken(value: string): boolean {
   return getFlagDefinition(token) !== undefined;
 }
 
+function shouldTreatUnknownDashTokenAsPositional(
+  command: string | null,
+  positionals: string[],
+  arg: string,
+): boolean {
+  if (!isNegativeNumericToken(arg)) return false;
+  if (!command) return false;
+  const schema = getCommandSchema(command);
+  if (!schema) return true;
+  if (schema.positionalArgs.length === 0) return false;
+  if (positionals.length < schema.positionalArgs.length) return true;
+  return schema.positionalArgs.some((entry) => entry.includes('?'));
+}
+
+function isNegativeNumericToken(value: string): boolean {
+  return /^-\d+(\.\d+)?$/.test(value);
+}
+
 export function toDaemonFlags(flags: CliFlags): Omit<CliFlags, 'json' | 'help' | 'version'> {
   const { json: _json, help: _help, version: _version, ...daemonFlags } = flags;
   return daemonFlags;

src/utils/command-schema.ts

@@ -607,13 +607,23 @@ export function getCliCommandNames(): string[] {
   return [...CLI_COMMAND_ORDER];
 }
 
+export function getSchemaCapabilityKeys(): string[] {
+  return Object.values(COMMAND_SCHEMAS)
+    .map((schema) => schema.capabilityKey)
+    .filter((key): key is string => typeof key === 'string')
+    .sort();
+}
+
 export function isStrictFlagModeEnabled(value: string | undefined): boolean {
   if (!value) return false;
   const normalized = value.trim().toLowerCase();
   return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
 }
 
+let cachedUsageText: string | null = null;
+
 export function buildUsageText(): string {
+  if (cachedUsageText) return cachedUsageText;
   const header = `agent-device <command> [args] [--json]
 
 CLI to control iOS and Android devices for AI agents.
@@ -646,9 +656,10 @@ CLI to control iOS and Android devices for AI agents.
     );
   }
 
-  return `${header}
+  cachedUsageText = `${header}
 ${commandLines.join('\n')}
 
 ${flagLines.join('\n')}
 `;
+  return cachedUsageText;
 }