From 8910f742e8d4b45e7545ac338397ab4c0807f6a1 Mon Sep 17 00:00:00 2001 From: Snider Date: Fri, 13 Mar 2026 13:38:01 +0000 Subject: [PATCH] docs: add CLAUDE.md project instructions Co-Authored-By: Virgil --- CLAUDE.md | 46 +++++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 05c8f5d..bce9c76 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,34 +1,42 @@ # CLAUDE.md -## Project Overview +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -`core/go-container` provides container runtime management, LinuxKit image building, and portable dev environments. Three packages: root (container runtime + LinuxKit), devenv (dev environment orchestration), sources (image download from CDN/GitHub). - -## Build & Development +## Build & Test ```bash -go test ./... -go test -race ./... +go test ./... # all tests +go test -race ./... # with race detector +go test -run TestState_Add_Good ./... # single test by name +go test ./sources/ # single package +go test ./devenv/ # single package ``` +No build step required -- this is a library. The `cmd/vm/` package registers CLI commands via `init()` into the parent `core/cli` binary. + +**Go workspace**: This module is part of a Go workspace (`~/Code/go.work`). Sibling modules (`go-io`, `go-config`, `go-i18n`, `cli`) are resolved via the workspace file during local development. + ## Architecture -Three packages: +Three packages with a clear dependency direction: `devenv` -> `container` (root) -> `sources`. -- Root (`container`) — Container lifecycle (start/stop/status), hypervisor abstraction (QEMU/Hyperkit), LinuxKit YAML config builder with embedded templates, state persistence -- `devenv/` — Dev environment management: config loading, image management, shell access, test runner, serve mode, Claude integration. Depends on container/ and sources/ -- `sources/` — Image download sources: CDN and GitHub release fetchers with checksum verification +- **Root (`container`)** -- Container lifecycle (`Manager` interface, `LinuxKitManager` implementation), hypervisor abstraction (`Hypervisor` interface with QEMU and Hyperkit implementations), JSON-persisted state (`~/.core/containers.json`), and LinuxKit template engine with embedded YAML templates and `${VAR:-default}` variable substitution. -## Dependencies +- **`devenv/`** -- `DevOps` orchestrator composing container and sources into a dev environment workflow: boot/stop/status, SSH shell and serial console access, project mounting via reverse SSHFS at `/app`, auto-detection of serve/test commands by project type, and sandboxed Claude sessions with auth forwarding. -- `go-io` — File/process utilities -- `go-config` — Configuration loading (devenv only) -- `testify` — Test assertions +- **`sources/`** -- `ImageSource` interface with CDN (HTTP GET) and GitHub (`gh release download`) implementations. `ImageManager` in devenv maintains a manifest tracking installed versions. + +## Key Patterns + +- **`io.Medium` abstraction** -- File system operations use `io.Medium` (from `go-io`) rather than `os` directly. Use `io.Local` for real file access. This enables test mocking. +- **Compile-time interface checks** -- `var _ Interface = (*Impl)(nil)` (see `sources/cdn.go`, `sources/github.go`). +- **Copy-on-read state** -- `State.Get()` and `State.All()` return copies to prevent data races. +- **All persistent data** lives under `~/.core/` (containers.json, logs, images, config.yaml, known_hosts, linuxkit templates). `CORE_IMAGES_DIR` env var overrides the images directory. ## Coding Standards -- UK English -- All functions have typed params/returns -- Tests use testify -- Test naming: `_Good`, `_Bad`, `_Ugly` suffixes -- License: EUPL-1.2 +- UK English (colour, organisation, honour) +- Tests use testify; naming convention: `_Good` (happy path), `_Bad` (expected errors), `_Ugly` (edge cases) +- Error wrapping: `fmt.Errorf("context: %w", err)` +- Context propagation: all blocking operations take `context.Context` as first parameter +- Licence: EUPL-1.2