mcr/PROGRESS.md

MCR Development Progress

Reverse-chronological log of development work. Most recent entries first. See PROJECT_PLAN.md for the implementation roadmap and ARCHITECTURE.md for the full design specification.

Current State

Phase: 1 complete, ready for Batch A (Phase 2 + Phase 3) Last updated: 2026-03-19

Completed

• Phase 0: Project scaffolding (all 4 steps)
• Phase 1: Configuration & database (all 3 steps)
• ARCHITECTURE.md — Full design specification (18 sections)
• CLAUDE.md — AI development guidance
• PROJECT_PLAN.md — Implementation plan (14 phases, 40+ steps)
• PROGRESS.md — This file

Next Steps

1. Begin Batch A: Phase 2 (blob storage) and Phase 3 (MCIAS auth) in parallel — these are independent
2. After both complete, proceed to Phase 4 (policy engine)

---

Log

2026-03-19 — Phase 1: Configuration & database

Task: Implement TOML config loading with env overrides and validation, SQLite database with migrations, and audit log helpers.

Changes:

Step 1.1 — internal/config/:

• config.go: Config struct matching ARCHITECTURE.md §10 (all 6 TOML sections: server, database, storage, mcias, web, log)
• Parsed with go-toml/v2; env overrides via MCR_ prefix using reflection-based struct walker
• Startup validation: 6 required fields checked (listen_addr, tls_cert, tls_key, database.path, storage.layers_path, mcias.server_url)
• Same-filesystem check for layers_path/uploads_path via device ID comparison (walks to nearest existing parent if path doesn't exist yet)
• Default values: read_timeout=30s, write_timeout=0, idle_timeout=120s, shutdown_timeout=60s, uploads_path derived from layers_path, log.level=info
• device_linux.go: Linux-specific extractDeviceID using syscall.Stat_t
• deploy/examples/mcr.toml: annotated example config

Step 1.2 — internal/db/:

• db.go: Open(path) creates/opens SQLite via modernc.org/sqlite, sets pragmas (WAL, foreign_keys, busy_timeout=5000), chmod 0600
• migrate.go: migration framework with schema_migrations tracking table; Migrate() applies pending migrations in transactions; SchemaVersion() reports current version
• Migration 000001: repositories, manifests, tags, blobs, manifest_blobs, uploads — all tables, constraints, and indexes per ARCHITECTURE.md §8
• Migration 000002: policy_rules, audit_log — tables and indexes per §8

Step 1.3 — internal/db/:

• audit.go: WriteAuditEvent(eventType, actorID, repository, digest, ip, details) with JSON-serialized details map; ListAuditEvents(AuditFilter) with filtering by event_type, actor_id, repository, time range, and offset/limit pagination (default 50, descending by event_time)
• AuditFilter struct with all filter fields
• AuditEvent struct with JSON tags for API serialization

Lint fix:

• .golangci.yaml: disabled fieldalignment analyzer in govet (micro- optimization that hurts struct readability; not a security/correctness concern)

Verification:

• make all passes: vet clean, lint 0 issues, 20 tests passing (7 config + 13 db/audit), all 3 binaries built
• Config tests: valid load, defaults applied, uploads_path default, 5 missing-required-field cases, env override (string + duration), same-filesystem check
• DB tests: open+migrate, idempotent migrate, 9 tables verified, foreign key enforcement, tag cascade on manifest delete, manifest_blobs cascade (blob row preserved), WAL mode verified
• Audit tests: write+list, filter by type, filter by actor, filter by repository, pagination (3 pages), null fields handled

---

2026-03-19 — Phase 0: Project scaffolding

Task: Set up Go module, build system, linter config, and binary entry points with cobra subcommands.

Changes:

• go.mod: module git.wntrmute.dev/kyle/mcr, Go 1.25, cobra dependency
• Directory skeleton: cmd/mcrsrv/, cmd/mcr-web/, cmd/mcrctl/, internal/, proto/mcr/v1/, gen/mcr/v1/, web/templates/, web/static/, deploy/docker/, deploy/examples/, deploy/scripts/, deploy/systemd/, docs/
• .gitignore: binaries, srv/, *.db*, IDE/OS files
• Makefile: standard targets (all, build, test, vet, lint, proto, proto-lint, clean, docker, devserver); all runs vet → lint → test → mcrsrv mcr-web mcrctl; CGO_ENABLED=0 on binary builds; version injection via -X main.version
• .golangci.yaml: golangci-lint v2 config matching mc-proxy conventions; linters: errcheck, govet, ineffassign, unused, errorlint, gosec, staticcheck, revive; formatters: gofmt, goimports; gosec G101 excluded in test files
• buf.yaml: protobuf linting (STANDARD) and breaking change detection (FILE)
• cmd/mcrsrv/main.go: root command with server, init, snapshot subcommands (stubs returning "not implemented")
• cmd/mcr-web/main.go: root command with server subcommand (stub)
• cmd/mcrctl/main.go: root command with status, repo (list/delete), gc (trigger/status), policy (list/create/update/delete), audit (tail), snapshot subcommands (stubs)
• All binaries accept --version flag

Verification:

• make all passes: vet clean, lint 0 issues, test (no test files), all three binaries built successfully
• ./mcrsrv --version → mcrsrv version 3695581
• ./mcr-web --version → mcr-web version 3695581
• All stubs return "not implemented" error as expected
• make clean removes binaries

---

2026-03-19 — Project planning

Task: Create design documents and implementation plan.

Changes:

• README.md: Existing one-line description
• ARCHITECTURE.md: Full design specification covering OCI Distribution Spec compliance, MCIAS authentication, policy engine, storage design, API surface (OCI + admin REST + gRPC), database schema, garbage collection, configuration, web UI, CLI tools, deployment, security model
• CLAUDE.md: Development guidance for AI-assisted implementation
• PROJECT_PLAN.md: 14-phase implementation plan with discrete steps, acceptance criteria, dependency graph, and batchable work identification
• PROGRESS.md: This progress tracker

Notes:

• No code written yet. All files are documentation/planning.
• ARCHITECTURE.md reviewed and corrected for: GC algorithm crash safety, policy glob semantics, tag FK cascade, OCI error format, API sync violations, timeout configuration, backup considerations, and other consistency issues.