happy-stacks 0.1.2 → 0.3.0

package/README.md

@@ -1,11 +1,6 @@
 # Happy Stacks
 
-
-
-Run the **Happy** stack locally (or many stacks in parallel) and access it remotely and securely (using Tailscale).
-
-`happy-stacks` is a CLI (`happys`) that orchestrate the real upstream repos
-cloned under your configured workspace (default: `~/.happy-stacks/workspace/components/*`).
+Run [**Happy**](https://happy.engineering/) locally and access it remotely and securely (using Tailscale).
 
 ## What is Happy?
 
@@ -13,62 +8,24 @@ Happy is an UI/CLI stack (server + web UI + CLI + daemon) who let you monitor an
 
 ## What is Happy Stacks?
 
-happy-stacks is a “launcher + workflow toolkit” to:
+happy-stacks is a guided installer + local orchestration CLI for Happy.
 
-- run Happy fully on your own machine (no hosted dependency)
-- safely access it remotely (HTTPS secure context) via Tailscale
-- manage **worktrees** for clean upstream PRs while keeping a patched fork
-- run **multiple isolated stacks** (ports + dirs + component overrides)
-- optionally manage autostart (macOS LaunchAgent) and a SwiftBar menu bar control panel
+If you only want to **self-host Happy**, start with the **Self-host** section below.
+If you want to **develop Happy** (worktrees, multiple stacks, upstream PR workflows), see the **Development** section further down.
 
-## Quickstart
+## Self-host Happy (install + run)
 
-### Step 1: Install / bootstrap
+### Step 1: Setup
 
 Recommended:
 
 ```bash
-npx happy-stacks init
-export PATH="$HOME/.happy-stacks/bin:$PATH"
-```
-
-Alternative (global install):
-
-```bash
-npm install -g happy-stacks
-happys init
-export PATH="$HOME/.happy-stacks/bin:$PATH"
+npx happy-stacks setup --profile=selfhost
 ```
 
-(`init` will run `bootstrap` automatically. Use `--no-bootstrap` if you only want to write config and shims.)
-
-Developer mode (clone this repo):
+`setup` can optionally start Happy and guide you through authentication.
 
-```bash
-git clone https://github.com/leeroybrun/happy-stacks.git
-cd happy-stacks
-
-node ./bin/happys.mjs bootstrap --interactive
-# legacy:
-# pnpm bootstrap -- --interactive
-```
-
-Notes:
-
-- In a cloned repo, `pnpm <script>` still works, but `happys <command>` is now the recommended UX (same underlying scripts).
-- To make the installed `~/.happy-stacks/bin/happys` shim (LaunchAgents / SwiftBar) run your local checkout without publishing to npm, set:
-
-  ```bash
-  echo 'HAPPY_STACKS_CLI_ROOT_DIR=/path/to/your/happy-stacks-checkout' >> ~/.happy-stacks/.env
-  ```
-
-  Or (recommended) persist it via init:
-
-  ```bash
-  happys init --cli-root-dir=/path/to/your/happy-stacks-checkout
-  ```
-
-### Step 2: Run the main stack
+### Step 2: Start Happy
 
 Starts the local server, CLI daemon, and serves the pre-built UI.
 
@@ -76,7 +33,7 @@ Starts the local server, CLI daemon, and serves the pre-built UI.
 happys start
 ```
 
-### Step 2b (first run only): authenticate the daemon
+### Step 3 (first run only): authenticate
 
 On a **fresh machine** (or any new stack), the daemon needs to authenticate once before it can register a “machine”.
 
@@ -84,34 +41,20 @@ On a **fresh machine** (or any new stack), the daemon needs to authenticate once
 happys auth login
 ```
 
-#### Troubleshooting: “no machine” on first run (daemon auth)
-
-If `.../new` shows “no machine” check whether this is **auth** vs a **daemon/runtime** issue:
+If you want a quick diagnosis:
 
 ```bash
 happys auth status
 ```
 
-If it says **auth is required**, run:
-
-```bash
-happys auth login
-```
-
-If auth is OK but the daemon isn’t running, run:
-
-```bash
-happys doctor
-```
-
-### Step 3: Enable Tailscale Serve (recommended for remote devices)
+### Step 4: Enable Tailscale Serve (recommended for mobile/remote)
 
 ```bash
 happys tailscale enable
 happys tailscale url
 ```
 
-### Step 4: Mobile access
+### Step 5: Mobile access
 
 Make sure Tailscale is [installed and running]
 ([https://tailscale.com/kb/1347/installation](https://tailscale.com/kb/1347/installation)) on your 
@@ -124,9 +67,41 @@ your local server](docs/remote-access.md).
 
 Details (secure context, phone instructions, automation knobs): `[docs/remote-access.md](docs/remote-access.md)`.
 
-## Why this exists
+## Development (worktrees, stacks, contributor workflows)
+
+### Setup (guided)
+
+```bash
+npx happy-stacks setup --profile=dev
+```
+
+### Developing from a cloned repo
+
+```bash
+git clone https://github.com/leeroybrun/happy-stacks.git
+cd happy-stacks
+
+node ./bin/happys.mjs setup --profile=dev
+```
+
+Notes:
+
+- In a cloned repo, `pnpm <script>` still works, but `happys <command>` is the recommended UX (same underlying scripts).
+- To make the installed `~/.happy-stacks/bin/happys` shim (LaunchAgents / SwiftBar) run your local checkout without publishing to npm, set:
+
+  ```bash
+  echo 'HAPPY_STACKS_CLI_ROOT_DIR=/path/to/your/happy-stacks-checkout' >> ~/.happy-stacks/.env
+  ```
+
+  Or (recommended) persist it via init:
+
+  ```bash
+  happys init --cli-root-dir=/path/to/your/happy-stacks-checkout
+  ```
+
+### Why this exists
 
-- **Automated setup**: `happys init` + `happys start` gets the whole stack up and running.
+- **Automated setup**: `happys setup` + `happys start` gets the whole stack up and running.
 - **No hosted dependency**: run the full stack on your own computer.
 - **Lower latency**: localhost/LAN is typically much faster than remote hosted servers.
 - **Custom forks**: easily use forks of the Happy UI + CLI (e.g. `leeroybrun/*`) while still contributing upstream to `slopus/*`.
@@ -134,7 +109,7 @@ Details (secure context, phone instructions, automation knobs): `[docs/remote-ac
 - **Stacks**: run multiple isolated instances in parallel (ports + dirs + component overrides).
 - **Remote access**: `happys tailscale ...` helps you get an HTTPS URL for mobile/remote devices.
 
-## How Happy Stacks wires “local” URLs
+### How Happy Stacks wires “local” URLs
 
 There are two “URLs” to understand:
 
@@ -170,7 +145,7 @@ Diagram:
 
 More details + automation: `[docs/remote-access.md](docs/remote-access.md)`.
 
-## How it’s organized
+### How it’s organized
 
 - **Scripts**: `scripts/*.mjs` (bootstrap/dev/start/build/stacks/worktrees/service/tailscale/mobile)
 - **Components**: `components/*` (each is its own Git repo)
@@ -183,9 +158,9 @@ Components:
 - `happy-server-light` (light server, can serve built UI)
 - `happy-server` (full server)
 
-## Quickstarts (feature-focused)
+### Quickstarts (feature-focused)
 
-### Remote access (Tailscale Serve)
+#### Remote access (Tailscale Serve)
 
 ```bash
 happys tailscale enable
@@ -194,7 +169,7 @@ happys tailscale url
 
 Details: `[docs/remote-access.md](docs/remote-access.md)`.
 
-### Worktrees + forks (clean upstream PRs)
+#### Worktrees + forks (clean upstream PRs)
 
 Create a clean upstream PR worktree:
 
@@ -210,9 +185,80 @@ happys wt pr happy https://github.com/slopus/happy/pull/123 --use
 happys wt pr happy 123 --update --stash
 ```
 
+##### 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 \
+  --happy=https://github.com/slopus/happy/pull/123 \
+  --happy-cli=https://github.com/slopus/happy-cli/pull/456 \
+  --seed-auth --copy-auth-from=dev-auth --link-auth \
+  --dev
+```
+
+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"
+```
+
+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 \
+  --happy=https://github.com/slopus/happy/pull/123 \
+  --happy-cli=https://github.com/slopus/happy-cli/pull/456
+```
+
+Optional: run it in a self-contained sandbox folder (delete it to uninstall completely):
+
+```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"
+```
+
+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)
+#### Server flavor (server-light vs full server)
 
 - Use `happy-server-light` for a light local stack (no Redis, no Postgres, no Docker), and UI serving via server-light.
 - Use `happy-server` when you need a more production-like server (Postgres + Redis + S3-compatible storage) or want to develop server changes for upstream.
@@ -233,7 +279,7 @@ happys stack srv exp1 -- use --interactive
 
 Details: `[docs/server-flavors.md](docs/server-flavors.md)`.
 
-### Stacks (multiple isolated instances)
+#### Stacks (multiple isolated instances)
 
 ```bash
 happys stack new exp1 --interactive
@@ -250,7 +296,15 @@ happys stack dev exp1
 
 Details: `[docs/stacks.md](docs/stacks.md)`.
 
-### Menu bar (SwiftBar)
+#### Dev stacks: browser origin isolation (IMPORTANT)
+
+Non-main stacks use a stack-specific localhost hostname (no `/etc/hosts` changes required):
+
+- `http://happy-<stack>.localhost:<uiPort>`
+
+This avoids browser auth/session collisions between stacks (separate origin per stack).
+
+#### Menu bar (SwiftBar)
 
 ```bash
 happys menubar install
@@ -259,7 +313,7 @@ happys menubar open
 
 Details: `[docs/menubar.md](docs/menubar.md)`.
 
-### Mobile iOS dev (optional)
+#### Mobile iOS dev (optional)
 
 ```bash
 happys mobile --help
@@ -268,7 +322,7 @@ happys mobile --json
 
 Details: `[docs/mobile-ios.md](docs/mobile-ios.md)`.
 
-### Tauri desktop app (optional)
+#### Tauri desktop app (optional)
 
 ```bash
 happys build --tauri
@@ -276,13 +330,12 @@ happys build --tauri
 
 Details: `[docs/tauri.md](docs/tauri.md)`.
 
-## Commands (high-signal)
+### Commands (high-signal)
 
 - **Setup**:
-  - `happys init`
-  - `happys bootstrap --interactive` (wizard)
-  - `happys bootstrap --forks|--upstream`
-  - `happys bootstrap --server=happy-server|happy-server-light|both`
+  - `happys setup` (guided; selfhost or dev)
+  - (advanced) `happys init` (plumbing: shims/runtime/pointer env)
+  - (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)
@@ -303,17 +356,18 @@ Details: `[docs/tauri.md](docs/tauri.md)`.
 - **Menu bar (SwiftBar)**:
   - `happys menubar install`
 
-## Docs (deep dives)
+### Docs (deep dives)
 
 - **Remote access (Tailscale + phone)**: `[docs/remote-access.md](docs/remote-access.md)`
 - **Server flavors (server-light vs server)**: `[docs/server-flavors.md](docs/server-flavors.md)`
 - **Worktrees + forks workflow**: `[docs/worktrees-and-forks.md](docs/worktrees-and-forks.md)`
 - **Stacks (multiple instances)**: `[docs/stacks.md](docs/stacks.md)`
+- **Paths + env precedence (home/workspace/runtime/stacks)**: `[docs/paths-and-env.md](docs/paths-and-env.md)`
 - **Menu bar (SwiftBar)**: `[docs/menubar.md](docs/menubar.md)`
 - **Mobile iOS dev**: `[docs/mobile-ios.md](docs/mobile-ios.md)`
 - **Tauri desktop app**: `[docs/tauri.md](docs/tauri.md)`
 
-## Configuration
+### Configuration
 
 Where config lives by default:
 
@@ -329,4 +383,25 @@ Notes:
   - **Use `.env.example` as the canonical template** (copy it to `.env` if you’re running this repo directly).
   - If an LLM tool refuses to read/edit `.env.example` due to safety restrictions, **do not create an `env.example` workaround**—instead, ask the user to apply the change manually.
 
+### Sandbox / test installs (fully isolated)
+
+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
+SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
+
+# Run a PR stack (fully isolated install)
+npx happy-stacks --sandbox-dir "$SANDBOX" setup-pr --happy=123 --happy-cli=456
+
+# Tear down + uninstall
+npx happy-stacks --sandbox-dir "$SANDBOX" stop --yes --no-service
+rm -rf "$SANDBOX"
+```
+
+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

@@ -7,15 +7,14 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { commandHelpArgs, renderHappysRootHelp, resolveHappysCommand } from '../scripts/utils/cli_registry.mjs';
+import { commandHelpArgs, renderHappysRootHelp, resolveHappysCommand } from '../scripts/utils/cli/cli_registry.mjs';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/paths/canonical_home.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-function expandHome(p) {
-  return String(p ?? '').replace(/^~(?=\/)/, homedir());
-}
+// expandHome is imported from scripts/utils/paths/canonical_home.mjs
 
 function dotenvGetQuick(envPath, key) {
   try {
@@ -47,7 +46,7 @@ function resolveCliRootDir() {
   if (fromEnv) return expandHome(fromEnv);
 
   // Stable pointer file: even if the real home dir is elsewhere, `happys init` writes the pointer here.
-  const canonicalEnv = join(homedir(), '.happy-stacks', '.env');
+  const canonicalEnv = getCanonicalHomeEnvPathFromEnv(process.env);
   const v =
     dotenvGetQuick(canonicalEnv, 'HAPPY_STACKS_CLI_ROOT_DIR') ||
     dotenvGetQuick(canonicalEnv, 'HAPPY_LOCAL_CLI_ROOT_DIR') ||
@@ -86,11 +85,66 @@ function resolveHomeDir() {
   if (fromEnv) return expandHome(fromEnv);
 
   // Stable pointer file: even if the real home dir is elsewhere, `happys init` writes the pointer here.
-  const canonicalEnv = join(homedir(), '.happy-stacks', '.env');
+  const canonicalEnv = getCanonicalHomeEnvPathFromEnv(process.env);
   const v = dotenvGetQuick(canonicalEnv, 'HAPPY_STACKS_HOME_DIR') || dotenvGetQuick(canonicalEnv, 'HAPPY_LOCAL_HOME_DIR') || '';
   return v ? expandHome(v) : join(homedir(), '.happy-stacks');
 }
 
+function stripGlobalOpt(argv, { name, aliases = [] }) {
+  const names = [name, ...aliases];
+  for (const n of names) {
+    const eq = `${n}=`;
+    const iEq = argv.findIndex((a) => a.startsWith(eq));
+    if (iEq >= 0) {
+      const value = argv[iEq].slice(eq.length);
+      const next = [...argv.slice(0, iEq), ...argv.slice(iEq + 1)];
+      return { value, argv: next };
+    }
+    const i = argv.indexOf(n);
+    if (i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('-')) {
+      const value = argv[i + 1];
+      const next = [...argv.slice(0, i), ...argv.slice(i + 2)];
+      return { value, argv: next };
+    }
+  }
+  return { value: '', argv };
+}
+
+function applySandboxDirIfRequested(argv) {
+  const explicit = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
+  const { value, argv: nextArgv } = stripGlobalOpt(argv, { name: '--sandbox-dir', aliases: ['--sandbox'] });
+  const raw = value || explicit;
+  if (!raw) return { argv: nextArgv, enabled: false };
+
+  const sandboxDir = expandHome(raw);
+  // Keep all state under one folder that can be deleted to reset completely.
+  const canonicalHomeDir = join(sandboxDir, 'canonical');
+  const homeDir = join(sandboxDir, 'home');
+  const workspaceDir = join(sandboxDir, 'workspace');
+  const runtimeDir = join(sandboxDir, 'runtime');
+  const storageDir = join(sandboxDir, 'storage');
+
+  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;
+
+  return { argv: nextArgv, enabled: true };
+}
+
 function maybeAutoUpdateNotice(cliRootDir, cmd) {
   // Non-blocking, cached update checks:
   // - never run network calls in-process
@@ -193,17 +247,23 @@ function runNodeScript(cliRootDir, scriptRelPath, args) {
 
 function main() {
   const cliRootDir = getCliRootDir();
+  const initialArgv = process.argv.slice(2);
+  const { argv, enabled: sandboxed } = applySandboxDirIfRequested(initialArgv);
+  void sandboxed;
   maybeReexecToCliRoot(cliRootDir);
-  const argv = process.argv.slice(2);
 
+  // If the user passed only flags (common via `npx happy-stacks --help`),
+  // treat it as root help rather than `help --help` (which would look like
+  // "unknown command: --help").
   const cmd = argv.find((a) => !a.startsWith('--')) ?? 'help';
-  const rest = cmd === 'help' ? [] : argv.slice(argv.indexOf(cmd) + 1);
+  const cmdIndex = argv.indexOf(cmd);
+  const rest = cmdIndex >= 0 ? argv.slice(cmdIndex + 1) : [];
 
   maybeAutoUpdateNotice(cliRootDir, cmd);
 
   if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    const target = argv[argv.indexOf(cmd) + 1];
-    if (!target) {
+    const target = rest[0];
+    if (!target || target.startsWith('-')) {
       console.log(usage());
       return;
     }