Skip to content
jrschumacherPublic

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

30 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Adder

🐍 Documentation-driven CLI generator for Cobra based Go applications

Adder generates type-safe CLI commands from markdown documentation, providing a clean separation between command structure and business logic.

Test Lint Release Go Reference Go Report Card Release

✨ Features

  • πŸ“ Documentation-First - Commands defined in readable markdown
  • πŸ”’ Type-Safe - Compile-time validation and structured requests
  • πŸ—οΈ Clean Architecture - Separation of CLI structure and business logic
  • ⚑ Performance - No runtime parsing overhead
  • 🎯 Handler Interfaces - Easy testing and dependency injection
  • πŸ“ Organized Output - Preserves directory structure to avoid naming conflicts
  • βœ… Enhanced Validation - Markdown linter with strict type checking and enum validation
  • πŸ”Œ Request Interface - All generated requests implement adder.Request for consistency
  • πŸ›‘οΈ Centralized Enum Validation - Clean adder.ValidateEnum() function for runtime validation
  • πŸ§ͺ Comprehensive Testing - Unit, integration, golden file, and example tests
  • πŸš€ Production Ready - Full CI/CD pipeline with automated releases
  • πŸ”§ Self-Dogfooding - Adder generates its own CLI commands

πŸš€ Quick Start

1. Install

Via Go Install:

go install github.com/jrschumacher/adder/cmd/adder@latest

Via GitHub Releases:

# Download binary for your platform from:
# https://github.com/jrschumacher/adder/releases

2. Configure Project

Create .adder.yaml:

binary_name: myapp              # Required: name of your CLI binary
input: docs/commands            # Default: docs/commands  
output: generated               # Default: generated
package: generated              # Default: generated
suffix: _generated.go           # Default: _generated.go
package_strategy: directory     # Default: directory
index_format: directory         # Default: directory

3. Define Command

Create docs/commands/hello.md:

---
title: Say hello to someone
command:
  name: hello [name]
  arguments:
    - name: name
      description: Name of the person to greet
      required: true
      type: string
  flags:
    - name: capitalize
      description: Capitalize the greeting
      type: bool
---

# Say hello to someone

Greet someone with a friendly hello message.

4. Generate Code

adder generate
# Or with flags: adder generate -i docs/commands -o generated -p generated

5. Implement Handler

func (h *HelloHandler) HandleHello(cmd *cobra.Command, req *generated.HelloRequest) error {
    greeting := fmt.Sprintf("Hello, %s!", req.Arguments.Name)
    if req.Flags.Capitalize {
        greeting = strings.ToUpper(greeting)
    }
    fmt.Println(greeting)
    return nil
}

6. Wire It Up

handler := &HelloHandler{}
helloCmd := generated.NewHelloCommand(handler)
rootCmd.AddCommand(helloCmd)

πŸ—οΈ Generated Structure

Adder creates clean, type-safe structures:

// Separate arguments from flags for clarity
type HelloRequestArguments struct {
    Name string `json:"name" validate:"required"`
}

type HelloRequestFlags struct {
    Capitalize bool `json:"capitalize"`
    Style      string `json:"style" validate:"oneof=normal bold italic"`
}

// All requests implement adder.Request interface
type HelloRequest struct {
    Arguments    HelloRequestArguments `json:"arguments"`
    Flags        HelloRequestFlags     `json:"flags"`
    RawArguments []string              `json:"raw_arguments"`
}

// GetRawArguments implements adder.Request interface
func (r *HelloRequest) GetRawArguments() []string {
    return r.RawArguments
}

// Handler receives full command access
type HelloHandler func(cmd *cobra.Command, req *HelloRequest) error

// Clean enum validation in generated code
if err := adder.ValidateEnum("style", style, []string{"normal", "bold", "italic"}); err != nil {
    return err
}

πŸ“ Directory Organization

Adder preserves your documentation structure:

docs/man/              generated/
β”œβ”€β”€ auth/              β”œβ”€β”€ auth/
β”‚   └── login.md  β†’    β”‚   └── login_generated.go
└── policy/            └── policy/
    └── create.md  β†’       └── create_generated.go

This prevents naming conflicts between commands like auth create and policy create.

βš™οΈ Configuration

Create .adder.yaml in your project root:

# Required: Name of your CLI binary (used to detect root command)
binary_name: myapp

# Optional: Input/output directories (can be overridden with flags)
input: docs/commands
output: generated
package: generated
suffix: _generated.go

# Optional: Package naming strategy
package_strategy: directory  # single, directory, path

# Optional: Index file format for subcommands
index_format: directory      # directory, index, _index, hugo

Root Command Detection:

  • The parser looks for {binary_name}.md in the input directory
  • This file becomes your CLI's root command
  • Example: binary_name: myapp β†’ looks for myapp.md

βœ… Enhanced Validation

Adder acts as a comprehensive markdown linter, catching configuration errors early:

Type Consistency Validation

# ❌ This will fail validation
flags:
  - name: count
    type: int
    default: "not-a-number"  # Error: must be integer for type 'int'

# βœ… This is correct
flags:
  - name: count
    type: int
    default: 42

Enum Validation

# ❌ This will fail validation
flags:
  - name: level
    type: int                    # Error: enum only supported on string type
    enum: ["debug", "info"]

# ❌ This will also fail
flags:
  - name: level
    type: string
    enum: ["debug", "info"]
    default: "invalid"           # Error: default must be in enum values

# βœ… This is correct
flags:
  - name: level
    type: string
    enum: ["debug", "info", "warn"]
    default: "info"

Validation Commands

# Validate without generating
adder generate --validate

# Example validation errors
❌ Validation failed: flag count: default value must be an integer for type 'int', got 'not-a-number'
❌ Validation failed: flag level: enum validation only supported on string type, got 'int'
❌ Validation failed: flag level: default value 'invalid' must be one of: [debug info warn]

🎯 Key Benefits

Feature Benefit
Type Safety Compile-time validation prevents runtime errors
Documentation-First Single source of truth in readable format
Performance No runtime parsing of embedded docs
Clean Architecture Handler interfaces promote testability
Organized Output Directory structure prevents naming conflicts
Command Access Full *cobra.Command capabilities available

πŸ† Production Ready

Adder is built with production use in mind:

βœ… Quality Assurance

  • 19 Active Linters - golangci-lint with comprehensive checks
  • 4 Test Categories - Unit, integration, golden file, and example tests
  • 90%+ Test Coverage - Comprehensive test suite
  • Automated Quality Gates - CI/CD pipeline enforces standards

βœ… Reliability

  • Multi-Platform Support - Linux, macOS, Windows (AMD64 + ARM64)
  • Semantic Versioning - Automated releases with conventional commits
  • Backward Compatibility - Careful API evolution

βœ… Developer Experience

  • Self-Dogfooding - Tool generates its own CLI commands
  • Comprehensive Documentation - Examples, guides, and API reference
  • Local Development Tools - Makefile with all common tasks
  • IDE Integration - Works with any Go-compatible editor

πŸ§ͺ Testing

Adder includes comprehensive testing:

# Run all tests
make test

# Run with coverage
make test-coverage

# Run linting
make lint

# Run all CI checks locally
make ci-test

Test Categories:

  • Unit Tests - Core parser and generator logic
  • Integration Tests - CLI command testing
  • Golden File Tests - Generated code validation
  • Example Tests - Handler testing patterns

πŸ“š Documentation

πŸ—οΈ Development

Local Development:

# Build the CLI
make build

# Build for all platforms (uses GitHub Actions)
make build-all

# Generate example commands
make generate-example

# Self-generate CLI commands (dogfooding)
make generate-self

🎬 Example Output

$ hello-example hello "Adder" --capitalize
HELLO, ADDER!

$ adder generate --input docs/man --output generated --package generated
🐍 Generating CLI commands from docs/man to generated...
πŸ” Validating documentation...
βœ… Code generation completed!
πŸ“Š Generated 3 commands with 5 flags and 2 arguments

πŸš€ Release Process

Adder uses automated releases with release-please and GoReleaser:

  1. Merge to main triggers release PR creation
  2. Merge release PR creates GitHub release
  3. GoReleaser automatically builds and publishes multi-platform binaries

Use conventional commits for automatic versioning:

  • feat: β†’ minor version bump
  • fix: β†’ patch version bump
  • BREAKING CHANGE: β†’ major version bump

🀝 Contributing

We welcome contributions!

Getting Started:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Run make ci-test to validate
  5. Submit a pull request

Code Quality:

  • All tests must pass
  • golangci-lint must pass
  • Include tests for new features
  • Update documentation as needed

πŸ“„ License

MIT License - see LICENSE file for details.

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

⌂ 捒网址