mcdsl/CLAUDE.md

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

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:

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:

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)