@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.12-preview.1

package/scripts/utils/expo/expo_state_running.test.mjs

@@ -2,11 +2,54 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
 import { spawn } from 'node:child_process';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { once } from 'node:events';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { isStateProcessRunning } from './expo.mjs';
+import {
+  commitExpoPidStatePublication,
+  isStateProcessRunning,
+  readPidState,
+  restoreExpoPidStatePublication,
+} from './expo.mjs';
+
+test('Expo PID publication loser cannot overwrite or roll back a successor', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-pid-publication-'));
+  t.after(async () => rm(tmp, { recursive: true, force: true }));
+  const statePath = join(tmp, 'expo.state.json');
+
+  await commitExpoPidStatePublication(statePath, {
+    publicationToken: 'A', expectedPreviousToken: null, generation: 1, state: { pid: 101, port: 8081 },
+  });
+  await commitExpoPidStatePublication(statePath, {
+    publicationToken: 'B', expectedPreviousToken: 'A', generation: 1, state: { pid: 202, port: 8082 },
+  });
+  await assert.rejects(
+    () => commitExpoPidStatePublication(statePath, {
+      publicationToken: 'A-late', expectedPreviousToken: 'A', generation: 2, state: { pid: 303, port: 8083 },
+    }),
+    (error) => error?.code === 'EEXPOPIDGENERATION',
+  );
+  assert.equal(await restoreExpoPidStatePublication(statePath, { publicationToken: 'A', priorState: null }), false);
+  assert.deepEqual(await readPidState(statePath), {
+    pid: 202,
+    port: 8082,
+    publicationGeneration: 1,
+    publicationToken: 'B',
+  });
+});
+
+test('Expo PID publication fails closed on malformed current state', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-pid-malformed-'));
+  t.after(async () => rm(tmp, { recursive: true, force: true }));
+  const statePath = join(tmp, 'expo.state.json');
+  await writeFile(statePath, '{broken', 'utf-8');
+  await assert.rejects(() => commitExpoPidStatePublication(statePath, {
+    publicationToken: 'A', expectedPreviousToken: null, generation: 1, state: { pid: 101, port: 8081 },
+  }), SyntaxError);
+  assert.equal(await readFile(statePath, 'utf-8'), '{broken');
+});
 
 function listen(server) {
   return new Promise((resolve, reject) => {
@@ -112,3 +155,62 @@ test('isStateProcessRunning does not treat an unrelated Metro on the same port a
     await rm(tmp, { recursive: true, force: true });
   }
 });
+
+test('isStateProcessRunning does not trust a live pid whose Expo isolation belongs to another state dir', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-state-pid-identity-'));
+  let child = null;
+  try {
+    const expectedStateDir = join(tmp, 'expected');
+    const foreignStateDir = join(tmp, 'foreign');
+    await mkdir(join(expectedStateDir, 'expo-home'), { recursive: true });
+    await mkdir(join(foreignStateDir, 'expo-home'), { recursive: true });
+
+    child = spawn(process.execPath, ['-e', "process.stdout.write('ready\\n'); setInterval(() => {}, 1000);"], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        TMPDIR: process.env.TMPDIR,
+        __UNSAFE_EXPO_HOME_DIRECTORY: join(foreignStateDir, 'expo-home'),
+      },
+    });
+    const ready = once(child.stdout, 'data');
+    await once(child, 'spawn');
+    await ready;
+
+    const statePath = join(expectedStateDir, 'expo.state.json');
+    await writeFile(
+      statePath,
+      JSON.stringify(
+        {
+          pid: child.pid,
+          port: 19000,
+          projectDir: join(tmp, 'expected-project'),
+        },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+
+    let res = null;
+    const identityDeadline = Date.now() + 15_000;
+    while (Date.now() < identityDeadline) {
+      res = await isStateProcessRunning(statePath, {
+        readProcessIdentityLineImpl: async () =>
+          `node __UNSAFE_EXPO_HOME_DIRECTORY=${join(foreignStateDir, 'expo-home')}`,
+      });
+      if (res.reason === 'pid_identity_mismatch') break;
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    assert.equal(res.running, false);
+    assert.equal(res.reason, 'pid_identity_mismatch');
+  } finally {
+    try {
+      child?.kill('SIGKILL');
+    } catch {
+      // ignore
+    }
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/utils/expo/expo_wait_for_metro.test.mjs

@@ -1,5 +1,8 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
 
 import { waitForExpoMetroRunning } from './expo.mjs';
 
@@ -48,3 +51,187 @@ test('waitForExpoMetroRunning returns a non-ok result when the timeout elapses',
   assert.equal(result.probes >= 2, true);
 });
 
+test('waitForExpoMetroRunning treats attended TUI deadlines as checkpoints while its owner is alive', async () => {
+  const ownerProc = new EventEmitter();
+  ownerProc.exitCode = null;
+  ownerProc.signalCode = null;
+  let probes = 0;
+  let checkpoints = 0;
+  const result = await waitForExpoMetroRunning({
+    port: 8081,
+    ownerProc,
+    timeoutMs: 25,
+    intervalMs: 10,
+    env: { HAPPIER_STACK_TUI: '1' },
+    onTimeoutCheckpoint: () => { checkpoints += 1; },
+  }, {
+    looksLikeExpoMetroImpl: async () => {
+      probes += 1;
+      return probes >= 5;
+    },
+    delayImpl: async () => {},
+    nowMsImpl: (() => {
+      let now = 0;
+      return () => { now += 10; return now; };
+    })(),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(checkpoints >= 1, true);
+});
+
+test('waitForExpoMetroRunning rejects a foreign Metro-shaped listener', async () => {
+  const result = await waitForExpoMetroRunning({
+    port: 8081,
+    ownerPid: 100,
+    timeoutMs: 25,
+    intervalMs: 10,
+    env: { TEST_READY_ENV: 'yes' },
+  }, {
+    looksLikeExpoMetroImpl: async ({ env }) => {
+      assert.equal(env.TEST_READY_ENV, 'yes');
+      return true;
+    },
+    listListenPidsWithStatusImpl: async () => ({ status: 'ok', pids: [200] }),
+    getProcessGroupIdImpl: async (pid) => pid,
+    delayImpl: async () => {},
+    nowMsImpl: (() => {
+      let now = 0;
+      return () => { now += 10; return now; };
+    })(),
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, 'listener_not_owned');
+  assert.deepEqual(result.listenerPids, [200]);
+});
+
+test('waitForExpoMetroRunning accepts a listener in the spawned process group', async () => {
+  const result = await waitForExpoMetroRunning({
+    port: 8081,
+    ownerPid: 100,
+    env: { TEST_READY_ENV: 'yes' },
+  }, {
+    looksLikeExpoMetroImpl: async ({ env }) => env.TEST_READY_ENV === 'yes',
+    listListenPidsWithStatusImpl: async () => ({ status: 'ok', pids: [101] }),
+    getProcessGroupIdImpl: async () => 500,
+  });
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.listenerPids, [101]);
+});
+
+test('waitForExpoMetroRunning preserves unsupported ownership evidence as inconclusive', async () => {
+  const result = await waitForExpoMetroRunning({
+    port: 8081,
+    ownerPid: 100,
+    timeoutMs: 1,
+    intervalMs: 1,
+  }, {
+    looksLikeExpoMetroImpl: async () => true,
+    listListenPidsWithStatusImpl: async () => ({ status: 'unsupported', pids: [], reason: 'unsupported-platform' }),
+    delayImpl: async () => {},
+    nowMsImpl: (() => {
+      let now = 0;
+      return () => { now += 1; return now; };
+    })(),
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, 'listener_ownership_inconclusive');
+  assert.equal(result.observation.reason, 'unsupported-platform');
+});
+
+test('waitForExpoMetroRunning does not downgrade a missing tracked owner to HTTP-only readiness', async () => {
+  const result = await waitForExpoMetroRunning({
+    port: 8081,
+    ownerPid: () => null,
+    timeoutMs: 1,
+    intervalMs: 1,
+  }, {
+    looksLikeExpoMetroImpl: async () => true,
+    delayImpl: async () => {},
+    nowMsImpl: (() => {
+      let now = 0;
+      return () => { now += 1; return now; };
+    })(),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, 'owner_process_missing');
+});
+
+test('waitForExpoMetroRunning fails promptly when the watched owner exits before HTTP readiness', async () => {
+  const ownerProc = new EventEmitter();
+  ownerProc.exitCode = null;
+  ownerProc.signalCode = null;
+  const pending = waitForExpoMetroRunning({
+    port: 8081,
+    ownerPid: 100,
+    ownerProc,
+    timeoutMs: 120_000,
+  }, {
+    looksLikeExpoMetroImpl: async () => await new Promise(() => {}),
+  });
+  queueMicrotask(() => ownerProc.emit('exit', 1, null));
+  const result = await pending;
+  assert.deepEqual(result, { ok: false, reason: 'owner_process_exited', probes: 0 });
+});
+
+test('waitForExpoMetroRunning certifies a Windows wrapper descendant listener', async () => {
+  const result = await waitForExpoMetroRunning({ port: 8081, ownerPid: 100 }, {
+    platform: 'win32',
+    looksLikeExpoMetroImpl: async () => true,
+    listListenPidsWithStatusImpl: async () => ({ status: 'ok', pids: [200] }),
+    isWindowsDescendantProcessImpl: async (listenerPid, ownerPid) => listenerPid === 200 && ownerPid === 100,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.ownerPid, 100);
+  assert.equal(result.listenerPid, 200);
+});
+
+test('waitForExpoMetroRunning rejects mixed owned and foreign listeners without naming the foreign PID', async () => {
+  const result = await waitForExpoMetroRunning({
+    port: 8081,
+    ownerPid: 100,
+    timeoutMs: 1,
+    intervalMs: 1,
+  }, {
+    looksLikeExpoMetroImpl: async () => true,
+    listListenPidsWithStatusImpl: async () => ({ status: 'ok', pids: [200, 100] }),
+    getProcessGroupIdImpl: async (pid) => pid,
+    delayImpl: async () => {},
+    nowMsImpl: (() => { let now = 0; return () => { now += 1; return now; }; })(),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, 'competing_listener');
+  assert.deepEqual(result.listenerPids, [200, 100]);
+  assert.equal('listenerPid' in result, false);
+});
+
+test('waitForExpoMetroRunning rejects a real owned-wildcard plus foreign-specific listener attack', { skip: process.platform !== 'darwin' }, async (t) => {
+  const owned = createServer((_req, res) => res.end('packager-status:running'));
+  await new Promise((resolve, reject) => {
+    owned.once('error', reject);
+    owned.listen(0, undefined, resolve);
+  });
+  const address = owned.address();
+  const port = typeof address === 'object' && address ? address.port : null;
+  assert.ok(port);
+  const source = `const http=require('node:http');const s=http.createServer((q,r)=>r.end('packager-status:running'));s.once('error',e=>{console.log('error:'+e.code);process.exit(0)});s.listen(${port},'127.0.0.1',()=>console.log('ready'));`;
+  const foreign = spawn(process.execPath, ['-e', source], { detached: true, stdio: ['ignore', 'pipe', 'ignore'] });
+  try {
+    const line = await new Promise((resolve) => foreign.stdout.once('data', (chunk) => resolve(String(chunk).trim())));
+    if (line !== 'ready') {
+      t.skip(`specific-listener coexistence unavailable: ${line}`);
+      return;
+    }
+    const result = await waitForExpoMetroRunning({ port, ownerPid: process.pid, timeoutMs: 2000, intervalMs: 25 });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'competing_listener');
+    assert.ok(result.ownedListenerPids.includes(process.pid));
+    assert.ok(result.foreignListenerPids.includes(foreign.pid));
+  } finally {
+    try { process.kill(-foreign.pid, 'SIGKILL'); } catch {}
+    await new Promise((resolve) => owned.close(resolve));
+  }
+});

package/scripts/utils/expo/metro_ports.mjs

@@ -1,4 +1,10 @@
-import { isTcpPortListening, listListenPids, pickNextFreeTcpPort } from '../net/ports.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { isTcpPortListening, listListenPids, listListenPidsWithStatus, pickNextFreeTcpPort, probeTcpPortBinding } from '../net/ports.mjs';
+
+const DEFAULT_METRO_LISTENER_OBSERVATION_TIMEOUT_MS = 5_000;
+const DEFAULT_METRO_BINDING_OBSERVATION_TIMEOUT_MS = 1_000;
+const DEFAULT_STABLE_METRO_PORT_ADMISSION_TIMEOUT_MS = 30_000;
+const DEFAULT_STABLE_METRO_PORT_RETRY_DELAY_MS = 250;
 
 function hashStringToInt(s) {
   let h = 0;
@@ -50,6 +56,71 @@ export async function pickMetroPort({
   return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
 }
 
+export async function observeMetroPortAvailability(
+  port,
+  {
+    host = '127.0.0.1',
+    allowBindOnly = false,
+    env = process.env,
+    listenerTimeoutMs = DEFAULT_METRO_LISTENER_OBSERVATION_TIMEOUT_MS,
+    bindingTimeoutMs = DEFAULT_METRO_BINDING_OBSERVATION_TIMEOUT_MS,
+  } = {},
+  {
+    listListenPidsWithStatusImpl = listListenPidsWithStatus,
+    probeTcpPortBindingImpl = probeTcpPortBinding,
+  } = {},
+) {
+  const listeners = await listListenPidsWithStatusImpl(port, { timeoutMs: listenerTimeoutMs, env });
+  if (listeners.status !== 'ok' && !(allowBindOnly && listeners.status === 'unsupported')) {
+    return { status: 'inconclusive', reason: listeners.reason ?? listeners.status };
+  }
+  if (listeners.pids.length) return { status: 'occupied', reason: 'listener-present', pids: [...listeners.pids] };
+  const binding = await probeTcpPortBindingImpl(port, { host, timeoutMs: bindingTimeoutMs });
+  if (binding.status === 'free') return { status: 'free' };
+  if (binding.status === 'in_use') return { status: 'occupied', reason: binding.reason };
+  return { status: 'inconclusive', reason: binding.reason ?? binding.status };
+}
+
+function isRetryableMetroPortObservation(observation) {
+  const reason = String(observation?.reason ?? '').trim();
+  return reason === 'listener-discovery-timeout'
+    || reason === 'listener-discovery-error'
+    || reason === 'port-bind-timeout';
+}
+
+async function observeStableMetroPortUntilConclusive({
+  port,
+  host,
+  env,
+  timeoutMs,
+  retryDelayMs,
+  observePortImpl,
+  nowImpl,
+  delayImpl,
+}) {
+  const deadline = nowImpl() + timeoutMs;
+  let observation = { status: 'inconclusive', reason: 'stable-port-admission-timeout' };
+  while (nowImpl() < deadline) {
+    const remainingMs = Math.max(1, deadline - nowImpl());
+    // eslint-disable-next-line no-await-in-loop
+    observation = await observePortImpl(port, {
+      host,
+      allowBindOnly: false,
+      env,
+      listenerTimeoutMs: Math.min(DEFAULT_METRO_LISTENER_OBSERVATION_TIMEOUT_MS, remainingMs),
+      bindingTimeoutMs: Math.min(DEFAULT_METRO_BINDING_OBSERVATION_TIMEOUT_MS, remainingMs),
+    });
+    if (observation.status !== 'inconclusive') return observation;
+    if (!isRetryableMetroPortObservation(observation)) return observation;
+
+    const waitMs = Math.min(retryDelayMs, Math.max(0, deadline - nowImpl()));
+    if (waitMs <= 0) break;
+    // eslint-disable-next-line no-await-in-loop
+    await delayImpl(waitMs);
+  }
+  return observation;
+}
+
 export function wantsStablePortStrategy({ env = process.env, strategyKey, legacyStrategyKey } = {}) {
   void legacyStrategyKey;
   const raw = (env[strategyKey] ?? 'ephemeral').toString().trim() || 'ephemeral';
@@ -106,3 +177,91 @@ export async function pickExpoDevMetroPort({
 
   return await pickMetroPort({ startPort, forcedPort, reservedPorts, host });
 }
+
+export async function selectExpoDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+  tries = 200,
+  observePortImpl = observeMetroPortAvailability,
+  onStableOccupied = null,
+  stableObservationTimeoutMs = DEFAULT_STABLE_METRO_PORT_ADMISSION_TIMEOUT_MS,
+  stableObservationRetryDelayMs = DEFAULT_STABLE_METRO_PORT_RETRY_DELAY_MS,
+  nowImpl = Date.now,
+  delayImpl = delay,
+} = {}) {
+  const forcedPort = (env.HAPPIER_STACK_EXPO_DEV_PORT ?? '').toString().trim() || '';
+  const stable = stackMode && wantsStablePortStrategy({ env, strategyKey: 'HAPPIER_STACK_EXPO_DEV_PORT_STRATEGY' });
+  const startPort = stable
+    ? resolveStablePortStart({
+        env,
+        stackName,
+        baseKey: 'HAPPIER_STACK_EXPO_DEV_PORT_BASE',
+        rangeKey: 'HAPPIER_STACK_EXPO_DEV_PORT_RANGE',
+        defaultBase: 8081,
+        defaultRange: 1000,
+      })
+    : 8081;
+  const forced = coercePositiveInt(forcedPort);
+  if (stable && forced && reservedPorts.has(forced)) {
+    const error = new Error(`[expo] stable expo port ${forced} is reserved by another stack service`);
+    error.code = 'EEXPOPORTOCCUPIED';
+    error.observation = { status: 'occupied', reason: 'reserved' };
+    throw error;
+  }
+  const observeStablePort = (port) => observeStableMetroPortUntilConclusive({
+    port,
+    host,
+    env,
+    timeoutMs: coercePositiveInt(stableObservationTimeoutMs) ?? DEFAULT_STABLE_METRO_PORT_ADMISSION_TIMEOUT_MS,
+    retryDelayMs: coercePositiveInt(stableObservationRetryDelayMs) ?? DEFAULT_STABLE_METRO_PORT_RETRY_DELAY_MS,
+    observePortImpl,
+    nowImpl,
+    delayImpl,
+  });
+  if (forced && !reservedPorts.has(forced)) {
+    const observeForcedPort = stable
+      ? () => observeStablePort(forced)
+      : () => observePortImpl(forced, { host, allowBindOnly: false, env });
+    let observation = await observeForcedPort();
+    if (stable && observation.status === 'occupied' && typeof onStableOccupied === 'function') {
+      await onStableOccupied({ port: forced, observation });
+      observation = await observeForcedPort();
+    }
+    if (observation.status === 'free') return { port: forced, persistPin: false, preferredStatus: 'free' };
+    if (stable) {
+      const error = new Error(
+        observation.status === 'occupied'
+          ? `[expo] stable expo port ${forced} is already occupied`
+          : `[expo] stable expo port ${forced} availability is inconclusive: ${observation.reason ?? 'unknown'}`
+      );
+      error.code = observation.status === 'occupied' ? 'EEXPOPORTOCCUPIED' : 'EEXPOPORTINCONCLUSIVE';
+      error.observation = observation;
+      throw error;
+    }
+  }
+  for (let offset = 0; offset < tries; offset += 1) {
+    const port = startPort + offset;
+    if (reservedPorts.has(port) || port === forced) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const observation = stable
+      ? await observeStablePort(port)
+      : await observePortImpl(port, { host, allowBindOnly: true, env });
+    if (observation.status === 'free') {
+      return { port, persistPin: stable && !forced, preferredStatus: forced ? 'unavailable' : 'unset' };
+    }
+    if (stable && observation.status === 'inconclusive') {
+      const error = new Error(
+        `[expo] stable expo port ${port} availability is inconclusive: ${observation.reason ?? 'unknown'}`,
+      );
+      error.code = 'EEXPOPORTINCONCLUSIVE';
+      error.observation = observation;
+      throw error;
+    }
+  }
+  const error = new Error(`[expo] unable to establish a conclusively free Metro port starting at ${startPort}`);
+  error.code = 'EEXPOPORTUNAVAILABLE';
+  throw error;
+}