happy-stacks 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +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?
 
@@ -11,51 +8,31 @@ 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"
+npx happy-stacks setup --profile=selfhost
 ```
 
 Alternative (global install):
 
 ```bash
 npm install -g happy-stacks
-happys init
-export PATH="$HOME/.happy-stacks/bin:$PATH"
+happys 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).
-
-### Step 2: Run the main stack
+### Step 2: Start Happy
 
 Starts the local server, CLI daemon, and serves the pre-built UI.
 
@@ -63,7 +40,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”.
 
@@ -71,34 +48,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 
@@ -111,9 +74,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:
 
-- **Automated setup**: `happys init` + `happys start` gets the whole stack up and running.
+- 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 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/*`.
@@ -121,7 +116,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:
 
@@ -143,9 +138,10 @@ Diagram:
                    v
            local machine (this repo)
      +--------------------------------+
-     | happy-server(-light)           |
+     | happy-server-light OR          |
+     | happy-server (via UI gateway)  |
      |  - listens on :PORT            |
-     |  - serves UI (server-light)    |
+     |  - serves UI at /              |
      +--------------------------------+
                    ^
                    | internal loopback
@@ -156,7 +152,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)
@@ -169,9 +165,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
@@ -180,7 +176,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:
 
@@ -196,12 +192,44 @@ 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):
+
+```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
+```
+
+One-shot “install + run PR stack” (best for maintainers who don’t have Happy Stacks set up yet):
+
+```bash
+npx happy-stacks setup pr \
+  --happy=https://github.com/slopus/happy/pull/123 \
+  --happy-cli=https://github.com/slopus/happy-cli/pull/456
+```
+
+You can also run it as:
+
+```bash
+npx happy-stacks setup-pr \
+  --happy=https://github.com/slopus/happy/pull/123 \
+  --happy-cli=https://github.com/slopus/happy-cli/pull/456
+```
+
+Updating when the PR changes:
+
+- Re-run the same command to fast-forward the PR worktrees.
+- If the PR was force-pushed, add `--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 some production-ready server (eg. to distribute and host multiple users) or develop server changes for upstream.
+- Use `happy-server` when you need a more production-like server (Postgres + Redis + S3-compatible storage) or want to develop server changes for upstream.
+  - Happy Stacks can **manage the required infra automatically per stack** (via Docker Compose) and runs a **UI gateway** so you still get a single `https://...ts.net` URL that serves the UI + proxies API/websockets/files.
 
 Switch globally:
 
@@ -218,7 +246,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
@@ -235,7 +263,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
@@ -244,7 +280,7 @@ happys menubar open
 
 Details: `[docs/menubar.md](docs/menubar.md)`.
 
-### Mobile iOS dev (optional)
+#### Mobile iOS dev (optional)
 
 ```bash
 happys mobile --help
@@ -253,7 +289,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
@@ -261,13 +297,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)
@@ -288,17 +323,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:
 
@@ -310,5 +346,25 @@ Notes:
 
 - Canonical env prefix is `HAPPY_STACKS_*` (legacy `HAPPY_LOCAL_*` still works).
 - Canonical stack storage is `~/.happy/stacks` (legacy `~/.happy/local` is still supported).
+- **Repo env templates**:
+  - **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 with:
+
+```bash
+npx happy-stacks --sandbox-dir /tmp/happy-stacks-sandbox setup pr --happy=123 --happy-cli=456
+```
+
+To reset completely, just delete the sandbox folder:
+
+```bash
+rm -rf /tmp/happy-stacks-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`.
 
-For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.
+For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.

package/bin/happys.mjs

@@ -7,18 +7,142 @@ 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/canonical_home.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
+// expandHome is imported from scripts/utils/canonical_home.mjs
+
+function dotenvGetQuick(envPath, key) {
+  try {
+    if (!envPath || !existsSync(envPath)) return '';
+    const lines = readFileSync(envPath, 'utf-8').split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      if (!trimmed.startsWith(`${key}=`)) continue;
+      let v = trimmed.slice(`${key}=`.length).trim();
+      if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+      if (v.startsWith("'") && v.endsWith("'")) v = v.slice(1, -1);
+      return v;
+    }
+  } catch {
+    // ignore
+  }
+  return '';
+}
+
+function resolveCliRootDir() {
+  const fromEnv = (
+    process.env.HAPPY_STACKS_CLI_ROOT_DIR ??
+    process.env.HAPPY_LOCAL_CLI_ROOT_DIR ??
+    process.env.HAPPY_STACKS_DEV_CLI_ROOT_DIR ??
+    process.env.HAPPY_LOCAL_DEV_CLI_ROOT_DIR ??
+    ''
+  ).trim();
+  if (fromEnv) return expandHome(fromEnv);
+
+  // Stable pointer file: even if the real home dir is elsewhere, `happys init` writes the pointer here.
+  const canonicalEnv = getCanonicalHomeEnvPathFromEnv(process.env);
+  const v =
+    dotenvGetQuick(canonicalEnv, 'HAPPY_STACKS_CLI_ROOT_DIR') ||
+    dotenvGetQuick(canonicalEnv, 'HAPPY_LOCAL_CLI_ROOT_DIR') ||
+    dotenvGetQuick(canonicalEnv, 'HAPPY_STACKS_DEV_CLI_ROOT_DIR') ||
+    dotenvGetQuick(canonicalEnv, 'HAPPY_LOCAL_DEV_CLI_ROOT_DIR') ||
+    '';
+  return v ? expandHome(v) : '';
+}
+
+function maybeReexecToCliRoot(cliRootDir) {
+  if ((process.env.HAPPY_STACKS_CLI_REEXEC ?? process.env.HAPPY_STACKS_DEV_REEXEC ?? '') === '1') return;
+  if ((process.env.HAPPY_STACKS_CLI_ROOT_DISABLE ?? process.env.HAPPY_STACKS_DEV_CLI_DISABLE ?? '') === '1') return;
+
+  const cliRoot = resolveCliRootDir();
+  if (!cliRoot) return;
+  if (cliRoot === cliRootDir) return;
+
+  const cliBin = join(cliRoot, 'bin', 'happys.mjs');
+  if (!existsSync(cliBin)) return;
+
+  const argv = process.argv.slice(2);
+  const res = spawnSync(process.execPath, [cliBin, ...argv], {
+    stdio: 'inherit',
+    cwd: cliRoot,
+    env: {
+      ...process.env,
+      HAPPY_STACKS_CLI_REEXEC: '1',
+      HAPPY_STACKS_CLI_ROOT_DIR: cliRoot,
+    },
+  });
+  process.exit(res.status ?? 1);
+}
+
 function resolveHomeDir() {
-  const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
-  if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+  const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? process.env.HAPPY_LOCAL_HOME_DIR ?? '').trim();
+  if (fromEnv) return expandHome(fromEnv);
+
+  // Stable pointer file: even if the real home dir is elsewhere, `happys init` writes the pointer here.
+  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 join(homedir(), '.happy-stacks');
+  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) {
@@ -123,16 +247,23 @@ function runNodeScript(cliRootDir, scriptRelPath, args) {
 
 function main() {
   const cliRootDir = getCliRootDir();
-  const argv = process.argv.slice(2);
+  const initialArgv = process.argv.slice(2);
+  const { argv, enabled: sandboxed } = applySandboxDirIfRequested(initialArgv);
+  void sandboxed;
+  maybeReexecToCliRoot(cliRootDir);
 
+  // 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;
     }