happy-stacks 0.4.0 → 0.5.0

package/README.md

@@ -4,28 +4,42 @@ Run [**Happy**](https://happy.engineering/) locally and access it remotely and s
 
 ## 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.
+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, from a web UI and/or from a desktop app.
 
 ## What is Happy Stacks?
 
 happy-stacks is a guided installer + local orchestration CLI for Happy.
 
-If you only want to **self-host Happy**, start with the **Self-host** section below.
+If you only want to **use Happy** and self-host it on your computer, start with the **Self-host** section below.
 If you want to **develop Happy** (worktrees, multiple stacks, upstream PR workflows), see the **Development** section further down.
 
 ## Self-host Happy (install + run)
 
-### Step 1: Setup
-
-Recommended:
+### Quickstart
 
 ```bash
 npx happy-stacks setup --profile=selfhost
 ```
 
-`setup` can optionally start Happy and guide you through authentication.
+Follow the guided instructions to install Happy and launch it.
+
+### Daily use
+
+#### Configure provider API keys for the daemon
+
+If you want the daemon to have access to provider API keys (for example OpenAI), you can set them so they are automatically loaded when the daemon starts:
+
+```bash
+happys env set OPENAI_API_KEY=sk-...
+```
 
-### Step 2: Start Happy
+Then restart so the daemon picks up the new environment:
+
+```bash
+happys start --restart
+```
+
+### Start Happy
 
 Starts the local server, CLI daemon, and serves the pre-built UI.
 
@@ -33,9 +47,9 @@ Starts the local server, CLI daemon, and serves the pre-built UI.
 happys start
 ```
 
-### Step 3 (first run only): authenticate
+### Authentication
 
-On a **fresh machine** (or any new stack), the daemon needs to authenticate once before it can register a “machine”.
+On a **fresh machine**, the daemon needs to authenticate once before it can register a “machine”.
 
 ```bash
 happys auth login
@@ -47,17 +61,16 @@ If you want a quick diagnosis:
 happys auth status
 ```
 
-### Step 4: Enable Tailscale Serve (recommended for mobile/remote)
+### Enable Tailscale Serve (recommended for mobile/remote)
 
 ```bash
 happys tailscale enable
 happys tailscale url
 ```
 
-### Step 5: Mobile access
+### Mobile access
 
-Make sure Tailscale is [installed and running]
-([https://tailscale.com/kb/1347/installation](https://tailscale.com/kb/1347/installation)) on your 
+Make sure Tailscale is [installed and running](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
@@ -69,36 +82,21 @@ Details (secure context, phone instructions, automation knobs): `[docs/remote-ac
 
 ## Development (worktrees, stacks, contributor workflows)
 
+If you want to **develop Happy** (worktrees, multiple stacks, upstream PR workflows), you can install Happy Stacks for development with:
+
 ### Setup (guided)
 
 ```bash
 npx happy-stacks setup --profile=dev
 ```
 
-### Developing from a cloned repo
+During setup, you’ll be asked where to store your **workspace** (the folder that will contain `components/` and `components/.worktrees/`).
+You can also set it non-interactively:
 
 ```bash
-git clone https://github.com/leeroybrun/happy-stacks.git
-cd happy-stacks
-
-node ./bin/happys.mjs setup --profile=dev
+npx happy-stacks setup --profile=dev --workspace-dir=~/Development/happy
 ```
 
-Notes:
-
-- In a cloned repo, `pnpm <script>` still works, but `happys <command>` is 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
-  ```
-
 ### Why this exists
 
 - **Automated setup**: `happys setup` + `happys start` gets the whole stack up and running.
@@ -401,6 +399,15 @@ Notes:
 
 - Canonical env prefix is `HAPPY_STACKS_*` (legacy `HAPPY_LOCAL_*` still works).
 - Canonical stack storage is `~/.happy/stacks` (legacy `~/.happy/local` is still supported).
+- To edit per-stack environment variables (including provider keys like `OPENAI_API_KEY`), use:
+
+  ```bash
+  happys stack env <stack> set KEY=VALUE
+  happys stack env <stack> unset KEY
+  happys stack env <stack> get KEY
+  happys stack env <stack> list
+  ```
+
 - **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.
@@ -427,3 +434,27 @@ Notes:
 - To explicitly allow those for testing, set `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1` (still recommended to clean up after).
 
 For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.
+
+### Developing Happy Stacks itself
+
+```bash
+git clone https://github.com/leeroybrun/happy-stacks.git
+cd happy-stacks
+
+node ./bin/happys.mjs setup --profile=dev
+```
+
+Notes:
+
+- In a cloned repo, `pnpm <script>` still works, but `happys <command>` is 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
+```

package/bin/happys.mjs

@@ -9,6 +9,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { commandHelpArgs, renderHappysRootHelp, resolveHappysCommand } from '../scripts/utils/cli/cli_registry.mjs';
 import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/paths/canonical_home.mjs';
+import { resolveStackEnvPath } from '../scripts/utils/paths/paths.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
@@ -377,8 +378,50 @@ function main() {
     return runNodeScript(cliRootDir, targetCmd.scriptRelPath, helpArgs);
   }
 
-  const resolved = resolveHappysCommand(cmd);
+  let resolved = resolveHappysCommand(cmd);
   if (!resolved) {
+    // Stack shorthand:
+    // If the first token is not a known command, but it *is* an existing stack name,
+    // treat `happys <stack> <command> ...` as `happys stack <command> <stack> ...`.
+    const stackName = cmd;
+    const { envPath } = resolveStackEnvPath(stackName, process.env);
+    const stackExists = existsSync(envPath);
+    if (stackExists) {
+      const cmdIdx = rest.findIndex((a) => !a.startsWith('-'));
+      if (cmdIdx < 0) {
+        if (rest.includes('--help') || rest.includes('-h')) {
+          const stackCmd = resolveHappysCommand('stack');
+          if (!stackCmd || stackCmd.kind !== 'node') {
+            console.error('[happys] internal error: missing stack command');
+            process.exit(1);
+          }
+          return runNodeScript(cliRootDir, stackCmd.scriptRelPath, ['--help']);
+        }
+        console.error(`[happys] missing command after stack name: ${stackName}`);
+        console.error('');
+        console.error('Try one of:');
+        console.error(`  happys ${stackName} env list`);
+        console.error(`  happys ${stackName} dev`);
+        console.error(`  happys ${stackName} start`);
+        console.error('');
+        console.error('Equivalent long form:');
+        console.error(`  happys stack <command> ${stackName} ...`);
+        process.exit(1);
+      }
+
+      const stackSubcmd = rest[cmdIdx];
+      const preFlags = rest.slice(0, cmdIdx);
+      const post = rest.slice(cmdIdx + 1);
+      const stackArgs = [stackSubcmd, stackName, ...preFlags, ...post];
+
+      resolved = resolveHappysCommand('stack');
+      if (!resolved || resolved.kind !== 'node') {
+        console.error('[happys] internal error: missing stack command');
+        process.exit(1);
+      }
+      return runNodeScript(cliRootDir, resolved.scriptRelPath, stackArgs);
+    }
+
     console.error(`[happys] unknown command: ${cmd}`);
     console.error('');
     console.error(usage());

package/docs/codex-mcp-resume.md

@@ -0,0 +1,130 @@
+# Codex MCP resume (experimental) — Happy integration spec
+
+This document describes how to integrate an **experimental** Codex MCP server fork
+that can **resume sessions from rollout JSONL** after restarts/crashes.
+
+## Goals
+
+- Allow Happy to use a Codex MCP server that supports **resume-from-rollout**.
+- Keep the feature **opt-in** and **safe by default** (pinned versions, clear UI).
+- Avoid requiring users to replace their global `codex` install.
+
+## Non-goals
+
+- Replacing OpenAI’s `@openai/codex` installation for general CLI usage.
+- Auto-updating to “latest” without user opt-in.
+
+## Key facts (implementation reality)
+
+- `codex-mcp-server` is **not** a thin wrapper around a user-installed `codex` binary.
+  It embeds Codex core and runs threads internally.
+- Therefore, when Happy uses this MCP server, the “engine” for those sessions is
+  the forked Codex Rust core shipped with the MCP server build.
+
+## Distribution model (recommended)
+
+Ship the MCP server as an npm package that bundles native binaries:
+
+- **npm package**: `@leeroy/codex-mcp-resume`
+- **binary launcher**: `npx -y @leeroy/codex-mcp-resume@<pinned-version>`
+- **native payload**: `vendor/<targetTriple>/codex-mcp-server/codex-mcp-server[.exe]`
+
+This mirrors how upstream Codex ships platform binaries via npm.
+
+## Versioning + updates
+
+### Pinned by Happy (default)
+
+- Happy pins an exact semver (example): `0.84.0-resume.123.a1`
+- Happy invokes:
+  - `npx -y @leeroy/codex-mcp-resume@0.84.0-resume.123.a1`
+
+**Update path**: users get new MCP builds when they update Happy (or when Happy updates the pin).
+
+### Optional “auto-update experimental tools” (opt-in)
+
+If you want faster iteration:
+
+- Happy uses `@latest` or a dedicated dist-tag (e.g. `resume`)
+- This should be opt-in, clearly labeled “may break”.
+
+## Happy-side feature flag / settings
+
+### Setting name (proposed)
+
+- **Config**: `experimental.codexMcpResume = true|false`
+- **Env override** (optional): `HAPPY_EXPERIMENTAL_CODEX_MCP_RESUME=1`
+
+### UX (proposed)
+
+- Settings → Experimental → “Use Codex MCP resume fork”
+- Subtext: “Runs a separate MCP server shipped by Happy; may differ from your global Codex install.”
+
+## Process + wiring
+
+### 1) Resolve the MCP server command
+
+When feature enabled, Happy should register an MCP server entry equivalent to:
+
+```toml
+[mcp_servers.codex_resume]
+command = "npx"
+args = ["-y", "@leeroy/codex-mcp-resume@0.84.0-resume.123.a1"]
+```
+
+Notes:
+- The MCP server is stdio-based; Happy should spawn it and speak MCP JSON-RPC over stdin/stdout.
+- Use `-y` to make it non-interactive.
+- Ensure Happy’s environment does **not** leak secrets in logs.
+
+### 2) Decide the Codex “home” used for sessions
+
+Session restoration depends on reading rollout JSONL files.
+
+Two viable modes:
+
+- **Shared home (recommended for seamless resume)**:
+  - Run with the user’s default Codex home (usually `~/.codex`), so the MCP server sees the same rollouts.
+- **Happy-managed home (more isolated)**:
+  - Provide a separate home (e.g. `~/.happy/codex`) but then “resume existing Codex sessions” won’t work unless you import/migrate.
+
+If you need an explicit home, pass env vars when spawning the MCP server:
+
+- `CODEX_HOME=<path>`
+
+### 3) Tool usage from Happy
+
+Happy should call MCP tools:
+
+- **Start new session**: `tools/call name="codex"` with desired config (model, cwd, approval_policy/sandbox, etc).
+- **Continue session**: `tools/call name="codex-reply"` with `{ threadId, prompt }`.
+
+The forked MCP server handles:
+
+- in-memory threads normally
+- on restart/crash: “resume thread” by reading rollout history
+
+### 4) Concurrency expectations
+
+Happy may issue multiple `codex-reply` calls concurrently (UI retries, double-submit, etc).
+The MCP server should serialize per-thread reply/resume to avoid event-stream races.
+
+## CI + publishing requirements (for maintainers)
+
+The fork’s CI should:
+
+- build `codex-mcp-server` for macOS/Linux/Windows (arm64 + x64 where relevant)
+- pack those into an npm tarball
+- publish via npm trusted publishing (OIDC)
+
+## What Happy devs need to implement (checklist)
+
+- Add a feature flag + settings surface (opt-in).
+- Add MCP server registry entry for `codex_resume` (command: `npx`, args pinned).
+- Decide and document which Codex home dir is used (shared vs isolated).
+- Route Codex session creation + reply calls through the selected MCP server.
+- Add telemetry/logging that records:
+  - selected MCP server (default vs resume fork)
+  - package version (pinned version string)
+  - threadId for correlation (no prompt contents)
+