feat: add client metro prepare command (#236)

* feat: add client metro prepare command

* fix: tighten metro prepare cli behavior

Author: thymikee

README.md

@@ -349,6 +349,7 @@ Navigation helpers:
 - `install`/`reinstall` accept package/bundle id style app names and support `~` in paths.
 - `install-from-source` supports `--retain-paths` and `--retention-ms <ms>` when callers need retained materialized artifact paths after the install.
 - When `AGENT_DEVICE_DAEMON_BASE_URL` targets a remote daemon, local `.apk`/`.aab`/`.ipa` files and `.app` bundles are uploaded automatically before `install`/`reinstall`.
+- `metro prepare --public-base-url <url>` starts or reuses a local Metro server for sandbox/client flows and prints runtime JSON to stdout. `--json` wraps the same payload in the standard `{ success, data }` envelope. Pass `--proxy-base-url <url>` plus `AGENT_DEVICE_PROXY_TOKEN` (preferred) or `--bearer-token <token>` when the runtime must be bridged through `agent-device-proxy`, and `--runtime-file <path>` only when a persisted artifact is needed.
 - Remote daemon clients can persist session-scoped runtime hints with `runtime set` before `open`; Android launches write React Native dev prefs, and iOS simulator launches write React Native bundle defaults before app start. Example: `agent-device runtime set --session my-session --platform android --metro-host 10.0.0.10 --metro-port 8081 --launch-url "myapp://dev"`.
 - Remote daemon screenshots and recordings are materialized back to the caller path instead of returning host-local daemon paths.
 - To force a daemon-side path instead of uploading a local file, prefix it with `remote:`, for example `remote:/srv/builds/MyApp.app`.
@@ -567,6 +568,7 @@ Environment selectors:
 - `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]` connect directly to a remote HTTP daemon and skip local daemon metadata/startup.
 - Remote daemon installs upload local artifacts through `POST /upload`; use a `remote:` path prefix when you need the daemon to read an existing server-side artifact path as-is.
 - `AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>` auth token for remote HTTP daemon mode; sent in both the JSON-RPC request token and HTTP auth headers (`Authorization: Bearer` and `x-agent-device-token`).
+- `AGENT_DEVICE_PROXY_TOKEN=<token>` preferred bearer token for `metro prepare --proxy-base-url <url>` so the proxy secret does not need to be passed on the command line. `AGENT_DEVICE_METRO_BEARER_TOKEN` is also supported.
 - `AGENT_DEVICE_DAEMON_SERVER_MODE=socket|http|dual` daemon server mode. `http` and `dual` expose JSON-RPC 2.0 at `POST /rpc` (`GET /health` available for liveness).
 - `AGENT_DEVICE_DAEMON_TRANSPORT=auto|socket|http` client preference when connecting to daemon metadata.
 - `AGENT_DEVICE_HTTP_AUTH_HOOK=<module-path>` optional HTTP auth hook module path for JSON-RPC server mode.

src/__tests__/cli-client-commands.test.ts

@@ -1,7 +1,11 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { tryRunClientBackedCommand } from '../cli-client-commands.ts';
-import type { AgentDeviceClient, AppInstallFromSourceOptions } from '../client.ts';
+import type {
+  AgentDeviceClient,
+  AppInstallFromSourceOptions,
+  MetroPrepareOptions,
+} from '../client.ts';
 import { AppError } from '../utils/errors.ts';
 
 test('install-from-source forwards URL and repeated headers to client.apps.installFromSource', async () => {
@@ -73,8 +77,129 @@ test('install-from-source rejects malformed header syntax', async () => {
   );
 });
 
+test('metro prepare forwards normalized options to client.metro.prepare', async () => {
+  let observed: MetroPrepareOptions | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+    prepareMetro: async (options) => {
+      observed = options;
+      return {
+        projectRoot: '/tmp/project',
+        kind: 'react-native',
+        dependenciesInstalled: false,
+        packageManager: null,
+        started: false,
+        reused: true,
+        pid: 0,
+        logPath: '/tmp/project/.agent-device/metro.log',
+        statusUrl: 'http://127.0.0.1:8081/status',
+        runtimeFilePath: null,
+        iosRuntime: {
+          platform: 'ios',
+          bundleUrl: 'https://sandbox.example.test/index.bundle?platform=ios',
+        },
+        androidRuntime: {
+          platform: 'android',
+          bundleUrl: 'https://sandbox.example.test/index.bundle?platform=android',
+        },
+        bridge: null,
+      };
+    },
+  });
+
+  const stdout = await captureStdout(async () => {
+    const handled = await tryRunClientBackedCommand({
+      command: 'metro',
+      positionals: ['prepare'],
+      flags: {
+        json: false,
+        help: false,
+        version: false,
+        metroProjectRoot: './apps/demo',
+        metroPublicBaseUrl: 'https://sandbox.example.test',
+        metroProxyBaseUrl: 'https://proxy.example.test',
+        metroBearerToken: 'secret',
+        metroPreparePort: 9090,
+        metroKind: 'expo',
+        metroRuntimeFile: './.agent-device/metro-runtime.json',
+        metroNoReuseExisting: true,
+        metroNoInstallDeps: true,
+      },
+      client,
+    });
+    assert.equal(handled, true);
+  });
+  const payload = JSON.parse(stdout);
+
+  assert.deepEqual(observed, {
+    projectRoot: './apps/demo',
+    publicBaseUrl: 'https://sandbox.example.test',
+    proxyBaseUrl: 'https://proxy.example.test',
+    bearerToken: 'secret',
+    port: 9090,
+    kind: 'expo',
+    runtimeFilePath: './.agent-device/metro-runtime.json',
+    reuseExisting: false,
+    installDependenciesIfNeeded: false,
+    listenHost: undefined,
+    statusHost: undefined,
+    startupTimeoutMs: undefined,
+    probeTimeoutMs: undefined,
+  });
+  assert.equal(payload.kind, 'react-native');
+  assert.equal(payload.runtimeFilePath, null);
+});
+
+test('metro prepare wraps output in the standard success envelope for --json', async () => {
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+  });
+
+  const stdout = await captureStdout(async () => {
+    const handled = await tryRunClientBackedCommand({
+      command: 'metro',
+      positionals: ['prepare'],
+      flags: {
+        json: true,
+        help: false,
+        version: false,
+        metroPublicBaseUrl: 'https://sandbox.example.test',
+      },
+      client,
+    });
+    assert.equal(handled, true);
+  });
+
+  const payload = JSON.parse(stdout);
+  assert.equal(payload.success, true);
+  assert.equal(payload.data.kind, 'react-native');
+  assert.equal(payload.data.iosRuntime.platform, 'ios');
+});
+
+async function captureStdout(run: () => Promise<void>): Promise<string> {
+  let stdout = '';
+  const originalWrite = process.stdout.write.bind(process.stdout);
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+
+  try {
+    await run();
+  } finally {
+    process.stdout.write = originalWrite;
+  }
+
+  return stdout;
+}
+
 function createStubClient(params: {
   installFromSource: AgentDeviceClient['apps']['installFromSource'];
+  prepareMetro?: AgentDeviceClient['metro']['prepare'];
 }): AgentDeviceClient {
   return {
     devices: {
@@ -140,6 +265,31 @@ function createStubClient(params: {
         identifiers: { session: 'default' },
       }),
     },
+    metro: {
+      prepare:
+        params.prepareMetro ??
+        (async () => ({
+          projectRoot: '/tmp/project',
+          kind: 'react-native',
+          dependenciesInstalled: false,
+          packageManager: null,
+          started: false,
+          reused: true,
+          pid: 0,
+          logPath: '/tmp/project/.agent-device/metro.log',
+          statusUrl: 'http://127.0.0.1:8081/status',
+          runtimeFilePath: null,
+          iosRuntime: {
+            platform: 'ios',
+            bundleUrl: 'https://sandbox.example.test/index.bundle?platform=ios',
+          },
+          androidRuntime: {
+            platform: 'android',
+            bundleUrl: 'https://sandbox.example.test/index.bundle?platform=android',
+          },
+          bridge: null,
+        })),
+    },
     capture: {
       snapshot: async () => ({
         nodes: [],