Add open --relaunch and persist replay semantics

Author: thymikee

src/core/dispatch.ts

@@ -34,6 +34,7 @@ export type CommandFlags = {
   snapshotRaw?: boolean;
   snapshotBackend?: 'ax' | 'xctest';
   saveScript?: boolean;
+  relaunch?: boolean;
   noRecord?: boolean;
   appsFilter?: 'launchable' | 'user-installed' | 'all';
   appsMetadata?: boolean;

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

@@ -93,3 +93,27 @@ test('saveScript flag enables .ad session log writing', () => {
   const files = fs.readdirSync(root);
   assert.equal(files.filter((file) => file.endsWith('.ad')).length, 1);
 });
+
+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/);
+});

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

@@ -120,3 +120,105 @@ test('boot succeeds for supported device in session', async () => {
     assert.equal(response.data?.booted, true);
   }
 });
+
+test('open --relaunch closes and reopens active session app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel Emulator',
+        kind: 'emulator',
+        booted: true,
+      }),
+      appName: 'com.example.app',
+    },
+  );
+
+  const calls: Array<{ command: string; positionals: string[] }> = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, command, positionals) => {
+      calls.push({ command, positionals });
+      return {};
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.equal(calls.length, 2);
+  assert.deepEqual(calls[0], { command: 'close', positionals: ['com.example.app'] });
+  assert.deepEqual(calls[1], { command: 'open', positionals: ['com.example.app'] });
+});
+
+test('open --relaunch fails without app when no session exists', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /requires an app argument/i);
+  }
+});
+
+test('replay parses open --relaunch flag and replays open with relaunch semantics', async () => {
+  const sessionStore = makeSessionStore();
+  const replayRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-relaunch-'));
+  const replayPath = path.join(replayRoot, 'relaunch.ad');
+  fs.writeFileSync(replayPath, 'open "Settings" --relaunch\n');
+
+  const invoked: DaemonRequest[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'replay',
+      positionals: [replayPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: async (req) => {
+      invoked.push(req);
+      return { ok: true, data: {} };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.replayed, 1);
+  }
+  assert.equal(invoked.length, 1);
+  assert.equal(invoked[0]?.command, 'open');
+  assert.deepEqual(invoked[0]?.positionals, ['Settings']);
+  assert.equal(invoked[0]?.flags?.relaunch, true);
+});

src/daemon/handlers/session.ts

@@ -286,10 +286,21 @@ export async function handleSessionCommands(params: {
   }
 
   if (command === 'open') {
+    const shouldRelaunch = req.flags?.relaunch === true;
     if (sessionStore.has(sessionName)) {
       const session = sessionStore.get(sessionName);
-      const appName = req.positionals?.[0];
+      const requestedAppName = req.positionals?.[0];
+      const appName = requestedAppName ?? (shouldRelaunch ? session?.appName : undefined);
       if (!session || !appName) {
+        if (shouldRelaunch) {
+          return {
+            ok: false,
+            error: {
+              code: 'INVALID_ARGS',
+              message: 'open --relaunch requires an app name or an active session app.',
+            },
+          };
+        }
         return {
           ok: false,
           error: {
@@ -307,7 +318,13 @@ export async function handleSessionCommands(params: {
           appBundleId = undefined;
         }
       }
-      await dispatch(session.device, 'open', req.positionals ?? [], req.flags?.out, {
+      const openPositionals = requestedAppName ? (req.positionals ?? []) : [appName];
+      if (shouldRelaunch) {
+        await dispatch(session.device, 'close', [appName], req.flags?.out, {
+          ...contextFromFlags(logPath, req.flags, appBundleId ?? session.appBundleId, session.trace?.outPath),
+        });
+      }
+      await dispatch(session.device, 'open', openPositionals, req.flags?.out, {
         ...contextFromFlags(logPath, req.flags, appBundleId),
       });
       const nextSession: SessionState = {
@@ -319,13 +336,23 @@ export async function handleSessionCommands(params: {
       };
       sessionStore.recordAction(nextSession, {
         command,
-        positionals: req.positionals ?? [],
+        positionals: openPositionals,
         flags: req.flags ?? {},
         result: { session: sessionName, appName, appBundleId },
       });
       sessionStore.set(sessionName, nextSession);
       return { ok: true, data: { session: sessionName, appName, appBundleId } };
     }
+    const appName = req.positionals?.[0];
+    if (shouldRelaunch && !appName) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'open --relaunch requires an app argument.',
+        },
+      };
+    }
     const device = await resolveTargetDevice(req.flags ?? {});
     const inUse = sessionStore.toArray().find((s) => s.device.id === device.id);
     if (inUse) {
@@ -339,15 +366,21 @@ export async function handleSessionCommands(params: {
       };
     }
     let appBundleId: string | undefined;
-    const appName = req.positionals?.[0];
     if (device.platform === 'ios') {
       try {
-        const { resolveIosApp } = await import('../../platforms/ios/index.ts');
-        appBundleId = await resolveIosApp(device, req.positionals?.[0] ?? '');
+        if (appName) {
+          const { resolveIosApp } = await import('../../platforms/ios/index.ts');
+          appBundleId = await resolveIosApp(device, appName);
+        }
       } catch {
         appBundleId = undefined;
       }
     }
+    if (shouldRelaunch && appName) {
+      await dispatch(device, 'close', [appName], req.flags?.out, {
+        ...contextFromFlags(logPath, req.flags, appBundleId),
+      });
+    }
     await dispatch(device, 'open', req.positionals ?? [], req.flags?.out, {
       ...contextFromFlags(logPath, req.flags, appBundleId),
     });
@@ -822,6 +855,19 @@ function parseReplayScriptLine(line: string): SessionAction | null {
     return action;
   }
 
+  if (command === 'open') {
+    action.positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+      const token = args[index];
+      if (token === '--relaunch') {
+        action.flags.relaunch = true;
+        continue;
+      }
+      action.positionals.push(token);
+    }
+    return action;
+  }
+
   if (command === 'click') {
     if (args.length === 0) return action;
     const target = args[0];
@@ -948,6 +994,15 @@ function formatReplayActionLine(action: SessionAction): string {
     }
     return parts.join(' ');
   }
+  if (action.command === 'open') {
+    for (const positional of action.positionals ?? []) {
+      parts.push(formatReplayArg(positional));
+    }
+    if (action.flags?.relaunch) {
+      parts.push('--relaunch');
+    }
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatReplayArg(positional));
   }

src/daemon/session-store.ts

@@ -166,6 +166,7 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     snapshotRaw,
     snapshotBackend,
     appsMetadata,
+    relaunch,
     saveScript,
     noRecord,
   } = flags;
@@ -183,6 +184,7 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     snapshotRaw,
     snapshotBackend,
     appsMetadata,
+    relaunch,
     saveScript,
     noRecord,
   };
@@ -261,6 +263,15 @@ function formatActionLine(action: SessionAction): string {
     }
     return parts.join(' ');
   }
+  if (action.command === 'open') {
+    for (const positional of action.positionals ?? []) {
+      parts.push(formatArg(positional));
+    }
+    if (action.flags?.relaunch) {
+      parts.push('--relaunch');
+    }
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatArg(positional));
   }

src/utils/__tests__/args.test.ts

@@ -0,0 +1,14 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseArgs, usage } from '../args.ts';
+
+test('parseArgs recognizes --relaunch', () => {
+  const parsed = parseArgs(['open', 'settings', '--relaunch']);
+  assert.equal(parsed.command, 'open');
+  assert.deepEqual(parsed.positionals, ['settings']);
+  assert.equal(parsed.flags.relaunch, true);
+});
+
+test('usage includes --relaunch flag', () => {
+  assert.match(usage(), /--relaunch/);
+});

src/utils/args.ts

@@ -22,6 +22,7 @@ export type ParsedArgs = {
     appsMetadata?: boolean;
     activity?: string;
     saveScript?: boolean;
+    relaunch?: boolean;
     noRecord?: boolean;
     replayUpdate?: boolean;
     help: boolean;
@@ -71,6 +72,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
       flags.saveScript = true;
       continue;
     }
+    if (arg === '--relaunch') {
+      flags.relaunch = true;
+      continue;
+    }
     if (arg === '--update' || arg === '-u') {
       flags.replayUpdate = true;
       continue;
@@ -232,6 +237,7 @@ Flags:
   --verbose                                  Stream daemon/runner logs
   --json                                     JSON output
   --save-script                             Save session script (.ad) on close
+  --relaunch                               open: terminate app process before launching it
   --no-record                                Do not record this action
   --update, -u                               Replay: update selectors and rewrite replay file in place
   --user-installed                           Apps: list user-installed packages (Android only)