happy-stacks 0.3.0 → 0.5.0

package/docs/monorepo-migration.md

@@ -0,0 +1,286 @@
+# Monorepo migration (split repos → `slopus/happy`)
+
+This doc explains the **recommended, safe, step-by-step** flow to port commits from the legacy split repos (`happy`, `happy-cli`, `happy-server`) into the new `slopus/happy` monorepo layout:
+
+- old `happy` (UI) → `expo-app/`
+- old `happy-cli`  → `cli/`
+- old `happy-server` → `server/`
+
+The tooling used here is `happys monorepo port` (from this repo / Happy Stacks). It ports commits by generating patches (`git format-patch`) and applying them with `git am` into the target monorepo branch.
+
+## Quick start (if you don’t already use Happy Stacks)
+
+If you’re an external collaborator and you **don’t** have `happys` installed yet, this is the fastest “migration environment” setup:
+
+```bash
+npx happy-stacks init --install-path
+happys bootstrap --interactive
+happys stack new monorepo-merge --interactive
+```
+
+### “No install” option (npx-only, port command only)
+
+If you *only* want to run the port helper (and you already have local clones of the source repos + target monorepo), you can run it directly via `npx` without installing anything globally:
+
+```bash
+npx --yes happy-stacks monorepo port --help
+```
+
+Example:
+
+```bash
+npx --yes happy-stacks monorepo port \
+  --target=/abs/path/to/slopus-happy-monorepo \
+  --branch=your-port-branch \
+  --base=origin/main \
+  --3way \
+  --from-happy=/abs/path/to/old-happy \
+  --from-happy-base=origin/main
+```
+
+Notes:
+- This “npx-only” mode is great for **one-off ports**, but it won’t manage stacks/worktrees for you.
+- For the full guided flow (stacks + worktrees + repeatable commands), use the installed setup above.
+
+### Port helpers (guide / status / continue)
+
+Happy Stacks also provides small helpers that make conflict resolution less error-prone:
+
+```bash
+happys monorepo port guide
+happys monorepo port status --target=/abs/path/to/monorepo
+happys monorepo port continue --target=/abs/path/to/monorepo
+```
+
+- `port guide` is interactive (TTY required) and helps you build the initial port command safely.
+- `port guide` can also **pause on conflicts**, let you resolve them, and then resume until the port completes.
+- `port status` shows whether a `git am` session is in progress, the current patch subject, and conflicted files.
+- `port continue` runs `git am --continue` for the target repo (after you staged resolved files). If you started from `port guide`, it can also resume the remaining port automatically after each continue.
+
+How to bring “the changes you want to port” into this environment:
+
+- **If you already have local checkouts** of your legacy repos (recommended for forks/branches that aren’t PRs yet):
+  - keep them wherever they are
+  - you’ll pass their absolute paths to `happys monorepo port` via `--from-happy=...`, `--from-happy-cli=...`, etc.
+
+- **If your changes exist as GitHub PRs**, you can let Happy Stacks create a clean worktree from the PR directly:
+  - `happys wt pr happy-cli <pr-url-or-number> --use`
+  - `happys wt pr happy <pr-url-or-number> --use`
+  - (repeat for whichever repos your changes live in)
+
+Once you have:
+- a **target monorepo worktree** (from upstream), and
+- one or more **source repos** (paths or worktrees)
+
+…continue with the rest of this doc.
+
+## Prereqs
+
+- You have a **clean** source worktree/branch for each legacy repo you want to port.
+  - No uncommitted changes (unless you intentionally want to include them as new commits first).
+  - Ideally based on `upstream/main` (or you know the correct base ref).
+- You have a **clean** target monorepo checkout (a worktree of `slopus/happy`).
+- You are ready to resolve conflicts with `git am` (this is normal for large refactors, i18n changes, renamed files, etc).
+
+## Recommended workflow (interactive, safest)
+
+### 1) Create an isolated stack (don’t touch `main`)
+
+Pick a new stack name (example: `monorepo-merge`):
+
+```bash
+happys stack new monorepo-merge --interactive
+```
+
+### 2) Create a clean monorepo worktree from upstream
+
+Create a worktree based on `upstream/main` for the **monorepo** (`slopus/happy`):
+
+```bash
+happys wt new happy tmp/monorepo-port --from=upstream
+```
+
+Point your stack at that worktree (this keeps `main` stable):
+
+```bash
+happys stack wt monorepo-merge -- use happy /absolute/path/to/components/.worktrees/happy/slopus/tmp/monorepo-port
+```
+
+Notes:
+- In monorepo mode, `happy`, `happy-cli`, and `happy-server` are **one git repo**; the stack overrides should point at the same monorepo root.
+- `happys ... wt use happy <monorepo-root>` automatically updates all three component dir overrides together (prevents UI/CLI/server version skew).
+- If you pass a monorepo root, Happy Stacks normalizes component dirs to:
+  - `happy` → `.../expo-app`
+  - `happy-cli` → `.../cli`
+  - `happy-server` → `.../server`
+
+### 3) Create a target branch
+
+In the monorepo worktree, create your migration branch from `upstream/main`:
+
+```bash
+happys wt git happy slopus/tmp/monorepo-port -- checkout -b <your-branch-name> upstream/main
+```
+
+Example:
+
+```bash
+happys wt git happy slopus/tmp/monorepo-port -- checkout -b leeroy-wip upstream/main
+```
+
+### 4) Port the UI commits (old `happy` → `expo-app/`)
+
+Run the port in **interactive mode**:
+
+- use `--onto-current` to apply onto the branch you already checked out
+- use `--3way` so git can do a 3-way merge and produce conflict markers instead of failing immediately
+- **do not** use `--continue-on-failure` (you want it to stop at the first conflict)
+
+```bash
+happys monorepo port \
+  --target=/abs/path/to/monorepo-root \
+  --onto-current \
+  --3way \
+  --from-happy=/abs/path/to/old-happy-repo \
+  --from-happy-base=upstream/main
+```
+
+What `--from-happy-base` means:
+- It’s the ref used to compute the patch range (`merge-base(base, HEAD)..HEAD`).
+- If your branch is based on `upstream/main`, this should be `upstream/main`.
+
+### 5) Resolve conflicts (when the port stops)
+
+If the port stops, you are now in a normal `git am` session.
+
+Helpful commands:
+
+```bash
+git am --show-current-patch=diff
+git status
+```
+
+Fix conflicts in the files with conflict markers:
+- look for `<<<<<<<`, `=======`, `>>>>>>>`
+- edit to the desired final content
+- then stage the resolved files:
+
+```bash
+git add <file...>
+git am --continue
+```
+
+If you decide a specific patch should not be ported:
+
+```bash
+git am --skip
+```
+
+If you want to fully abort the current patch application:
+
+```bash
+git am --abort
+```
+
+Then rerun the `happys monorepo port ... --onto-current ...` command.
+
+### 6) Port the CLI commits (old `happy-cli` → `cli/`)
+
+After the UI port completes, port CLI commits onto the same branch:
+
+```bash
+happys monorepo port \
+  --target=/abs/path/to/monorepo-root \
+  --onto-current \
+  --3way \
+  --from-happy-cli=/abs/path/to/old-happy-cli-repo \
+  --from-happy-cli-base=upstream/main
+```
+
+Resolve conflicts the same way (`git am --continue`).
+
+### 7) Verify what landed
+
+Quick sanity checks:
+
+```bash
+# ensure upstream/main is an ancestor of your branch
+git merge-base --is-ancestor upstream/main HEAD
+
+# list commits introduced by the port
+git log --oneline upstream/main..HEAD
+```
+
+If you are porting multiple legacy branches, it’s often useful to compare counts:
+
+```bash
+git rev-list --count upstream/main..HEAD
+```
+
+### 8) Push and open a PR
+
+Push to the remote you intend to PR against (example uses `upstream`):
+
+```bash
+git push upstream HEAD:<branch-name>
+```
+
+## Common failures (expected) and what to do
+
+### “target repo is not clean”
+
+`happys monorepo port` refuses to run when the target has local changes.
+
+Fix: commit, stash, or reset your target worktree, then re-run.
+
+### “a git am operation is already in progress”
+
+You have an unfinished `git am` session from a previous attempt.
+
+Fix it first:
+
+```bash
+git am --continue   # after resolving conflicts
+# or
+git am --abort
+```
+
+Then re-run `happys monorepo port ...`.
+
+### “patch does not apply” / i18n churn / renamed files
+
+This usually means upstream moved and the patch context no longer matches.
+
+Recommended: rerun with `--3way` (3-way merge) so you get conflict markers to resolve.
+
+### “already exists in working directory”
+
+This often happens when a commit (especially “new file”) was already folded into the monorepo history.
+
+The tool auto-skips:
+- patches that are already present (exact-match reverse apply check)
+- pure new-file patches when the target already contains identical content
+
+If you still hit this manually during a stopped `git am`, decide whether to:
+- keep the existing file and `git am --skip`, or
+- reconcile content and continue.
+
+### Missing file path errors
+
+If the patch references files that no longer exist (or moved) in the monorepo, you’ll need to:
+- map the change to the new file location, or
+- skip that patch if it’s obsolete.
+
+Use `git am --show-current-patch=diff` to understand intent, then implement the equivalent change in the monorepo layout and continue.
+
+## Optional: audit mode (best-effort report)
+
+If you want a full report of what would apply vs fail (without stopping at the first conflict), you can run:
+
+```bash
+happys monorepo port ... --continue-on-failure --json
+```
+
+This is **not** the recommended way to produce a final clean branch, but it can be useful to:
+- discover the full set of expected conflicts
+- share a machine-readable report for assistance

package/docs/server-flavors.md

@@ -4,7 +4,21 @@ Happy Stacks supports two server “flavors”. You can switch between them glob
 
 ## What’s the difference?
 
-Both are forks/flavors of the same upstream server repo (`slopus/happy-server`), but optimized for different use cases:
+Both are forks/flavors of the same upstream server repo (`slopus/happy-server`), but optimized for different use cases.
+
+### Unified codebase (recommended)
+
+When your `happy-server` checkout includes the light flavor artifacts (notably `prisma/sqlite/schema.prisma` — legacy: `prisma/schema.sqlite.prisma`), Happy Stacks treats it as a **single unified server codebase** that supports both:
+
+- `happy-server` (full / Postgres+Redis+S3)
+- `happy-server-light` (light / SQLite+local files, can serve UI)
+
+In that setup:
+
+- there is **no server code duplication**
+- `happy-server-light` can point at the **same checkout/worktree** as `happy-server`
+- `happys stack new` will default to pinning **both** server component dirs to the same path
+- `happys start/dev --server=happy-server-light` will run `start:light` / `dev:light` when available
 
 - **`happy-server-light`** (recommended default)
   - optimized for local usage
@@ -73,7 +87,7 @@ Notes:
 - **`happys start`** is “production-like”. It avoids running heavyweight schema sync loops under launchd KeepAlive.
 - **`happys dev`** is for rapid iteration:
   - for `happy-server`: Happy Stacks runs `prisma migrate deploy` by default (configurable via `HAPPY_STACKS_PRISMA_MIGRATE`).
-  - for `happy-server-light`: the upstream dev script runs `prisma db push` by default (configurable via `HAPPY_STACKS_PRISMA_PUSH`).
+  - for `happy-server-light`: Happy Stacks runs `prisma migrate deploy` (SQLite migrations) using the unified schema under `prisma/sqlite/schema.prisma`.
 
 Important: for a given run (`happys start` / `happys dev`) you choose **one** flavor.
 
@@ -125,7 +139,9 @@ There are two separate concepts:
   - controlled by `HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT` and `HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER`
   - easiest via `happys wt use happy-server-light ...` / `happys wt use happy-server ...`
 
-If you set `HAPPY_STACKS_SERVER_COMPONENT=happy-server-light` but accidentally point the *server-light component dir* at a `happy-server` worktree (or vice versa), `happys start/dev/doctor` will refuse to run and print a fix hint.
+If you set `HAPPY_STACKS_SERVER_COMPONENT=happy-server-light` but accidentally point the *server-light component dir* at a postgres-only `happy-server` checkout (or vice versa), `happys start/dev/doctor` will refuse to run and print a fix hint.
+
+In unified mode (same repo supports both flavors), it is valid (and recommended) for both component dirs to point at the same checkout.
 
 `happys wt use` also prevents the most common mismatch when selecting server worktrees inside `components/` / `components/.worktrees/`.
 

package/docs/stacks.md

@@ -238,6 +238,41 @@ Cloned-repo fallback (before you run `happys init`):
 2. `<repo>/env.local` (optional overrides)
 3. `HAPPY_STACKS_ENV_FILE` (stack env)
 
+## Manage per-stack environment variables (including API keys)
+
+To add/update environment variables in a stack env file from the CLI:
+
+```bash
+happys stack env <stack> set KEY=VALUE [KEY2=VALUE2...]
+```
+
+To remove keys:
+
+```bash
+happys stack env <stack> unset KEY [KEY2...]
+```
+
+To inspect:
+
+```bash
+happys stack env <stack> get KEY
+happys stack env <stack> list
+happys stack env <stack> path
+```
+
+Notes:
+
+- This is the recommended place for **provider API keys** the daemon needs (example: `OPENAI_API_KEY`).
+- Changes apply on the **next start** of the stack/daemon. Restart to pick them up:
+  - `main`: `happys start --restart`
+  - named stack: `happys stack start <stack> -- --restart` (or `happys stack dev <stack> -- --restart`)
+
+Self-host shortcut (defaults to `main` when not running under a stack wrapper):
+
+```bash
+happys env set OPENAI_API_KEY=sk-...
+```
+
 ## Daemon auth + “no machine” on first run
 
 On a **fresh machine** (or any new stack), the daemon may need to authenticate before it can register a “machine”.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "happy-stacks",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "packageManager": "pnpm@10.18.3",
   "bin": {
     "happys": "./bin/happys.mjs",
@@ -55,5 +55,9 @@
     "menubar:install": "node ./scripts/menubar.mjs install",
     "menubar:uninstall": "node ./scripts/menubar.mjs uninstall",
     "menubar:open": "bash -lc 'DIR=\"$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)\"; if [[ -z \"$DIR\" ]]; then DIR=\"$HOME/Library/Application Support/SwiftBar/Plugins\"; fi; open \"$DIR\"'"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4",
+    "qrcode-terminal": "^0.12.0"
   }
 }

package/scripts/auth.mjs

@@ -16,6 +16,7 @@ import { dirname } from 'node:path';
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
 import { ensureDepsInstalled, pmExecBin } from './utils/proc/pm.mjs';
 import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/server/infra/happy_server_infra.mjs';
+import { resolvePrismaClientImportForServerComponent, resolveServerLightPrismaMigrateDeployArgs } from './utils/server/flavor_scripts.mjs';
 import { clearDevAuthKey, readDevAuthKey, writeDevAuthKey } from './utils/auth/dev_key.mjs';
 import { getExpoStatePaths, isStateProcessRunning } from './utils/expo/expo.mjs';
 import { resolveAuthSeedFromEnv } from './utils/stack/startup.mjs';
@@ -32,7 +33,7 @@ import {
   getServerLightDataDirFromEnvOrDefault,
   resolveCliHomeDir,
 } from './utils/stack/dirs.mjs';
-import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+import { resolveLocalhostHost, preferStackLocalhostUrl } from './utils/paths/localhost_host.mjs';
 
 function getInternalServerUrlCompat() {
   const { port, internalServerUrl } = getInternalServerUrl({ env: process.env, defaultPort: 3005 });
@@ -45,9 +46,9 @@ async function resolveWebappUrlFromRunningExpo({ rootDir, stackName }) {
     const uiDir = getComponentDir(rootDir, 'happy');
     const uiPaths = getExpoStatePaths({
       baseDir,
-      kind: 'ui-dev',
+      kind: 'expo-dev',
       projectDir: uiDir,
-      stateFileName: 'ui.state.json',
+      stateFileName: 'expo.state.json',
     });
     const uiRunning = await isStateProcessRunning(uiPaths.statePath);
     if (!uiRunning.running) return null;
@@ -227,6 +228,15 @@ async function seedAccountsFromSourceDbToTargetDb({
   const sourceCwd = resolveServerComponentDir({ rootDir, serverComponent: fromServerComponent });
   const targetCwd = resolveServerComponentDir({ rootDir, serverComponent: targetServerComponent });
 
+  const sourceClientImport = resolvePrismaClientImportForServerComponent({
+    serverComponentName: fromServerComponent,
+    serverDir: sourceCwd,
+  });
+  const targetClientImport = resolvePrismaClientImportForServerComponent({
+    serverComponentName: targetServerComponent,
+    serverDir: targetCwd,
+  });
+
   const listScript = `
 process.on('uncaughtException', (e) => {
   console.error(e instanceof Error ? e.message : String(e));
@@ -236,7 +246,11 @@ process.on('unhandledRejection', (e) => {
   console.error(e instanceof Error ? e.message : String(e));
   process.exit(1);
 });
-import { PrismaClient } from '@prisma/client';
+const mod = await import(${JSON.stringify(sourceClientImport)});
+const PrismaClient = mod?.PrismaClient ?? mod?.default?.PrismaClient;
+if (!PrismaClient) {
+  throw new Error('Failed to load PrismaClient for DB seed (source).');
+}
 const db = new PrismaClient();
 try {
   const accounts = await db.account.findMany({ select: { id: true, publicKey: true } });
@@ -255,7 +269,11 @@ process.on('unhandledRejection', (e) => {
   console.error(e instanceof Error ? e.message : String(e));
   process.exit(1);
 });
-import { PrismaClient } from '@prisma/client';
+const mod = await import(${JSON.stringify(targetClientImport)});
+const PrismaClient = mod?.PrismaClient ?? mod?.default?.PrismaClient;
+if (!PrismaClient) {
+  throw new Error('Failed to load PrismaClient for DB seed (target).');
+}
 import fs from 'node:fs';
 const FORCE = ${force ? 'true' : 'false'};
 const raw = fs.readFileSync(0, 'utf8').trim();
@@ -580,7 +598,7 @@ async function cmdCopyFrom({ argv, json }) {
       const managed = (targetEnv.HAPPY_STACKS_MANAGED_INFRA ?? targetEnv.HAPPY_LOCAL_MANAGED_INFRA ?? '1').toString().trim() !== '0';
       if (targetServerComponent === 'happy-server' && withInfra && managed) {
         const { port } = getInternalServerUrlCompat();
-        const publicServerUrl = `http://localhost:${port}`;
+        const publicServerUrl = await preferStackLocalhostUrl(`http://localhost:${port}`, { stackName });
         const envPath = resolveStackEnvPath(stackName).envPath;
         const infra = await ensureHappyServerManagedInfra({
           stackName,
@@ -633,7 +651,7 @@ async function cmdCopyFrom({ argv, json }) {
           await pmExecBin({
             dir: serverDirForPrisma,
             bin: 'prisma',
-            args: ['db', 'push'],
+            args: resolveServerLightPrismaMigrateDeployArgs({ serverDir: serverDirForPrisma }),
             env: { ...process.env, DATABASE_URL: targetDatabaseUrl },
             quiet: json,
           }).catch(() => {});
@@ -689,6 +707,7 @@ async function cmdStatus({ json }) {
     defaultPublicUrl,
     envPublicUrl,
     allowEnable: false,
+    stackName,
   });
 
   const cliHomeDir = resolveCliHomeDir();
@@ -770,7 +789,7 @@ async function cmdStatus({ json }) {
 async function cmdLogin({ argv, json }) {
   const rootDir = getRootDir(import.meta.url);
   const stackName = getStackName();
-  const { kv } = parseArgs(argv);
+  const { flags, kv } = parseArgs(argv);
 
   const { port, url: internalServerUrl } = getInternalServerUrlCompat();
   const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port, stackName });
@@ -779,10 +798,12 @@ async function cmdLogin({ argv, json }) {
     defaultPublicUrl,
     envPublicUrl,
     allowEnable: false,
+    stackName,
   });
   const { envWebappUrl } = getWebappUrlEnvOverride({ env: process.env, stackName });
   const expoWebappUrl = await resolveWebappUrlFromRunningExpo({ rootDir, stackName });
-  const webappUrl = envWebappUrl || expoWebappUrl || publicServerUrl;
+  const webappUrlRaw = envWebappUrl || expoWebappUrl || publicServerUrl;
+  const webappUrl = await preferStackLocalhostUrl(webappUrlRaw, { stackName });
   const webappUrlSource = expoWebappUrl ? 'expo' : envWebappUrl ? 'stack env override' : 'server';
 
   const cliHomeDir = resolveCliHomeDir();
@@ -818,7 +839,8 @@ async function cmdLogin({ argv, json }) {
     return;
   }
 
-  if (!json) {
+  const quietUx = flags.has('--quiet') || flags.has('--no-ux');
+  if (!json && !quietUx) {
     printAuthLoginInstructions({
       stackName,
       context,

package/scripts/build.mjs

@@ -1,18 +1,21 @@
 import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { componentDirEnvKey, getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
 import { ensureDepsInstalled, pmExecBin, requireDir } from './utils/proc/pm.mjs';
 import { resolveServerPortFromEnv } from './utils/server/urls.mjs';
 import { dirname, join } from 'node:path';
 import { readFile, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tailscaleServeHttpsUrl } from './tailscale.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, wantsExpoClearCache } from './utils/expo/expo.mjs';
+import { expoExec } from './utils/expo/command.mjs';
+import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
 
 /**
  * Build a lightweight static web UI bundle (no Expo dev server).
  *
  * Output directory default: ~/.happy/stacks/main/ui (legacy: ~/.happy/local/ui)
- * Server will serve it at / when HAPPY_SERVER_LIGHT_UI_DIR is set.
+ * Server will serve it at / when HAPPY_SERVER_UI_DIR is set.
  * (Legacy /ui paths are redirected to /.)
  */
 
@@ -29,12 +32,29 @@ async function main() {
         '  happys build [--tauri] [--json]',
         '  (legacy in a cloned repo): pnpm build [-- --tauri] [--json]',
         '  node scripts/build.mjs [--tauri|--no-tauri] [--no-ui] [--json]',
+        '',
+        'note:',
+        '  If run from inside the Happy UI checkout/worktree, the build uses that checkout.',
       ].join('\n'),
     });
     return;
   }
   const rootDir = getRootDir(import.meta.url);
 
+  // If invoked from inside the Happy UI checkout/worktree, prefer that directory without requiring `happys wt use ...`.
+  const inferred = inferComponentFromCwd({
+    rootDir,
+    invokedCwd: getInvokedCwd(process.env),
+    components: ['happy'],
+  });
+  if (inferred?.component === 'happy') {
+    const stacksKey = componentDirEnvKey('happy');
+    const legacyKey = stacksKey.replace(/^HAPPY_STACKS_/, 'HAPPY_LOCAL_');
+    if (!(process.env[stacksKey] ?? '').toString().trim() && !(process.env[legacyKey] ?? '').toString().trim()) {
+      process.env[stacksKey] = inferred.repoDir;
+    }
+  }
+
   // Optional: skip building the web UI bundle.
   //
   // This is useful for evidence capture flows that validate non-UI components (e.g. `happy-cli`)
@@ -87,7 +107,17 @@ async function main() {
   };
 
   // Expo CLI is available via node_modules/.bin once dependencies are installed.
-  await pmExecBin({ dir: uiDir, bin: 'expo', args: ['export', '--platform', 'web', '--output-dir', outDir], env });
+  {
+    const paths = getExpoStatePaths({
+      baseDir: getDefaultAutostartPaths().baseDir,
+      kind: 'ui-export',
+      projectDir: uiDir,
+      stateFileName: 'ui.export.state.json',
+    });
+    await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+    const args = ['export', '--platform', 'web', '--output-dir', outDir, ...(wantsExpoClearCache({ env }) ? ['-c'] : [])];
+    await expoExec({ dir: uiDir, args, env, ensureDepsLabel: 'happy' });
+  }
 
   if (json) {
     printResult({ json, data: { ok: true, outDir, tauriBuilt: false } });
@@ -146,13 +176,30 @@ async function main() {
   };
   delete tauriEnv.EXPO_PUBLIC_WEB_BASE_URL;
 
-  await pmExecBin({
+  {
+    const paths = getExpoStatePaths({
+      baseDir: getDefaultAutostartPaths().baseDir,
+      kind: 'ui-export-tauri',
+      projectDir: uiDir,
+      stateFileName: 'ui.export.tauri.state.json',
+    });
+    await ensureExpoIsolationEnv({ env: tauriEnv, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+  }
+
+  await expoExec({
     dir: uiDir,
-    bin: 'expo',
-    // Important: clear bundler cache so EXPO_PUBLIC_* inlining doesn't reuse
-    // the previous (web) export's transform results.
-    args: ['export', '--platform', 'web', '--output-dir', tauriDistDir, '-c'],
+    args: [
+      'export',
+      '--platform',
+      'web',
+      '--output-dir',
+      tauriDistDir,
+      // Important: clear bundler cache so EXPO_PUBLIC_* inlining doesn't reuse
+      // the previous (web) export's transform results.
+      '-c',
+    ],
     env: tauriEnv,
+    ensureDepsLabel: 'happy',
   });
 
   // Build the Tauri app using a generated config that skips upstream beforeBuildCommand (which uses yarn).