finfocus

Repository Guidelines

Table of Contents:

• Project Snapshot
• Build, Lint, and Test Commands
• Go Formatting and Imports
• Types, Naming, and API Surface
• Error Handling and Control Flow
• Logging Expectations
• Testing Guidelines
• Testify Assertions (Required)
• Documentation and Markdown
• Commit and PR Guidance
• Security and Configuration
• Common Workflows
• Current Stack
• Cursor/Copilot Rules
• Active Technologies
• Recent Changes

Project Snapshot

• Go CLI for finfocus in cmd/finfocus with unexported logic in internal/.
• Fixtures live in examples/, testdata/, and test/e2e/fixtures/.
• Docs are in docs/; scripts in scripts/; build artifacts in bin/.

Build, Lint, and Test Commands

• make tools: Install the toolchain pinned in mise.toml (single source of truth for tool versions; run mise install directly if preferred).
• make build: Build the finfocus binary into bin/ with version metadata.
• make run / make dev: Build then run the CLI; make inspect launches MCP inspector.
• make test | make test-race: Run unit tests (optionally with race detector).
• go test ./...: Run the full Go test suite.
• go test -run TestName ./path/to/package: Run a single test in one package.
• go test -v ./... -run TestFunc: Run a single test across all packages.
• make lint: Run golangci-lint v2.13.2 plus markdownlint.
• make validate: Run go mod tidy -diff and go vet checks.
• make docs-lint: Lint docs when editing Markdown.

Go Formatting and Imports

• Go 1.27.3+; use tabs for indentation and run gofmt on Go files.
• Imports grouped as: standard library, third-party, internal packages.
• goimports/golines enforced via golangci-lint; keep lines tidy.
• Avoid init() and global variables (lint rule).
• //nolint:lintername only when required and with justification.

Types, Naming, and API Surface

• Package names lowercase and short (engine, config, pluginhost).
• Custom domain types preferred (type Duration time.Duration).
• Exported identifiers require Go doc comments when part of CLI surface.
• Struct tags use JSON/YAML tags (yaml:"field_name").
• CLI flags are kebab-case; env/config keys uppercase snake (FINFOCUS_*).
• Define interfaces before implementations; keep interfaces small.
• Pass context.Context through request lifecycles.

Error Handling and Control Flow

• Wrap errors with %w: fmt.Errorf("operation failed: %w", err).
• Sentinel errors are var ErrName = errors.New("description").
• Validate inputs early and return descriptive errors.
• Prefer early returns to reduce nesting.
• Use context cancellation and return partial results where sensible.

Logging Expectations

• Use internal/logging for structured logging.
• Fetch logger from context: log := logging.FromContext(ctx).
• Include component and operation fields for traceability.
• Use Debug for detailed flow, Info for milestones, Warn for recoverable issues.

Testing Guidelines

• Table-driven tests with clear wantErr / errContains fields.
• Test both success and failure paths, especially file I/O and validation.
• Use fixtures from testdata/ or examples/ over large literals.
• Use integration tests in examples/ for HTTP/CRUD flows.
• Plugins: add conformance coverage in internal/conformance and targeted tests in internal/engine or internal/registry.

Testify Assertions (Required)

CRITICAL: All Go tests must use testify/assert and testify/require.

Required imports:

import (
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

Use require.* for setup failures and nil checks, assert.* for value comparisons.

Documentation and Markdown

• Docs use frontmatter with title, description, and layout.
• Frontmatter title is the H1; content must start with H2 or body text.
• Run make docs-lint after Markdown edits.
• markdownlint runs as part of make lint.

Commit and PR Guidance

• Conventional Commits required (feat:, fix:, chore:...).
• PRs include summary, linked issues, and a test plan (e.g., make test).
• Avoid bundling unrelated changes; call out breaking changes.
• Run make lint and make test before committing.

Security and Configuration

• Never commit secrets; use FINFOCUS_PLUGIN_* env vars or ~/.finfocus/config.yaml.
• Plugins live in ~/.finfocus/plugins/<name>/<version>/.
• Validate plugins with finfocus plugin validate and finfocus plugin certify.
• Scrub Pulumi plan fixtures if identifiers appear.

Common Workflows

Adding Resource Types

1. Declare a resource type in internal/engine/types.go.
2. Implement validation in the resource's Validate() method.
3. Provide pricing data in specs/ or via plugin support.
4. Create unit tests in internal/engine/types_test.go.
5. Create integration tests in internal/conformance/.

User-Facing CLI Features

• Constitution Principle VII (Web Parity): the spec has a Web UI Fit section, an internal/webui hook that calls the CLI's Go method is part of the feature, and a UX-only web-ui follow-up issue is filed on completion. A feature with no web surface records Not applicable and a reason instead.
• Layout: docs/src/content/docs/architecture/web-ui.md.

Plugin Development

• finfocus plugin init scaffolds new plugins.
• Implement the protocol from finfocus-spec.
• Install to ~/.finfocus/plugins/<name>/<version>/.

Current Stack

• Go 1.27.1 with github.com/Masterminds/semver/v3 and finfocus plugin SDK.
• charmbracelet/lipgloss v1.0.0 and golang.org/x/term v0.37.0.
• Tool versions (Go, golangci-lint, node, markdownlint, actionlint, shellcheck, govulncheck, specify-cli) are pinned in mise.toml; run make tools to install.
• Plugin directory: ~/.finfocus/plugins/<plugin-name>/<version>/.

Cursor/Copilot Rules

• No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md found.

Active Technologies

• 631-carbon-plugin (implemented): Go 1.27.1, finfocus-spec v0.7.6, static CCF data, and generic carbon enrichment.
• Go 1.27.1 + finfocus-spec SDK, Cobra CLI, zerolog, gRPC, pluginsdk (001-plugin-init-recorder)
• Local filesystem for fixture downloads and recorded request output (001-plugin-init-recorder)

Recent Changes

• 001-plugin-init-recorder: Added Go 1.27.1 + finfocus-spec SDK, Cobra CLI, zerolog, gRPC, pluginsdk