agent-device 0.4.2 → 0.5.0

package/src/daemon/__tests__/selectors.test.ts

@@ -1,261 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import type { SnapshotState } from '../../utils/snapshot.ts';
-import {
-  buildSelectorChainForNode,
-  findSelectorChainMatch,
-  isSelectorToken,
-  parseSelectorChain,
-  resolveSelectorChain,
-  splitSelectorFromArgs,
-} from '../selectors.ts';
-
-const nodes: SnapshotState['nodes'] = [
-  {
-    ref: 'e1',
-    index: 0,
-    type: 'XCUIElementTypeTextField',
-    label: 'Email',
-    value: '',
-    identifier: 'login_email',
-    rect: { x: 0, y: 0, width: 200, height: 44 },
-    enabled: true,
-    hittable: true,
-  },
-  {
-    ref: 'e2',
-    index: 1,
-    type: 'XCUIElementTypeButton',
-    label: 'Continue',
-    identifier: 'auth_continue',
-    rect: { x: 0, y: 80, width: 200, height: 44 },
-    enabled: true,
-    hittable: true,
-  },
-  {
-    ref: 'e3',
-    index: 2,
-    type: 'XCUIElementTypeButton',
-    label: 'Continue',
-    identifier: 'secondary_continue',
-    rect: { x: 0, y: 140, width: 200, height: 44 },
-    enabled: true,
-    hittable: true,
-  },
-];
-
-test('parseSelectorChain parses fallback and boolean terms', () => {
-  const chain = parseSelectorChain('id=auth_continue || role=button label="Continue" visible=true');
-  assert.equal(chain.selectors.length, 2);
-  assert.equal(chain.selectors[0].terms[0].key, 'id');
-  assert.equal(chain.selectors[1].terms[2].key, 'visible');
-});
-
-test('resolveSelectorChain resolves unique match', () => {
-  const chain = parseSelectorChain('id=login_email');
-  const resolved = resolveSelectorChain(nodes, chain, {
-    platform: 'ios',
-    requireRect: true,
-    requireUnique: true,
-  });
-  assert.ok(resolved);
-  assert.equal(resolved.node.ref, 'e1');
-});
-
-test('resolveSelectorChain falls back when first selector is ambiguous', () => {
-  const chain = parseSelectorChain('label="Continue" || id=auth_continue');
-  const resolved = resolveSelectorChain(nodes, chain, {
-    platform: 'ios',
-    requireRect: true,
-    requireUnique: true,
-  });
-  assert.ok(resolved);
-  assert.equal(resolved.selectorIndex, 1);
-  assert.equal(resolved.node.ref, 'e2');
-});
-
-test('resolveSelectorChain keeps strict ambiguity behavior by default', () => {
-  const chain = parseSelectorChain('label="Continue"');
-  const resolved = resolveSelectorChain(nodes, chain, {
-    platform: 'ios',
-    requireRect: true,
-    requireUnique: true,
-  });
-  assert.equal(resolved, null);
-});
-
-test('resolveSelectorChain disambiguates to deeper/smaller matching node when enabled', () => {
-  const disambiguationNodes: SnapshotState['nodes'] = [
-    {
-      ref: 'e1',
-      index: 0,
-      type: 'Other',
-      label: 'Press me',
-      rect: { x: 0, y: 0, width: 300, height: 300 },
-      depth: 1,
-      enabled: true,
-      hittable: true,
-    },
-    {
-      ref: 'e2',
-      index: 1,
-      type: 'Other',
-      label: 'Press me',
-      rect: { x: 10, y: 10, width: 100, height: 20 },
-      depth: 2,
-      enabled: true,
-      hittable: true,
-    },
-  ];
-  const chain = parseSelectorChain('role="other" label="Press me" || label="Press me"');
-  const resolved = resolveSelectorChain(disambiguationNodes, chain, {
-    platform: 'ios',
-    requireRect: true,
-    requireUnique: true,
-    disambiguateAmbiguous: true,
-  });
-  assert.ok(resolved);
-  assert.equal(resolved.node.ref, 'e2');
-  assert.equal(resolved.matches, 2);
-});
-
-test('resolveSelectorChain disambiguation tie falls back to next selector', () => {
-  const tieNodes: SnapshotState['nodes'] = [
-    {
-      ref: 'e1',
-      index: 0,
-      type: 'Other',
-      label: 'Press me',
-      rect: { x: 0, y: 0, width: 100, height: 20 },
-      depth: 2,
-      enabled: true,
-      hittable: true,
-    },
-    {
-      ref: 'e2',
-      index: 1,
-      type: 'Other',
-      label: 'Press me',
-      rect: { x: 0, y: 40, width: 100, height: 20 },
-      depth: 2,
-      enabled: true,
-      hittable: true,
-    },
-    {
-      ref: 'e3',
-      index: 2,
-      type: 'Other',
-      label: 'Press me',
-      identifier: 'press_me_unique',
-      rect: { x: 0, y: 80, width: 100, height: 20 },
-      depth: 2,
-      enabled: true,
-      hittable: true,
-    },
-  ];
-  const chain = parseSelectorChain('label="Press me" || id="press_me_unique"');
-  const resolved = resolveSelectorChain(tieNodes, chain, {
-    platform: 'ios',
-    requireRect: true,
-    requireUnique: true,
-    disambiguateAmbiguous: true,
-  });
-  assert.ok(resolved);
-  assert.equal(resolved.selectorIndex, 1);
-  assert.equal(resolved.node.ref, 'e3');
-});
-
-test('findSelectorChainMatch returns first matching selector for existence checks', () => {
-  const chain = parseSelectorChain('label="Continue" || id=auth_continue');
-  const match = findSelectorChainMatch(nodes, chain, {
-    platform: 'ios',
-  });
-  assert.ok(match);
-  assert.equal(match.selectorIndex, 0);
-  assert.equal(match.matches, 2);
-});
-
-test('splitSelectorFromArgs extracts selector prefix and trailing value', () => {
-  const split = splitSelectorFromArgs(['id=login_email', 'editable=true', 'qa@example.com']);
-  assert.ok(split);
-  assert.equal(split.selectorExpression, 'id=login_email editable=true');
-  assert.deepEqual(split.rest, ['qa@example.com']);
-});
-
-test('splitSelectorFromArgs prefers trailing token for value when requested', () => {
-  const split = splitSelectorFromArgs(['label="Filter"', 'visible=true'], { preferTrailingValue: true });
-  assert.ok(split);
-  assert.equal(split.selectorExpression, 'label="Filter"');
-  assert.deepEqual(split.rest, ['visible=true']);
-});
-
-test('splitSelectorFromArgs keeps full selector when trailing value preference is disabled', () => {
-  const split = splitSelectorFromArgs(['label="Filter"', 'visible=true']);
-  assert.ok(split);
-  assert.equal(split.selectorExpression, 'label="Filter" visible=true');
-  assert.deepEqual(split.rest, []);
-});
-
-test('parseSelectorChain rejects unknown keys and malformed quotes', () => {
-  assert.throws(() => parseSelectorChain('foo=bar'), /Unknown selector key/i);
-  assert.throws(() => parseSelectorChain('label="unclosed'), /Unclosed quote/i);
-  assert.throws(() => parseSelectorChain(''), /cannot be empty/i);
-});
-
-test('parseSelectorChain handles quoted values ending in escaped backslashes', () => {
-  const chain = parseSelectorChain('label="path\\\\" || id=auth_continue');
-  assert.equal(chain.selectors.length, 2);
-});
-
-test('isSelectorToken only accepts known keys for key=value tokens', () => {
-  assert.equal(isSelectorToken('id=foo'), true);
-  assert.equal(isSelectorToken('editable=true'), true);
-  assert.equal(isSelectorToken('foo=bar'), false);
-  assert.equal(isSelectorToken('a=b'), false);
-});
-
-test('text selector matches extractNodeText semantics (first non-empty field)', () => {
-  const chainByLabel = parseSelectorChain('text=Email');
-  const chainById = parseSelectorChain('text=login_email');
-  const resolvedLabel = resolveSelectorChain(nodes, chainByLabel, {
-    platform: 'ios',
-    requireUnique: true,
-  });
-  const resolvedId = resolveSelectorChain(nodes, chainById, {
-    platform: 'ios',
-    requireUnique: true,
-  });
-  assert.ok(resolvedLabel);
-  assert.equal(resolvedLabel.node.ref, 'e1');
-  assert.equal(resolvedId, null);
-});
-
-test('buildSelectorChainForNode prefers id and adds editable for fill action', () => {
-  const target = nodes[0];
-  const chain = buildSelectorChainForNode(target, 'ios', { action: 'fill' });
-  assert.ok(chain.some((entry) => entry.includes('id=')));
-  assert.ok(chain.some((entry) => entry.includes('editable=true')));
-});
-
-test('role selector normalization matches Android class names by leaf type', () => {
-  const androidNodes: SnapshotState['nodes'] = [
-    {
-      ref: 'a1',
-      index: 0,
-      type: 'android.widget.Button',
-      label: 'Continue',
-      identifier: 'auth_continue',
-      rect: { x: 0, y: 0, width: 120, height: 44 },
-      enabled: true,
-      hittable: true,
-    },
-  ];
-  const chain = parseSelectorChain('role=button label="Continue"');
-  const resolved = resolveSelectorChain(androidNodes, chain, {
-    platform: 'android',
-    requireRect: true,
-    requireUnique: true,
-  });
-  assert.ok(resolved);
-  assert.equal(resolved.node.ref, 'a1');
-});

package/src/daemon/__tests__/session-routing.test.ts

@@ -1,108 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import os from 'node:os';
-import path from 'node:path';
-import { SessionStore } from '../session-store.ts';
-import { resolveEffectiveSessionName } from '../session-routing.ts';
-import type { SessionState } from '../types.ts';
-
-function makeSession(name: string): SessionState {
-  return {
-    name,
-    device: {
-      platform: 'android',
-      id: 'emulator-5554',
-      name: 'Pixel',
-      kind: 'emulator',
-      booted: true,
-    },
-    createdAt: Date.now(),
-    actions: [],
-  };
-}
-
-function makeStore(): SessionStore {
-  return new SessionStore(path.join(os.tmpdir(), 'agent-device-session-routing-tests'));
-}
-
-test('reuses lone active session for implicit default session', () => {
-  const store = makeStore();
-  store.set('android', makeSession('android'));
-
-  const resolved = resolveEffectiveSessionName(
-    {
-      token: 't',
-      session: 'default',
-      command: 'open',
-      positionals: ['com.google.android.apps.maps'],
-      flags: {},
-    },
-    store,
-  );
-
-  assert.equal(resolved, 'android');
-});
-
-test('keeps requested default when explicit --session is provided', () => {
-  const store = makeStore();
-  store.set('android', makeSession('android'));
-
-  const resolved = resolveEffectiveSessionName(
-    {
-      token: 't',
-      session: 'default',
-      command: 'open',
-      positionals: ['com.google.android.apps.maps'],
-      flags: { session: 'default' },
-    },
-    store,
-  );
-
-  assert.equal(resolved, 'default');
-});
-
-test('keeps requested non-default session names', () => {
-  const store = makeStore();
-  store.set('android', makeSession('android'));
-
-  const resolved = resolveEffectiveSessionName(
-    {
-      token: 't',
-      session: 'maps-test',
-      command: 'open',
-      positionals: ['com.google.android.apps.maps'],
-      flags: {},
-    },
-    store,
-  );
-
-  assert.equal(resolved, 'maps-test');
-});
-
-test('does not reuse when multiple sessions are active', () => {
-  const store = makeStore();
-  store.set('android', makeSession('android'));
-  store.set('ios', {
-    ...makeSession('ios'),
-    device: {
-      platform: 'ios',
-      id: 'ios-sim',
-      name: 'iPhone',
-      kind: 'simulator',
-      booted: true,
-    },
-  });
-
-  const resolved = resolveEffectiveSessionName(
-    {
-      token: 't',
-      session: 'default',
-      command: 'open',
-      positionals: ['com.google.android.apps.maps'],
-      flags: {},
-    },
-    store,
-  );
-
-  assert.equal(resolved, 'default');
-});

package/src/daemon/__tests__/session-selector.test.ts

@@ -1,64 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { assertSessionSelectorMatches } from '../session-selector.ts';
-import { AppError } from '../../utils/errors.ts';
-import type { SessionState } from '../types.ts';
-
-function makeSession(overrides?: Partial<SessionState>): SessionState {
-  return {
-    name: 'default',
-    device: {
-      platform: 'android',
-      id: 'emulator-5554',
-      name: 'Pixel 9',
-      kind: 'emulator',
-      booted: true,
-    },
-    createdAt: Date.now(),
-    actions: [],
-    ...overrides,
-  };
-}
-
-test('accepts matching platform and serial selectors', () => {
-  const session = makeSession();
-  assert.doesNotThrow(() =>
-    assertSessionSelectorMatches(session, {
-      platform: 'android',
-      serial: 'emulator-5554',
-    }),
-  );
-});
-
-test('rejects mismatched platform selector', () => {
-  const session = makeSession();
-  assert.throws(
-    () => assertSessionSelectorMatches(session, { platform: 'ios' }),
-    (err: unknown) =>
-      err instanceof AppError &&
-      err.code === 'INVALID_ARGS' &&
-      err.message.includes('--platform=ios'),
-  );
-});
-
-test('rejects mismatched serial selector', () => {
-  const session = makeSession();
-  assert.throws(
-    () => assertSessionSelectorMatches(session, { serial: 'emulator-9999' }),
-    (err: unknown) =>
-      err instanceof AppError &&
-      err.code === 'INVALID_ARGS' &&
-      err.message.includes('--serial=emulator-9999'),
-  );
-});
-
-test('rejects udid selector for android session', () => {
-  const session = makeSession();
-  assert.throws(
-    () => assertSessionSelectorMatches(session, { udid: 'ABC-123' }),
-    (err: unknown) =>
-      err instanceof AppError &&
-      err.code === 'INVALID_ARGS' &&
-      err.message.includes('--udid=ABC-123'),
-  );
-});

package/src/daemon/__tests__/session-store.test.ts

@@ -1,142 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { SessionStore } from '../session-store.ts';
-import type { SessionState } from '../types.ts';
-
-function makeSession(name: string): SessionState {
-  return {
-    name,
-    device: {
-      platform: 'ios',
-      id: 'sim-1',
-      name: 'iPhone',
-      kind: 'simulator',
-      booted: true,
-    },
-    createdAt: Date.now(),
-    actions: [],
-  };
-}
-
-test('recordAction stores normalized action entries', () => {
-  const store = new SessionStore(path.join(os.tmpdir(), 'agent-device-tests'));
-  const session = makeSession('default');
-  store.recordAction(session, {
-    command: 'snapshot',
-    positionals: [],
-    flags: { platform: 'ios', snapshotInteractiveOnly: true, verbose: true },
-    result: { nodes: 1 },
-  });
-  assert.equal(session.actions.length, 1);
-  assert.equal(session.actions[0].command, 'snapshot');
-  assert.equal(session.actions[0].flags.platform, 'ios');
-  assert.equal(session.actions[0].flags.snapshotInteractiveOnly, true);
-});
-
-test('recordAction skips entries marked noRecord', () => {
-  const store = new SessionStore(path.join(os.tmpdir(), 'agent-device-tests'));
-  const session = makeSession('default');
-  store.recordAction(session, {
-    command: 'click',
-    positionals: ['@e1'],
-    flags: { noRecord: true },
-    result: {},
-  });
-  assert.equal(session.actions.length, 0);
-});
-
-test('defaultTracePath sanitizes session name', () => {
-  const store = new SessionStore(path.join(os.tmpdir(), 'agent-device-tests'));
-  const session = makeSession('session with spaces');
-  const tracePath = store.defaultTracePath(session);
-  assert.match(tracePath, /session_with_spaces/);
-  assert.match(tracePath, /\.trace\.log$/);
-});
-
-test('writeSessionLog writes .ad only when recording is enabled', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-disabled-'));
-  const store = new SessionStore(root);
-  const session = makeSession('default');
-  store.recordAction(session, {
-    command: 'open',
-    positionals: ['Settings'],
-    flags: { platform: 'ios' },
-    result: {},
-  });
-
-  store.writeSessionLog(session);
-  const files = fs.readdirSync(root);
-  assert.equal(files.filter((file) => file.endsWith('.ad')).length, 0);
-});
-
-test('saveScript flag enables .ad session log writing', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-enabled-'));
-  const store = new SessionStore(root);
-  const session = makeSession('default');
-  store.recordAction(session, {
-    command: 'open',
-    positionals: ['Settings'],
-    flags: { platform: 'ios', saveScript: true },
-    result: {},
-  });
-  store.recordAction(session, {
-    command: 'close',
-    positionals: [],
-    flags: { platform: 'ios' },
-    result: {},
-  });
-
-  store.writeSessionLog(session);
-  const files = fs.readdirSync(root);
-  assert.equal(files.filter((file) => file.endsWith('.ad')).length, 1);
-});
-
-test('saveScript path writes session log to custom location', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-custom-path-'));
-  const store = new SessionStore(path.join(root, 'sessions'));
-  const session = makeSession('default');
-  const customPath = path.join(root, 'workflows', 'my-flow.ad');
-  store.recordAction(session, {
-    command: 'open',
-    positionals: ['Settings'],
-    flags: { platform: 'ios', saveScript: customPath },
-    result: {},
-  });
-  store.recordAction(session, {
-    command: 'close',
-    positionals: [],
-    flags: { platform: 'ios' },
-    result: {},
-  });
-
-  store.writeSessionLog(session);
-  assert.equal(fs.existsSync(customPath), true);
-  assert.equal(fs.existsSync(path.join(root, 'sessions')), false);
-});
-
-test('writeSessionLog persists open --relaunch in script output', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-relaunch-'));
-  const store = new SessionStore(root);
-  const session = makeSession('default');
-  store.recordAction(session, {
-    command: 'open',
-    positionals: ['Settings'],
-    flags: { platform: 'ios', saveScript: true, relaunch: true },
-    result: {},
-  });
-  store.recordAction(session, {
-    command: 'close',
-    positionals: [],
-    flags: { platform: 'ios' },
-    result: {},
-  });
-
-  store.writeSessionLog(session);
-  const scriptFile = fs.readdirSync(root).find((file) => file.endsWith('.ad'));
-  assert.ok(scriptFile);
-  const script = fs.readFileSync(path.join(root, scriptFile!), 'utf8');
-  assert.match(script, /open "Settings" --relaunch/);
-});

package/src/daemon/__tests__/snapshot-processing.test.ts

@@ -1,47 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { attachRefs } from '../../utils/snapshot.ts';
-import {
-  findNearestHittableAncestor,
-  isFillableType,
-  pruneGroupNodes,
-  resolveRefLabel,
-} from '../snapshot-processing.ts';
-
-test('pruneGroupNodes drops unlabeled group wrappers and rebalances depth', () => {
-  const raw = [
-    { index: 0, depth: 0, type: 'XCUIElementTypeWindow', label: 'Root' },
-    { index: 1, depth: 1, type: 'XCUIElementTypeGroup' },
-    { index: 2, depth: 2, type: 'XCUIElementTypeButton', label: 'Continue' },
-  ];
-  const pruned = pruneGroupNodes(raw);
-  assert.equal(pruned.length, 2);
-  assert.equal(pruned[1].depth, 1);
-  assert.equal(pruned[1].label, 'Continue');
-});
-
-test('resolveRefLabel falls back to nearest meaningful neighbor', () => {
-  const nodes = attachRefs([
-    { index: 0, depth: 0, label: 'Email', rect: { x: 0, y: 10, width: 100, height: 20 } },
-    { index: 1, depth: 0, label: '', value: '', rect: { x: 0, y: 14, width: 100, height: 20 } },
-  ]);
-  const resolved = resolveRefLabel(nodes[1], nodes);
-  assert.equal(resolved, 'Email');
-});
-
-test('findNearestHittableAncestor walks parents until hittable node', () => {
-  const nodes = attachRefs([
-    { index: 0, parentIndex: undefined, hittable: true, rect: { x: 0, y: 0, width: 100, height: 40 } },
-    { index: 1, parentIndex: 0, hittable: false, rect: { x: 0, y: 0, width: 50, height: 20 } },
-    { index: 2, parentIndex: 1, hittable: false, rect: { x: 0, y: 0, width: 20, height: 20 } },
-  ]);
-  const ancestor = findNearestHittableAncestor(nodes, nodes[2]);
-  assert.equal(ancestor?.ref, 'e1');
-});
-
-test('isFillableType matches platform-specific editable controls', () => {
-  assert.equal(isFillableType('XCUIElementTypeTextField', 'ios'), true);
-  assert.equal(isFillableType('XCUIElementTypeButton', 'ios'), false);
-  assert.equal(isFillableType('android.widget.EditText', 'android'), true);
-  assert.equal(isFillableType('android.widget.Button', 'android'), false);
-});

package/src/daemon/action-utils.ts

@@ -1,29 +0,0 @@
-import type { SessionAction } from './types.ts';
-
-export function inferFillText(action: SessionAction): string {
-  const resultText = action.result?.text;
-  if (typeof resultText === 'string' && resultText.trim().length > 0) {
-    return resultText;
-  }
-  const positionals = action.positionals ?? [];
-  if (positionals.length === 0) return '';
-  if (positionals[0].startsWith('@')) {
-    if (positionals.length >= 3) return positionals.slice(2).join(' ').trim();
-    return positionals.slice(1).join(' ').trim();
-  }
-  if (positionals.length >= 3 && !Number.isNaN(Number(positionals[0])) && !Number.isNaN(Number(positionals[1]))) {
-    return positionals.slice(2).join(' ').trim();
-  }
-  return positionals.slice(1).join(' ').trim();
-}
-
-export function uniqueStrings(values: string[]): string[] {
-  const seen = new Set<string>();
-  const output: string[] = [];
-  for (const value of values) {
-    if (seen.has(value)) continue;
-    seen.add(value);
-    output.push(value);
-  }
-  return output;
-}

package/src/daemon/context.ts

@@ -1,48 +0,0 @@
-import type { CommandFlags } from '../core/dispatch.ts';
-
-export type DaemonCommandContext = {
-  appBundleId?: string;
-  activity?: string;
-  verbose?: boolean;
-  logPath?: string;
-  traceLogPath?: string;
-  snapshotInteractiveOnly?: boolean;
-  snapshotCompact?: boolean;
-  snapshotDepth?: number;
-  snapshotScope?: string;
-  snapshotBackend?: 'ax' | 'xctest';
-  snapshotRaw?: boolean;
-  count?: number;
-  intervalMs?: number;
-  holdMs?: number;
-  jitterPx?: number;
-  pauseMs?: number;
-  pattern?: 'one-way' | 'ping-pong';
-};
-
-export function contextFromFlags(
-  logPath: string,
-  flags: CommandFlags | undefined,
-  appBundleId?: string,
-  traceLogPath?: string,
-): DaemonCommandContext {
-  return {
-    appBundleId,
-    activity: flags?.activity,
-    verbose: flags?.verbose,
-    logPath,
-    traceLogPath,
-    snapshotInteractiveOnly: flags?.snapshotInteractiveOnly,
-    snapshotCompact: flags?.snapshotCompact,
-    snapshotDepth: flags?.snapshotDepth,
-    snapshotScope: flags?.snapshotScope,
-    snapshotRaw: flags?.snapshotRaw,
-    snapshotBackend: flags?.snapshotBackend,
-    count: flags?.count,
-    intervalMs: flags?.intervalMs,
-    holdMs: flags?.holdMs,
-    jitterPx: flags?.jitterPx,
-    pauseMs: flags?.pauseMs,
-    pattern: flags?.pattern,
-  };
-}