Skip to content

Development Guide

Jump to bottom
Eshan Roy edited this page Jun 16, 2026 · 2 revisions

Development Guide

Prerequisites

  • Go 1.25+
  • Git
  • golangci-lint (for linting)
  • goreleaser (for releases, optional)

Building

# Clone the repository
git clone https://github.com/eshanized/M31A.git
cd M31A

# Build optimized binary
make build

# Build debug binary (with symbols)
make debug

# Build and run immediately
make dev

# Install to $GOBIN
make install

All builds use CGO_ENABLED=0 for static binaries. Version info is injected via ldflags:

var (
    Version = "dev"     // git describe --tags
    Commit  = "..."     // git rev-parse --short HEAD
    Date    = "..."     // date -u
)

Testing

# Run all tests with race detector and coverage
make test

# Run tests without race detector (faster)
make test-fast

# Run tests with verbose output
make test-verbose

# Run a specific test
make test-specific TEST=TestReplModel

# Run benchmarks
make bench

# Generate HTML coverage report
make cover

Coverage Targets

Package Target
Overall 75%
pkg/taskrunner 90%
pkg/bisect 90%
pkg/rollback 90%

Test Organization

Tests follow Go conventions with _test.go files alongside source files. Additional test patterns:

  • *_extra_test.go -- Extended test coverage beyond the primary test file
  • *_security_test.go -- Security-specific tests (SSRF, permissions, path traversal)
  • *_integration_test.go -- Cross-package integration tests
  • test_helpers_test.go -- Shared test utilities

Code Quality

# Run golangci-lint
make lint

# Run linter with auto-fix
make lint-fix

# Run go vet
make vet

# Format all Go files
make fmt

# Clean up go.mod
make tidy

# Run all checks (fmt + tidy + vet + test)
make check

Linter Configuration

Source: .golangci.yml

The project uses golangci-lint with a 5-minute timeout. Linting is run in CI on every push.

Cross-Compilation

# Build for all supported platforms
make cross

# Build for a specific platform
make build-linux-amd64
make build-darwin-arm64
make build-windows-amd64

Supported platforms:

  • Linux (amd64, arm64)
  • macOS (amd64, arm64)
  • Windows (amd64, arm64)

Releases

Releases use GoReleaser:

# Snapshot release (local testing)
make release

# Dry run
make release-dry

Source: .goreleaser.yaml

CI/CD

Source: .github/workflows/ci.yml

CI runs on every push and pull request:

  1. Go setup with module caching
  2. go vet ./...
  3. golangci-lint run
  4. go test -race -cover ./...

Dependabot

Source: .github/dependabot.yml

Automated dependency updates for Go modules and GitHub Actions.

Project Structure Conventions

Package Naming

  • internal/ packages are private (not importable by external projects)
  • pkg/ packages are public and importable
  • Each pkg/ package has a doc.go with package-level documentation

File Naming

  • *_unix.go / *_windows.go -- Platform-specific code using build tags
  • *_test.go -- Standard Go tests
  • *_extra_test.go -- Additional test coverage

Import Organization

import (
    // Standard library
    "context"
    "fmt"

    // Third-party
    "github.com/charmbracelet/bubbletea"

    // Internal packages
    "github.com/eshanized/M31A/internal/config"
    "github.com/eshanized/M31A/internal/types"

    // Public packages
    "github.com/eshanized/M31A/pkg/session"
)

Error Handling Patterns

  • Use sentinel errors from internal/errors/ for known failure modes
  • Wrap errors with context: fmt.Errorf("save checkpoint: %w", err)
  • Use UserMessage() for user-facing error display
  • Return toolResultError for soft tool errors, regular errors for hard failures

Concurrency Patterns

  • Bubble Tea's single-threaded Update() loop for TUI state
  • sync.RWMutex for provider registry and dispatcher
  • sync.Once for lazy initialization (codeintel, tool definitions)
  • atomic.Bool / atomic.Int64 for lock-free counters and guards
  • Channel-based communication between workflow engine and TUI

Contributing

See CONTRIBUTING.md for:

  • Code style guidelines
  • Architecture rules
  • PR conventions
  • Issue templates

Acceptance Tests

Source: scripts/verify_v1.sh

The acceptance test suite validates the full V1 feature set:

  • Build verification
  • Tool execution
  • Session persistence
  • Provider fallback
  • Workflow phases

Utilities

# Show binary size
make size

# Show version info
make version

# Update dependencies
make deps

# Verify dependency checksums
make deps-verify

# Remove build artifacts
make clean

# Clean everything (including module cache)
make nuke

Clone this wiki locally