Changelog

All notable changes to HexaGo will be documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

---

v0.0.3 - 2026-03-04

--working-directory global flag

• New -w / --working-directory persistent flag on the root command — every subcommand can now target a project in a different directory without cd-ing into it first.
• All hexago add * and hexago validate commands accept the flag and pass it to the project detector. When omitted, the current working directory is used as before.
• hexago init --working-directory <dir> creates the project under <dir> instead of the current directory.

# Add a service to a project located elsewhere — no cd required
hexago add service CreateUser --working-directory /home/user/projects/my-api

--in-place flag for hexago init

• New --in-place bool flag: generates project files directly into working_directory instead of creating a <name> subdirectory inside it.
• Useful when the target directory already exists and is the intended project root (e.g. a freshly cloned empty repo or the current working directory).

# Scaffold into the current directory
hexago init my-api --module github.com/user/my-api --in-place

# Scaffold into an existing remote directory
hexago init my-api --module github.com/user/my-api \
  --working-directory /home/user/projects/my-api \
  --in-place

Built-in MCP Server (hexago mcp)

HexaGo now ships with a built-in Model Context Protocol server, letting AI assistants scaffold hexagonal architecture projects without leaving the conversation.

hexago mcp   # start the stdio MCP server

Register with Claude Code:

claude mcp add --scope project hexago -- hexago mcp

Nine tools are available — each delegates to the hexago CLI with --working-directory:

Tool	What it does
hexago_init	Bootstrap a new project
hexago_add_service	Add a business-logic service
hexago_add_domain_entity	Add a domain entity
hexago_add_domain_valueobject	Add a domain value object
hexago_add_adapter	Add a primary or secondary adapter
hexago_add_worker	Add a background worker
hexago_add_migration	Add a database migration
hexago_add_tool	Add an infrastructure utility
hexago_validate	Validate architecture compliance

The server delivers comprehensive usage instructions on every initialize handshake, covering all parameter names, valid enum values, defaults, field format, and a directive that prevents AI agents from falling back to raw CLI shell calls.

See hexago mcp for client configuration examples (Claude Code, Claude Desktop, VS Code, Cursor, Windsurf, Zed).

Changed

• GetCurrentProjectConfig() signature updated to GetCurrentProjectConfig(dir string) — empty string falls back to os.Getwd(). All call sites updated.
• cmd/init.go resolves OutputDir from the --working-directory flag value with an os.Getwd() fallback.
• internal/generator/project.go and detector.go migrated from pkg/fileutil to pkg/utils for file-system helpers (internal refactor, no behaviour change).

---

0.0.2 — 2026-02-26

Release Highlights

Template management commands, project config file, and cleaner generated HTTP server architecture.

Template Management (hexago templates)

Full control over the templates HexaGo uses to generate your projects:

• hexago templates list — Lists all built-in templates grouped by directory. Templates with an active override are annotated with ← project-local or ← user-global.
• hexago templates which <name> — Shows which source wins for a given template (embedded, project-local, user-global, or binary-local) with its full path.
• hexago templates export <name> [--global] — Copies a built-in template to .hexago/templates/<name> (project-local) or ~/.hexago/templates/<name> (user-global) for customization.
• hexago templates export-all [--global] [--force] — Bulk-exports every embedded template at once; skips templates that already have an override unless --force is passed.
• hexago templates validate <path> — Parses a template file and reports text/template syntax errors. Prints ✓ on success, ✗ <error> on failure.
• hexago templates reset <name> [--global] — Removes a custom override, reverting to the next-priority source.

See Template Customization for full details.

.hexago.yaml Project Configuration File

• hexago init now writes .hexago.yaml into the generated project root after scaffolding, persisting all init-time settings (framework, adapter style, features, etc.).
• hexago add * reads .hexago.yaml automatically — no need to repeat flags on every invocation. Settings detected from the config file supplement filesystem heuristics.
• Acts as a defaults layer — priority is flags > .hexago.yaml > hardcoded defaults. Any flag not explicitly passed is filled from .hexago.yaml, enabling personal or team-wide preferences.
• Useful for sharing consistent conventions across a team without enforcing every flag.

HTTP Server Architecture (Generated Code)

• Shared Server interface in pkg/server/server.go — a single Run(errChan chan<- error) / Stop(ctx context.Context) error contract shared across all adapters.
• Framework-specific server.go extracted into internal/adapters/{primary|driver}/http/server.go for all five supported frameworks (Echo, Gin, Chi, Fiber, stdlib). Each adapter's New() constructor returns the shared srv.Server interface, hiding all framework types behind the abstraction boundary.
• Thin cmd/run.go orchestrator — now completely framework-agnostic: no framework imports, no repeated signal/shutdown boilerplate. Just calls httpserver.New(), srv.Run(), and srv.Stop().
• Compile-time interface guards (var _ srv.Server = (*server)(nil)) catch implementation drift at build time.

Refactored (Internal — No Generated-Code Change)

• Removed global template loader singleton — TemplateLoader is now a field on ProjectConfig, scoping it to its owning config and making generators straightforward to test in isolation.
• New pkg/utils package — ToSnakeCase and ToTitleCase helpers replace multiple identical local copies across the generator.
• Observability templates moved — misc/health.go.tmpl, misc/metrics.go.tmpl, and misc/server.go.tmpl relocated to observability/ to match the generated internal/observability/ package structure.
• Extended pkg/fileutil — HomeDir() and BinaryDir() migrated from the generator package into pkg/fileutil, removing private helpers from the generator.

---

0.0.1 — 2026-02-17

MVP Release

Initial public release of HexaGo.

Core Features

• Project Type Support: Generate projects with different architectural patterns
  • http-server — HTTP API server with framework support (Echo, Gin, Chi, Fiber, stdlib)
  • service — Long-running daemon/service with no web framework for main logic
• Hexagonal Architecture — Strict separation of concerns with core/adapters structure
• Framework Support — Echo, Gin, Chi, Fiber, and Go stdlib for HTTP servers
• Graceful Shutdown — Context-based cancellation with signal handling for all project types
• Configuration Management — Viper-based config with YAML files and environment variable support
• Structured Logging — Logger package with configurable levels and formats

Observability

• Health Checks:
  • /health — Complete health report with component status
  • /health/ready — Kubernetes readiness probe
  • /health/live — Kubernetes liveness probe
• Prometheus Metrics — Request counters, latency histograms, active operations gauge
• Separate Observability Server — Runs on independent port (default: 8080)
• Component Registration — Register custom health checks for databases, queues, etc.

Service Pattern (Long-Running Daemon)

• Processor Pattern — Main business logic in Processor.Start(ctx) method
• Context-Based Shutdown — Clean cancellation and resource cleanup
• Background Processing — Example implementations for queues, schedulers, file watchers
• Signal Handling — SIGINT, SIGTERM, SIGQUIT support
• Configurable Timeouts — Grace period for shutdown operations

Template System

• Externalized Templates — All code templates can be customized
• Multi-Source Loading:
  • Binary-local: templates/ (next to executable)
  • Project-local: .hexago/templates/ (per-project customization)
  • User-global: ~/.hexago/templates/ (user-wide customization)
  • Embedded: Fallback templates compiled into binary
• Company Branding — Easy to customize headers, comments, and code style
• Version Control — Share custom templates across teams

Code Generation

• Component Generators:
  • Services/UseCases — Business logic layer
  • Domain Entities — Core domain objects with fields
  • Value Objects — Immutable domain values
  • HTTP Adapters — Framework-specific handlers
  • Database Adapters — Repository implementations
  • External Service Adapters — API client wrappers
  • Cache Adapters — Redis/memory cache implementations
  • Queue Adapters — Message queue consumers
• Background Workers — Queue-based, periodic, and event-driven patterns
• Database Migrations — Sequential numbered migrations with golang-migrate support
• Infrastructure Tools — Loggers, validators, mappers, middleware

Project Flexibility

• Optional Features — All features opt-in via flags (default: false)
  • --with-docker — Docker files (Dockerfile, compose.yaml)
  • --with-observability — Health checks and metrics
  • --with-migrations — Database migration setup
  • --with-workers — Background worker pattern
  • --with-metrics — Prometheus metrics (deprecated, use --with-observability)
  • --with-example — Example code
  • --explicit-ports — Explicit ports/ directory structure
• Naming Conventions:
  • Adapter style: primary-secondary or driver-driven
  • Core logic: services or usecases
• Architecture Validation — Auto-detection of existing project conventions

Developer Experience

• Cobra CLI — Command structure with subcommands
• Auto-Detection — Respects existing project structure and conventions
• Smart Defaults — Sensible defaults with override options
• Helpful Messages — Clear error messages and configuration summaries
• Educational Comments — Generated code includes architecture guidance

Build & Release

• GoReleaser Integration — Automated multi-platform builds
• GitHub Actions — CI/CD workflow for releases
• Platform Support:
  • Linux: x86_64, arm64
  • macOS: x86_64 (Intel), arm64 (Apple Silicon)
• Static Binaries — CGO_ENABLED=0 for portability
• Homebrew Support — Ready for homebrew-tap publication

Documentation

• Comprehensive README with examples
• Quick start guide
• Architecture documentation
• Template customization guide
• Project type comparison

Project Types Use Cases

HTTP Server (http-server) — Perfect for:

• REST APIs
• GraphQL servers
• Microservices with HTTP interfaces
• Web applications with API backends

Service (service) — Perfect for:

• MQTT/Kafka message consumers
• File system watchers
• Background job processors
• Event stream processors
• Periodic task schedulers
• Data pipeline processors

Security

• No external dependencies in core (stdlib only)
• Static binary compilation
• No code execution from templates (text/template, not html/template)

---

How to Update

go install github.com/padiazg/hexago@v0.0.2

Or download binaries from GitHub Releases.