happy-stacks 0.0.0 → 0.1.2

package/README.md

@@ -1,5 +1,7 @@
 # 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
@@ -54,6 +56,17 @@ node ./bin/happys.mjs 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
 
@@ -143,9 +156,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
@@ -201,7 +215,8 @@ Details: `[docs/worktrees-and-forks.md](docs/worktrees-and-forks.md)`.
 ### 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:
 
@@ -310,5 +325,8 @@ 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.
 
-For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.
+For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.

package/bin/happys.mjs

@@ -13,12 +13,82 @@ function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-function resolveHomeDir() {
-  const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
-  if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+function expandHome(p) {
+  return String(p ?? '').replace(/^~(?=\/)/, homedir());
+}
+
+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 join(homedir(), '.happy-stacks');
+  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 = join(homedir(), '.happy-stacks', '.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 ?? 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 = join(homedir(), '.happy-stacks', '.env');
+  const v = dotenvGetQuick(canonicalEnv, 'HAPPY_STACKS_HOME_DIR') || dotenvGetQuick(canonicalEnv, 'HAPPY_LOCAL_HOME_DIR') || '';
+  return v ? expandHome(v) : join(homedir(), '.happy-stacks');
 }
 
 function maybeAutoUpdateNotice(cliRootDir, cmd) {
@@ -123,6 +193,7 @@ function runNodeScript(cliRootDir, scriptRelPath, args) {
 
 function main() {
   const cliRootDir = getCliRootDir();
+  maybeReexecToCliRoot(cliRootDir);
   const argv = process.argv.slice(2);
 
   const cmd = argv.find((a) => !a.startsWith('--')) ?? 'help';

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:
 
@@ -52,6 +53,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 +138,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 +151,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
 

package/extras/swiftbar/auth-login.sh

@@ -18,14 +18,14 @@ _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
+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/happy-stacks.5s.sh

@@ -17,7 +17,44 @@
 # Configuration
 # ============================================================================
 
-HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
+# SwiftBar runs with a minimal environment, so users often won't have
+# HAPPY_STACKS_HOME_DIR / HAPPY_STACKS_WORKSPACE_DIR exported.
+# Treat ~/.happy-stacks/.env as the canonical pointer file (written by `happys init`).
+CANONICAL_ENV_FILE="$HOME/.happy-stacks/.env"
+
+_dotenv_get_quick() {
+  # Usage: _dotenv_get_quick /path/to/env KEY
+  local file="$1"
+  local key="$2"
+  [[ -n "$file" && -n "$key" && -f "$file" ]] || return 0
+  local line
+  line="$(grep -E "^${key}=" "$file" 2>/dev/null | head -n 1 || true)"
+  [[ -n "$line" ]] || return 0
+  local v="${line#*=}"
+  v="${v%$'\r'}"
+  # Strip simple surrounding quotes.
+  if [[ "$v" == \"*\" && "$v" == *\" ]]; then v="${v#\"}"; v="${v%\"}"; fi
+  if [[ "$v" == \'*\' && "$v" == *\' ]]; then v="${v#\'}"; v="${v%\'}"; fi
+  echo "$v"
+}
+
+_expand_home_quick() {
+  local p="$1"
+  if [[ "$p" == "~/"* ]]; then
+    echo "$HOME/${p#~/}"
+  else
+    echo "$p"
+  fi
+}
+
+_home_from_canonical=""
+if [[ -f "$CANONICAL_ENV_FILE" ]]; then
+  _home_from_canonical="$(_dotenv_get_quick "$CANONICAL_ENV_FILE" "HAPPY_STACKS_HOME_DIR")"
+  [[ -z "$_home_from_canonical" ]] && _home_from_canonical="$(_dotenv_get_quick "$CANONICAL_ENV_FILE" "HAPPY_LOCAL_HOME_DIR")"
+fi
+_home_from_canonical="$(_expand_home_quick "${_home_from_canonical:-}")"
+
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-${_home_from_canonical:-$HOME/.happy-stacks}}"
 HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-$HAPPY_STACKS_HOME_DIR}"
 HAPPY_LOCAL_PORT="${HAPPY_LOCAL_PORT:-3005}"
 
@@ -26,17 +63,6 @@ if [[ -n "${HAPPY_STACKS_WT_TERMINAL:-}" && -z "${HAPPY_LOCAL_WT_TERMINAL:-}" ]]
 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"
@@ -82,7 +108,15 @@ 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")"
+if [[ -z "$MAIN_ENV_FILE" ]]; then
+  MAIN_ENV_FILE="$(resolve_stack_env_file main)"
+fi
+HAPPY_HOME_DIR="$(resolve_stack_base_dir main "$MAIN_ENV_FILE")"
+CLI_HOME_DIR="$(resolve_stack_cli_home_dir main "$MAIN_ENV_FILE")"
+LOGS_DIR="$HAPPY_HOME_DIR/logs"
+MAIN_LABEL="$(resolve_stack_label main)"
+
+MAIN_COLLECT="$(collect_stack_status "$MAIN_PORT" "$CLI_HOME_DIR" "$MAIN_LABEL" "$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
@@ -112,10 +146,10 @@ echo "---"
 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_stack_info "" "main" "$MAIN_PORT" "$MAIN_SERVER_COMPONENT" "$HAPPY_HOME_DIR" "$CLI_HOME_DIR" "$MAIN_LABEL" "$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" "$MAIN_LABEL"
 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_autostart "" "main" "$MAIN_LABEL" "$MAIN_LAUNCHAGENT_STATUS" "$MAIN_AUTOSTART_PID" "$MAIN_AUTOSTART_METRICS" "$LOGS_DIR"
 render_component_tailscale "" "main" "$TAILSCALE_URL"
 
 echo "---"
@@ -123,33 +157,39 @@ 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"
+  HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
+  echo "New stack (interactive) | bash=$HAPPYS_TERM param1=stack param2=new param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "List stacks | bash=$HAPPYS_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)"
+STACKS_DIR="$(resolve_stacks_storage_root)"
+LEGACY_STACKS_DIR="$HOME/.happy/local/stacks"
+if [[ -d "$STACKS_DIR" ]] || [[ -d "$LEGACY_STACKS_DIR" ]]; then
+  STACK_NAMES="$(
+    {
+      ls -1 "$STACKS_DIR" 2>/dev/null || true
+      ls -1 "$LEGACY_STACKS_DIR" 2>/dev/null || true
+    } | sort -u
+  )"
   if [[ -z "$STACK_NAMES" ]]; then
     echo "No stacks found | color=$GRAY"
   fi
   for s in $STACK_NAMES; do
-    env_file="$STACKS_DIR/$s/env"
+    env_file="$(resolve_stack_env_file "$s")"
     [[ -f "$env_file" ]] || continue
 
-    port="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_PORT")"
+    port="$(dotenv_get "$env_file" "HAPPY_STACKS_SERVER_PORT")"
+    [[ -z "$port" ]] && port="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_PORT")"
     [[ -n "$port" ]] || continue
 
-    server_component="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_COMPONENT")"
+    server_component="$(dotenv_get "$env_file" "HAPPY_STACKS_SERVER_COMPONENT")"
+    [[ -z "$server_component" ]] && 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"
+    base_dir="$(resolve_stack_base_dir "$s" "$env_file")"
+    cli_home_dir="$(resolve_stack_cli_home_dir "$s" "$env_file")"
+    label="$(resolve_stack_label "$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"
@@ -169,22 +209,22 @@ if [[ -d "$STACKS_DIR" ]]; then
     render_components_menu "--" "stack" "$s" "$env_file"
   done
 else
-  echo "No stacks dir found at ~/.happy/stacks | color=$GRAY"
+  echo "No stacks dir found at: $(shorten_path "$STACKS_DIR" 52) | color=$GRAY"
 fi
 
 echo "---"
-render_components_menu "" "main" "main" ""
+render_components_menu "" "main" "main" "$MAIN_ENV_FILE"
 
 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"
+  HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
+  echo "--Use (interactive) | bash=$HAPPYS_TERM param1=wt param2=use param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--New (interactive) | bash=$HAPPYS_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 (dry-run) | bash=$HAPPYS_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
 
@@ -193,10 +233,10 @@ 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"
+  HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
+  echo "--Bootstrap (clone/install) | bash=$HAPPYS_TERM param1=bootstrap dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--CLI link (install happy wrapper) | bash=$HAPPYS_TERM param1=cli:link dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  echo "--Mobile dev helper | bash=$HAPPYS_TERM param1=mobile dir=$HAPPY_LOCAL_DIR terminal=false"
 fi
 
 echo "---"
@@ -215,4 +255,6 @@ echo "--1h | bash=$SET_INTERVAL param1=1h dir=$HAPPY_LOCAL_DIR terminal=false re
 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
+echo "--1d | bash=$SET_INTERVAL param1=1d dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+
+exit 0

package/extras/swiftbar/happys-term.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+set -euo pipefail
+
+# Open preferred terminal and run a happys command.
+#
+# Preference order follows wt shell semantics:
+# - HAPPY_LOCAL_WT_TERMINAL=ghostty|iterm|terminal|current
+#   (also accepts "auto" which tries ghostty->iterm->terminal->current)
+#
+# Notes:
+# - iTerm / Terminal: we run the command automatically via AppleScript.
+# - Ghostty: best-effort; if we can't run the command, we open Ghostty in the dir and copy the command to clipboard.
+
+CANONICAL_ENV_FILE="$HOME/.happy-stacks/.env"
+
+dotenv_get_quick() {
+  local file="$1"
+  local key="$2"
+  [[ -n "$file" && -n "$key" && -f "$file" ]] || return 0
+  local line
+  line="$(grep -E "^${key}=" "$file" 2>/dev/null | head -n 1 || true)"
+  [[ -n "$line" ]] || return 0
+  local v="${line#*=}"
+  v="${v%$'\r'}"
+  if [[ "$v" == \"*\" && "$v" == *\" ]]; then v="${v#\"}"; v="${v%\"}"; fi
+  if [[ "$v" == \'*\' && "$v" == *\' ]]; then v="${v#\'}"; v="${v%\'}"; fi
+  echo "$v"
+}
+
+expand_home_quick() {
+  local p="$1"
+  if [[ "$p" == "~/"* ]]; then
+    echo "$HOME/${p#~/}"
+  else
+    echo "$p"
+  fi
+}
+
+home_from_canonical=""
+ws_from_canonical=""
+if [[ -f "$CANONICAL_ENV_FILE" ]]; then
+  home_from_canonical="$(dotenv_get_quick "$CANONICAL_ENV_FILE" "HAPPY_STACKS_HOME_DIR")"
+  [[ -z "$home_from_canonical" ]] && home_from_canonical="$(dotenv_get_quick "$CANONICAL_ENV_FILE" "HAPPY_LOCAL_HOME_DIR")"
+  ws_from_canonical="$(dotenv_get_quick "$CANONICAL_ENV_FILE" "HAPPY_STACKS_WORKSPACE_DIR")"
+  [[ -z "$ws_from_canonical" ]] && ws_from_canonical="$(dotenv_get_quick "$CANONICAL_ENV_FILE" "HAPPY_LOCAL_WORKSPACE_DIR")"
+fi
+home_from_canonical="$(expand_home_quick "${home_from_canonical:-}")"
+ws_from_canonical="$(expand_home_quick "${ws_from_canonical:-}")"
+
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-${home_from_canonical:-$HOME/.happy-stacks}}"
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-$HAPPY_STACKS_HOME_DIR}"
+
+WORKDIR="${HAPPY_STACKS_WORKSPACE_DIR:-${ws_from_canonical:-$HAPPY_STACKS_HOME_DIR/workspace}}"
+if [[ ! -d "$WORKDIR" ]]; then
+  WORKDIR="$HOME"
+fi
+
+HAPPYS_SH="$HAPPY_LOCAL_DIR/extras/swiftbar/happys.sh"
+if [[ ! -x "$HAPPYS_SH" ]]; then
+  echo "missing happys wrapper: $HAPPYS_SH" >&2
+  exit 1
+fi
+
+pref_raw="$(echo "${HAPPY_STACKS_WT_TERMINAL:-${HAPPY_LOCAL_WT_TERMINAL:-auto}}" | tr '[:upper:]' '[:lower:]')"
+pref="$pref_raw"
+if [[ "$pref" == "" ]]; then pref="auto"; fi
+
+cmd=( "$HAPPYS_SH" "$@" )
+
+escape_for_osascript_string() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  echo "$s"
+}
+
+shell_cmd() {
+  local joined=""
+  local q
+  joined="cd \"${WORKDIR//\"/\\\"}\"; "
+  for q in "${cmd[@]}"; do
+    local escaped
+    escaped="$(printf "%s" "$q" | sed "s/'/'\\\\''/g")"
+    joined+="'${escaped}' "
+  done
+  joined+="; echo; echo \"[happy-stacks] done\"; exec /bin/zsh -i"
+  echo "$joined"
+}
+
+run_iterm() {
+  if ! command -v osascript >/dev/null 2>&1; then
+    return 1
+  fi
+  local s
+  s="$(shell_cmd)"
+  s="$(escape_for_osascript_string "$s")"
+  osascript \
+    -e 'tell application "iTerm" to activate' \
+    -e 'tell application "iTerm" to create window with default profile' \
+    -e "tell application \"iTerm\" to tell current session of current window to write text \"${s}\"" >/dev/null
+}
+
+run_terminal_app() {
+  if ! command -v osascript >/dev/null 2>&1; then
+    return 1
+  fi
+  local s
+  s="$(shell_cmd)"
+  s="$(escape_for_osascript_string "$s")"
+  osascript \
+    -e 'tell application "Terminal" to activate' \
+    -e "tell application \"Terminal\" to do script \"${s}\"" >/dev/null
+}
+
+run_ghostty() {
+  if ! command -v ghostty >/dev/null 2>&1; then
+    return 1
+  fi
+
+  local s
+  s="$(shell_cmd)"
+  if ghostty --working-directory "$WORKDIR" -e /bin/zsh -lc "$s" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  echo -n "$s" | pbcopy 2>/dev/null || true
+  ghostty --working-directory "$WORKDIR" >/dev/null 2>&1 || true
+  return 0
+}
+
+try_one() {
+  local t="$1"
+  case "$t" in
+    ghostty) run_ghostty ;;
+    iterm) run_iterm ;;
+    terminal) run_terminal_app ;;
+    current) ( cd "$WORKDIR"; exec "${cmd[@]}" ) ;;
+    *) return 1 ;;
+  esac
+}
+
+if [[ "$pref" == "auto" ]]; then
+  for t in ghostty iterm terminal current; do
+    if try_one "$t"; then
+      exit 0
+    fi
+  done
+  exit 1
+fi
+
+try_one "$pref"