Skip to content

Commit 9c79b16

Browse files
JacobCoffeeclaude
JacobCoffee
and
claude
authored
refactor: migrate from npm+prettier to bun+biome (#121)
Co-authored-by: Claude <[email protected]>
1 parent 4bf179e commit 9c79b16

File tree

12 files changed

+1294
-1292
lines changed

12 files changed

+1294
-1292
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,11 @@ repos:
3737
rev: 1.20.0
3838
hooks:
3939
- id: blacken-docs
40-
- repo: https://github.com/pre-commit/mirrors-prettier
41-
rev: v4.0.0-alpha.8
40+
- repo: https://github.com/biomejs/pre-commit
41+
rev: "v0.4.0"
4242
hooks:
43-
- id: prettier
44-
exclude: "_templates|.git"
43+
- id: biome-check
44+
additional_dependencies: ["@biomejs/[email protected]"]
4545
# - repo: https://github.com/thibaudcolas/curlylint
4646
# rev: v0.13.1
4747
# hooks:

‎.prettierrc‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎CLAUDE.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
# Byte Bot - Development Guide
2+
3+
> **Version**: 0.3.0 (Phase 2 - Microservices) **Python**: 3.13 **Architecture**: Microservices (uv workspace)
4+
> **Updated**: 2025-11-23
5+
6+
---
7+
8+
## ⚡ Critical Rules
9+
10+
1. **NEVER work on main branch** - Always use feature branches via `git worktree` but using `make worktree` command from
11+
makefile!
12+
2. **ALWAYS ensure you write tests** for changes!
13+
3. **ALWAYS run `make ci`** before committing - Must pass (lint + type-check + fmt + test)
14+
4. **ALWAYS use `uv run`** for Python - Never call `python`/`python3` directly
15+
5. **ALWAYS update docs/** for user-facing changes - Sphinx RST format
16+
6. **ALWAYS create atomic commits** - Small, focused, reviewable
17+
7. **Use prek, not pre-commit** - Git hooks configured with prek
18+
8. **Dispatch subagents for complex tasks** - `ui-engineer`, `python-backend`, `software-architect`,
19+
`documentation-expert`
20+
21+
- Ready-to-use .env is at /Users/coffee/git/public/JacobCoffee/byte/ with loaded values.
22+
- `make worktree` automatically copies `.claude/settings.local.json` and `.env` to new worktrees.
23+
24+
---
25+
26+
## 🏗️ Architecture (Post-Phase 2)
27+
28+
**uv Workspace** with 3 members:
29+
30+
```
31+
workspace root (pyproject.toml)
32+
├── packages/byte-common # Shared models, schemas, utils
33+
├── services/api # Litestar REST API + web dashboard
34+
└── services/bot # discord.py bot
35+
```
36+
37+
**Runtime**:
38+
39+
- **Docker Compose** (recommended): All services + PostgreSQL in containers
40+
- **Local**: Services run separately, PostgreSQL in Docker via `make infra-up`
41+
42+
**Communication**:
43+
44+
- Bot → API via HTTP (`byte_bot/api_client.py`)
45+
- API → PostgreSQL (direct SQLAlchemy)
46+
- Shared code via `byte-common` package
47+
48+
---
49+
50+
## 🚀 Quick Start Commands
51+
52+
### Setup
53+
54+
```bash
55+
# Full install (backend + frontend + prek hooks)
56+
make install
57+
58+
# Docker development (PRIMARY workflow)
59+
make docker-up # Start all services
60+
make docker-logs # Follow logs
61+
make docker-down # Stop all services
62+
```
63+
64+
### Development
65+
66+
```bash
67+
# Local development (alternative)
68+
make infra-up # Start PostgreSQL only
69+
make run-dev-server # Terminal 1: Litestar API (hot-reload)
70+
make run-dev-bot # Terminal 2: Discord bot
71+
make run-dev-frontend # Terminal 3: TailwindCSS watcher
72+
73+
# Quality checks (MUST PASS before commit)
74+
make ci # Run all checks
75+
76+
# Individual checks
77+
make lint # prek hooks (ruff + codespell)
78+
make fmt # Ruff format
79+
make type-check # ty type checker
80+
make test # pytest with coverage
81+
```
82+
83+
### Database
84+
85+
```bash
86+
# Migrations (from services/api/)
87+
cd services/api
88+
uv run alembic revision --autogenerate -m "description"
89+
make migrate # Apply migrations
90+
91+
# Container management
92+
make refresh-container # Wipe DB, migrate, load test data
93+
```
94+
95+
### Docker Utilities
96+
97+
```bash
98+
make docker-rebuild # Force rebuild all services
99+
make docker-shell-api # Enter API container shell
100+
make docker-shell-bot # Enter bot container shell
101+
make docker-shell-postgres # PostgreSQL shell
102+
```
103+
104+
---
105+
106+
## 📁 Project Structure (Essential Paths)
107+
108+
```
109+
byte/
110+
├── pyproject.toml # Workspace root config
111+
├── Makefile # Primary automation (280 lines)
112+
├── docker-compose.yml # Development environment
113+
│
114+
├── packages/byte-common/ # Shared package
115+
│ ├── src/byte_common/
116+
│ │ ├── models/ # SQLAlchemy ORM models
117+
│ │ ├── schemas/ # Pydantic API schemas
118+
│ │ └── utils.py
119+
│ └── pyproject.toml
120+
│
121+
├── services/api/ # Litestar web service
122+
│ ├── src/byte_api/
123+
│ │ ├── app.py # create_app() factory
124+
│ │ ├── domain/ # Business logic (guilds, github, system, web)
125+
│ │ └── lib/ # Infrastructure (db, settings, openapi, etc.)
126+
│ │ └── db/migrations/ # Alembic migrations
127+
│ ├── Dockerfile
128+
│ └── pyproject.toml
129+
│
130+
├── services/bot/ # Discord bot service
131+
│ ├── src/byte_bot/
132+
│ │ ├── bot.py # Bot class, run_bot()
133+
│ │ ├── api_client.py # HTTP client to API service
134+
│ │ ├── plugins/ # Discord commands (auto-loaded)
135+
│ │ └── views/ # Discord UI components
136+
│ ├── Dockerfile
137+
│ └── pyproject.toml
138+
│
139+
├── tests/ # Integration + unit tests
140+
├── docs/ # Sphinx documentation (RST)
141+
│ └── conf.py
142+
└── worktrees/ # Git worktrees (keep in repo)
143+
```
144+
145+
---
146+
147+
## 🔧 Technology Stack
148+
149+
| Component | Tool | Notes |
150+
| ------------------------ | --------------------------------- | ------------------------------------- |
151+
| **Package Manager (PY)** | uv | Fast, PEP 517 build backend |
152+
| **Package Manager (JS)** | bun | Fast JavaScript runtime & package manager |
153+
| **Linting (Python)** | ruff | Replaces black, flake8, isort |
154+
| **Linting (JS/TS)** | Biome | Fast formatter & linter (replaces Prettier) |
155+
| **Type Checking** | ty | Type checks all services and packages |
156+
| **Testing** | pytest + pytest-asyncio | Coverage required |
157+
| **Git Hooks** | prek | NOT pre-commit |
158+
| **Web Framework** | Litestar 2.4.3+ | ASGI, OpenAPI, Jinja2 |
159+
| **Discord Bot** | discord.py 2.3.2+ | Slash commands, views |
160+
| **ORM** | SQLAlchemy 2.0 + Advanced Alchemy | Async, repository pattern |
161+
| **Database** | PostgreSQL 15+ | Via Docker or Railway |
162+
| **Frontend** | TailwindCSS + DaisyUI | Compiled via separate watcher |
163+
164+
**Documentation**: Sphinx, Context7 MCP, allowed WebFetch domains:
165+
166+
- `docs.astral.sh` (uv docs)
167+
- `docs.litestar.dev` (Litestar framework)
168+
- `discordpy.readthedocs.io` (discord.py)
169+
170+
---
171+
172+
## 🔄 Git Workflow
173+
174+
### Branching with Worktrees (REQUIRED for parallel work)
175+
176+
```bash
177+
# Create feature branch in worktree (automated)
178+
make worktree
179+
# OR manually:
180+
git checkout main && git pull
181+
git worktree add worktrees/feature-name -b feature/feature-name
182+
183+
# Work in worktree
184+
cd worktrees/feature-name
185+
# ... make atomic commits ...
186+
187+
# Cleanup after merge
188+
cd ../..
189+
git worktree remove worktrees/feature-name
190+
191+
# Clean up stale worktrees
192+
make worktree-prune
193+
# OR: git worktree prune -v
194+
```
195+
196+
### Commit Standards
197+
198+
- **Atomic commits**: One logical change per commit
199+
- **Conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, etc.
200+
- **Examples**:
201+
- ✅ `feat: add guild caching to API client`
202+
- ✅ `fix: handle missing Discord token gracefully`
203+
- ❌ `feat: complete Phase 3 migration` (too large)
204+
205+
### PR Workflow
206+
207+
```bash
208+
# Ensure CI passes locally
209+
make ci
210+
211+
# Create PR via gh CLI
212+
gh pr create --title "feat: description" --body "..."
213+
214+
# Check PR status
215+
gh pr checks
216+
```
217+
218+
---
219+
220+
## 🐛 Common Issues
221+
222+
| Issue | Solution |
223+
| -------------------------------- | -------------------------------------------------------------- |
224+
| **Bot not responding** | Check `DISCORD_TOKEN`, `DISCORD_DEV_GUILD_ID` in `.env` |
225+
| **Import errors** | Run `uv sync` to install dependencies |
226+
| **Database connection errors** | Ensure PostgreSQL running: `make infra-up` or `make docker-up` |
227+
| **Migrations failing** | Check DB connection, try `make refresh-container` |
228+
| **Frontend styles not updating** | Restart `make run-dev-frontend` watcher |
229+
| **Docker build fails** | Try `make docker-rebuild` |
230+
231+
---
232+
233+
## 📝 Development Patterns
234+
235+
### Environment Variables
236+
237+
Key variables in `.env`:
238+
239+
- `DISCORD_TOKEN` - Bot token from Discord Developer Portal
240+
- `DB_URL` - PostgreSQL connection (format: `postgresql+asyncpg://user:pass@host:port/db`)
241+
- `SECRET_KEY` - API secret for JWT/sessions
242+
- `GITHUB_APP_*` - GitHub App credentials (ID, private key, client ID/secret)
243+
244+
### Code Style (Enforced by `make ci`)
245+
246+
- **Line length**: 120 characters
247+
- **Type hints**: Required (modern union syntax: `str | None`)
248+
- **Docstrings**: Google style (enforced by ruff)
249+
- **Async**: Use `async`/`await` (SQLAlchemy 2.0 async mode)
250+
251+
### Testing
252+
253+
```python
254+
# Tests in tests/ directory
255+
# Markers: @pytest.mark.unit, @pytest.mark.integration
256+
# Async tests: @pytest.mark.asyncio (auto-enabled)
257+
```
258+
259+
### Database Models
260+
261+
- **Location**: `packages/byte-common/src/byte_common/models/`
262+
- **Migrations**: `cd services/api && uv run alembic revision --autogenerate -m "msg"`
263+
- **Apply**: `make migrate`
264+
265+
### Bot Plugins
266+
267+
- **Location**: `services/bot/src/byte_bot/plugins/`
268+
- **Auto-loaded**: Place `*.py` files, add `def setup(bot)` function
269+
- **Example**: See `plugins/admin.py`, `plugins/github.py`
270+
271+
---
272+
273+
## 🤖 Subagent Coordination
274+
275+
When dispatching subagents:
276+
277+
1. **Create separate worktrees** for each agent
278+
2. **Assign clear boundaries** (files/modules)
279+
3. **Coordinate via git commits** (atomic, descriptive)
280+
4. **Merge incrementally** (review each commit)
281+
282+
**Available agents**:
283+
284+
- `ui-engineer` - Frontend, TailwindCSS, Jinja2 templates
285+
- `python-backend` - API, database, business logic
286+
- `software-architect` - System design, refactoring
287+
- `documentation-expert` - Sphinx docs, API references, tutorials
288+
289+
---
290+
291+
## 📚 Resources
292+
293+
- **Project Docs**: `docs/` (Sphinx RST format)
294+
- **Docker Guide**: `docs/docker-setup.md`
295+
- **API Docs**: http://localhost:8000/api/swagger (when running)
296+
- **External**:
297+
- discord.py: https://discordpy.readthedocs.io/
298+
- Litestar: https://docs.litestar.dev/
299+
- uv: https://docs.astral.sh/uv/
300+
301+
---
302+
303+
**Repository**: https://github.com/JacobCoffee/byte

0 commit comments

Comments
 (0)