refactor: extract companion tunnel core (#442)

Author: thymikee

src/__tests__/cli-react-devtools.test.ts

@@ -6,13 +6,16 @@ vi.mock('../utils/exec.ts', () => ({
   runCmdStreaming: vi.fn(),
 }));
 
-vi.mock('../client-metro-companion.ts', () => ({
-  ensureMetroCompanion: vi.fn(),
-  stopMetroCompanion: vi.fn(),
+vi.mock('../client-react-devtools-companion.ts', () => ({
+  ensureReactDevtoolsCompanion: vi.fn(),
+  stopReactDevtoolsCompanion: vi.fn(),
 }));
 
 import { runCmdStreaming } from '../utils/exec.ts';
-import { ensureMetroCompanion, stopMetroCompanion } from '../client-metro-companion.ts';
+import {
+  ensureReactDevtoolsCompanion,
+  stopReactDevtoolsCompanion,
+} from '../client-react-devtools-companion.ts';
 import {
   AGENT_REACT_DEVTOOLS_PACKAGE,
   buildReactDevtoolsNpmExecArgs,
@@ -54,13 +57,13 @@ test('react-devtools starts remote Android companion around passthrough command'
     stdout: '',
     stderr: '',
   });
-  vi.mocked(ensureMetroCompanion).mockResolvedValueOnce({
+  vi.mocked(ensureReactDevtoolsCompanion).mockResolvedValueOnce({
     pid: 123,
     spawned: true,
     statePath: '/tmp/state.json',
     logPath: '/tmp/companion.log',
   });
-  vi.mocked(stopMetroCompanion).mockResolvedValueOnce({
+  vi.mocked(stopReactDevtoolsCompanion).mockResolvedValueOnce({
     stopped: true,
     statePath: '/tmp/state.json',
   });
@@ -84,22 +87,17 @@ test('react-devtools starts remote Android companion around passthrough command'
   });
 
   assert.equal(exitCode, 0);
-  assert.equal(vi.mocked(ensureMetroCompanion).mock.calls.length, 1);
-  assert.deepEqual(vi.mocked(ensureMetroCompanion).mock.calls[0]?.[0], {
+  assert.equal(vi.mocked(ensureReactDevtoolsCompanion).mock.calls.length, 1);
+  assert.deepEqual(vi.mocked(ensureReactDevtoolsCompanion).mock.calls[0]?.[0], {
     projectRoot: '/tmp/project',
     stateDir: '/tmp/agent-device-state',
-    kind: 'react-devtools',
     serverBaseUrl: 'https://bridge.example.test',
     bearerToken: 'token',
-    localBaseUrl: 'http://127.0.0.1:8097',
     bridgeScope: {
       tenantId: 'tenant-1',
       runId: 'run-1',
       leaseId: 'lease-1',
     },
-    registerPath: '/api/react-devtools/companion/register',
-    unregisterPath: '/api/react-devtools/companion/unregister',
-    devicePort: 8097,
     session: 'default',
     profileKey: '/tmp/remote.json',
     consumerKey: 'default',
@@ -108,11 +106,10 @@ test('react-devtools starts remote Android companion around passthrough command'
   assert.equal(vi.mocked(runCmdStreaming).mock.calls[0]?.[0], 'npm');
   assert.equal(vi.mocked(runCmdStreaming).mock.calls[0]?.[2]?.cwd, '/tmp/project');
   assert.equal(vi.mocked(runCmdStreaming).mock.calls[0]?.[2]?.env, env);
-  assert.equal(vi.mocked(stopMetroCompanion).mock.calls.length, 1);
-  assert.deepEqual(vi.mocked(stopMetroCompanion).mock.calls[0]?.[0], {
+  assert.equal(vi.mocked(stopReactDevtoolsCompanion).mock.calls.length, 1);
+  assert.deepEqual(vi.mocked(stopReactDevtoolsCompanion).mock.calls[0]?.[0], {
     projectRoot: '/tmp/project',
     stateDir: '/tmp/agent-device-state',
-    kind: 'react-devtools',
     profileKey: '/tmp/remote.json',
     consumerKey: 'default',
   });
@@ -138,8 +135,8 @@ test('react-devtools skips companion for non-Android remote sessions', async ()
     },
   });
 
-  assert.equal(vi.mocked(ensureMetroCompanion).mock.calls.length, 0);
-  assert.equal(vi.mocked(stopMetroCompanion).mock.calls.length, 0);
+  assert.equal(vi.mocked(ensureReactDevtoolsCompanion).mock.calls.length, 0);
+  assert.equal(vi.mocked(stopReactDevtoolsCompanion).mock.calls.length, 0);
 });
 
 test('react-devtools fails clearly when remote Android bridge scope is incomplete', async () => {
@@ -161,5 +158,5 @@ test('react-devtools fails clearly when remote Android bridge scope is incomplet
   );
 
   assert.equal(vi.mocked(runCmdStreaming).mock.calls.length, 0);
-  assert.equal(vi.mocked(ensureMetroCompanion).mock.calls.length, 0);
+  assert.equal(vi.mocked(ensureReactDevtoolsCompanion).mock.calls.length, 0);
 });

…__/client-metro-companion-worker.test.ts …_/client-companion-tunnel-worker.test.tssrc/__tests__/client-metro-companion-worker.test.ts renamed to src/__tests__/client-companion-tunnel-worker.test.ts src/__tests__/client-metro-companion-worker.test.ts renamed to src/__tests__/client-companion-tunnel-worker.test.ts

@@ -8,7 +8,7 @@ import path from 'node:path';
 import type { Duplex } from 'node:stream';
 import { setTimeout as delay } from 'node:timers/promises';
 import { afterEach, test } from 'vitest';
-import { buildCompanionPayload } from '../client-metro-companion-worker.ts';
+import { buildCompanionPayload } from '../client-companion-tunnel-worker.ts';
 
 type Deferred<T> = {
   promise: Promise<T>;
@@ -358,6 +358,7 @@ test('metro companion worker proxies websocket frames to the local upstream serv
         AGENT_DEVICE_METRO_COMPANION_SERVER_BASE_URL: `http://127.0.0.1:${bridgePort}`,
         AGENT_DEVICE_METRO_COMPANION_BEARER_TOKEN: 'test-token',
         AGENT_DEVICE_METRO_COMPANION_LOCAL_BASE_URL: `http://127.0.0.1:${upstreamPort}`,
+        AGENT_DEVICE_METRO_COMPANION_REGISTER_PATH: '/api/metro/companion/register',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_TENANT_ID: 'tenant-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_RUN_ID: 'run-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_LEASE_ID: 'lease-1',
@@ -509,6 +510,7 @@ test('metro companion worker reconnects after the bridge closes immediately afte
         AGENT_DEVICE_METRO_COMPANION_SERVER_BASE_URL: `http://127.0.0.1:${bridgePort}`,
         AGENT_DEVICE_METRO_COMPANION_BEARER_TOKEN: 'test-token',
         AGENT_DEVICE_METRO_COMPANION_LOCAL_BASE_URL: `http://127.0.0.1:${localPort}`,
+        AGENT_DEVICE_METRO_COMPANION_REGISTER_PATH: '/api/metro/companion/register',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_TENANT_ID: 'tenant-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_RUN_ID: 'run-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_LEASE_ID: 'lease-1',
@@ -616,6 +618,7 @@ test('metro companion worker exits after its state file is removed', async () =>
         AGENT_DEVICE_METRO_COMPANION_SERVER_BASE_URL: `http://127.0.0.1:${bridgePort}`,
         AGENT_DEVICE_METRO_COMPANION_BEARER_TOKEN: 'test-token',
         AGENT_DEVICE_METRO_COMPANION_LOCAL_BASE_URL: `http://127.0.0.1:${localPort}`,
+        AGENT_DEVICE_METRO_COMPANION_REGISTER_PATH: '/api/metro/companion/register',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_TENANT_ID: 'tenant-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_RUN_ID: 'run-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_LEASE_ID: 'lease-1',
@@ -663,6 +666,7 @@ test('metro companion worker exits immediately when its state file is already mi
         AGENT_DEVICE_METRO_COMPANION_SERVER_BASE_URL: 'http://127.0.0.1:1',
         AGENT_DEVICE_METRO_COMPANION_BEARER_TOKEN: 'test-token',
         AGENT_DEVICE_METRO_COMPANION_LOCAL_BASE_URL: 'http://127.0.0.1:1',
+        AGENT_DEVICE_METRO_COMPANION_REGISTER_PATH: '/api/metro/companion/register',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_TENANT_ID: 'tenant-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_RUN_ID: 'run-1',
         AGENT_DEVICE_METRO_COMPANION_SCOPE_LEASE_ID: 'lease-1',

src/__tests__/client-metro-companion.test.ts

@@ -23,6 +23,7 @@ import {
   waitForProcessExit,
 } from '../utils/process-identity.ts';
 import { ensureMetroCompanion, stopMetroCompanion } from '../client-metro-companion.ts';
+import { ensureReactDevtoolsCompanion } from '../client-react-devtools-companion.ts';
 
 const TEST_BRIDGE_SCOPE = {
   tenantId: 'tenant-1',
@@ -46,6 +47,12 @@ function assertCompanionSpawnTarget(): void {
   assert.equal(firstCall[1].at(-1), '--agent-device-run-metro-companion');
 }
 
+function assertCompanionRunArg(callIndex: number, runArg: string): void {
+  const call = vi.mocked(runCmdDetached).mock.calls[callIndex];
+  assert.ok(call, `expected runCmdDetached call ${callIndex}`);
+  assert.equal(call[1].at(-1), runArg);
+}
+
 test('companion ownership is profile-scoped and consumer-counted', async () => {
   const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-metro-companion-state-'));
   try {
@@ -196,6 +203,54 @@ test('launchUrl changes force a companion respawn for the same profile', async (
   }
 });
 
+test('metro and React DevTools companions use distinct profile state paths', async () => {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-companion-paths-'));
+  try {
+    vi.mocked(runCmdDetached).mockReturnValueOnce(777).mockReturnValueOnce(888);
+    vi.mocked(readProcessStartTime).mockImplementation((pid) =>
+      pid === 777 ? 'start-777' : 'start-888',
+    );
+    vi.mocked(readProcessCommand).mockImplementation((pid) =>
+      pid === 888
+        ? `${process.execPath} src/metro-companion.ts --agent-device-run-react-devtools-companion`
+        : `${process.execPath} src/metro-companion.ts --agent-device-run-metro-companion`,
+    );
+
+    const profileKey = '/tmp/shared-remote.json';
+    const metro = await ensureMetroCompanion({
+      projectRoot,
+      serverBaseUrl: 'https://bridge.example.test',
+      bearerToken: 'token',
+      localBaseUrl: 'http://127.0.0.1:8081',
+      bridgeScope: TEST_BRIDGE_SCOPE,
+      launchUrl: 'myapp://open',
+      profileKey,
+      consumerKey: 'session-a',
+    });
+    const reactDevtools = await ensureReactDevtoolsCompanion({
+      projectRoot,
+      serverBaseUrl: 'https://bridge.example.test',
+      bearerToken: 'token',
+      bridgeScope: TEST_BRIDGE_SCOPE,
+      session: 'session-a',
+      profileKey,
+      consumerKey: 'session-a',
+    });
+
+    assert.notEqual(metro.statePath, reactDevtools.statePath);
+    assert.notEqual(metro.logPath, reactDevtools.logPath);
+    assert.match(metro.statePath, /metro-companion[/\\]metro-companion-[a-f0-9]+\.json$/);
+    assert.match(
+      reactDevtools.statePath,
+      /react-devtools-companion[/\\]react-devtools-companion-[a-f0-9]+\.json$/,
+    );
+    assertCompanionRunArg(0, '--agent-device-run-metro-companion');
+    assertCompanionRunArg(1, '--agent-device-run-react-devtools-companion');
+  } finally {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  }
+});
+
 test('legacy state without bridge scope is stopped before respawn', async () => {
   const projectRoot = fs.mkdtempSync(
     path.join(os.tmpdir(), 'agent-device-metro-companion-legacy-'),

src/__tests__/remote-connection.test.ts

@@ -8,6 +8,10 @@ vi.mock('../client-metro-companion.ts', () => ({
   stopMetroCompanion: vi.fn(),
 }));
 
+vi.mock('../client-react-devtools-companion.ts', () => ({
+  stopReactDevtoolsCompanion: vi.fn(),
+}));
+
 import {
   connectCommand,
   connectionCommand,

src/cli/commands/connection-runtime.ts

@@ -1,8 +1,8 @@
 import { resolveDaemonPaths } from '../../daemon/config.ts';
-import { stopMetroCompanion } from '../../client-metro-companion.ts';
+import { stopReactDevtoolsCompanion } from '../../client-react-devtools-companion.ts';
 import { stopMetroTunnel } from '../../metro.ts';
 import { resolveRemoteConfigProfile } from '../../remote-config.ts';
-import type { MetroBridgeScope } from '../../client-metro-companion-contract.ts';
+import type { CompanionTunnelScope as MetroBridgeScope } from '../../client-companion-tunnel-contract.ts';
 import {
   buildRemoteConnectionDaemonState,
   hashRemoteConfigFile,
@@ -242,10 +242,9 @@ export async function stopReactDevtoolsCleanup(options: {
   state: Pick<RemoteConnectionState, 'remoteConfigPath' | 'session'>;
 }): Promise<void> {
   try {
-    await stopMetroCompanion({
+    await stopReactDevtoolsCompanion({
       projectRoot: process.cwd(),
       stateDir: options.stateDir,
-      kind: 'react-devtools',
       profileKey: options.state.remoteConfigPath,
       consumerKey: options.state.session,
     });

src/cli/commands/react-devtools.ts

@@ -1,15 +1,14 @@
 import { runCmdStreaming } from '../../utils/exec.ts';
-import { ensureMetroCompanion, stopMetroCompanion } from '../../client-metro-companion.ts';
+import {
+  ensureReactDevtoolsCompanion,
+  stopReactDevtoolsCompanion,
+} from '../../client-react-devtools-companion.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';
 
 export const AGENT_REACT_DEVTOOLS_VERSION = '0.4.0';
 export const AGENT_REACT_DEVTOOLS_PACKAGE = `agent-react-devtools@${AGENT_REACT_DEVTOOLS_VERSION}`;
 const AGENT_REACT_DEVTOOLS_BIN = 'agent-react-devtools';
-const REACT_DEVTOOLS_LOCAL_BASE_URL = 'http://127.0.0.1:8097';
-const REACT_DEVTOOLS_DEVICE_PORT = 8097;
-const REACT_DEVTOOLS_REGISTER_PATH = '/api/react-devtools/companion/register';
-const REACT_DEVTOOLS_UNREGISTER_PATH = '/api/react-devtools/companion/unregister';
 
 type ReactDevtoolsCommandOptions = {
   flags?: Pick<
@@ -101,21 +100,16 @@ async function withRemoteAndroidDevtoolsCompanion<T>(
   const session = options.session ?? flags?.session ?? 'default';
   const profileKey =
     flags?.remoteConfig ?? `${bridgeConfig.tenantId}:${bridgeConfig.runId}:${bridgeConfig.leaseId}`;
-  await ensureMetroCompanion({
+  await ensureReactDevtoolsCompanion({
     projectRoot: options.cwd ?? process.cwd(),
     stateDir,
-    kind: 'react-devtools',
     serverBaseUrl: bridgeConfig.serverBaseUrl,
     bearerToken: bridgeConfig.bearerToken,
-    localBaseUrl: REACT_DEVTOOLS_LOCAL_BASE_URL,
     bridgeScope: {
       tenantId: bridgeConfig.tenantId,
       runId: bridgeConfig.runId,
       leaseId: bridgeConfig.leaseId,
     },
-    registerPath: REACT_DEVTOOLS_REGISTER_PATH,
-    unregisterPath: REACT_DEVTOOLS_UNREGISTER_PATH,
-    devicePort: REACT_DEVTOOLS_DEVICE_PORT,
     session,
     profileKey,
     consumerKey: session,
@@ -124,10 +118,9 @@ async function withRemoteAndroidDevtoolsCompanion<T>(
   try {
     return await action();
   } finally {
-    await stopMetroCompanion({
+    await stopReactDevtoolsCompanion({
       projectRoot: options.cwd ?? process.cwd(),
       stateDir,
-      kind: 'react-devtools',
       profileKey,
       consumerKey: session,
     });

src/client-companion-tunnel-contract.ts

@@ -0,0 +1,37 @@
+export const METRO_COMPANION_RUN_ARG = '--agent-device-run-metro-companion';
+export const REACT_DEVTOOLS_COMPANION_RUN_ARG = '--agent-device-run-react-devtools-companion';
+export const COMPANION_TUNNEL_RECONNECT_DELAY_MS = 1_000;
+export const COMPANION_TUNNEL_LEASE_CHECK_INTERVAL_MS = 250;
+export const WS_READY_STATE_OPEN = 1;
+
+export const ENV_COMPANION_TUNNEL_SERVER_BASE_URL = 'AGENT_DEVICE_METRO_COMPANION_SERVER_BASE_URL';
+export const ENV_COMPANION_TUNNEL_BEARER_TOKEN = 'AGENT_DEVICE_METRO_COMPANION_BEARER_TOKEN';
+export const ENV_COMPANION_TUNNEL_LOCAL_BASE_URL = 'AGENT_DEVICE_METRO_COMPANION_LOCAL_BASE_URL';
+export const ENV_COMPANION_TUNNEL_LAUNCH_URL = 'AGENT_DEVICE_METRO_COMPANION_LAUNCH_URL';
+export const ENV_COMPANION_TUNNEL_STATE_PATH = 'AGENT_DEVICE_METRO_COMPANION_STATE_PATH';
+export const ENV_COMPANION_TUNNEL_SCOPE_TENANT_ID = 'AGENT_DEVICE_METRO_COMPANION_SCOPE_TENANT_ID';
+export const ENV_COMPANION_TUNNEL_SCOPE_RUN_ID = 'AGENT_DEVICE_METRO_COMPANION_SCOPE_RUN_ID';
+export const ENV_COMPANION_TUNNEL_SCOPE_LEASE_ID = 'AGENT_DEVICE_METRO_COMPANION_SCOPE_LEASE_ID';
+export const ENV_COMPANION_TUNNEL_REGISTER_PATH = 'AGENT_DEVICE_METRO_COMPANION_REGISTER_PATH';
+export const ENV_COMPANION_TUNNEL_UNREGISTER_PATH = 'AGENT_DEVICE_METRO_COMPANION_UNREGISTER_PATH';
+export const ENV_COMPANION_TUNNEL_DEVICE_PORT = 'AGENT_DEVICE_METRO_COMPANION_DEVICE_PORT';
+export const ENV_COMPANION_TUNNEL_SESSION = 'AGENT_DEVICE_METRO_COMPANION_SESSION';
+
+export type CompanionTunnelScope = {
+  tenantId: string;
+  runId: string;
+  leaseId: string;
+};
+
+export type CompanionTunnelWorkerOptions = {
+  serverBaseUrl: string;
+  bearerToken: string;
+  localBaseUrl: string;
+  bridgeScope: CompanionTunnelScope;
+  registerPath: string;
+  launchUrl?: string;
+  statePath?: string;
+  unregisterPath?: string;
+  devicePort?: number;
+  session?: string;
+};