|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build & Run |
| 6 | + |
| 7 | +```bash |
| 8 | +# Build the binary (requires CGO for BLS crypto) |
| 9 | +CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" GO111MODULE=on go build -o ./cmd/flow/flow ./cmd/flow |
| 10 | + |
| 11 | +# Or use Make |
| 12 | +make binary |
| 13 | + |
| 14 | +# Run directly without building |
| 15 | +go run cmd/flow/main.go [command] |
| 16 | +``` |
| 17 | + |
| 18 | +## Testing |
| 19 | + |
| 20 | +```bash |
| 21 | +# Run all tests |
| 22 | +make test |
| 23 | +# Equivalent: CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" GO111MODULE=on go test -coverprofile=coverage.txt ./... |
| 24 | + |
| 25 | +# Run a single test package |
| 26 | +CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" go test ./internal/accounts/... |
| 27 | + |
| 28 | +# Run a specific test |
| 29 | +CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" go test ./internal/accounts/... -run TestFunctionName |
| 30 | + |
| 31 | +# Skip network-dependent tests (e.g. in sandboxed environments) |
| 32 | +SKIP_NETWORK_TESTS=1 make test |
| 33 | +``` |
| 34 | + |
| 35 | +## Linting |
| 36 | + |
| 37 | +```bash |
| 38 | +make lint # Run golangci-lint |
| 39 | +make fix-lint # Auto-fix lint issues |
| 40 | +make check-headers # Verify Apache license headers on all Go files |
| 41 | +go generate ./... # Regenerate generated code (required before lint) |
| 42 | +``` |
| 43 | + |
| 44 | +## Architecture |
| 45 | + |
| 46 | +The CLI is a [Cobra](https://github.com/spf13/cobra)-based application with three main layers: |
| 47 | + |
| 48 | +### Entry Point |
| 49 | +`cmd/flow/main.go` — wires all subcommands into the root `flow` command. |
| 50 | + |
| 51 | +### Command Framework (`internal/command/`) |
| 52 | +The `command.Command` struct wraps a `cobra.Command` with two execution modes: |
| 53 | +- `Run` — for commands that don't need a loaded `flow.json` state |
| 54 | +- `RunS` — for commands that require an initialized project state (`*flowkit.State`) |
| 55 | + |
| 56 | +`Command.AddToParent()` handles all shared boilerplate: loading `flow.json`, resolving network/host, creating the gRPC gateway, initializing `flowkit.Services`, version checking, analytics, and error formatting. **All new commands should use this pattern.** |
| 57 | + |
| 58 | +Every command's run function returns a `command.Result` interface with three output methods: `String()` (human-readable), `Oneliner()` (grep-friendly inline), and `JSON()` (structured). The framework handles `--output`, `--filter`, and `--save` flags automatically. |
| 59 | + |
| 60 | +### Command Packages (`internal/`) |
| 61 | +Each feature area is its own package with a top-level `Cmd *cobra.Command` that aggregates subcommands. Pattern: |
| 62 | +- `accounts.Cmd` (`internal/accounts/`) — registered in `main.go` via `cmd.AddCommand(accounts.Cmd)` |
| 63 | +- Subcommands (e.g., `get.go`, `create.go`) define a package-level `var getCommand = &command.Command{...}` and register via `init()` or the parent's `init()` |
| 64 | + |
| 65 | +Key packages: |
| 66 | +- `internal/super/` — high-level "super commands": `flow init`, `flow dev`, `flow generate`, `flow flix` |
| 67 | +- `internal/super/generator/` — code generation engine for Cadence contracts, scripts, transactions, and tests |
| 68 | +- `internal/dependencymanager/` — `flow deps` commands for managing on-chain contract dependencies |
| 69 | +- `internal/config/` — `flow config` subcommands for managing `flow.json` |
| 70 | +- `internal/emulator/` — wraps the Flow emulator |
| 71 | + |
| 72 | +### flowkit Dependency |
| 73 | +The CLI delegates all blockchain interactions to the `github.com/onflow/flowkit/v2` module (external). The `flowkit.Services` interface is the primary abstraction for network calls. The local `flowkit/` directory is a historical artifact (migrated to the external module) and contains only a README and schema. |
| 74 | + |
| 75 | +### Global Flags |
| 76 | +Defined in `internal/command/global_flags.go`, applied to every command: `--network`, `--host`, `--log`, `--output`, `--filter`, `--save`, `--config-path`, `--yes`, `--skip-version-check`. |
| 77 | + |
| 78 | +### Configuration |
| 79 | +`flow.json` is the project config file. `flowkit.Load()` reads it. The `internal/config/` commands modify it. `state.Networks()`, `state.Accounts()`, etc. provide typed access. |
| 80 | + |
| 81 | +## CLI Design Conventions |
| 82 | +- Commands follow `noun verb` pattern (`flow accounts get`) |
| 83 | +- Prefer flags over positional args; use args only for the primary required value |
| 84 | +- `--output json` must always work for machine-readable output |
| 85 | +- Errors go to stderr; normal output to stdout |
| 86 | +- Progress indicators for long-running operations via `logger.StartProgress()` / `logger.StopProgress()` |
| 87 | +- Long-running commands support `--yes` to skip confirmation prompts |
| 88 | + |
| 89 | +## License Headers |
| 90 | +All Go source files must have the Apache 2.0 license header. Run `make check-headers` to verify. |
0 commit comments