happy-stacks 0.1.2 → 0.3.0

package/scripts/utils/dev/expo_web.mjs

@@ -0,0 +1,112 @@
+import { ensureDepsInstalled, pmSpawnBin } from '../proc/pm.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, wantsExpoClearCache, writePidState } from '../expo/expo.mjs';
+import { pickDevMetroPort, resolveStackUiDevPortStart } from './server.mjs';
+import { recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
+
+export async function startDevExpoWebUi({
+  startUi,
+  uiDir,
+  autostart,
+  baseEnv,
+  apiServerUrl,
+  restart,
+  stackMode,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  spawnOptions = {},
+}) {
+  if (!startUi) return { ok: true, skipped: true, reason: 'disabled' };
+
+  await ensureDepsInstalled(uiDir, 'happy');
+  const uiEnv = { ...baseEnv };
+  delete uiEnv.CI;
+  uiEnv.EXPO_PUBLIC_HAPPY_SERVER_URL = apiServerUrl;
+  uiEnv.EXPO_PUBLIC_DEBUG = uiEnv.EXPO_PUBLIC_DEBUG ?? '1';
+
+  // We own the browser opening behavior in Happy Stacks so we can reliably open the correct origin.
+  uiEnv.EXPO_NO_BROWSER = '1';
+  uiEnv.BROWSER = 'none';
+
+  const uiPaths = getExpoStatePaths({
+    baseDir: autostart.baseDir,
+    kind: 'ui-dev',
+    projectDir: uiDir,
+    stateFileName: 'ui.state.json',
+  });
+
+  await ensureExpoIsolationEnv({
+    env: uiEnv,
+    stateDir: uiPaths.stateDir,
+    expoHomeDir: uiPaths.expoHomeDir,
+    tmpDir: uiPaths.tmpDir,
+  });
+
+  const uiRunning = await isStateProcessRunning(uiPaths.statePath);
+  const uiAlreadyRunning = Boolean(uiRunning.running);
+
+  if (uiAlreadyRunning && !restart) {
+    const pid = Number(uiRunning.state?.pid);
+    const port = Number(uiRunning.state?.port);
+    if (stackMode && runtimeStatePath && Number.isFinite(pid) && pid > 1) {
+      await recordStackRuntimeUpdate(runtimeStatePath, {
+        processes: { expoWebPid: pid },
+        expo: { webPort: Number.isFinite(port) && port > 0 ? port : null },
+      }).catch(() => {});
+    }
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'already_running',
+      pid: Number.isFinite(pid) ? pid : null,
+      port: Number.isFinite(port) ? port : null,
+    };
+  }
+
+  const strategy =
+    (baseEnv.HAPPY_STACKS_UI_DEV_PORT_STRATEGY ?? baseEnv.HAPPY_LOCAL_UI_DEV_PORT_STRATEGY ?? 'ephemeral').toString().trim() ||
+    'ephemeral';
+  const stable = strategy === 'stable';
+  const startPort = stackMode && stable ? resolveStackUiDevPortStart({ env: baseEnv, stackName }) : 8081;
+  const metroPort = await pickDevMetroPort({ startPort });
+  uiEnv.RCT_METRO_PORT = String(metroPort);
+
+  const uiArgs = ['start', '--web', '--port', String(metroPort)];
+  if (wantsExpoClearCache({ env: baseEnv })) {
+    uiArgs.push('--clear');
+  }
+
+  if (restart && uiRunning.state?.pid) {
+    const prevPid = Number(uiRunning.state.pid);
+    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-web', json: true });
+    if (!res.killed) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[local] ui: not stopping existing Expo pid=${prevPid} because it does not look stack-owned.\n` +
+          `[local] ui: continuing by starting a new Expo process on a free port.`
+      );
+    }
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] ui: starting Expo web (metro port=${metroPort})`);
+  const ui = await pmSpawnBin({ label: 'ui', dir: uiDir, bin: 'expo', args: uiArgs, env: uiEnv, options: spawnOptions });
+  children.push(ui);
+
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeUpdate(runtimeStatePath, {
+      processes: { expoWebPid: ui.pid },
+      expo: { webPort: metroPort },
+    }).catch(() => {});
+  }
+
+  try {
+    await writePidState(uiPaths.statePath, { pid: ui.pid, port: metroPort, uiDir, startedAt: new Date().toISOString() });
+  } catch {
+    // ignore
+  }
+
+  return { ok: true, skipped: false, pid: ui.pid, port: metroPort, proc: ui };
+}

package/scripts/utils/dev/server.mjs

@@ -0,0 +1,183 @@
+import { join, resolve } from 'node:path';
+
+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';
+
+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;
+}
+
+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);
+}
+
+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 });
+}
+
+export async function startDevServer({
+  serverComponentName,
+  serverDir,
+  autostart,
+  baseEnv,
+  serverPort,
+  internalServerUrl,
+  publicServerUrl,
+  envPath,
+  stackMode,
+  runtimeStatePath,
+  serverAlreadyRunning,
+  restart,
+  children,
+}) {
+  const serverEnv = {
+    ...baseEnv,
+    PORT: String(serverPort),
+    PUBLIC_URL: publicServerUrl,
+    // Avoid noisy failures if a previous run left the metrics port busy.
+    METRICS_ENABLED: baseEnv.METRICS_ENABLED ?? 'false',
+  };
+
+  if (serverComponentName === 'happy-server-light') {
+    const dataDir = baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR?.trim()
+      ? baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR.trim()
+      : join(autostart.baseDir, 'server-light');
+    serverEnv.HAPPY_SERVER_LIGHT_DATA_DIR = dataDir;
+    serverEnv.HAPPY_SERVER_LIGHT_FILES_DIR = baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR?.trim()
+      ? baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR.trim()
+      : join(dataDir, 'files');
+    serverEnv.DATABASE_URL = baseEnv.DATABASE_URL?.trim() ? baseEnv.DATABASE_URL.trim() : `file:${join(dataDir, 'happy-server-light.sqlite')}`;
+  }
+
+  if (serverComponentName === 'happy-server') {
+    const managed = (baseEnv.HAPPY_STACKS_MANAGED_INFRA ?? baseEnv.HAPPY_LOCAL_MANAGED_INFRA ?? '1') !== '0';
+    if (managed) {
+      const infra = await ensureHappyServerManagedInfra({
+        stackName: autostart.stackName,
+        baseDir: autostart.baseDir,
+        serverPort,
+        publicServerUrl,
+        envPath,
+        env: baseEnv,
+      });
+      Object.assign(serverEnv, infra.env);
+    }
+
+    const autoMigrate = (baseEnv.HAPPY_STACKS_PRISMA_MIGRATE ?? baseEnv.HAPPY_LOCAL_PRISMA_MIGRATE ?? '1') !== '0';
+    if (autoMigrate) {
+      await applyHappyServerMigrations({ serverDir, env: serverEnv });
+    }
+  }
+
+  // Ensure server deps exist before any Prisma/docker work.
+  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';
+
+  // Restart behavior (stack-safe): only kill when we can prove ownership via runtime state.
+  if (restart && stackMode && runtimeStatePath && serverAlreadyRunning) {
+    const st = await readStackRuntimeStateFile(runtimeStatePath);
+    const pid = Number(st?.processes?.serverPid);
+    if (pid > 1) {
+      const res = await killProcessGroupOwnedByStack(pid, { stackName: autostart.stackName, envPath, label: 'server', json: true });
+      if (!res.killed) {
+        // Fail-closed if the port is still occupied.
+        const free = await isTcpPortFree(serverPort, { host: '127.0.0.1' });
+        if (!free) {
+          throw new Error(
+            `[local] restart refused: server port ${serverPort} is occupied and the PID is not provably stack-owned.\n` +
+              `[local] Fix: run 'happys stack stop ${autostart.stackName}' then re-run, or re-run without --restart.`
+          );
+        }
+      }
+    }
+  }
+
+  if (serverAlreadyRunning && !restart) {
+    return { serverEnv, serverScript, serverProc: null };
+  }
+
+  const server = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
+  children.push(server);
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: server.pid } }).catch(() => {});
+  }
+  await waitForServerReady(internalServerUrl);
+  return { serverEnv, serverScript, serverProc: server };
+}
+
+export function watchDevServerAndRestart({
+  enabled,
+  stackMode,
+  serverComponentName,
+  serverDir,
+  serverPort,
+  internalServerUrl,
+  serverScript,
+  serverEnv,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  serverProcRef,
+  isShuttingDown,
+}) {
+  if (!enabled) return null;
+
+  // Only watch full server by default; happy-server-light already has a good upstream dev loop.
+  if (serverComponentName !== 'happy-server') return null;
+
+  return watchDebounced({
+    paths: [resolve(serverDir)],
+    debounceMs: 600,
+    onChange: async () => {
+      if (isShuttingDown?.()) return;
+      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 });
+
+      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})`);
+    },
+  });
+}

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

@@ -1,14 +1,18 @@
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { ensureEnvFileUpdated } from './env_file.mjs';
-import { getHappyStacksHomeDir, resolveStackEnvPath } from './paths.mjs';
+import { getHappyStacksHomeDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getCanonicalHomeDirFromEnv } from '../paths/canonical_home.mjs';
 
 export function getHomeEnvPath() {
   return join(getHappyStacksHomeDir(), '.env');
 }
 
+export function getCanonicalHomeDir() {
+  return getCanonicalHomeDirFromEnv(process.env);
+}
+
 export function getCanonicalHomeEnvPath() {
-  return join(homedir(), '.happy-stacks', '.env');
+  return join(getCanonicalHomeDir(), '.env');
 }
 
 export function getHomeEnvLocalPath() {
@@ -46,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,13 +4,32 @@ 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 '../paths/canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
 
 async function loadEnvFile(path, { override = false, overridePrefix = null } = {}) {
   try {
     const contents = await readFile(path, 'utf-8');
     const parsed = parseDotenv(contents);
+    const allowTransientComponentDirOverrides =
+      !overridePrefix &&
+      override &&
+      ((process.env.HAPPY_STACKS_TRANSIENT_COMPONENT_OVERRIDES ?? '').trim() === '1' ||
+        (process.env.HAPPY_LOCAL_TRANSIENT_COMPONENT_OVERRIDES ?? '').trim() === '1');
     for (const [k, v] of parsed.entries()) {
       const allowOverride = override && (!overridePrefix || k.startsWith(overridePrefix));
+      // Special-case: allow one-shot CLI overrides (e.g. `happys stack typecheck <stack> --happy-cli=...`)
+      // to win over stack env files for component directories.
+      //
+      // This keeps stack env files authoritative by default (we also scrub HAPPY_STACKS_* from the parent
+      // environment in `withStackEnv()`), but lets the stack wrappers inject a temporary override when explicitly requested.
+      if (
+        allowTransientComponentDirOverrides &&
+        (k.startsWith('HAPPY_STACKS_COMPONENT_DIR_') || k.startsWith('HAPPY_LOCAL_COMPONENT_DIR_')) &&
+        (process.env[k] ?? '').trim()
+      ) {
+        continue;
+      }
       if (allowOverride || process.env[k] == null || process.env[k] === '') {
         process.env[k] = v;
       }
@@ -20,16 +39,30 @@ async function loadEnvFile(path, { override = false, overridePrefix = null } = {
   }
 }
 
+async function loadEnvFileIgnoringPrefixes(path, { ignorePrefixes = [] } = {}) {
+  try {
+    const contents = await readFile(path, 'utf-8');
+    const parsed = parseDotenv(contents);
+    for (const [k, v] of parsed.entries()) {
+      if (ignorePrefixes.some((p) => k.startsWith(p))) {
+        continue;
+      }
+      if (process.env[k] == null || process.env[k] === '') {
+        process.env[k] = v;
+      }
+    }
+  } catch {
+    // ignore missing/invalid env file
+  }
+}
+
 // 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);
 
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
-
 function resolveHomeDir() {
   const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
   if (fromEnv) {
@@ -65,11 +98,11 @@ function applyStacksPrefixMapping() {
   }
 }
 
-// If HAPPY_STACKS_HOME_DIR isn't set, try the canonical pointer file at ~/.happy-stacks/.env first.
+// If HAPPY_STACKS_HOME_DIR isn't set, try the canonical pointer file at <canonicalHomeDir>/.env first.
 //
 // This allows installs where the "real" home/workspace/runtime are elsewhere, while still
 // giving us a stable discovery location for launchd/SwiftBar/minimal shells.
-const canonicalEnvPath = join(homedir(), '.happy-stacks', '.env');
+const canonicalEnvPath = getCanonicalHomeEnvPathFromEnv(process.env);
 if (!(process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() && existsSync(canonicalEnvPath)) {
   await loadEnvFile(canonicalEnvPath, { override: false });
   await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_STACKS_' });
@@ -83,12 +116,15 @@ process.env.HAPPY_STACKS_HOME_DIR = process.env.HAPPY_STACKS_HOME_DIR ?? __homeD
 //   ~/.happy-stacks/.env
 //   ~/.happy-stacks/env.local
 //
-// Backwards compatible fallback for cloned-repo usage (when home config doesn't exist yet):
-//   <repo>/.env
-//   <repo>/env.local
+// Additionally: when running from a cloned repo, load <repo>/.env as a *fallback* even if home config exists.
+// This helps keep repo-local dev settings (e.g. custom Codex binaries) working without requiring users to
+// duplicate them into ~/.happy-stacks/env.local.
 const homeEnv = join(__homeDir, '.env');
 const homeLocal = join(__homeDir, 'env.local');
-const hasHomeConfig = existsSync(homeEnv) || existsSync(homeLocal);
+// In sandbox mode, never load repo env.local (it can contain "real" machine paths/URLs).
+// Treat sandbox runs as having home config even if the sandbox home env files don't exist yet.
+const hasHomeConfig = isSandboxed() || existsSync(homeEnv) || existsSync(homeLocal);
+const repoEnv = join(__cliRootDir, '.env');
 
 // 1) Load defaults first (lowest precedence)
 if (hasHomeConfig) {
@@ -101,6 +137,19 @@ if (hasHomeConfig) {
   await loadEnvFile(join(__cliRootDir, 'env.local'), { override: true, overridePrefix: 'HAPPY_STACKS_' });
 }
 
+// Repo-local fallback (dev convenience):
+// If the repo has a .env, load it without overriding anything already set by the environment or home config.
+// Note: we intentionally do NOT load repo env.local here, because env.local is treated as higher-precedence
+// overrides and could unexpectedly fight with stack/home configuration when present.
+if (hasHomeConfig) {
+  // IMPORTANT:
+  // When home config exists, do not let repo-local .env set HAPPY_STACKS_* / HAPPY_LOCAL_* keys.
+  // Otherwise a cloned repo's .env can accidentally leak global URLs/ports into every stack.
+  await loadEnvFileIgnoringPrefixes(repoEnv, { ignorePrefixes: ['HAPPY_STACKS_', 'HAPPY_LOCAL_'] });
+} else {
+  await loadEnvFile(repoEnv, { override: false });
+}
+
 // If no explicit env file is set, and we're on the default "main" stack, prefer the stack-scoped env file
 // if it exists: ~/.happy/stacks/main/env
 (() => {
@@ -112,7 +161,8 @@ if (hasHomeConfig) {
   const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
   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 legacyStacksRoot = join(homedir(), '.happy', 'local', 'stacks');
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
+  const legacyStacksRoot = allowLegacy ? join(homedir(), '.happy', 'local', 'stacks') : join(stacksStorageRoot, '__legacy_disabled__');
 
   const candidates = [
     join(stacksStorageRoot, stackName, 'env'),
@@ -158,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) {
@@ -10,6 +10,17 @@ export async function ensureEnvFileUpdated({ envPath, updates }) {
   await writeFileIfChanged(envPath, applyEnvUpdates(await readText(envPath), updates), envPath);
 }
 
+export async function ensureEnvFilePruned({ envPath, removeKeys }) {
+  const keys = Array.from(new Set((removeKeys ?? []).map((k) => String(k).trim()).filter(Boolean)));
+  if (!keys.length) {
+    return;
+  }
+  await mkdir(dirname(envPath), { recursive: true });
+  const existing = await readText(envPath);
+  const next = pruneEnvKeys(existing, keys);
+  await writeFileIfChanged(existing, next, envPath);
+}
+
 async function readText(path) {
   try {
     return (await pathExists(path)) ? await readFile(path, 'utf-8') : '';
@@ -42,6 +53,31 @@ function applyEnvUpdates(existing, updates) {
   return next.join('\n');
 }
 
+function pruneEnvKeys(existing, removeKeys) {
+  const keys = new Set(removeKeys);
+  const lines = (existing ?? '').split('\n');
+  const kept = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      kept.push(line);
+      continue;
+    }
+    // Remove any "KEY=..." line for keys in removeKeys.
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) {
+      kept.push(line);
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    if (keys.has(key)) {
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
 async function writeFileIfChanged(existingContent, nextContent, path) {
   const normalizedNext = nextContent.endsWith('\n') ? nextContent : nextContent + '\n';
   const normalizedExisting = existingContent.endsWith('\n') ? existingContent : existingContent + (existingContent ? '\n' : '');
@@ -57,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/sandbox.mjs

@@ -0,0 +1,14 @@
+export function getSandboxDir() {
+  const v = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
+  return v || '';
+}
+
+export function isSandboxed() {
+  return Boolean(getSandboxDir());
+}
+
+export function sandboxAllowsGlobalSideEffects() {
+  const raw = (process.env.HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL ?? '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'y';
+}
+

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

@@ -3,6 +3,9 @@ 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';
+
+export { isPidAlive };
 
 function hashDir(dir) {
   return createHash('sha1').update(String(dir ?? '')).digest('hex').slice(0, 12);
@@ -26,10 +29,12 @@ export async function ensureExpoIsolationEnv({ env, stateDir, expoHomeDir, tmpDi
   await mkdir(tmpDir, { recursive: true });
 
   // Expo CLI uses this to override ~/.expo.
-  env.__UNSAFE_EXPO_HOME_DIRECTORY = env.__UNSAFE_EXPO_HOME_DIRECTORY ?? expoHomeDir;
+  // Always override: stack/worktree isolation must not fall back to the user's global ~/.expo.
+  env.__UNSAFE_EXPO_HOME_DIRECTORY = expoHomeDir;
 
   // Metro default cache root is `path.join(os.tmpdir(), 'metro-cache')`, so TMPDIR isolates it.
-  env.TMPDIR = env.TMPDIR ?? tmpDir;
+  // Always override: macOS sets TMPDIR by default, so a "set-if-missing" guard would not isolate Metro.
+  env.TMPDIR = tmpDir;
 }
 
 export function wantsExpoClearCache({ env }) {
@@ -54,15 +59,6 @@ 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 };

package/scripts/utils/fs/json.mjs

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+
+export async function readJsonIfExists(path, { defaultValue = null } = {}) {
+  try {
+    const p = String(path ?? '').trim();
+    if (!p || !existsSync(p)) return defaultValue;
+    const raw = await readFile(p, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return defaultValue;
+  }
+}
+
+export async function writeJsonAtomic(path, value) {
+  const p = String(path ?? '').trim();
+  if (!p) throw new Error('writeJsonAtomic: path is required');
+  const dir = dirname(p);
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  const tmp = join(dir, `.tmp.${Date.now()}.${Math.random().toString(16).slice(2)}.json`);
+  await writeFile(tmp, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+  await rename(tmp, p);
+}
+