happy-stacks 0.2.0 → 0.4.0

package/scripts/utils/dev/expo_dev.mjs

@@ -0,0 +1,246 @@
+import {
+  ensureExpoIsolationEnv,
+  getExpoStatePaths,
+  isStateProcessRunning,
+  wantsExpoClearCache,
+  writePidState,
+} from '../expo/expo.mjs';
+import { pickExpoDevMetroPort } from '../expo/metro_ports.mjs';
+import { recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
+import { expoSpawn } from '../expo/command.mjs';
+import { resolveMobileExpoConfig } from '../mobile/config.mjs';
+import { resolveMobileReachableServerUrl } from '../server/mobile_api_url.mjs';
+
+function normalizeExpoHost(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (v === 'localhost' || v === 'lan' || v === 'tunnel') return v;
+  return 'lan';
+}
+
+export function resolveExpoDevHost({ env = process.env } = {}) {
+  // Always prefer LAN by default so phones can reach Metro.
+  const raw = (env.HAPPY_STACKS_EXPO_HOST ?? env.HAPPY_LOCAL_EXPO_HOST ?? '').toString();
+  return normalizeExpoHost(raw || 'lan');
+}
+
+export function buildExpoStartArgs({ port, host, wantWeb, wantDevClient, scheme, clearCache }) {
+  const metroPort = Number(port);
+  if (!Number.isFinite(metroPort) || metroPort <= 0) {
+    throw new Error(`[expo] invalid Metro port: ${String(port)}`);
+  }
+  if (!wantWeb && !wantDevClient) {
+    throw new Error('[expo] cannot build Expo args: neither web nor dev-client requested');
+  }
+
+  // IMPORTANT:
+  // - We must only run one Expo per stack.
+  // - Expo dev-client mode is known to still serve web when accessed locally, so when mobile is
+  //   requested we prefer `--dev-client` as the single shared process (no second `--web` process).
+  const args = wantDevClient
+    ? ['start', '--dev-client', '--host', host, '--port', String(metroPort)]
+    : ['start', '--web', '--host', host, '--port', String(metroPort)];
+
+  if (wantDevClient) {
+    const s = String(scheme ?? '').trim();
+    if (s) {
+      args.push('--scheme', s);
+    }
+  }
+
+  if (clearCache && !args.includes('--clear')) {
+    args.push('--clear');
+  }
+
+  return args;
+}
+
+function expoModeLabel({ wantWeb, wantDevClient }) {
+  if (wantWeb && wantDevClient) return 'dev-client+web';
+  if (wantDevClient) return 'dev-client';
+  if (wantWeb) return 'web';
+  return 'disabled';
+}
+
+export async function ensureDevExpoServer({
+  startUi,
+  startMobile,
+  uiDir,
+  autostart,
+  baseEnv,
+  apiServerUrl,
+  restart,
+  stackMode,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  spawnOptions = {},
+} = {}) {
+  const wantWeb = Boolean(startUi);
+  const wantDevClient = Boolean(startMobile);
+  if (!wantWeb && !wantDevClient) {
+    return { ok: true, skipped: true, reason: 'disabled' };
+  }
+
+  const env = { ...(baseEnv || process.env) };
+  delete env.CI;
+  // Expo app config: this is what both web + native app use to reach the Happy server.
+  // When dev-client is enabled, `localhost` / `*.localhost` are not reachable from the phone,
+  // so rewrite to LAN IP here (centralized) to avoid relying on call sites.
+  const serverPortFromEnvRaw = (env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT ?? '').toString().trim();
+  const serverPortFromEnv = serverPortFromEnvRaw ? Number(serverPortFromEnvRaw) : null;
+  const effectiveApiServerUrl = wantDevClient
+    ? resolveMobileReachableServerUrl({
+        env,
+        serverUrl: apiServerUrl,
+        serverPort: Number.isFinite(serverPortFromEnv) ? serverPortFromEnv : null,
+      })
+    : apiServerUrl;
+  env.EXPO_PUBLIC_HAPPY_SERVER_URL = effectiveApiServerUrl;
+  env.EXPO_PUBLIC_DEBUG = env.EXPO_PUBLIC_DEBUG ?? '1';
+
+  // Optional: allow per-stack storage isolation inside a single dev-client build by
+  // scoping app persistence (MMKV / SecureStore) to a stack-specific namespace.
+  //
+  // This stays upstream-safe because the app behavior is unchanged unless the Expo public
+  // env var is explicitly set. Happy Stacks sets it automatically for stack-mode dev-client.
+  if (wantDevClient) {
+    const explicitScope = (
+      env.HAPPY_STACKS_STORAGE_SCOPE ??
+      env.HAPPY_LOCAL_STORAGE_SCOPE ??
+      env.EXPO_PUBLIC_HAPPY_STORAGE_SCOPE ??
+      ''
+    )
+      .toString()
+      .trim();
+    const defaultScope = stackMode && stackName ? String(stackName).trim() : '';
+    const scope = explicitScope || defaultScope;
+    if (scope && !env.EXPO_PUBLIC_HAPPY_STORAGE_SCOPE) {
+      env.EXPO_PUBLIC_HAPPY_STORAGE_SCOPE = scope;
+    }
+  }
+
+  // We own the browser opening behavior in Happy Stacks so we can reliably open the correct origin.
+  env.EXPO_NO_BROWSER = '1';
+  env.BROWSER = 'none';
+
+  // Mobile config is needed for `--scheme` and for the app's environment.
+  let scheme = '';
+  if (wantDevClient) {
+    const cfg = resolveMobileExpoConfig({ env });
+    env.APP_ENV = cfg.appEnv;
+    scheme = cfg.scheme;
+  }
+
+  const paths = getExpoStatePaths({
+    baseDir: autostart.baseDir,
+    kind: 'expo-dev',
+    projectDir: uiDir,
+    stateFileName: 'expo.state.json',
+  });
+  await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+
+  const running = await isStateProcessRunning(paths.statePath);
+  const alreadyRunning = Boolean(running.running);
+
+  // Always publish runtime metadata when we can.
+  const publishRuntime = async ({ pid, port }) => {
+    if (!stackMode || !runtimeStatePath) return;
+    const nPid = Number(pid);
+    const nPort = Number(port);
+    await recordStackRuntimeUpdate(runtimeStatePath, {
+      processes: { expoPid: Number.isFinite(nPid) && nPid > 1 ? nPid : null },
+      expo: {
+        port: Number.isFinite(nPort) && nPort > 0 ? nPort : null,
+        // For now keep these populated for callers that still expect webPort/mobilePort.
+        webPort: wantWeb && Number.isFinite(nPort) && nPort > 0 ? nPort : null,
+        mobilePort: wantDevClient && Number.isFinite(nPort) && nPort > 0 ? nPort : null,
+        webEnabled: wantWeb,
+        devClientEnabled: wantDevClient,
+        host: resolveExpoDevHost({ env }),
+        scheme: wantDevClient ? scheme : null,
+      },
+    }).catch(() => {});
+  };
+
+  if (alreadyRunning && !restart) {
+    const pid = Number(running.state?.pid);
+    const port = Number(running.state?.port);
+
+    // Capability check: refuse to spawn a second Expo, so if the existing process doesn't match the
+    // requested capabilities we fail closed and instruct a restart with the superset.
+    const stateWeb = Boolean(running.state?.webEnabled);
+    const stateDevClient = Boolean(running.state?.devClientEnabled);
+    const stateHasCaps = 'webEnabled' in (running.state ?? {}) || 'devClientEnabled' in (running.state ?? {});
+    const missingWeb = wantWeb && stateHasCaps && !stateWeb;
+    const missingDevClient = wantDevClient && stateHasCaps && !stateDevClient;
+    if (missingWeb || missingDevClient) {
+      throw new Error(
+        `[expo] Expo already running for stack=${stackName}, but it does not match the requested mode.\n` +
+          `- running: ${expoModeLabel({ wantWeb: stateWeb, wantDevClient: stateDevClient })}\n` +
+          `- wanted:  ${expoModeLabel({ wantWeb, wantDevClient })}\n` +
+          `Fix: re-run with --restart (and include --mobile if you need dev-client).`
+      );
+    }
+
+    await publishRuntime({ pid, port });
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'already_running',
+      pid: Number.isFinite(pid) ? pid : null,
+      port: Number.isFinite(port) ? port : null,
+      mode: expoModeLabel({ wantWeb, wantDevClient }),
+    };
+  }
+
+  const metroPort = await pickExpoDevMetroPort({ env: baseEnv, stackMode, stackName });
+  env.RCT_METRO_PORT = String(metroPort);
+  const host = resolveExpoDevHost({ env });
+  const args = buildExpoStartArgs({
+    port: metroPort,
+    host,
+    wantWeb,
+    wantDevClient,
+    scheme,
+    clearCache: wantsExpoClearCache({ env: baseEnv || process.env }),
+  });
+
+  if (restart && running.state?.pid) {
+    const prevPid = Number(running.state.pid);
+    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo', json: true });
+    if (!res.killed) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[local] expo: not stopping existing Expo pid=${prevPid} because it does not look stack-owned.\n` +
+          `[local] expo: continuing by starting a new Expo process on a free port.`
+      );
+    }
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] expo: starting Expo (${expoModeLabel({ wantWeb, wantDevClient })}, metro port=${metroPort}, host=${host})`);
+  const proc = await expoSpawn({ label: 'expo', dir: uiDir, args, env, options: spawnOptions });
+  children.push(proc);
+
+  await publishRuntime({ pid: proc.pid, port: metroPort });
+
+  try {
+    await writePidState(paths.statePath, {
+      pid: proc.pid,
+      port: metroPort,
+      uiDir,
+      startedAt: new Date().toISOString(),
+      webEnabled: wantWeb,
+      devClientEnabled: wantDevClient,
+      host,
+      scheme: wantDevClient ? scheme : null,
+    });
+  } catch {
+    // ignore
+  }
+
+  return { ok: true, skipped: false, pid: proc.pid, port: metroPort, proc, mode: expoModeLabel({ wantWeb, wantDevClient }) };
+}
+

package/scripts/utils/dev/expo_dev.test.mjs

@@ -0,0 +1,76 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildExpoStartArgs, resolveExpoDevHost } from './expo_dev.mjs';
+
+test('resolveExpoDevHost defaults to lan and normalizes values', () => {
+  assert.equal(resolveExpoDevHost({ env: {} }), 'lan');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'LAN' } }), 'lan');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'localhost' } }), 'localhost');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'tunnel' } }), 'tunnel');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'nope' } }), 'lan');
+});
+
+test('buildExpoStartArgs builds dev-client args (preferred when mobile enabled)', () => {
+  const args = buildExpoStartArgs({
+    port: 8081,
+    host: 'lan',
+    wantWeb: true,
+    wantDevClient: true,
+    scheme: 'happy',
+    clearCache: true,
+  });
+  assert.deepEqual(args, ['start', '--dev-client', '--host', 'lan', '--port', '8081', '--scheme', 'happy', '--clear']);
+});
+
+test('buildExpoStartArgs builds web args when dev-client is not requested', () => {
+  const args = buildExpoStartArgs({
+    port: 8081,
+    host: 'lan',
+    wantWeb: true,
+    wantDevClient: false,
+    scheme: '',
+    clearCache: false,
+  });
+  assert.deepEqual(args, ['start', '--web', '--host', 'lan', '--port', '8081']);
+});
+
+test('buildExpoStartArgs omits --scheme when empty', () => {
+  const args = buildExpoStartArgs({
+    port: 8081,
+    host: 'lan',
+    wantWeb: false,
+    wantDevClient: true,
+    scheme: '',
+    clearCache: false,
+  });
+  assert.deepEqual(args, ['start', '--dev-client', '--host', 'lan', '--port', '8081']);
+});
+
+test('buildExpoStartArgs throws on invalid requests', () => {
+  assert.throws(
+    () =>
+      buildExpoStartArgs({
+        port: 0,
+        host: 'lan',
+        wantWeb: true,
+        wantDevClient: false,
+        scheme: '',
+        clearCache: false,
+      }),
+    /invalid Metro port/i
+  );
+  assert.throws(
+    () =>
+      buildExpoStartArgs({
+        port: 8081,
+        host: 'lan',
+        wantWeb: false,
+        wantDevClient: false,
+        scheme: '',
+        clearCache: false,
+      }),
+    /neither web nor dev-client requested/i
+  );
+});
+

package/scripts/utils/{dev_server.mjs → dev/server.mjs}

@@ -1,42 +1,32 @@
 import { join, resolve } from 'node:path';
 
-import { ensureDepsInstalled, pmSpawnScript } from './pm.mjs';
-import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './happy_server_infra.mjs';
-import { waitForServerReady } from './server.mjs';
-import { isTcpPortFree, pickNextFreeTcpPort } from './ports.mjs';
-import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from './stack_runtime_state.mjs';
-import { killProcessGroupOwnedByStack } from './ownership.mjs';
-import { watchDebounced } from './watch.mjs';
-
-function hashStringToInt(s) {
-  let h = 0;
-  const str = String(s ?? '');
-  for (let i = 0; i < str.length; i++) {
-    h = (h * 31 + str.charCodeAt(i)) >>> 0;
-  }
-  return h >>> 0;
-}
+import { ensureDepsInstalled, pmSpawnScript } from '../proc/pm.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
+import { waitForServerReady } from '../server/server.mjs';
+import { isTcpPortFree, pickNextFreeTcpPort } from '../net/ports.mjs';
+import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
+import { watchDebounced } from '../proc/watch.mjs';
+import { pickMetroPort, resolveStablePortStart } from '../expo/metro_ports.mjs';
 
 export function resolveStackUiDevPortStart({ env = process.env, stackName }) {
-  const baseRaw = (env.HAPPY_STACKS_UI_DEV_PORT_BASE ?? env.HAPPY_LOCAL_UI_DEV_PORT_BASE ?? '8081').toString().trim();
-  const rangeRaw = (env.HAPPY_STACKS_UI_DEV_PORT_RANGE ?? env.HAPPY_LOCAL_UI_DEV_PORT_RANGE ?? '1000').toString().trim();
-  const base = Number(baseRaw);
-  const range = Number(rangeRaw);
-  const b = Number.isFinite(base) ? base : 8081;
-  const r = Number.isFinite(range) && range > 0 ? range : 1000;
-  return b + (hashStringToInt(stackName) % r);
+  return resolveStablePortStart({
+    env: {
+      ...env,
+      HAPPY_STACKS_UI_DEV_PORT_BASE: (env.HAPPY_STACKS_UI_DEV_PORT_BASE ?? env.HAPPY_LOCAL_UI_DEV_PORT_BASE ?? '8081').toString(),
+      HAPPY_STACKS_UI_DEV_PORT_RANGE: (env.HAPPY_STACKS_UI_DEV_PORT_RANGE ?? env.HAPPY_LOCAL_UI_DEV_PORT_RANGE ?? '1000').toString(),
+    },
+    stackName,
+    baseKey: 'HAPPY_STACKS_UI_DEV_PORT_BASE',
+    rangeKey: 'HAPPY_STACKS_UI_DEV_PORT_RANGE',
+    defaultBase: 8081,
+    defaultRange: 1000,
+  });
 }
 
 export async function pickDevMetroPort({ startPort, reservedPorts = new Set(), host = '127.0.0.1' } = {}) {
-  const forcedRaw = (process.env.HAPPY_STACKS_UI_DEV_PORT ?? process.env.HAPPY_LOCAL_UI_DEV_PORT ?? '').toString().trim();
-  if (forcedRaw) {
-    const forced = Number(forcedRaw);
-    if (Number.isFinite(forced) && forced > 0) {
-      const ok = await isTcpPortFree(forced, { host });
-      if (ok) return forced;
-    }
-  }
-  return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
+  const forcedPort = (process.env.HAPPY_STACKS_UI_DEV_PORT ?? process.env.HAPPY_LOCAL_UI_DEV_PORT ?? '').toString().trim();
+  return await pickMetroPort({ startPort, forcedPort, reservedPorts, host });
 }
 
 export async function startDevServer({

package/scripts/utils/dev_auth_key.mjs

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
-import { expandHome } from './canonical_home.mjs';
+import { expandHome } from './paths/canonical_home.mjs';
 
 export function resolveHappyStacksHomeDir(env = process.env) {
   const fromEnv = (env.HAPPY_STACKS_HOME_DIR ?? env.HAPPY_LOCAL_HOME_DIR ?? '').toString().trim();

package/scripts/utils/{config.mjs → env/config.mjs}

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { ensureEnvFileUpdated } from './env_file.mjs';
-import { getHappyStacksHomeDir, resolveStackEnvPath } from './paths.mjs';
-import { getCanonicalHomeDirFromEnv } from './canonical_home.mjs';
+import { getHappyStacksHomeDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getCanonicalHomeDirFromEnv } from '../paths/canonical_home.mjs';
 
 export function getHomeEnvPath() {
   return join(getHappyStacksHomeDir(), '.env');
@@ -50,3 +50,4 @@ export async function ensureUserConfigEnvUpdated({ cliRootDir, updates }) {
   await ensureEnvFileUpdated({ envPath, updates });
   return envPath;
 }
+

package/scripts/utils/{dotenv.mjs → env/dotenv.mjs}

@@ -28,3 +28,6 @@ export function parseDotenv(contents) {
   return out;
 }
 
+export function parseEnvToObject(contents) {
+  return Object.fromEntries(parseDotenv(contents));
+}

package/scripts/utils/{env.mjs → env/env.mjs}

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDotenv } from './dotenv.mjs';
-import { expandHome, getCanonicalHomeEnvPathFromEnv } from './canonical_home.mjs';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../paths/canonical_home.mjs';
 import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
 
 async function loadEnvFile(path, { override = false, overridePrefix = null } = {}) {
@@ -57,8 +57,9 @@ async function loadEnvFileIgnoringPrefixes(path, { ignorePrefixes = [] } = {}) {
 }
 
 // Load happy-stacks env (optional). This is intentionally lightweight and does not require extra deps.
-// This file lives under scripts/utils/, so repo root is two directories up.
-const __utilsDir = dirname(fileURLToPath(import.meta.url));
+// This file lives under scripts/utils/env, so repo root is three directories up.
+const __envDir = dirname(fileURLToPath(import.meta.url));
+const __utilsDir = dirname(__envDir);
 const __scriptsDir = dirname(__utilsDir);
 const __cliRootDir = dirname(__scriptsDir);
 
@@ -207,3 +208,4 @@ process.env.NPM_CONFIG_PACKAGE_MANAGER_STRICT = process.env.NPM_CONFIG_PACKAGE_M
   const next = [...want.filter((p) => p && !current.includes(p)), ...current];
   process.env.PATH = next.join(delimiter);
 })();
+

package/scripts/utils/{env_file.mjs → env/env_file.mjs}

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { pathExists } from './fs.mjs';
+import { pathExists } from '../fs/fs.mjs';
 
 export async function ensureEnvFileUpdated({ envPath, updates }) {
   if (!updates.length) {
@@ -93,3 +93,4 @@ async function writeFileIfChanged(existingContent, nextContent, path) {
   }
   await writeFile(path, normalizedNext, 'utf-8');
 }
+

package/scripts/utils/{env_local.mjs → env/env_local.mjs}

@@ -23,3 +23,4 @@ export async function ensureEnvLocalUpdated({ rootDir, updates }) {
 
   await ensureEnvFileUpdated({ envPath: join(rootDir, 'env.local'), updates });
 }
+

package/scripts/utils/env/read.mjs

@@ -0,0 +1,30 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+
+import { parseDotenv } from './dotenv.mjs';
+
+export async function readEnvValueFromFile(envPath, key, { defaultValue = '' } = {}) {
+  try {
+    const p = String(envPath ?? '').trim();
+    const k = String(key ?? '').trim();
+    if (!p || !k) return defaultValue;
+    if (!existsSync(p)) return defaultValue;
+    const raw = await readFile(p, 'utf-8');
+    const parsed = parseDotenv(raw ?? '');
+    return String(parsed.get(k) ?? '').trim();
+  } catch {
+    return defaultValue;
+  }
+}
+
+export async function readEnvObjectFromFile(envPath) {
+  try {
+    const p = String(envPath ?? '').trim();
+    if (!p || !existsSync(p)) return {};
+    const raw = await readFile(p, 'utf-8');
+    return Object.fromEntries(parseDotenv(raw ?? '').entries());
+  } catch {
+    return {};
+  }
+}
+

package/scripts/utils/env/values.mjs

@@ -0,0 +1,13 @@
+export function getEnvValue(obj, key) {
+  const v = (obj?.[key] ?? '').toString().trim();
+  return v || '';
+}
+
+export function getEnvValueAny(obj, keys) {
+  for (const k of keys) {
+    const v = getEnvValue(obj, k);
+    if (v) return v;
+  }
+  return '';
+}
+

package/scripts/utils/expo/command.mjs

@@ -0,0 +1,52 @@
+import { ensureDepsInstalled, pmExecBin, pmSpawnBin } from '../proc/pm.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, wantsExpoClearCache } from './expo.mjs';
+
+export async function prepareExpoCommandEnv({
+  baseDir,
+  kind,
+  projectDir,
+  baseEnv,
+  stateFileName,
+}) {
+  const env = { ...(baseEnv ?? process.env) };
+  const paths = getExpoStatePaths({ baseDir, kind, projectDir, stateFileName });
+  await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+  return { env, paths };
+}
+
+export function maybeAddExpoClear({ args, env }) {
+  const next = [...(args ?? [])];
+  if (wantsExpoClearCache({ env: env ?? process.env })) {
+    // Expo supports `--clear` for start, and `-c` for export.
+    // Callers should pass the right flag for their subcommand; we only add when missing.
+    if (!next.includes('--clear') && !next.includes('-c')) {
+      // Prefer `--clear` as a safe default; callers can override per-command.
+      next.push('--clear');
+    }
+  }
+  return next;
+}
+
+export async function expoExec({
+  dir,
+  args,
+  env,
+  ensureDepsLabel = 'happy',
+  quiet = false,
+}) {
+  await ensureDepsInstalled(dir, ensureDepsLabel, { quiet });
+  await pmExecBin({ dir, bin: 'expo', args, env, quiet });
+}
+
+export async function expoSpawn({
+  label,
+  dir,
+  args,
+  env,
+  ensureDepsLabel = 'happy',
+  options,
+}) {
+  await ensureDepsInstalled(dir, ensureDepsLabel);
+  return await pmSpawnBin({ label, dir, bin: 'expo', args, env, options });
+}
+

package/scripts/utils/{expo.mjs → expo/expo.mjs}

@@ -3,6 +3,10 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
+import { isPidAlive } from '../proc/pids.mjs';
+import { isTcpPortFree } from '../net/ports.mjs';
+
+export { isPidAlive };
 
 function hashDir(dir) {
   return createHash('sha1').update(String(dir ?? '')).digest('hex').slice(0, 12);
@@ -56,20 +60,29 @@ export async function readPidState(statePath) {
   }
 }
 
-export function isPidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export async function isStateProcessRunning(statePath) {
   const state = await readPidState(statePath);
   if (!state) return { running: false, state: null };
   const pid = Number(state.pid);
-  return { running: isPidAlive(pid), state };
+  if (isPidAlive(pid)) {
+    return { running: true, state, reason: 'pid' };
+  }
+
+  // Expo/Metro can sometimes be “up” even if the original wrapper pid exited (pm/yarn layers).
+  // If we have a port and something is listening on it, treat it as running.
+  const port = Number(state?.port);
+  if (Number.isFinite(port) && port > 0) {
+    try {
+      const free = await isTcpPortFree(port, { host: '127.0.0.1' });
+      if (!free) {
+        return { running: true, state, reason: 'port' };
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return { running: false, state };
 }
 
 export async function writePidState(statePath, state) {