refactor: finish companion tunnel naming

Author: thymikee

rslib.config.ts

@@ -31,6 +31,7 @@ export default defineConfig({
           selectors: 'src/selectors.ts',
           finders: 'src/finders.ts',
           bin: 'src/bin.ts',
+          'companion-tunnel': 'src/companion-tunnel.ts',
           'metro-companion': 'src/metro-companion.ts',
           daemon: 'src/daemon.ts',
           'update-check-entry': 'src/utils/update-check-entry.ts',

src/__tests__/client-companion-tunnel-worker.test.ts

@@ -350,18 +350,18 @@ test('metro companion worker proxies websocket frames to the local upstream serv
 
   const companion = spawn(
     process.execPath,
-    ['--experimental-strip-types', 'src/metro-companion.ts', '--agent-device-run-metro-companion'],
+    ['--experimental-strip-types', 'src/companion-tunnel.ts', '--agent-device-run-metro-companion'],
     {
       cwd: process.cwd(),
       env: {
         ...process.env,
-        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',
+        AGENT_DEVICE_COMPANION_TUNNEL_SERVER_BASE_URL: `http://127.0.0.1:${bridgePort}`,
+        AGENT_DEVICE_COMPANION_TUNNEL_BEARER_TOKEN: 'test-token',
+        AGENT_DEVICE_COMPANION_TUNNEL_LOCAL_BASE_URL: `http://127.0.0.1:${upstreamPort}`,
+        AGENT_DEVICE_COMPANION_TUNNEL_REGISTER_PATH: '/api/metro/companion/register',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_TENANT_ID: 'tenant-1',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_RUN_ID: 'run-1',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_LEASE_ID: 'lease-1',
       },
       stdio: ['ignore', 'pipe', 'pipe'],
     },
@@ -502,18 +502,18 @@ test('metro companion worker reconnects after the bridge closes immediately afte
 
   const companion = spawn(
     process.execPath,
-    ['--experimental-strip-types', 'src/metro-companion.ts', '--agent-device-run-metro-companion'],
+    ['--experimental-strip-types', 'src/companion-tunnel.ts', '--agent-device-run-metro-companion'],
     {
       cwd: process.cwd(),
       env: {
         ...process.env,
-        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',
+        AGENT_DEVICE_COMPANION_TUNNEL_SERVER_BASE_URL: `http://127.0.0.1:${bridgePort}`,
+        AGENT_DEVICE_COMPANION_TUNNEL_BEARER_TOKEN: 'test-token',
+        AGENT_DEVICE_COMPANION_TUNNEL_LOCAL_BASE_URL: `http://127.0.0.1:${localPort}`,
+        AGENT_DEVICE_COMPANION_TUNNEL_REGISTER_PATH: '/api/metro/companion/register',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_TENANT_ID: 'tenant-1',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_RUN_ID: 'run-1',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_LEASE_ID: 'lease-1',
       },
       stdio: ['ignore', 'pipe', 'pipe'],
     },
@@ -610,19 +610,19 @@ test('metro companion worker exits after its state file is removed', async () =>
 
   const companion = spawn(
     process.execPath,
-    ['--experimental-strip-types', 'src/metro-companion.ts', '--agent-device-run-metro-companion'],
+    ['--experimental-strip-types', 'src/companion-tunnel.ts', '--agent-device-run-metro-companion'],
     {
       cwd: process.cwd(),
       env: {
         ...process.env,
-        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',
-        AGENT_DEVICE_METRO_COMPANION_STATE_PATH: statePath,
+        AGENT_DEVICE_COMPANION_TUNNEL_SERVER_BASE_URL: `http://127.0.0.1:${bridgePort}`,
+        AGENT_DEVICE_COMPANION_TUNNEL_BEARER_TOKEN: 'test-token',
+        AGENT_DEVICE_COMPANION_TUNNEL_LOCAL_BASE_URL: `http://127.0.0.1:${localPort}`,
+        AGENT_DEVICE_COMPANION_TUNNEL_REGISTER_PATH: '/api/metro/companion/register',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_TENANT_ID: 'tenant-1',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_RUN_ID: 'run-1',
+        AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_LEASE_ID: 'lease-1',
+        AGENT_DEVICE_COMPANION_TUNNEL_STATE_PATH: statePath,
       },
       stdio: ['ignore', 'pipe', 'pipe'],
     },
@@ -649,7 +649,7 @@ test('metro companion worker exits after its state file is removed', async () =>
   assert.equal(exit.code, 0, `unexpected worker stderr: ${stderr}`);
 });
 
-test('metro companion worker exits immediately when its state file is already missing', async () => {
+test('metro companion compatibility launcher reads legacy env and exits when state file is missing', async () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-metro-companion-worker-'));
   const statePath = path.join(tempRoot, 'missing-metro-companion.json');
   cleanupTasks.push(async () => {

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

@@ -41,7 +41,7 @@ function assertCompanionSpawnTarget(): void {
   assert.ok(firstCall, 'expected runCmdDetached to be called');
   assert.equal(firstCall[0], process.execPath);
   assert.ok(
-    firstCall[1].some((arg) => arg.includes('src/metro-companion.ts')),
+    firstCall[1].some((arg) => arg.includes('src/companion-tunnel.ts')),
     `expected companion entry path in ${JSON.stringify(firstCall[1])}`,
   );
   assert.equal(firstCall[1].at(-1), '--agent-device-run-metro-companion');
@@ -251,6 +251,48 @@ test('metro and React DevTools companions use distinct profile state paths', asy
   }
 });
 
+test('spawned companion uses neutral env names and clears stale legacy names', async () => {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-companion-env-'));
+  try {
+    vi.mocked(runCmdDetached).mockReturnValueOnce(999);
+    vi.mocked(readProcessStartTime).mockReturnValue('start-999');
+    vi.mocked(readProcessCommand).mockReturnValue(
+      `${process.execPath} src/companion-tunnel.ts --agent-device-run-metro-companion`,
+    );
+
+    await ensureMetroCompanion({
+      projectRoot,
+      serverBaseUrl: 'https://bridge.example.test',
+      bearerToken: 'token',
+      localBaseUrl: 'http://127.0.0.1:8081',
+      bridgeScope: TEST_BRIDGE_SCOPE,
+      launchUrl: 'myapp://open',
+      env: {
+        AGENT_DEVICE_METRO_COMPANION_SERVER_BASE_URL: 'https://legacy.example.test',
+        AGENT_DEVICE_METRO_COMPANION_BEARER_TOKEN: 'legacy-token',
+        AGENT_DEVICE_METRO_COMPANION_LOCAL_BASE_URL: 'http://127.0.0.1:9999',
+        AGENT_DEVICE_METRO_COMPANION_LAUNCH_URL: 'legacy://open',
+      },
+    });
+
+    const env = vi.mocked(runCmdDetached).mock.calls[0]?.[2]?.env;
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_SERVER_BASE_URL, 'https://bridge.example.test');
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_BEARER_TOKEN, 'token');
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_LOCAL_BASE_URL, 'http://127.0.0.1:8081');
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_LAUNCH_URL, 'myapp://open');
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_REGISTER_PATH, '/api/metro/companion/register');
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_TENANT_ID, 'tenant-1');
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_RUN_ID, 'run-1');
+    assert.equal(env?.AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_LEASE_ID, 'lease-1');
+    assert.equal(env?.AGENT_DEVICE_METRO_COMPANION_SERVER_BASE_URL, undefined);
+    assert.equal(env?.AGENT_DEVICE_METRO_COMPANION_BEARER_TOKEN, undefined);
+    assert.equal(env?.AGENT_DEVICE_METRO_COMPANION_LOCAL_BASE_URL, undefined);
+    assert.equal(env?.AGENT_DEVICE_METRO_COMPANION_LAUNCH_URL, undefined);
+  } 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/cli/commands/connection-runtime.ts

@@ -2,7 +2,7 @@ import { resolveDaemonPaths } from '../../daemon/config.ts';
 import { stopReactDevtoolsCompanion } from '../../client-react-devtools-companion.ts';
 import { stopMetroTunnel } from '../../metro.ts';
 import { resolveRemoteConfigProfile } from '../../remote-config.ts';
-import type { CompanionTunnelScope as MetroBridgeScope } from '../../client-companion-tunnel-contract.ts';
+import type { MetroBridgeScope } from '../../client-companion-tunnel-contract.ts';
 import {
   buildRemoteConnectionDaemonState,
   hashRemoteConfigFile,

src/client-companion-tunnel-contract.ts

@@ -4,25 +4,31 @@ 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 const ENV_COMPANION_TUNNEL_SERVER_BASE_URL = 'AGENT_DEVICE_COMPANION_TUNNEL_SERVER_BASE_URL';
+export const ENV_COMPANION_TUNNEL_BEARER_TOKEN = 'AGENT_DEVICE_COMPANION_TUNNEL_BEARER_TOKEN';
+export const ENV_COMPANION_TUNNEL_LOCAL_BASE_URL = 'AGENT_DEVICE_COMPANION_TUNNEL_LOCAL_BASE_URL';
+export const ENV_COMPANION_TUNNEL_LAUNCH_URL = 'AGENT_DEVICE_COMPANION_TUNNEL_LAUNCH_URL';
+export const ENV_COMPANION_TUNNEL_STATE_PATH = 'AGENT_DEVICE_COMPANION_TUNNEL_STATE_PATH';
+export const ENV_COMPANION_TUNNEL_SCOPE_TENANT_ID = 'AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_TENANT_ID';
+export const ENV_COMPANION_TUNNEL_SCOPE_RUN_ID = 'AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_RUN_ID';
+export const ENV_COMPANION_TUNNEL_SCOPE_LEASE_ID = 'AGENT_DEVICE_COMPANION_TUNNEL_SCOPE_LEASE_ID';
+export const ENV_COMPANION_TUNNEL_REGISTER_PATH = 'AGENT_DEVICE_COMPANION_TUNNEL_REGISTER_PATH';
+export const ENV_COMPANION_TUNNEL_UNREGISTER_PATH = 'AGENT_DEVICE_COMPANION_TUNNEL_UNREGISTER_PATH';
+export const ENV_COMPANION_TUNNEL_DEVICE_PORT = 'AGENT_DEVICE_COMPANION_TUNNEL_DEVICE_PORT';
+export const ENV_COMPANION_TUNNEL_SESSION = 'AGENT_DEVICE_COMPANION_TUNNEL_SESSION';
 
 export type CompanionTunnelScope = {
   tenantId: string;
   runId: string;
   leaseId: string;
 };
 
+export type MetroBridgeScope = CompanionTunnelScope;
+
+export class MissingCompanionEnvError extends Error {
+  override name = 'MissingCompanionEnvError';
+}
+
 export type CompanionTunnelWorkerOptions = {
   serverBaseUrl: string;
   bearerToken: string;

src/client-companion-tunnel-env.ts

@@ -0,0 +1,31 @@
+const CURRENT_ENV_PREFIX = 'AGENT_DEVICE_COMPANION_TUNNEL_';
+const LEGACY_ENV_PREFIX = 'AGENT_DEVICE_METRO_COMPANION_';
+
+type CompanionTunnelEnvName = `${typeof CURRENT_ENV_PREFIX}${string}`;
+
+function legacyEnvName(name: CompanionTunnelEnvName): string {
+  return name.replace(CURRENT_ENV_PREFIX, LEGACY_ENV_PREFIX);
+}
+
+export function setWorkerEnv(
+  env: NodeJS.ProcessEnv,
+  name: CompanionTunnelEnvName,
+  value: string,
+): void {
+  env[name] = value;
+  delete env[legacyEnvName(name)];
+}
+
+export function clearWorkerEnv(env: NodeJS.ProcessEnv, name: CompanionTunnelEnvName): void {
+  delete env[name];
+  delete env[legacyEnvName(name)];
+}
+
+export function readWorkerEnv(
+  env: NodeJS.ProcessEnv,
+  name: CompanionTunnelEnvName,
+): string | undefined {
+  const value = env[name]?.trim();
+  if (value) return value;
+  return env[legacyEnvName(name)]?.trim() || undefined;
+}

src/client-companion-tunnel-worker.ts

@@ -18,8 +18,10 @@ import {
   METRO_COMPANION_RUN_ARG,
   REACT_DEVTOOLS_COMPANION_RUN_ARG,
   WS_READY_STATE_OPEN,
+  MissingCompanionEnvError,
   type CompanionTunnelWorkerOptions,
 } from './client-companion-tunnel-contract.ts';
+import { readWorkerEnv } from './client-companion-tunnel-env.ts';
 import type {
   MetroTunnelRequestMessage as MetroCompanionRequest,
   MetroTunnelResponseMessage,
@@ -446,21 +448,27 @@ function readWorkerOptions(
   if (commandArg !== METRO_COMPANION_RUN_ARG && commandArg !== REACT_DEVTOOLS_COMPANION_RUN_ARG) {
     return null;
   }
-  const serverBaseUrl = env[ENV_COMPANION_TUNNEL_SERVER_BASE_URL]?.trim();
-  const bearerToken = env[ENV_COMPANION_TUNNEL_BEARER_TOKEN]?.trim();
-  const localBaseUrl = env[ENV_COMPANION_TUNNEL_LOCAL_BASE_URL]?.trim();
+  const serverBaseUrl = readWorkerEnv(env, ENV_COMPANION_TUNNEL_SERVER_BASE_URL);
+  const bearerToken = readWorkerEnv(env, ENV_COMPANION_TUNNEL_BEARER_TOKEN);
+  const localBaseUrl = readWorkerEnv(env, ENV_COMPANION_TUNNEL_LOCAL_BASE_URL);
   if (!serverBaseUrl || !bearerToken || !localBaseUrl) {
-    throw new Error('Companion tunnel worker is missing required environment configuration.');
+    throw new MissingCompanionEnvError(
+      'Companion tunnel worker is missing required environment configuration.',
+    );
   }
-  const tenantId = env[ENV_COMPANION_TUNNEL_SCOPE_TENANT_ID]?.trim();
-  const runId = env[ENV_COMPANION_TUNNEL_SCOPE_RUN_ID]?.trim();
-  const leaseId = env[ENV_COMPANION_TUNNEL_SCOPE_LEASE_ID]?.trim();
+  const tenantId = readWorkerEnv(env, ENV_COMPANION_TUNNEL_SCOPE_TENANT_ID);
+  const runId = readWorkerEnv(env, ENV_COMPANION_TUNNEL_SCOPE_RUN_ID);
+  const leaseId = readWorkerEnv(env, ENV_COMPANION_TUNNEL_SCOPE_LEASE_ID);
   if (!tenantId || !runId || !leaseId) {
-    throw new Error('Companion tunnel worker is missing required bridge scope configuration.');
+    throw new MissingCompanionEnvError(
+      'Companion tunnel worker is missing required bridge scope configuration.',
+    );
   }
-  const registerPath = env[ENV_COMPANION_TUNNEL_REGISTER_PATH]?.trim();
+  const registerPath = readWorkerEnv(env, ENV_COMPANION_TUNNEL_REGISTER_PATH);
   if (!registerPath) {
-    throw new Error('Companion tunnel worker is missing required register path configuration.');
+    throw new MissingCompanionEnvError(
+      'Companion tunnel worker is missing required register path configuration.',
+    );
   }
   return {
     serverBaseUrl,
@@ -472,11 +480,11 @@ function readWorkerOptions(
       runId,
       leaseId,
     },
-    launchUrl: env[ENV_COMPANION_TUNNEL_LAUNCH_URL]?.trim() || undefined,
-    statePath: env[ENV_COMPANION_TUNNEL_STATE_PATH]?.trim() || undefined,
-    unregisterPath: env[ENV_COMPANION_TUNNEL_UNREGISTER_PATH]?.trim() || undefined,
-    devicePort: parseDevicePort(env[ENV_COMPANION_TUNNEL_DEVICE_PORT]),
-    session: env[ENV_COMPANION_TUNNEL_SESSION]?.trim() || undefined,
+    launchUrl: readWorkerEnv(env, ENV_COMPANION_TUNNEL_LAUNCH_URL),
+    statePath: readWorkerEnv(env, ENV_COMPANION_TUNNEL_STATE_PATH),
+    unregisterPath: readWorkerEnv(env, ENV_COMPANION_TUNNEL_UNREGISTER_PATH),
+    devicePort: parseDevicePort(readWorkerEnv(env, ENV_COMPANION_TUNNEL_DEVICE_PORT)),
+    session: readWorkerEnv(env, ENV_COMPANION_TUNNEL_SESSION),
   };
 }