ason

README

※ Ason - Shake Your Projects Into Being

The sacred rattle that transforms templates into living code

A powerful, lightweight project scaffolding tool that catalyzes the transformation of templates into fully-formed projects. Built with Go's simplicity and minimal dependencies.

Installation

macOS (Homebrew - Recommended)

# Add the tap and install
brew tap madstone-tech/tap
brew install ason

# Verify installation
ason --version

Shell completions are automatically installed with Homebrew.

Linux

Download Binary (All distributions)

# AMD64
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_Linux_x86_64.tar.gz | tar xz
sudo mv ason /usr/local/bin/

# ARM64
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_Linux_arm64.tar.gz | tar xz
sudo mv ason /usr/local/bin/

Windows

Download the latest .zip from releases, extract, and add to your PATH.

Using Go

go install github.com/madstone-tech/ason@latest

Quick Start

# View available commands
ason --help

# Register a template
ason register my-template ./path/to/template

# List registered templates
ason list

# Create a project from a template
ason new my-template my-project

# Or use a local template directly
ason new ./path/to/template my-project

Using Ason as a Library

Ason provides a comprehensive public API for using it as a library in your Go projects.

Installation

go get github.com/madstone-tech/ason

Core Features

1. Generator - Template Rendering

package main

import (
	"context"
	"log"
	"github.com/madstone-tech/ason/pkg"
)

func main() {
	// Create a generator with the default engine
	engine := pkg.NewDefaultEngine()
	gen, err := pkg.NewGenerator(engine)
	if err != nil {
		log.Fatal(err)
	}

	// Generate a project
	variables := map[string]interface{}{
		"project_name": "my-app",
		"author":       "Alice",
	}
	
	ctx := context.Background()
	err = gen.Generate(ctx, "./template", variables, "./output")
	if err != nil {
		log.Fatal(err)
	}
}

2. Registry - Template Management

package main

import (
	"log"
	"github.com/madstone-tech/ason/pkg"
)

func main() {
	// Use default XDG-compliant registry
	reg, err := pkg.NewRegistry()
	if err != nil {
		log.Fatal(err)
	}

	// Register a template
	err = reg.Register("my-template", "/path/to/template", "My project template")
	if err != nil {
		log.Fatal(err)
	}

	// List templates
	templates, err := reg.List()
	if err != nil {
		log.Fatal(err)
	}
	
	for _, t := range templates {
		println(t.Name, t.Path)
	}

	// Remove a template
	err = reg.Remove("my-template")
	if err != nil {
		log.Fatal(err)
	}
}

3. Custom Engines - Pluggable Template Engines

package main

import (
	"context"
	"log"
	"github.com/madstone-tech/ason/pkg"
)

type CustomEngine struct{}

func (e *CustomEngine) Render(template string, ctx map[string]interface{}) (string, error) {
	// Implement your template rendering logic
	return template, nil
}

func (e *CustomEngine) RenderFile(filePath string, ctx map[string]interface{}) (string, error) {
	// Implement file rendering
	return "", nil
}

func main() {
	// Use a custom engine
	engine := &CustomEngine{}
	gen, err := pkg.NewGenerator(engine)
	if err != nil {
		log.Fatal(err)
	}

	variables := map[string]interface{}{}
	ctx := context.Background()
	err = gen.Generate(ctx, "./template", variables, "./output")
	if err != nil {
		log.Fatal(err)
	}
}

Key Components

• Generator: NewGenerator(engine Engine) - Create a generator with any engine

  • Generate() - Render templates with context support
  • GetEngine() - Retrieve the configured engine

• Registry: NewRegistry() / NewRegistryAt(path) - Manage templates

  • Register(), List(), Remove() - Template CRUD operations
  • XDG Base Directory compliant storage

• Engine Interface: Pluggable template engine system

  • NewDefaultEngine() - Default Pongo2 implementation
  • RenderWithEngine() - Context-aware rendering helper
  • Implement Engine interface for custom engines

API Documentation

For detailed API documentation, see:

• Engine Interface Documentation
• GoDoc

Thread Safety

All public types are thread-safe:

• Generator: RWMutex-protected for concurrent operations
• Registry: Multiple concurrent reads, serialized writes
• Engine: Implementation must be thread-safe

Error Handling

Ason provides specific error types for proper error handling:

• TemplateNotFoundError - Template doesn't exist
• InvalidPathError - Invalid path (traversal prevention)
• VariableValidationError - Invalid variable names/values
• GenerationError - Template rendering failed
• EngineError - Engine-specific failure

All errors support Unwrap() for error chaining.

Features

• 🪇 Rhythmic Generation: Fast, lightweight operation with minimal dependencies
• 🎭 Jinja2-like Templating: Uses Pongo2 for familiar template syntax
• 📿 Template Registry: Local management of your template collection
• 💫 Interactive Prompts: Beautiful terminal UI with Bubble Tea
• 🔮 Terraform Integration: Seamless infrastructure-as-code support
• ⚡ Shell Autocompletion: Tab completion for bash, zsh, and fish

Shell Autocompletion

Ason supports autocompletion for bash, zsh, and fish shells, providing intelligent suggestions for:

• Template names from your registry
• File and directory paths
• Command flags and options
• Variable names (name=, version=, etc.)

Quick Installation

# Install completion for your current shell
./scripts/install-completion.sh

# Or install for specific shells
./scripts/install-completion.sh bash zsh fish

# Or install for all available shells
./scripts/install-completion.sh all

Manual Installation

Bash

# Generate completion script
ason completion bash > ~/.local/share/bash-completion/completions/ason

# Or for system-wide installation (requires sudo)
sudo ason completion bash > /usr/share/bash-completion/completions/ason

Zsh

For Oh My Zsh users (recommended):

# Create custom plugin
mkdir -p ~/.oh-my-zsh/custom/plugins/ason
ason completion zsh > ~/.oh-my-zsh/custom/plugins/ason/_ason

# Add to plugins list in ~/.zshrc
# plugins=(... ason)

Alternative for Oh My Zsh:

# Direct to completions directory (if it exists)
ason completion zsh > ~/.oh-my-zsh/completions/_ason

For standard Zsh setup:

mkdir -p ~/.zfunc
ason completion zsh > ~/.zfunc/_ason

# Add to ~/.zshrc if not already present
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
echo 'autoload -U compinit' >> ~/.zshrc
echo 'compinit' >> ~/.zshrc

Fish

# Install fish completion
ason completion fish > ~/.config/fish/completions/ason.fish

Testing Completion

After installation, test completion by typing:

ason <TAB>          # Shows available commands
ason new <TAB>      # Shows available templates and directories
ason remove <TAB>   # Shows templates in registry
ason --<TAB>        # Shows available flags

Building and Releasing

This project uses Taskfile for automation and GoReleaser for building and releasing.

Development Tasks

# Install Task (if not already installed)
go install github.com/go-task/task/v3/cmd/task@latest

# Show all available tasks
task

# Setup and installation
task setup              # Complete development environment setup
task install            # Install binary to GOPATH/bin
task uninstall          # Remove binary from GOPATH/bin

# Common development tasks
task build              # Build for current platform
task test               # Run tests
task test:coverage      # Run tests with coverage
task lint               # Run linters
task clean              # Clean build artifacts

Building for Multiple Platforms

# Build for all platforms (local, no publish)
task release:local

# Create snapshot release (test release process)
task release:snapshot

# Test release process (dry run)
task release:test

Creating Releases

# Create and push a git tag
task git:tag TAG=v1.0.0

# Publish release (requires GITHUB_TOKEN)
export GITHUB_TOKEN=your_token_here
task release:publish

Release Artifacts

The release process automatically creates:

• Homebrew formula (macOS)
• Universal binaries for macOS (Intel + Apple Silicon)
• Binary archives for Linux (amd64, arm64) and Windows
• Source code archives

About the Name

Ason is named after the sacred rattle used in Haitian Vodou ceremonies - a tool that catalyzes transformation and invokes change. Just as the ason's rhythm activates spiritual work, this tool activates the transformation of templates into living projects.

License

MIT

Documentation

Overview

Package main is the entry point for the Ason CLI tool.