mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-05 06:59:42 +02:00
101 lines
3.1 KiB
Markdown
101 lines
3.1 KiB
Markdown
# Contributing to Codeman
|
|
|
|
## Prerequisites
|
|
|
|
- **Node.js 22** (use `nvm use` — `.nvmrc` is included)
|
|
- **tmux** — required for session management
|
|
- **Claude CLI** — installed and accessible in `$PATH`
|
|
|
|
## First-Time Setup
|
|
|
|
```bash
|
|
# 1. Clone and enter the repo
|
|
git clone https://github.com/Ark0N/Codeman.git
|
|
cd Codeman
|
|
|
|
# 2. Pin Node version
|
|
nvm use
|
|
|
|
# 3. Install dependencies (also links packages/xterm-zerolag-input workspace)
|
|
npm install
|
|
|
|
# 4. Start the dev server
|
|
npm run dev
|
|
# Open http://localhost:3000
|
|
```
|
|
|
|
## Development Commands
|
|
|
|
| Command | Purpose |
|
|
|---------|---------|
|
|
| `npm run dev` | Dev server at localhost:3000 |
|
|
| `npm run typecheck` | TypeScript type check |
|
|
| `npm run lint` | ESLint |
|
|
| `npm run lint:fix` | Auto-fix lint issues |
|
|
| `npm run format` | Prettier format |
|
|
| `npm run format:check` | Check formatting (used in CI) |
|
|
| `npm run build` | Production build |
|
|
| `npm run clean` | Remove dist/ |
|
|
|
|
## Running Tests Safely
|
|
|
|
> **CRITICAL:** If you are running inside a Codeman-managed tmux session, **never** run the full test suite — it spawns and kills tmux sessions and will crash your own session.
|
|
|
|
```bash
|
|
# Safe: run a single test file
|
|
npx vitest run test/<file>.test.ts
|
|
|
|
# Safe: run tests matching a name pattern
|
|
npx vitest run -t "pattern"
|
|
|
|
# DANGEROUS — only run outside of Codeman:
|
|
# npx vitest run
|
|
```
|
|
|
|
Test files use unique ports starting at 3150. Search `const PORT =` before adding a new test file.
|
|
|
|
## Code Style
|
|
|
|
- **TypeScript strict mode** — all strict flags are enabled in `tsconfig.json`. Code must pass `npm run typecheck` with zero errors.
|
|
- **ESLint** — run `npm run lint` before submitting a PR. Use `npm run lint:fix` for auto-fixable issues.
|
|
- **Prettier** — run `npm run format` to format source files. CI enforces `format:check`.
|
|
- **Import conventions:**
|
|
- Utilities: `import { LRUMap, stripAnsi } from './utils'`
|
|
- Types: `import type { SessionState } from './types'`
|
|
- Config: `import { MAX_TERMINAL_BUFFER_SIZE } from './config/buffer-limits'`
|
|
|
|
## Architecture Quick Reference
|
|
|
|
| Concern | File |
|
|
|---------|------|
|
|
| Session/PTY | `src/session.ts` |
|
|
| Web server (~105 routes) | `src/web/server.ts` |
|
|
| All TypeScript types | `src/types.ts` |
|
|
| Frontend (vanilla JS) | `src/web/public/app.js` |
|
|
| Respawn state machine | `src/respawn-controller.ts` |
|
|
| Task/Ralph loop | `src/ralph-loop.ts`, `src/ralph-tracker.ts` |
|
|
|
|
See `CLAUDE.md` for the full architecture reference.
|
|
|
|
## PR Checklist
|
|
|
|
- [ ] `npm run typecheck` passes
|
|
- [ ] `npm run lint` passes (or issues are documented)
|
|
- [ ] `npm run format:check` passes
|
|
- [ ] Relevant test file updated or added
|
|
- [ ] No full test suite run inside a Codeman session
|
|
- [ ] tmux safety respected (no blind `tmux kill-session`)
|
|
|
|
## Repository Layout
|
|
|
|
```
|
|
src/ TypeScript source
|
|
test/ Vitest tests (run individually)
|
|
scripts/ Build and utility scripts
|
|
packages/ Local npm workspaces (xterm-zerolag-input)
|
|
tools/ Dev utilities (Remotion video generation)
|
|
docs/ Architecture docs and planning documents
|
|
mobile-test/ Playwright mobile test suite
|
|
agent-teams/ Agent Teams feature docs
|
|
```
|