97 lines
3.7 KiB
Markdown
97 lines
3.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
MCDSL (Metacircular Dynamics Standard Library) is the shared Go library for the Metacircular platform. It extracts common patterns from production services into reusable, tested packages. MCDSL is not a deployed service — it is imported by other services.
|
|
|
|
**Module path:** `git.wntrmute.dev/kyle/mcdsl`
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
make all # vet -> lint -> test -> build
|
|
make build # go build ./...
|
|
make test # go test ./...
|
|
make vet # go vet ./...
|
|
make lint # golangci-lint run ./...
|
|
make clean # go clean ./...
|
|
```
|
|
|
|
Run a single test:
|
|
```bash
|
|
go test ./auth/ -run TestCacheExpiry
|
|
```
|
|
|
|
## Packages
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| `auth` | MCIAS token validation with 30s SHA-256 cache |
|
|
| `db` | SQLite setup (WAL, foreign keys, busy timeout), migration runner, VACUUM INTO snapshots |
|
|
| `config` | TOML loading with env var overrides, Base config struct with standard sections |
|
|
| `httpserver` | TLS 1.3 HTTP server with chi, logging middleware, JSON helpers, graceful shutdown |
|
|
| `grpcserver` | gRPC server with TLS, auth/admin interceptors, default-deny for unmapped methods |
|
|
| `csrf` | HMAC-SHA256 double-submit cookie CSRF protection |
|
|
| `web` | Session cookies, auth middleware, template rendering for htmx UIs |
|
|
| `health` | REST and gRPC health check handlers |
|
|
| `archive` | tar.zst snapshots with SQLite-aware backup (VACUUM INTO) |
|
|
|
|
## Import Pattern
|
|
|
|
Services import individual packages with aliased imports:
|
|
|
|
```go
|
|
import (
|
|
mcdslauth "git.wntrmute.dev/kyle/mcdsl/auth"
|
|
mcdsldb "git.wntrmute.dev/kyle/mcdsl/db"
|
|
mcdslconfig "git.wntrmute.dev/kyle/mcdsl/config"
|
|
"git.wntrmute.dev/kyle/mcdsl/httpserver"
|
|
"git.wntrmute.dev/kyle/mcdsl/grpcserver"
|
|
)
|
|
```
|
|
|
|
## Inter-Package Dependencies
|
|
|
|
```
|
|
archive --> db
|
|
auth --> (mcias client library)
|
|
config --> auth (for auth.Config type)
|
|
csrf --> (stdlib only)
|
|
db --> (modernc.org/sqlite)
|
|
grpcserver --> auth, config
|
|
health --> db
|
|
httpserver --> config
|
|
web --> auth, csrf
|
|
```
|
|
|
|
No circular dependencies. Each package can be imported independently except where noted.
|
|
|
|
## Key Design Decisions
|
|
|
|
- **No global state, no init().** Explicit construction, explicit errors.
|
|
- **Stdlib-compatible types.** Functions accept and return `*sql.DB`, `http.Handler`, `*slog.Logger`, `context.Context` — not custom wrappers.
|
|
- **TLS 1.3 minimum is non-configurable.** `httpserver` and `grpcserver` enforce this unconditionally.
|
|
- **Default-deny for unmapped gRPC methods.** A method not in the MethodMap is rejected, not allowed. This is the most important safety property.
|
|
- **Cookie security flags are non-configurable.** Session cookies are always `HttpOnly`, `Secure`, `SameSite=Strict`.
|
|
- **Extract, don't invent.** Every package comes from patterns proven across multiple services. No speculative abstractions.
|
|
- **Optional composition.** Services import only the packages they need.
|
|
|
|
## Critical Rules
|
|
|
|
- No CGo — all builds use `CGO_ENABLED=0`, SQLite via `modernc.org/sqlite`
|
|
- Testing uses stdlib `testing` only, real SQLite in `t.TempDir()`, no mocks for databases
|
|
- Token cache keys are SHA-256 of the raw token (never use raw token as map key)
|
|
- CSRF secrets must come from `crypto/rand`, unique per service instance
|
|
- Database file permissions are always `0600`
|
|
- Verify changes with `go build ./...` and `go test ./...` before claiming resolution
|
|
|
|
## Key Documents
|
|
|
|
- `ARCHITECTURE.md` — Full library specification with all package APIs
|
|
- `README.md` — Usage examples and quick start
|
|
- `PROJECT_PLAN.md` — Implementation phases
|
|
- `PROGRESS.md` — Development status
|
|
- `../engineering-standards.md` — Platform-wide standards (authoritative reference)
|