mcr/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCR (Metacircular Container Registry) is a container registry service integrated with MCIAS for authentication and authorization. It is part of the Metacircular Dynamics platform. See ARCHITECTURE.md for the full specification (must be written before implementation begins).

Priorities (in order): security, robustness, correctness.

Build Commands

make all          # vet → lint → test → build
make mcr          # build binary with version injection
make build        # compile all packages
make test         # run all tests
make vet          # go vet
make lint         # golangci-lint
make proto        # regenerate gRPC code from proto definitions
make proto-lint   # buf lint + breaking change detection
make devserver    # build and run locally with srv/mcr.toml
make clean        # remove built binaries
make docker       # build container image

Run a single test:

go test ./internal/server -run TestPushManifest

Tech Stack

• Language: Go 1.25+, CGO_ENABLED=0, statically linked
• Module path: git.wntrmute.dev/kyle/mcr
• Database: SQLite via modernc.org/sqlite (pure-Go, no CGo)
• Config: TOML via go-toml/v2, env overrides via MCR_*
• APIs: REST (chi) + gRPC (protobuf), kept in sync
• Web UI: Go html/template + htmx, embedded via //go:embed
• Auth: Delegated to MCIAS — no local user database
• Linting: golangci-lint v2 with .golangci.yaml
• Testing: stdlib testing only, real SQLite in t.TempDir()

Architecture

• REST and gRPC APIs over HTTPS/TLS 1.3 (minimum, no exceptions)
• SQLite with WAL mode, foreign_keys=ON, busy_timeout=5000
• Write-through pattern: gRPC mutations write to DB first, then update in-memory state
• Every REST endpoint must have a corresponding gRPC RPC, and vice versa
• gRPC interceptor maps (authRequiredMethods, adminRequiredMethods) enforce access control — adding an RPC without adding it to the correct maps is a security defect
• Web UI runs as a separate binary (mcr-web) that talks to the API server via gRPC — no direct DB access
• Runtime data in /srv/mcr/, never committed to the repo

Package Structure

• cmd/mcr/ — CLI entry point (cobra subcommands: server, init, status, snapshot)
• cmd/mcr-web/ — Web UI entry point
• internal/auth/ — MCIAS integration (token validation, 30s cache by SHA-256)
• internal/config/ — TOML config loading and validation
• internal/db/ — SQLite setup, migrations (idempotent, tracked in schema_migrations)
• internal/server/ — REST API server, chi routes, middleware
• internal/grpcserver/ — gRPC server, interceptors, service handlers
• internal/webserver/ — Web UI server, template routes, htmx handlers
• proto/mcr/v1/ — Protobuf definitions (source of truth)
• gen/mcr/v1/ — Generated gRPC code (never edit by hand)
• web/ — Templates and static files, embedded via //go:embed
• deploy/ — Docker, systemd units, install scripts, example config

Development Workflow

1. Check PROGRESS.md for current state and next steps (create it if it doesn't exist)
2. Design first — write or update ARCHITECTURE.md before implementing
3. Implement, test, lint, commit, update PROGRESS.md
4. Pre-push: make all must pass clean

Critical Rules

• API sync: every REST endpoint has a matching gRPC RPC, updated in the same change
• No local user database — all auth delegated to MCIAS
• Default deny — unauthenticated and unauthorized requests always rejected
• No custom crypto — use stdlib crypto/... or well-audited packages only
• TLS 1.3 minimum, no fallback ciphers
• Never log secrets (passwords, tokens, keys)
• Security-sensitive changes must include a Security: line in the commit body
• Migrations are idempotent and never modified after deployment
• Generated code in gen/ is never edited by hand
• Verify fixes by running go build ./... and go test ./... before claiming resolution

Key Documents

• ARCHITECTURE.md — Full system specification (required before implementation)
• PROJECT_PLAN.md — Implementation phases with acceptance criteria
• PROGRESS.md — Development progress tracking (update after each step)
• RUNBOOK.md — Operational procedures (to be written)
• ../engineering-standards.md — Platform-wide standards (authoritative reference)