happy-stacks 0.3.0 → 0.5.0

package/scripts/utils/dev/server.mjs

@@ -2,41 +2,32 @@ import { join, resolve } from 'node:path';
 
 import { ensureDepsInstalled, pmSpawnScript } from '../proc/pm.mjs';
 import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
+import { resolveServerDevScript } from '../server/flavor_scripts.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';
-
-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 { 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({
@@ -97,12 +88,7 @@ export async function startDevServer({
   await ensureDepsInstalled(serverDir, serverComponentName);
 
   const prismaPush = (baseEnv.HAPPY_STACKS_PRISMA_PUSH ?? baseEnv.HAPPY_LOCAL_PRISMA_PUSH ?? '1').toString().trim() !== '0';
-  const serverScript =
-    serverComponentName === 'happy-server'
-      ? 'start'
-      : serverComponentName === 'happy-server-light' && !prismaPush
-        ? 'start'
-        : 'dev';
+  const serverScript = resolveServerDevScript({ serverComponentName, serverDir, prismaPush });
 
   // Restart behavior (stack-safe): only kill when we can prove ownership via runtime state.
   if (restart && stackMode && runtimeStatePath && serverAlreadyRunning) {
@@ -165,19 +151,27 @@ export function watchDevServerAndRestart({
       const pid = Number(serverProcRef?.current?.pid);
       if (!Number.isFinite(pid) || pid <= 1) return;
 
-      // eslint-disable-next-line no-console
-      console.log('[local] watch: server changed → restarting...');
-      await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: 'server', json: false });
+      try {
+        // eslint-disable-next-line no-console
+        console.log('[local] watch: server changed → restarting...');
+        await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: 'server', json: false });
 
-      const next = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
-      children.push(next);
-      serverProcRef.current = next;
-      if (stackMode && runtimeStatePath) {
-        await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: next.pid } }).catch(() => {});
+        const next = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
+        children.push(next);
+        serverProcRef.current = next;
+        if (stackMode && runtimeStatePath) {
+          await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: next.pid } }).catch(() => {});
+        }
+        await waitForServerReady(internalServerUrl);
+        // eslint-disable-next-line no-console
+        console.log(`[local] watch: server restarted (pid=${next.pid}, port=${serverPort})`);
+      } catch (e) {
+        const msg = e instanceof Error ? e.stack || e.message : String(e);
+        // eslint-disable-next-line no-console
+        console.error('[local] watch: server restart failed; keeping existing process as-is (will retry on next change).');
+        // eslint-disable-next-line no-console
+        console.error(msg);
       }
-      await waitForServerReady(internalServerUrl);
-      // eslint-disable-next-line no-console
-      console.log(`[local] watch: server restarted (pid=${next.pid}, port=${serverPort})`);
     },
   });
 }

package/scripts/utils/dev_auth_key.mjs

@@ -0,0 +1,169 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+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();
+  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happy-stacks');
+}
+
+export function getDevAuthKeyPath(env = process.env) {
+  return join(resolveHappyStacksHomeDir(env), 'keys', 'dev-auth.json');
+}
+
+function base64UrlToBytes(s) {
+  try {
+    const raw = String(s ?? '').trim();
+    if (!raw) return null;
+    const b64 = raw.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+    return new Uint8Array(Buffer.from(b64 + pad, 'base64'));
+  } catch {
+    return null;
+  }
+}
+
+function bytesToBase64Url(bytes) {
+  const b64 = Buffer.from(bytes).toString('base64');
+  return b64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+// Base32 alphabet (RFC 4648)
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+function bytesToBase32(bytes) {
+  let result = '';
+  let buffer = 0;
+  let bufferLength = 0;
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bufferLength += 8;
+    while (bufferLength >= 5) {
+      bufferLength -= 5;
+      result += BASE32_ALPHABET[(buffer >> bufferLength) & 0x1f];
+    }
+  }
+  if (bufferLength > 0) {
+    result += BASE32_ALPHABET[(buffer << (5 - bufferLength)) & 0x1f];
+  }
+  return result;
+}
+
+function base32ToBytes(base32) {
+  let normalized = String(base32 ?? '')
+    .toUpperCase()
+    .replace(/0/g, 'O')
+    .replace(/1/g, 'I')
+    .replace(/8/g, 'B')
+    .replace(/9/g, 'G');
+  const cleaned = normalized.replace(/[^A-Z2-7]/g, '');
+  if (!cleaned) throw new Error('no valid base32 characters');
+
+  const bytes = [];
+  let buffer = 0;
+  let bufferLength = 0;
+  for (const char of cleaned) {
+    const value = BASE32_ALPHABET.indexOf(char);
+    if (value === -1) throw new Error('invalid base32 character');
+    buffer = (buffer << 5) | value;
+    bufferLength += 5;
+    if (bufferLength >= 8) {
+      bufferLength -= 8;
+      bytes.push((buffer >> bufferLength) & 0xff);
+    }
+  }
+  return new Uint8Array(bytes);
+}
+
+export function normalizeDevAuthKeyInputToBytes(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) return null;
+
+  // Match Happy UI behavior:
+  // - backup format is base32 and is long (usually grouped with '-' / spaces)
+  // - base64url is short (~43 chars) and may contain '-' / '_' legitimately
+  //
+  // Key point: avoid mis-parsing backup base32 as base64.
+  if (raw.length > 50) {
+    try {
+      const b32 = base32ToBytes(raw);
+      return b32.length === 32 ? b32 : null;
+    } catch {
+      return null;
+    }
+  }
+
+  const b64 = base64UrlToBytes(raw);
+  if (b64 && b64.length === 32) return b64;
+  try {
+    const b32 = base32ToBytes(raw);
+    return b32.length === 32 ? b32 : null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatDevAuthKeyBackup(secretKeyBase64Url) {
+  const bytes = base64UrlToBytes(secretKeyBase64Url);
+  if (!bytes || bytes.length !== 32) throw new Error('invalid secret key (expected base64url 32 bytes)');
+  const base32 = bytesToBase32(bytes);
+  const groups = [];
+  for (let i = 0; i < base32.length; i += 5) groups.push(base32.slice(i, i + 5));
+  return groups.join('-');
+}
+
+export async function readDevAuthKey({ env = process.env } = {}) {
+  if ((env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY ?? '').toString().trim()) {
+    const bytes = normalizeDevAuthKeyInputToBytes(env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY);
+    if (!bytes) return { ok: false, error: 'invalid_env_key', source: 'env', secretKeyBase64Url: null, backup: null };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: 'env:HAPPY_STACKS_DEV_AUTH_SECRET_KEY', secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url) };
+  }
+
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const raw = await readFile(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    const input = parsed?.secretKeyBase64Url ?? parsed?.secretKey ?? parsed?.key ?? null;
+    const bytes = normalizeDevAuthKeyInputToBytes(input);
+    if (!bytes) return { ok: false, error: 'invalid_file_key', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: `file:${path}`, secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url), path };
+  } catch (e) {
+    return { ok: false, error: 'failed_to_read', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path, details: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export async function writeDevAuthKey({ env = process.env, input } = {}) {
+  const bytes = normalizeDevAuthKeyInputToBytes(input);
+  if (!bytes || bytes.length !== 32) {
+    throw new Error('invalid secret key (expected 32 bytes; accept base64url or backup format)');
+  }
+  const secretKeyBase64Url = bytesToBase64Url(bytes);
+  const path = getDevAuthKeyPath(env);
+  await mkdir(dirname(path), { recursive: true });
+  const payload = {
+    v: 1,
+    createdAt: new Date().toISOString(),
+    secretKeyBase64Url,
+  };
+  await writeFile(path, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+  await chmod(path, 0o600).catch(() => {});
+  return { ok: true, path, secretKeyBase64Url, backup: formatDevAuthKeyBackup(secretKeyBase64Url) };
+}
+
+export async function clearDevAuthKey({ env = process.env } = {}) {
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, deleted: false, path };
+    await unlink(path);
+    return { ok: true, deleted: true, path };
+  } catch (e) {
+    return { ok: false, deleted: false, path, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/scripts/utils/edison/git_roots.mjs

@@ -0,0 +1,29 @@
+import { dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+export function findGitRootForPath(dir) {
+  let cur = resolve(String(dir ?? '').trim());
+  if (!cur) return '';
+  while (true) {
+    try {
+      if (existsSync(join(cur, '.git'))) {
+        return cur;
+      }
+    } catch {
+      // ignore
+    }
+    const parent = dirname(cur);
+    if (parent === cur) return '';
+    cur = parent;
+  }
+}
+
+export function normalizeGitRoots(paths) {
+  const list = Array.isArray(paths) ? paths : [];
+  const normalized = list
+    .map((d) => findGitRootForPath(d) || String(d ?? '').trim())
+    .map((d) => resolve(d))
+    .filter(Boolean);
+  return Array.from(new Set(normalized));
+}
+

package/scripts/utils/edison/git_roots.test.mjs

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { findGitRootForPath, normalizeGitRoots } from './git_roots.mjs';
+
+async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-edison-git-roots-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+test('findGitRootForPath returns nearest ancestor containing .git marker', async (t) => {
+  const root = await withTempRoot(t);
+  const repoRoot = join(root, 'repo');
+  await mkdir(join(repoRoot, 'a', 'b'), { recursive: true });
+  await writeFile(join(repoRoot, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  assert.equal(findGitRootForPath(join(repoRoot, 'a', 'b')), repoRoot);
+});
+
+test('normalizeGitRoots de-duplicates multiple paths inside the same repo', async (t) => {
+  const root = await withTempRoot(t);
+  const repoRoot = join(root, 'repo');
+  await mkdir(join(repoRoot, 'expo-app'), { recursive: true });
+  await mkdir(join(repoRoot, 'cli'), { recursive: true });
+  await writeFile(join(repoRoot, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  const roots = normalizeGitRoots([join(repoRoot, 'expo-app'), join(repoRoot, 'cli')]);
+  assert.deepEqual(roots, [repoRoot]);
+});
+

package/scripts/utils/env/env.mjs

@@ -162,7 +162,12 @@ if (hasHomeConfig) {
   const stacksStorageRootRaw = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
   const stacksStorageRoot = stacksStorageRootRaw ? expandHome(stacksStorageRootRaw) : join(homedir(), '.happy', 'stacks');
   const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
-  const legacyStacksRoot = allowLegacy ? join(homedir(), '.happy', 'local', 'stacks') : join(stacksStorageRoot, '__legacy_disabled__');
+  // If the user explicitly overrides the stacks storage root, do not auto-discover a legacy env file from the real home dir.
+  // This keeps isolated runs (tests, sandboxes, custom dirs) from accidentally loading a "real" machine stack env file.
+  const legacyStacksRoot =
+    allowLegacy && !stacksStorageRootRaw
+      ? join(homedir(), '.happy', 'local', 'stacks')
+      : join(stacksStorageRoot, '__legacy_disabled__');
 
   const candidates = [
     join(stacksStorageRoot, stackName, 'env'),
@@ -204,8 +209,7 @@ process.env.NPM_CONFIG_PACKAGE_MANAGER_STRICT = process.env.NPM_CONFIG_PACKAGE_M
   const delimiter = process.platform === 'win32' ? ';' : ':';
   const current = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
   const nodeBinDir = dirname(process.execPath);
-  const want = [nodeBinDir, '/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin'];
+  const want = [nodeBinDir, '/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin', '/usr/bin', '/bin'];
   const next = [...want.filter((p) => p && !current.includes(p)), ...current];
   process.env.PATH = next.join(delimiter);
 })();
-

package/scripts/utils/env/env_file.mjs

@@ -7,7 +7,9 @@ export async function ensureEnvFileUpdated({ envPath, updates }) {
     return;
   }
   await mkdir(dirname(envPath), { recursive: true });
-  await writeFileIfChanged(envPath, applyEnvUpdates(await readText(envPath), updates), envPath);
+  const existing = await readText(envPath);
+  const next = applyEnvUpdates(existing, updates);
+  await writeFileIfChanged(existing, next, envPath);
 }
 
 export async function ensureEnvFilePruned({ envPath, removeKeys }) {
@@ -30,7 +32,7 @@ async function readText(path) {
 }
 
 function applyEnvUpdates(existing, updates) {
-  const lines = existing.split('\n');
+  const lines = existing ? existing.split('\n') : [];
   const next = [...lines];
 
   const upsert = (key, value) => {

package/scripts/utils/env/env_file.test.mjs

@@ -0,0 +1,44 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { ensureEnvFilePruned, ensureEnvFileUpdated } from './env_file.mjs';
+
+test('ensureEnvFileUpdated appends new key and ensures trailing newline', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-env-file-'));
+  const envPath = join(dir, 'env');
+
+  await ensureEnvFileUpdated({ envPath, updates: [{ key: 'OPENAI_API_KEY', value: 'sk-test' }] });
+  const next = await readFile(envPath, 'utf-8');
+  assert.equal(next, 'OPENAI_API_KEY=sk-test\n');
+});
+
+test('ensureEnvFileUpdated does not touch file when no content changes', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-env-file-'));
+  const envPath = join(dir, 'env');
+
+  await writeFile(envPath, 'FOO=bar\n', 'utf-8');
+  const before = await stat(envPath);
+
+  // Ensure filesystem mtime resolution won't hide unintended writes.
+  await delay(25);
+
+  await ensureEnvFileUpdated({ envPath, updates: [{ key: 'FOO', value: 'bar' }] });
+  const after = await stat(envPath);
+  assert.equal(after.mtimeMs, before.mtimeMs);
+});
+
+test('ensureEnvFilePruned removes a key but keeps comments/blank lines', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-env-file-'));
+  const envPath = join(dir, 'env');
+
+  await writeFile(envPath, '# header\nFOO=bar\n\nBAZ=qux\n', 'utf-8');
+  await ensureEnvFilePruned({ envPath, removeKeys: ['FOO'] });
+
+  const next = await readFile(envPath, 'utf-8');
+  assert.equal(next, '# header\n\nBAZ=qux\n');
+});
+

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/expo.mjs

@@ -4,6 +4,7 @@ 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 };
 
@@ -63,7 +64,25 @@ 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) {

package/scripts/utils/expo/metro_ports.mjs

@@ -0,0 +1,114 @@
+import { isTcpPortFree, pickNextFreeTcpPort } from '../net/ports.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;
+}
+
+function coercePositiveInt(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function resolveStablePortStart({
+  env = process.env,
+  stackName,
+  baseKey,
+  rangeKey,
+  defaultBase,
+  defaultRange,
+}) {
+  const baseRaw = (env[baseKey] ?? '').toString().trim();
+  const rangeRaw = (env[rangeKey] ?? '').toString().trim();
+  const base = coercePositiveInt(baseRaw) ?? defaultBase;
+  const range = coercePositiveInt(rangeRaw) ?? defaultRange;
+  return base + (hashStringToInt(stackName) % range);
+}
+
+export async function pickMetroPort({
+  startPort,
+  forcedPort,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  const forced = coercePositiveInt(forcedPort);
+  if (forced) {
+    const ok = await isTcpPortFree(forced, { host });
+    if (ok) return forced;
+  }
+  return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
+}
+
+export function wantsStablePortStrategy({ env = process.env, strategyKey, legacyStrategyKey } = {}) {
+  const raw = (env[strategyKey] ?? env[legacyStrategyKey] ?? 'ephemeral').toString().trim() || 'ephemeral';
+  return raw === 'stable';
+}
+
+export async function pickUiDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  // Legacy alias: UI dev Metro is now the unified Expo dev server port.
+  return await pickExpoDevMetroPort({ env, stackMode, stackName, reservedPorts, host });
+}
+
+export async function pickMobileDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  // Legacy alias: mobile dev Metro is now the unified Expo dev server port.
+  return await pickExpoDevMetroPort({ env, stackMode, stackName, reservedPorts, host });
+}
+
+export async function pickExpoDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  const forcedPort =
+    (env.HAPPY_STACKS_EXPO_DEV_PORT ??
+      env.HAPPY_LOCAL_EXPO_DEV_PORT ??
+      // Back-compat: older knobs.
+      env.HAPPY_STACKS_UI_DEV_PORT ??
+      env.HAPPY_LOCAL_UI_DEV_PORT ??
+      env.HAPPY_STACKS_MOBILE_DEV_PORT ??
+      env.HAPPY_LOCAL_MOBILE_DEV_PORT ??
+      env.HAPPY_STACKS_MOBILE_PORT ??
+      env.HAPPY_LOCAL_MOBILE_PORT ??
+      '')
+      .toString()
+      .trim() || '';
+
+  const stable =
+    stackMode &&
+    wantsStablePortStrategy({
+      env,
+      strategyKey: 'HAPPY_STACKS_EXPO_DEV_PORT_STRATEGY',
+      legacyStrategyKey: 'HAPPY_LOCAL_EXPO_DEV_PORT_STRATEGY',
+    });
+  const startPort = stable
+    ? resolveStablePortStart({
+        env,
+        stackName,
+        baseKey: 'HAPPY_STACKS_EXPO_DEV_PORT_BASE',
+        rangeKey: 'HAPPY_STACKS_EXPO_DEV_PORT_RANGE',
+        defaultBase: 8081,
+        defaultRange: 1000,
+      })
+    : 8081;
+
+  return await pickMetroPort({ startPort, forcedPort, reservedPorts, host });
+}
+