very-happy local development

The repository uses pnpm workspaces. The production client is packages/happy-web-v2; do not route Web work to the legacy happy-app.

First setup

pnpm install --frozen-lockfile
pnpm -C packages/happy-wire build

happy-wire/dist is gitignored but consumed through the package entrypoint, so a clean checkout must build it before packages that import wire.

UI 工作同时读取 .agents/skills/design/SKILL.md，遵循项目统一设计契约并验证真实功能完整性。

Fast package loops

Web V2 (defaults to port 8082 and proxies API/socket traffic):

pnpm -C packages/happy-web-v2 dev
pnpm -C packages/happy-web-v2 exec vitest run
pnpm -C packages/happy-web-v2 exec tsc --noEmit
pnpm -C packages/happy-web-v2 exec vite build

Verify a test actually pins the line it claims to (source-assertion tests can pass after the asserted string is deleted — see docs/PROCESS.md):

node scripts/dev/mutation-check.mjs --pkg happy-web-v2 \
  --test src/screens/onboarding/connectMachine.test.ts \
  --mutate "packages/happy-web-v2/src/screens/sessions/Sidebar.tsx:key: 'connect-machine'"

视觉/CSS 改动要在真实浏览器里量（AGENTS「验收」是硬要求），别现搭 harness：

# 真实 CSS + 真 Chromium；scenario 里写 measure()，需要时写 pixels() 采像素
node scripts/dev/css-probe.mjs path/to/scenario.mjs --out ~/code/github/skills/tmp/ui-review/shots

手机验证必须读取实际 matchMedia('(pointer: coarse)').matches，不能仅凭 hasTouch/窗口宽度认定触屏生效。当前锁定 Playwright 与缓存 Chromium 的长页截图会重置触屏模拟；css-probe.mjs 已在 page 创建后显式启用原生触屏，手机通过 CDP 只截真实视口，并核验截图后仍为 coarse。长内容另验滚动和可达性，不能把手机视口截图当全页截图。自定义浏览器脚本也要在导航/截图后核验媒体查询，截图与交互必须采用同一指针模式。

「这个功能该不该做」先量语料再决定：

node scripts/dev/corpus-stats.mjs                # 本机 transcript 里 agent 输出的 markdown 形态
node scripts/dev/corpus-stats.mjs --samples math # 看命中样本（数学那一项几乎全是假阳性）

Vitest runs happy-web-v2 in the node environment, so a test that renders a real component must call installBrowserTestGlobals() from @/testing/browserTestGlobals before importing it (dynamically — static imports hoist above the setup). Pure-function modules need nothing.

Standalone server (PGlite, no Postgres/Redis/S3 required):

pnpm -C packages/happy-server standalone:dev
pnpm -C packages/happy-server exec vitest run
pnpm -C packages/happy-server exec tsc --noEmit

CLI/daemon:

pnpm -C packages/happy-cli test
node packages/happy-cli/dist/index.mjs --version

For a disposable CLI home, never reuse the production daemon state:

VH_DEV_HOME=$(mktemp -d)
HAPPY_HOME_DIR="$VH_DEV_HOME" HAPPY_SERVER_URL=http://127.0.0.1:3005 \
  node packages/happy-cli/dist/index.mjs daemon start

packages/happy-cli's cli:install deliberately replaces the global binary and restarts the real daemon using ~/.happy; use it only when that side effect is intended.

Full local Web V2 + server

Terminal 1:

pnpm -C packages/happy-server standalone:dev

Terminal 2:

VH_SERVER_URL=http://127.0.0.1:3005 pnpm -C packages/happy-web-v2 dev

The Vite server uses the configured target for /v1, /v2, /v3, /health and WebSocket proxying, preserving the production same-origin shape.

The root pnpm env:* manager still contains upstream Expo assumptions. Until it is migrated to Web V2, do not use pnpm env:web as proof of the production Web path; prefer the two-terminal loop above.

Logs and daemon recovery

ls -t ~/.happy/logs | head
tail -f ~/.happy/logs/$(ls -t ~/.happy/logs | head -1)
very-happy daemon status

If a dev daemon is stuck, resolve the exact HAPPY_HOME_DIR first, then stop it and remove only that home's daemon.state.json.lock. Never broadly delete ~/.happy.

The daemon resolves claude through PATH. Non-interactive shells and launchd do not source .zshrc, so PATH must explicitly include ~/.local/bin.

Cross-package rules

• Protocol/schema changes: update happy-wire, build its dist, and document the old/new compatibility matrix in a spec.
• Synced setting fields never receive Zod .default() values; defaults live in the settings defaults layer.
• Repository tools run through pnpm exec, never bare npx.
• The merge gates and known exception are canonical in AGENTS.md and docs/PROCESS.md; do not invent a lighter package-specific gate here.

Production is not a dev environment

Do not test local changes by mutating vh-sg, the relays or the daemon hosts (mac-office, dev-sg) unless the user asked for a deployment. Production topology and recovery commands live in docs/operations.md.