diff --git a/CLAUDE.md b/CLAUDE.md index 41d80b7..0d7f438 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,45 +48,7 @@ before you open a PR. ## Code map -Server (`server/`, Node + Express 5 + ws, run by tsx in development; esbuild bundles it into `dist-server/` for npm): -- `index.ts`: entry; picks the real or demo backend, REST routes under `/api`, the `/ws` and `/ws/term` websockets, serves `dist/`, shutdown. -- `config.ts`: `SWARM_PORT` (default 4417), `SWARM_HOME` (default `codedungeon-home` beside the repo), `--demo`, state file, intervals, - the default projects folder. -- `swarm.ts`: the orchestrator. Floors, agents, scheduling/auto-assign, dev → QA → fix → merge loop, dev and QA - prompts, CEO job queue, phone messages, persistence (`state.json` / `demo-state.json`), websocket fan-out. -- `agentRunner.ts`: one Agent SDK session; options, env stripping, Playwright MCP, and turning the SDK stream into - terminal lines. -- `cliRunner.ts`: the terminal runtime (the default): one agent as the real CLI in a node-pty, same session contract - as `agentRunner.ts`. Claude Code reports through HTTP hooks (`POST /api/hooks/:token`; PreToolUse approves every - call); Codex reports turn endings (notify) and, once the manager trusts them, its steps (`-c hooks.*`); OpenCode - only turn endings. Codex/OpenCode screenshots are collected from the session's Playwright output folder. Esc in a - terminal ends the session as `interrupted`. The CEO's office tools are served over MCP (`/api/mcp/:token`). -- `ptyHost.ts`: the terminal keeper, a detached process of its own (`launch` re-spawns it outside the office's process - tree) holding the CLIs' pseudo-terminals and relaying their hooks, so agents keep working through office restarts. - `ptyClient.ts` is the office's side (start/connect, spawn, adopt after a restart, local fallback); `ptyProtocol.ts` - their JSON-lines messages. The launcher's `office:shutdown` says `restart: false` when quitting: CLIs stop then. - A developer's CLI stays at its prompt after the task (`keepAlive`): follow-ups and prompts typed there reuse it. -- `boxes.ts`, `boxRunner.ts`: coders in Upstash Boxes (`@upstash/box`). `boxes.ts` is the box layer: the API key and - GitHub token (env or the Windows user environment), the base snapshot (`BASE_SETUP`), desk and sign-in scripts, and - the events program every hook and status line runs in a box. `boxRunner.ts`'s `BoxPty` implements `Pty` for a CLI - in tmux in the box: `tmux attach` over a PTY session (reconnects with backoff), events followed with `tail -F`. - `shared/cloudBoxes.ts` holds the settings and who may move into a box. Testers stay local. -- `clis.ts`: the CLIs (Claude Code from the SDK's bundled binary, Codex, OpenCode): detection, Windows `.cmd` shim - unwrapping, each one's command line, and the helper scripts they call back with. -- `terminal.ts`: `AgentTerminal`, a headless xterm mirror per agent (replay for late viewers, saved to disk), its - `/ws/term` viewers, and keystrokes/resizes to the running CLI. -- `ceo.ts`: the CEO's office MCP tools (`createOfficeTools`, zod-validated), `ceoSystemPrompt`, `ceoJobPrompt`. -- `backend.ts`: the `Backend` interface (everything touching GitHub, git, disk and sessions) and `realBackend`. -- `demo.ts`: `createDemoBackend()`: fake GitHub, fake sessions (drawn into the agent's terminal in the terminal runtime), fake previews for `--demo`. -- `github.ts`: all GitHub access through the `gh` CLI. -- `workspace.ts`: floor checkouts, per-agent worktrees (`/workspaces/__/desks/`), - fast-forwarding main, per-repo git lock, stopping processes an agent left running. -- `exec.ts`: `run` / `git` / `gh`: `execFile` without a shell, prompts disabled, `CommandError` with stderr. -- `previews.ts`: one preview per floor: ports (6300 + floor), statuses, config validation. -- `previewRunner.ts`: checks out, installs and runs a floor's app in its preview worktree; kills the process tree. -- `httpError.ts`: `HttpError(status, message)`. -- `officeUpdate.ts`: the office's self-update: the drain decision, the launcher contract (IPC, `last-update.json`). -- `pacing.ts`: pacing new work after Claude's usage warnings: the start/skip decision and the usage state. +The server's and client's file-by-file maps are in `server/CLAUDE.md` and `client/CLAUDE.md`. The `cubefarm` command (`bin/cubefarm.js`, plain JS): checks Node/git/gh/Claude login, starts `dist-server/index.js`, opens the browser; `login` and `doctor` subcommands. @@ -101,17 +63,6 @@ Shared (`shared/`, imported by both sides): - `types.ts`: the REST/websocket contract (`WorldSnapshot`, `ServerEvent`, views, settings). - `issues.ts`: issue conventions (`swarm:` labels, `Depends on #N`, hold-up ranking). -Client (`client/`, Vite root; React 19, R3F, drei, zustand): -- `src/world/`: the 3D building: floors, desks, characters (`appearance.ts`, `characterParts.ts`), elevator, - whiteboard, player movement and collisions (`layout.ts`), canvas textures (`draw.ts`), `toys/` (Rapier physics: the dart board, its darts and the chalk tally; rules in `dartboard.ts`), `nav.ts` (grid pathfinding), `dungeon.ts` (the plan: hall, gallery, chambers), `models.tsx` (glTF models in - `client/public/models`, built from the CC0 Quaternius packs by `scripts/build-models.py`), `stone.ts` (tiling stone - materials), `lightPool.tsx` (torches register as anchors; a fixed pool of point lights follows the nearest). -- `src/ui/`: HTML overlays: HUD, terminal (`LiveTerminal.tsx`: xterm.js on `/ws/term`), Kanban, manager's console, - phone, elevator panel, app - viewer, sounds (`sfx.ts`). -- `src/store.ts`: the zustand store; `apply(ServerEvent)` folds websocket events into UI state. -- `src/api.ts`: REST calls; errors become toasts. -- `src/net.ts`: the websocket connection with reconnect. `src/perf.tsx`: render pausing, adaptive DPR, `?stats`. ## Conventions diff --git a/client/CLAUDE.md b/client/CLAUDE.md new file mode 100644 index 0000000..ab0699a --- /dev/null +++ b/client/CLAUDE.md @@ -0,0 +1,15 @@ +# Client code map + +Loaded when working under `client/`. The rest of the rules are in the root CLAUDE.md. + +Client (`client/`, Vite root; React 19, R3F, drei, zustand): +- `src/world/`: the 3D building: floors, desks, characters (`appearance.ts`, `characterParts.ts`), elevator, + whiteboard, player movement and collisions (`layout.ts`), canvas textures (`draw.ts`), `toys/` (Rapier physics: the dart board, its darts and the chalk tally; rules in `dartboard.ts`), `nav.ts` (grid pathfinding), `dungeon.ts` (the plan: hall, gallery, chambers), `models.tsx` (glTF models in + `client/public/models`, built from the CC0 Quaternius packs by `scripts/build-models.py`), `stone.ts` (tiling stone + materials), `lightPool.tsx` (torches register as anchors; a fixed pool of point lights follows the nearest). +- `src/ui/`: HTML overlays: HUD, terminal (`LiveTerminal.tsx`: xterm.js on `/ws/term`), Kanban, manager's console, + phone, elevator panel, app + viewer, sounds (`sfx.ts`). +- `src/store.ts`: the zustand store; `apply(ServerEvent)` folds websocket events into UI state. +- `src/api.ts`: REST calls; errors become toasts. +- `src/net.ts`: the websocket connection with reconnect. `src/perf.tsx`: render pausing, adaptive DPR, `?stats`. diff --git a/package-lock.json b/package-lock.json index 010267e..8ad3790 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "codedungeon", - "version": "0.22.2", + "version": "0.22.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "codedungeon", - "version": "0.22.2", + "version": "0.22.3", "license": "MIT", "dependencies": { "@anthropic-ai/claude-agent-sdk": "^0.3.291", diff --git a/package.json b/package.json index 9842707..4feee58 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codedungeon", - "version": "0.22.2", + "version": "0.22.3", "description": "A medieval dungeon you walk through, where every coder is a real AI coding agent working through your GitHub issues.", "keywords": [ "claude-code", diff --git a/server/CLAUDE.md b/server/CLAUDE.md new file mode 100644 index 0000000..9b52b4f --- /dev/null +++ b/server/CLAUDE.md @@ -0,0 +1,43 @@ +# Server code map + +Loaded when working under `server/`. The rest of the rules are in the root CLAUDE.md. + +Server (`server/`, Node + Express 5 + ws, run by tsx in development; esbuild bundles it into `dist-server/` for npm): +- `index.ts`: entry; picks the real or demo backend, REST routes under `/api`, the `/ws` and `/ws/term` websockets, serves `dist/`, shutdown. +- `config.ts`: `SWARM_PORT` (default 4417), `SWARM_HOME` (default `codedungeon-home` beside the repo), `--demo`, state file, intervals, + the default projects folder. +- `swarm.ts`: the orchestrator. Floors, agents, scheduling/auto-assign, dev → QA → fix → merge loop, dev and QA + prompts, CEO job queue, phone messages, persistence (`state.json` / `demo-state.json`), websocket fan-out. +- `agentRunner.ts`: one Agent SDK session; options, env stripping, Playwright MCP, and turning the SDK stream into + terminal lines. +- `cliRunner.ts`: the terminal runtime (the default): one agent as the real CLI in a node-pty, same session contract + as `agentRunner.ts`. Claude Code reports through HTTP hooks (`POST /api/hooks/:token`; PreToolUse approves every + call); Codex reports turn endings (notify) and, once the manager trusts them, its steps (`-c hooks.*`); OpenCode + only turn endings. Codex/OpenCode screenshots are collected from the session's Playwright output folder. Esc in a + terminal ends the session as `interrupted`. The CEO's office tools are served over MCP (`/api/mcp/:token`). +- `ptyHost.ts`: the terminal keeper, a detached process of its own (`launch` re-spawns it outside the office's process + tree) holding the CLIs' pseudo-terminals and relaying their hooks, so agents keep working through office restarts. + `ptyClient.ts` is the office's side (start/connect, spawn, adopt after a restart, local fallback); `ptyProtocol.ts` + their JSON-lines messages. The launcher's `office:shutdown` says `restart: false` when quitting: CLIs stop then. + A developer's CLI stays at its prompt after the task (`keepAlive`): follow-ups and prompts typed there reuse it. +- `boxes.ts`, `boxRunner.ts`: coders in Upstash Boxes (`@upstash/box`). `boxes.ts` is the box layer: the API key and + GitHub token (env or the Windows user environment), the base snapshot (`BASE_SETUP`), desk and sign-in scripts, and + the events program every hook and status line runs in a box. `boxRunner.ts`'s `BoxPty` implements `Pty` for a CLI + in tmux in the box: `tmux attach` over a PTY session (reconnects with backoff), events followed with `tail -F`. + `shared/cloudBoxes.ts` holds the settings and who may move into a box. Testers stay local. +- `clis.ts`: the CLIs (Claude Code from the SDK's bundled binary, Codex, OpenCode): detection, Windows `.cmd` shim + unwrapping, each one's command line, and the helper scripts they call back with. +- `terminal.ts`: `AgentTerminal`, a headless xterm mirror per agent (replay for late viewers, saved to disk), its + `/ws/term` viewers, and keystrokes/resizes to the running CLI. +- `ceo.ts`: the CEO's office MCP tools (`createOfficeTools`, zod-validated), `ceoSystemPrompt`, `ceoJobPrompt`. +- `backend.ts`: the `Backend` interface (everything touching GitHub, git, disk and sessions) and `realBackend`. +- `demo.ts`: `createDemoBackend()`: fake GitHub, fake sessions (drawn into the agent's terminal in the terminal runtime), fake previews for `--demo`. +- `github.ts`: all GitHub access through the `gh` CLI. +- `workspace.ts`: floor checkouts, per-agent worktrees (`/workspaces/__/desks/`), + fast-forwarding main, per-repo git lock, stopping processes an agent left running. +- `exec.ts`: `run` / `git` / `gh`: `execFile` without a shell, prompts disabled, `CommandError` with stderr. +- `previews.ts`: one preview per floor: ports (6300 + floor), statuses, config validation. +- `previewRunner.ts`: checks out, installs and runs a floor's app in its preview worktree; kills the process tree. +- `httpError.ts`: `HttpError(status, message)`. +- `officeUpdate.ts`: the office's self-update: the drain decision, the launcher contract (IPC, `last-update.json`). +- `pacing.ts`: pacing new work after Claude's usage warnings: the start/skip decision and the usage state.