happy-stacks 0.3.0 → 0.4.0

package/scripts/utils/stacks.mjs

@@ -0,0 +1,38 @@
+import { readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getLegacyStorageRoot, getStacksStorageRoot } from './paths/paths.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './env/sandbox.mjs';
+
+export async function listAllStackNames() {
+  const names = new Set(['main']);
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
+  const roots = [
+    // New layout: ~/.happy/stacks/<name>/env
+    getStacksStorageRoot(),
+    // Legacy layout: ~/.happy/local/stacks/<name>/env
+    ...(allowLegacy ? [join(getLegacyStorageRoot(), 'stacks')] : []),
+  ];
+
+  for (const root of roots) {
+    let entries = [];
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const name = ent.name;
+      if (!name || name.startsWith('.')) continue;
+      const envPath = join(root, name, 'env');
+      if (existsSync(envPath)) {
+        names.add(name);
+      }
+    }
+  }
+
+  return Array.from(names).sort();
+}

package/scripts/utils/ui/qr.mjs

@@ -0,0 +1,17 @@
+import qrcodeTerminal from 'qrcode-terminal';
+
+export async function renderQrAscii(text, { small = true } = {}) {
+  const qrText = String(text ?? '');
+  if (!qrText) return { ok: false, lines: [], error: 'empty QR payload' };
+  try {
+    const out = await new Promise((resolvePromise) => {
+      qrcodeTerminal.generate(qrText, { small: Boolean(small) }, (qr) => resolvePromise(String(qr ?? '')));
+    });
+    // Important: keep whitespace; scanners rely on quiet-zone padding.
+    const lines = String(out ?? '').replace(/\r/g, '').split('\n');
+    return { ok: true, lines, error: null };
+  } catch (e) {
+    return { ok: false, lines: [], error: e instanceof Error ? e.message : String(e) };
+  }
+}
+

package/scripts/utils/validate.mjs

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { getComponentsDir } from './paths/paths.mjs';
+
+function isInside(path, dir) {
+  const p = resolve(path);
+  const d = resolve(dir);
+  return p === d || p.startsWith(d.endsWith(sep) ? d : d + sep);
+}
+
+export function detectServerComponentDirMismatch({ rootDir, serverComponentName, serverDir }) {
+  const componentsDir = getComponentsDir(rootDir);
+
+  const other = serverComponentName === 'happy-server-light' ? 'happy-server' : serverComponentName === 'happy-server' ? 'happy-server-light' : null;
+  if (!other) {
+    return null;
+  }
+
+  const otherRepo = resolve(componentsDir, other);
+  const otherWts = resolve(componentsDir, '.worktrees', other);
+
+  if (isInside(serverDir, otherRepo) || isInside(serverDir, otherWts)) {
+    return { expected: serverComponentName, actual: other, serverDir };
+  }
+
+  return null;
+}
+
+export function assertServerComponentDirMatches({ rootDir, serverComponentName, serverDir }) {
+  const mismatch = detectServerComponentDirMismatch({ rootDir, serverComponentName, serverDir });
+  if (!mismatch) {
+    return;
+  }
+
+  const hint =
+    mismatch.expected === 'happy-server-light'
+      ? 'Fix: either switch flavor (`happys srv use happy-server`) or switch the active checkout for happy-server-light (`happys wt use happy-server-light default` or a worktree under .worktrees/happy-server-light/).'
+      : 'Fix: either switch flavor (`happys srv use happy-server-light`) or switch the active checkout for happy-server (`happys wt use happy-server default` or a worktree under .worktrees/happy-server/).';
+
+  throw new Error(
+    `[server] server component dir mismatch:\n` +
+      `- selected flavor: ${mismatch.expected}\n` +
+      `- but HAPPY_STACKS_COMPONENT_DIR_* points inside: ${mismatch.actual}\n` +
+      `- path: ${mismatch.serverDir}\n` +
+      `${hint}`
+  );
+}
+
+function detectPrismaProvider(schemaText) {
+  // Best-effort parse of:
+  // datasource db { provider = "sqlite" ... }
+  const m = schemaText.match(/datasource\s+db\s*\{[\s\S]*?\bprovider\s*=\s*\"([a-zA-Z0-9_-]+)\"/m);
+  return m?.[1] ?? '';
+}
+
+export function assertServerPrismaProviderMatches({ serverComponentName, serverDir }) {
+  const schemaPath = join(serverDir, 'prisma', 'schema.prisma');
+  let schemaText = '';
+  try {
+    schemaText = readFileSync(schemaPath, 'utf-8');
+  } catch {
+    // If it doesn't exist, skip validation; not every server component necessarily uses Prisma.
+    return;
+  }
+
+  const provider = detectPrismaProvider(schemaText);
+  if (!provider) {
+    return;
+  }
+
+  if (serverComponentName === 'happy-server-light' && provider !== 'sqlite') {
+    throw new Error(
+      `[server] happy-server-light expects Prisma datasource provider \"sqlite\", but found \"${provider}\" in:\n` +
+        `- ${schemaPath}\n` +
+        `This usually means you're pointing happy-server-light at an upstream happy-server checkout/PR (Postgres).\n` +
+        `Fix: either switch server flavor to happy-server, or point happy-server-light at a fork checkout that keeps sqlite support.`
+    );
+  }
+
+  if (serverComponentName === 'happy-server' && provider === 'sqlite') {
+    throw new Error(
+      `[server] happy-server expects Prisma datasource provider \"postgresql\", but found \"sqlite\" in:\n` +
+        `- ${schemaPath}\n` +
+        `Fix: either switch server flavor to happy-server-light, or point happy-server at the full-server checkout.`
+    );
+  }
+}
+

package/scripts/worktrees.mjs

@@ -14,10 +14,13 @@ import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
 import { ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { isSandboxed } from './utils/env/sandbox.mjs';
 import { existsSync } from 'node:fs';
 import { getHomeEnvLocalPath, getHomeEnvPath, resolveUserConfigEnvPath } from './utils/env/config.mjs';
 import { detectServerComponentDirMismatch } from './utils/server/validate.mjs';
 
+const DEFAULT_COMPONENTS = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
+
 function getActiveStackName() {
   return (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
 }
@@ -162,41 +165,100 @@ async function installDependencies({ dir }) {
     return { installed: false, reason: 'no package manager detected (no package.json)' };
   }
 
+  // IMPORTANT:
+  // When a caller requests --json, stdout must be reserved for JSON output only.
+  // Package managers (especially Yarn) write progress to stdout, which would corrupt JSON parsing
+  // in wrappers like `stack pr`.
+  const jsonMode = Boolean((process.argv ?? []).includes('--json'));
+  const runForJson = async (cmd, args) => {
+    try {
+      const out = await runCapture(cmd, args, { cwd: dir });
+      if (out) process.stderr.write(out);
+    } catch (e) {
+      const out = String(e?.out ?? '');
+      const err = String(e?.err ?? '');
+      if (out) process.stderr.write(out);
+      if (err) process.stderr.write(err);
+      throw e;
+    }
+  };
+
   if (pm.kind === 'pnpm') {
-    await run('pnpm', ['install', '--frozen-lockfile'], { cwd: dir });
+    if (jsonMode) {
+      await runForJson('pnpm', ['install', '--frozen-lockfile']);
+    } else {
+      await run('pnpm', ['install', '--frozen-lockfile'], { cwd: dir });
+    }
     return { installed: true, reason: null };
   }
   if (pm.kind === 'yarn') {
     // Works for yarn classic; yarn berry will ignore/translate flags as needed.
-    await run('yarn', ['install', '--frozen-lockfile'], { cwd: dir });
+    if (jsonMode) {
+      await runForJson('yarn', ['install', '--frozen-lockfile']);
+    } else {
+      await run('yarn', ['install', '--frozen-lockfile'], { cwd: dir });
+    }
     return { installed: true, reason: null };
   }
   // npm
   if (pm.lockfile && pm.lockfile !== 'package.json') {
-    await run('npm', ['ci'], { cwd: dir });
+    if (jsonMode) {
+      await runForJson('npm', ['ci']);
+    } else {
+      await run('npm', ['ci'], { cwd: dir });
+    }
   } else {
-    await run('npm', ['install'], { cwd: dir });
+    if (jsonMode) {
+      await runForJson('npm', ['install']);
+    } else {
+      await run('npm', ['install'], { cwd: dir });
+    }
   }
   return { installed: true, reason: null };
 }
 
-async function maybeSetupDeps({ repoRoot, baseDir, worktreeDir, depsMode }) {
+function allowNodeModulesSymlinkForComponent(component) {
+  const c = String(component ?? '').trim();
+  if (!c) return true;
+  // Expo/Metro commonly breaks with symlinked node_modules. Avoid symlinks for the Happy UI worktree by default.
+  // Override if you *really* want to experiment:
+  //   HAPPY_STACKS_WT_ALLOW_HAPPY_NODE_MODULES_SYMLINK=1
+  const allowHappySymlink =
+    (process.env.HAPPY_STACKS_WT_ALLOW_HAPPY_NODE_MODULES_SYMLINK ?? process.env.HAPPY_LOCAL_WT_ALLOW_HAPPY_NODE_MODULES_SYMLINK ?? '')
+      .toString()
+      .trim() === '1';
+  if (c === 'happy' && !allowHappySymlink) return false;
+  return true;
+}
+
+async function maybeSetupDeps({ repoRoot, baseDir, worktreeDir, depsMode, component }) {
   if (!depsMode || depsMode === 'none') {
     return { mode: 'none', linked: false, installed: false, message: null };
   }
 
   // Prefer explicit baseDir if provided, otherwise link from the primary checkout (repoRoot).
   const linkFrom = baseDir || repoRoot;
+  const allowSymlink = allowNodeModulesSymlinkForComponent(component);
 
   if (depsMode === 'link' || depsMode === 'link-or-install') {
-    const res = await linkNodeModules({ fromDir: linkFrom, toDir: worktreeDir });
-    if (res.linked) {
-      return { mode: depsMode, linked: true, installed: false, message: null };
-    }
-    if (depsMode === 'link') {
-      return { mode: depsMode, linked: false, installed: false, message: res.reason };
+    if (!allowSymlink) {
+      const msg =
+        `[wt] refusing to symlink node_modules for ${component} (Expo/Metro is often broken by symlinks).\n` +
+        `[wt] Fix: use --deps=install (recommended). To override: set HAPPY_STACKS_WT_ALLOW_HAPPY_NODE_MODULES_SYMLINK=1`;
+      if (depsMode === 'link') {
+        return { mode: depsMode, linked: false, installed: false, message: msg };
+      }
+      // link-or-install: fall through to install.
+    } else {
+      const res = await linkNodeModules({ fromDir: linkFrom, toDir: worktreeDir });
+      if (res.linked) {
+        return { mode: depsMode, linked: true, installed: false, message: null };
+      }
+      if (depsMode === 'link') {
+        return { mode: depsMode, linked: false, installed: false, message: res.reason };
+      }
+      // fall through to install
     }
-    // fall through to install
   }
 
   const inst = await installDependencies({ dir: worktreeDir });
@@ -430,11 +492,9 @@ async function migrateComponentWorktrees({ rootDir, component }) {
 }
 
 async function cmdMigrate({ rootDir }) {
-  const components = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
-
   let totalMoved = 0;
   let totalRenamed = 0;
-  for (const component of components) {
+  for (const component of DEFAULT_COMPONENTS) {
     const res = await migrateComponentWorktrees({ rootDir, component });
     totalMoved += res.moved;
     totalRenamed += res.renamed;
@@ -679,7 +739,7 @@ async function cmdNew({ rootDir, argv }) {
   }
 
   const depsMode = parseDepsMode(kv.get('--deps'));
-  const deps = await maybeSetupDeps({ repoRoot, baseDir: baseWorktreeDir || '', worktreeDir: destPath, depsMode });
+  const deps = await maybeSetupDeps({ repoRoot, baseDir: baseWorktreeDir || '', worktreeDir: destPath, depsMode, component });
 
   const shouldUse = flags.has('--use');
   const force = flags.has('--force');
@@ -765,8 +825,14 @@ async function cmdPr({ rootDir, argv }) {
     throw new Error(`[wt] unable to parse PR: ${prInput}`);
   }
 
-  const remoteName = (kv.get('--remote') ?? '').trim() || 'upstream';
-  const { owner } = await resolveRemoteOwner(repoRoot, remoteName);
+  const remoteFromArg = (kv.get('--remote') ?? '').trim();
+  const canFetchByUrl = !remoteFromArg && pr.owner && pr.repo;
+  const fetchTarget = canFetchByUrl ? `https://github.com/${pr.owner}/${pr.repo}.git` : null;
+
+  // If we can fetch directly from the PR URL's repo, do it. This avoids any assumptions about local
+  // remote names like "origin" vs "upstream" and works even when the repo doesn't have that remote set up.
+  const remoteName = canFetchByUrl ? '' : await normalizeRemoteName(repoRoot, remoteFromArg || 'upstream');
+  const { owner } = canFetchByUrl ? { owner: pr.owner } : await resolveRemoteOwner(repoRoot, remoteName);
 
   const slugExtra = sanitizeSlugPart(kv.get('--slug') ?? '');
   const slug = slugExtra ? `pr/${pr.number}-${slugExtra}` : `pr/${pr.number}`;
@@ -783,7 +849,9 @@ async function cmdPr({ rootDir, argv }) {
   }
 
   // Fetch PR head ref (GitHub convention). Use + to allow force-updated PR branches when --force is set.
-  const force = flags.has('--force');
+  // In sandbox mode, be more aggressive: the entire workspace is disposable, so it's safe to
+  // reset an existing local PR branch to the fetched PR head if needed.
+  const force = flags.has('--force') || isSandboxed();
   let oldHead = null;
   const prRef = `refs/pull/${pr.number}/head`;
   if (exists) {
@@ -799,14 +867,17 @@ async function cmdPr({ rootDir, argv }) {
     }
 
     oldHead = (await git(destPath, ['rev-parse', 'HEAD'])).trim();
-    await git(repoRoot, ['fetch', '--quiet', remoteName, prRef]);
+    await git(repoRoot, ['fetch', '--quiet', fetchTarget ?? remoteName, prRef]);
     const newTip = (await git(repoRoot, ['rev-parse', 'FETCH_HEAD'])).trim();
 
     const isAncestor = await gitOk(repoRoot, ['merge-base', '--is-ancestor', oldHead, newTip]);
     if (!isAncestor && !force) {
+      const hint = fetchTarget
+        ? `[wt] re-run with: happys wt pr ${component} ${pr.number} --update --force`
+        : `[wt] re-run with: happys wt pr ${component} ${pr.number} --remote=${remoteName} --update --force`;
       throw new Error(
         `[wt] PR update is not a fast-forward (likely force-push) for ${branchName}\n` +
-          `[wt] re-run with: happys wt pr ${component} ${pr.number} --remote=${remoteName} --update --force`
+          hint
       );
     }
 
@@ -837,16 +908,22 @@ async function cmdPr({ rootDir, argv }) {
       );
     }
   } else {
-    await git(repoRoot, ['fetch', '--quiet', remoteName, prRef]);
+    await git(repoRoot, ['fetch', '--quiet', fetchTarget ?? remoteName, prRef]);
     const newTip = (await git(repoRoot, ['rev-parse', 'FETCH_HEAD'])).trim();
 
     const branchExists = await gitOk(repoRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branchName}`]);
     if (branchExists) {
       if (!force) {
-        throw new Error(`[wt] branch already exists: ${branchName}\n[wt] re-run with --force to reset it to the PR head`);
+        // If the branch already points at the fetched PR tip, we can safely just attach a worktree.
+        const branchHead = (await git(repoRoot, ['rev-parse', branchName])).trim();
+        if (branchHead !== newTip) {
+          throw new Error(`[wt] branch already exists: ${branchName}\n[wt] re-run with --force to reset it to the PR head`);
+        }
+        await git(repoRoot, ['worktree', 'add', destPath, branchName]);
+      } else {
+        await git(repoRoot, ['branch', '-f', branchName, newTip]);
+        await git(repoRoot, ['worktree', 'add', destPath, branchName]);
       }
-      await git(repoRoot, ['branch', '-f', branchName, newTip]);
-      await git(repoRoot, ['worktree', 'add', destPath, branchName]);
     } else {
       // Create worktree at PR head (new local branch).
       await git(repoRoot, ['worktree', 'add', '-b', branchName, destPath, newTip]);
@@ -855,7 +932,7 @@ async function cmdPr({ rootDir, argv }) {
 
   // Optional deps handling (useful when PR branches add/change dependencies).
   const depsMode = parseDepsMode(kv.get('--deps'));
-  const deps = await maybeSetupDeps({ repoRoot, baseDir: repoRoot, worktreeDir: destPath, depsMode });
+  const deps = await maybeSetupDeps({ repoRoot, baseDir: repoRoot, worktreeDir: destPath, depsMode, component });
 
   const shouldUse = flags.has('--use');
   if (shouldUse) {
@@ -1422,8 +1499,6 @@ async function cmdCursor({ rootDir, argv }) {
   throw new Error("[wt] Cursor CLI 'cursor' not found on PATH (and non-macOS fallback is unavailable).");
 }
 
-const DEFAULT_COMPONENTS = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
-
 async function cmdSyncAll({ rootDir, argv }) {
   const { flags, kv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
@@ -1556,43 +1631,48 @@ async function cmdNewInteractive({ rootDir, argv }) {
   });
 }
 
-async function cmdList({ rootDir, args }) {
-  const component = args[0];
-  if (!component) {
-    throw new Error('[wt] usage: happys wt list <component>');
-  }
-
+async function cmdListOne({ rootDir, component }) {
   const wtRoot = getWorktreesRoot(rootDir);
   const dir = join(wtRoot, component);
+  const key = componentDirEnvKey(component);
+  const active = (process.env[key] ?? '').trim() || join(getComponentsDir(rootDir), component);
+
   if (!(await pathExists(dir))) {
-    return { component, activeDir: (process.env[key] ?? '').trim() || join(getComponentsDir(rootDir), component), worktrees: [] };
+    return { component, activeDir: active, worktrees: [] };
   }
 
-  const leafs = [];
+  const worktrees = [];
   const walk = async (d) => {
+    // In git worktrees, ".git" is usually a file that points to the shared git dir.
+    // If this is a worktree root, record it and do not descend into it (avoids traversing huge trees like node_modules).
+    if (await pathExists(join(d, '.git'))) {
+      worktrees.push(d);
+      return;
+    }
     const entries = await readdir(d, { withFileTypes: true });
     for (const e of entries) {
-      if (!e.isDirectory()) {
-        continue;
-      }
-      const p = join(d, e.name);
-      leafs.push(p);
-      await walk(p);
+      if (!e.isDirectory()) continue;
+      if (e.name === 'node_modules') continue;
+      if (e.name.startsWith('.')) continue;
+      await walk(join(d, e.name));
     }
   };
   await walk(dir);
-  leafs.sort();
+  worktrees.sort();
 
-  const key = componentDirEnvKey(component);
-  const active = (process.env[key] ?? '').trim() || join(getComponentsDir(rootDir), component);
+  return { component, activeDir: active, worktrees };
+}
 
-  const worktrees = [];
-  for (const p of leafs) {
-    if (await pathExists(join(p, '.git'))) {
-      worktrees.push(p);
+async function cmdList({ rootDir, args }) {
+  const component = args[0];
+  if (!component) {
+    const results = [];
+    for (const c of DEFAULT_COMPONENTS) {
+      results.push(await cmdListOne({ rootDir, component: c }));
     }
+    return { components: DEFAULT_COMPONENTS, results };
   }
-  return { component, activeDir: active, worktrees };
+  return await cmdListOne({ rootDir, component });
 }
 
 async function main() {
@@ -1616,7 +1696,7 @@ async function main() {
         '  happys wt migrate [--json]',
         '  happys wt sync <component> [--remote=<name>] [--json]',
         '  happys wt sync-all [--remote=<name>] [--json]',
-        '  happys wt list <component> [--json]',
+        '  happys wt list [component] [--json]',
         '  happys wt new <component> <slug> [--from=upstream|origin] [--remote=<name>] [--base=<ref>|--base-worktree=<spec>] [--deps=none|link|install|link-or-install] [--use] [--force] [--interactive|-i] [--json]',
         '  happys wt duplicate <component> <fromWorktreeSpec|path|active|default> <newSlug> [--remote=<name>] [--deps=none|link|install|link-or-install] [--use] [--json]',
         '  happys wt pr <component> <pr-url|number> [--remote=upstream] [--slug=<name>] [--deps=none|link|install|link-or-install] [--use] [--update] [--stash|--stash-keep] [--force] [--json]',
@@ -1637,7 +1717,7 @@ async function main() {
         '  "<absolute path>": explicit checkout path',
         '',
         'components:',
-        '  happy | happy-cli | happy-server-light | happy-server',
+        `  ${DEFAULT_COMPONENTS.join(' | ')}`,
       ].join('\n'),
     });
     return;
@@ -1796,9 +1876,15 @@ async function main() {
     if (json) {
       printResult({ json, data: res });
     } else {
-      const lines = [`[wt] ${res.component} worktrees:`, `- active: ${res.activeDir}`];
-      for (const p of res.worktrees) {
-        lines.push(`- ${p}`);
+      const results = Array.isArray(res?.results) ? res.results : [res];
+      const lines = [];
+      for (const r of results) {
+        lines.push(`[wt] ${r.component} worktrees:`);
+        lines.push(`- active: ${r.activeDir}`);
+        for (const p of r.worktrees) {
+          lines.push(`- ${p}`);
+        }
+        lines.push('');
       }
       printResult({ json: false, text: lines.join('\n') });
     }

package/scripts/utils/dev/expo_web.mjs

@@ -1,112 +0,0 @@
-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 };
-}