solo: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Solo (@hiero-ledger/solo) is a CLI tool for deploying and managing private Hedera Networks on Kubernetes. It orchestrates consensus nodes, mirror nodes, block explorers, and JSON-RPC relays via Helm charts and Kubernetes APIs.

• Language: TypeScript (ES2022, ESM)
• Runtime: Node.js >= 22.0.0
• CLI Framework: Yargs with Listr2 for task execution

Common Commands

All task commands use Task (task):

# Install dependencies
npm install

# Build (compile TypeScript + lint)
task build

# Compile only
task build:compile

# Build the SEA binary for the current platform (not part of task build)
task sea:build

# Run unit tests with coverage
task test

# Auto-fix lint/formatting issues (run before committing)
task format

# List all available tasks including E2E tests
task --list-all

# Run a specific E2E test suite
task test-e2e-integration
task test-e2e-standard

# Run solo via tsx (development mode, without building)
npm run solo-test -- <COMMAND> <ARGS>

To run a single unit test file directly:

npx mocha 'test/unit/path/to/test.ts'

Logs are written to $HOME/.solo/logs/solo.log. Tail with: tail -f $HOME/.solo/logs/solo.log | jq

Architecture

The codebase follows a layered, command-driven architecture with dependency injection (tsyringe-neo):

Entry point: solo.ts → ArgumentProcessor (Yargs) → Command Layer

Layer Overview

1. src/commands/ — 14 CLI commands (account, deployment, network, node, cluster, block-node, explorer, mirror-node, relay, one-shot, backup-restore, rapid-fire, file). Each command extends BaseCommand and implements command-specific workflows.

2. src/core/ — ~95 services: account-manager.ts, config-manager.ts, chart-manager.ts, key-manager.ts, lock/ (distributed leases), logging/ (Pino), dependency-managers/ (installation checks and dynamic command loading).