chore: harden command input typing

Author: thymikee

src/commands/cli-grammar/common.ts

@@ -1,4 +1,8 @@
-import type { ElementTarget, InteractionTarget } from '../../client-types.ts';
+import type {
+  ElementTarget,
+  InteractionTarget,
+  InternalRequestOptions,
+} from '../../client-types.ts';
 import { splitSelectorFromArgs } from '../../daemon/selectors.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';
 import { AppError } from '../../utils/errors.ts';
@@ -25,12 +29,19 @@ export function request(
   return { command, positionals, options: normalizeCommonRequestOptions(options) };
 }
 
-function normalizeCommonRequestOptions(options: CommandInput): CommandInput {
-  const normalizedTarget =
-    options.deviceTarget ?? (typeof options.target === 'string' ? options.target : undefined);
-  if (normalizedTarget === undefined && options.target === undefined) return options;
+function normalizeCommonRequestOptions(options: CommandInput): InternalRequestOptions {
+  const normalizedTarget = readDeviceTarget(options.deviceTarget ?? options.target);
+  if (normalizedTarget === undefined && options.target === undefined) {
+    return options as InternalRequestOptions;
+  }
   const { target: _target, ...rest } = options;
-  return normalizedTarget === undefined ? rest : { ...rest, target: normalizedTarget };
+  return (
+    normalizedTarget === undefined ? rest : { ...rest, target: normalizedTarget }
+  ) as InternalRequestOptions;
+}
+
+function readDeviceTarget(value: unknown): InternalRequestOptions['target'] | undefined {
+  return value === 'mobile' || value === 'tv' || value === 'desktop' ? value : undefined;
 }
 
 export function commonInputFromFlags(flags: CliFlags): Record<string, unknown> {

src/commands/cli-grammar/system.ts

@@ -40,7 +40,8 @@ export const systemCliReaders = {
 
 export const systemDaemonWriters = {
   appstate: direct(PUBLIC_COMMANDS.appState),
-  back: (input) => request(PUBLIC_COMMANDS.back, [], { ...input, backMode: input.mode }),
+  back: (input) =>
+    request(PUBLIC_COMMANDS.back, [], { ...input, backMode: readBackMode(input.mode) }),
   home: direct(PUBLIC_COMMANDS.home),
   rotate: direct(PUBLIC_COMMANDS.rotate, (input) => [
     requiredDaemonString(input.orientation, 'rotate requires orientation'),
@@ -55,6 +56,10 @@ export const systemDaemonWriters = {
   ]),
 } satisfies Record<string, DaemonWriter>;
 
+function readBackMode(value: unknown): 'in-app' | 'system' | undefined {
+  return value === 'in-app' || value === 'system' ? value : undefined;
+}
+
 function clipboardPositionals(input: ClipboardCommandOptions): string[] {
   return input.action === 'read' ? ['read'] : ['write', input.text];
 }
@@ -83,11 +88,24 @@ function readClipboardInput(positionals: string[]): Record<string, unknown> {
   return { action, text: positionals.slice(1).join(' ') };
 }
 
-function readKeyboardAction(value: string | undefined): 'status' | 'dismiss' | undefined {
+function readKeyboardAction(
+  value: string | undefined,
+): 'status' | 'dismiss' | 'enter' | 'return' | undefined {
   const action = value?.toLowerCase();
   if (action === 'get') return 'status';
-  if (action === undefined || action === 'status' || action === 'dismiss') return action;
-  throw new AppError('INVALID_ARGS', 'keyboard action must be status, get, or dismiss.');
+  if (
+    action === undefined ||
+    action === 'status' ||
+    action === 'dismiss' ||
+    action === 'enter' ||
+    action === 'return'
+  ) {
+    return action;
+  }
+  throw new AppError(
+    'INVALID_ARGS',
+    'keyboard action must be status, get, dismiss, enter, or return.',
+  );
 }
 
 function readReactNativeAction(value: string | undefined): 'dismiss-overlay' {

src/commands/cli-grammar/types.ts

@@ -7,7 +7,61 @@ export type DaemonCommandRequest = {
   options: InternalRequestOptions;
 };
 
-export type CommandInput = InternalRequestOptions & Record<string, any>;
+type PointInput = {
+  x?: number;
+  y?: number;
+};
+
+export type CommandInput = Omit<InternalRequestOptions, 'batchSteps' | 'target'> &
+  Omit<Partial<CliFlags>, 'batchSteps' | 'target'> & {
+    target?: InternalRequestOptions['target'] | Record<string, unknown>;
+    action?: string;
+    amount?: number;
+    app?: string;
+    appPath?: string;
+    backend?: string;
+    degrees?: number;
+    direction?: string;
+    distance?: number;
+    durationMs?: number;
+    dx?: number;
+    dy?: number;
+    delta?: PointInput;
+    env?: string[];
+    event?: string;
+    format?: string;
+    from?: PointInput;
+    include?: CliFlags['networkInclude'];
+    kind?: string;
+    locator?: string;
+    mode?: 'in-app' | 'system' | 'full' | 'limited';
+    button?: 'primary' | 'secondary' | 'middle';
+    first?: boolean;
+    last?: boolean;
+    maxSteps?: number;
+    onError?: 'stop';
+    origin?: PointInput;
+    path?: string;
+    paths?: string[];
+    payload?: unknown;
+    permission?: string;
+    predicate?: string;
+    query?: string;
+    retainPaths?: boolean;
+    retentionMs?: number;
+    scale?: number;
+    selector?: string;
+    source?: InternalRequestOptions['installSource'];
+    state?: string;
+    text?: string;
+    to?: PointInput;
+    update?: boolean;
+    url?: string;
+    value?: string;
+    velocity?: number;
+    x?: number;
+    y?: number;
+  } & Record<string, unknown>;
 
 export type SelectionOptions = {
   platform?: CliFlags['platform'];

src/utils/cli-command-overrides.ts

@@ -147,9 +147,10 @@ const CLI_COMMAND_OVERRIDES = {
     allowsExtraPositionals: true,
   },
   keyboard: {
-    usageOverride: 'keyboard [status|get|dismiss]',
-    helpDescription: 'Inspect Android keyboard visibility/type or dismiss the device keyboard',
-    summary: 'Inspect or dismiss the device keyboard',
+    usageOverride: 'keyboard [status|get|dismiss|enter|return]',
+    helpDescription:
+      'Inspect Android keyboard visibility/type or press/dismiss the device keyboard',
+    summary: 'Inspect, press, or dismiss the device keyboard',
     positionalArgs: ['action?'],
   },
   back: {
@@ -197,16 +198,17 @@ const CLI_COMMAND_OVERRIDES = {
   },
   replay: {
     positionalArgs: ['path'],
-    allowedFlags: ['replayMaestro', ...REPLAY_FLAGS],
+    allowedFlags: ['replayMaestro', ...REPLAY_FLAGS, 'timeoutMs'],
   },
   test: {
     usageOverride: 'test <path-or-glob>...',
     listUsageOverride: 'test <path-or-glob>...',
-    helpDescription: 'Run one or more .ad scripts as a serial test suite',
-    summary: 'Run .ad test suites',
+    helpDescription: 'Run one or more replay scripts as a serial test suite',
+    summary: 'Run replay test suites',
     positionalArgs: ['pathOrGlob'],
     allowsExtraPositionals: true,
     allowedFlags: [
+      'replayMaestro',
       ...REPLAY_FLAGS,
       'failFast',
       'timeoutMs',

src/utils/cli-flags.ts

@@ -760,7 +760,7 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'boolean',
     usageLabel: '--maestro',
     usageDescription:
-      'Replay: treat input as a Maestro YAML compatibility flow. Supported subset: launchApp without state-reset side effects, runFlow file/inline with when.platform, onFlowStart/onFlowComplete, deterministic repeat.times, tapOn, doubleTapOn, longPressOn, inputText, pasteText, openLink, assertVisible, assertNotVisible, assertTrue literal true/false, extendedWaitUntil, scroll, absolute/percentage swipe, takeScreenshot, hideKeyboard, pressKey back/enter/home, back, waitForAnimationToEnd, stopApp/killApp, setAirplaneMode, setLocation, setOrientation, supported setPermissions targets, and startRecording/stopRecording. ' +
+      'Replay: treat input as a Maestro YAML compatibility flow. Supported subset: launchApp without state-reset side effects, runFlow file/inline with when.platform, onFlowStart/onFlowComplete, deterministic repeat.times, ordered trusted runScript, tapOn, doubleTapOn, longPressOn, inputText, pasteText, openLink, assertVisible, assertNotVisible, assertTrue literal true/false, extendedWaitUntil, scroll, absolute/percentage swipe, takeScreenshot, hideKeyboard, pressKey back/enter/home, back, waitForAnimationToEnd, stopApp/killApp, setAirplaneMode, setLocation, setOrientation, supported setPermissions targets, and startRecording/stopRecording. ' +
       'Unsupported syntax fails loudly with a link to https://github.com/callstackincubator/agent-device/issues/558',
   },
   {