# MCDSL — Metacircular Dynamics Standard Library

MCDSL is a shared Go library for Metacircular Dynamics services. It extracts
the common patterns that every service implements independently — MCIAS
authentication, SQLite database setup, TLS server bootstrapping, CSRF
protection, configuration loading, and service data snapshots — into a single,
tested, reusable module.

## Why

Every Metacircular service follows the same patterns (see
`engineering-standards.md`). Today, each service copy-pastes these patterns
into its own `internal/` packages. This means:

- Bug fixes must be applied N times (once per service).
- Subtle divergences accumulate (e.g., CSRF tokens use base64 in one service,
  hex in another; auth cache keys are `[32]byte` in some, hex strings in
  others).
- New services require copying and adapting boilerplate from an existing
  service.

MCDSL extracts the 95%+ identical code into a shared library. Services import
it and provide only their service-specific logic.

## Module Path

```
git.wntrmute.dev/kyle/mcdsl
```

## Packages

| Package | Purpose |
|---------|---------|
| `auth` | MCIAS token validation with 30-second SHA-256 cache |
| `db` | SQLite connection setup (WAL, FK, busy timeout), migration runner, VACUUM INTO snapshots |
| `config` | TOML config loading with environment variable overrides, standard section types |
| `httpserver` | TLS 1.3 HTTP server setup with chi, graceful shutdown, logging middleware |
| `grpcserver` | gRPC server setup with TLS, interceptor chain helpers, method map auth |
| `csrf` | HMAC-SHA256 double-submit cookie CSRF protection |
| `web` | Session cookie management, template rendering helpers, auth middleware |
| `archive` | tar.zst service directory snapshot and restore with SQLite-aware handling |
| `health` | Standard health check implementation (gRPC Health/v1 + REST) |

## Quick Start

```go
import (
    "git.wntrmute.dev/kyle/mcdsl/auth"
    "git.wntrmute.dev/kyle/mcdsl/db"
    "git.wntrmute.dev/kyle/mcdsl/config"
    "git.wntrmute.dev/kyle/mcdsl/httpserver"
)

// Load config with standard sections + service-specific fields.
type MyConfig struct {
    config.Base
    MyService MyServiceConfig `toml:"my_service"`
}

cfg, err := config.Load[MyConfig]("my-service.toml", "MYSERVICE")

// Open database with standard pragmas and run migrations.
database, err := db.Open(cfg.Database.Path)
migrations := []db.Migration{
    {Version: 1, Name: "initial schema", SQL: `CREATE TABLE ...`},
}
db.Migrate(database, migrations)

// Set up MCIAS authentication with token caching.
mcauth, err := auth.New(cfg.MCIAS)

// Start TLS server with standard middleware.
srv := httpserver.New(cfg.Server, logger)
srv.Route(func(r chi.Router) {
    r.Use(srv.LoggingMiddleware)
    // register routes...
})
srv.ListenAndServeTLS()
```

## Build and Test

```bash
go build ./...
go test ./...
go vet ./...
golangci-lint run ./...
```

## Documentation

- [ARCHITECTURE.md](ARCHITECTURE.md) — full library specification
- [PROJECT_PLAN.md](PROJECT_PLAN.md) — implementation phases
- [PROGRESS.md](PROGRESS.md) — development status
- [../engineering-standards.md](../engineering-standards.md) — platform-wide standards