happy-stacks 0.0.0

package/docs/worktrees-and-forks.md

@@ -0,0 +1,395 @@
+# Worktrees + forks (happy-stacks)
+
+This repo is designed to run the Happy stack locally, while still making it easy to:
+
+- keep using **your fork** day-to-day (your fork’s `main` stays your “distribution” branch)
+- create **clean upstream PR branches** quickly (without carrying fork-only patches)
+
+## Key idea: keep “active components” stable, put worktrees elsewhere
+
+`happy-stacks` runs components from these default paths (in your workspace):
+
+- `components/happy`
+- `components/happy-cli`
+- `components/happy-server-light`
+- (optional) `components/happy-server`
+
+All worktrees live under a hidden folder:
+
+```
+components/.worktrees/<component>/<owner>/<branch...>
+```
+
+Examples:
+
+- `components/.worktrees/happy/slopus/pr/session-rename-upstream`
+- `components/.worktrees/happy-cli/slopus/ci/typecheck-gha-upstream`
+- `components/.worktrees/happy/leeroybrun/local/my-fork-only-patch`
+
+## Branch naming convention
+
+Branches created/managed by `happy-stacks` worktree tooling are named:
+
+```
+<owner>/<branch...>
+```
+
+Where:
+
+- `<owner>` is derived from the repo remote you’re basing on
+  - **origin** → usually your fork owner (e.g. `leeroybrun`)
+  - **upstream** → upstream owner (e.g. `slopus`)
+- `<branch...>` is whatever you choose (`pr/...`, `feat/...`, `local/...`, etc.)
+
+## Choosing which checkout happy-stacks runs
+
+`happy-stacks` supports per-component directory overrides via the stack env file (main: `~/.happy/stacks/main/env`, or a specific stack: `~/.happy/stacks/<name>/env`):
+
+- `HAPPY_STACKS_COMPONENT_DIR_HAPPY` (legacy: `HAPPY_LOCAL_COMPONENT_DIR_HAPPY`)
+- `HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI` (legacy: `HAPPY_LOCAL_COMPONENT_DIR_HAPPY_CLI`)
+- `HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT` (legacy: `HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER_LIGHT`)
+- `HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER` (legacy: `HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER`)
+
+The easiest way to set these is with:
+
+```bash
+happys wt use happy slopus/pr/session-rename-upstream
+happys wt use happy-cli slopus/pr/resume-session-from-ui-upstream
+```
+
+Now `happys dev`, `happys start`, and `happys build` will use those active checkouts.
+
+## Switching server flavor (server-light vs full server)
+
+You can persistently switch which server implementation is used by setting `HAPPY_STACKS_SERVER_COMPONENT` (legacy: `HAPPY_LOCAL_SERVER_COMPONENT`) in the stack env file (main: `~/.happy/stacks/main/env`).
+
+Use the convenience CLI (recommended):
+
+```bash
+happys srv status
+happys srv use happy-server-light
+happys srv use happy-server
+happys srv use --interactive
+```
+
+Note: in a cloned repo, the legacy equivalent is `pnpm srv -- ...`.
+
+Reset back to default:
+
+```bash
+happys wt use happy default
+happys wt use happy-cli default
+happys wt use happy-server-light default
+happys wt use happy-server default
+```
+
+Note:
+- `happys srv use ...` picks **which** server component is run.
+- `happys wt use happy-server-light ...` / `happys wt use happy-server ...` pick **which checkout** is used for each server component.
+- `happys start/dev/doctor` will error if these are accidentally mismatched (e.g. server-light selected but its component dir points inside a `happy-server` checkout).
+
+## Creating worktrees
+
+Create a new worktree branch based on **upstream** (for upstream PRs):
+
+```bash
+happys wt new happy pr/my-feature --from=upstream --use
+```
+
+## Testing a GitHub PR locally (`wt pr`)
+
+If you have a GitHub PR URL (or just the PR number), you can create a worktree at the PR head ref:
+
+```bash
+happys wt pr happy https://github.com/slopus/happy/pull/123 --use
+
+# same, but specify the remote explicitly
+happys wt pr happy 123 --remote=upstream --use
+```
+
+Notes:
+- This uses GitHub’s standard `refs/pull/<N>/head` ref on the chosen remote (default: `upstream`).
+- To refresh the worktree when new commits are pushed to the PR, re-run with `--update`:
+
+```bash
+happys wt pr happy 123 --update
+```
+
+- If you have uncommitted changes in the PR worktree, you can use `--stash` / `--stash-keep`:
+
+```bash
+happys wt pr happy 123 --update --stash
+```
+
+- If the PR was force-pushed and the update is not a fast-forward, `--update` will abort and tell you to re-run with `--update --force`.
+- Use `--slug=<name>` to create a nicer local branch name (example: `slopus/pr/123-fix-thing`).
+
+### Testing a PR inside a stack (recommended)
+
+Create a dedicated stack, then apply the PR into that stack env:
+
+```bash
+happys stack new pr123
+happys stack wt pr123 -- pr happy https://github.com/slopus/happy/pull/123 --use
+happys stack dev pr123
+```
+
+Create a new worktree branch based on **your fork** (for fork-only patches):
+
+```bash
+happys wt new happy local/my-patch --from=origin --use
+```
+
+### Remote + base behavior (automatic)
+
+If you do **not** pass `--remote`, `happys wt new` defaults to using the Git remote named `upstream`.
+
+It will also keep a local **mirror branch** named after the remote owner **and that remote’s default branch**:
+
+- if `upstream` points at `slopus/*` and its default branch is `main`, it will create/update `slopus/main` tracking `upstream/main`
+- if `origin` (or `fork`) points at `leeroybrun/*` and its default branch is `happy-server-light`, it will create/update `leeroybrun/happy-server-light` tracking `fork/happy-server-light`
+
+New PR worktrees created without `--base` will default to using that mirror branch (example: `slopus/main`) as the base.
+
+### Syncing a remote to a local mirror branch
+
+`happys wt sync <component>` keeps a local mirror branch up to date inside that component repo:
+
+- It fetches the remote’s **default branch** (for that remote + component)
+- Then it updates a local branch named `<owner>/<default-branch>` to track it
+
+Examples:
+
+```bash
+# Sync upstream (usually slopus/main)
+happys wt sync happy --remote=upstream
+
+# Sync your fork remote (origin/fork). For happy-server-light this is typically leeroybrun/happy-server-light.
+happys wt sync happy-server-light --remote=origin
+```
+
+After syncing, you can explicitly base a new worktree on the mirror branch if you want:
+
+```bash
+happys wt new happy pr/my-feature --remote=upstream --base=slopus/main --use
+```
+
+### Interactive mode
+
+If you prefer prompts:
+
+```bash
+happys wt new --interactive
+happys wt use --interactive
+```
+
+### JSON mode
+
+For programmatic usage:
+
+```bash
+happys wt list happy --json
+happys wt sync happy --json
+happys wt new happy pr/my-feature --use --json
+happys wt status happy --json
+happys wt update happy default --dry-run --json
+happys wt push happy default --dry-run --json
+```
+
+## Migrating old worktree layout (one-time)
+
+## Workflow helpers (sync / update / push)
+
+These are convenience commands to keep PR branches updated and to automate the “check conflicts first” loop.
+
+### `wt status`
+
+Shows branch / upstream / ahead/behind / clean state:
+
+```bash
+happys wt status happy
+happys wt status happy --json
+```
+
+## Worktree selector semantics (`default` / `main` / `active`)
+
+Many `happys wt` commands accept an optional “selector” argument to choose *which checkout* you mean.
+
+- **(omitted)** or **`active`**: the currently active checkout for that component (env override if set; otherwise `components/<component>`)
+- **`default`** or **`main`**: the default embedded checkout at `components/<component>`
+- **`<owner>/<branch...>`**: resolves to `components/.worktrees/<component>/<owner>/<branch...>`
+- **`/absolute/path`**: explicit checkout path
+
+Important: `default` / `main` refers to the **checkout location**, not the Git branch name.
+
+### `wt update`
+
+Update a worktree branch from its upstream base.
+
+- **Default base**: the per-repo mirror branch (example: `slopus/main`, or `leeroybrun/happy-server-light` when syncing from your fork remote)
+- **Default mode**: `rebase` (recommended for clean PR branches)
+
+```bash
+# Check if update would conflict (no changes applied)
+happys wt update happy default --dry-run
+
+# Apply rebase if clean; if conflicts, abort and print conflicting files
+happys wt update happy default
+
+# If you have uncommitted changes, auto-stash, update, then pop the stash back (only if the update was clean)
+happys wt update happy default --stash
+
+# Same, but keep the stash (do not pop) so you can apply it later
+happys wt update happy default --stash-keep
+
+# Keep conflict state in place for manual resolution
+happys wt update happy default --force
+
+# Use merge instead of rebase (optional)
+happys wt update happy default --merge
+```
+
+## Open a “real” shell in a worktree (`wt shell`)
+
+This starts a new interactive shell **with cwd set to the worktree**, which is the closest thing to a “real cd” a CLI can do:
+
+```bash
+happys wt shell happy slopus/pr/123
+
+# choose a shell explicitly
+happys wt shell happy slopus/pr/123 --shell=/bin/zsh
+```
+
+You can also ask it to open a new terminal window/tab (best-effort):
+
+```bash
+happys wt shell happy slopus/pr/123 --new-window
+```
+
+On macOS, auto-detection tries: Ghostty → iTerm → Terminal. You can override via:
+
+- `HAPPY_STACKS_WT_TERMINAL=ghostty|iterm|terminal|current` (legacy: `HAPPY_LOCAL_WT_TERMINAL`)
+- `HAPPY_STACKS_WT_SHELL=/path/to/shell` (legacy: `HAPPY_LOCAL_WT_SHELL`)
+
+Works with stacks too:
+
+```bash
+happys stack wt pr123 -- shell happy active
+```
+
+## Open in editors (`wt code` / `wt cursor`)
+
+```bash
+happys wt code happy slopus/pr/123
+happys wt cursor happy slopus/pr/123
+```
+
+Notes:
+- `wt code` requires VS Code’s `code` CLI on PATH.
+- `wt cursor` uses the `cursor` CLI if available; on macOS it falls back to `open -a Cursor`.
+
+### `wt push`
+
+Push current HEAD branch to a remote:
+
+```bash
+happys wt push happy default
+happys wt push happy default --remote=origin
+happys wt push happy default --dry-run
+```
+
+### Create worktrees from an existing worktree/branch
+
+If you want to base a new worktree off another worktree’s current branch/HEAD:
+
+```bash
+happys wt new happy pr/next-step --base-worktree=slopus/pr/my-existing-thing
+```
+
+## Run git inside a worktree (`wt git`)
+
+This is a convenience wrapper that runs `git` in a selected checkout:
+
+```bash
+happys wt git happy main -- status
+happys wt git happy active -- log -n 5 --oneline
+happys wt git happy slopus/pr/session-rename-upstream -- diff
+```
+
+For programmatic usage:
+
+```bash
+happys wt git happy main -- status --porcelain -b --json
+```
+
+## Sync/update everything
+
+```bash
+happys wt sync-all
+happys wt sync-all --json
+
+# Dry-run updates across all worktrees for a component (or all components if omitted)
+happys wt update-all happy --dry-run
+happys wt update-all --dry-run --json
+```
+
+If you previously had worktrees under `components/happy-worktrees/*`, run:
+
+```bash
+happys wt migrate
+```
+
+This will:
+
+- move worktrees into `components/.worktrees/...`
+- rename checked-out branches to the `<owner>/...` convention
+
+## Server selection: happy-server-light vs happy-server
+
+By default, `happy-stacks` uses `happy-server-light`.
+
+To run the full upstream server instead:
+
+```bash
+happys bootstrap --server=happy-server
+happys dev --server=happy-server
+```
+
+Notes:
+
+- `happys start` (production-like) serves the built UI via `happy-server-light`; UI serving is **disabled** automatically when using `happy-server`.
+- `happys dev` works with either server (it runs the UI separately via Expo).
+
+### Selecting server via env (including LaunchAgent service)
+
+You can set a default server implementation via:
+
+- `HAPPY_STACKS_SERVER_COMPONENT=happy-server-light` (default) (legacy: `HAPPY_LOCAL_SERVER_COMPONENT`)
+- `HAPPY_STACKS_SERVER_COMPONENT=happy-server` (legacy: `HAPPY_LOCAL_SERVER_COMPONENT`)
+
+If you use the macOS LaunchAgent (`happys service install`), the service persists only a pointer to the env file path; the server flavor is read from that env file on every start.
+
+## Env precedence (important)
+
+When `happy-stacks` starts, it loads env in this order:
+
+1) `~/.happy-stacks/.env` (defaults)
+2) `~/.happy-stacks/env.local` (optional global overrides; most config is written to the stack env)
+3) `HAPPY_STACKS_ENV_FILE` (stack env / explicit overlay; highest precedence for `HAPPY_STACKS_*` / `HAPPY_LOCAL_*`)
+
+Notes:
+
+- `HAPPY_STACKS_ENV_FILE` (legacy: `HAPPY_LOCAL_ENV_FILE`) is the mechanism used by `happys stack ...` to apply stack-specific settings.
+- For stack runs, the stack wrapper clears any already-exported `HAPPY_STACKS_*` / legacy `HAPPY_LOCAL_*` variables so the stack env file stays authoritative.
+ - By default (after `happys init`), commands that “persist config” write to the main stack env file: `~/.happy/stacks/main/env`.
+
+## Repo URLs
+
+You can override clone sources in your main stack env file (`~/.happy/stacks/main/env`) or any explicit `HAPPY_STACKS_ENV_FILE`:
+
+- `HAPPY_STACKS_REPO_SOURCE=forks|upstream` (legacy: `HAPPY_LOCAL_REPO_SOURCE`)
+- `HAPPY_STACKS_UI_REPO_URL` (legacy: `HAPPY_LOCAL_UI_REPO_URL`)
+- `HAPPY_STACKS_CLI_REPO_URL` (legacy: `HAPPY_LOCAL_CLI_REPO_URL`)
+- `HAPPY_STACKS_SERVER_REPO_URL` (legacy: `HAPPY_LOCAL_SERVER_REPO_URL`) (server-light, backwards compatible)
+- `HAPPY_STACKS_SERVER_LIGHT_REPO_URL` (legacy: `HAPPY_LOCAL_SERVER_LIGHT_REPO_URL`)
+- `HAPPY_STACKS_SERVER_FULL_REPO_URL` (legacy: `HAPPY_LOCAL_SERVER_FULL_REPO_URL`)

package/extras/swiftbar/auth-login.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+set -euo pipefail
+
+# Run auth login (interactive) in the user's preferred terminal.
+#
+# Usage (backwards compatible with older callers):
+#   ./auth-login.sh main <serverUrl> <webappUrl>
+#   ./auth-login.sh <stackName> <serverUrl> <webappUrl> <cliHomeDir>
+#
+# New behavior:
+# - Delegate to `happys auth login` / `happys stack auth <name> login` so URL + cliHome resolution stays centralized.
+
+stack="${1:-main}"
+_server_url="${2:-}"   # ignored (kept for backwards compatibility)
+_webapp_url="${3:-}"   # ignored (kept for backwards compatibility)
+_cli_home_dir="${4:-}" # ignored (kept for backwards compatibility)
+
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-$HAPPY_STACKS_HOME_DIR}"
+
+PNPM_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/pnpm-term.sh"
+if [[ ! -x "$PNPM_TERM" ]]; then
+  echo "missing terminal happys wrapper: $PNPM_TERM" >&2
+  exit 1
+fi
+
+if [[ "$stack" == "main" ]]; then
+  exec "$PNPM_TERM" auth login
+fi
+
+exec "$PNPM_TERM" stack auth "$stack" login

package/extras/swiftbar/happy-stacks.5s.sh

@@ -0,0 +1,218 @@
+#!/bin/bash
+
+# <xbar.title>Happy Stacks</xbar.title>
+# <xbar.version>1.0.0</xbar.version>
+# <xbar.author>Happy Stacks</xbar.author>
+# <xbar.author.github>leeroybrun</xbar.author.github>
+# <xbar.desc>Monitor and control your Happy stacks from the menu bar</xbar.desc>
+# <xbar.dependencies>node</xbar.dependencies>
+# <swiftbar.hideAbout>true</swiftbar.hideAbout>
+# <swiftbar.hideRunInTerminal>true</swiftbar.hideRunInTerminal>
+# <swiftbar.hideLastUpdated>false</swiftbar.hideLastUpdated>
+# <swiftbar.hideDisablePlugin>true</swiftbar.hideDisablePlugin>
+# <swiftbar.hideSwiftBar>true</swiftbar.hideSwiftBar>
+# <swiftbar.refreshOnOpen>false</swiftbar.refreshOnOpen>
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-$HAPPY_STACKS_HOME_DIR}"
+HAPPY_LOCAL_PORT="${HAPPY_LOCAL_PORT:-3005}"
+
+# Map common preferences from HAPPY_STACKS_* -> HAPPY_LOCAL_* (SwiftBar scripts are shell-based).
+if [[ -n "${HAPPY_STACKS_WT_TERMINAL:-}" && -z "${HAPPY_LOCAL_WT_TERMINAL:-}" ]]; then HAPPY_LOCAL_WT_TERMINAL="$HAPPY_STACKS_WT_TERMINAL"; fi
+if [[ -n "${HAPPY_STACKS_WT_SHELL:-}" && -z "${HAPPY_LOCAL_WT_SHELL:-}" ]]; then HAPPY_LOCAL_WT_SHELL="$HAPPY_STACKS_WT_SHELL"; fi
+if [[ -n "${HAPPY_STACKS_SWIFTBAR_ICON_PATH:-}" && -z "${HAPPY_LOCAL_SWIFTBAR_ICON_PATH:-}" ]]; then HAPPY_LOCAL_SWIFTBAR_ICON_PATH="$HAPPY_STACKS_SWIFTBAR_ICON_PATH"; fi
+
+# Storage root migrated from ~/.happy/local -> ~/.happy/stacks/main.
+if [[ -z "${HAPPY_HOME_DIR:-}" ]]; then
+  if [[ -d "$HOME/.happy/stacks/main" ]] || [[ ! -d "$HOME/.happy/local" ]]; then
+    HAPPY_HOME_DIR="$HOME/.happy/stacks/main"
+  else
+    HAPPY_HOME_DIR="$HOME/.happy/local"
+  fi
+fi
+CLI_HOME_DIR="$HAPPY_HOME_DIR/cli"
+LOGS_DIR="$HAPPY_HOME_DIR/logs"
+
+# Colors
+GREEN="#34C759"
+RED="#FF3B30"
+YELLOW="#FFCC00"
+GRAY="#8E8E93"
+BLUE="#007AFF"
+
+# ============================================================================
+# Load libs
+# ============================================================================
+
+LIB_DIR="$HAPPY_LOCAL_DIR/extras/swiftbar/lib"
+if [[ ! -f "$LIB_DIR/utils.sh" ]]; then
+  echo "Happy Stacks"
+  echo "---"
+  echo "SwiftBar libs missing at: $LIB_DIR"
+  echo "↪ run: happys menubar install"
+  exit 0
+fi
+
+# shellcheck source=/dev/null
+source "$LIB_DIR/utils.sh"
+HAPPY_LOCAL_DIR="$(resolve_happy_local_dir)"
+LIB_DIR="$HAPPY_LOCAL_DIR/extras/swiftbar/lib"
+# shellcheck source=/dev/null
+source "$LIB_DIR/icons.sh"
+# shellcheck source=/dev/null
+source "$LIB_DIR/system.sh"
+# shellcheck source=/dev/null
+source "$LIB_DIR/git.sh"
+# shellcheck source=/dev/null
+source "$LIB_DIR/render.sh"
+
+# ============================================================================
+# Menu
+# ============================================================================
+
+PNPM_BIN="$(resolve_pnpm_bin)"
+MAIN_PORT="$(resolve_main_port)"
+MAIN_SERVER_COMPONENT="$(resolve_main_server_component)"
+TAILSCALE_URL="$(get_tailscale_url)"
+MAIN_ENV_FILE="$(resolve_main_env_file)"
+
+ensure_launchctl_cache
+
+MAIN_COLLECT="$(collect_stack_status "$MAIN_PORT" "$CLI_HOME_DIR" "com.happy.stacks" "$HAPPY_HOME_DIR")"
+IFS=$'\t' read -r MAIN_LEVEL MAIN_SERVER_STATUS MAIN_SERVER_PID MAIN_SERVER_METRICS MAIN_DAEMON_STATUS MAIN_DAEMON_PID MAIN_DAEMON_METRICS MAIN_DAEMON_UPTIME MAIN_LAST_HEARTBEAT MAIN_LAUNCHAGENT_STATUS MAIN_AUTOSTART_PID MAIN_AUTOSTART_METRICS <<<"$MAIN_COLLECT"
+for v in MAIN_SERVER_PID MAIN_SERVER_METRICS MAIN_DAEMON_PID MAIN_DAEMON_METRICS MAIN_DAEMON_UPTIME MAIN_LAST_HEARTBEAT MAIN_AUTOSTART_PID MAIN_AUTOSTART_METRICS; do
+  if [[ "${!v}" == "-" ]]; then
+    printf -v "$v" '%s' ""
+  fi
+done
+
+# Menu bar icon
+MENU_STATUS_ICON_B64="$(status_icon_b64 "$MAIN_LEVEL" 18)"
+if [[ -n "$MENU_STATUS_ICON_B64" ]]; then
+  echo " | image=$MENU_STATUS_ICON_B64"
+else
+  STATUS_COLOR="$(color_for_level "$MAIN_LEVEL")"
+  ICON_B64="$(get_menu_icon_b64)"
+  if [[ -n "$ICON_B64" ]]; then
+    echo "● | templateImage=$ICON_B64 color=$STATUS_COLOR"
+  else
+    echo "Happy"
+  fi
+fi
+
+echo "---"
+echo "Happy Stacks | size=14 font=SF Pro Display"
+echo "---"
+
+# Main stack (inline)
+echo "Main stack"
+echo "---"
+export MAIN_LEVEL="$MAIN_LEVEL"
+render_stack_info "" "main" "$MAIN_PORT" "$MAIN_SERVER_COMPONENT" "$HAPPY_HOME_DIR" "$CLI_HOME_DIR" "com.happy.stacks" "$MAIN_ENV_FILE" "$TAILSCALE_URL"
+render_component_server "" "main" "$MAIN_PORT" "$MAIN_SERVER_COMPONENT" "$MAIN_SERVER_STATUS" "$MAIN_SERVER_PID" "$MAIN_SERVER_METRICS" "$TAILSCALE_URL" "com.happy.stacks"
+render_component_daemon "" "$MAIN_DAEMON_STATUS" "$MAIN_DAEMON_PID" "$MAIN_DAEMON_METRICS" "$MAIN_DAEMON_UPTIME" "$MAIN_LAST_HEARTBEAT" "$CLI_HOME_DIR/daemon.state.json" "main"
+render_component_autostart "" "main" "com.happy.stacks" "$MAIN_LAUNCHAGENT_STATUS" "$MAIN_AUTOSTART_PID" "$MAIN_AUTOSTART_METRICS" "$LOGS_DIR"
+render_component_tailscale "" "main" "$TAILSCALE_URL"
+
+echo "---"
+echo "Stacks"
+echo "---"
+
+if [[ -n "$PNPM_BIN" ]]; then
+  PNPM_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/pnpm-term.sh"
+  echo "New stack (interactive) | bash=$PNPM_TERM param1=stack param2=new param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "List stacks | bash=$PNPM_TERM param1=stack param2=list dir=$HAPPY_LOCAL_DIR terminal=false"
+  echo "---"
+fi
+
+STACKS_DIR="$HOME/.happy/stacks"
+if [[ -d "$STACKS_DIR" ]]; then
+  STACK_NAMES="$(ls -1 "$STACKS_DIR" 2>/dev/null || true)"
+  if [[ -z "$STACK_NAMES" ]]; then
+    echo "No stacks found | color=$GRAY"
+  fi
+  for s in $STACK_NAMES; do
+    env_file="$STACKS_DIR/$s/env"
+    [[ -f "$env_file" ]] || continue
+
+    port="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_PORT")"
+    [[ -n "$port" ]] || continue
+
+    server_component="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_COMPONENT")"
+    [[ -n "$server_component" ]] || server_component="happy-server-light"
+
+    cli_home_dir="$(dotenv_get "$env_file" "HAPPY_LOCAL_CLI_HOME_DIR")"
+    [[ -n "$cli_home_dir" ]] || cli_home_dir="$STACKS_DIR/$s/cli"
+
+    base_dir="$STACKS_DIR/$s"
+    label="com.happy.stacks.$s"
+
+    COLLECT="$(collect_stack_status "$port" "$cli_home_dir" "$label" "$base_dir")"
+    IFS=$'\t' read -r LEVEL SERVER_STATUS SERVER_PID SERVER_METRICS DAEMON_STATUS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT LAUNCHAGENT_STATUS AUTOSTART_PID AUTOSTART_METRICS <<<"$COLLECT"
+    for v in SERVER_PID SERVER_METRICS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT AUTOSTART_PID AUTOSTART_METRICS; do
+      if [[ "${!v}" == "-" ]]; then
+        printf -v "$v" '%s' ""
+      fi
+    done
+
+    render_stack_overview_item "Stack: $s" "$LEVEL" ""
+    export STACK_LEVEL="$LEVEL"
+    render_stack_info "--" "$s" "$port" "$server_component" "$base_dir" "$cli_home_dir" "$label" "$env_file" ""
+    render_component_server "--" "$s" "$port" "$server_component" "$SERVER_STATUS" "$SERVER_PID" "$SERVER_METRICS" "" "$label"
+    render_component_daemon "--" "$DAEMON_STATUS" "$DAEMON_PID" "$DAEMON_METRICS" "$DAEMON_UPTIME" "$LAST_HEARTBEAT" "$cli_home_dir/daemon.state.json" "$s"
+    render_component_autostart "--" "$s" "$label" "$LAUNCHAGENT_STATUS" "$AUTOSTART_PID" "$AUTOSTART_METRICS" "$base_dir/logs"
+    render_component_tailscale "--" "$s" ""
+    render_components_menu "--" "stack" "$s" "$env_file"
+  done
+else
+  echo "No stacks dir found at ~/.happy/stacks | color=$GRAY"
+fi
+
+echo "---"
+render_components_menu "" "main" "main" ""
+
+echo "Worktrees | sfimage=arrow.triangle.branch"
+if [[ -z "$PNPM_BIN" ]]; then
+  echo "--⚠️ happys not found (run: npx happy-stacks init, or install happy-stacks globally)"
+else
+  PNPM_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/pnpm-term.sh"
+  echo "--Use (interactive) | bash=$PNPM_TERM param1=wt param2=use param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--New (interactive) | bash=$PNPM_TERM param1=wt param2=new param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--PR worktree (prompt) | bash=$HAPPY_LOCAL_DIR/extras/swiftbar/wt-pr.sh dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--Sync mirrors (all) | bash=$PNPM_BIN param1=wt param2=sync-all dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--Update all (dry-run) | bash=$PNPM_TERM param1=wt param2=update-all param3=--dry-run dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--Update all (apply) | bash=$PNPM_BIN param1=wt param2=update-all dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+fi
+
+echo "---"
+echo "Setup / Tools"
+if [[ -z "$PNPM_BIN" ]]; then
+  echo "--⚠️ happys not found (run: npx happy-stacks init, or install happy-stacks globally)"
+else
+  PNPM_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/pnpm-term.sh"
+  echo "--Bootstrap (clone/install) | bash=$PNPM_TERM param1=bootstrap dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--CLI link (install happy wrapper) | bash=$PNPM_TERM param1=cli:link dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--Mobile dev helper | bash=$PNPM_TERM param1=mobile dir=$HAPPY_LOCAL_DIR terminal=false"
+fi
+
+echo "---"
+echo "Refresh | sfimage=arrow.clockwise refresh=true"
+echo "---"
+echo "Refresh interval | sfimage=timer"
+SET_INTERVAL="$HAPPY_LOCAL_DIR/extras/swiftbar/set-interval.sh"
+echo "--10s | bash=$SET_INTERVAL param1=10s dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--30s | bash=$SET_INTERVAL param1=30s dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--1m | bash=$SET_INTERVAL param1=1m dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--5m (recommended) | bash=$SET_INTERVAL param1=5m dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--10m | bash=$SET_INTERVAL param1=10m dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--15m | bash=$SET_INTERVAL param1=15m dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--30m | bash=$SET_INTERVAL param1=30m dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--1h | bash=$SET_INTERVAL param1=1h dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--2h | bash=$SET_INTERVAL param1=2h dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--6h | bash=$SET_INTERVAL param1=6h dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--12h | bash=$SET_INTERVAL param1=12h dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+echo "--1d | bash=$SET_INTERVAL param1=1d dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"exit 0