happy-stacks 0.2.0 → 0.4.0

package/scripts/lint.mjs

@@ -1,36 +1,16 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { getComponentDir, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, requirePnpm } from './utils/pm.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run } from './utils/proc.mjs';
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { componentDirEnvKey, getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { detectPackageManagerCmd, pickFirstScript, readPackageJsonScripts } from './utils/proc/package_scripts.mjs';
+import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
 
 const DEFAULT_COMPONENTS = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
 
-async function detectPackageManagerCmd(dir) {
-  if (await pathExists(join(dir, 'yarn.lock'))) {
-    return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
-  }
-  await requirePnpm();
-  return { name: 'pnpm', cmd: 'pnpm', argsForScript: (script) => ['--silent', script] };
-}
-
-async function readScripts(dir) {
-  try {
-    const raw = await readFile(join(dir, 'package.json'), 'utf-8');
-    const pkg = JSON.parse(raw);
-    const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
-    return scripts;
-  } catch {
-    return null;
-  }
-}
-
 function pickLintScript(scripts) {
-  if (!scripts) return null;
   const candidates = [
     'lint',
     'lint:ci',
@@ -39,7 +19,7 @@ function pickLintScript(scripts) {
     'eslint',
     'eslint:check',
   ];
-  return candidates.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+  return pickFirstScript(scripts, candidates);
 }
 
 async function main() {
@@ -61,18 +41,37 @@ async function main() {
         'examples:',
         '  happys lint',
         '  happys lint happy happy-cli',
+        '',
+        'note:',
+        '  If run from inside a component checkout/worktree and no components are provided, defaults to that component.',
       ].join('\n'),
     });
     return;
   }
 
+  const rootDir = getRootDir(import.meta.url);
+
   const positionals = argv.filter((a) => !a.startsWith('--'));
-  const requested = positionals.length ? positionals : ['all'];
+  const inferred =
+    positionals.length === 0
+      ? inferComponentFromCwd({
+          rootDir,
+          invokedCwd: getInvokedCwd(process.env),
+          components: DEFAULT_COMPONENTS,
+        })
+      : null;
+  if (inferred) {
+    const stacksKey = componentDirEnvKey(inferred.component);
+    const legacyKey = stacksKey.replace(/^HAPPY_STACKS_/, 'HAPPY_LOCAL_');
+    if (!(process.env[stacksKey] ?? '').toString().trim() && !(process.env[legacyKey] ?? '').toString().trim()) {
+      process.env[stacksKey] = inferred.repoDir;
+    }
+  }
+
+  const requested = positionals.length ? positionals : inferred ? [inferred.component] : ['all'];
   const wantAll = requested.includes('all');
   const components = wantAll ? DEFAULT_COMPONENTS : requested;
 
-  const rootDir = getRootDir(import.meta.url);
-
   const results = [];
   for (const component of components) {
     if (!DEFAULT_COMPONENTS.includes(component)) {
@@ -86,7 +85,7 @@ async function main() {
       continue;
     }
 
-    const scripts = await readScripts(dir);
+    const scripts = await readPackageJsonScripts(dir);
     if (!scripts) {
       results.push({ component, ok: true, skipped: true, dir, reason: 'no package.json' });
       continue;

package/scripts/menubar.mjs

@@ -1,14 +1,15 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { cp, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
+import { getHappyStacksHomeDir, getRootDir } from './utils/paths/paths.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { normalizeProfile } from './utils/cli/normalize.mjs';
 
 async function ensureSwiftbarAssets({ cliRootDir }) {
   const homeDir = getHappyStacksHomeDir();
@@ -59,14 +60,6 @@ function removeSwiftbarPlugins({ patterns }) {
   return out || null;
 }
 
-function normalizeMenubarMode(raw) {
-  const v = String(raw ?? '').trim().toLowerCase();
-  if (!v) return '';
-  if (v === 'selfhost' || v === 'self-host' || v === 'self_host' || v === 'host') return 'selfhost';
-  if (v === 'dev' || v === 'developer') return 'dev';
-  return '';
-}
-
 async function main() {
   const rawArgv = process.argv.slice(2);
   const argv = rawArgv[0] === 'menubar' ? rawArgv.slice(1) : rawArgv;
@@ -128,7 +121,7 @@ async function main() {
   if (cmd === 'mode') {
     const positionals = argv.filter((a) => !a.startsWith('--'));
     const raw = positionals[1] ?? '';
-    const mode = normalizeMenubarMode(raw);
+    const mode = normalizeProfile(raw);
     if (!mode) {
       throw new Error('[menubar] usage: happys menubar mode <selfhost|dev> [--json]');
     }

package/scripts/migrate.mjs

@@ -1,17 +1,18 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { copyFile, mkdir, readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { createRequire } from 'node:module';
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { parseDotenv } from './utils/dotenv.mjs';
-import { ensureEnvFileUpdated } from './utils/env_file.mjs';
-import { resolveStackEnvPath } from './utils/paths.mjs';
-import { ensureDepsInstalled } from './utils/pm.mjs';
-import { ensureHappyServerManagedInfra, applyHappyServerMigrations } from './utils/happy_server_infra.mjs';
-import { runCapture } from './utils/proc.mjs';
-import { pickNextFreeTcpPort } from './utils/ports.mjs';
+import { ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { readEnvObjectFromFile } from './utils/env/read.mjs';
+import { resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { ensureHappyServerManagedInfra, applyHappyServerMigrations } from './utils/server/infra/happy_server_infra.mjs';
+import { runCapture } from './utils/proc/proc.mjs';
+import { pickNextFreeTcpPort } from './utils/net/ports.mjs';
+import { getEnvValue } from './utils/env/values.mjs';
 
 function usage() {
   return [
@@ -25,18 +26,7 @@ function usage() {
   ].join('\n');
 }
 
-async function readEnvObject(envPath) {
-  try {
-    const raw = await readFile(envPath, 'utf-8');
-    return Object.fromEntries(parseDotenv(raw).entries());
-  } catch {
-    return {};
-  }
-}
-
-function getEnvValue(env, key) {
-  return (env?.[key] ?? '').toString().trim();
-}
+const readEnvObject = readEnvObjectFromFile;
 
 function parseFileDatabaseUrl(url) {
   const raw = String(url ?? '').trim();
@@ -290,7 +280,7 @@ async function main() {
     throw new Error('[migrate] --to-stack is required');
   }
 
-  const rootDir = (await import('./utils/paths.mjs')).getRootDir(import.meta.url);
+  const rootDir = (await import('./utils/paths/paths.mjs')).getRootDir(import.meta.url);
   await migrateLightToServer({ rootDir, fromStack, toStack, includeFiles, force, json });
 }
 

package/scripts/mobile.mjs

@@ -1,12 +1,17 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { pickNextFreeTcpPort } from './utils/ports.mjs';
-import { run, runCapture, spawnProc } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/pm.mjs';
+import { run, runCapture, spawnProc } from './utils/proc/proc.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/proc/pm.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo.mjs';
-import { killProcessGroupOwnedByStack } from './utils/ownership.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths } from './utils/expo/expo.mjs';
+import { resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
+import { resolveMobileExpoConfig } from './utils/mobile/config.mjs';
+import { resolveStackContext } from './utils/stack/context.mjs';
+import { expoExec } from './utils/expo/command.mjs';
+import { ensureDevExpoServer } from './utils/dev/expo_dev.mjs';
+import { resolveMobileReachableServerUrl } from './utils/server/mobile_api_url.mjs';
+import { patchIosXcodeProjectsForSigningAndIdentity, resolveIosAppXcodeProjects } from './utils/mobile/ios_xcodeproj_patch.mjs';
 
 /**
  * Mobile dev helper for the embedded `components/happy` Expo app.
@@ -58,7 +63,7 @@ async function main() {
         '',
         'Notes:',
         '- This script is designed to avoid editing upstream `components/happy` config in-place.',
-        '- It sets EXPO_PUBLIC_HAPPY_SERVER_URL from HAPPY_STACKS_SERVER_URL (legacy: HAPPY_LOCAL_SERVER_URL) if provided.',
+        '- If you explicitly set HAPPY_STACKS_SERVER_URL (legacy: HAPPY_LOCAL_SERVER_URL), it bakes that URL into the app via EXPO_PUBLIC_HAPPY_SERVER_URL.',
       ].join('\n'),
     });
     return;
@@ -69,19 +74,6 @@ async function main() {
   await requireDir('happy', uiDir);
   await ensureDepsInstalled(uiDir, 'happy');
 
-  const sanitizeBundleIdSegment = (s) =>
-    (s ?? '')
-      .toString()
-      .trim()
-      .toLowerCase()
-      .replace(/[^a-z0-9-]+/g, '-')
-      .replace(/^-+|-+$/g, '') || 'user';
-
-  const defaultLocalBundleId = (() => {
-    const user = sanitizeBundleIdSegment(process.env.USER ?? process.env.USERNAME ?? 'user');
-    return `com.happy.local.${user}.dev`;
-  })();
-
   async function readXcdeviceList() {
     if (process.platform !== 'darwin') {
       return [];
@@ -96,21 +88,6 @@ async function main() {
   // Default to the existing dev bundle identifier, which is also registered as a URL scheme
   // (Info.plist includes `com.slopus.happy.dev`), so iOS will open the dev build instead of the App Store app.
   const appEnv = process.env.APP_ENV ?? kv.get('--app-env') ?? 'development';
-  const iosAppName =
-    kv.get('--ios-app-name') ??
-    process.env.HAPPY_STACKS_IOS_APP_NAME ??
-    process.env.HAPPY_LOCAL_IOS_APP_NAME ??
-    '';
-  const iosBundleId =
-    kv.get('--ios-bundle-id') ??
-    process.env.HAPPY_STACKS_IOS_BUNDLE_ID ??
-    process.env.HAPPY_LOCAL_IOS_BUNDLE_ID ??
-    defaultLocalBundleId;
-  const scheme =
-    kv.get('--scheme') ??
-    process.env.HAPPY_STACKS_MOBILE_SCHEME ??
-    process.env.HAPPY_LOCAL_MOBILE_SCHEME ??
-    iosBundleId;
   const host = kv.get('--host') ?? process.env.HAPPY_STACKS_MOBILE_HOST ?? process.env.HAPPY_LOCAL_MOBILE_HOST ?? 'lan';
   const portRaw = kv.get('--port') ?? process.env.HAPPY_STACKS_MOBILE_PORT ?? process.env.HAPPY_LOCAL_MOBILE_PORT ?? '8081';
   // Default behavior:
@@ -125,26 +102,56 @@ async function main() {
     APP_ENV: appEnv,
   };
 
+  const cfgBase = resolveMobileExpoConfig({ env });
+  const iosAppName = (kv.get('--ios-app-name') ?? cfgBase.iosAppName ?? '').toString();
+  const iosBundleId = (kv.get('--ios-bundle-id') ?? cfgBase.iosBundleId ?? '').toString();
+  const scheme = (kv.get('--scheme') ?? cfgBase.scheme ?? iosBundleId).toString();
+
   const autostart = getDefaultAutostartPaths();
-  const mobilePaths = getExpoStatePaths({
+  const stackCtx = resolveStackContext({ env, autostart });
+  const { stackMode, runtimeStatePath, stackName, envPath } = stackCtx;
+
+  // Ensure the built iOS app registers the same scheme we use for dev-client QR links.
+  // (Happy app reads EXPO_APP_SCHEME in app.config.js; default remains unchanged when unset.)
+  env.EXPO_APP_SCHEME = scheme;
+  // Ensure the app display name + bundle id are consistent with what we install.
+  // (app.config.js keeps upstream defaults unless these are explicitly set.)
+  if (iosAppName && iosAppName.trim()) {
+    env.EXPO_APP_NAME = iosAppName.trim();
+  }
+  if (iosBundleId && iosBundleId.trim()) {
+    env.EXPO_APP_BUNDLE_ID = iosBundleId.trim();
+  }
+
+  // Always isolate Expo home + TMPDIR to avoid cross-worktree cache pollution (and to keep sandbox runs contained).
+  const expoPaths = getExpoStatePaths({
     baseDir: autostart.baseDir,
-    kind: 'mobile-dev',
+    kind: 'expo-dev',
     projectDir: uiDir,
-    stateFileName: 'mobile.state.json',
+    stateFileName: 'expo.state.json',
   });
   await ensureExpoIsolationEnv({
     env,
-    stateDir: mobilePaths.stateDir,
-    expoHomeDir: mobilePaths.expoHomeDir,
-    tmpDir: mobilePaths.tmpDir,
+    stateDir: expoPaths.stateDir,
+    expoHomeDir: expoPaths.expoHomeDir,
+    tmpDir: expoPaths.tmpDir,
   });
 
   // Allow happy-stacks to define the default server URL baked into the app bundle.
   // This is read by the app via `process.env.EXPO_PUBLIC_HAPPY_SERVER_URL`.
-  const stacksServerUrl =
-    process.env.HAPPY_STACKS_SERVER_URL?.trim() || process.env.HAPPY_LOCAL_SERVER_URL?.trim() || '';
-  if (stacksServerUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
-    env.EXPO_PUBLIC_HAPPY_SERVER_URL = stacksServerUrl;
+  const serverPort = resolveServerPortFromEnv({ env, defaultPort: 3005 });
+  const allowEnableTailscale =
+    !stackMode || stackName === 'main' || (env.HAPPY_STACKS_TAILSCALE_SERVE ?? env.HAPPY_LOCAL_TAILSCALE_SERVE ?? '0').toString().trim() === '1';
+  const resolvedUrls = await resolveServerUrls({ env, serverPort, allowEnable: allowEnableTailscale });
+  if (resolvedUrls.publicServerUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
+    env.EXPO_PUBLIC_HAPPY_SERVER_URL = resolvedUrls.publicServerUrl;
+  }
+  if (env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
+    env.EXPO_PUBLIC_HAPPY_SERVER_URL = resolveMobileReachableServerUrl({
+      env,
+      serverUrl: env.EXPO_PUBLIC_HAPPY_SERVER_URL,
+      serverPort,
+    });
   }
 
   if (json) {
@@ -178,13 +185,12 @@ async function main() {
     if (shouldClean) {
       prebuildArgs.push('--clean');
     }
-    await pmExecBin({ dir: uiDir, bin: 'expo', args: prebuildArgs, env });
+    await expoExec({ dir: uiDir, args: prebuildArgs, env, ensureDepsLabel: 'happy' });
 
     // Always patch iOS props if iOS was generated.
     if (platform === 'ios' || platform === 'all') {
       const fs = await import('node:fs/promises');
       const podPropsPath = `${uiDir}/ios/Podfile.properties.json`;
-      const pbxprojPath = `${uiDir}/ios/Happydev.xcodeproj/project.pbxproj`;
       try {
         const raw = await fs.readFile(podPropsPath, 'utf-8');
         const json = JSON.parse(raw);
@@ -195,14 +201,17 @@ async function main() {
         // ignore if path missing (platform != ios)
       }
 
-      try {
-        const raw = await fs.readFile(pbxprojPath, 'utf-8');
-        const next = raw.replaceAll('IPHONEOS_DEPLOYMENT_TARGET = 15.1;', 'IPHONEOS_DEPLOYMENT_TARGET = 16.0;');
-        if (next !== raw) {
-          await fs.writeFile(pbxprojPath, next, 'utf-8');
+      const iosProjects = await resolveIosAppXcodeProjects({ uiDir });
+      for (const project of iosProjects) {
+        try {
+          const raw = await fs.readFile(project.pbxprojPath, 'utf-8');
+          const next = raw.replaceAll('IPHONEOS_DEPLOYMENT_TARGET = 15.1;', 'IPHONEOS_DEPLOYMENT_TARGET = 16.0;');
+          if (next !== raw) {
+            await fs.writeFile(project.pbxprojPath, next, 'utf-8');
+          }
+        } catch {
+          // ignore missing/invalid pbxproj; Expo will surface actionable errors if needed
         }
-      } catch {
-        // ignore missing pbxproj (unexpected)
       }
 
       // Ensure CocoaPods doesn't crash due to locale issues.
@@ -263,25 +272,9 @@ async function main() {
       // xcodebuild fails with:
       //   "Automatic signing is disabled ... pass -allowProvisioningUpdates"
       //
-      // We force Expo CLI to go through its signing configuration path by clearing DEVELOPMENT_TEAM,
-      // so it will re-set the team and include the provisioning flags.
-      try {
-        const fs = await import('node:fs/promises');
-        const pbxprojPath = `${uiDir}/ios/Happydev.xcodeproj/project.pbxproj`;
-        const raw = await fs.readFile(pbxprojPath, 'utf-8');
-        let next = raw.replaceAll(/^\s*DEVELOPMENT_TEAM = ".*";\s*$/gm, '');
-        next = next.replaceAll(/PRODUCT_BUNDLE_IDENTIFIER = [^;]+;/g, `PRODUCT_BUNDLE_IDENTIFIER = ${iosBundleId};`);
-        if (iosAppName && iosAppName.trim()) {
-          const name = iosAppName.trim();
-          const quoted = name.includes(' ') || name.includes('"') ? `"${name.replaceAll('"', '\\"')}"` : name;
-          next = next.replaceAll(/PRODUCT_NAME = [^;]+;/g, `PRODUCT_NAME = ${quoted};`);
-        }
-        if (next !== raw) {
-          await fs.writeFile(pbxprojPath, next, 'utf-8');
-        }
-      } catch {
-        // ignore
-      }
+      // We force Expo CLI to go through its signing configuration path by clearing any pre-existing
+      // team/profile identifiers, so it will re-set the team and include the provisioning flags.
+      await patchIosXcodeProjectsForSigningAndIdentity({ uiDir, iosBundleId, iosAppName });
     }
 
     const configuration = kv.get('--configuration') ?? 'Debug';
@@ -292,47 +285,39 @@ async function main() {
     // Ensure CocoaPods doesn't crash due to locale issues.
     env.LANG = env.LANG ?? 'en_US.UTF-8';
     env.LC_ALL = env.LC_ALL ?? 'en_US.UTF-8';
-    await pmExecBin({ dir: uiDir, bin: 'expo', args, env });
+    await expoExec({ dir: uiDir, args, env, ensureDepsLabel: 'happy' });
   }
 
   if (!shouldStartMetro) {
     return;
   }
 
-  const running = await isStateProcessRunning(mobilePaths.statePath);
-  if (!restart && running.running) {
-    // eslint-disable-next-line no-console
-    console.log(`[mobile] Metro already running for this stack/worktree (pid=${running.state.pid}, port=${running.state.port})`);
-    return;
-  }
-  if (restart && running.state?.pid) {
-    const prevPid = Number(running.state.pid);
-    const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || autostart.stackName;
-    const envPath = (process.env.HAPPY_STACKS_ENV_FILE ?? process.env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
-    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-mobile', json: true });
-    if (!res.killed) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[mobile] not stopping existing Metro pid=${prevPid} because it does not look stack-owned.\n` +
-          `[mobile] continuing by starting a new Metro on a free port.`
-      );
-    }
-  }
-
-  const requestedPort = Number.parseInt(String(portRaw), 10);
-  const startPort = Number.isFinite(requestedPort) && requestedPort > 0 ? requestedPort : 8081;
-  const portNumber = await pickNextFreeTcpPort(startPort);
-  env.RCT_METRO_PORT = String(portNumber);
+  // Unify Expo: one Expo dev server per stack/worktree. If dev mode already started Expo, we reuse it.
+  // If Expo is already running without dev-client enabled, we fail closed (no second Expo).
+  env.HAPPY_STACKS_EXPO_HOST = host;
+  env.HAPPY_LOCAL_EXPO_HOST = host;
+  env.HAPPY_STACKS_MOBILE_HOST = host;
+  env.HAPPY_LOCAL_MOBILE_HOST = host;
+  env.HAPPY_STACKS_MOBILE_SCHEME = scheme;
+  env.HAPPY_LOCAL_MOBILE_SCHEME = scheme;
+  env.HAPPY_STACKS_EXPO_DEV_PORT = String(portRaw);
+  env.HAPPY_LOCAL_EXPO_DEV_PORT = String(portRaw);
 
-  // Start Metro for a dev client.
-  // The critical part is --scheme: without it, Expo defaults to `exp+<slug>` (here `exp+happy`)
-  // which the App Store app also registers, so iOS can open the wrong app.
-  const args = ['start', '--dev-client', '--host', host, '--port', String(portNumber), '--scheme', scheme];
-  if (wantsExpoClearCache({ env })) {
-    args.push('--clear');
-  }
-  const child = await pmSpawnBin({ label: 'mobile', dir: uiDir, bin: 'expo', args, env });
-  await writePidState(mobilePaths.statePath, { pid: child.pid, port: portNumber, uiDir, startedAt: new Date().toISOString() });
+  const children = [];
+  await ensureDevExpoServer({
+    startUi: false,
+    startMobile: true,
+    uiDir,
+    autostart,
+    baseEnv: env,
+    apiServerUrl: env.EXPO_PUBLIC_HAPPY_SERVER_URL ?? '',
+    restart,
+    stackMode,
+    runtimeStatePath,
+    stackName,
+    envPath,
+    children,
+  });
 
   await new Promise(() => {});
 }

package/scripts/mobile_dev_client.mjs

@@ -0,0 +1,83 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { getRootDir } from './utils/paths/paths.mjs';
+import { join } from 'node:path';
+
+import { defaultDevClientIdentity } from './utils/mobile/identifiers.mjs';
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags }) || flags.has('--help') || argv.length === 0) {
+    printResult({
+      json,
+      data: {
+        flags: ['--device=<id-or-name>', '--clean', '--configuration=Debug|Release', '--json'],
+      },
+      text: [
+        '[mobile-dev-client] usage:',
+        '  happys mobile-dev-client --install [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
+        '',
+        'Notes:',
+        '- Installs a dedicated "Happy Stacks Dev" Expo dev-client app on your iPhone.',
+        '- This app is intended to be reused across stacks (no per-stack installs for dev-client).',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  if (!flags.has('--install')) {
+    printResult({
+      json,
+      data: { ok: false, error: 'missing_install_flag' },
+      text: '[mobile-dev-client] missing --install. Run: happys mobile-dev-client --help',
+    });
+    process.exit(1);
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const mobileScript = join(rootDir, 'scripts', 'mobile.mjs');
+
+  const device = kv.get('--device') ?? '';
+  const clean = flags.has('--clean');
+  const configuration = kv.get('--configuration') ?? 'Debug';
+
+  const id = defaultDevClientIdentity({ user: process.env.USER ?? process.env.USERNAME ?? 'user' });
+
+  const args = [
+    mobileScript,
+    '--app-env=development',
+    `--ios-app-name=${id.iosAppName}`,
+    `--ios-bundle-id=${id.iosBundleId}`,
+    `--scheme=${id.scheme}`,
+    '--prebuild',
+    ...(clean ? ['--clean'] : []),
+    '--run-ios',
+    `--configuration=${configuration}`,
+    '--no-metro',
+    ...(device ? [`--device=${device}`] : []),
+  ];
+
+  const env = {
+    ...process.env,
+    // Ensure Expo app config uses the dev-client scheme.
+    EXPO_APP_SCHEME: id.scheme,
+    // Ensure per-stack storage isolation is available during dev-client usage.
+    EXPO_PUBLIC_HAPPY_STORAGE_SCOPE: process.env.EXPO_PUBLIC_HAPPY_STORAGE_SCOPE ?? '',
+  };
+
+  const out = await run(process.execPath, args, { cwd: rootDir, env });
+  if (json) {
+    printResult({ json, data: { ok: true, installed: true, identity: id, out } });
+  }
+}
+
+main().catch((err) => {
+  console.error('[mobile-dev-client] failed:', err);
+  process.exit(1);
+});
+

package/scripts/provision/linux-ubuntu-review-pr.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Provision a fresh Ubuntu VM for running happy-local's `review-pr` end-to-end.
+# Intended for Apple Silicon users running Ubuntu ARM64 via Lima/UTM.
+#
+# This installs:
+# - Node (via nvm)
+# - corepack (yarn/pnpm shims)
+# - basic build tooling for native deps used by Expo/React Native ecosystem
+
+if [[ "$(uname -s)" != "Linux" ]]; then
+  echo "[provision] expected Linux; got: $(uname -s)" >&2
+  exit 1
+fi
+
+export DEBIAN_FRONTEND=noninteractive
+
+echo "[provision] installing apt dependencies..."
+sudo apt-get update -y
+sudo apt-get install -y \
+  ca-certificates \
+  curl \
+  git \
+  build-essential \
+  python3 \
+  pkg-config
+
+echo "[provision] installing nvm + Node..."
+export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+if [[ ! -s "$NVM_DIR/nvm.sh" ]]; then
+  mkdir -p "$NVM_DIR"
+  curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+fi
+
+# shellcheck disable=SC1090
+source "$NVM_DIR/nvm.sh"
+
+# Use a modern Node; match the repo's expectations if it ever adds .nvmrc.
+NODE_VERSION="${NODE_VERSION:-22}"
+nvm install "$NODE_VERSION"
+nvm use "$NODE_VERSION"
+
+echo "[provision] enabling corepack..."
+corepack enable >/dev/null 2>&1 || true
+
+echo "[provision] done."
+echo "[provision] Node: $(node --version)"
+echo "[provision] npm:  $(npm --version)"
+echo "[provision] git:  $(git --version)"
+