@happier-dev/stack 0.1.0-preview.5.1

package/docs/stacks.md

@@ -0,0 +1,330 @@
+# Stacks (multiple local Happier instances)
+
+`hstack` 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**
+- a repo checkout pin (point at a specific worktree/checkout)
+- (when using `happier-server`) isolated **infra** (Postgres/Redis/Minio) managed per-stack
+
+Stacks are configured via a plain env file stored under:
+
+```
+~/.happier/stacks/<name>/env
+```
+
+## Create a stack
+
+Non-interactive:
+
+```bash
+hstack stack new exp1 --port=3010 --server=happier-server-light
+```
+
+Auto-pick a port:
+
+```bash
+hstack 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
+hstack stack pr pr123 \
+  --repo=https://github.com/happier-dev/happier/pull/123 \
+  --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 `hstack stack auth <stack> copy-from <source>` under the hood, which also best-effort seeds DB Account rows (avoids FK errors like Prisma `P2003`).
+- `--link-auth` symlinks auth files instead of copying them (keeps credentials in sync, but reduces isolation).
+- For full-server stacks (`happier-server`), seeding may require Docker infra to be running.
+
+## Auth seeding (recommended: dev-auth)
+
+Create the `dev-auth` seed stack once, authenticate once, then reuse it when creating new stacks:
+
+```bash
+hstack auth seed
+```
+
+Interactive wizard (TTY only):
+
+```bash
+hstack stack new --interactive
+```
+
+The wizard lets you:
+
+- pick the server type (`happier-server-light` or `happier-server`)
+- pick or create a repo worktree for the Happier monorepo
+- choose which Git remote to base newly-created worktrees on (defaults to `upstream`)
+
+When creating `--server=happier-server` stacks, hstack will also reserve additional ports and persist
+the stack-scoped infra config in the stack env file (so restarts are stable):
+
+- `HAPPIER_STACK_PG_PORT`
+- `HAPPIER_STACK_REDIS_PORT`
+- `HAPPIER_STACK_MINIO_PORT`
+- `HAPPIER_STACK_MINIO_CONSOLE_PORT`
+- `DATABASE_URL`, `REDIS_URL`, `S3_*`
+
+## Run a stack
+
+Dev mode:
+
+```bash
+hstack stack dev exp1
+```
+
+Production-like mode:
+
+```bash
+hstack stack start exp1
+```
+
+Build UI for a stack (server-light serving):
+
+```bash
+hstack stack build exp1
+```
+
+Doctor:
+
+```bash
+hstack stack doctor exp1
+```
+
+## Edit a stack (interactive)
+
+To change server flavor, port, or repo worktree for an existing stack:
+
+```bash
+hstack stack edit exp1 --interactive
+```
+
+## Switch server flavor for a stack
+
+You can change `happier-server-light` vs `happier-server` for an existing stack without re-running the full edit wizard:
+
+```bash
+hstack stack srv exp1 -- status
+hstack stack srv exp1 -- use happier-server-light
+hstack stack srv exp1 -- use happier-server
+hstack stack srv exp1 -- use --interactive
+```
+
+## Switch repo worktree for a stack (`stack wt`)
+
+If you want the **exact** same UX as `hstack wt`, but scoped to a stack env file:
+
+```bash
+hstack stack wt exp1 -- status
+hstack stack wt exp1 -- use pr/my-ui-pr
+hstack stack wt exp1 -- use default
+```
+
+This updates the stack env file (`~/.happier/stacks/<name>/env`), not repo `env.local` (legacy path still supported).
+
+## Run the Happier CLI against a specific stack (`stack happier`)
+
+If you want to run a `happier` CLI command against a specific stack (instead of whatever your current shell env points at), use:
+
+```bash
+hstack stack happier exp1 -- status
+hstack stack happier exp1 -- daemon status
+```
+
+Stack shorthand also works:
+
+```bash
+hstack exp1 happier status
+```
+
+## Stack wrappers you can use
+
+These commands run with the stack env file applied:
+
+- `hstack stack dev <name>`
+- `hstack stack start <name>`
+- `hstack stack build <name>`
+- `hstack stack doctor <name>`
+- `hstack stack mobile <name>`
+- `hstack stack eas <name> [subcommand...]`
+- `hstack stack happier <name> [-- ...]`
+- `hstack stack srv <name> -- status|use ...`
+- `hstack stack wt <name> -- <wt args...>`
+- `hstack stack tailscale:status|enable|disable|url <name>`
+- `hstack stack service:* <name>`
+
+Global/non-stack commands:
+
+- `hstack setup` (recommended; installs shims/runtime and bootstraps the monorepo)
+- (advanced) `hstack init` (plumbing: shims/runtime/pointer env)
+- (advanced) `hstack bootstrap` (clone/install monorepo + deps)
+
+## Services (autostart)
+
+Each stack can have its own autostart service (so multiple stacks can start at login).
+
+```bash
+hstack stack service exp1 install
+hstack stack service exp1 status
+hstack stack service exp1 restart
+hstack stack service exp1 logs
+```
+
+Implementation notes:
+
+- Service name/label is stack-scoped:
+  - `main` → `com.happier.stack`
+  - `exp1` → `com.happier.stack.exp1`
+- macOS: implemented via **launchd LaunchAgents**
+- Linux: implemented via **systemd user services** (if available)
+- The service persists `HAPPIER_STACK_ENV_FILE`, so you can edit the stack env file without reinstalling.
+
+## Repo/worktree selection per stack
+
+When creating a stack you can point the stack at a repo worktree:
+
+```bash
+  hstack stack new exp3 \\
+  --repo=local/my-feature \\
+  --server=happier-server
+```
+
+Worktree specs are interpreted relative to the workspace:
+
+```
+main                -> <workspace>/main
+dev                 -> <workspace>/dev
+pr/<...>            -> <workspace>/pr/<...>
+local/<...>         -> <workspace>/local/<owner>/<...>
+tmp/<...>           -> <workspace>/tmp/<owner>/<...>
+```
+
+So `--repo=pr/foo` maps to:
+
+```
+<workspace>/pr/foo
+```
+
+You can also pass an absolute path.
+
+## Stack env + repo env precedence
+
+On startup, `hstack` loads env in this order:
+
+1. `~/.happier-stack/.env` (defaults)
+2. `~/.happier-stack/env.local` (optional global overrides; prefer stack env for persistent config)
+3. `HAPPIER_STACK_ENV_FILE` (stack env; highest precedence)
+
+`hstack stack ...` sets `HAPPIER_STACK_ENV_FILE=~/.happier/stacks/<name>/env` and clears any already-exported `HAPPIER_STACK_*` 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 `hstack init`):
+
+1. `<repo>/.env` (defaults)
+2. `<repo>/env.local` (optional overrides)
+3. `HAPPIER_STACK_ENV_FILE` (stack env)
+
+## Manage per-stack environment variables (including API keys)
+
+To add/update environment variables in a stack env file from the CLI:
+
+```bash
+hstack stack env <stack> set KEY=VALUE [KEY2=VALUE2...]
+```
+
+To remove keys:
+
+```bash
+hstack stack env <stack> unset KEY [KEY2...]
+```
+
+To inspect:
+
+```bash
+hstack stack env <stack> get KEY
+hstack stack env <stack> list
+hstack stack env <stack> path
+```
+
+Notes:
+
+- This is the recommended place for **provider API keys** the daemon needs (example: `OPENAI_API_KEY`).
+- Changes apply on the **next start** of the stack/daemon. Restart to pick them up:
+  - `main`: `hstack start --restart`
+  - named stack: `hstack stack start <stack> -- --restart` (or `hstack stack dev <stack> -- --restart`)
+
+Self-host shortcut (defaults to `main` when not running under a stack wrapper):
+
+```bash
+hstack env set OPENAI_API_KEY=sk-...
+```
+
+## 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:
+
+- `~/.happier/stacks/<stack>/cli/access.key`
+
+To check / authenticate a stack, run:
+
+```bash
+hstack stack auth <stack> status
+hstack stack auth <stack> login
+```
+
+Notes:
+- You can run **multiple daemons for the same stack** on **different accounts** using `--identity=<name>`.
+  - `default` (no flag): `~/.happier/stacks/<stack>/cli/...`
+  - `--identity=account-b`: `~/.happier/stacks/<stack>/cli-identities/account-b/...`
+- To authenticate an identity without auto-opening a browser, use `--no-open` (it prints the URL so you can open it
+  in the browser profile/incognito window you want):
+
+```bash
+hstack stack auth <stack> login --identity=account-a --no-open
+hstack stack auth <stack> login --identity=account-b --no-open
+```
+
+- To start/stop an identity’s daemon explicitly:
+
+```bash
+hstack stack daemon <stack> start --identity=account-a
+hstack stack daemon <stack> stop  --identity=account-a
+```
+
+- For the **main** stack, use `<stack>=main` and the default `<port>=3005` (unless you changed it).
+- If you use Tailscale Serve, `HAPPIER_WEBAPP_URL` should be your HTTPS URL (what you get from `hstack tailscale url`).
+- Logs live under:
+  - default identity: `~/.happier/stacks/<stack>/cli/logs/`
+  - named identities: `~/.happier/stacks/<stack>/cli-identities/<identity>/logs/`
+
+## JSON mode
+
+For programmatic usage:
+
+```bash
+hstack stack list --json
+hstack stack new exp3 --json
+hstack stack edit exp3 --interactive --json
+```

package/docs/tauri.md

@@ -0,0 +1,60 @@
+# 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” Happier 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, `hstack` 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:<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
+hstack build --tauri
+```
+
+Or during bootstrap:
+
+```bash
+hstack bootstrap --tauri
+```
+
+## Run it
+
+1) Start the local server (or install the service):
+
+```bash
+hstack start
+```
+
+2) Launch the built app bundle (location is under `~/.happier/stacks/main/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 `hstack 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)
+
+- `HAPPIER_STACK_TAURI_IDENTIFIER` (default `com.happier.stack`)
+- `HAPPIER_STACK_TAURI_PRODUCT_NAME` (default `Happier`)
+- `HAPPIER_STACK_TAURI_DEBUG=0` (build release-like without devtools)
+- `HAPPIER_STACK_TAURI_SERVER_URL` (force the embedded API URL)
+- `HAPPIER_STACK_TAURI_PREFER_TAILSCALE=0` (disable Tailscale detection; always embed `127.0.0.1`)

package/docs/worktrees-and-forks.md

@@ -0,0 +1,133 @@
+# Worktrees + forks (hstack)
+
+This repo is designed to run the **Happier** stack locally, while still making it easy to:
+
+- keep using **your fork** day-to-day
+- create **clean upstream PR branches** quickly (without carrying fork-only patches)
+
+hstack is **monorepo-only**: UI/CLI/server all live in the same Happier git repo.
+
+---
+
+## Key idea
+
+- Keep a stable checkout at `<workspace>/main`
+- Put all development work in `<workspace>/dev` or repo worktrees under `<workspace>/{pr,local,tmp}/...`
+- Point stacks at a repo checkout via **`HAPPIER_STACK_REPO_DIR`** (managed by `hstack wt use ...` / `hstack stack wt ...`)
+
+---
+
+## Layout
+
+Default paths (see `hstack where` for your actual values):
+
+- Stable checkout: `<workspace>/main`
+- Dev checkout: `<workspace>/dev` (created by `hstack setup --profile=dev`)
+- Worktrees:
+  - PRs: `<workspace>/pr/...`
+  - locals: `<workspace>/local/<owner>/...`
+  - tmp: `<workspace>/tmp/<owner>/...`
+
+Examples:
+
+- `<workspace>/pr/123-fix-thing`
+- `<workspace>/local/<owner>/my-feature`
+- `<workspace>/tmp/<owner>/scratch`
+
+Inside the monorepo, services live under:
+
+- `apps/ui` (UI)
+- `apps/cli` (CLI + daemon)
+- `apps/server` (server; light/full flavors)
+
+---
+
+## Branch naming convention
+
+Branches created/managed by `hstack` worktree tooling are typically named:
+
+```
+<owner>/<slug>
+```
+
+PR worktrees use `pr/...` branch names.
+
+---
+
+## Choosing which checkout hstack runs
+
+hstack selects the active repo checkout using:
+
+- `HAPPIER_STACK_REPO_DIR` (absolute path to the monorepo root)
+
+Recommended ways to set it:
+
+```bash
+# Switch the active checkout for the current (non-stack) commands
+hstack wt use pr/123-fix-thing
+
+# Switch the active checkout for a specific stack
+hstack stack wt pr123 -- use pr/123-fix-thing
+```
+
+If you want a one-shot override without changing the stack env file:
+
+```bash
+hstack stack typecheck pr123 --repo=pr/123-fix-thing
+hstack stack build pr123 --repo=/absolute/path/to/checkout
+```
+
+---
+
+## Creating worktrees
+
+Create a new local worktree (recommended for day-to-day feature work):
+
+```bash
+hstack wt new my-feature --use
+hstack wt push active --remote=origin
+```
+
+Use `--category=tmp` for truly throwaway worktrees.
+
+---
+
+## Testing a GitHub PR locally (`wt pr`)
+
+Create a worktree at the PR head ref:
+
+```bash
+hstack wt pr https://github.com/happier-dev/happier/pull/123 --use
+
+# or just the PR number (remote defaults to upstream)
+hstack wt pr 123 --use
+```
+
+Update when the PR changes:
+
+```bash
+hstack wt pr 123 --update --stash
+```
+
+Notes:
+
+- `--update` fails closed if the PR was force-pushed and the update is not a fast-forward; re-run with `--force`.
+- `--slug=<name>` creates a nicer local branch name (example: `pr/123-fix-thing`).
+
+---
+
+## Switching server flavor (light vs full)
+
+Choose which backend flavor a stack runs with:
+
+```bash
+hstack srv status
+hstack srv use happier-server-light
+hstack srv use happier-server
+hstack srv use --interactive
+```
+
+Notes:
+
+- This selects a runtime flavor (light/full). It does **not** select a different git repo.
+- Both flavors come from the same monorepo server code (`apps/server`).

package/extras/swiftbar/auth-login.sh

@@ -0,0 +1,29 @@
+#!/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>
+#
+# Behavior:
+# - Delegate to `hstack auth login` / `hstack 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)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+hstack_TERM="$SCRIPT_DIR/hstack-term.sh"
+if [[ ! -x "$hstack_TERM" ]]; then
+  echo "missing hstack terminal wrapper: $hstack_TERM" >&2
+  exit 1
+fi
+
+if [[ "$stack" == "main" ]]; then
+  exec "$hstack_TERM" auth login
+fi
+
+exec "$hstack_TERM" stack auth "$stack" login

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

@@ -0,0 +1,122 @@
+#!/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_ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+hstack_ROOT_DIR="${HAPPIER_STACK_CLI_ROOT_DIR:-$DEFAULT_ROOT_DIR}"
+LIB_DIR="$hstack_ROOT_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"
+hstack_ROOT_DIR="$(resolve_hstack_root_dir)"
+LIB_DIR="$hstack_ROOT_DIR/extras/swiftbar/lib"
+# shellcheck source=/dev/null
+source "$LIB_DIR/git.sh"
+
+components=(happier-ui happier-cli happier-server-light happier-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)"
+    STACK_NAMES="$(
+      {
+        ls -1 "$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