lynkeus 0.2.0

package/src/commands/crawl/return.ts

@@ -0,0 +1,130 @@
+import { execSync } from 'node:child_process';
+
+import type { Screen } from 'lynkeus-protocol';
+
+import type { Device } from '../../device/driver.js';
+import { runFlow } from '../../flow/runner.js';
+import type { CrawlOptions } from '../crawl.js';
+import { clearOverlayIfShown } from '../overlay.js';
+import { isCloser, presented, stateKey, targetFor, targetOf } from './state.js';
+
+/** Fatal: exploring a logged-out app would record its intro screens as reachable from logged-in ones, and poison `plan`. */
+export class RecoveryError extends Error {}
+
+type Context = { device: Device; options: CrawlOptions; goTo: (route: string | undefined) => Promise<void> };
+
+/** How the crawl gets back to where it was standing, or back to life. */
+export const createReturns = ({ device, options, goTo }: Context) => {
+  const dead = (s: Screen) => !s.route && s.elements.length === 0;
+  const pressed = (target: ReturnType<typeof targetFor>, timeoutMs: number) =>
+    device
+      .waitFor({ target, timeoutMs })
+      .then(() => device.press(target))
+      .then(
+        () => true,
+        () => false,
+      );
+
+  const logIn = async (login: NonNullable<CrawlOptions['login']>) => {
+    const entry = (await device.screen()).route;
+    const vars = { ...login.vars };
+    for (const flow of login.flows) {
+      for (const name of flow.vars ?? []) {
+        const command = login.varCommands?.[name];
+        if (!command) continue;
+        options.log?.(`${name} ← ${command}`);
+        vars[name] = execSync(command, { encoding: 'utf8' }).trim();
+        if (!vars[name]) throw new RecoveryError(`the command for {{${name}}} printed nothing`);
+      }
+      options.log?.(`login: ${flow.name}`);
+      const report = await runFlow(flow, { device, vars });
+      if (!report.ok) throw new RecoveryError(`login flow "${flow.name}" failed at step ${report.steps.length}`);
+    }
+    const after = await device.screen();
+    if (!after.route || after.route === entry) throw new RecoveryError(`login left the app on ${after.route ?? 'no route'}`);
+  };
+
+  const recover = async () => {
+    if (device.server.hello?.app?.runtime === 'headless') {
+      // A host has no process to relaunch; a reset mounts the app again from scratch.
+      await device.command('reset');
+      if (options.login) await logIn(options.login);
+      return;
+    }
+    if (!options.appId) throw new RecoveryError('App disconnected and no --app to relaunch');
+    await device.launchApp(options.appId, { fresh: true });
+    await clearOverlayIfShown(device, options.overlay);
+  };
+
+  // Sheets animate on the UI thread after React has gone quiet: a screen whose controls are all still covered gets one more look.
+  const settle = async (): Promise<Screen> => {
+    await device.idle({ quietMs: 150, timeoutMs: 800 });
+    const screen = await device.screen();
+    const controls = presented(screen).filter((e) => e.kind === 'button');
+    if (controls.length === 0 || !controls.every((e) => e.covered)) return screen;
+    await new Promise((r) => setTimeout(r, 400));
+    return device.screen();
+  };
+
+  const changedFrom = async (now: Screen) => {
+    await device.idle({ quietMs: 150, timeoutMs: 800 });
+    return stateKey(await device.screen()) !== stateKey(now);
+  };
+
+  /** Without knowing what an app calls its close button: its declared closer, then its backdrop, a swipe down, back. */
+  const closeOverlay = async (now: Screen) => {
+    // Only what the layer offers: a "Close" on the screen it covers is out of reach.
+    const closer = options.closers ? presented(now).find((e) => isCloser(e, options.closers!)) : undefined;
+    if (closer) return device.press(targetOf(closer));
+    const backdrop = now.presenting ? now.elements[now.presenting.i] : undefined;
+    if (backdrop?.kind === 'button' && backdrop.enabled) {
+      await device.press(targetOf(backdrop));
+      if (await changedFrom(now)) return;
+    }
+    await device.swipe({ direction: 'down' });
+    if (await changedFrom(now)) return;
+    await device.back().catch(() => undefined);
+  };
+
+  const revive = async (): Promise<Screen> => {
+    const now = await settle();
+    if (!dead(now)) return now;
+    options.log?.('navigator is dead; recovering before exploring');
+    await recover().catch(() => undefined);
+    return settle();
+  };
+
+  /** Back on the route is enough: lists and banners drift between visits. */
+  const returnTo = async (origin: Screen): Promise<boolean> => {
+    for (let i = 0; i < 4; i++) {
+      let now = await device.screen();
+      if (dead(now)) {
+        options.log?.('navigator is dead; recovering');
+        await recover();
+        now = await device.screen();
+      }
+      if (now.route === origin.route && !now.presenting) return true;
+      if (now.route !== origin.route) {
+        const popped = await device.back().then(
+          () => true,
+          () => false,
+        );
+        if (!popped) await goTo(origin.route);
+      } else await closeOverlay(now);
+      await device.idle({ quietMs: 200, timeoutMs: 1500 });
+    }
+    const back = (await device.screen()).route === origin.route;
+    if (!back) options.log?.(`could not return to ${origin.route ?? '?'}`);
+    return back;
+  };
+
+  /** A sheet is named after the control that opens it, so getting back in is pressing that control again. */
+  const restore = async (origin: Screen, layer?: string): Promise<boolean> => {
+    if (!(await returnTo(origin))) return false;
+    if (!layer || (await device.screen()).presenting) return true;
+    if (!(await pressed(targetFor(layer), 800))) return false;
+    return (await settle()).presenting !== undefined;
+  };
+
+  return { dead, recover, settle, revive, restore };
+};

package/src/commands/crawl/state.ts

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+
+import type { Element, Screen, Target } from 'lynkeus-protocol';
+
+const layerOf = (s: Screen) => s.presenting?.testId ?? (s.presenting?.modal ? 'modal' : 'overlay');
+
+/**
+ * What makes a screen a different screen: its route, the layer over it and the
+ * set of controls it offers. A set because carousels and lists repeat testIDs
+ * and animate; hashed rather than truncated, because cutting a long list made
+ * two screens look identical and the crawl never went inside the second.
+ */
+export const stateKey = (s: Screen) => {
+  const ids = [
+    ...new Set(
+      presented(s)
+        .filter((e) => e.kind === 'button' && e.testId && !e.covered)
+        .map((e) => e.testId),
+    ),
+  ]
+    .sort()
+    .join(',');
+  return `${s.route ?? '?'}${s.presenting ? `+${layerOf(s)}` : ''}|${createHash('sha1').update(ids).digest('hex').slice(0, 12)}`;
+};
+
+/** Another tab, or the screen a sheet covers, is mounted but out of a finger's reach. */
+export const presented = (s: Screen): Element[] => s.elements.filter((e) => !e.hidden);
+
+/** A sheet has no route, so it is named after the control that opened it: that is also how to get back into it. */
+export const layerName = (s: Screen, openedBy?: string): string | undefined => (s.presenting ? (openedBy ?? layerOf(s)) : undefined);
+
+export const controlName = (e: Element): string => e.testId ?? `text:${e.text ?? ''}`;
+
+/** Where the agent stands; a sheet that mounted a beat after the press still belongs to itself, not to the screen under it. */
+export const nodeOf = (s: Screen, layer?: string): string => {
+  const here = layer ?? (s.presenting ? (s.presenting.testId ?? 'overlay') : undefined);
+  return `${s.route ?? '?'}${here ? `#${here}` : ''}`;
+};
+
+/** A control by the name the frontier and the edges record it under. */
+export const targetFor = (control: string): Target => (control.startsWith('text:') ? { text: control.slice(5) } : { testId: control });
+
+export const targetOf = (e: Element): Target => targetFor(controlName(e));
+
+// List rows carry their record id in the testID; one row per pattern is enough to learn where rows lead.
+export const pattern = (e: Element) => (e.testId ?? e.text ?? '').replace(/[0-9a-f]{8}-[0-9a-f-]{27}|\d+/gi, '*');
+
+const words = (e: Element) => `${e.testId ?? ''} ${e.text ?? ''}`;
+
+/**
+ * The controls worth pressing. A closer or a back control leads to where the
+ * crawl came from, not somewhere new; without an app's own list of back
+ * controls, a small one in the top-left corner is taken for one.
+ */
+export const candidates = (s: Screen, neverPress?: RegExp, backs?: RegExp, closers?: RegExp): Element[] => {
+  const seen = new Set<string>();
+  const corner = (e: Element) => e.frame.x < s.window.w / 4 && e.frame.y < s.window.h / 8 && e.frame.w < s.window.w / 4;
+  return presented(s).filter((e) => {
+    if (e.kind !== 'button' || !e.enabled || e.covered || !(e.testId || e.text)) return false;
+    if (neverPress?.test(words(e)) || closers?.test(words(e)) || (backs ? backs.test(words(e)) : corner(e))) return false;
+    const key = pattern(e);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
+
+export const label = (e: Element) => ({ testId: e.testId, text: e.text?.slice(0, 40) });
+
+export const isCloser = (e: Element, closers: RegExp) => e.kind === 'button' && e.enabled && !e.covered && closers.test(words(e));

package/src/commands/crawl.ts

@@ -0,0 +1,262 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { Element, Screen } from 'lynkeus-protocol';
+
+import type { Device } from '../device/driver.js';
+import type { Flow } from '../flow/types.js';
+import { pathOf, problemsOf } from '../knowledge/problems.js';
+import { createReturns, RecoveryError } from './crawl/return.js';
+import { candidates, controlName, label, layerName, nodeOf, pattern, presented, stateKey, targetOf } from './crawl/state.js';
+import { clearOverlayIfShown, type Overlay } from './overlay.js';
+
+export type LoginRecovery = {
+  /** Run in order after a reset, with `vars`; the last should land logged in. */
+  flows: Flow[];
+  vars: Record<string, unknown>;
+  /** Shell commands that print a variable, run right before a flow that declares it: a one-time code, a minted session. */
+  varCommands?: Record<string, string>;
+};
+
+// The one signal about a press's consequences that holds in any app, with no vocabulary.
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+export type Transition = {
+  from: string;
+  fromRoute?: string;
+  fromLayer?: string;
+  toLayer?: string;
+  button: { testId?: string; text?: string };
+  to: string;
+  toRoute?: string;
+  ms: number;
+  problems: string[];
+  /** The writes the press caused, when it caused any. */
+  wrote?: string[];
+};
+
+export type CrawlOptions = {
+  device: Device;
+  outDir: string;
+  depth: number;
+  maxActions: number;
+  neverPress?: RegExp;
+  errorCopy?: RegExp;
+  /** Without one, an overlay is closed by tapping its backdrop, then by a swipe down. */
+  closers?: RegExp;
+  backs?: RegExp;
+  /** `read-only` (default): a press that makes the app write is reported, never repeated, and not explored past. */
+  safety?: 'read-only' | 'anything';
+  appId?: string;
+  overlay?: Overlay;
+  /** How to log in again after a headless host is reset (a crashed screen kills its navigator). */
+  login?: LoginRecovery;
+  /** Press what the directions say leads here first, and stop on arrival. */
+  goal?: string;
+  /** What earlier crawls pressed, and what this one learns. */
+  memory?: {
+    tried: (node: string) => string[];
+    record: (node: string, update: { tried?: string[]; seen?: string[]; visited?: boolean }) => void;
+    /** Places with controls nobody has pressed, most owed first. */
+    unfinished: () => string[];
+  };
+  directions?: (from: string, to: string) => { press?: string; to: string }[] | null;
+  onTransition?: (t: Transition) => void;
+  log?: (line: string) => void;
+};
+
+export const crawl = async (options: CrawlOptions): Promise<{ transitions: Transition[]; states: Record<string, Screen> }> => {
+  const { device, memory } = options;
+  const readOnly = (options.safety ?? 'read-only') === 'read-only';
+  fs.mkdirSync(options.outDir, { recursive: true });
+  const transitions: Transition[] = [];
+  const states: Record<string, Screen> = {};
+  const explored = new Set<string>();
+  const wrote = new Set<string>();
+  const walked = new Set<string>();
+  let actions = 0;
+  let reached = false;
+  let start: string | undefined;
+  const goTo = async (route: string | undefined): Promise<void> => {
+    const target = route ?? start;
+    if (target) await device.navigate(target);
+    else await device.back();
+  };
+  const { dead, recover, settle, revive, restore } = createReturns({ device, options, goTo });
+
+  const report = (transition: Transition, t0: number) => {
+    transition.ms = Math.round(performance.now() - t0);
+    transitions.push(transition);
+    options.onTransition?.(transition);
+  };
+
+  /** With a goal, whatever the directions say leads towards it goes first. */
+  const ordered = (buttons: Element[], next: string | undefined): Element[] => {
+    const toward = next ? buttons.filter((b) => b.testId === next) : [];
+    if (toward.length === 0) return buttons;
+    options.log?.(`towards ${options.goal}: press ${next} first`);
+    return [...toward, ...buttons.filter((b) => !toward.includes(b))];
+  };
+
+  const explore = async (origin: Screen, depth: number, layer?: string): Promise<void> => {
+    const key = stateKey(origin);
+    if (explored.has(key) || depth > options.depth || reached) return;
+    explored.add(key);
+    states[key] = origin;
+    const node = nodeOf(origin, layer);
+    const all = candidates(origin, options.neverPress, options.backs, options.closers);
+    // Only a testID is promised to a later run: a control known by its text may render differently next time.
+    memory?.record(node, { seen: all.filter((b) => b.testId).map(controlName), visited: true });
+    const done = new Set(memory?.tried(node) ?? []);
+    const next = options.goal && options.directions ? options.directions(node, options.goal)?.[0]?.press : undefined;
+    const buttons = ordered(
+      all.filter((b) => !done.has(controlName(b))),
+      next,
+    );
+    const found = new Map<string, { button: Element; layer?: string }>();
+    options.log?.(
+      `explore ${origin.route ?? '?'}${layer ? ` +${layer}` : ''} depth ${depth}: ${buttons.length} buttons ` +
+        `(${origin.elements.filter((e) => e.hidden).length} hidden, ${presented(origin).filter((e) => e.covered).length} covered)`,
+    );
+    for (const button of buttons) {
+      if (actions >= options.maxActions || reached) return;
+      if (readOnly && wrote.has(pattern(button))) continue;
+      const t0 = performance.now();
+      const transition: Transition = { from: key, fromRoute: origin.route, fromLayer: layer, button: label(button), to: '', ms: 0, problems: [] };
+      try {
+        if (!device.server.connected) {
+          await recover();
+          if (!(await restore(origin, layer))) return;
+        }
+        const before = await device.requests();
+        const present = await device.waitFor({ target: targetOf(button), timeoutMs: 800 }).then(
+          () => true,
+          () => false,
+        );
+        if (!present) {
+          options.log?.(`skip ${controlName(button)}: no longer on screen`);
+          continue;
+        }
+        actions++;
+        await device.press(targetOf(button));
+        const after = await settle();
+        transition.to = stateKey(after);
+        transition.toRoute = after.route;
+        // A press made inside a layer that is still up stays in it; one that raised a layer names it.
+        transition.toLayer = layerName(after, origin.presenting ? layer : controlName(button));
+        const { requests } = await device.requests(before.requests.at(-1)?.id);
+        transition.problems.push(...problemsOf(after, requests, options.errorCopy));
+        const writes = requests.filter((r) => WRITE_METHODS.has(r.method.toUpperCase()));
+        if (writes.length) {
+          transition.wrote = [...new Set(writes.map((r) => `${r.method} ${pathOf(r.url)}`))];
+          wrote.add(pattern(button));
+        }
+        report(transition, t0);
+        memory?.record(node, { tried: [controlName(button)] });
+        if (options.goal && after.route === options.goal) {
+          options.log?.(`reached ${options.goal}`);
+          reached = true;
+          return;
+        }
+        if (transition.to === key) continue;
+        if (transition.wrote && readOnly) {
+          options.log?.(`stop here: pressing ${controlName(button)} wrote (${transition.wrote.join(', ')})`);
+        } else if (next !== undefined && button.testId === next) {
+          // Getting somewhere in particular: follow the directions now instead of sweeping this screen first.
+          await explore(after, depth + 1, transition.toLayer);
+        } else if (!explored.has(transition.to) && !found.has(transition.to)) {
+          found.set(transition.to, { button, layer: transition.toLayer });
+        }
+        if (after.route) memory?.record(nodeOf(after, transition.toLayer), {});
+        if (!device.server.connected) await recover();
+        if (!(await restore(origin, layer))) {
+          await goTo(origin.route);
+          await device.idle({ quietMs: 200, timeoutMs: 1500 });
+        }
+      } catch (error) {
+        if (error instanceof RecoveryError) throw error;
+        transition.problems.push(error instanceof Error ? error.message : String(error));
+        report(transition, t0);
+        if (!device.server.connected) await recover().catch(() => undefined);
+        if (!(await restore(origin, layer).catch(() => false))) await goTo(origin.route).catch(() => undefined);
+      }
+    }
+
+    // The whole screen is swept before going into what it opened: depth-first from the first control would
+    // spend the budget inside it. Layers go first: one only exists while this screen holds it open, while a
+    // route stays reachable by name.
+    const queue = [...found].sort(([, a], [, b]) => Number(b.layer !== undefined) - Number(a.layer !== undefined));
+    for (const [to, { button, layer: into }] of queue) {
+      if (reached) return;
+      if (actions >= options.maxActions || explored.has(to)) continue;
+      if (!(await restore(origin, layer).catch(() => false))) return;
+      const target = targetOf(button);
+      const back = await device
+        .waitFor({ target, timeoutMs: 800 })
+        .then(() => device.press(target))
+        .then(() => settle())
+        .catch(() => undefined);
+      if (!back) continue;
+      // What is there now, not what was: a banner may have rotated since the sweep.
+      await explore(back, depth + 1, into);
+      if (!device.server.connected) await recover().catch(() => undefined);
+    }
+  };
+
+  /** A route can be jumped to; a layer is opened again from the route under it, the way the edge that found it says. */
+  const walkTo = async (node: string): Promise<Screen | undefined> => {
+    const [route, layer] = node.split('#');
+    if (!route) return undefined;
+    const jump = async () => {
+      await device.navigate(route).catch(() => undefined);
+      await device.idle({ quietMs: 200, timeoutMs: 2000 });
+      return settle();
+    };
+    await revive();
+    let now = await jump();
+    if (now.route !== route) {
+      // A dead navigator answers every jump with the same nothing; one reset is the difference between resuming and not.
+      if (!dead(now)) return undefined;
+      await revive();
+      now = await jump();
+      if (now.route !== route) return undefined;
+    }
+    if (!layer) return now;
+    for (const step of options.directions?.(route, node) ?? []) {
+      if (!step.press) return undefined;
+      const press = step.press;
+      const ok = await device
+        .waitFor({ target: { testId: press }, timeoutMs: 1000 })
+        .then(() => device.press({ testId: press }))
+        .then(
+          () => true,
+          () => false,
+        );
+      if (!ok) return undefined;
+      now = await settle();
+    }
+    return now.presenting ? now : undefined;
+  };
+
+  await clearOverlayIfShown(device, options.overlay);
+  const first = await revive();
+  start = first.route;
+  await explore(first, 0);
+
+  // The budget is per run and the app is bigger than one: what is left goes back in the frontier, and what
+  // is still reachable gets walked to while there is budget.
+  while (!reached && actions < options.maxActions) {
+    const next = memory?.unfinished().find((node) => !walked.has(node));
+    if (!next) break;
+    walked.add(next);
+    options.log?.(`resuming at ${next}`);
+    const there = await walkTo(next);
+    if (!there) {
+      options.log?.(`could not get back to ${next}`);
+      continue;
+    }
+    await explore(there, 0, next.split('#')[1]);
+  }
+  fs.writeFileSync(path.join(options.outDir, 'transitions.json'), JSON.stringify({ transitions, states }, null, 2));
+  return { transitions, states };
+};

package/src/commands/device.ts

@@ -0,0 +1,119 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import type { Platform } from '../device/devices.js';
+
+const run = promisify(execFile);
+
+/** `optional`: a failure is the desired end state too (terminating an app that is not running). */
+type Invocation = { bin: string; args: string[]; optional?: boolean };
+
+const IOS_SERVICES = new Set([
+  'all',
+  'calendar',
+  'contacts-limited',
+  'contacts',
+  'location',
+  'location-always',
+  'photos-add',
+  'photos',
+  'media-library',
+  'microphone',
+  'motion',
+  'reminders',
+  'siri',
+  'camera',
+]);
+
+export const simulatorArgv = (platform: Platform, deviceId: string, sub: string, args: string[], appId?: string): Invocation[] => {
+  const needApp = (): string => {
+    if (!appId) throw new Error(`lynkeus os ${sub} needs --app <bundleId>`);
+    return appId;
+  };
+  if (platform === 'ios') {
+    switch (sub) {
+      case 'permissions': {
+        const [action, service] = args;
+        if (!action || !['grant', 'revoke', 'reset'].includes(action)) throw new Error('lynkeus os permissions grant|revoke|reset <service> --app <bundleId>');
+        if (!service || !IOS_SERVICES.has(service)) throw new Error(`service must be one of ${[...IOS_SERVICES].join(', ')}`);
+        return [{ bin: 'xcrun', args: ['simctl', 'privacy', deviceId, action, service, needApp()] }];
+      }
+      case 'push': {
+        const [payload] = args;
+        if (!payload) throw new Error("lynkeus os push '<json>' | <file.json> --app <bundleId>");
+        let file = payload;
+        if (!fs.existsSync(payload)) {
+          file = path.join(os.tmpdir(), `lynkeus-push-${Date.now()}.json`);
+          // simctl wants an APNS payload: wrap a bare notification under "aps".
+          const parsed = JSON.parse(payload) as Record<string, unknown>;
+          fs.writeFileSync(file, JSON.stringify('aps' in parsed ? parsed : { aps: parsed }));
+        }
+        return [{ bin: 'xcrun', args: ['simctl', 'push', deviceId, needApp(), file] }];
+      }
+      case 'appearance': {
+        const [mode] = args;
+        if (mode !== 'light' && mode !== 'dark') throw new Error('lynkeus os appearance light|dark');
+        return [{ bin: 'xcrun', args: ['simctl', 'ui', deviceId, 'appearance', mode] }];
+      }
+      case 'location': {
+        const [where] = args;
+        if (where === 'clear') return [{ bin: 'xcrun', args: ['simctl', 'location', deviceId, 'clear'] }];
+        if (!where || !/^-?\d+(\.\d+)?,-?\d+(\.\d+)?$/.test(where)) throw new Error('lynkeus os location <lat>,<lon> | clear');
+        return [{ bin: 'xcrun', args: ['simctl', 'location', deviceId, 'set', where] }];
+      }
+      case 'language': {
+        // No system-wide switch on a booted simulator: relaunch the app with the
+        // launch arguments iOS reads for its locale.
+        const [tag] = args;
+        if (!tag) throw new Error('lynkeus os language <bcp47, e.g. de-DE> --app <bundleId>');
+        const app = needApp();
+        const locale = tag.replace('-', '_');
+        return [
+          { bin: 'xcrun', args: ['simctl', 'terminate', deviceId, app], optional: true },
+          { bin: 'xcrun', args: ['simctl', 'launch', deviceId, app, '-AppleLanguages', `(${tag})`, '-AppleLocale', locale] },
+        ];
+      }
+      default:
+        throw new Error(`unknown os subcommand "${sub}"; one of permissions, push, appearance, location, language`);
+    }
+  }
+  const adb = (a: string[]): Invocation => ({ bin: 'adb', args: ['-s', deviceId, ...a] });
+  switch (sub) {
+    case 'permissions': {
+      const [action, service] = args;
+      if (!action || !['grant', 'revoke'].includes(action) || !service)
+        throw new Error('lynkeus os permissions grant|revoke <android.permission.X> --app <applicationId>');
+      return [adb(['shell', 'pm', action, needApp(), service.includes('.') ? service : `android.permission.${service.toUpperCase()}`])];
+    }
+    case 'appearance': {
+      const [mode] = args;
+      if (mode !== 'light' && mode !== 'dark') throw new Error('lynkeus os appearance light|dark');
+      return [adb(['shell', 'cmd', 'uimode', 'night', mode === 'dark' ? 'yes' : 'no'])];
+    }
+    case 'location': {
+      const [where] = args;
+      if (!where || !/^-?\d+(\.\d+)?,-?\d+(\.\d+)?$/.test(where)) throw new Error('lynkeus os location <lat>,<lon>');
+      const [lat, lon] = where.split(',');
+      return [adb(['emu', 'geo', 'fix', lon!, lat!])];
+    }
+    default:
+      throw new Error(`"${sub}" is not available on Android through lynkeus; permissions, appearance and location are`);
+  }
+};
+
+export const simulatorCommand = async (platform: Platform, deviceId: string, sub: string, args: string[], appId?: string): Promise<string[]> => {
+  const out: string[] = [];
+  for (const c of simulatorArgv(platform, deviceId, sub, args, appId)) {
+    try {
+      const { stdout } = await run(c.bin, c.args);
+      out.push(`${c.bin} ${c.args.join(' ')}${stdout.trim() ? `\n${stdout.trim()}` : ''}`);
+    } catch (error) {
+      if (c.optional) continue;
+      throw new Error(`${c.bin} ${c.args.join(' ')} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return out;
+};