refactor: add command definition foundation (#513)

* refactor: add command definition foundation

* fix: satisfy fallow for command definitions

* refactor: tighten command definition foundation

Author: thymikee

src/cli/commands/generic.ts

@@ -2,6 +2,8 @@ import type { AgentDeviceClient, CommandRequestResult } from '../../client.ts';
 import { CLIENT_COMMANDS } from '../../client-command-registry.ts';
 import type { RecordOptions } from '../../client-types.ts';
 import { announceReplayTestRun } from '../../cli-test.ts';
+import { runTypeCliCommand } from '../../commands/interactions/cli.ts';
+import { typeCommandDefinition } from '../../commands/interactions/definition.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';
 import {
@@ -151,14 +153,9 @@ export const genericClientCommandHandlers = {
         y: Number(positionals[1]),
       }),
   ),
-  [CLIENT_COMMANDS.type]: createGenericClientCommandHandler(
-    CLIENT_COMMANDS.type,
-    ({ client, positionals, flags }) =>
-      client.interactions.type({
-        ...buildSelectionOptions(flags),
-        text: positionals.join(' '),
-        delayMs: flags.delayMs,
-      }),
+  [typeCommandDefinition.name]: createGenericClientCommandHandler(
+    typeCommandDefinition.name,
+    runTypeCliCommand,
   ),
   [CLIENT_COMMANDS.fill]: createGenericClientCommandHandler(
     CLIENT_COMMANDS.fill,

src/commands/command-definition.ts

@@ -0,0 +1,30 @@
+import type { CommandCapability } from '../core/capabilities.ts';
+import type { CommandSchema } from '../utils/command-schema.ts';
+
+export type CommandDefinition<TName extends string = string> = {
+  name: TName;
+  schema: CommandSchema;
+  capability: CommandCapability;
+};
+
+export function defineCommand<const TDefinition extends CommandDefinition>(
+  definition: TDefinition,
+): TDefinition {
+  return definition;
+}
+
+export function commandSchemaMap<TName extends string>(
+  definitions: readonly CommandDefinition<TName>[],
+): Record<TName, CommandSchema> {
+  return Object.fromEntries(
+    definitions.map((definition) => [definition.name, definition.schema]),
+  ) as Record<TName, CommandSchema>;
+}
+
+export function commandCapabilityMap<TName extends string>(
+  definitions: readonly CommandDefinition<TName>[],
+): Record<TName, CommandCapability> {
+  return Object.fromEntries(
+    definitions.map((definition) => [definition.name, definition.capability]),
+  ) as Record<TName, CommandCapability>;
+}

src/commands/interactions/__tests__/definition.test.ts

@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { getCommandCapability } from '../../../core/capabilities.ts';
+import { getCommandSchema } from '../../../utils/command-schema.ts';
+import { INTERACTION_COMMAND_DEFINITIONS } from '../definition.ts';
+
+test('interaction command definitions feed schema and capability registries', () => {
+  for (const definition of INTERACTION_COMMAND_DEFINITIONS) {
+    assert.deepEqual(getCommandSchema(definition.name), definition.schema);
+    assert.deepEqual(getCommandCapability(definition.name), definition.capability);
+  }
+});

src/commands/interactions/cli.ts

@@ -0,0 +1,21 @@
+import type { AgentDeviceClient, CommandRequestResult } from '../../client.ts';
+import type { CliFlags } from '../../utils/command-schema.ts';
+import { buildSelectionOptions } from '../../cli/commands/shared.ts';
+
+export type InteractionCliCommandParams = {
+  client: AgentDeviceClient;
+  positionals: string[];
+  flags: CliFlags;
+};
+
+export async function runTypeCliCommand({
+  client,
+  positionals,
+  flags,
+}: InteractionCliCommandParams): Promise<CommandRequestResult> {
+  return await client.interactions.type({
+    ...buildSelectionOptions(flags),
+    text: positionals.join(' '),
+    delayMs: flags.delayMs,
+  });
+}

src/commands/interactions/definition.ts

@@ -0,0 +1,24 @@
+import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
+import { commandCapabilityMap, commandSchemaMap, defineCommand } from '../command-definition.ts';
+
+export const typeCommandDefinition = defineCommand({
+  name: PUBLIC_COMMANDS.type,
+  schema: {
+    helpDescription: 'Type text in focused field',
+    positionalArgs: ['text'],
+    allowsExtraPositionals: true,
+    allowedFlags: ['delayMs'],
+  },
+  capability: {
+    apple: { simulator: true, device: true },
+    android: { emulator: true, device: true, unknown: true },
+    linux: { device: true },
+  },
+});
+
+export const INTERACTION_COMMAND_DEFINITIONS = [typeCommandDefinition] as const;
+
+export const INTERACTION_COMMAND_SCHEMAS = commandSchemaMap(INTERACTION_COMMAND_DEFINITIONS);
+export const INTERACTION_COMMAND_CAPABILITIES = commandCapabilityMap(
+  INTERACTION_COMMAND_DEFINITIONS,
+);

src/core/capabilities.ts

@@ -1,4 +1,5 @@
 import { isApplePlatform, type DeviceInfo } from '../utils/device.ts';
+import { INTERACTION_COMMAND_CAPABILITIES } from '../commands/interactions/definition.ts';
 
 type KindMatrix = {
   simulator?: boolean;
@@ -7,7 +8,7 @@ type KindMatrix = {
   unknown?: boolean;
 };
 
-type CommandCapability = {
+export type CommandCapability = {
   apple?: KindMatrix;
   android?: KindMatrix;
   linux?: KindMatrix;
@@ -227,11 +228,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
     android: { emulator: true, device: true, unknown: true },
     linux: LINUX_NONE,
   },
-  type: {
-    apple: { simulator: true, device: true },
-    android: { emulator: true, device: true, unknown: true },
-    linux: LINUX_DEVICE,
-  },
+  ...INTERACTION_COMMAND_CAPABILITIES,
   wait: {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true },
@@ -253,6 +250,10 @@ export function isCommandSupportedOnDevice(command: string, device: DeviceInfo):
   return byPlatform[kind] === true;
 }
 
+export function getCommandCapability(command: string): CommandCapability | undefined {
+  return COMMAND_CAPABILITY_MATRIX[command];
+}
+
 export function listCapabilityCommands(): string[] {
   return Object.keys(COMMAND_CAPABILITY_MATRIX).sort();
 }

src/daemon/handlers/interaction.ts

@@ -8,6 +8,7 @@ import { createInteractionRuntime } from './interaction-runtime.ts';
 import { finalizeTouchInteraction } from './interaction-common.ts';
 import { errorResponse } from './response.ts';
 import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import { typeCommandDefinition } from '../../commands/interactions/definition.ts';
 import { normalizeError } from '../../utils/errors.ts';
 import { successText } from '../../utils/success-text.ts';
 import { recoverAndroidBlockingSystemDialog } from '../android-system-dialog.ts';
@@ -27,7 +28,7 @@ export async function handleInteractionCommands(
   }
 
   switch (params.req.command) {
-    case 'type':
+    case typeCommandDefinition.name:
       return await dispatchTypeViaRuntime({
         ...params,
         captureSnapshotForSession,
@@ -49,7 +50,7 @@ async function dispatchTypeViaRuntime(
   const { req, sessionName, sessionStore } = params;
   const session = sessionStore.get(sessionName);
   if (!session) return errorResponse('SESSION_NOT_FOUND', 'No active session. Run open first.');
-  if (!isCommandSupportedOnDevice('type', session.device)) {
+  if (!isCommandSupportedOnDevice(typeCommandDefinition.name, session.device)) {
     return errorResponse('UNSUPPORTED_OPERATION', 'type is not supported on this device');
   }
   if (session.device.platform === 'android' && session.recording) {

src/utils/command-schema.ts

@@ -1,6 +1,7 @@
 import { SETTINGS_USAGE_OVERRIDE } from '../core/settings-contract.ts';
 import { SESSION_SURFACES } from '../core/session-surface.ts';
 import type { DaemonInstallSource } from '../contracts.ts';
+import { INTERACTION_COMMAND_SCHEMAS } from '../commands/interactions/definition.ts';
 
 export type CliFlags = {
   json: boolean;
@@ -130,7 +131,7 @@ export type FlagDefinition = {
   usageDescription?: string;
 };
 
-type CommandSchema = {
+export type CommandSchema = {
   helpDescription: string;
   summary?: string;
   positionalArgs: readonly string[];
@@ -1779,12 +1780,7 @@ const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     positionalArgs: ['x', 'y'],
     allowedFlags: [],
   },
-  type: {
-    helpDescription: 'Type text in focused field',
-    positionalArgs: ['text'],
-    allowsExtraPositionals: true,
-    allowedFlags: ['delayMs'],
-  },
+  ...INTERACTION_COMMAND_SCHEMAS,
   fill: {
     usageOverride: 'fill <x> <y> <text> | fill <@ref|selector> <text>',
     helpDescription: 'Tap then type',