dev - SKILL.md Agent Skill

name: dev description: > Local development guide for the Happy monorepo. How to build, install, test, and run the CLI, server, mobile app, and desktop (Tauri) locally. Use when the user types /dev, asks how to "build", "start dev", "install locally", or "run the ___ package".

/dev - Local Development

Happy is a pnpm monorepo. Everything uses pnpm workspaces — do not use npm or yarn directly.

First-time setup

pnpm install                       # installs deps for every package
pnpm --filter happy cli:install    # builds happy-cli + links it as the global `happy` binary

cli:install replaces whatever happy is on your PATH (npm-installed or not) with a symlink to packages/happy-cli/. Daemon is restarted as part of the script. Uses ~/.happy/ — same as production.

To undo: npm unlink -g happy && npm i -g happy@latest.

Packages

packages/happy-cli     # the `happy` CLI and daemon, published to npm
packages/happy-server  # Node + Prisma server, deployed via TeamCity
packages/happy-app     # Expo app: iOS, Android, web, Tauri desktop
packages/happy-agent   # agent runtime
packages/happy-wire    # shared Zod schemas + wire types

happy-cli

packages/happy-cli
scripts in package.json:
  typecheck      # tsc --noEmit
  build          # rm -rf dist && tsc --noEmit && pkgroll
  test           # build + vitest run
  cli:install    # build + stop daemon + npm link + start daemon
  prepublishOnly # pnpm test (runs build inside test)
  postinstall    # unpacks difft + rg binaries into tools/unpacked/

Work loop:

pnpm --filter happy cli:install   # rebuild + relink + restart daemon
happy daemon status               # confirm your build is running
happy doctor                      # list all happy processes
tail -f ~/.happy/logs/$(ls -t ~/.happy/logs/ | head -1)

Run a single test file quickly:

pnpm --filter happy exec vitest run src/path/to/file.test.ts

Unit-only (fast, ~1 min):

pnpm --filter happy exec vitest run --project unit

Integration tests hit real APIs and are flaky — run on demand, never in the release gate.

Dev data sandbox (optional)

happy reads HAPPY_HOME_DIR to override ~/.happy/. To run two versions side-by-side without touching your prod auth:

HAPPY_HOME_DIR=~/.happy-dev happy daemon start
HAPPY_HOME_DIR=~/.happy-dev happy auth

Point at a local server the same way:

HAPPY_SERVER_URL=http://localhost:3005 happy daemon start

happy-server

pnpm --filter happy-server standalone:dev   # localhost:3005, embedded PGlite, no Docker

App auto-reloads on source changes. Point the CLI or the Expo app at it with HAPPY_SERVER_URL=http://localhost:3005 / EXPO_PUBLIC_HAPPY_SERVER_URL=....

happy-app (Expo)

pnpm --filter happy-app start           # expo start (Metro bundler)
pnpm --filter happy-app ios:dev         # iOS simulator, development variant
pnpm --filter happy-app android:dev
pnpm --filter happy-app web             # web build, served locally
pnpm --filter happy-app tauri:dev       # macOS desktop app

Variants:

development    com.slopus.happy.dev       # hot reload, internal
preview        com.slopus.happy.preview   # OTA / beta testing
production     com.ex3ndr.happy           # App Store

Rebuild and reinstall the desktop .app

When the user asks to "rebuild the desktop app", "kill the running one and reinstall", or anything in that shape — do all four steps in order, do not stop after building.

Variants → product name → build script:

production    Happy.app           pnpm --filter happy-app tauri:build:production
preview       Happy (preview).app pnpm --filter happy-app tauri:build:preview
dev           Happy (dev).app     pnpm --filter happy-app tauri:build:dev

Build output for all variants:

packages/happy-app/src-tauri/target/release/bundle/macos/<ProductName>.app

If the variant is ambiguous, check what's running with ps aux | grep "/Applications/.*Happy" | grep -v grep and match. Production is the default.

Steps (substitute $NAME with the product name, e.g. Happy or Happy (dev)):

# 1. build (slow: ~3–10 min, expo web export then cargo release build)
pnpm --filter happy-app tauri:build:production

# 2. quit the running app gracefully (no-op if not running)
osascript -e 'tell application "$NAME" to quit' || true

# 3. replace the installed bundle
rm -rf "/Applications/$NAME.app"
cp -R "packages/happy-app/src-tauri/target/release/bundle/macos/$NAME.app" /Applications/

# 4. relaunch
open -a "$NAME"

Notes:

Run the build in the background (run_in_background: true on Bash) and poll the output file. It prints Finished \release` profile` near the end.
osascript ... to quit is graceful — it gives the app a chance to flush state. Only fall back to pkill -f "/Applications/$NAME.app/Contents/MacOS/app" if the quit hangs.
Do NOT skip the rm -rf before cp — cp -R over an existing .app merges directories and leaves stale files.
If macOS Gatekeeper complains on relaunch, xattr -dr com.apple.quarantine "/Applications/$NAME.app" clears it. Local builds are unsigned.

happy-app-logs (remote log receiver)

pnpm --filter happy-app-logs dev       # starts on http://0.0.0.0:8787

Receives POST requests to /logs from the mobile app's patched console (see consoleLogging.ts). Logs to stdout and ~/.happy/app-logs/<timestamp>.log.

To connect: set the log server URL in the app's dev settings to http://<LAN_IP>:8787. The app's consoleLogging.ts sends all console.log/warn/error to this endpoint when configured.

Console output must be enabled in the app (dev/preview variants default on, production defaults off, togglable from the dev settings screen).

Cross-cutting

Hoisted deps: pnpm hoists node_modules to the repo root. packages/*/node_modules/ is mostly empty. Node's resolution walks up, so imports work transparently.
Workspace deps: "@slopus/happy-wire": "workspace:*" resolves to packages/happy-wire/ — edits are picked up live.
$npm_execpath: legacy; happy-cli uses pnpm literally. Windows cmd.exe doesn't expand $VAR.
Build before tests: tests spawn the built CLI binary (for daemon integration), so pnpm test runs build first. Do not remove.

Releasing

Do not publish by hand. Use /release — it handles npm publish, git tags, GitHub releases, and the smoke check.

Troubleshooting

happy: command not found     → pnpm --filter happy cli:install
daemon won't start           → happy daemon stop; rm ~/.happy/daemon.state.json.lock; happy daemon start
wrong `happy` version        → which happy && ls -la $(which happy) — confirms where it resolves to
tools/unpacked missing       → pnpm install (postinstall re-extracts)
stale deps after branch swap → pnpm install (pnpm is picky about lockfile drift)

Rules

Never use npm install or yarn install — only pnpm.
Never add a dev / cli tsx-based script back to happy-cli. The build step is not optional — daemon spawns the built binary and would desync.
Never bring back release-it. Releases go through /release.
Never introduce ~/.happy-dev as a default. It exists as an opt-in via HAPPY_HOME_DIR, nothing more.