happy-stacks 0.2.0 → 0.4.0

package/README.md

@@ -23,13 +23,6 @@ Recommended:
 npx happy-stacks setup --profile=selfhost
 ```
 
-Alternative (global install):
-
-```bash
-npm install -g happy-stacks
-happys setup --profile=selfhost
-```
-
 `setup` can optionally start Happy and guide you through authentication.
 
 ### Step 2: Start Happy
@@ -157,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:
 
@@ -192,7 +186,10 @@ happys wt pr happy https://github.com/slopus/happy/pull/123 --use
 happys wt pr happy 123 --update --stash
 ```
 
-Create a fully isolated PR stack (creates stack + PR worktrees + optional auth seeding + starts dev):
+##### Developer quickstart: create a PR stack (isolated ports/dirs; idempotent updates)
+
+This creates (or reuses) a named stack, checks out PR worktrees for the selected components, optionally seeds auth, and starts the stack.
+Re-run with `--reuse` to update the existing worktrees when the PR changes.
 
 ```bash
 happys stack pr pr123 \
@@ -202,15 +199,33 @@ happys stack pr pr123 \
   --dev
 ```
 
-One-shot “install + run PR stack” (best for maintainers who don’t have Happy Stacks set up yet):
+Optional: enable Expo dev-client for mobile reviewers (reuses the same Expo dev server; no second Metro process):
 
 ```bash
-npx happy-stacks setup pr \
-  --happy=https://github.com/slopus/happy/pull/123 \
-  --happy-cli=https://github.com/slopus/happy-cli/pull/456
+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
+SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
+happys --sandbox-dir "$SANDBOX" stack pr pr123 --happy=123 --happy-cli=456 --dev
+rm -rf "$SANDBOX"
 ```
 
-You can also run it as:
+Update when the PR changes:
+
+- Re-run with `--reuse` to fast-forward worktrees when possible.
+- If the PR was force-pushed, add `--force`.
+
+```bash
+happys stack pr pr123 --happy=123 --happy-cli=456 --reuse
+happys stack pr pr123 --happy=123 --happy-cli=456 --reuse --force
+```
+
+##### Maintainer quickstart: one-shot “install + run PR stack” (idempotent)
+
+This is the maintainer-friendly entrypoint. It is safe to re-run and will keep the PR stack wiring intact.
 
 ```bash
 npx happy-stacks setup-pr \
@@ -218,11 +233,40 @@ npx happy-stacks setup-pr \
   --happy-cli=https://github.com/slopus/happy-cli/pull/456
 ```
 
-Updating when the PR changes:
+Optional: enable Expo dev-client for mobile reviewers (works with both default `--dev` and `--start`):
+
+```bash
+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):
+
+```bash
+npx happy-stacks setup-pr --happy=123 --happy-cli=456
+```
+
+Override stack name (optional):
+
+```bash
+npx happy-stacks setup-pr --name=pr123 --happy=123 --happy-cli=456
+```
+
+Update when the PR changes:
 
 - Re-run the same command to fast-forward the PR worktrees.
 - If the PR was force-pushed, add `--force`.
 
+```bash
+npx happy-stacks setup-pr --happy=123 --happy-cli=456
+npx happy-stacks setup-pr --happy=123 --happy-cli=456 --force
+```
+
 Details: `[docs/worktrees-and-forks.md](docs/worktrees-and-forks.md)`.
 
 #### Server flavor (server-light vs full server)
@@ -283,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
@@ -305,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`
@@ -319,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`
 
@@ -352,19 +407,23 @@ Notes:
 
 ### Sandbox / test installs (fully isolated)
 
-If you want to test the full setup flow (including PR stacks) without impacting your “real” install, run with:
+If you want to test the full setup flow (including PR stacks) without impacting your “real” install, run everything with `--sandbox-dir`.
+To fully uninstall the test run, stop the sandbox stacks and delete the sandbox folder.
 
 ```bash
-npx happy-stacks --sandbox-dir /tmp/happy-stacks-sandbox setup pr --happy=123 --happy-cli=456
-```
+SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
 
-To reset completely, just delete the sandbox folder:
+# Run a PR stack (fully isolated install)
+npx happy-stacks --sandbox-dir "$SANDBOX" setup-pr --happy=123 --happy-cli=456
 
-```bash
-rm -rf /tmp/happy-stacks-sandbox
+# Tear down + uninstall
+npx happy-stacks --sandbox-dir "$SANDBOX" stop --yes --no-service
+rm -rf "$SANDBOX"
 ```
 
-Sandbox mode disables global OS side effects (PATH edits, SwiftBar plugin install, LaunchAgents/systemd services) by default.
-To explicitly allow them for testing, set `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1`.
+Notes:
+
+- Sandbox mode disables global OS side effects (**PATH edits**, **SwiftBar plugin install**, **LaunchAgents/systemd services**, **Tailscale Serve enable/disable**) by default.
+- To explicitly allow those for testing, set `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1` (still recommended to clean up after).
 
 For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.

package/bin/happys.mjs

@@ -8,13 +8,13 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { commandHelpArgs, renderHappysRootHelp, resolveHappysCommand } from '../scripts/utils/cli/cli_registry.mjs';
-import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/canonical_home.mjs';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/paths/canonical_home.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-// expandHome is imported from scripts/utils/canonical_home.mjs
+// expandHome is imported from scripts/utils/paths/canonical_home.mjs
 
 function dotenvGetQuick(envPath, key) {
   try {
@@ -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.
+