@happier-dev/stack 0.1.0 → 0.2.0

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

@@ -0,0 +1,490 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, writeFile, chmod } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  buildStackTauriDevProcessInvocation,
+  buildTauriDevInvocation,
+  buildTauriRuntimeEnv,
+  resolveTauriDevUrl,
+} from './tauri_dev.mjs';
+import { getDefaultAutostartPaths } from '../paths/paths.mjs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const repoRootDir = resolve(join(__dirname, '../../../../..'));
+const stackRootDir = join(repoRootDir, 'apps', 'stack');
+
+function splitPathEntries(pathValue) {
+  return String(pathValue ?? '')
+    .split(process.platform === 'win32' ? ';' : ':')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+test('resolveTauriDevUrl points at the existing Expo dev server port', () => {
+  assert.equal(resolveTauriDevUrl({ expoPort: 8081 }), 'http://localhost:8081');
+});
+
+test('buildTauriDevInvocation disables beforeDevCommand and reuses the existing Expo dev url', () => {
+  const invocation = buildTauriDevInvocation({
+    expoPort: 8081,
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+  });
+
+  assert.equal(invocation.command, 'tauri');
+  assert.ok(invocation.args.includes('dev'));
+  assert.ok(invocation.args.includes('--no-dev-server-wait'));
+  assert.ok(invocation.args.includes('--config'));
+  assert.ok(invocation.args.includes('src-tauri/tauri.publicdev.conf.json'));
+
+  const overrideIndex = invocation.args.indexOf('-c');
+  assert.notEqual(overrideIndex, -1);
+  const overrideJson = JSON.parse(String(invocation.args[overrideIndex + 1] ?? '{}'));
+  assert.deepEqual(overrideJson, {
+    build: {
+      beforeDevCommand: '',
+      devUrl: 'http://localhost:8081',
+    },
+  });
+});
+
+test('buildStackTauriDevProcessInvocation launches tauri from apps/ui/src-tauri with the repo-local binary', () => {
+  const expectedTauriEntrypoint = join(repoRootDir, 'node_modules', '@tauri-apps', 'cli', 'tauri.js');
+
+  const invocation = buildStackTauriDevProcessInvocation({
+    rootDir: stackRootDir,
+    env: process.env,
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+    configOverride: {
+      build: {
+        beforeDevCommand: '',
+        devUrl: 'http://localhost:8081',
+      },
+    },
+  });
+
+  assert.equal(invocation.command, process.execPath);
+  assert.equal(invocation.args[0], expectedTauriEntrypoint);
+  assert.equal(invocation.args[1], 'dev');
+  const configIndex = invocation.args.indexOf('--config');
+  assert.notEqual(configIndex, -1);
+  assert.equal(invocation.args[configIndex + 1], 'tauri.publicdev.conf.json');
+  const overrideIndex = invocation.args.indexOf('-c');
+  assert.notEqual(overrideIndex, -1);
+  const overrideJson = JSON.parse(String(invocation.args[overrideIndex + 1] ?? '{}'));
+  assert.deepEqual(overrideJson, {
+    build: {
+      beforeDevCommand: '',
+      devUrl: 'http://localhost:8081',
+    },
+  });
+  assert.equal(invocation.cwd, join(repoRootDir, 'apps', 'ui', 'src-tauri'));
+});
+
+test('buildStackTauriDevProcessInvocation scopes the cargo target directory to the active stack', () => {
+  const stackName = 'codex-bootstrap-qa-24534';
+  const invocation = buildStackTauriDevProcessInvocation({
+    rootDir: stackRootDir,
+    env: {
+      ...process.env,
+      HAPPIER_STACK_STACK: stackName,
+    },
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+    configOverride: {
+      build: {
+        beforeDevCommand: '',
+        devUrl: 'http://localhost:8081',
+      },
+    },
+  });
+
+  assert.equal(
+    invocation.env?.CARGO_TARGET_DIR,
+    `${getDefaultAutostartPaths({ ...process.env, HAPPIER_STACK_STACK: stackName }).baseDir}/tauri-target`
+  );
+});
+
+test('buildStackTauriDevProcessInvocation uses the explicitly resolved UI dir even when stack env points elsewhere', async () => {
+  const explicitUiDir = join(repoRootDir, 'apps', 'ui');
+  const expectedTauriEntrypoint = join(repoRootDir, 'node_modules', '@tauri-apps', 'cli', 'tauri.js');
+  const fakeRepo = await mkdir(`${tmpdir()}/happier-tauri-bad-repo-${Date.now()}`, { recursive: true });
+
+  const invocation = buildStackTauriDevProcessInvocation({
+    rootDir: stackRootDir,
+    repoRootDir: repoRootDir,
+    uiDir: explicitUiDir,
+    env: {
+      ...process.env,
+      HAPPIER_STACK_REPO_DIR: fakeRepo,
+    },
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+    configOverride: {
+      build: {
+        beforeDevCommand: '',
+        devUrl: 'http://localhost:8081',
+      },
+    },
+  });
+
+  assert.equal(invocation.cwd, join(explicitUiDir, 'src-tauri'));
+  assert.equal(invocation.args[0], expectedTauriEntrypoint);
+});
+
+test('buildStackTauriDevProcessInvocation prepends the cargo bin directory when cargo is outside PATH', async () => {
+  const cargoHome = await mkdir(`${tmpdir()}/happier-tauri-cargo-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${cargoHome}/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const invocation = buildStackTauriDevProcessInvocation({
+    rootDir: stackRootDir,
+    env: {
+      ...process.env,
+      PATH: '/usr/bin:/bin',
+      CARGO_HOME: cargoHome,
+    },
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+    configOverride: {
+      build: {
+        beforeDevCommand: '',
+        devUrl: 'http://localhost:8081',
+      },
+    },
+  });
+
+  assert.match(String(invocation.env?.PATH ?? ''), new RegExp(`^${cargoBinDir.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+  const entries = splitPathEntries(invocation.env?.PATH);
+  assert.ok(entries.includes('/usr/bin'));
+  assert.ok(entries.includes('/bin'));
+  assert.equal(invocation.env?.CARGO, cargoBinary);
+});
+
+test('buildStackTauriDevProcessInvocation detects cargo under the real user home when HOME is stack-isolated', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-realhome-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-isolatedhome-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const invocation = buildStackTauriDevProcessInvocation({
+    rootDir: stackRootDir,
+    env: {
+      ...process.env,
+      PATH: '/usr/bin:/bin',
+      HOME: isolatedHome,
+      USERPROFILE: isolatedHome,
+    },
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+    configOverride: {
+      build: {
+        beforeDevCommand: '',
+        devUrl: 'http://localhost:8081',
+      },
+    },
+    resolveUserHomeDir: () => realHome,
+  });
+
+  const escapedCargoBinDir = cargoBinDir.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  assert.match(
+    String(invocation.env?.PATH ?? ''),
+    new RegExp(`^${escapedCargoBinDir}`)
+  );
+  assert.equal(invocation.env?.HOME, realHome);
+  assert.equal(invocation.env?.USERPROFILE, realHome);
+});
+
+test('buildStackTauriDevProcessInvocation prefers cargo under the resolved user home when HOME is isolated even if PATH contains a cargo shim', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-realhome-prefer-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-isolatedhome-prefer-${Date.now()}`, { recursive: true });
+  const realCargoBinDir = `${realHome}/.cargo/bin`;
+  const isolatedCargoBinDir = `${isolatedHome}/bin`;
+  await mkdir(realCargoBinDir, { recursive: true });
+  await mkdir(isolatedCargoBinDir, { recursive: true });
+
+  const cargoName = process.platform === 'win32' ? 'cargo.exe' : 'cargo';
+  const realCargoBinary = `${realCargoBinDir}/${cargoName}`;
+  const isolatedCargoBinary = `${isolatedCargoBinDir}/${cargoName}`;
+  await writeFile(realCargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await writeFile(isolatedCargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(realCargoBinary, 0o755);
+  await chmod(isolatedCargoBinary, 0o755);
+
+  const invocation = buildStackTauriDevProcessInvocation({
+    rootDir: stackRootDir,
+    env: {
+      ...process.env,
+      PATH: `${isolatedCargoBinDir}:/usr/bin:/bin`,
+      HOME: isolatedHome,
+      USERPROFILE: isolatedHome,
+    },
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+    configOverride: {
+      build: {
+        beforeDevCommand: '',
+        devUrl: 'http://localhost:8081',
+      },
+    },
+    resolveUserHomeDir: () => realHome,
+  });
+
+  const escapedCargoBinDir = realCargoBinDir.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  assert.match(String(invocation.env?.PATH ?? ''), new RegExp(`^${escapedCargoBinDir}`));
+});
+
+test('buildStackTauriDevProcessInvocation exports rustup homes for the detected user cargo toolchain', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-rustup-home-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-rustup-isolated-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const invocation = buildStackTauriDevProcessInvocation({
+    rootDir: stackRootDir,
+    env: {
+      ...process.env,
+      PATH: '/usr/bin:/bin',
+      HOME: isolatedHome,
+      USERPROFILE: isolatedHome,
+    },
+    configPath: 'src-tauri/tauri.publicdev.conf.json',
+    configOverride: {
+      build: {
+        beforeDevCommand: '',
+        devUrl: 'http://localhost:8081',
+      },
+    },
+    resolveUserHomeDir: () => realHome,
+  });
+
+  assert.equal(invocation.env?.CARGO_HOME, `${realHome}/.cargo`);
+  assert.equal(invocation.env?.RUSTUP_HOME, `${realHome}/.rustup`);
+});
+
+test('buildTauriRuntimeEnv infers rustup home when cargo comes from an explicit CARGO_HOME but HOME is isolated', async () => {
+  if (process.platform === 'win32') {
+    // Path inference uses `.cargo/bin` semantics on POSIX; keep Windows coverage in the invocation tests.
+    return;
+  }
+
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-rustup-infer-home-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-rustup-infer-isolated-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/cargo`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const env = buildTauriRuntimeEnv({
+    env: {
+      ...process.env,
+      HOME: isolatedHome,
+      USERPROFILE: isolatedHome,
+      PATH: '/usr/bin:/bin',
+      CARGO_HOME: `${realHome}/.cargo`,
+    },
+    resolveUserHomeDir: () => isolatedHome,
+  });
+
+  assert.equal(env.CARGO_HOME, `${realHome}/.cargo`);
+  assert.equal(env.RUSTUP_HOME, `${realHome}/.rustup`);
+});
+
+test('buildStackTauriDevProcessInvocation preserves the host PATH while keeping stack and cargo entries', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-host-path-home-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-host-path-isolated-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const originalPath = process.env.PATH;
+  process.env.PATH = `/host/bin${process.platform === 'win32' ? ';' : ':'}/usr/bin`;
+  try {
+    const invocation = buildStackTauriDevProcessInvocation({
+      rootDir: stackRootDir,
+      env: {
+        ...process.env,
+        PATH: '/stack/bin',
+        HOME: isolatedHome,
+        USERPROFILE: isolatedHome,
+      },
+      configPath: 'src-tauri/tauri.publicdev.conf.json',
+      configOverride: {
+        build: {
+          beforeDevCommand: '',
+          devUrl: 'http://localhost:8081',
+        },
+      },
+      resolveUserHomeDir: () => realHome,
+    });
+
+    const entries = splitPathEntries(invocation.env?.PATH);
+    const nodeBinDir = process.execPath.replace(/[/\\][^/\\]+$/, '');
+    assert.equal(entries[0], cargoBinDir);
+    assert.equal(entries[1], nodeBinDir);
+    assert.equal(entries[2], '/stack/bin');
+    assert.ok(entries.includes('/host/bin'));
+    assert.ok(entries.includes('/usr/bin'));
+  } finally {
+    process.env.PATH = originalPath;
+  }
+});
+
+test('buildTauriRuntimeEnv prepends the current Node binary directory for GUI-launched sidecars', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-node-path-home-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-node-path-isolated-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const originalPath = process.env.PATH;
+  process.env.PATH = '/host/bin:/usr/bin';
+  try {
+    const env = buildTauriRuntimeEnv({
+      env: {
+        ...process.env,
+        PATH: '/stack/bin',
+        HOME: isolatedHome,
+        USERPROFILE: isolatedHome,
+        CARGO_HOME: `${realHome}/.cargo`,
+      },
+      resolveUserHomeDir: () => realHome,
+    });
+
+    const entries = splitPathEntries(env.PATH);
+    assert.equal(entries[0], cargoBinDir);
+    assert.equal(entries[1], process.execPath.replace(/[/\\][^/\\]+$/, ''));
+    assert.ok(entries.includes('/stack/bin'));
+    assert.ok(entries.includes('/host/bin'));
+  } finally {
+    process.env.PATH = originalPath;
+  }
+});
+
+test('buildTauriRuntimeEnv replaces an invalid CARGO env var with the resolved cargo binary path', async () => {
+  if (process.platform === 'win32') {
+    // Environment variable semantics differ on Windows; keep the fix scoped to POSIX to avoid flaky shebang execution.
+    return;
+  }
+
+  const cargoHome = await mkdir(`${tmpdir()}/happier-tauri-invalid-cargo-env-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${cargoHome}/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/cargo`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const env = buildTauriRuntimeEnv({
+    env: {
+      ...process.env,
+      PATH: '/usr/bin:/bin',
+      CARGO_HOME: cargoHome,
+      CARGO: '/no/such/cargo',
+    },
+  });
+
+  assert.equal(env.CARGO, cargoBinary);
+});
+
+test('buildTauriRuntimeEnv overrides a non-path CARGO env var with the resolved cargo binary path', async () => {
+  if (process.platform === 'win32') {
+    // Environment variable semantics differ on Windows; keep the fix scoped to POSIX to avoid flaky shebang execution.
+    return;
+  }
+
+  const cargoHome = await mkdir(`${tmpdir()}/happier-tauri-nonpath-cargo-env-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${cargoHome}/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/cargo`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const env = buildTauriRuntimeEnv({
+    env: {
+      ...process.env,
+      PATH: '/usr/bin:/bin',
+      CARGO_HOME: cargoHome,
+      CARGO: 'cargo',
+    },
+  });
+
+  assert.equal(env.CARGO, cargoBinary);
+});
+
+test('buildStackTauriDevProcessInvocation fails fast with a friendly error when cargo is unavailable', async () => {
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-missing-cargo-${Date.now()}`, { recursive: true });
+  const originalPath = process.env.PATH;
+
+  process.env.PATH = '/usr/bin:/bin';
+  try {
+    assert.throws(
+      () =>
+        buildStackTauriDevProcessInvocation({
+          rootDir: stackRootDir,
+          env: {
+            ...process.env,
+            PATH: '/usr/bin:/bin',
+            HOME: isolatedHome,
+            USERPROFILE: isolatedHome,
+            CARGO_HOME: `${isolatedHome}/.cargo-missing`,
+          },
+          configPath: 'src-tauri/tauri.publicdev.conf.json',
+          configOverride: {
+            build: {
+              beforeDevCommand: '',
+              devUrl: 'http://localhost:8081',
+            },
+          },
+          resolveUserHomeDir: () => isolatedHome,
+        }),
+      /cargo.*not found/i
+    );
+  } finally {
+    process.env.PATH = originalPath;
+  }
+});
+
+test('buildStackTauriDevProcessInvocation rejects a cargo binary that cannot execute (prevents tauri cargo-metadata ENOENT)', async () => {
+  if (process.platform === 'win32') {
+    // The Windows path uses cargo.exe; exercising a broken executable is not portable in this suite.
+    return;
+  }
+
+  const cargoHome = await mkdir(`${tmpdir()}/happier-tauri-broken-cargo-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${cargoHome}/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/cargo`;
+  await writeFile(cargoBinary, '#!/no/such/interpreter\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  assert.throws(
+    () =>
+      buildStackTauriDevProcessInvocation({
+        rootDir: stackRootDir,
+        env: {
+          ...process.env,
+          PATH: '/usr/bin:/bin',
+          CARGO_HOME: cargoHome,
+        },
+        configPath: 'src-tauri/tauri.publicdev.conf.json',
+        configOverride: {
+          build: {
+            beforeDevCommand: '',
+            devUrl: 'http://localhost:8081',
+          },
+        },
+      }),
+    /cargo.*failed|cargo.*unable|cargo.*cannot/i
+  );
+});

package/scripts/utils/env/scrub_env.mjs

@@ -3,6 +3,12 @@ export const SANDBOX_PRESERVE_KEYS = [
   'HAPPIER_STACK_INVOKED_CWD',
   'HAPPIER_STACK_SANDBOX_DIR',
   'HAPPIER_STACK_SANDBOX_ALLOW_GLOBAL',
+  'HAPPIER_STACK_SANDBOX_WORKSPACE_DIR',
+  // Mobile review UX (safe to preserve; required so dev-client links target the correct app scheme).
+  'HAPPIER_STACK_DEV_CLIENT_SCHEME',
+  'HAPPIER_STACK_REVIEW_MOBILE_SCHEME',
+  'HAPPIER_STACK_MOBILE_SCHEME',
+  'HAPPIER_STACK_MOBILE_HOST',
   'HAPPIER_STACK_UPDATE_CHECK',
   'HAPPIER_STACK_UPDATE_CHECK_INTERVAL_MS',
   'HAPPIER_STACK_UPDATE_NOTIFY_INTERVAL_MS',
@@ -16,6 +22,7 @@ export const STACK_WRAPPER_PRESERVE_KEYS = [
   // Sandbox detection + policy.
   'HAPPIER_STACK_SANDBOX_DIR',
   'HAPPIER_STACK_SANDBOX_ALLOW_GLOBAL',
+  'HAPPIER_STACK_SANDBOX_WORKSPACE_DIR',
 
   // Sandbox-enforced dirs.
   'HAPPIER_STACK_CLI_ROOT_DISABLE',
@@ -40,6 +47,14 @@ export const STACK_WRAPPER_PRESERVE_KEYS = [
   // Safe global defaults.
   'HAPPIER_STACK_STACK_PORT_START',
 
+  // Explicit local runtime/build overrides for source-mode stack launches.
+  'HAPPIER_STACK_CLI_BUILD',
+  'HAPPIER_STACK_CLI_BUILD_MODE',
+  'HAPPIER_STACK_SKIP_REFRESH_DEPS',
+  'HAPPIER_STACK_DISABLE_REFRESH_DEPS',
+  'HAPPIER_STACK_ALLOW_REFRESH_DEPS',
+  'HAPPIER_STACK_SERVICE_ALLOW_REFRESH_DEPS',
+
   'HAPPIER_STACK_BIND_MODE',
   'HAPPIER_STACK_EXPO_HOST',
 
@@ -48,6 +63,12 @@ export const STACK_WRAPPER_PRESERVE_KEYS = [
   'HAPPIER_STACK_EXPO_DEV_PORT_STRATEGY',
   'HAPPIER_STACK_EXPO_DEV_PORT_BASE',
   'HAPPIER_STACK_EXPO_DEV_PORT_RANGE',
+
+  // Mobile review UX.
+  'HAPPIER_STACK_DEV_CLIENT_SCHEME',
+  'HAPPIER_STACK_REVIEW_MOBILE_SCHEME',
+  'HAPPIER_STACK_MOBILE_SCHEME',
+  'HAPPIER_STACK_MOBILE_HOST',
 ];
 
 export function scrubHappierStackEnv(

package/scripts/utils/expo/command.mjs

@@ -3,7 +3,75 @@ import { join } from 'node:path';
 import { ensureDepsInstalled, ensureWorkspacePackagesBuiltForComponent } from '../proc/pm.mjs';
 import { run } from '../proc/proc.mjs';
 import { spawnProc } from '../proc/proc.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths, wantsExpoClearCache } from './expo.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, resolveExpoTmpDir, wantsExpoClearCache } from './expo.mjs';
+import { coerceHappyMonorepoRootFromPath } from '../paths/paths.mjs';
+import { pathExists } from '../fs/fs.mjs';
+import { applyExpoNodeHeapEnv } from './expoNodeHeapEnv.mjs';
+
+const DEFAULT_EXPO_EXPORT_MAX_WORKERS_NONINTERACTIVE = 1;
+
+async function resolveExpoBin(runnerDir) {
+  const workspaceBin = join(runnerDir, 'node_modules', '.bin', 'expo');
+  if (await pathExists(workspaceBin)) return workspaceBin;
+
+  const monorepoRoot = coerceHappyMonorepoRootFromPath(runnerDir);
+  if (monorepoRoot) {
+    const rootBin = join(monorepoRoot, 'node_modules', '.bin', 'expo');
+    if (await pathExists(rootBin)) return rootBin;
+  }
+
+  return workspaceBin;
+}
+
+function hasFlag(args, name) {
+  const needle = String(name ?? '').trim();
+  if (!needle) return false;
+  for (const a of args ?? []) {
+    if (a === needle) return true;
+    if (typeof a === 'string' && a.startsWith(`${needle}=`)) return true;
+  }
+  return false;
+}
+
+function coerceNonNegativeInt(v) {
+  const n = Number(String(v ?? '').trim());
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+
+function parseExpoExportMaxWorkers(env) {
+  const raw = (env?.HAPPIER_STACK_EXPO_EXPORT_MAX_WORKERS ?? '').toString().trim();
+  if (!raw) return { explicit: false, value: null };
+  if (raw === '0') return { explicit: true, value: 0 };
+  const n = coerceNonNegativeInt(raw);
+  return { explicit: true, value: n };
+}
+
+function resolveDefaultExpoExportMaxWorkers() {
+  // Only apply a conservative default in non-interactive contexts, where Expo/Metro
+  // can be more sensitive to high worker fan-out (e.g. in Docker/CI).
+  const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (isInteractive) return null;
+  return DEFAULT_EXPO_EXPORT_MAX_WORKERS_NONINTERACTIVE;
+}
+
+function applyExpoExportMaxWorkersArgs(args, env) {
+  const a = Array.isArray(args) ? [...args] : [];
+  if (a[0] !== 'export') return a;
+  if (hasFlag(a, '--max-workers')) return a;
+
+  const { explicit, value } = parseExpoExportMaxWorkers(env);
+  if (explicit) {
+    // Explicit disable (0) or invalid value: do not inject a default.
+    if (value === 0 || value == null) return a;
+    a.push('--max-workers', String(value));
+    return a;
+  }
+
+  const def = resolveDefaultExpoExportMaxWorkers();
+  if (def == null) return a;
+  a.push('--max-workers', String(def));
+  return a;
+}
 
 export async function prepareExpoCommandEnv({
   baseDir,
@@ -14,7 +82,8 @@ export async function prepareExpoCommandEnv({
 }) {
   const env = { ...(baseEnv ?? process.env) };
   const paths = getExpoStatePaths({ baseDir, kind, projectDir, stateFileName });
-  await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+  const tmpDir = resolveExpoTmpDir({ env, defaultTmpDir: paths.tmpDir, kind, projectDir });
+  await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir });
   return { env, paths };
 }
 
@@ -44,8 +113,12 @@ export async function expoExec({
   await ensureDepsInstalled(runnerDir, ensureDepsLabel, { quiet, env });
   const workspaceDepsDir = projectDir ?? runnerDir;
   await ensureWorkspacePackagesBuiltForComponent(workspaceDepsDir, { quiet, env });
-  const expoBin = join(runnerDir, 'node_modules', '.bin', 'expo');
-  await run(expoBin, args, { cwd, env, stdio: quiet ? 'ignore' : 'inherit' });
+  const expoBin = await resolveExpoBin(runnerDir);
+  const effectiveEnv = applyExpoNodeHeapEnv(env, {
+    envKey: 'HAPPIER_STACK_EXPO_MAX_OLD_SPACE_SIZE_MB',
+  });
+  const effectiveArgs = applyExpoExportMaxWorkersArgs(args, effectiveEnv);
+  await run(expoBin, effectiveArgs, { cwd, env: effectiveEnv, stdio: quiet ? 'ignore' : 'inherit' });
 }
 
 export async function expoSpawn({
@@ -63,6 +136,10 @@ export async function expoSpawn({
   await ensureDepsInstalled(runnerDir, ensureDepsLabel, { quiet, env });
   const workspaceDepsDir = projectDir ?? runnerDir;
   await ensureWorkspacePackagesBuiltForComponent(workspaceDepsDir, { quiet, env });
-  const expoBin = join(runnerDir, 'node_modules', '.bin', 'expo');
-  return spawnProc(label, expoBin, args, env, { cwd, ...(options ?? {}) });
+  const expoBin = await resolveExpoBin(runnerDir);
+  const effectiveEnv = applyExpoNodeHeapEnv(env, {
+    envKey: 'HAPPIER_STACK_EXPO_MAX_OLD_SPACE_SIZE_MB',
+  });
+  const effectiveArgs = applyExpoExportMaxWorkersArgs(args, effectiveEnv);
+  return spawnProc(label, expoBin, effectiveArgs, effectiveEnv, { cwd, ...(options ?? {}) });
 }