Hatch

A beautiful, interactive CLI tool for Protoflow - built with Charm components for an exceptional developer experience.

Hatch scaffolds production-ready event-driven services with:

• 🏗️ Complete project structure - App orchestration, use cases, events, database support
• 📊 OpenTelemetry integration - Tracing, metrics, and structured logging out of the box
• 🔧 Viper configuration - Environment-driven config with sensible defaults
• 🎯 Best practices - Pre-commit hooks, Taskfile automation, comprehensive documentation
• 🚀 Multiple transports - Kafka, RabbitMQ, NATS, AWS, HTTP, and more

Features

• 🎨 Beautiful UI: Built with Charm's Bubble Tea and Lip Gloss for a delightful terminal experience
• 🚀 Project Scaffolding: hatch init - Generate new Protoflow projects instantly
• 📝 Handler Generation: hatch handler add - Create type-safe handlers with boilerplate
• ✅ Configuration Validation: hatch validate - Validate configs before runtime
• 🎯 Interactive Prompts: Charm's survey components for guided workflows

Installation

From Source

git clone https://github.com/drblury/hatch.git
cd hatch
go install ./cmd/hatch

Via Go Install

go install github.com/drblury/hatch/cmd/hatch@latest

Via Homebrew (Coming Soon)

brew install hatch

Quick Start

Initialize a New Project

hatch init my-service

This will create a production-ready project with:

• Application Structure: main.go with build metadata, internal/app for lifecycle management
• Business Logic: internal/usecase package for clean architecture
• Event Handling: internal/events with middleware, validation, and retries
• Database Support: internal/database with MongoDB integration and health checks
• Observability: pkg/logging with OTEL tracing, metrics, and structured logging
• Configuration: Viper-based config with .env.example template
• Development Tools: Pre-commit hooks, Taskfile, comprehensive documentation

Add a Handler

hatch handler add OrderCreated --type proto --consume orders.created

Validate Configuration

hatch validate .env

Commands

hatch init [name]

Scaffold a new Protoflow service project.

Options:

• --transport <name> - Select transport (kafka, rabbitmq, nats, aws, http, io, sqlite, postgres, channel)
• --with-examples - Include example handlers
• --with-simulator - Include event simulator
• --interactive - Use interactive mode (default when no args provided)

Example:

hatch init my-service --transport kafka

hatch handler add <name>

Generate boilerplate for a new handler.

Releases

Releases are automatically created when a git tag is pushed. The CI pipeline uses GoReleaser to build binaries for multiple platforms and create GitHub releases.

Creating a Release

1. Update version numbers and changelog
2. Commit your changes
3. Create and push a git tag:

   git tag -a v1.0.0 -m "Release v1.0.0"
   git push origin v1.0.0

The GitHub Actions workflow will automatically:

• Build binaries for Linux, macOS, and Windows (amd64 and arm64)
• Create a GitHub release with release notes
• Upload all binaries and checksums
• Generate Homebrew formula (if configured)

Manual Release

You can also trigger a release manually via GitHub Actions:

1. Go to Actions → Release workflow
2. Click "Run workflow"
3. Enter the tag name (e.g., v1.0.0)
4. Click "Run workflow"

Options:

• --type <proto|json|cloudevents> - Handler type (default: proto)
• --consume <queue> - Consume queue/topic (required)
• --publish <queue> - Publish queue/topic (optional)
• --interactive - Use interactive mode (default)

Example:

hatch handler add ProcessPayment \
  --type json \
  --consume payments.process \
  --publish payments.completed

hatch validate [config-file]

Validate Protoflow configuration without running the service.

Options:

• --config <file> - Configuration file path (default: .env)
• --transport <name> - Validate transport-specific config
• --verbose - Show detailed validation results

Example:

hatch validate .env
hatch validate --config .env --verbose

Architecture

Built with Charm libraries:

• Bubble Tea - TUI framework for interactive CLI
• Lip Gloss - Styling and layout
• Spinner - Loading indicators
• Table - Beautiful tables
• Progress - Progress bars
• Bubbles - Reusable Bubble Tea components

Development

Prerequisites

• Go 1.21+
• Protoflow library (for validation)

Building

go build -o hatch ./cmd/hatch

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
go tool cover -func=coverage.out
go tool cover -html=coverage.out -o coverage.html

# Run tests with verbose output
go test -v ./...

Generated Project Structure

When you run hatch init, you get a complete production-ready structure:

my-service/
├── main.go                  # Entry point with build metadata
├── go.mod                   # Dependencies
├── .env.example             # Environment configuration template
├── .pre-commit-config.yaml  # Pre-commit hooks
├── taskfile.yml             # Task automation
├── handlers/
│   ├── registry.go         # Handler registration
│   └── *.go                # Your event handlers
├── internal/
│   ├── app/                # Application orchestration
│   │   ├── app.go          # Main app lifecycle
│   │   ├── bootstrap.go    # Initialization
│   │   ├── config.go       # Viper-based config
│   │   └── http_server.go  # HTTP server setup
│   ├── usecase/            # Business logic layer
│   │   └── usecase.go      # Use case implementation
│   ├── events/             # Event handling
│   │   ├── events_setup.go # Event service setup
│   │   ├── validator.go    # Event validation
│   │   └── config.go       # Events config
│   └── database/           # Database support
│       ├── db.go           # MongoDB connection
│       └── config.go       # Database config
└── pkg/
    └── logging/            # Logging & observability
        ├── logging.go      # Structured logging
        ├── tracing/        # OTEL tracing
        └── metrics/        # OTEL metrics

CLI Project Structure

hatch/
├── cmd/hatch/          # CLI entry point
├── internal/
│   ├── commands/           # Command implementations
│   ├── ui/                 # Charm UI components
│   └── scaffold/           # Code generation & templates
├── docs/                   # Documentation
└── README.md

Testing

The project maintains high test coverage with comprehensive unit tests:

# Run all tests with coverage
go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
go tool cover -func=coverage.out
go tool cover -html=coverage.out -o coverage.html

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

1. Clone the repository
2. Install dependencies: go mod download
3. Run tests: go test ./...
4. Build: go build ./cmd/hatch

License

MIT License - see LICENSE file.

What Gets Generated

The CLI generates a production-ready event-driven service with:

• App Orchestration (internal/app) - Lifecycle management, graceful shutdown, initialization
• Use Case Layer (internal/usecase) - Business logic separation from handlers
• Event Handling (internal/events) - Event service setup with middleware, validation, retries
• Database Support (internal/database) - MongoDB integration with health checks
• Observability (pkg/logging) - Structured logging, OTEL tracing & metrics (stubs ready for implementation)
• Configuration - Viper-based config with environment variable support
• Development Tools - Pre-commit hooks, Taskfile, comprehensive .env.example

Related Projects

• Protoflow - The main library
• Charm - Beautiful CLI tools
• Event-Driven-Service-Example - Reference implementation