happy-stacks 0.1.0 → 0.2.0

package/docs/menubar.md

@@ -32,6 +32,26 @@ SwiftBar runs a script on an interval and renders its output as native macOS men
   - Each component includes a **Worktrees** submenu listing all worktrees, with actions to switch/open
   - Quick actions: `wt status/sync/update`, PR worktree prompt, open shells/editors (`wt shell/code/cursor`)
   - Shows **origin** and **upstream** comparisons for the component repo’s main branch (based on your last `git fetch`)
+  - Uses a **Git cache** by default so SwiftBar refresh stays fast even with many stacks/worktrees
+
+## Modes: selfhost vs dev
+
+The menu supports two modes:
+
+- **Selfhost mode** (`selfhost`): lightweight “control panel” for running Happy.
+  - Shows only the main stack essentials (Server/Daemon/Autostart/Tailscale) plus a small **Maintenance** section.
+  - Hides developer-oriented sections like stacks enumeration, components git/worktrees, and worktree tooling.
+- **Dev mode** (`dev`): full happy-stacks control plane (stacks + components + worktrees).
+
+### How to switch modes
+
+- In the menu, use the **Mode** section at the top, or
+- From a terminal:
+
+```bash
+happys menubar mode selfhost
+happys menubar mode dev
+```
 
 ## Stacks (multiple instances)
 
@@ -125,6 +145,40 @@ The plugin defaults to a slower interval (recommended), and also sets:
 
 You can also change the interval directly from the menu via **Refresh interval** (it renames the plugin file and restarts SwiftBar).
 
+## Git cache (important for performance)
+
+Git/worktree inspection is the most expensive part of the menu when you have many stacks.
+By default, the plugin runs in **cached mode**:
+
+- It renders git/worktree info from an on-disk cache under `~/.happy-stacks/cache/swiftbar/git`.
+- Normal menu refreshes do **not** run git commands (so refresh stays snappy).
+- The cache is refreshed explicitly (via menu actions), and can optionally refresh on TTL expiry.
+
+Controls and settings:
+
+- **Refresh now**: open **Components → Git cache** and run:
+  - “Refresh now (main components)”
+  - “Refresh now (all stacks/components)”
+  - or “Refresh now (this stack)” from a stack’s Components menu
+- **TTL**: `HAPPY_STACKS_SWIFTBAR_GIT_TTL_SEC` (default `3600` seconds)
+- **TTL**: `HAPPY_STACKS_SWIFTBAR_GIT_TTL_SEC` (default `21600` seconds = 6 hours)
+- **Mode**: `HAPPY_STACKS_SWIFTBAR_GIT_MODE=cached|live` (default `cached`)
+- (Optional) **Background auto-refresh**: `HAPPY_STACKS_SWIFTBAR_GIT_AUTO_REFRESH_SCOPE=main|all|off` (default `main`)
+
+Notes:
+
+- Cached git info can be stale; it’s meant for at-a-glance signal.
+- Actions like worktree switching/build/dev are always live (they use `happys`); only *displayed git status* is cached.
+
+## Maintenance (selfhost mode)
+
+In **selfhost** mode, the menu includes a **Maintenance** section that can:
+
+- show whether a `happy-stacks` update is available (from cached `~/.happy-stacks/cache/update.json`)
+- run:
+  - `happys self check`
+  - `happys self update`
+
 ## Terminal preference for interactive actions
 
 Many menu actions open a terminal (interactive wizards, long-running dev servers, etc).

package/docs/paths-and-env.md

@@ -0,0 +1,141 @@
+# Paths, folders, and env precedence
+
+This doc explains the **directories** that Happy Stacks uses (home/workspace/runtime/stacks), and the **environment file precedence** used by `happys`.
+
+If you’re ever unsure what your machine is actually using, run:
+
+```bash
+happys where
+```
+
+---
+
+## Quick glossary
+
+- **CLI root dir**
+  - The directory containing the `happy-stacks` scripts (`scripts/*.mjs`) that your `happys` command is currently executing.
+  - This is *not* necessarily your current shell `cwd`.
+  - It can be:
+    - a cloned repo checkout (e.g. `/Users/<you>/.../happy-local`), or
+    - the installed runtime package under `~/.happy-stacks/runtime/node_modules/happy-stacks` (see “Runtime dir”).
+
+- **Home dir** (`HAPPY_STACKS_HOME_DIR`)
+  - Default: `~/.happy-stacks`
+  - Stores **global user config** + caches, and may include a runtime install.
+
+- **Runtime dir** (`HAPPY_STACKS_RUNTIME_DIR`)
+  - Default: `~/.happy-stacks/runtime`
+  - Used by `happys self update` to install/upgrade a pinned `happy-stacks` runtime package.
+
+- **Workspace dir** (`HAPPY_STACKS_WORKSPACE_DIR`)
+  - Default: `~/.happy-stacks/workspace` (when it exists).
+  - This is the **storage workspace for component repos and worktrees** used by Happy Stacks.
+  - Important: this is **not your IDE workspace**; it’s where Happy Stacks keeps `components/` by default.
+  - Back-compat: before you run `happys init` (cloned repo usage), we fall back to using the CLI root dir as the workspace, so `components/` lives inside the repo checkout.
+
+- **Components dir**
+  - Computed as: `<workspaceDir>/components`
+  - Contains `happy`, `happy-cli`, `happy-server-light`, `happy-server`, plus `.worktrees/`.
+
+- **Stacks storage dir**
+  - Default: `~/.happy/stacks`
+  - Each stack lives under `~/.happy/stacks/<name>/...` and has its own env file:
+    - `~/.happy/stacks/<name>/env`
+  - Legacy stacks path is also supported:
+    - `~/.happy/local/stacks/<name>/env`
+
+---
+
+## “Where am I actually running from?”
+
+`happys` may **re-exec** to a different CLI root dir (for example, when you use an installed shim but want it to run a local checkout).
+
+- Run `happys where` to see:
+  - **rootDir** (CLI root dir)
+  - **homeDir** (stacks home dir)
+  - **runtimeDir**
+  - **workspaceDir**
+  - resolved env file paths
+
+Tip: `happys where --json` is easier to parse.
+
+---
+
+## Env files + precedence (lowest → highest)
+
+Happy Stacks loads env in `scripts/utils/env.mjs`.
+
+### 0) “Canonical pointer” env (discovery)
+
+If `HAPPY_STACKS_HOME_DIR` is *not* set, we first try to read the **canonical pointer** env file to discover the intended home dir (useful for LaunchAgents / SwiftBar / minimal shells).
+
+- Default canonical pointer path: `~/.happy-stacks/.env`
+- Override canonical pointer location:
+  - `HAPPY_STACKS_CANONICAL_HOME_DIR=/some/dir` (pointer becomes `<dir>/.env`)
+
+### 1) Global defaults (home config) OR cloned-repo defaults
+
+If home config exists, we load:
+
+- `~/.happy-stacks/.env` (**defaults**)
+- `~/.happy-stacks/env.local` (**overrides**, prefix-aware for `HAPPY_STACKS_*` / `HAPPY_LOCAL_*`)
+
+If home config does *not* exist (cloned repo usage before `happys init`), we load:
+
+- `<cliRootDir>/.env`
+- `<cliRootDir>/env.local` (prefix-aware for `HAPPY_STACKS_*` / `HAPPY_LOCAL_*`)
+
+### 2) Repo `.env` fallback (dev convenience)
+
+Even when home config exists, we also load:
+
+- `<cliRootDir>/.env` (non-overriding fallback)
+
+This exists so repo-local dev settings (example: `HAPPY_CODEX_BIN`) can work without forcing everyone to duplicate them into `~/.happy-stacks/env.local`.
+
+Notes:
+- This is a **fallback only** (`override: false`): it won’t stomp on values already provided by the environment or home config.
+- We intentionally do **not** auto-load `<cliRootDir>/env.local` in this “home config exists” path, because it’s higher-precedence and can unexpectedly fight stack config.
+
+### 3) Stack env overlay (highest precedence)
+
+Finally, we load the active stack env file (override = true):
+
+- `HAPPY_STACKS_ENV_FILE` (or legacy `HAPPY_LOCAL_ENV_FILE`)
+- if neither is set, we auto-select the env file for the current stack (defaults to `main`) if it exists
+
+Stack env files are allowed to contain **non-prefixed keys** (like `DATABASE_URL`) because that’s required for per-stack isolation.
+
+---
+
+## What should go where? (rules of thumb)
+
+- Put **global, machine-wide defaults** in `~/.happy-stacks/.env`.
+- Put **your personal overrides** in `~/.happy-stacks/env.local`.
+- Put **per-stack isolation config** in the stack env file `~/.happy/stacks/<name>/env` (this is what `happys stack edit` and `happys stack wt` mutate).
+- Put **repo-local dev-only defaults** in `<cliRootDir>/.env` (works best when you’re actually running from that checkout as the CLI root dir).
+
+---
+
+## Sandbox / test installs (fully isolated)
+
+If you want to test the full install + setup flows without touching your real installation, run with:
+
+```bash
+npx happy-stacks --sandbox-dir /tmp/happy-stacks-sandbox where
+```
+
+In sandbox mode, Happy Stacks redirects **home/workspace/runtime/storage** under the sandbox folder (so you can `rm -rf` it to reset).
+
+Global OS side effects (PATH edits, SwiftBar plugin install, LaunchAgents/systemd services) are **disabled by default** in sandbox mode.
+To explicitly allow them for testing, set:
+
+- `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1`
+
+---
+
+## Related docs
+
+- `docs/stacks.md` (stacks lifecycle + commands)
+- `docs/worktrees-and-forks.md` (worktrees layout + upstream/fork workflows)
+

package/docs/server-flavors.md

@@ -13,8 +13,67 @@ Both are forks/flavors of the same upstream server repo (`slopus/happy-server`),
 
 - **`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
+  - the upstream server typically does **not** serve the built UI itself, but happy-stacks provides a **UI gateway** so you still get a single URL that serves the UI and proxies API/websockets/files
+  - useful when you need to test upstream/server-only behavior or reproduce upstream issues, with per-stack infra isolation
+
+## Full server infra (no AWS required)
+
+`happy-server` requires:
+
+- Postgres (`DATABASE_URL`)
+- Redis (`REDIS_URL`)
+- S3-compatible object storage (`S3_*`)
+
+Happy Stacks can **manage this for you automatically per stack** using Docker Compose (Postgres + Redis + Minio),
+so you **do not need AWS S3**.
+
+This happens automatically when you run `happys start/dev --server=happy-server` (or when a stack uses `happy-server`),
+unless you disable it with:
+
+```bash
+export HAPPY_STACKS_MANAGED_INFRA=0
+```
+
+If disabled, you must provide `DATABASE_URL`, `REDIS_URL`, and `S3_*` yourself.
+
+## UI serving with `happy-server`
+
+The upstream `happy-server` does not serve the built UI itself.
+
+For a “one URL” UX (especially with Tailscale), happy-stacks starts a lightweight **UI gateway** that:
+
+- serves the built UI at `/` (if a build exists)
+- reverse-proxies API calls to the backend server
+- reverse-proxies realtime websocket upgrades (`/v1/updates`)
+- reverse-proxies public files (to local Minio)
+
+This means `happys start --server=happy-server` can still work end-to-end without requiring AWS S3 or a separate nginx setup.
+
+## Migrating between flavors (SQLite ⇢ Postgres)
+
+Happy Stacks includes an **experimental** migration helper that can copy core chat data from a
+`happy-server-light` stack (SQLite) into a `happy-server` stack (Postgres):
+
+```bash
+happys migrate light-to-server --from-stack=main --to-stack=full1
+```
+
+Optional: include local public files (server-light `files/`) by mirroring them into Minio:
+
+```bash
+happys migrate light-to-server --from-stack=main --to-stack=full1 --include-files
+```
+
+Notes:
+- This preserves IDs (session URLs remain valid on the target server).
+- It also copies the `HANDY_MASTER_SECRET` from the source stack into the target stack’s secret file so auth tokens remain valid.
+
+## Prisma behavior (why start is safer under LaunchAgents)
+
+- **`happys start`** is “production-like”. It avoids running heavyweight schema sync loops under launchd KeepAlive.
+- **`happys dev`** is for rapid iteration:
+  - for `happy-server`: Happy Stacks runs `prisma migrate deploy` by default (configurable via `HAPPY_STACKS_PRISMA_MIGRATE`).
+  - for `happy-server-light`: the upstream dev script runs `prisma db push` by default (configurable via `HAPPY_STACKS_PRISMA_PUSH`).
 
 Important: for a given run (`happys start` / `happys dev`) you choose **one** flavor.
 

package/docs/stacks.md

@@ -7,6 +7,7 @@ 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)
+- (when using `happy-server`) isolated **infra** (Postgres/Redis/Minio) managed per-stack
 
 Stacks are configured via a plain env file stored under:
 
@@ -40,6 +41,43 @@ Auto-pick a port:
 happys stack new exp2
 ```
 
+## Create a PR test stack (copy/paste friendly)
+
+If you want maintainers to be able to try your PR quickly, you can give them a single command that:
+
+- creates an isolated stack
+- checks out PR(s) into worktrees
+- pins those worktrees to the stack
+- optionally seeds auth
+- optionally starts the stack in dev mode
+
+Example (most common):
+
+```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
+```
+
+Notes:
+
+- `--remote` (default `upstream`) controls which Git remote is used to fetch `refs/pull/<n>/head`.
+- `--seed-auth` uses `happys stack auth <stack> copy-from <source>` under the hood, which also best-effort seeds DB Account rows (avoids FK errors like Prisma `P2003`).
+- You can use your existing non-stacks Happy install as an auth seed source with:
+  - `--copy-auth-from=legacy` (reads from `~/.happy/{cli,server-light}` best-effort)
+- `--link-auth` symlinks auth files instead of copying them (keeps credentials in sync, but reduces isolation).
+- For full-server stacks (`happy-server`), seeding may need Docker infra:
+
+```bash
+happys stack pr pr789 \
+  --server=happy-server \
+  --happy-server=https://github.com/slopus/happy-server/pull/789 \
+  --seed-auth --copy-auth-from=dev-auth --with-infra \
+  --dev
+```
+
 Interactive wizard (TTY only):
 
 ```bash
@@ -52,6 +90,15 @@ The wizard lets you:
 - 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`)
 
+When creating `--server=happy-server` stacks, happy-stacks will also reserve additional ports and persist
+the stack-scoped infra config in the stack env file (so restarts are stable):
+
+- `HAPPY_STACKS_PG_PORT`
+- `HAPPY_STACKS_REDIS_PORT`
+- `HAPPY_STACKS_MINIO_PORT`
+- `HAPPY_STACKS_MINIO_CONSOLE_PORT`
+- `DATABASE_URL`, `REDIS_URL`, `S3_*`
+
 ## Run a stack
 
 Dev mode:
@@ -128,9 +175,9 @@ Global/non-stack commands:
 - `happys bootstrap` (sets up shared component repos)
 - `happys cli:link` (installs `happy` shim under `~/.happy-stacks/bin/`)
 
-## Services (macOS LaunchAgents)
+## Services (autostart)
 
-Each stack can have its own LaunchAgent (so multiple stacks can start at login).
+Each stack can have its own autostart service (so multiple stacks can start at login).
 
 ```bash
 happys stack service exp1 install
@@ -141,10 +188,12 @@ happys stack service exp1 logs
 
 Implementation notes:
 
-- Service label is stack-scoped:
+- Service name/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.
+- macOS: implemented via **launchd LaunchAgents**
+- Linux: implemented via **systemd user services** (if available)
+- The service 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
 
@@ -181,6 +230,8 @@ On startup, `happy-stacks` loads env in this order:
 
 `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.
 
+For a full explanation of the different folders/paths (`home` vs `workspace` vs `runtime` vs stack storage) and the exact env precedence rules, see: `[docs/paths-and-env.md](docs/paths-and-env.md)`.
+
 Cloned-repo fallback (before you run `happys init`):
 
 1. `<repo>/.env` (defaults)

package/extras/swiftbar/auth-login.sh

@@ -15,17 +15,20 @@ _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}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_HOME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-PNPM_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/pnpm-term.sh"
-if [[ ! -x "$PNPM_TERM" ]]; then
-  echo "missing terminal happys wrapper: $PNPM_TERM" >&2
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-${HAPPY_STACKS_HOME_DIR:-$DEFAULT_HOME_DIR}}"
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HAPPY_LOCAL_DIR}"
+
+HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
+if [[ ! -x "$HAPPYS_TERM" ]]; then
+  echo "missing terminal happys wrapper: $HAPPYS_TERM" >&2
   exit 1
 fi
 
 if [[ "$stack" == "main" ]]; then
-  exec "$PNPM_TERM" auth login
+  exec "$HAPPYS_TERM" auth login
 fi
 
-exec "$PNPM_TERM" stack auth "$stack" login
+exec "$HAPPYS_TERM" stack auth "$stack" login

package/extras/swiftbar/git-cache-refresh.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+set -euo pipefail
+
+# Refresh SwiftBar Git/worktree cache.
+#
+# Usage:
+#   ./git-cache-refresh.sh all
+#   ./git-cache-refresh.sh main
+#   ./git-cache-refresh.sh stack <name>
+#   ./git-cache-refresh.sh component <context:main|stack> <stackName> <component>
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_HOME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-${HAPPY_STACKS_HOME_DIR:-$DEFAULT_HOME_DIR}}"
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HAPPY_LOCAL_DIR}"
+
+LIB_DIR="$HAPPY_LOCAL_DIR/extras/swiftbar/lib"
+if [[ ! -f "$LIB_DIR/utils.sh" ]]; then
+  echo "missing SwiftBar libs at: $LIB_DIR" >&2
+  exit 1
+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/git.sh"
+
+components=(happy happy-cli happy-server-light happy-server)
+
+refresh_one() {
+  local context="$1"
+  local stack="$2"
+  local component="$3"
+  local env_file="$4"
+
+  local active_dir=""
+  if [[ -n "$env_file" && -f "$env_file" ]]; then
+    active_dir="$(resolve_component_dir_from_env_file "$env_file" "$component")"
+  else
+    active_dir="$(resolve_component_dir_from_env "$component")"
+  fi
+
+  git_cache_refresh_one "$context" "$stack" "$component" "$active_dir" >/dev/null
+}
+
+refresh_stack() {
+  local stack="$1"
+  local env_file=""
+  if [[ "$stack" == "main" ]]; then
+    env_file="$(resolve_main_env_file)"
+    [[ -z "$env_file" ]] && env_file="$(resolve_stack_env_file main)"
+  else
+    env_file="$(resolve_stack_env_file "$stack")"
+  fi
+
+  for c in "${components[@]}"; do
+    refresh_one "stack" "$stack" "$c" "$env_file"
+  done
+}
+
+cmd="${1:-}"
+case "$cmd" in
+  all)
+    refresh_stack "main"
+    STACKS_DIR="$(resolve_stacks_storage_root)"
+    LEGACY_STACKS_DIR="$HOME/.happy/local/stacks"
+    if swiftbar_is_sandboxed; then
+      LEGACY_STACKS_DIR=""
+    fi
+    STACK_NAMES="$(
+      {
+        ls -1 "$STACKS_DIR" 2>/dev/null || true
+        [[ -n "$LEGACY_STACKS_DIR" ]] && ls -1 "$LEGACY_STACKS_DIR" 2>/dev/null || true
+      } | sort -u
+    )"
+    while IFS= read -r s; do
+      [[ -n "$s" ]] || continue
+      [[ "$s" == "main" ]] && continue
+      refresh_stack "$s"
+    done <<<"$STACK_NAMES"
+    git_cache_touch_last_refresh "all"
+    echo "ok: git cache refreshed (all)"
+    ;;
+  main)
+    # Main stack only (fast).
+    local_env="$(resolve_main_env_file)"
+    for c in "${components[@]}"; do
+      refresh_one "main" "main" "$c" "$local_env"
+    done
+    git_cache_touch_last_refresh "main"
+    echo "ok: git cache refreshed (main)"
+    ;;
+  stack)
+    stack="${2:-}"
+    if [[ -z "$stack" ]]; then
+      echo "usage: $0 stack <name>" >&2
+      exit 2
+    fi
+    refresh_stack "$stack"
+    git_cache_touch_last_refresh "stack:${stack}"
+    echo "ok: git cache refreshed (stack $stack)"
+    ;;
+  component)
+    context="${2:-}"
+    stack="${3:-}"
+    component="${4:-}"
+    if [[ -z "$context" || -z "$stack" || -z "$component" ]]; then
+      echo "usage: $0 component <main|stack> <stackName> <component>" >&2
+      exit 2
+    fi
+    env_file=""
+    if [[ "$stack" == "main" ]]; then
+      env_file="$(resolve_main_env_file)"
+      [[ -z "$env_file" ]] && env_file="$(resolve_stack_env_file main)"
+    else
+      env_file="$(resolve_stack_env_file "$stack")"
+    fi
+    refresh_one "$context" "$stack" "$component" "$env_file"
+    git_cache_touch_last_refresh "component:${context}:${stack}:${component}"
+    echo "ok: git cache refreshed ($context/$stack/$component)"
+    ;;
+  *)
+    echo "usage: $0 all|main|stack <name>|component <context> <stackName> <component>" >&2
+    exit 2
+    ;;
+esac
+