This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
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.
These rules apply every time code is changed in this repository.
-
When starting a new PR, automatically:
- Fetch and check out the latest
main:git fetch origin && git checkout main && git pull origin main - 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.
- Fetch and check out the latest
-
After every code change, run
task lintto auto-format the code before considering the work done. -
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 orgit add -f'd — it must not appear in any PR or in this public repository. -
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
-
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
-
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.
-
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 underdocs/commands/— its example block, its flag table, and any nearby explanatory text. Pick the file by stack:Stack File block nodedocs/commands/block-node.mdnetwork firewalldocs/commands/network/firewall.mdnetwork policydocs/commands/network/policy.mdnetwork shapedocs/commands/network/shape.mdalloyandesodocs/commands/alloy.mdkube cluster,teleport,daemon service,consensus migration soak,versionthe matching section of docs/commands/README.mdroot persistent flags docs/reference/global-flags.mdconfig file / env vars / proxy docs/reference/configuration.mdAlso update the quick reference card in
docs/commands/README.mdwhen a subcommand is added or renamed. Only touchdocs/quickstart.mdif 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 incmd/cli/commands/common/flags_common.goand the--helpoutput. CLI surface changes that miss this step ship docs that drift out of date. -
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 incmd/cli/commands/root.goRegisterMigrations()) 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.
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>.pyTemplate 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>.pyas the script path — never write the.pyhelper inside the repository tree, where it could be staged and committed by mistake.
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- Unit tests: tagged
!integration— run withgo 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
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:statusfor VM lifecycle management.
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.
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.
Key packages:
internal/workflows/— Multi-phase orchestration (preflight → setup → deploy → verify) using the automa framework. Workflow steps live ininternal/workflows/steps/. Notification helpers live ininternal/workflows/notify/.internal/migration/— Scoped migration framework (startup migrations run before every CLI invocation; block-node migrations run during upgrades). Seedocs/dev/migration-framework.md.internal/state/— Application state management (cluster state, software state, atomic writes)internal/blocknode/— Block node provisioning logic and storage migrationsinternal/kube/— Kubernetes client and admin operationsinternal/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 renderinginternal/doctor/— Error handling, diagnostics, and styled CLI outputinternal/mount/— Linux-only mount operations (build-taggedlinux)internal/network/— Network configurationinternal/nio/— Network I/O utilities (stdout/stderr wrappers)internal/paths/— Path management utilitiesinternal/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 managementinternal/templates/— Embedded template files (alloy, block-node, cilium, crio, health, kubeadm, metallb, sysctl, teleport)internal/tomlx/— TOML extension utilitiesinternal/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)
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 managementpkg/exit/— Exit code handlingpkg/hardware/— Hardware specs, validation, and requirementspkg/os/— OS operations (signals, swap, systemd)pkg/sanity/— Sanity/domain checkspkg/semver/— Semantic versioning utilitiespkg/version/— Version printing
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.
Uses github.com/automa-saga/logx (zerolog-based). Trace IDs are initialized in main.go and propagated via context.
Detailed framework docs live in docs/dev/:
error-handling.md—errorx+errxcontract: reason codes, hints, typed errorssecurity-model.md— Trust boundaries and sandbox binary risksmigration-framework.md— Migration system design and usagefunctionality-test-suite.md— Testing approach and patternsacceptance-tests.md— Acceptance/UAT test patternsgolden-image.md— VM golden image setuphidden-flags.md— Undocumented/hidden flags referenceeffective-value-resolution.md— Flag and config value resolutionlabel_profiles.md— Deployment profile label conventionsproxy.md— HTTP proxy configuration and activationtui-output.md— TUI output modes and formattingtui-workflow-mapping.md— Mapping of workflow steps to TUI messagestraffic-shaper.md— Block-node traffic-shaper/firewall files, systemd units, and boot persistence
- All dependencies are vendored in
/vendor— rungo mod vendorafter updatinggo.mod - Builds produce two binaries at
bin/solo-provisioner-{OS}-{ARCH}(CLI) andbin/solo-provisioner-daemon-{OS}-{ARCH}(daemon);task buildproduces both. The top-leveltask hash/task signaggregators cover both binaries (they fan out to the per-binaryhash:cli:all/hash:daemon:allandsign:cli:all/sign:daemon:alltasks) - The daemon is built before the CLI, and its SHA-256 is stamped into the CLI at link time (
-X …/pkg/software.pinnedDaemonDigest, seebuild:cliintaskfiles/cli.yaml). That digest is what the CLI's daemon auto-download verifies against, sobuild:clideclaresbuild:daemonas a dep andtask buildcalls onlybuild:cli:all.task signends withverify: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.releasercand.github/workflows/flow-deploy-release-artifact.yaml. Each release attaches all CLI and daemon artifacts (binary,.sha256, and.ascGPG signatures) so CLIvX.Y.Zand daemonvX.Y.Zalways ship together at the same version. - Version/commit are stamped into
github.com/automa-saga/versionat link time via-ldflags(see theLDFLAGSvar inTaskfile.yaml); shared code reads the running binary's version through that package. Override withVERSION=ontask build/hash/sign(defaults to0.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 viaerrx.Decorate(err, reasons.X, "step", ...)on the error passed toautoma.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 getreasons.Internaland no hints - seedocs/dev/error-handling.md - Decorate only where an error crosses a package boundary — an exported
errorreturn, aStepFailureReport, or aRunEreturn. Errors staying inside a package keep a plainerrorx.<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-inerrorx.<Type>and let the reason code classify. If a caller must branch on one exact error, declare it aserrorx.<Builtin>.NewSubtype("…")— a fresh namespace silently changes the operator-visible error code. - Render errors on human surfaces through
doctor.OperatorMessage, noterr.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/kubeclient, injected askube.ClientProviderFromContext— passkube.ClientFromContextat 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 (seedocs/dev/security-model.md). Follow thestep_cluster_*pattern: take a provider, resolve the client once inExecute, and read via a named helper