feat: expose typed client command methods

Author: thymikee

src/__tests__/cli-client-commands.test.ts

@@ -274,6 +274,121 @@ test('screenshot reports annotated ref count in non-json mode', async () => {
   assert.equal(stdout, 'Annotated 2 refs onto /tmp/screenshot.png\n');
 });
 
+test('wait routes through the typed client command API', async () => {
+  let observed: Parameters<AgentDeviceClient['command']['wait']>[0] | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+  });
+  client.command.wait = async (options) => {
+    observed = options;
+    return { selector: 'role=button[name="Continue"]', waitedMs: 12 };
+  };
+
+  const handled = await tryRunClientBackedCommand({
+    command: 'wait',
+    positionals: ['role=button[name="Continue"]', '1500'],
+    flags: {
+      json: false,
+      help: false,
+      version: false,
+      platform: 'android',
+      snapshotDepth: 3,
+      snapshotRaw: true,
+    },
+    client,
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(observed, {
+    platform: 'android',
+    target: undefined,
+    device: undefined,
+    udid: undefined,
+    serial: undefined,
+    iosSimulatorDeviceSet: undefined,
+    androidDeviceAllowlist: undefined,
+    depth: 3,
+    scope: undefined,
+    raw: true,
+    selector: 'role=button[name="Continue"]',
+    timeoutMs: 1500,
+  });
+});
+
+test('back routes through the typed client command API', async () => {
+  let observed: Parameters<AgentDeviceClient['command']['back']>[0] | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+  });
+  client.command.back = async (options) => {
+    observed = options;
+    return { action: 'back', mode: 'system', message: 'Back' };
+  };
+
+  const stdout = await captureStdout(async () => {
+    const handled = await tryRunClientBackedCommand({
+      command: 'back',
+      positionals: [],
+      flags: {
+        json: false,
+        help: false,
+        version: false,
+        platform: 'android',
+        backMode: 'system',
+      },
+      client,
+    });
+    assert.equal(handled, true);
+  });
+
+  assert.equal(stdout, 'Back\n');
+  assert.equal(observed?.platform, 'android');
+  assert.equal(observed?.mode, 'system');
+});
+
+test('appstate routes through the typed client command API and keeps human output', async () => {
+  let observed: Parameters<AgentDeviceClient['command']['appState']>[0] | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+  });
+  client.command.appState = async (options) => {
+    observed = options;
+    return {
+      platform: 'ios',
+      appName: 'Settings',
+      appBundleId: 'com.apple.Preferences',
+      source: 'session',
+    };
+  };
+
+  const stdout = await captureStdout(async () => {
+    const handled = await tryRunClientBackedCommand({
+      command: 'appstate',
+      positionals: [],
+      flags: {
+        json: false,
+        help: false,
+        version: false,
+        platform: 'ios',
+      },
+      client,
+    });
+    assert.equal(handled, true);
+  });
+
+  assert.equal(
+    stdout,
+    'Foreground app: Settings\nBundle: com.apple.Preferences\nSource: session\n',
+  );
+  assert.equal(observed?.platform, 'ios');
+});
+
 test('metro prepare wraps output in the standard success envelope for --json', async () => {
   const client = createStubClient({
     installFromSource: async () => {
@@ -634,7 +749,21 @@ function createStubClient(params: {
   open?: AgentDeviceClient['apps']['open'];
   screenshot?: AgentDeviceClient['capture']['screenshot'];
 }): AgentDeviceClient {
+  const unexpectedCommandCall = async (): Promise<never> => {
+    throw new Error('unexpected command call');
+  };
   return {
+    command: {
+      wait: unexpectedCommandCall,
+      alert: unexpectedCommandCall,
+      appState: unexpectedCommandCall,
+      back: unexpectedCommandCall,
+      home: unexpectedCommandCall,
+      rotate: unexpectedCommandCall,
+      appSwitcher: unexpectedCommandCall,
+      keyboard: unexpectedCommandCall,
+      clipboard: unexpectedCommandCall,
+    },
     devices: {
       list: async () => [],
     },

src/__tests__/client.test.ts

@@ -1,5 +1,8 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { createAgentDeviceClient, type AgentDeviceClientConfig } from '../client.ts';
 import type { DaemonRequest, DaemonResponse } from '../daemon/types.ts';
 import { AppError } from '../utils/errors.ts';
@@ -347,6 +350,169 @@ test('client throws AppError for daemon failures', async () => {
   );
 });
 
+test('client.command.back forwards typed options through shared request metadata', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      action: 'back',
+      mode: 'system',
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const result = await client.command.back({
+    mode: 'system',
+    platform: 'android',
+  });
+
+  assert.equal(setup.calls.length, 1);
+  assert.equal(setup.calls[0]?.session, 'qa');
+  assert.equal(setup.calls[0]?.command, 'back');
+  assert.deepEqual(setup.calls[0]?.positionals, []);
+  assert.equal(setup.calls[0]?.flags?.backMode, 'system');
+  assert.equal(setup.calls[0]?.flags?.platform, 'android');
+  assert.equal(setup.calls[0]?.flags?.daemonBaseUrl, 'http://daemon.example.test');
+  assert.equal(setup.calls[0]?.meta?.tenantId, 'acme');
+  assert.equal(setup.calls[0]?.meta?.runId, 'run-123');
+  assert.equal(setup.calls[0]?.meta?.leaseId, 'lease-123');
+  assert.deepEqual(result, {
+    action: 'back',
+    mode: 'system',
+  });
+});
+
+test('client.command.wait prepares selector options without raw daemon requests', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      selector: 'role=button[name="Continue"]',
+      waitedMs: 120,
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const result = await client.command.wait({
+    selector: 'role=button[name="Continue"]',
+    timeoutMs: 1_500,
+    depth: 3,
+    raw: true,
+  });
+
+  assert.equal(setup.calls.length, 1);
+  assert.equal(setup.calls[0]?.command, 'wait');
+  assert.deepEqual(setup.calls[0]?.positionals, ['role=button[name="Continue"]', '1500']);
+  assert.equal(setup.calls[0]?.flags?.snapshotDepth, 3);
+  assert.equal(setup.calls[0]?.flags?.snapshotRaw, true);
+  assert.deepEqual(result, {
+    selector: 'role=button[name="Continue"]',
+    waitedMs: 120,
+  });
+});
+
+test('client.command.appSwitcher maps to daemon app-switcher command', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      action: 'app-switcher',
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  await client.command.appSwitcher();
+
+  assert.equal(setup.calls.length, 1);
+  assert.equal(setup.calls[0]?.command, 'app-switcher');
+  assert.deepEqual(setup.calls[0]?.positionals, []);
+});
+
+test('remote-config defaults are scoped to the command escape hatch', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-client-remote-scope-'));
+  try {
+    const remoteConfig = path.join(tempRoot, 'remote.json');
+    fs.writeFileSync(
+      remoteConfig,
+      JSON.stringify({
+        session: 'remote-session',
+        platform: 'android',
+        daemonBaseUrl: 'http://127.0.0.1:9124/agent-device',
+      }),
+    );
+    const setup = createTransport(async () => ({
+      ok: true,
+      data: {
+        devices: [],
+      },
+    }));
+    const client = createAgentDeviceClient(
+      {
+        session: 'local-session',
+        remoteConfig,
+        cwd: tempRoot,
+      },
+      { transport: setup.transport },
+    );
+
+    await client.devices.list();
+
+    assert.equal(setup.calls.length, 1);
+    assert.equal(setup.calls[0]?.session, 'local-session');
+    assert.equal(setup.calls[0]?.command, 'devices');
+    assert.equal(setup.calls[0]?.flags?.platform, undefined);
+    assert.equal(setup.calls[0]?.flags?.daemonBaseUrl, undefined);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('client.command.home applies remote-config defaults before daemon transport', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-client-remote-config-'));
+  try {
+    const remoteConfig = path.join(tempRoot, 'remote.json');
+    fs.writeFileSync(
+      remoteConfig,
+      JSON.stringify({
+        session: 'remote-session',
+        platform: 'android',
+        daemonBaseUrl: 'http://127.0.0.1:9124/agent-device',
+        tenant: 'remote-tenant',
+        sessionIsolation: 'tenant',
+        runId: 'remote-run',
+        leaseId: 'remote-lease',
+      }),
+    );
+    const setup = createTransport(async () => ({
+      ok: true,
+      data: {
+        action: 'home',
+      },
+    }));
+    const client = createAgentDeviceClient(
+      {
+        remoteConfig,
+        cwd: tempRoot,
+      },
+      { transport: setup.transport },
+    );
+
+    await client.command.home();
+
+    assert.equal(setup.calls.length, 1);
+    assert.equal(setup.calls[0]?.session, 'remote-session');
+    assert.equal(setup.calls[0]?.command, 'home');
+    assert.equal(setup.calls[0]?.flags?.platform, 'android');
+    assert.equal(setup.calls[0]?.flags?.daemonBaseUrl, 'http://127.0.0.1:9124/agent-device');
+    assert.equal(setup.calls[0]?.flags?.tenant, 'remote-tenant');
+    assert.equal(setup.calls[0]?.flags?.sessionIsolation, 'tenant');
+    assert.equal(setup.calls[0]?.flags?.runId, 'remote-run');
+    assert.equal(setup.calls[0]?.flags?.leaseId, 'remote-lease');
+    assert.equal(setup.calls[0]?.meta?.tenantId, 'remote-tenant');
+    assert.equal(setup.calls[0]?.meta?.runId, 'remote-run');
+    assert.equal(setup.calls[0]?.meta?.leaseId, 'remote-lease');
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test('client capture.snapshot preserves visibility metadata from daemon responses', async () => {
   const setup = createTransport(async () => ({
     ok: true,