happy-stacks 0.3.0 → 0.4.0

package/README.md

@@ -150,6 +150,7 @@ More details + automation: `[docs/remote-access.md](docs/remote-access.md)`.
 - **Scripts**: `scripts/*.mjs` (bootstrap/dev/start/build/stacks/worktrees/service/tailscale/mobile)
 - **Components**: `components/*` (each is its own Git repo)
 - **Worktrees**: `components/.worktrees/<component>/<owner>/<branch...>`
+- **CWD-scoped commands**: if you run `happys test/typecheck/lint` from inside a component checkout/worktree and omit components, it runs just that component; `happys build/dev/start` also prefer the checkout you’re currently inside.
 
 Components:
 
@@ -198,6 +199,12 @@ happys stack pr pr123 \
   --dev
 ```
 
+Optional: enable Expo dev-client for mobile reviewers (reuses the same Expo dev server; no second Metro process):
+
+```bash
+happys stack pr pr123 --happy=123 --happy-cli=456 --dev --mobile
+```
+
 Optional: run it in a self-contained sandbox folder (delete it to uninstall completely):
 
 ```bash
@@ -226,12 +233,16 @@ npx happy-stacks setup-pr \
   --happy-cli=https://github.com/slopus/happy-cli/pull/456
 ```
 
-Optional: run it in a self-contained sandbox folder (delete it to uninstall completely):
+Optional: enable Expo dev-client for mobile reviewers (works with both default `--dev` and `--start`):
 
 ```bash
-SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
-npx happy-stacks --sandbox-dir "$SANDBOX" setup-pr --happy=123 --happy-cli=456
-rm -rf "$SANDBOX"
+npx happy-stacks setup-pr --happy=123 --happy-cli=456 --mobile
+```
+
+Optional: run it in a self-contained sandbox folder (auto-cleaned):
+
+```bash
+npx happy-stacks review-pr --happy=123 --happy-cli=456
 ```
 
 Short form (PR numbers):
@@ -316,12 +327,20 @@ Details: `[docs/menubar.md](docs/menubar.md)`.
 #### Mobile iOS dev (optional)
 
 ```bash
-happys mobile --help
-happys mobile --json
+# Install the shared "Happy Stacks Dev" dev-client app on your iPhone:
+happys mobile-dev-client --install
+
+# Install an isolated per-stack app (Release config, unique bundle id + scheme):
+happys stack mobile:install <stack> --name="Happy (<stack>)"
 ```
 
 Details: `[docs/mobile-ios.md](docs/mobile-ios.md)`.
 
+#### Reviewing PRs in an isolated sandbox
+
+- **Unique hostname per run (default)**: `happys review-pr` generates a unique stack name by default, which results in a unique `happy-<stack>.localhost` hostname. This prevents browser storage collisions when the sandbox is deleted between runs.
+- **Reuse an existing sandbox**: if a previous run preserved a sandbox (e.g. `--keep-sandbox` or a failure in verbose mode), re-running `happys review-pr` offers an interactive choice to reuse it (keeping the same hostname + on-disk auth), or create a fresh sandbox.
+
 #### Tauri desktop app (optional)
 
 ```bash
@@ -338,7 +357,7 @@ Details: `[docs/tauri.md](docs/tauri.md)`.
   - (advanced) `happys bootstrap --interactive` (component installer wizard)
 - **Run**:
   - `happys start` (production-like; serves built UI via server-light)
-  - `happys dev` (dev; Expo web dev server for UI)
+  - `happys dev` (dev; Expo dev server for UI, optional dev-client via `--mobile`)
 - **Server flavor**:
   - `happys srv status`
   - `happys srv use --interactive`
@@ -352,7 +371,10 @@ Details: `[docs/tauri.md](docs/tauri.md)`.
   - `happys stack dev <name>` / `happys stack start <name>`
   - `happys stack edit <name> --interactive`
   - `happys stack wt <name> -- use --interactive`
+  - `happys stack review <name> [component...] [--reviewers=coderabbit,codex] [--base-ref=<ref>]`
   - `happys stack migrate`
+- **Reviews (local diff review)**:
+  - `happys review [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>]`
 - **Menu bar (SwiftBar)**:
   - `happys menubar install`
 

package/bin/happys.mjs

@@ -110,6 +110,42 @@ function stripGlobalOpt(argv, { name, aliases = [] }) {
   return { value: '', argv };
 }
 
+function applyVerbosityIfRequested(argv) {
+  // Global verbosity:
+  // - supports -v/-vv/-vvv anywhere before/after the command
+  // - supports --verbose and --verbose=N
+  //
+  // We set HAPPY_STACKS_VERBOSE (0-3) and strip these args so downstream scripts don't need to support them.
+  let level = Number.isFinite(Number(process.env.HAPPY_STACKS_VERBOSE)) ? Number(process.env.HAPPY_STACKS_VERBOSE) : null;
+  let next = [];
+  for (const a of argv) {
+    if (a === '-v' || a === '-vv' || a === '-vvv') {
+      const n = a.length - 1;
+      level = Math.max(level ?? 0, n);
+      continue;
+    }
+    if (a === '--verbose') {
+      level = Math.max(level ?? 0, 1);
+      continue;
+    }
+    if (a.startsWith('--verbose=')) {
+      const raw = a.slice('--verbose='.length).trim();
+      const n = Number(raw);
+      if (Number.isFinite(n)) {
+        level = Math.max(level ?? 0, Math.max(0, Math.min(3, Math.floor(n))));
+      } else {
+        level = Math.max(level ?? 0, 1);
+      }
+      continue;
+    }
+    next.push(a);
+  }
+  if (level != null) {
+    process.env.HAPPY_STACKS_VERBOSE = String(Math.max(0, Math.min(3, Math.floor(level))));
+  }
+  return next;
+}
+
 function applySandboxDirIfRequested(argv) {
   const explicit = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
   const { value, argv: nextArgv } = stripGlobalOpt(argv, { name: '--sandbox-dir', aliases: ['--sandbox'] });
@@ -117,6 +153,8 @@ function applySandboxDirIfRequested(argv) {
   if (!raw) return { argv: nextArgv, enabled: false };
 
   const sandboxDir = expandHome(raw);
+  const allowGlobalRaw = (process.env.HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL ?? '').trim().toLowerCase();
+  const allowGlobal = allowGlobalRaw === '1' || allowGlobalRaw === 'true' || allowGlobalRaw === 'yes' || allowGlobalRaw === 'y';
   // Keep all state under one folder that can be deleted to reset completely.
   const canonicalHomeDir = join(sandboxDir, 'canonical');
   const homeDir = join(sandboxDir, 'home');
@@ -124,23 +162,76 @@ function applySandboxDirIfRequested(argv) {
   const runtimeDir = join(sandboxDir, 'runtime');
   const storageDir = join(sandboxDir, 'storage');
 
+  // Sandbox isolation MUST win over any pre-exported Happy Stacks env vars.
+  // Otherwise sandbox runs can accidentally read/write "real" machine state.
+  //
+  // Keep only a tiny set of sandbox-safe globals; everything else should be driven by flags
+  // and stack env files inside the sandbox.
+  const preserved = new Map();
+  const keepKeys = [
+    'HAPPY_STACKS_VERBOSE',
+    'HAPPY_STACKS_INVOKED_CWD',
+    'HAPPY_STACKS_SANDBOX_DIR',
+    'HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL',
+    'HAPPY_STACKS_UPDATE_CHECK',
+    'HAPPY_STACKS_UPDATE_CHECK_INTERVAL_MS',
+    'HAPPY_STACKS_UPDATE_NOTIFY_INTERVAL_MS',
+  ];
+  for (const k of keepKeys) {
+    if (process.env[k] != null && String(process.env[k]).trim() !== '') {
+      preserved.set(k, process.env[k]);
+    }
+  }
+  for (const k of Object.keys(process.env)) {
+    if (k.startsWith('HAPPY_STACKS_') || k.startsWith('HAPPY_LOCAL_')) {
+      delete process.env[k];
+      continue;
+    }
+    // Also clear unprefixed Happy vars; sandbox commands should compute these from stack state.
+    if (k === 'HAPPY_HOME_DIR' || k === 'HAPPY_SERVER_URL' || k === 'HAPPY_WEBAPP_URL') {
+      delete process.env[k];
+    }
+  }
+  for (const [k, v] of preserved.entries()) {
+    process.env[k] = v;
+  }
+
   process.env.HAPPY_STACKS_SANDBOX_DIR = sandboxDir;
   process.env.HAPPY_STACKS_CLI_ROOT_DISABLE = '1'; // never re-exec into a user's "real" install when sandboxing
 
-  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR ?? canonicalHomeDir;
-  process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR = process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR ?? process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
-
-  process.env.HAPPY_STACKS_HOME_DIR = process.env.HAPPY_STACKS_HOME_DIR ?? homeDir;
-  process.env.HAPPY_LOCAL_HOME_DIR = process.env.HAPPY_LOCAL_HOME_DIR ?? process.env.HAPPY_STACKS_HOME_DIR;
-
-  process.env.HAPPY_STACKS_WORKSPACE_DIR = process.env.HAPPY_STACKS_WORKSPACE_DIR ?? workspaceDir;
-  process.env.HAPPY_LOCAL_WORKSPACE_DIR = process.env.HAPPY_LOCAL_WORKSPACE_DIR ?? process.env.HAPPY_STACKS_WORKSPACE_DIR;
-
-  process.env.HAPPY_STACKS_RUNTIME_DIR = process.env.HAPPY_STACKS_RUNTIME_DIR ?? runtimeDir;
-  process.env.HAPPY_LOCAL_RUNTIME_DIR = process.env.HAPPY_LOCAL_RUNTIME_DIR ?? process.env.HAPPY_STACKS_RUNTIME_DIR;
-
-  process.env.HAPPY_STACKS_STORAGE_DIR = process.env.HAPPY_STACKS_STORAGE_DIR ?? storageDir;
-  process.env.HAPPY_LOCAL_STORAGE_DIR = process.env.HAPPY_LOCAL_STORAGE_DIR ?? process.env.HAPPY_STACKS_STORAGE_DIR;
+  // In sandbox mode, we MUST force all state directories into the sandbox, even if the user
+  // exported HAPPY_STACKS_* in their shell. Otherwise sandbox runs can accidentally read/write
+  // "real" machine state (breaking isolation).
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = canonicalHomeDir;
+  process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR = canonicalHomeDir;
+
+  process.env.HAPPY_STACKS_HOME_DIR = homeDir;
+  process.env.HAPPY_LOCAL_HOME_DIR = homeDir;
+
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = workspaceDir;
+  process.env.HAPPY_LOCAL_WORKSPACE_DIR = workspaceDir;
+
+  process.env.HAPPY_STACKS_RUNTIME_DIR = runtimeDir;
+  process.env.HAPPY_LOCAL_RUNTIME_DIR = runtimeDir;
+
+  process.env.HAPPY_STACKS_STORAGE_DIR = storageDir;
+  process.env.HAPPY_LOCAL_STORAGE_DIR = storageDir;
+
+  // Sandbox default: disallow global side effects unless explicitly opted in.
+  // This keeps sandbox runs fast, deterministic, and isolated.
+  if (!allowGlobal) {
+    // Network-y UX (background update checks) are not useful in a temporary sandbox.
+    process.env.HAPPY_STACKS_UPDATE_CHECK = '0';
+    process.env.HAPPY_STACKS_UPDATE_CHECK_INTERVAL_MS = '0';
+    process.env.HAPPY_STACKS_UPDATE_NOTIFY_INTERVAL_MS = '0';
+
+    // Never auto-enable or reset Tailscale Serve in sandbox.
+    // (Tailscale is global machine state; sandbox runs must not touch it.)
+    process.env.HAPPY_LOCAL_TAILSCALE_SERVE = '0';
+    process.env.HAPPY_STACKS_TAILSCALE_SERVE = '0';
+    process.env.HAPPY_LOCAL_TAILSCALE_RESET_ON_EXIT = '0';
+    process.env.HAPPY_STACKS_TAILSCALE_RESET_ON_EXIT = '0';
+  }
 
   return { argv: nextArgv, enabled: true };
 }
@@ -248,8 +339,16 @@ function runNodeScript(cliRootDir, scriptRelPath, args) {
 function main() {
   const cliRootDir = getCliRootDir();
   const initialArgv = process.argv.slice(2);
-  const { argv, enabled: sandboxed } = applySandboxDirIfRequested(initialArgv);
+  const argv0 = applyVerbosityIfRequested(initialArgv);
+  const { argv, enabled: sandboxed } = applySandboxDirIfRequested(argv0);
   void sandboxed;
+
+  // Preserve the original working directory across re-exec to the CLI root so commands can infer
+  // component/worktree context even when the actual scripts run with cwd=cliRootDir.
+  if (!(process.env.HAPPY_STACKS_INVOKED_CWD ?? '').trim()) {
+    process.env.HAPPY_STACKS_INVOKED_CWD = process.cwd();
+  }
+
   maybeReexecToCliRoot(cliRootDir);
 
   // If the user passed only flags (common via `npx happy-stacks --help`),

package/docs/happy-development.md

@@ -559,9 +559,9 @@ Most commands support `--help` and `--json`.
 ### Core run commands
 
 - **`happys start`**: production-like run (no Expo)
-  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--no-browser`
+  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--no-browser`, `--mobile`
 - **`happys dev`**: dev run (server + daemon + Expo web)
-  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--watch`, `--no-watch`, `--no-browser`
+  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--watch`, `--no-watch`, `--no-browser`, `--mobile`
 - **`happys stop`**: stop stacks and related processes
   - Flags: `--except-stacks=main,exp1`, `--yes`, `--aggressive`, `--sweep-owned`, `--no-docker`, `--no-service`
 

package/docs/isolated-linux-vm.md

@@ -0,0 +1,82 @@
+# Isolated Linux VM (Apple Silicon) for `review-pr`
+
+If you want to validate `happys review-pr` on a **fresh system** (no existing `~/.happy-stacks`, no host tooling), the simplest repeatable approach on Apple Silicon is a Linux VM managed by **Lima** (it uses Apple’s Virtualization.framework).
+
+This avoids Docker/container UX issues (browser opening, Expo networking, file watching) while still being truly “clean”.
+
+## Option A (recommended): Lima + Ubuntu ARM64
+
+### 1) Install Lima (macOS host)
+
+```bash
+brew install lima
+```
+
+### 2) Create a VM
+
+```bash
+limactl create --name happy-pr --tty=false template://ubuntu-24.04
+limactl start happy-pr
+```
+
+### 3) Provision the VM (Node + build deps)
+
+```bash
+limactl shell happy-pr
+```
+
+Inside the VM:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/leeroybrun/happy-local/main/scripts/provision/linux-ubuntu-review-pr.sh -o /tmp/linux-ubuntu-review-pr.sh && chmod +x /tmp/linux-ubuntu-review-pr.sh && /tmp/linux-ubuntu-review-pr.sh
+```
+
+### 4) Run `review-pr` via `npx` (published package)
+
+Inside the VM:
+
+```bash
+npx --yes happy-stacks@latest review-pr \
+  --happy=https://github.com/leeroybrun/happy/pull/10 \
+  --happy-cli=https://github.com/leeroybrun/happy-cli/pull/12 \
+  --no-mobile \
+  --verbose
+```
+
+Notes:
+- `--no-mobile` keeps the validation focused (Expo mobile dev-client adds more host requirements).
+- You can also add `--keep-sandbox` if you want to inspect the sandbox contents after a failure.
+- For full reproducibility, pin the version: `npx --yes happy-stacks@0.3.0 review-pr ...`
+
+### Optional: test **unreleased local changes**
+
+If you need to test changes that aren’t published to npm yet:
+
+1) On your Mac (repo checkout):
+
+```bash
+npm pack
+```
+
+2) Copy the generated `happy-stacks-*.tgz` into the VM (any method you like), then inside the VM:
+
+```bash
+npx --yes ./happy-stacks-*.tgz review-pr ...
+```
+
+## Option B: GUI VM (UTM) – simplest when you want a “real desktop”
+
+If you want the most realistic “reviewer” experience (open browser, etc.), a GUI VM is great:
+
+1. Install UTM (macOS host): `brew install --cask utm`
+2. Create an Ubuntu 24.04 ARM64 VM (UTM wizard).
+3. Run the same provisioning + `node bin/happys.mjs review-pr ...` inside the VM.
+
+## Option C: Apple “container” / Docker
+
+Containers are excellent for server-only validation, but are usually **not** the best fit for end-to-end `review-pr` UX because:
+- opening the host browser from inside the container is awkward
+- Expo/dev-server workflows and networking tend to require extra port mapping and host interaction
+
+Use containers only if you explicitly want “CLI-only” checks and are okay opening URLs manually.
+

package/docs/mobile-ios.md

@@ -8,101 +8,166 @@ see the “Using Happy from your phone” section in the main README.
 - Xcode installed
 - CocoaPods installed (`brew install cocoapods`)
 
-## Step 1: Generate iOS native project + Pods (run when needed)
+## Two supported modes
 
-Run this after pulling changes that affect native deps/config, or if `ios/` was deleted:
+- **Shared dev-client app** (recommended for development):
+  - Install *one* “Happy Stacks Dev” app on your phone.
+  - Run any stack with `--mobile`; scan the QR to open that stack inside the dev-client.
+  - Per-stack auth/storage is isolated via `EXPO_PUBLIC_HAPPY_STORAGE_SCOPE` (set automatically in stack mode).
 
-```bash
-happys mobile:prebuild
-```
+- **Per-stack “release” app** (recommended for demos / strict isolation):
+  - Install a separate iOS app per stack (unique bundle id + scheme).
+  - Each stack app is isolated by iOS app container (no token collisions).
+
+## Shared dev-client app (install once)
 
-## Step 2: Install the iOS dev build
+Install the dedicated Happy Stacks dev-client app on your iPhone (USB).
 
-- **iOS Simulator**:
+This command **runs a prebuild** (generates `ios/` + runs CocoaPods) and then installs a Debug build
+without starting Metro:
 
 ```bash
-happys mobile --run-ios --device="iPhone 16 Pro"
+happys mobile-dev-client --install
 ```
 
-- **Real iPhone** (requires code signing in Xcode once):
+If you want to ensure the dev-client is built from a specific stack’s active `happy` worktree
+(e.g. to include upstream changes that aren’t merged into your default checkout yet), run:
 
 ```bash
-happys mobile --run-ios --device="Your iPhone"
+happys stack mobile-dev-client <stack> --install
 ```
 
-Tip: you can omit `--device` to auto-pick the first connected iPhone over USB:
+Optional:
 
 ```bash
-happys mobile --run-ios
+happys mobile-dev-client --install --device="Your iPhone"
+happys mobile-dev-client --install --clean
 ```
 
-To see the exact device names/IDs you can pass:
+Then run any stack with mobile enabled:
 
 ```bash
-happys mobile:devices
+happys stack dev <stack> --mobile
+# or:
+happys dev --mobile
 ```
 
-If you hit a bundle identifier error (e.g. `com.slopus.happy.dev` “not available”), set a unique local bundle id:
+Notes:
+
+- **LAN requirement**: for physical iPhones, Metro must be reachable over LAN.
+  - Happy Stacks defaults to `lan` for mobile, and will print a QR code + deep link.
+  - For simulators you can usually use `localhost` (see `HAPPY_STACKS_MOBILE_HOST` below).
+- **If Expo is already running in web-only mode**: re-run with `--restart` and include `--mobile`.
+
+## Per-stack app install (isolated)
+
+Install an isolated app for a specific stack (unique bundle id + scheme, Release config, no Metro):
 
 ```bash
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --run-ios
-# legacy: HAPPY_LOCAL_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --run-ios
+happys stack mobile:install <stack> --name="Happy (<stack>)"
+happys stack mobile:install <stack> --name="Happy PR 272" --device="Your iPhone"
 ```
 
-## Release build (runs without Metro)
+The chosen app name is persisted in the stack env so you can re-run installs without re-typing it.
+
+## Native iOS regeneration / “prebuild” (critical)
+
+You’ll need to regenerate the iOS native project + Pods when:
+
+- you pull changes that affect native deps / Expo config
+- `components/happy/ios/` was deleted
+- you hit CocoaPods / deployment-target mismatches after a dependency bump
 
-Build + install a Release configuration (no Metro required at runtime):
+Run:
 
 ```bash
-happys mobile:install
+happys mobile --prebuild
+# (optional) fully regenerate ios/:
+happys mobile --prebuild --clean
 ```
 
-## Step 3: Start Metro (dev client)
+What this does today:
 
-- **iOS Simulator**:
+- runs `expo prebuild --no-install` (so we can patch before CocoaPods runs)
+- patches `ios/Podfile.properties.json` to:
+  - set `ios.deploymentTarget` to `16.0`
+  - set `ios.buildReactNativeFromSource` to `true`
+- patches the generated Xcode project deployment target (where applicable)
+- runs `pod install`
+
+Notes:
+
+- **You usually don’t need to run this manually** because both:
+  - `happys mobile-dev-client --install`
+  - `happys stack mobile:install <stack>`
+  already include `--prebuild`.
+- Legacy alias: `happys mobile:prebuild` exists (hidden), but prefer `happys mobile --prebuild`.
+
+## Manual `happys mobile` usage (advanced)
+
+If you want to work on the embedded Expo app directly (outside `happys dev --mobile`), `happys mobile` supports:
 
 ```bash
-happys mobile --host=localhost
+# Start Metro (keeps running):
+happys mobile --host=lan
+
+# Build + install on iOS (and exit). If you omit --device, it will try to auto-pick a connected iPhone over USB:
+happys mobile --prebuild --run-ios --device="Your iPhone"
+happys mobile --prebuild --run-ios --configuration=Release --no-metro
 ```
 
-- **Real iPhone** (same Wi‑Fi as your Mac):
+## Notes / troubleshooting
+
+- **QR opens the wrong app**:
+  - The dev-client QR uses the `HAPPY_STACKS_DEV_CLIENT_SCHEME` (default: `happystacks-dev`).
+  - Per-stack installs use a different per-stack scheme, so they should not intercept dev-client QR scans.
+
+- **List connected devices** (for `--device=`):
 
 ```bash
-happys mobile --host=lan
+happys mobile:devices
 ```
 
-Open the dev build and tap Reload. Scanning the QR should open the dev build (not the App Store app).
+- **Code signing weirdness on a real iPhone**:
+  - Happy Stacks will try to “un-pin” signing fields in the generated `.pbxproj` so Expo/Xcode can reconfigure signing
+    (this avoids failures where automatic signing is disabled because `DEVELOPMENT_TEAM`/profiles were pinned).
+  - If you want to manage signing manually, pass `--no-signing-fix` to `happys mobile ...` / `happys stack mobile <stack> ...`.
 
 ## Bake the default server URL into the app (optional)
 
 If you want the built app to default to your happy-stacks server URL, set this **when building**:
 
 ```bash
-HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" happys mobile:install
+HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" happys mobile-dev-client --install
 ```
 
-Note: changing `HAPPY_STACKS_SERVER_URL` requires rebuilding/reinstalling the Release app (`happys mobile:install`).
+Note: changing `HAPPY_STACKS_SERVER_URL` requires rebuilding/reinstalling the app you care about.
 
-You can also set a custom bundle id (recommended for real devices):
+Important:
 
-```bash
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" happys mobile:install
-```
+- For **non-main stacks**, `HAPPY_STACKS_SERVER_URL` is only respected if it’s set **in that stack’s env file**
+  (safety: we ignore “global” URLs for non-main stacks to avoid accidentally repointing other stacks).
+
+## Customizing the app identity (optional / advanced)
+
+Happy Stacks uses these identities:
 
-## Customizing the app identity (optional)
+- **Dev-client**: defaults to `Happy Stacks Dev` + bundle id `com.happystacks.dev.<user>`
+- **Per-stack release**: defaults to `Happy (<stack>)` + bundle id `com.happystacks.stack.<user>.<stack>`
+
+If you want to build/install *manually* (instead of `mobile-dev-client` / `stack mobile:install`), you can override:
 
 - **Bundle identifier (recommended for real iPhones)**:
-  - You may *need* this if the default `com.slopus.happy.dev` can’t be registered on your Apple team.
+  - You may need this if the bundle id you’re using isn’t available/owned by your Apple team.
 
 ```bash
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --run-ios
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile:install
+HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --prebuild --run-ios --no-metro
 ```
 
 - **App name (what shows on the home screen)**:
 
 ```bash
-HAPPY_STACKS_IOS_APP_NAME="Happy Local" happys mobile:install
+HAPPY_STACKS_IOS_APP_NAME="Happy Local" happys mobile --prebuild --run-ios --no-metro
 ```
 
 ## Suggested env (recommended)
@@ -110,25 +175,18 @@ HAPPY_STACKS_IOS_APP_NAME="Happy Local" happys mobile:install
 Add these to your main stack env file (`~/.happy/stacks/main/env`) (or `~/.happy-stacks/env.local` for global overrides) so you don’t have to prefix every command:
 
 ```bash
-# Required if you want the Release app to default to your stack server:
-HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net"
+# How the phone reaches Metro:
+# - lan: recommended for real devices
+# - localhost: OK for simulators
+HAPPY_STACKS_MOBILE_HOST="lan"
 
-# Strongly recommended for real devices (needs to be unique + owned by your Apple team):
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev"
+# (optional) default scheme used in the dev-client QR / deep link
+# (must match your installed dev-client app):
+HAPPY_STACKS_DEV_CLIENT_SCHEME="happystacks-dev"
+
+# Default public server URL for the stack (baked into the Expo app config):
+HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net"
 
 # Optional: home screen name:
 HAPPY_STACKS_IOS_APP_NAME="Happy Local"
 ```
-
-## Personal build on iPhone (EAS internal distribution)
-
-```bash
-cd "$HOME/.happy-stacks/workspace/components/happy"
-eas build --profile development --platform ios
-```
-
-Then keep Metro running from `happy-stacks`:
-
-```bash
-happys mobile --host=lan
-```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "happy-stacks",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -32,7 +32,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 +45,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;
@@ -580,7 +580,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,
@@ -689,6 +689,7 @@ async function cmdStatus({ json }) {
     defaultPublicUrl,
     envPublicUrl,
     allowEnable: false,
+    stackName,
   });
 
   const cliHomeDir = resolveCliHomeDir();
@@ -770,7 +771,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 +780,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 +821,8 @@ async function cmdLogin({ argv, json }) {
     return;
   }
 
-  if (!json) {
+  const quietUx = flags.has('--quiet') || flags.has('--no-ux');
+  if (!json && !quietUx) {
     printAuthLoginInstructions({
       stackName,
       context,