fix: project structured batch targets

Author: thymikee

src/__tests__/cli-batch.test.ts

@@ -62,6 +62,22 @@ test('batch --steps-file parses file payload', async () => {
   assert.equal((req.flags?.batchSteps ?? [])[0]?.command, 'wait');
 });
 
+test('batch structured interaction target is projected to positionals, not device flags', async () => {
+  const result = await runCliCapture([
+    'batch',
+    '--steps',
+    '[{"command":"press","input":{"target":{"kind":"point","x":10,"y":20},"count":2}}]',
+    '--json',
+  ]);
+
+  assert.equal(result.code, null);
+  assert.equal(result.calls.length, 1);
+  const step = (result.calls[0]?.flags?.batchSteps ?? [])[0];
+  assert.deepEqual(step?.positionals, ['10', '20']);
+  assert.equal(step?.flags?.target, undefined);
+  assert.equal(step?.flags?.count, 2);
+});
+
 test('batch accepts legacy positionals/flags steps with deprecation warning', async () => {
   const result = await runCliCapture([
     'batch',

src/commands/cli-grammar/common.ts

@@ -26,9 +26,11 @@ export function request(
 }
 
 function normalizeCommonRequestOptions(options: CommandInput): CommandInput {
-  return options.deviceTarget !== undefined && options.target === undefined
-    ? { ...options, target: options.deviceTarget }
-    : options;
+  const normalizedTarget =
+    options.deviceTarget ?? (typeof options.target === 'string' ? options.target : undefined);
+  if (normalizedTarget === undefined && options.target === undefined) return options;
+  const { target: _target, ...rest } = options;
+  return normalizedTarget === undefined ? rest : { ...rest, target: normalizedTarget };
 }
 
 export function commonInputFromFlags(flags: CliFlags): Record<string, unknown> {
@@ -99,15 +101,47 @@ export function targetInputFromClientTarget(
   return { kind: 'point', x: point.x, y: point.y };
 }
 
-export function interactionTargetPositionals(input: InteractionTarget): string[] {
-  if (input.ref !== undefined) return [input.ref, ...optionalString(input.label)];
-  if (input.selector !== undefined) return [input.selector];
-  return [String(input.x), String(input.y)];
+export function interactionTargetPositionals(input: InteractionTarget | CommandInput): string[] {
+  const target = readTargetRecord(input);
+  if (typeof target.ref === 'string') return [target.ref, ...optionalTargetLabel(target.label)];
+  if (typeof target.selector === 'string') return [target.selector];
+  if (target.kind === 'point' || target.x !== undefined || target.y !== undefined) {
+    return [
+      String(requiredTargetNumber(target.x, 'x')),
+      String(requiredTargetNumber(target.y, 'y')),
+    ];
+  }
+  throw new AppError('INVALID_ARGS', 'interaction requires @ref, selector, or point target');
+}
+
+export function elementTargetPositionals(input: ElementTarget | CommandInput): string[] {
+  const target = readTargetRecord(input);
+  if (typeof target.ref === 'string') return [target.ref, ...optionalTargetLabel(target.label)];
+  if (typeof target.selector === 'string') return [target.selector];
+  throw new AppError('INVALID_ARGS', 'element command requires @ref or selector target');
+}
+
+function readTargetRecord(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new AppError('INVALID_ARGS', 'Expected target object.');
+  }
+  const record = input as Record<string, unknown>;
+  const nestedTarget = record.target;
+  if (nestedTarget && typeof nestedTarget === 'object' && !Array.isArray(nestedTarget)) {
+    return nestedTarget as Record<string, unknown>;
+  }
+  return record;
+}
+
+function requiredTargetNumber(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new AppError('INVALID_ARGS', `point target requires numeric ${field}.`);
+  }
+  return value;
 }
 
-export function elementTargetPositionals(input: ElementTarget): string[] {
-  if (input.ref !== undefined) return [input.ref, ...optionalString(input.label)];
-  return [input.selector];
+function optionalTargetLabel(value: unknown): string[] {
+  return typeof value === 'string' && value.length > 0 ? [value] : [];
 }
 
 export function readElementTargetFromPositionals(positionals: string[]): ElementTarget {

src/utils/cli-help.ts

@@ -207,6 +207,7 @@ Validation and evidence:
   Inline batch JSON example:
     agent-device batch --steps '[{"command":"open","input":{"app":"settings"}},{"command":"wait","input":{"kind":"duration","durationMs":100}}]'
   Batch step keys are command, input, and optional runtime. Put command arguments inside input using the same fields as the MCP/Node command. CLI still accepts legacy positionals/flags steps with a deprecation warning until the next major version.
+  Never use args, step positionals, or flags for new batch JSON; put command inputs under input.
   Android animations: settings animations off/on, not animations disable/restore.
   Debug logs: logs clear --restart, logs mark, reproduce, then logs path; do not split clear/restart into separate stop/start commands.
   Network headers: network dump --include headers; do not write network log headers.