feat: parametrise .ad replay scripts (#433)

* feat: parametrise .ad replay scripts

Support ${VAR} substitution with env header directives and CLI -e
overrides so flows can be reused across app variants, environments,
and devices without duplicating the script.

Precedence (high->low): CLI -e > AD_* shell env > file-local env >
built-ins (AD_PLATFORM, AD_SESSION, AD_FILENAME, AD_DEVICE,
AD_ARTIFACTS). Supports ${VAR:-default} fallback, \${ escape, and
fails with file:line on unresolved vars.

* refactor: harden .ad replay parametrisation

Tighten the parametrisation surface introduced in the feat commit after
an internal review pass:

- Reserve the AD_* namespace for built-ins. User env (file env, CLI -e,
  shell AD_VAR_*) can no longer define AD_* keys, which closes a built-in
  shadowing vector (e.g. AD_VAR_AD_SESSION).
- Change the shell-env prefix from AD_* to AD_VAR_* so unrelated CI
  secrets that happen to start with AD_ (AD_TOKEN, AD_SECRET_KEY) are
  not auto-imported into replay scripts.
- Extend the replay -u guard to also reject scripts with \${VAR}
  substitutions in any action, not just those with env directives, so
  the writer never silently drops substitutions on heal-rewrite.
- Reword DX-unfriendly regex errors ("must match /^[A-Z_]...$/" ->
  "must be uppercase letters, digits, and underscores, e.g. APP_ID").
- Docs rewrite with precedence table, three recipes, fallback/escape
  examples, and a Notes block covering replay -u limitation, remote
  daemon caveat, no nested fallback, and loud typo behaviour.
- Additional unit tests: namespace reservation on every path, shell
  prefix migration, \${VAR} round-trip preservation through
  writeReplayScript, green-path integration test with a fake invoke.

* fix: collect .ad replay shell env on the CLI, not the daemon

Review feedback (#433 (comment)):
the daemon was reading AD_VAR_* from its own process.env, which meant
"AD_VAR_K=V agent-device replay" only worked if V was set when the
daemon started, and never worked for remote daemons.

The client now filters process.env for AD_VAR_* at request time and
ships the result as replayShellEnv on the DaemonRequest flags. The
daemon prefers the request value when present and falls back to its
own process.env for direct-daemon callers (internal tests).

Adds two integration tests pinning both paths and updates the docs
Notes block to reflect the new behaviour.

* fix: thread per-attempt artifacts dir into AD_ARTIFACTS under test

Review feedback (#433 (comment)):
AD_ARTIFACTS is documented as available under "agent-device test", but
buildReplayBuiltinVars was only reading the raw flags.artifactsDir.
Under the default artifacts layout the flag is unset and \${AD_ARTIFACTS}
failed; when set with --artifacts-dir it pointed at the suite root, not
the resolved per-attempt directory the test runner actually writes to.

Plumb the attempt-level artifacts dir from session-test.ts through the
runReplay callback (via runReplayTestAttempt) down into the nested
replay request's flags.artifactsDir. The daemon side is unchanged -
buildReplayBuiltinVars just now sees the right value.

Extracts the nested-request flag merge into a testable helper
(buildNestedReplayFlags) to close the coverage gap between the test
harness and the replay runtime.

* refactor: DRY .ad replay parametrisation internals

- Share VAR_KEY_RE between session-replay-vars and session-replay-script
  instead of re-declaring the same /^[A-Z_][A-Z0-9_]*$/ in each.
- Fold resolveReplayFlags + resolveReplayRuntime into a single generic
  resolveStringProps<T>; the two were near-identical object-walkers.
- Un-export parseReplayEnvLine (was only used inside its own module).
- Table-drive the four "reject AD_* namespace" tests with test.each
  instead of four near-duplicate test blocks.
- Extract runReplayFixture helper for runReplayScriptFile integration
  tests; each test is now ~10 lines instead of ~30.

No behaviour change. 812 tests still green.

* docs: clarify replay built-in variables

* test: cover replay env serialization

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

Author: kacper-mikolajczak

src/__tests__/client.test.ts

@@ -371,6 +371,42 @@ test('client throws AppError for daemon failures', async () => {
   );
 });
 
+test('replay.run serializes client-collected AD_VAR shell env into daemon request', async () => {
+  const previousAppId = process.env.AD_VAR_APP_ID;
+  const previousWaitMs = process.env.AD_VAR_WAIT_MS;
+  const previousLegacy = process.env.AD_APP_ID;
+  process.env.AD_VAR_APP_ID = 'com.example.debug';
+  process.env.AD_VAR_WAIT_MS = '750';
+  process.env.AD_APP_ID = 'legacy-prefix-ignored';
+  try {
+    const setup = createTransport(async () => ({ ok: true, data: {} }));
+    const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+    await client.replay.run({
+      path: './flows/login.ad',
+      env: ['APP_ID=cli-override'],
+    });
+
+    assert.equal(setup.calls.length, 1);
+    assert.equal(setup.calls[0]?.command, 'replay');
+    assert.deepEqual(setup.calls[0]?.positionals, ['./flows/login.ad']);
+    assert.deepEqual(setup.calls[0]?.flags?.replayEnv, ['APP_ID=cli-override']);
+    const replayShellEnv = setup.calls[0]?.flags?.replayShellEnv as
+      | Record<string, string>
+      | undefined;
+    assert.equal(replayShellEnv?.AD_VAR_APP_ID, 'com.example.debug');
+    assert.equal(replayShellEnv?.AD_VAR_WAIT_MS, '750');
+    assert.equal(Object.prototype.hasOwnProperty.call(replayShellEnv ?? {}, 'AD_APP_ID'), false);
+  } finally {
+    if (previousAppId === undefined) delete process.env.AD_VAR_APP_ID;
+    else process.env.AD_VAR_APP_ID = previousAppId;
+    if (previousWaitMs === undefined) delete process.env.AD_VAR_WAIT_MS;
+    else process.env.AD_VAR_WAIT_MS = previousWaitMs;
+    if (previousLegacy === undefined) delete process.env.AD_APP_ID;
+    else process.env.AD_APP_ID = previousLegacy;
+  }
+});
+
 test('client.command.wait prepares selector options and rejects invalid selectors', async () => {
   const setup = createTransport(async () => ({
     ok: true,

src/cli/commands/generic.ts

@@ -73,6 +73,7 @@ export const genericClientCommandHandlers = {
         ...buildSelectionOptions(flags),
         path: required(positionals[0], 'replay requires path'),
         update: flags.replayUpdate,
+        env: flags.replayEnv,
       }),
   ),
   [CLIENT_COMMANDS.test]: createGenericClientCommandHandler(
@@ -83,6 +84,7 @@ export const genericClientCommandHandlers = {
         ...buildSelectionOptions(flags),
         paths: positionals,
         update: flags.replayUpdate,
+        env: flags.replayEnv,
         failFast: flags.failFast,
         timeoutMs: flags.timeoutMs,
         retries: flags.retries,

src/cli/commands/router.ts

@@ -13,10 +13,7 @@ import { snapshotCommand } from './snapshot.ts';
 import { screenshotCommand, diffCommand } from './screenshot.ts';
 import { clientCommandMethodHandlers } from './client-command.ts';
 import { genericClientCommandHandlers } from './generic.ts';
-import type {
-  ClientCommandHandler,
-  ClientCommandHandlerMap,
-} from './router-types.ts';
+import type { ClientCommandHandler, ClientCommandHandlerMap } from './router-types.ts';
 
 export type {
   ClientCommandHandler,

src/client-normalizers.ts

@@ -289,6 +289,8 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     headless: options.headless,
     restart: options.restart,
     replayUpdate: options.replayUpdate,
+    replayEnv: options.replayEnv,
+    replayShellEnv: options.replayShellEnv,
     failFast: options.failFast,
     timeoutMs: options.timeoutMs,
     retries: options.retries,

src/client-types.ts

@@ -611,12 +611,14 @@ export type FindOptions =
 export type ReplayRunOptions = AgentDeviceRequestOverrides & {
   path: string;
   update?: boolean;
+  env?: string[];
 };
 
 export type ReplayTestOptions = AgentDeviceRequestOverrides &
   AgentDeviceSelectionOptions & {
     paths: string[];
     update?: boolean;
+    env?: string[];
     failFast?: boolean;
     timeoutMs?: number;
     retries?: number;
@@ -738,6 +740,8 @@ type CommandExecutionOptions = {
   headless?: boolean;
   restart?: boolean;
   replayUpdate?: boolean;
+  replayEnv?: string[];
+  replayShellEnv?: Record<string, string>;
   failFast?: boolean;
   timeoutMs?: number;
   retries?: number;

src/client.ts

@@ -407,11 +407,15 @@ export function createAgentDeviceClient(
         await executeCommandRequest(CLIENT_COMMANDS.replay, [options.path], {
           ...options,
           replayUpdate: options.update,
+          replayEnv: options.env,
+          replayShellEnv: collectReplayClientShellEnv(process.env),
         }),
       test: async (options) =>
         await executeCommandRequest(CLIENT_COMMANDS.test, options.paths, {
           ...options,
           replayUpdate: options.update,
+          replayEnv: options.env,
+          replayShellEnv: collectReplayClientShellEnv(process.env),
         }),
     },
     batch: {
@@ -521,6 +525,18 @@ function optionalNumber(value: number | undefined): string[] {
   return value === undefined ? [] : [String(value)];
 }
 
+const REPLAY_SHELL_ENV_PREFIX = 'AD_VAR_';
+
+function collectReplayClientShellEnv(env: NodeJS.ProcessEnv): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value === 'string' && key.startsWith(REPLAY_SHELL_ENV_PREFIX)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 function mergeClientOptions(
   config: AgentDeviceClientConfig,
   options: InternalRequestOptions,

src/commands/selector-read-shared.ts

@@ -1,4 +1,8 @@
-import type { AgentDeviceRuntime, CommandContext, CommandSessionRecord } from '../runtime-contract.ts';
+import type {
+  AgentDeviceRuntime,
+  CommandContext,
+  CommandSessionRecord,
+} from '../runtime-contract.ts';
 import { AppError } from '../utils/errors.ts';
 import type { SnapshotNode, SnapshotState } from '../utils/snapshot.ts';
 import { findNodeByRef, normalizeRef } from '../utils/snapshot.ts';

src/core/interactors.ts

@@ -55,12 +55,7 @@ import {
 import { readLinuxClipboard, writeLinuxClipboard } from '../platforms/linux/clipboard.ts';
 import type { Interactor, RunnerContext } from './interactor-types.ts';
 
-export type {
-  BackMode,
-  Interactor,
-  RunnerContext,
-  ScreenshotOptions,
-} from './interactor-types.ts';
+export type { BackMode, Interactor, RunnerContext, ScreenshotOptions } from './interactor-types.ts';
 
 export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext): Interactor {
   switch (device.platform) {

src/daemon/handlers/__tests__/session-replay-script.test.ts

@@ -259,3 +259,57 @@ test('readReplayScriptMetadata rejects conflicting metadata keys in context head
       /Conflicting replay test metadata "timeoutMs"/.test(error.message),
   );
 });
+
+test('writeReplayScript round-trips ${VAR} tokens byte-for-byte across positionals and flags', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-script-vars-'));
+  const replayPath = path.join(root, 'flow.ad');
+  const actions: SessionAction[] = [
+    {
+      ts: Date.now(),
+      command: 'open',
+      positionals: ['${APP_ID}'],
+      runtime: {
+        platform: 'android',
+        metroHost: '${HOST}',
+      },
+      flags: { relaunch: true },
+    },
+    {
+      ts: Date.now(),
+      command: 'click',
+      positionals: ['label=Wait || ${EXTRA}'],
+      flags: {},
+    },
+    {
+      ts: Date.now(),
+      command: 'snapshot',
+      positionals: [],
+      flags: { snapshotScope: '${SNAPSHOT_SCOPE:-app}' },
+    },
+    {
+      ts: Date.now(),
+      command: 'fill',
+      positionals: ['@e2', 'value-${SUFFIX}'],
+      flags: {},
+    },
+  ];
+
+  writeReplayScript(replayPath, actions, makeSession());
+  const script = fs.readFileSync(replayPath, 'utf8');
+  // Each raw ${...} token must be preserved on disk.
+  assert.ok(script.includes('${APP_ID}'), `missing \${APP_ID} in:\n${script}`);
+  assert.ok(script.includes('${HOST}'), `missing \${HOST} in:\n${script}`);
+  assert.ok(script.includes('label=Wait || ${EXTRA}'), `missing \${EXTRA} in:\n${script}`);
+  assert.ok(
+    script.includes('${SNAPSHOT_SCOPE:-app}'),
+    `missing \${SNAPSHOT_SCOPE:-app} in:\n${script}`,
+  );
+  assert.ok(script.includes('value-${SUFFIX}'), `missing \${SUFFIX} in:\n${script}`);
+
+  const parsed = parseReplayScript(script);
+  assert.deepEqual(parsed[0]?.positionals, ['${APP_ID}']);
+  assert.equal(parsed[0]?.runtime?.metroHost, '${HOST}');
+  assert.deepEqual(parsed[1]?.positionals, ['label=Wait || ${EXTRA}']);
+  assert.equal(parsed[2]?.flags.snapshotScope, '${SNAPSHOT_SCOPE:-app}');
+  assert.deepEqual(parsed[3]?.positionals, ['@e2', 'value-${SUFFIX}']);
+});