happy-stacks 0.0.0

package/docs/mobile-ios.md

@@ -0,0 +1,134 @@
+# Mobile app development (iOS)
+
+This is optional. Most people can use the served web UI on mobile via Tailscale:
+see the “Using Happy from your phone” section in the main README.
+
+## Prereqs (one-time)
+
+- Xcode installed
+- CocoaPods installed (`brew install cocoapods`)
+
+## Step 1: Generate iOS native project + Pods (run when needed)
+
+Run this after pulling changes that affect native deps/config, or if `ios/` was deleted:
+
+```bash
+happys mobile:prebuild
+```
+
+## Step 2: Install the iOS dev build
+
+- **iOS Simulator**:
+
+```bash
+happys mobile --run-ios --device="iPhone 16 Pro"
+```
+
+- **Real iPhone** (requires code signing in Xcode once):
+
+```bash
+happys mobile --run-ios --device="Your iPhone"
+```
+
+Tip: you can omit `--device` to auto-pick the first connected iPhone over USB:
+
+```bash
+happys mobile --run-ios
+```
+
+To see the exact device names/IDs you can pass:
+
+```bash
+happys mobile:devices
+```
+
+If you hit a bundle identifier error (e.g. `com.slopus.happy.dev` “not available”), set a unique local bundle id:
+
+```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
+```
+
+## Release build (runs without Metro)
+
+Build + install a Release configuration (no Metro required at runtime):
+
+```bash
+happys mobile:install
+```
+
+## Step 3: Start Metro (dev client)
+
+- **iOS Simulator**:
+
+```bash
+happys mobile --host=localhost
+```
+
+- **Real iPhone** (same Wi‑Fi as your Mac):
+
+```bash
+happys mobile --host=lan
+```
+
+Open the dev build and tap Reload. Scanning the QR should open the dev build (not the App Store app).
+
+## 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
+```
+
+Note: changing `HAPPY_STACKS_SERVER_URL` requires rebuilding/reinstalling the Release app (`happys mobile:install`).
+
+You can also set a custom bundle id (recommended for real devices):
+
+```bash
+HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" happys mobile:install
+```
+
+## Customizing the app identity (optional)
+
+- **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.
+
+```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
+```
+
+- **App name (what shows on the home screen)**:
+
+```bash
+HAPPY_STACKS_IOS_APP_NAME="Happy Local" happys mobile:install
+```
+
+## Suggested env (recommended)
+
+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"
+
+# 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: 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/docs/remote-access.md

@@ -0,0 +1,43 @@
+# Remote access (Tailscale + phone)
+
+Happy relies on “secure context” browser features (WebCrypto). Browsers treat `http://localhost` as a secure context, but **not** `http://<lan-ip>:<port>` or `http://<tailscale-ip>:<port>`.
+
+For remote access (phone, another laptop, etc) you should use **HTTPS**.
+
+The recommended approach is **Tailscale Serve**, which gives you an `https://*.ts.net` URL for your machine that is only accessible inside your tailnet.
+
+## Quickstart
+
+1) Install Tailscale and sign in on your computer.
+
+2) Enable Serve:
+
+```bash
+happys tailscale enable
+happys tailscale url
+```
+
+3) Open the URL from `happys tailscale url` on another device (also signed into Tailscale).
+
+Tip: on iOS, you can “Add to Home Screen” from Safari to use it like an app.
+
+## Automation
+
+If Serve is already configured, `happys start` will automatically prefer the `https://*.ts.net` URL for “public” links unless you explicitly set `HAPPY_STACKS_SERVER_URL` (legacy: `HAPPY_LOCAL_SERVER_URL`).
+
+You can also ask happy-stacks to enable Serve automatically at boot:
+
+```bash
+HAPPY_STACKS_TAILSCALE_SERVE=1 happys start
+```
+
+Useful knobs:
+- `HAPPY_STACKS_TAILSCALE_WAIT_MS` (legacy: `HAPPY_LOCAL_TAILSCALE_WAIT_MS`)
+- `HAPPY_STACKS_TAILSCALE_BIN` (legacy: `HAPPY_LOCAL_TAILSCALE_BIN`)
+
+## Using the native Happy mobile app (optional)
+
+The upstream Happy mobile app has an “API Endpoint” setting (developer mode).
+Point it at the same HTTPS `*.ts.net` URL to use your local server.
+
+However, the simplest option is usually the **served web UI** (no app updates needed).

package/docs/server-flavors.md

@@ -0,0 +1,79 @@
+# Server flavors: `happy-server-light` vs `happy-server`
+
+Happy Stacks supports two server “flavors”. You can switch between them globally (main stack) or per stack.
+
+## What’s the difference?
+
+Both are forks/flavors of the same upstream server repo (`slopus/happy-server`), but optimized for different use cases:
+
+- **`happy-server-light`** (recommended default)
+  - optimized for local usage
+  - can **serve the built web UI** (so `happys start` works end-to-end without a separate web server)
+  - usually the best choice when you just want a stable “main” stack on your machine
+
+- **`happy-server`** (full server)
+  - closer to upstream “full” behavior (useful when developing server changes meant to go upstream)
+  - typically does **not** serve the built UI (you’ll use the UI dev server or connect the UI separately)
+  - useful when you need to test upstream/server-only behavior or reproduce upstream issues
+
+Important: for a given run (`happys start` / `happys dev`) you choose **one** flavor.
+
+## How to switch (main stack)
+
+Use the `srv` helper (persisted in `~/.happy/stacks/main/env` by default, or in your stack env file when using `happys stack ...`):
+
+```bash
+happys srv status
+happys srv use happy-server-light
+happys srv use happy-server
+happys srv use --interactive
+```
+
+This persists `HAPPY_STACKS_SERVER_COMPONENT` (and also writes the legacy alias `HAPPY_LOCAL_SERVER_COMPONENT` for compatibility).
+
+## How to switch for a specific stack
+
+Use the stack wrapper:
+
+```bash
+happys stack srv exp1 -- status
+happys stack srv exp1 -- use happy-server-light
+happys stack srv exp1 -- use happy-server
+happys stack srv exp1 -- use --interactive
+```
+
+This updates the stack env file (typically `~/.happy/stacks/<name>/env`).
+
+## One-off overrides (do not persist)
+
+You can override the server flavor for a single run:
+
+```bash
+happys start --server=happy-server-light
+happys start --server=happy-server
+
+happys dev --server=happy-server-light
+happys dev --server=happy-server
+```
+
+## Flavor vs worktree selection (common pitfall)
+
+There are two separate concepts:
+
+- **Flavor selection**: which server component the launcher will run
+  - controlled by `HAPPY_STACKS_SERVER_COMPONENT` (via `happys srv use ...`)
+- **Worktree selection**: which checkout directory to use for each component
+  - 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.
+
+`happys wt use` also prevents the most common mismatch when selecting server worktrees inside `components/` / `components/.worktrees/`.
+
+## Setup note (cloning both)
+
+If you want both component repos present under `components/`:
+
+```bash
+happys bootstrap --server=both
+```

package/docs/stacks.md

@@ -0,0 +1,218 @@
+# Stacks (multiple local Happy instances)
+
+`happy-stacks` supports running **multiple stacks** in parallel on the same machine.
+
+A “stack” is just:
+
+- a dedicated **server port**
+- isolated directories for **UI build output**, **CLI home**, and **logs**
+- optional per-component overrides (point at specific worktrees)
+
+Stacks are configured via a plain env file stored under:
+
+```
+~/.happy/stacks/<name>/env
+```
+
+Legacy path (still supported during migration):
+
+```
+~/.happy/local/stacks/<name>/env
+```
+
+To migrate existing stacks:
+
+```bash
+happys stack migrate
+```
+
+## Create a stack
+
+Non-interactive:
+
+```bash
+happys stack new exp1 --port=3010 --server=happy-server-light
+```
+
+Auto-pick a port:
+
+```bash
+happys stack new exp2
+```
+
+Interactive wizard (TTY only):
+
+```bash
+happys stack new --interactive
+```
+
+The wizard lets you:
+
+- pick the server type (`happy-server-light` or `happy-server`)
+- pick or create worktrees for `happy`, `happy-cli`, and the chosen server component
+- choose which Git remote to base newly-created worktrees on (defaults to `upstream`)
+
+## Run a stack
+
+Dev mode:
+
+```bash
+happys stack dev exp1
+```
+
+Production-like mode:
+
+```bash
+happys stack start exp1
+```
+
+Build UI for a stack (server-light serving):
+
+```bash
+happys stack build exp1
+```
+
+Doctor:
+
+```bash
+happys stack doctor exp1
+```
+
+## Edit a stack (interactive)
+
+To change server flavor, port, or component worktrees for an existing stack:
+
+```bash
+happys stack edit exp1 --interactive
+```
+
+## Switch server flavor for a stack
+
+You can change `happy-server-light` vs `happy-server` for an existing stack without re-running the full edit wizard:
+
+```bash
+happys stack srv exp1 -- status
+happys stack srv exp1 -- use happy-server-light
+happys stack srv exp1 -- use happy-server
+happys stack srv exp1 -- use --interactive
+```
+
+## Switch component worktrees for a stack (`stack wt`)
+
+If you want the **exact** same UX as `happys wt`, but scoped to a stack env file:
+
+```bash
+happys stack wt exp1 -- status happy
+happys stack wt exp1 -- use happy slopus/pr/my-ui-pr
+happys stack wt exp1 -- use happy-cli default
+```
+
+This updates the stack env file (`~/.happy/stacks/<name>/env`), not repo `env.local` (legacy path still supported).
+
+## Stack wrappers you can use
+
+These commands run with the stack env file applied:
+
+- `happys stack dev <name>`
+- `happys stack start <name>`
+- `happys stack build <name>`
+- `happys stack doctor <name>`
+- `happys stack mobile <name>`
+- `happys stack srv <name> -- status|use ...`
+- `happys stack wt <name> -- <wt args...>`
+- `happys stack tailscale:status|enable|disable|url <name>`
+- `happys stack service:* <name>`
+
+Global/non-stack commands:
+
+- `happys bootstrap` (sets up shared component repos)
+- `happys cli:link` (installs `happy` shim under `~/.happy-stacks/bin/`)
+
+## Services (macOS LaunchAgents)
+
+Each stack can have its own LaunchAgent (so multiple stacks can start at login).
+
+```bash
+happys stack service exp1 install
+happys stack service exp1 status
+happys stack service exp1 restart
+happys stack service exp1 logs
+```
+
+Implementation notes:
+
+- Service label is stack-scoped:
+  - `main` → `com.happy.stacks` (legacy: `com.happy.local`)
+  - `exp1` → `com.happy.stacks.exp1` (legacy: `com.happy.local.exp1`)
+- The LaunchAgent persists `HAPPY_STACKS_ENV_FILE` (and legacy `HAPPY_LOCAL_ENV_FILE`), so you can edit the stack env file without reinstalling.
+
+## Component/worktree selection per stack
+
+When creating a stack you can point components at worktrees:
+
+```bash
+happys stack new exp3 \\
+  --happy=slopus/pr/my-ui-pr \\
+  --happy-cli=slopus/pr/my-cli-pr \\
+  --server=happy-server
+```
+
+Worktree specs are interpreted as:
+
+```
+components/.worktrees/<component>/<spec...>
+```
+
+So `--happy=slopus/pr/foo` maps to:
+
+```
+components/.worktrees/happy/slopus/pr/foo
+```
+
+You can also pass an absolute path.
+
+## Stack env + repo env precedence
+
+On startup, `happy-stacks` loads env in this order:
+
+1. `~/.happy-stacks/.env` (defaults)
+2. `~/.happy-stacks/env.local` (optional global overrides; prefer stack env for persistent config)
+3. `HAPPY_STACKS_ENV_FILE` (stack env; highest precedence for `HAPPY_STACKS_*` / `HAPPY_LOCAL_*`)
+
+`happys stack ...` sets `HAPPY_STACKS_ENV_FILE=~/.happy/stacks/<name>/env` (and also sets legacy `HAPPY_LOCAL_ENV_FILE`) and clears any already-exported `HAPPY_STACKS_*` / `HAPPY_LOCAL_*` variables so the stack env stays authoritative.
+
+Cloned-repo fallback (before you run `happys init`):
+
+1. `<repo>/.env` (defaults)
+2. `<repo>/env.local` (optional overrides)
+3. `HAPPY_STACKS_ENV_FILE` (stack env)
+
+## 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”.
+If the UI shows “no machine” (or the daemon shows `auth_required`), it usually means the stack-specific CLI home
+doesn’t have credentials yet:
+
+- `~/.happy/stacks/<stack>/cli/access.key`
+
+To check / authenticate a stack, run:
+
+```bash
+happys stack auth <stack> status
+happys stack auth <stack> login
+```
+
+Notes:
+- For the **main** stack, use `<stack>=main` and the default `<port>=3005` (unless you changed it).
+- If you use Tailscale Serve, `HAPPY_WEBAPP_URL` should be your HTTPS URL (what you get from `happys tailscale url`).
+- Logs live under `~/.happy/stacks/<stack>/cli/logs/`.
+
+## JSON mode
+
+For programmatic usage:
+
+```bash
+happys stack list --json
+happys stack new exp3 --json
+happys stack edit exp3 --interactive --json
+```

package/docs/tauri.md

@@ -0,0 +1,62 @@
+# Tauri desktop app (optional)
+
+The Tauri app is a native desktop wrapper around the web UI. It’s useful when you want:
+
+- a native desktop window (instead of a browser tab)
+- separate storage from the “regular” Happy desktop app (so it doesn’t reuse old server URLs/auth)
+
+## Important behavior
+
+- The Tauri app must embed an explicit API base URL.
+- By default, `happy-stacks` will embed:
+  - a **Tailscale Serve** `https://*.ts.net` URL if it detects one on this machine (so the built app can be copied to other devices on the same tailnet), otherwise
+  - the local loopback URL `http://127.0.0.1:<HAPPY_LOCAL_SERVER_PORT>` (same-machine only).
+- If you change what URL you want embedded, rebuild the Tauri app.
+
+## Prereqs
+
+- Rust toolchain installed
+- Tauri build dependencies installed for your OS
+
+## Build it
+
+Build (one-off):
+
+```bash
+happys build --tauri
+```
+
+Or during bootstrap:
+
+```bash
+happys bootstrap --tauri
+```
+
+## Run it
+
+1) Start the local server (or install the service):
+
+```bash
+happys start
+```
+
+2) Launch the built app bundle (location is under `~/.happy/local/tauri-target/`).
+   - New default: `~/.happy/stacks/main/tauri-target/`
+   - Legacy: `~/.happy/local/tauri-target/`
+
+## “Portable” Tauri builds (send to another computer)
+
+If you build the Tauri app while Tailscale Serve is enabled on the server machine, the app will embed the `https://*.ts.net` URL and can be copied to another computer.
+
+Requirements:
+
+- The server machine is running `happys start` and Tailscale Serve is enabled
+- The other computer is on the same tailnet and can access the `https://*.ts.net` URL
+
+## Configuration (high-signal)
+
+- `HAPPY_STACKS_TAURI_IDENTIFIER` (legacy: `HAPPY_LOCAL_TAURI_IDENTIFIER`) (default `com.happy.stacks`)
+- `HAPPY_STACKS_TAURI_PRODUCT_NAME` (legacy: `HAPPY_LOCAL_TAURI_PRODUCT_NAME`) (default `Happy Stacks`)
+- `HAPPY_STACKS_TAURI_DEBUG=0` (legacy: `HAPPY_LOCAL_TAURI_DEBUG=0`) (build release-like without devtools)
+- `HAPPY_STACKS_TAURI_SERVER_URL` (legacy: `HAPPY_LOCAL_TAURI_SERVER_URL`) (force the embedded API URL)
+- `HAPPY_STACKS_TAURI_PREFER_TAILSCALE=0` (legacy: `HAPPY_LOCAL_TAURI_PREFER_TAILSCALE=0`) (disable Tailscale detection; always embed `127.0.0.1`)