Fix strict no-command flags and negative positional parsing

Author: thymikee

src/utils/__tests__/args.test.ts

@@ -118,11 +118,33 @@ test('negative numeric positionals are accepted without -- separator', () => {
   assert.equal(typed.command, 'type');
   assert.deepEqual(typed.positionals, ['-123']);
 
+  const typedMulti = parseArgs(['type', '-123', '-456'], { strictFlags: true });
+  assert.equal(typedMulti.command, 'type');
+  assert.deepEqual(typedMulti.positionals, ['-123', '-456']);
+
   const pressed = parseArgs(['press', '-10', '20'], { strictFlags: true });
   assert.equal(pressed.command, 'press');
   assert.deepEqual(pressed.positionals, ['-10', '20']);
 });
 
+test('command-specific flags without command fail in strict mode', () => {
+  assert.throws(
+    () => parseArgs(['--depth', '3'], { strictFlags: true }),
+    (error) =>
+      error instanceof AppError &&
+      error.code === 'INVALID_ARGS' &&
+      error.message.includes('requires a command that supports it'),
+  );
+});
+
+test('command-specific flags without command warn and strip in compat mode', () => {
+  const parsed = parseArgs(['--depth', '3'], { strictFlags: false });
+  assert.equal(parsed.command, null);
+  assert.equal(parsed.flags.snapshotDepth, undefined);
+  assert.equal(parsed.warnings.length, 1);
+  assert.match(parsed.warnings[0], /requires a command that supports/);
+});
+
 test('all commands participate in strict command-flag validation', () => {
   assert.throws(
     () => parseArgs(['open', 'Settings', '--depth', '1'], { strictFlags: true }),

src/utils/args.ts

@@ -77,12 +77,9 @@ export function parseArgs(argv: string[], options?: ParseArgsOptions): ParsedArg
     ...(commandSchema?.allowedFlags ?? []),
   ]);
   const disallowed = providedFlags.filter((entry) => !allowedFlagKeys.has(entry.key));
-  if (disallowed.length > 0 && command) {
+  if (disallowed.length > 0) {
     const unsupported = disallowed.map((entry) => entry.token);
-    const message =
-      unsupported.length === 1
-        ? `Flag ${unsupported[0]} is not supported for command ${command}.`
-        : `Flags ${unsupported.join(', ')} are not supported for command ${command}.`;
+    const message = formatUnsupportedFlagMessage(command, unsupported);
     if (strictFlags) {
       throw new AppError('INVALID_ARGS', message);
     }
@@ -179,6 +176,7 @@ function shouldTreatUnknownDashTokenAsPositional(
   if (!command) return false;
   const schema = getCommandSchema(command);
   if (!schema) return true;
+  if (schema.allowsExtraPositionals) return true;
   if (schema.positionalArgs.length === 0) return false;
   if (positionals.length < schema.positionalArgs.length) return true;
   return schema.positionalArgs.some((entry) => entry.includes('?'));
@@ -188,6 +186,17 @@ function isNegativeNumericToken(value: string): boolean {
   return /^-\d+(\.\d+)?$/.test(value);
 }
 
+function formatUnsupportedFlagMessage(command: string | null, unsupported: string[]): string {
+  if (!command) {
+    return unsupported.length === 1
+      ? `Flag ${unsupported[0]} requires a command that supports it.`
+      : `Flags ${unsupported.join(', ')} require a command that supports them.`;
+  }
+  return unsupported.length === 1
+    ? `Flag ${unsupported[0]} is not supported for command ${command}.`
+    : `Flags ${unsupported.join(', ')} are not supported for command ${command}.`;
+}
+
 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

@@ -53,6 +53,7 @@ export type CommandSchema = {
   description: string;
   details?: readonly string[];
   positionalArgs: readonly string[];
+  allowsExtraPositionals?: boolean;
   allowedFlags: readonly FlagKey[];
   defaults?: Partial<CliFlags>;
 };
@@ -457,6 +458,7 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     usage: 'wait <ms>|text <text>|@ref|<selector> [timeoutMs]',
     description: 'Wait for duration, text, ref, or selector to appear',
     positionalArgs: ['durationOrSelector', 'timeoutMs?'],
+    allowsExtraPositionals: true,
     allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS],
   },
   alert: {
@@ -529,6 +531,7 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     usage: 'type <text>',
     description: 'Type text in focused field',
     positionalArgs: ['text'],
+    allowsExtraPositionals: true,
     allowedFlags: [],
   },
   fill: {
@@ -537,6 +540,7 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     usage: 'fill <x> <y> <text> | fill <@ref|selector> <text>',
     description: 'Tap then type',
     positionalArgs: ['targetOrX', 'yOrText', 'text?'],
+    allowsExtraPositionals: true,
     allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS],
   },
   scroll: {
@@ -600,6 +604,7 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
       'find id <id> <action> [value]',
     ],
     positionalArgs: ['query', 'action', 'value?'],
+    allowsExtraPositionals: true,
     allowedFlags: [...FIND_SNAPSHOT_FLAGS],
   },
   is: {
@@ -608,6 +613,7 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     usage: 'is <predicate> <selector> [value]',
     description: 'Assert UI state (visible|hidden|exists|editable|selected|text)',
     positionalArgs: ['predicate', 'selector', 'value?'],
+    allowsExtraPositionals: true,
     allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS],
   },
   settings: {