finfocus-dev
FinFocus Core development workflow guide for contributors. Use when implementing features, fixing bugs, writing tests, running CI checks, or following project conventions in the finfocus Go codebase. Triggers on: adding CLI commands, writing Go tests, running make targets, debugg
Install
npx skills add https://github.com/rshade/finfocus/tree/main/.claude/skills/finfocus-dev/finfocus-dev
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rshade-finfocus@llmmart
git clone https://github.com/rshade/finfocus.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rshade/finfocus collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
FinFocus Development Workflow
Quick Reference
make build # Build binary to bin/finfocus
make test # Unit tests (fast, default)
make lint # golangci-lint + markdownlint (5+ min, use extended timeout)
make validate # go mod tidy + go vet
make test-race # Race detector
make test-integration # Cross-component tests (10min timeout)
make build-all # Build binary + all plugins
Critical rules: Always run make lint and make test before claiming success.
Never run git commit (user commits manually). Never modify .golangci.yml.
Adding a CLI Command
- Create
internal/cli/your_command.go - Follow constructor pattern:
func NewYourCmd() *cobra.Command {
var flagVar string
cmd := &cobra.Command{
Use: "your-command",
Short: "Description",
RunE: func(cmd *cobra.Command, args []string) error {
// Use cmd.Printf() not fmt.Printf()
return nil
},
}
cmd.Flags().StringVar(&flagVar, "flag", "", "description")
return cmd
}
- Register in parent command (e.g.,
root.goorcost.go) - Use
RunE(notRun) for error handling - Defer cleanup immediately:
defer cleanup()
Resource Processing Pipeline
All cost commands follow:
ingest.LoadPulumiPlan(path) -> ingest.MapResources() -> registry.Open(ctx, adapter)
-> engine.GetProjectedCost/GetActualCost() -> engine.RenderResults(format, results)
Testing Standards
- Use
testify/assertandtestify/requireexclusively (never manualif/t.Errorf) require.*for setup that must succeed;assert.*for value checks- Table-driven tests for variations
- Package suffix
_testfor black-box testing t.TempDir()for temporary files (auto-cleanup)- Capture output:
cmd.SetOut(&buf)andcmd.SetErr(&buf) - Target 80% coverage minimum, 95% for critical paths
See references/testing-patterns.md for detailed test patterns and examples.
Project Structure
See references/project-structure.md for the complete package map and key file locations.
Error Handling
- Wrap errors:
fmt.Errorf("context: %w", err) - Return early on errors
- Plugin failures don't stop processing (graceful degradation)
- Validation prefix:
"VALIDATION: %v", plugin error prefix:"ERROR:"
Logging (zerolog)
log := logging.FromContext(ctx)
log.Debug().Ctx(ctx).Str("component", "engine").Msg("message")
Standard fields: trace_id, component, operation, duration_ms.
Enable debug: --debug flag or FINFOCUS_LOG_LEVEL=debug.
Date Handling
Support both "2006-01-02" and RFC3339. Default --to to time.Now().
Validate ranges (to must be after from).
Output Formats
Three formats via --output flag: table (default), json, ndjson.
Always use cmd.Printf() for testability.
Files (finfocus)
-
references
-
project-structure.md 5 KB
Loading… -
testing-patterns.md 4.5 KB
Loading…
-
-
SKILL.md 3.3 KB
--- name: finfocus-dev description: > FinFocus Core development workflow guide for contributors. Use when implementing features, fixing bugs, writing tests, running CI checks, or following project conventions in the finfocus Go codebase. Triggers on: adding CLI commands, writing Go tests, running make targets, debugging CI failures, understanding project structure, or any Go development task within finfocus-core. --- # FinFocus Development Workflow ## Quick Reference ```bash make build # Build binary to bin/finfocus make test # Unit tests (fast, default) make lint # golangci-lint + markdownlint (5+ min, use extended timeout) make validate # go mod tidy + go vet make test-race # Race detector make test-integration # Cross-component tests (10min timeout) make build-all # Build binary + all plugins ``` **Critical rules**: Always run `make lint` and `make test` before claiming success. Never run `git commit` (user commits manually). Never modify `.golangci.yml`. ## Adding a CLI Command 1. Create `internal/cli/your_command.go` 1. Follow constructor pattern: ```go func NewYourCmd() *cobra.Command { var flagVar string cmd := &cobra.Command{ Use: "your-command", Short: "Description", RunE: func(cmd *cobra.Command, args []string) error { // Use cmd.Printf() not fmt.Printf() return nil }, } cmd.Flags().StringVar(&flagVar, "flag", "", "description") return cmd } ``` 1. Register in parent command (e.g., `root.go` or `cost.go`) 1. Use `RunE` (not `Run`) for error handling 1. Defer cleanup immediately: `defer cleanup()` ## Resource Processing Pipeline All cost commands follow: ```text ingest.LoadPulumiPlan(path) -> ingest.MapResources() -> registry.Open(ctx, adapter) -> engine.GetProjectedCost/GetActualCost() -> engine.RenderResults(format, results) ``` ## Testing Standards - Use `testify/assert` and `testify/require` exclusively (never manual `if/t.Errorf`) - `require.*` for setup that must succeed; `assert.*` for value checks - Table-driven tests for variations - Package suffix `_test` for black-box testing - `t.TempDir()` for temporary files (auto-cleanup) - Capture output: `cmd.SetOut(&buf)` and `cmd.SetErr(&buf)` - Target 80% coverage minimum, 95% for critical paths See [references/testing-patterns.md](references/testing-patterns.md) for detailed test patterns and examples. ## Project Structure See [references/project-structure.md](references/project-structure.md) for the complete package map and key file locations. ## Error Handling - Wrap errors: `fmt.Errorf("context: %w", err)` - Return early on errors - Plugin failures don't stop processing (graceful degradation) - Validation prefix: `"VALIDATION: %v"`, plugin error prefix: `"ERROR:"` ## Logging (zerolog) ```go log := logging.FromContext(ctx) log.Debug().Ctx(ctx).Str("component", "engine").Msg("message") ``` Standard fields: `trace_id`, `component`, `operation`, `duration_ms`. Enable debug: `--debug` flag or `FINFOCUS_LOG_LEVEL=debug`. ## Date Handling Support both `"2006-01-02"` and RFC3339. Default `--to` to `time.Now()`. Validate ranges (to must be after from). ## Output Formats Three formats via `--output` flag: `table` (default), `json`, `ndjson`. Always use `cmd.Printf()` for testability.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.