feat: add install command for in-place app deployment

Author: thymikee

README.md

@@ -14,7 +14,7 @@ The project is in early development and considered experimental. Pull requests a
 
 ## Features
 - Platforms: iOS/tvOS (simulator + physical device core automation) and Android/AndroidTV (emulator + device).
-- Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `reinstall`, `push`, `trigger-app-event`.
+- Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `install`, `reinstall`, `push`, `trigger-app-event`.
 - Inspection commands: `snapshot` (accessibility tree), `diff snapshot` (structural baseline diff), `appstate`, `apps`, `devices`.
 - Clipboard commands: `clipboard read`, `clipboard write <text>`.
 - Keyboard commands: `keyboard status|get|dismiss` (Android).
@@ -143,7 +143,7 @@ agent-device scrollintoview @e42
 ```
 
 ## Command Index
-- `boot`, `open`, `close`, `reinstall`, `home`, `back`, `app-switcher`
+- `boot`, `open`, `close`, `install`, `reinstall`, `home`, `back`, `app-switcher`
 - `push`
 - `batch`
 - `snapshot`, `diff snapshot`, `find`, `get`
@@ -308,8 +308,9 @@ Navigation helpers:
 - `boot --platform ios|android|apple` ensures the target is ready without launching an app.
 - Use `boot` mainly when starting a new session and `open` fails because no booted simulator/emulator is available.
 - `open [app|url] [url]` already boots/activates the selected target when needed.
+- `install <app> <path>` installs app binary without uninstalling first (Android + iOS simulator/device).
 - `reinstall <app> <path>` uninstalls and installs the app binary in one command (Android + iOS simulator/device).
-- `reinstall` accepts package/bundle id style app names and supports `~` in paths.
+- `install`/`reinstall` accept package/bundle id style app names and support `~` in paths.
 
 Deep links:
 - `open <url>` supports deep links with `scheme://...`.

src/core/__tests__/capabilities.test.ts

@@ -74,6 +74,12 @@ test('reinstall supports iOS simulator, iOS device, and Android', () => {
   assert.equal(isCommandSupportedOnDevice('reinstall', androidDevice), true, 'reinstall on Android');
 });
 
+test('install supports iOS simulator, iOS device, and Android', () => {
+  assert.equal(isCommandSupportedOnDevice('install', iosSimulator), true, 'install on iOS sim');
+  assert.equal(isCommandSupportedOnDevice('install', iosDevice), true, 'install on iOS device');
+  assert.equal(isCommandSupportedOnDevice('install', androidDevice), true, 'install on Android');
+});
+
 test('core commands support iOS simulator, iOS device, and Android', () => {
   for (const cmd of [
     'app-switcher',
@@ -88,6 +94,7 @@ test('core commands support iOS simulator, iOS device, and Android', () => {
     'focus',
     'get',
     'home',
+    'install',
     'longpress',
     'logs',
     'open',

src/core/capabilities.ts

@@ -36,6 +36,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   longpress: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   open: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   perf: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  install: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   reinstall: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   press: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   push: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },

src/daemon/handlers/__tests__/session-reinstall.test.ts

@@ -8,7 +8,7 @@ import { SessionStore } from '../../session-store.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from '../../types.ts';
 
 function makeStore(): SessionStore {
-  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-reinstall-'));
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-app-deploy-'));
   return new SessionStore(path.join(tempRoot, 'sessions'));
 }
 
@@ -22,7 +22,7 @@ function makeSession(name: string, device: SessionState['device']): SessionState
 }
 
 const invoke = async (_req: DaemonRequest): Promise<DaemonResponse> => {
-  return { ok: false, error: { code: 'INVALID_ARGS', message: 'invoke should not be called in reinstall tests' } };
+  return { ok: false, error: { code: 'INVALID_ARGS', message: 'invoke should not be called in app deploy tests' } };
 };
 
 test('reinstall requires active session or explicit device selector', async () => {
@@ -229,3 +229,122 @@ test('reinstall succeeds on active Android session with normalized appId', async
     assert.equal(response.data?.appPath, appPath);
   }
 });
+
+test('install requires active session or explicit device selector', async () => {
+  const sessionStore = makeStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'install',
+      positionals: ['com.example.app', '/tmp/app.apk'],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+  });
+  assert.ok(response);
+  assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /active session or an explicit device selector/i);
+  }
+});
+
+test('install succeeds on active iOS simulator session and records action', async () => {
+  const sessionStore = makeStore();
+  const session = makeSession('default', {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone',
+    kind: 'simulator',
+    booted: true,
+  });
+  sessionStore.set('default', session);
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-install-success-ios-'));
+  const appPath = path.join(tempRoot, 'Sample.app');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'install',
+      positionals: ['com.example.app', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+    installOps: {
+      ios: async (_device, app, pathToBinary) => {
+        assert.equal(app, 'com.example.app');
+        assert.equal(pathToBinary, appPath);
+        return { bundleId: 'com.example.app' };
+      },
+      android: async () => {
+        throw new Error('unexpected android install');
+      },
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response.ok, true);
+  if (response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.appId, 'com.example.app');
+    assert.equal(response.data?.bundleId, 'com.example.app');
+    assert.equal(response.data?.appPath, appPath);
+  }
+  assert.equal(session.actions.length, 1);
+  assert.equal(session.actions[0]?.command, 'install');
+});
+
+test('install omits app id fields when platform op cannot resolve them', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set(
+    'default',
+    makeSession('default', {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel',
+      kind: 'emulator',
+      booted: true,
+    }),
+  );
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-install-fallback-appid-'));
+  const appPath = path.join(tempRoot, 'Sample.apk');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'install',
+      positionals: ['Demo', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+    installOps: {
+      ios: async () => {
+        throw new Error('unexpected ios install');
+      },
+      android: async () => ({}),
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response.ok, true);
+  if (response.ok) {
+    assert.equal(response.data?.platform, 'android');
+    assert.equal(response.data?.appId, undefined);
+    assert.equal(response.data?.package, undefined);
+    assert.equal(response.data?.appPath, appPath);
+  }
+});