Skip to content

Latest commit

 

History

History
268 lines (208 loc) · 17.7 KB

CLAUDE.md

File metadata and controls

268 lines (208 loc) · 17.7 KB

CLAUDE.md

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

Project Overview

solo-weaver (binary: solo-provisioner) is a Go-based CLI for automating Kubernetes deployment of Hedera network components (block nodes, alloy clusters). It helps node operators migrate from traditional deployment to containerized infrastructure.

Workflow Reminders

These rules apply every time code is changed in this repository.

  1. When starting a new PR, automatically:

    1. Fetch and check out the latest main: git fetch origin && git checkout main && git pull origin main
    2. Create and switch to a new branch named <issue_number>-<short-description> where <issue_number> is zero-padded to 5 digits (e.g. issue 123 → 00123-fix-block-node-crash): git checkout -b <issue_number>-<short-description>
    • Ask the user for the GitHub issue number and a short description (kebab-case) if they haven't provided them.
  2. After every code change, run task lint to auto-format the code before considering the work done.

  3. After finishing implementation, generate a review guide at docs/claude/reviews/<issue_number>-<short-description>.md (e.g. docs/claude/reviews/00477-fix-metallb-annotation-on-upgrade.md) that includes:

    • A short summary of the problem and solution
    • A table of changed files with a one-line description each
    • A code review checklist (one bullet per key invariant to verify)
    • Commands to run unit and integration tests for the changed code
    • Step-by-step manual UAT instructions (with expected output snippets)

    This guide is for local use only. The docs/claude/ folder is gitignored (.gitignore), so the guide stays on your machine and must never be committed or git add -f'd — it must not appear in any PR or in this public repository.

  4. Every commit must use a Conventional Commits subject line (e.g. feat(scope): ..., fix(scope): ..., refactor(scope): ...) and be created with both -s (sign-off) and -S (GPG sign) flags:

    git commit -sS -m "type(scope): short description"
    # or for multiline messages:
    git commit -sS -F /tmp/commit-msg.txt
  5. Before creating a new commit, check whether the change logically belongs to an existing unpushed commit on the branch (git log --oneline origin/<base>..HEAD). If it does, amend that commit instead of adding a new one:

    git add <files>
    git commit --amend -sS --no-edit   # keep message, or drop --no-edit to reword
    # if the target is not HEAD, use interactive rebase:
    git rebase -i origin/<base>        # mark the target commit as 'edit', then amend
  6. Before committing or pushing, always show the full commit message and the list of files to be committed/pushed, and wait for explicit user approval before proceeding.

  7. When you add, rename, remove, or change the semantics of a CLI flag or subcommand (under cmd/cli/commands/...), also update the command's guide under docs/commands/ — its example block, its flag table, and any nearby explanatory text. Pick the file by stack:

    Stack File
    block node docs/commands/block-node.md
    network firewall docs/commands/network/firewall.md
    network policy docs/commands/network/policy.md
    network shape docs/commands/network/shape.md
    alloy and eso docs/commands/alloy.md
    kube cluster, teleport, daemon service, consensus migration soak, version the matching section of docs/commands/README.md
    root persistent flags docs/reference/global-flags.md
    config file / env vars / proxy docs/reference/configuration.md

    Also update the quick reference card in docs/commands/README.md when a subcommand is added or renamed. Only touch docs/quickstart.md if the change affects the zero-to-running-block-node path — it is a short onboarding doc, not a flag reference, and must stay under ~200 lines. Flag descriptions must match the description string in cmd/cli/commands/common/flags_common.go and the --help output. CLI surface changes that miss this step ship docs that drift out of date.

  8. When you change an embedded template or any config consumed at install time (e.g. internal/templates/files/**), trace the existing-cluster upgrade path before assuming the change is fresh-install-only. Startup migrations (internal/workflows/migration_*.go, registered in cmd/cli/commands/root.go RegisterMigrations()) run on every CLI invocation and, when crossing their version boundary, re-render the entire template and re-apply it (e.g. software.ReconfigureCiliumConfig() + cilium upgrade --values). That means a template edit you intended only for new installs can leak into already-provisioned clusters that cross such a boundary. Confirm whether that application is intended, and call out any unintended/early application in the PR's Risks section.

Writing Markdown Files

Never use shell heredocs to write .md files. The terminal mangles backticks, special characters, and indented content inside heredocs, producing corrupt output.

Instead, always write markdown via a temporary Python script placed under /tmp so it is never accidentally committed:

# 1. Create the script with the tool (create_file), writing to /tmp/write_<name>.py
# 2. Execute it:
python3 /tmp/write_<name>.py

Template for the script:

lines = [
    "# Heading\n",
    "\n",
    "Normal paragraph.\n",
    "\n",
    "```bash\n",
    "some command\n",
    "```\n",
]
with open("/path/to/file.md", "w") as f:
    f.writelines(lines)
print("done")

Use a lines list of strings (each ending with \n) rather than a single triple-quoted string — this avoids any escaping issues with backticks or backslashes inside the content.

Always use /tmp/write_<name>.py as the script path — never write the .py helper inside the repository tree, where it could be staged and committed by mistake.

Build & Development Commands

This project uses Task as the build system. All commands run via task.

# Build for current platform
task build:cli GOOS=linux GOARCH=amd64

# Build all platforms
task build

# Run unit tests
task test:unit

# Run unit tests with verbose console output
task test:unit:verbose

# Run a single integration test
task test:integration:verbose TEST_NAME='^Test_StepKubeadm_Fresh_Integration$'

# Run with coverage for specific paths
task test:coverage TEST_PATHS=./pkg/software/... TEST_REGEX="."

# Lint (format check)
task lint:check

# Auto-format
task lint

# Check license headers
task license:check

# Regenerate mocks
task mocks

# Clean build artifacts
task clean

Test Tags

  • Unit tests: tagged !integration — run with go test -race -cover -tags='!integration' ./internal/... ./pkg/... ./cmd/...
  • Integration tests: tagged integration — require a running environment
  • Cluster-dependent tests: tagged require_cluster — require a Kubernetes cluster
  • Integration test files follow the naming convention *_it_test.go

Platform Constraints

Several packages (e.g. internal/mount) are Linux-only and will not compile on macOS. This means:

  • Unit tests must be run inside a UTM VM to get full coverage. Use task vm:test:unit.
  • Integration tests must always be run inside a UTM VM. Use:
# Run all integration tests in the UTM VM
task vm:test:integration

# Run a single integration test in the UTM VM
task vm:test:integration TEST_NAME='^Test_StepKubeadm_Fresh_Integration$'
  • On macOS you can still build and test packages that have no Linux-only dependencies (e.g. ./internal/migration/..., ./internal/state/..., ./pkg/...), but always validate the full suite in the VM before merging.
  • The VM is a UTM-managed Linux guest. See task vm:start, task vm:stop, task vm:status for VM lifecycle management.

Architecture

CLI Layer (cmd/cli/)

Entry point is cmd/cli/main.go, producing the solo-provisioner binary. Commands use Cobra organized hierarchically:

solo-provisioner
├── install              # Self-install the provisioner
├── uninstall            # Self-uninstall the provisioner
├── kube cluster         # Kubernetes cluster (install, uninstall)
├── block node           # Block node lifecycle (check, init, install, upgrade, reset, uninstall)
├── teleport             # Teleport integration
│   ├── node install     #   Install node-level teleport agent (SSH access)
│   ├── node uninstall   #   Uninstall node-level teleport agent
│   ├── cluster install  #   Install cluster-level teleport agent (kubectl access)
│   └── cluster uninstall#   Uninstall cluster-level teleport agent
├── alloy cluster        # Alloy observability cluster (install, uninstall)
├── version              # Print version information
└── (demo)               # TUI demo command (dev/debug use only)

Root persistent flags: --config, --output, --version/-v, --log-level, --force, --skip-hardware-checks (hidden), --verbose/-V (expanded step-by-step TUI output), --non-interactive.

Command-specific flags (on block, kube): --profile. Error control flags (on workflow commands like block node): --stop-on-error, --rollback-on-error, --continue-on-error.

Daemon Layer (cmd/daemon/)

Entry point is cmd/daemon/main.go, producing the standalone solo-provisioner-daemon binary. The daemon is a long-running process started by the solo-provisioner-daemon.service systemd unit; it has its own minimal Cobra root (no shared commands/ subtree with the CLI) and intentionally does not import any package under cmd/cli/. Logs to solo-provisioner-daemon.log. Persistent flags: --config, --log-level, --version/-v, --output/-o.

Business Logic (internal/)

Key packages:

  • internal/workflows/ — Multi-phase orchestration (preflight → setup → deploy → verify) using the automa framework. Workflow steps live in internal/workflows/steps/. Notification helpers live in internal/workflows/notify/.
  • internal/migration/ — Scoped migration framework (startup migrations run before every CLI invocation; block-node migrations run during upgrades). See docs/dev/migration-framework.md.
  • internal/state/ — Application state management (cluster state, software state, atomic writes)
  • internal/blocknode/ — Block node provisioning logic and storage migrations
  • internal/kube/ — Kubernetes client and admin operations
  • internal/bll/ — Business logic layer with subpackages: bll/blocknode/ (install, upgrade, reset, uninstall handlers), bll/cluster/ (cluster install handler), bll/teleport/ (node and cluster agent install/uninstall handlers)
  • internal/reality/ — Hardware detection/validation (machine, cluster, block node, teleport checkers)
  • internal/alloy/ — Grafana Alloy observability configuration and rendering
  • internal/doctor/ — Error handling, diagnostics, and styled CLI output
  • internal/mount/ — Linux-only mount operations (build-tagged linux)
  • internal/network/ — Network configuration
  • internal/nio/ — Network I/O utilities (stdout/stderr wrappers)
  • internal/paths/ — Path management utilities
  • internal/proxy/ — HTTP proxy activation from configuration (sets env vars for downstream tools)
  • internal/rsl/ — Runtime specification layer (machine, cluster, block node, teleport runtimes)
  • internal/sysctl/ — System control parameter management
  • internal/templates/ — Embedded template files (alloy, block-node, cilium, crio, health, kubeadm, metallb, sysctl, teleport)
  • internal/tomlx/ — TOML extension utilities
  • internal/ui/ — TUI rendering: verbose/non-interactive modes, console logging suppression, prompts (ui/prompt/), message models, and output capture (unix/windows)
  • internal/version/ — Version file management (VERSION, COMMIT)

Public Packages (pkg/)

Reusable packages with defined interfaces and generated mocks:

  • pkg/fsx/ — Filesystem abstraction (interface + mock for testing)
  • pkg/software/ — Software management (interface + mock)
  • pkg/kernel/ — Kernel management (interface + mock)
  • pkg/security/principal/ — Security/principal management (interface + mock)
  • pkg/helm/ — Helm chart operations (interface + mock)
  • pkg/config/ — Configuration models (parsed via Viper)
  • pkg/models/ — Shared data models (profiles, paths, inputs, execution modes)

Additional packages:

  • pkg/collections/ — Data structure utilities (pairs)
  • pkg/deps/ — Dependency management
  • pkg/exit/ — Exit code handling
  • pkg/hardware/ — Hardware specs, validation, and requirements
  • pkg/os/ — OS operations (signals, swap, systemd)
  • pkg/sanity/ — Sanity/domain checks
  • pkg/semver/ — Semantic versioning utilities
  • pkg/version/ — Version printing

Mocks

Mocks are generated with mockgen from interface files. When adding a new interface that needs mocking, add the mockgen invocation to the mocks task in Taskfile.yaml.

Logging

Uses github.com/automa-saga/logx (zerolog-based). Trace IDs are initialized in main.go and propagated via context.

Developer Documentation

Detailed framework docs live in docs/dev/:

  • error-handling.md — errorx + errx contract: reason codes, hints, typed errors
  • security-model.md — Trust boundaries and sandbox binary risks
  • migration-framework.md — Migration system design and usage
  • functionality-test-suite.md — Testing approach and patterns
  • acceptance-tests.md — Acceptance/UAT test patterns
  • golden-image.md — VM golden image setup
  • hidden-flags.md — Undocumented/hidden flags reference
  • effective-value-resolution.md — Flag and config value resolution
  • label_profiles.md — Deployment profile label conventions
  • proxy.md — HTTP proxy configuration and activation
  • tui-output.md — TUI output modes and formatting
  • tui-workflow-mapping.md — Mapping of workflow steps to TUI messages
  • traffic-shaper.md — Block-node traffic-shaper/firewall files, systemd units, and boot persistence

Key Conventions

  • All dependencies are vendored in /vendor — run go mod vendor after updating go.mod
  • Builds produce two binaries at bin/solo-provisioner-{OS}-{ARCH} (CLI) and bin/solo-provisioner-daemon-{OS}-{ARCH} (daemon); task build produces both. The top-level task hash / task sign aggregators cover both binaries (they fan out to the per-binary hash:cli:all/hash:daemon:all and sign:cli:all/sign:daemon:all tasks)
  • The daemon is built before the CLI, and its SHA-256 is stamped into the CLI at link time (-X …/pkg/software.pinnedDaemonDigest, see build:cli in taskfiles/cli.yaml). That digest is what the CLI's daemon auto-download verifies against, so build:cli declares build:daemon as a dep and task build calls only build:cli:all. task sign ends with verify:cli:all, which fails the release if any CLI does not carry the digest of the daemon beside it — never publish a CLI/daemon pair that has not passed it
  • Both binaries are released together by a single pipeline under one tag namespace vX.Y.Z, driven by .releaserc and .github/workflows/flow-deploy-release-artifact.yaml. Each release attaches all CLI and daemon artifacts (binary, .sha256, and .asc GPG signatures) so CLI vX.Y.Z and daemon vX.Y.Z always ship together at the same version.
  • Version/commit are stamped into github.com/automa-saga/version at link time via -ldflags (see the LDFLAGS var in Taskfile.yaml); shared code reads the running binary's version through that package. Override with VERSION= on task build/hash/sign (defaults to 0.0.0)
  • Deployment profiles: local, perfnet, testnet, previewnet, mainnet
  • PR titles must follow Conventional Commits
  • License headers (SPDX) are required on all source files — enforced by task license:check
  • New or changed automa.StepFailureReports attach a reason code and operator-actionable hints via errx.Decorate(err, reasons.X, "step", ...) on the error passed to automa.WithError(...). Hints are commands to run or paths to check; a report without them is as incomplete as one without a message — except internal bugs, which get reasons.Internal and no hints - see docs/dev/error-handling.md
  • Decorate only where an error crosses a package boundary — an exported error return, a StepFailureReport, or a RunE return. Errors staying inside a package keep a plain errorx.<Type>.Wrap; decorating every layer duplicates hints and overwrites the reason, since the outermost wins.
  • Don't declare new typed errors or errorx.NewNamespace. Use a built-in errorx.<Type> and let the reason code classify. If a caller must branch on one exact error, declare it as errorx.<Builtin>.NewSubtype("…") — a fresh namespace silently changes the operator-visible error code.
  • Render errors on human surfaces through doctor.OperatorMessage, not err.Error() — the latter carries the printable {reason: X}, which belongs in logs only.
  • Prefer pure-Go over shelling out to external binaries. Read cluster state through the Kubernetes API (internal/kube client, injected as kube.ClientProviderFromContext — pass kube.ClientFromContext at the call site) rather than execing tool binaries (cilium, kubectl, …) and parsing their stdout — running binaries from the sandbox bin dir is a malicious-binary risk (see docs/dev/security-model.md). Follow the step_cluster_* pattern: take a provider, resolve the client once in Execute, and read via a named helper