happy-stacks 0.0.0

package/README.md

@@ -0,0 +1,314 @@
+# 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
+cloned under your configured workspace (default: `~/.happy-stacks/workspace/components/*`).
+
+## What is Happy?
+
+Happy is an UI/CLI stack (server + web UI + CLI + daemon) who let you monitor and interact with Claude Code, Codex and Gemini sessions from your mobile, a web UI and/or a desktop app.
+
+## What is Happy Stacks?
+
+happy-stacks is a “launcher + workflow toolkit” to:
+
+- run Happy fully on your own machine (no hosted dependency)
+- safely access it remotely (HTTPS secure context) via Tailscale
+- manage **worktrees** for clean upstream PRs while keeping a patched fork
+- run **multiple isolated stacks** (ports + dirs + component overrides)
+- optionally manage autostart (macOS LaunchAgent) and a SwiftBar menu bar control panel
+
+## Quickstart
+
+### Step 1: Install / bootstrap
+
+Recommended:
+
+```bash
+npx happy-stacks init
+export PATH="$HOME/.happy-stacks/bin:$PATH"
+```
+
+Alternative (global install):
+
+```bash
+npm install -g happy-stacks
+happys init
+export PATH="$HOME/.happy-stacks/bin:$PATH"
+```
+
+(`init` will run `bootstrap` automatically. Use `--no-bootstrap` if you only want to write config and shims.)
+
+Developer mode (clone this repo):
+
+```bash
+git clone https://github.com/leeroybrun/happy-stacks.git
+cd happy-stacks
+
+node ./bin/happys.mjs bootstrap --interactive
+# legacy:
+# pnpm bootstrap -- --interactive
+```
+
+Notes:
+
+- In a cloned repo, `pnpm <script>` still works, but `happys <command>` is now the recommended UX (same underlying scripts).
+
+### Step 2: Run the main stack
+
+Starts the local server, CLI daemon, and serves the pre-built UI.
+
+```bash
+happys start
+```
+
+### Step 2b (first run only): authenticate the daemon
+
+On a **fresh machine** (or any new stack), the daemon needs to authenticate once before it can register a “machine”.
+
+```bash
+happys auth login
+```
+
+#### Troubleshooting: “no machine” on first run (daemon auth)
+
+If `.../new` shows “no machine” check whether this is **auth** vs a **daemon/runtime** issue:
+
+```bash
+happys auth status
+```
+
+If it says **auth is required**, run:
+
+```bash
+happys auth login
+```
+
+If auth is OK but the daemon isn’t running, run:
+
+```bash
+happys doctor
+```
+
+### Step 3: Enable Tailscale Serve (recommended for remote devices)
+
+```bash
+happys tailscale enable
+happys tailscale url
+```
+
+### Step 4: Mobile access
+
+Make sure Tailscale is [installed and running]
+([https://tailscale.com/kb/1347/installation](https://tailscale.com/kb/1347/installation)) on your 
+phone, then either:
+
+- Open the URL from `happys tailscale url` on your phone and “Add to Home Screen”, or
+- [Download the Happy mobile app]
+([https://happy.engineering/](https://happy.engineering/)) and [configure it to use 
+your local server](docs/remote-access.md).
+
+Details (secure context, phone instructions, automation knobs): `[docs/remote-access.md](docs/remote-access.md)`.
+
+## Why this exists
+
+- **Automated setup**: `happys init` + `happys start` gets the whole stack up and running.
+- **No hosted dependency**: run the full stack on your own computer.
+- **Lower latency**: localhost/LAN is typically much faster than remote hosted servers.
+- **Custom forks**: easily use forks of the Happy UI + CLI (e.g. `leeroybrun/*`) while still contributing upstream to `slopus/*`.
+- **Worktrees**: clean upstream PR branches without mixing fork-only patches.
+- **Stacks**: run multiple isolated instances in parallel (ports + dirs + component overrides).
+- **Remote access**: `happys tailscale ...` helps you get an HTTPS URL for mobile/remote devices.
+
+## How Happy Stacks wires “local” URLs
+
+There are two “URLs” to understand:
+
+- **Internal URL**: used by local processes on this machine (server/daemon/CLI)
+  - typically `http://127.0.0.1:<port>`
+- **Public URL**: used by other devices (phone/laptop) and embedded links/QR codes
+  - recommended: `https://<machine>.<tailnet>.ts.net` via Tailscale Serve
+
+Diagram:
+
+```text
+             other device (phone/laptop)
+                   |
+                   |  HTTPS (secure context)
+                   v
+        https://<machine>.<tailnet>.ts.net
+                   |
+                   | (tailscale serve)
+                   v
+           local machine (this repo)
+     +--------------------------------+
+     | happy-server(-light)           |
+     |  - listens on :PORT            |
+     |  - serves UI (server-light)    |
+     +--------------------------------+
+                   ^
+                   | internal loopback
+                   |
+            http://127.0.0.1:<port>
+               (daemon / CLI)
+```
+
+More details + automation: `[docs/remote-access.md](docs/remote-access.md)`.
+
+## How it’s organized
+
+- **Scripts**: `scripts/*.mjs` (bootstrap/dev/start/build/stacks/worktrees/service/tailscale/mobile)
+- **Components**: `components/*` (each is its own Git repo)
+- **Worktrees**: `components/.worktrees/<component>/<owner>/<branch...>`
+
+Components:
+
+- `happy` (UI)
+- `happy-cli` (CLI + daemon)
+- `happy-server-light` (light server, can serve built UI)
+- `happy-server` (full server)
+
+## Quickstarts (feature-focused)
+
+### Remote access (Tailscale Serve)
+
+```bash
+happys tailscale enable
+happys tailscale url
+```
+
+Details: `[docs/remote-access.md](docs/remote-access.md)`.
+
+### Worktrees + forks (clean upstream PRs)
+
+Create a clean upstream PR worktree:
+
+```bash
+happys wt new happy pr/my-feature --from=upstream --use
+happys wt push happy active --remote=upstream
+```
+
+Test an upstream PR locally:
+
+```bash
+happys wt pr happy https://github.com/slopus/happy/pull/123 --use
+happys wt pr happy 123 --update --stash
+```
+
+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.
+
+Switch globally:
+
+```bash
+happys srv status
+happys srv use --interactive
+```
+
+Switch per-stack:
+
+```bash
+happys stack srv exp1 -- use --interactive
+```
+
+Details: `[docs/server-flavors.md](docs/server-flavors.md)`.
+
+### Stacks (multiple isolated instances)
+
+```bash
+happys stack new exp1 --interactive
+happys stack dev exp1
+```
+
+Point a stack at a PR worktree:
+
+```bash
+happys wt pr happy 123 --use
+happys stack wt exp1 -- use happy slopus/pr/123-fix-thing
+happys stack dev exp1
+```
+
+Details: `[docs/stacks.md](docs/stacks.md)`.
+
+### Menu bar (SwiftBar)
+
+```bash
+happys menubar install
+happys menubar open
+```
+
+Details: `[docs/menubar.md](docs/menubar.md)`.
+
+### Mobile iOS dev (optional)
+
+```bash
+happys mobile --help
+happys mobile --json
+```
+
+Details: `[docs/mobile-ios.md](docs/mobile-ios.md)`.
+
+### Tauri desktop app (optional)
+
+```bash
+happys build --tauri
+```
+
+Details: `[docs/tauri.md](docs/tauri.md)`.
+
+## Commands (high-signal)
+
+- **Setup**:
+  - `happys init`
+  - `happys bootstrap --interactive` (wizard)
+  - `happys bootstrap --forks|--upstream`
+  - `happys bootstrap --server=happy-server|happy-server-light|both`
+- **Run**:
+  - `happys start` (production-like; serves built UI via server-light)
+  - `happys dev` (dev; Expo web dev server for UI)
+- **Server flavor**:
+  - `happys srv status`
+  - `happys srv use --interactive`
+- **Worktrees**:
+  - `happys wt use --interactive`
+  - `happys wt pr <component> <pr-url|number> --use [--update] [--stash] [--force]`
+  - `happys wt sync-all`
+  - `happys wt update-all --dry-run` / `happys wt update-all --stash`
+- **Stacks**:
+  - `happys stack new --interactive`
+  - `happys stack dev <name>` / `happys stack start <name>`
+  - `happys stack edit <name> --interactive`
+  - `happys stack wt <name> -- use --interactive`
+  - `happys stack migrate`
+- **Menu bar (SwiftBar)**:
+  - `happys menubar install`
+
+## Docs (deep dives)
+
+- **Remote access (Tailscale + phone)**: `[docs/remote-access.md](docs/remote-access.md)`
+- **Server flavors (server-light vs server)**: `[docs/server-flavors.md](docs/server-flavors.md)`
+- **Worktrees + forks workflow**: `[docs/worktrees-and-forks.md](docs/worktrees-and-forks.md)`
+- **Stacks (multiple instances)**: `[docs/stacks.md](docs/stacks.md)`
+- **Menu bar (SwiftBar)**: `[docs/menubar.md](docs/menubar.md)`
+- **Mobile iOS dev**: `[docs/mobile-ios.md](docs/mobile-ios.md)`
+- **Tauri desktop app**: `[docs/tauri.md](docs/tauri.md)`
+
+## Configuration
+
+Where config lives by default:
+
+- `~/.happy-stacks/.env`: stable “pointer” file (home/workspace/runtime)
+- `~/.happy-stacks/env.local`: optional global overrides
+- `~/.happy/stacks/main/env`: main stack config (port, server flavor, component overrides)
+
+Notes:
+
+- Canonical env prefix is `HAPPY_STACKS_*` (legacy `HAPPY_LOCAL_*` still works).
+- Canonical stack storage is `~/.happy/stacks` (legacy `~/.happy/local` is still supported).
+
+For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.

package/bin/happys.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { commandHelpArgs, renderHappysRootHelp, resolveHappysCommand } from '../scripts/utils/cli_registry.mjs';
+
+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());
+  }
+  return join(homedir(), '.happy-stacks');
+}
+
+function maybeAutoUpdateNotice(cliRootDir, cmd) {
+  // Non-blocking, cached update checks:
+  // - never run network calls in-process
+  // - optionally print a notice (TTY only) if cache says an update is available
+  // - periodically kick off a background check that refreshes the cache
+  const enabled = (process.env.HAPPY_STACKS_UPDATE_CHECK ?? '1') !== '0';
+  if (!enabled) return;
+  // Never do background checks for non-interactive invocations (CI, LaunchAgents, scripts).
+  if (!process.stdout.isTTY) return;
+  if (process.env.HAPPY_STACKS_UPDATE_CHECK_SPAWNED === '1') return;
+  if (cmd === 'self' || cmd === 'help' || cmd === '--help' || cmd === '-h') return;
+
+  const homeDir = resolveHomeDir();
+  const cacheDir = join(homeDir, 'cache');
+  const cachePath = join(cacheDir, 'update.json');
+
+  const intervalMsRaw = (process.env.HAPPY_STACKS_UPDATE_CHECK_INTERVAL_MS ?? '').trim();
+  const intervalMs = intervalMsRaw ? Number(intervalMsRaw) : 24 * 60 * 60 * 1000;
+  const notifyIntervalMsRaw = (process.env.HAPPY_STACKS_UPDATE_NOTIFY_INTERVAL_MS ?? '').trim();
+  const notifyIntervalMs = notifyIntervalMsRaw ? Number(notifyIntervalMsRaw) : 24 * 60 * 60 * 1000;
+
+  let cached = null;
+  try {
+    if (existsSync(cachePath)) {
+      cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
+    }
+  } catch {
+    cached = null;
+  }
+
+  const now = Date.now();
+  const checkedAt = typeof cached?.checkedAt === 'number' ? cached.checkedAt : 0;
+  const shouldCheck = !checkedAt || (Number.isFinite(intervalMs) && now - checkedAt > intervalMs);
+
+  const updateAvailable = Boolean(cached?.updateAvailable);
+  const latest = typeof cached?.latest === 'string' ? cached.latest : '';
+  const current = typeof cached?.current === 'string' ? cached.current : '';
+  const notifiedAt = typeof cached?.notifiedAt === 'number' ? cached.notifiedAt : 0;
+  const shouldNotify =
+    Boolean(updateAvailable && latest) &&
+    Boolean(process.stdout.isTTY) &&
+    (!notifiedAt || (Number.isFinite(notifyIntervalMs) && now - notifiedAt > notifyIntervalMs));
+
+  if (shouldNotify) {
+    const from = current ? current : 'current';
+    // Keep it short; no network calls here.
+    console.error(`[happys] update available: ${from} -> ${latest} (run: happys self update)`);
+    try {
+      mkdirSync(cacheDir, { recursive: true });
+      writeFileSync(
+        cachePath,
+        JSON.stringify(
+          {
+            ...(cached ?? {}),
+            notifiedAt: now,
+          },
+          null,
+          2
+        ) + '\n',
+        'utf-8'
+      );
+    } catch {
+      // ignore
+    }
+  }
+
+  if (!shouldCheck) return;
+
+  // Kick off a background refresh (best-effort, no logs).
+  try {
+    const child = spawn(process.execPath, [join(cliRootDir, 'scripts', 'self.mjs'), 'check', '--quiet'], {
+      stdio: 'ignore',
+      cwd: cliRootDir,
+      env: { ...process.env, HAPPY_STACKS_UPDATE_CHECK_SPAWNED: '1' },
+      detached: true,
+    });
+    child.unref();
+  } catch {
+    // ignore
+  }
+}
+
+function usage() {
+  return renderHappysRootHelp();
+}
+
+function runNodeScript(cliRootDir, scriptRelPath, args) {
+  const scriptPath = join(cliRootDir, scriptRelPath);
+  if (!existsSync(scriptPath)) {
+    console.error(`[happys] missing script: ${scriptPath}`);
+    process.exit(1);
+  }
+  const res = spawnSync(process.execPath, [scriptPath, ...args], {
+    stdio: 'inherit',
+    env: process.env,
+    cwd: cliRootDir,
+  });
+  process.exit(res.status ?? 1);
+}
+
+function main() {
+  const cliRootDir = getCliRootDir();
+  const argv = process.argv.slice(2);
+
+  const cmd = argv.find((a) => !a.startsWith('--')) ?? 'help';
+  const rest = cmd === 'help' ? [] : argv.slice(argv.indexOf(cmd) + 1);
+
+  maybeAutoUpdateNotice(cliRootDir, cmd);
+
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    const target = argv[argv.indexOf(cmd) + 1];
+    if (!target) {
+      console.log(usage());
+      return;
+    }
+    const targetCmd = resolveHappysCommand(target);
+    if (!targetCmd || targetCmd.kind !== 'node') {
+      console.error(`[happys] unknown command: ${target}`);
+      console.error('');
+      console.log(usage());
+      process.exit(1);
+    }
+    const helpArgs = commandHelpArgs(target) ?? ['--help'];
+    return runNodeScript(cliRootDir, targetCmd.scriptRelPath, helpArgs);
+  }
+
+  const resolved = resolveHappysCommand(cmd);
+  if (!resolved) {
+    console.error(`[happys] unknown command: ${cmd}`);
+    console.error('');
+    console.error(usage());
+    process.exit(1);
+  }
+
+  if (resolved.kind === 'external') {
+    const args = resolved.external?.argsFromRest ? resolved.external.argsFromRest(rest) : rest;
+    const res = spawnSync(resolved.external.cmd, args, { stdio: 'inherit', env: process.env });
+    process.exit(res.status ?? 1);
+  }
+
+  const args = resolved.argsFromRest ? resolved.argsFromRest(rest) : rest;
+  return runNodeScript(cliRootDir, resolved.scriptRelPath, args);
+}
+
+main();

package/docs/menubar.md

@@ -0,0 +1,186 @@
+# Menu bar (SwiftBar)
+
+`happy-stacks` ships a macOS menu bar plugin powered by [SwiftBar](https://swiftbar.app/).
+
+SwiftBar runs a script on an interval and renders its output as native macOS menu items.
+
+## Features
+
+- **Status at a glance** with dynamic icons (green/orange/red)
+  - Server health
+  - Daemon status (PID + optional control server probe)
+  - Autostart LaunchAgent status
+  - Tailscale Serve status / URL (if configured)
+- **Quick controls**
+  - Start / stop / restart the stack
+  - Install / enable / disable / uninstall autostart
+  - Enable / disable Tailscale Serve
+- **Details**
+  - PID, CPU %, RAM MB, uptime (where available)
+  - Useful URLs and file paths
+  - Open logs in Console.app
+- **Refresh control**
+  - Manual refresh
+  - In-menu refresh interval toggles (includes slower intervals like 10m/15m/30m/1h/6h/12h/1d)
+  - Uses a small helper script (`extras/swiftbar/set-interval.sh`) to avoid SwiftBar quoting issues
+- **Stacks + components layout**
+  - Main stack is shown directly (no extra nesting level)
+  - Each stack shows component rows (Server/Daemon/Autostart/Tailscale) with per-component submenus
+ - **Components (git/worktrees)**
+  - Available under a top-level **Components** submenu (to keep the main menu clean)
+  - Shows repo/worktree status for each component under `components/`
+  - 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`)
+
+## Stacks (multiple instances)
+
+If you create additional stacks (see `docs/stacks.md`), the plugin shows:
+
+- **Main stack** (the default, stack name `main`)
+- **Stacks** section listing each stack found under `~/.happy/stacks/<name>/env` (legacy: `~/.happy/local/stacks/<name>/env`)
+
+Each stack row renders the same “mini control panel” (server/daemon/autostart/logs + a few actions) with stack-specific ports, dirs, and LaunchAgent label.
+
+The menu also includes:
+
+- `stack new --interactive` (create stacks)
+- `stack edit <name> --interactive` (edit stack port/server flavor/worktrees)
+- `stack wt <name> -- use --interactive` (switch component worktrees inside a stack)
+- “PR worktree into this stack (prompt)” (creates `wt pr ... --use` scoped to the stack env)
+
+## Worktrees (quick entry points)
+
+The menu also provides “jump off” actions for the worktree tooling:
+
+- `happys wt use --interactive`
+- `happys wt new --interactive`
+- `happys wt sync-all`
+- `happys wt update-all --dry-run` / `happys wt update-all`
+- `happys wt pr ...` (via an in-menu prompt)
+
+For stack-specific worktree selection (which components a stack uses), use:
+
+- `happys stack edit <name> --interactive`
+  - or `happys stack wt <name> -- use --interactive`
+
+## Implementation notes
+
+- **Entry script**: `extras/swiftbar/happy-stacks.5s.sh` (installed into SwiftBar as `happy-stacks.<interval>.sh`)
+- **Shared functions**: `extras/swiftbar/lib/*.sh` (sourced by the entry script)
+- **Helper scripts**:
+  - `extras/swiftbar/set-interval.sh`
+  - `extras/swiftbar/set-server-flavor.sh`
+
+## Install
+
+### 1) Install SwiftBar
+
+```bash
+brew install --cask swiftbar
+```
+
+### 2) Install the plugin
+
+From the `happy-stacks` repo:
+
+```bash
+happys menubar install
+```
+
+If you want a different default refresh interval at install time:
+
+```bash
+HAPPY_STACKS_SWIFTBAR_INTERVAL=15m happys menubar install
+# legacy: HAPPY_LOCAL_SWIFTBAR_INTERVAL=15m happys menubar install
+```
+
+### 3) Open the active SwiftBar plugin folder
+
+SwiftBar can be configured to use a custom plugin directory. To open the *active* one:
+
+```bash
+happys menubar open
+```
+
+## Uninstall
+
+Remove the installed SwiftBar plugin files (does not delete your stacks/workspace):
+
+```bash
+happys menubar uninstall
+```
+
+## How refresh works (important)
+
+SwiftBar’s refresh interval is controlled by the **filename** suffix:
+
+- `happy-stacks.30s.sh` → every 30 seconds
+- `happy-stacks.5m.sh` → every 5 minutes
+- `happy-stacks.1h.sh` → every 1 hour
+
+The plugin defaults to a slower interval (recommended), and also sets:
+
+- `refreshOnOpen=false` (recommended) to avoid surprise refreshes while you’re navigating the menu.
+
+You can also change the interval directly from the menu via **Refresh interval** (it renames the plugin file and restarts SwiftBar).
+
+## Terminal preference for interactive actions
+
+Many menu actions open a terminal (interactive wizards, long-running dev servers, etc).
+The plugin uses helper scripts so these run in your preferred terminal, using the same env var as `wt shell`:
+
+- `HAPPY_STACKS_WT_TERMINAL=auto|ghostty|iterm|terminal|current` (legacy: `HAPPY_LOCAL_WT_TERMINAL`)
+
+Notes:
+- `auto` tries ghostty → iTerm → Terminal → current.
+- Ghostty is best-effort; if your Ghostty build can’t execute the command automatically, the command is copied to your clipboard and Ghostty is opened in the repo directory.
+
+## Start SwiftBar at login (optional)
+
+SwiftBar is independent from the Happy Stacks LaunchAgent.
+
+- In SwiftBar Preferences, enable **Launch at Login**, or
+- Add SwiftBar to macOS **Login Items**.
+
+## Troubleshooting
+
+### Plugin doesn’t show up
+
+- Ensure SwiftBar is running.
+- Check which plugin folder SwiftBar is using:
+  - SwiftBar → Preferences → Plugin Folder
+- Open the active folder:
+  - `happys menubar open`
+
+### Daemon shows “auth required” / “no machine”
+
+This happens on a **fresh machine** (or any new stack) when the daemon does not yet have credentials in the
+stack-specific CLI home directory.
+
+**What’s going on**
+
+- The daemon stores credentials in `access.key` under the CLI home directory.
+- For stacks (including main), that’s typically:
+  - `~/.happy/stacks/<name>/cli/access.key`
+- When `access.key` is missing, `happy-cli daemon start` enters an interactive auth flow and won’t become a “machine” until it completes.
+  - Under `launchd` (autostart), this shows up as **no machine** and the daemon may appear “stopped”.
+
+**If it still needs auth**
+
+- In SwiftBar, open the **Daemon** section:
+  - If it shows `auth_required`, click **Auth login (opens browser)**
+- Or run manually:
+
+```bash
+happys auth login
+```
+
+### “Daemon stale” even though it’s running
+
+The plugin checks:
+
+- `daemon.state.json` **PID is alive**, and
+- (optionally) the daemon control server responds.
+
+If the daemon is running but the menu is stale, refresh and check the **PID** line under “Daemon”.