hapi/AGENTS.md

AGENTS.md

Guidelines for AI agents working in this workspace.

Monorepo Structure

Bun workspaces monorepo with three packages:

Package	Path	Purpose
hapi	cli/	CLI tool (npm package) - hapi / hapi-mcp commands
hapi-server	server/	API server + Telegram bot (serves web/dist/)
hapi-web	web/	Web frontend / Mini App / PWA (Vite → dist/)

hapi/
├── package.json              # Workspace root
├── tsconfig.base.json        # Shared TS config
├── cli/
│   ├── package.json          # npm: hapi
│   ├── src/                  # CLI source
│   └── bin/                  # Executables
├── server/
│   ├── package.json          # private
│   └── src/                  # Hono + Socket.IO + Grammy
└── web/
    ├── package.json          # private
    ├── vite.config.ts
    └── src/                  # React + Tailwind

Shared Rules

• TypeScript strict - No untyped code
• Bun workspaces - Run bun install / bun run ... from repo root
• Path aliases - @/* → ./src/* (per-package tsconfig)
• No backward compatibility - Break old formats freely
• 4-space indent - Prefer 4 spaces

Commands

Run from repo root:

# Build
bun run build            # Build all packages
bun run build:cli        # CLI only (pkgroll → CJS + ESM)
bun run build:server     # Server only (bun build)
bun run build:web        # Web only (Vite)

# Type check
bun run typecheck        # All packages

# Development
bun run dev:server       # Server with --watch
bun run dev:web          # Vite dev server

# Test
bun run test             # CLI tests (Vitest)

Package Details

cli/ (hapi)

• Entry: src/index.ts → bin/happy.mjs
• Build: pkgroll generates CJS + ESM bundles
• Test: vitest with .env.integration-test
• Publish: npm publish (see cli/package.json)

server/ (hapi-server)

• Entry: src/index.ts
• Runtime: Bun
• Stack: Hono (HTTP) + Socket.IO + Grammy (Telegram)
• Static: Serves ../web/dist/ via src/web/server.ts

web/ (hapi-web)

• Entry: src/main.tsx
• Stack: React 19 + Tailwind + Vite
• Output: dist/ (served by server)

Key Source Directories

Package	Key Paths
cli	src/api/, src/claude/, src/commands/, src/codex/
server	src/web/, src/socket/, src/telegram/, src/sync/
web	src/components/, src/api/, src/hooks/