72 lines
2.2 KiB
Markdown
72 lines
2.2 KiB
Markdown
# AGENTS.md — Timmy Tower World
|
|
|
|
Development conventions and workflows for agents and contributors.
|
|
|
|
## One-time setup
|
|
|
|
```bash
|
|
make install
|
|
```
|
|
|
|
This activates git hooks that run `typecheck` and `lint` before every commit and push.
|
|
|
|
## Quality checks
|
|
|
|
```bash
|
|
pnpm run typecheck # TypeScript type-checking (tsc --build across all packages)
|
|
pnpm run lint # ESLint across all TypeScript source files
|
|
make check # Run both in sequence (same as CI)
|
|
```
|
|
|
|
## Pushing to Gitea
|
|
|
|
All pushes go through the bore tunnel helper script (see replit.md for full docs):
|
|
|
|
```bash
|
|
bash scripts/push-to-gitea.sh [PORT]
|
|
```
|
|
|
|
- First call after bore starts: pass the port once — it's saved for the session
|
|
- Subsequent calls: no argument needed, reads from `.bore-port`
|
|
- Bore port changes every restart — pass the new port to update
|
|
|
|
Set `GITEA_TOKEN` or write the token to `.gitea-credentials` (gitignored). Never commit credentials.
|
|
|
|
## Branch and PR conventions
|
|
|
|
- **Never push directly to `main`** — Gitea enforces branch protection
|
|
- Every change lives on a feature branch: `feat/<slug>`, `fix/<slug>`, `chore/<slug>`
|
|
- Open a PR on Gitea and squash-merge after review
|
|
- CI runs `pnpm typecheck && pnpm lint` on every PR automatically
|
|
|
|
## Stub mode
|
|
|
|
The API server starts without Lightning or AI credentials:
|
|
|
|
- **LNbits stub**: invoices are simulated in-memory. Mark paid via `POST /api/dev/stub/pay/:hash`
|
|
- **AI stub**: Anthropic credentials absent → canned AI responses. Set `AI_INTEGRATIONS_ANTHROPIC_API_KEY` for real AI
|
|
|
|
## Workspace structure
|
|
|
|
```
|
|
artifacts/api-server/ — Express 5 API server (@workspace/api-server)
|
|
lib/db/ — Drizzle ORM schema + PostgreSQL client (@workspace/db)
|
|
lib/api-spec/ — OpenAPI spec + Orval codegen
|
|
lib/api-zod/ — Generated Zod schemas (do not edit by hand)
|
|
lib/api-client-react/ — Generated React Query hooks (do not edit by hand)
|
|
scripts/ — Utility scripts (@workspace/scripts)
|
|
```
|
|
|
|
## Running the API server
|
|
|
|
```bash
|
|
pnpm --filter @workspace/api-server run dev
|
|
```
|
|
|
|
## Gitea repos
|
|
|
|
| Repo | Purpose |
|
|
|---|---|
|
|
| `replit/token-gated-economy` | This repo — TypeScript API |
|
|
| `perplexity/the-matrix` | Three.js 3D world frontend |
|