---

🚀 What is Topia?

Topia is a modern, high-performance task automation framework built with Crystal that transforms how you handle development workflows. Think Gulp.js or Webpack, but with Crystal's speed, type safety, and elegance.

✨ Why Choose Topia?

• 🔧 Code over Configuration - Write workflows in pure Crystal, no complex config files
• ⚡ High Performance - Built for speed with async operations, caching, and parallelism
• 🧩 Composable - Chain tasks, plugins, and commands like building blocks
• 🔒 Type Safe - Leverage Crystal's compile-time type checking for bulletproof workflows
• 🎯 Developer Friendly - Professional CLI, interactive modes, and comprehensive debugging tools

---

🎯 Key Features

🏗️ Flexible Task Creation

# Simple command task
Topia.task("build")
  .command("crystal build src/main.cr")

# Complex pipeline
Topia.task("process")
  .src("./scss/*.scss")
  .pipe(SassCompiler.new)
  .pipe(CssMinifier.new)
  .dist("./public/css/")

🔗 Smart Dependencies

Topia.task("deploy")
  .depends_on(["test", "build"])
  .command("./deploy.sh")

# Automatic dependency resolution & parallel execution
Topia.run("deploy")  # Runs test + build first, then deploy

👀 File Watching

Topia.task("dev")
  .watch("./src/**/*.cr", read_sources: true)
  .pipe(CrystalCompiler.new)
  .command("./bin/app")

🔌 Plugin Architecture

class CustomPlugin < Topia::BasePlugin
  def run(input, args)
    announce "Processing #{input}..."
    # Your custom logic here
    success "Done!"
    processed_result
  end
end

Topia.task("custom")
  .pipe(CustomPlugin.new)

⚡ High Performance

• Async Operations - Non-blocking spinners and file watchers
• Intelligent Caching - SHA256-based task result caching
• Parallel Execution - Dependency-aware concurrent task processing
• Optimized I/O - Efficient file system operations

---

🎯 Developer Experience

Topia provides a professional-grade developer experience that scales from individual developers to enterprise teams. Every aspect has been designed for productivity, discoverability, and ease of use.

🖥️ Professional CLI Interface

Comprehensive Help System

$ topia --help
Topia v0.1.0 - Crystal Task Automation Framework

Usage: topia [options] [task_names...]

Main Options:
  -h, --help                     Show this help message
  -v, --version                  Show version information
  -l, --list                     List all available tasks
      --list-detailed            List tasks with detailed information

Execution Options:
  -p, --parallel                 Run tasks in parallel
  -j JOBS, --jobs=JOBS           Number of parallel jobs (default: CPU cores)
      --dry-run                  Show what would be executed without running
  -w, --watch                    Watch for file changes and re-run tasks
  -i, --interactive              Interactive task selection

Output Control:
  -q, --quiet                    Suppress all output except errors
      --verbose                  Enable verbose output
  -d, --debug                    Enable debug mode with detailed logging
      --no-color                 Disable colored output
      --stats                    Show execution statistics

[... 20+ more options with examples ...]

Smart Task Discovery

# List all available tasks with dependency visualization
$ topia --list
Available tasks:
  ○ clean
  ● build
    Dependencies: clean
  ○ test
  ○ dev

Default tasks: build

# Get detailed information about any task
$ topia --list-detailed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Task: build
Dependencies: clean
Source: defined in code
Pipeline: 1 command(s)
Description: Build the project

🎛️ Intelligent Output Modes

Quiet Mode - Perfect for CI/CD

$ topia -q build test deploy
# Only errors are shown - clean logs for automation

Verbose Mode - Detailed Development Insights

$ topia --verbose build
Running task 1/1: build
DEBUG: Loading configuration from topia.yml
DEBUG: Task 'build' dependencies: [clean]
✓ Task 'build' completed in 245ms

Statistics Mode - Performance Monitoring

$ topia --stats --verbose clean build test
Running tasks: clean, build, test

Execution Statistics:
  Total time: 2.1s
  Tasks executed: 3
  Execution mode: Sequential
  Success rate: 100%

Detailed Task Statistics:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
build:
  Status: success
  Runs: 1
  Duration: 245ms
  Last run: 2025-06-29 15:30:42

⚙️ Configuration Management

Zero-Config Initialization

# Generate professional configuration template
$ topia --init
✓ Created topia.yml
Edit topia.yml to customize your tasks and configuration.

# Validate configuration before execution
$ topia --validate-config
Validating configuration...
✓ Configuration is valid

Smart YAML Configuration

# topia.yml - Generated template with best practices
name: "My Project"
version: "1.0.0"
variables:
  build_dir: "./build"
  src_dir: "./src"

default_tasks: ["build"]

tasks:
  build:
    description: "Build the project"
    dependencies: ["clean"]
    sources: ["${src_dir}/**/*.cr"]
    commands: ["crystal build src/main.cr -o ${build_dir}/app"]

🔍 Enhanced Debugging & Monitoring

# Enable debug mode programmatically
Topia.debug = true

# Or use comprehensive CLI debugging
./app -d task_name                    # Debug mode with detailed logging
./app --verbose --stats task_name     # Verbose output with performance stats
./app --profile task_name             # Performance profiling
./app --dependencies task_name        # Analyze task dependencies
./app --where task_name               # Find task source location
./app --dry-run task_name             # Preview execution without running

# Custom logging with multiple levels
Topia.logger.info("Custom message")
Topia.logger.debug("Debug information")
Topia.logger.error("Error details")

# Task execution monitoring
Topia.task("monitored")
  .describe("Task with rich monitoring")
  .command("long_running_process")
# Automatically tracks: execution time, success/failure, cache hits, etc.

🚀 Interactive Development

Interactive Task Selection

$ topia --interactive
Interactive Task Selection
Available tasks:
  1. clean
  2. build
  3. test
  4. deploy

Select task numbers (e.g., 1,3,5 or 1-3): 2,3
Running tasks: build, test

Watch Mode for Live Development

# Automatically re-run tasks when files change
$ topia -w --verbose build
Starting watch mode for tasks: build
Press Ctrl+C to stop watching

Files changed: src/main.cr, src/models/user.cr
Re-running tasks due to file changes...
✓ Task 'build' completed in 180ms

📊 Performance Insights

Real-time Performance Monitoring

• Task execution times with millisecond precision
• Success/failure rates across runs
• Parallel execution efficiency metrics
• Cache hit rates for optimized builds
• Memory usage tracking for resource optimization

Performance Optimization Guidance

# Identify bottlenecks with detailed timing
$ topia --profile --stats build test
📊 Performance Profile:
  Slowest task: test (1.2s)
  Fastest task: clean (3ms)
  Cache hits: 85%
  Parallel efficiency: 3.2x speedup

Recommendations:
  ⚡ Consider parallelizing 'lint' and 'test'
  💾 'build' task has 90% cache hit rate - well optimized!

🛠️ Developer Productivity Features

Rich Task Descriptions

Topia.task("deploy")
  .describe("Deploy application to production with health checks")
  .depends_on("build")
  .command("./scripts/deploy.sh")

Professional Error Handling

ERROR: Task 'missing-dependency' not found
Did you mean: 'build', 'test', or 'clean'?

Use 'topia --list' to see all available tasks.

Configuration Validation with Context

ERROR: Configuration syntax error in topia.yml:
  Line 15: Invalid YAML - missing closing quote

Use 'topia --validate-config' to check syntax before running.

📈 Enterprise Features

CI/CD Integration

# Perfect for automated environments
topia --validate-config --quiet && topia -p -j 8 --stats lint test build

# Structured error reporting for log analysis
topia -q deploy || echo "Deploy failed with exit code $?"

Team Collaboration

# Share standardized workflows
topia --init my-project/
git add topia.yml

# Consistent execution across environments
topia -c team-config.yml --parallel build test

Monitoring & Analytics

• Build time trends over time
• Task failure analysis with detailed logs
• Resource usage optimization suggestions
• Team productivity metrics and insights

---

📦 Installation

Add to your shard.yml:

dependencies:
  topia:
    github: azutoolkit/topia

Then run:

shards install

---

🏃‍♂️ Quick Start

1. Create Your First Task

# tasks.cr
require "topia"

# Simple hello world
Topia.task("hello")
  .command("echo 'Hello from Topia!'")

# Run it
Topia.run("hello")

2. Build a Real Workflow

require "topia"

# Setup task
Topia.task("setup")
  .command("mkdir -p build/")
  .command("echo 'Environment ready'")

# Build with dependencies
Topia.task("build")
  .depends_on("setup")
  .src("./src/**/*.cr")
  .command("crystal build src/main.cr -o build/app")

# Test with dependencies
Topia.task("test")
  .depends_on("build")
  .command("crystal spec")

# Development workflow with watching
Topia.task("dev")
  .depends_on("setup")
  .watch("./src/**/*.cr", read_sources: true)
  .command("crystal build src/main.cr -o build/app")
  .command("./build/app")

# Run with CLI
Topia.cli(ARGV)

3. Use the Enhanced CLI

# Build CLI binary for better performance
crystal build tasks.cr -o ./topia

# Professional CLI with comprehensive features
./topia --help                    # Comprehensive help system
./topia --list                    # List all tasks with dependencies
./topia --list-detailed           # Detailed task information
./topia --init                    # Generate configuration template
./topia --validate-config         # Validate configuration

# Enhanced execution modes
./topia build                     # Run single task
./topia -p test build            # Parallel execution
./topia -j 4 lint test build     # Control parallel jobs
./topia -q deploy                # Quiet mode for CI/CD
./topia --verbose --stats build  # Verbose with performance stats
./topia -w build                 # Watch mode for development
./topia -i                       # Interactive task selection
./topia --dry-run deploy         # Preview execution plan

# Advanced analysis
./topia --dependencies deploy    # Analyze task dependencies
./topia --where build           # Find task source location

---

📚 Comprehensive Examples

🔧 Task Creation Patterns

Basic Tasks

# Command-only task
Topia.task("clean")
  .command("rm -rf build/")

# Multi-command task
Topia.task("deploy")
  .command("echo 'Starting deployment...'")
  .command("./scripts/build.sh")
  .command("./scripts/deploy.sh")
  .command("echo 'Deployment complete!'")

File Processing

# Process files through pipeline
Topia.task("process_assets")
  .src("./assets/**/*.{css,js}")
  .pipe(Minifier.new)
  .pipe(Gzipper.new)
  .dist("./public/")

# Watch and process
Topia.task("watch_assets")
  .watch("./assets/**/*", read_sources: true)
  .pipe(AssetProcessor.new)
  .dist("./public/")

Dependencies & Composition

# Linear dependencies
Topia.task("integration_test")
  .depends_on("unit_test")
  .command("./integration_tests.sh")

# Multiple dependencies
Topia.task("release")
  .depends_on(["test", "build", "lint"])
  .command("./release.sh")

# Complex workflow
Topia.task("full_ci")
  .depends_on(["setup"])
  .src("./src/**/*.cr")
  .pipe(Linter.new)
  .pipe(TestRunner.new)
  .command("crystal build --release")
  .dist("./releases/")

Dynamic Task Generation

# Generate tasks for multiple environments
["dev", "staging", "prod"].each do |env|
  Topia.task("deploy_#{env}")
    .depends_on("test")
    .command("./deploy.sh #{env}")
end

# Generate from configuration
configs = [
  {name: "lint", cmd: "crystal tool format --check"},
  {name: "docs", cmd: "crystal docs"},
  {name: "audit", cmd: "./security_audit.sh"}
]

configs.each do |config|
  Topia.task(config[:name])
    .command(config[:cmd])
end

🎯 Task Execution Methods

Direct Execution

# Run single task
Topia.run("build")

# Run multiple tasks sequentially
Topia.run(["clean", "build", "test"])

# Run with parameters
Topia.run("deploy", ["production", "--force"])

Parallel Execution

# Run independent tasks in parallel
Topia.run_parallel(["lint", "test", "docs"])

# Dependency-aware parallel execution
Topia.run_parallel(["integration_test", "build"])
# Automatically resolves: setup → test → integration_test
#                        setup → build

Enhanced CLI Interface

# In your main file
Topia.cli(ARGV)

# Professional CLI with 20+ options
./app --help                    # Comprehensive help system
./app --version                 # Detailed version information
./app --list                    # Smart task discovery with dependencies
./app --list-detailed           # Rich task information with pipeline details

# Enhanced execution modes
./app task_name                 # Run specific task
./app -p -j 4 task1 task2      # Parallel execution with job control
./app -q task_name             # Quiet mode for automation
./app --verbose --stats task   # Verbose output with performance metrics
./app -w task_name             # Watch mode with file change detection
./app -i                       # Interactive task selection
./app --dry-run task_name      # Preview execution plan

# Advanced analysis and debugging
./app -d task_name             # Debug mode with detailed logging
./app --dependencies task      # Analyze task dependencies
./app --where task             # Find task source location
./app --profile task           # Performance profiling

# Configuration management
./app --init                   # Generate professional config template
./app --validate-config        # Validate configuration syntax
./app -c custom.yml task       # Use custom configuration file

Configuration Files

# topia.yml
name: "My Project"
version: "1.0.0"
variables:
  src_dir: "./src"
  build_dir: "./build"

tasks:
  clean:
    description: "Clean build directory"
    commands: ["rm -rf ${build_dir}"]

  build:
    description: "Build application"
    dependencies: ["clean"]
    commands: ["crystal build ${src_dir}/main.cr -o ${build_dir}/app"]

# Load and use configuration
Topia.configure("topia.yml")
Topia.run("build")  # Uses tasks from YAML

🔌 Plugin Development

Simple Plugin

class EchoPlugin < Topia::BasePlugin
  def run(input, args)
    announce "Echo plugin running..."
    puts "Input: #{input}"
    puts "Args: #{args.join(", ")}"
    success "Echo complete!"
    input  # Return processed input
  end
end

Advanced Plugin with Lifecycle

class AdvancedPlugin < Topia::BasePlugin
  def run(input, args)
    validate_input(input)
    result = process(input, args)
    cleanup
    result
  end

  def on(event : String)
    case event
    when "pre_run"
      announce "Starting advanced processing..."
    when "after_run"
      success "Advanced processing completed!"
    when "error"
      error "Processing failed!"
    end
  end

  private def process(input, args)
    # Your processing logic
    input.to_s.upcase
  end
end

File Processing Plugin

class FileProcessor < Topia::BasePlugin
  def run(input, args)
    case input
    when Array(Topia::InputFile)
      announce "Processing #{input.size} files..."
      input.map { |file| process_file(file) }
    else
      error "Expected Array(InputFile), got #{input.class}"
      input
    end
  end

  private def process_file(file : Topia::InputFile)
    # Process file content
    file.contents = file.contents.gsub(/old/, "new")
    file
  end
end

---

⚡ Performance Features

🔄 Async Operations

• Non-blocking spinners - 15x CPU usage reduction
• Event-driven file watching - 5x fewer I/O operations
• Concurrent task execution - Up to 4x faster builds

💾 Intelligent Caching

# Tasks are automatically cached based on:
# - Input file checksums
# - Command signatures
# - Plugin configurations
# - Dependency states

Topia.task("expensive_build")
  .src("./src/**/*.cr")
  .pipe(SlowCompiler.new)
  .dist("./build/")

# First run: Full execution
# Subsequent runs: Instant cache hits (if nothing changed)

📊 Performance Metrics

🔧 Performance Optimization with Enhanced CLI

# Identify bottlenecks with detailed profiling
$ topia --profile --stats build test deploy
📊 Performance Profile:
  Total time: 3.2s
  Parallel efficiency: 3.8x speedup
  Cache hit rate: 87%

Task Breakdown:
  test: 1.8s (56% of total time) ⚠️  Consider optimization
  build: 800ms (25% of total time) ✓ Well optimized
  deploy: 600ms (19% of total time) ✓ Cached result

Recommendations:
  ⚡ Run 'lint' and 'test' in parallel to save 400ms
  💾 Enable caching for 'deploy' task
  🔄 Consider splitting 'test' into smaller parallel tasks

---

🛠️ Advanced Features

🔍 Enhanced Debugging & Monitoring

# Enable debug mode programmatically
Topia.debug = true

# Or use comprehensive CLI debugging
./app -d task_name                    # Debug mode with detailed logging
./app --verbose --stats task_name     # Verbose output with performance stats
./app --profile task_name             # Performance profiling
./app --dependencies task_name        # Analyze task dependencies
./app --where task_name               # Find task source location
./app --dry-run task_name             # Preview execution without running

# Custom logging with multiple levels
Topia.logger.info("Custom message")
Topia.logger.debug("Debug information")
Topia.logger.error("Error details")

# Task execution monitoring
Topia.task("monitored")
  .describe("Task with rich monitoring")
  .command("long_running_process")
# Automatically tracks: execution time, success/failure, cache hits, etc.

⚙️ Configuration Management

# Set variables programmatically
Topia::Config.set_variable("env", "production")

# Use in tasks
Topia.task("deploy")
  .command("deploy --env=${env}")

# Environment variable access
# In YAML: ${ENV_PATH} automatically resolves

# Professional configuration workflow
./app --init                          # Generate configuration template
./app --validate-config               # Validate syntax and dependencies
./app -c production.yml deploy        # Use environment-specific config

🔄 Lifecycle Hooks

class MyPlugin < Topia::BasePlugin
  def on(event : String)
    case event
    when "pre_run"   then setup
    when "after_run" then cleanup
    when "error"     then handle_error
    end
  end
end

---

🏗️ Architecture

📁 Project Structure

topia/
├── src/topia/
│   ├── task.cr              # Main task orchestrator
│   ├── plugin.cr            # Plugin interface & base
│   ├── pipe.cr              # Type-safe pipeline
│   ├── command.cr           # Command execution
│   ├── watcher.cr           # File watching
│   ├── cli.cr               # Command-line interface
│   ├── dependency_manager.cr # Task dependencies
│   ├── config.cr            # Configuration system
│   ├── task_cache.cr        # Intelligent caching
│   └── concurrent_executor.cr # Parallel execution
├── playground/              # Examples and demos
└── spec/                   # Test suite

🧩 Core Components

• Task - Main orchestrator with fluent API
• Plugin - Extensible processing units
• Pipe - Type-safe data pipeline
• CLI - Comprehensive command-line interface
• DependencyManager - Topological task sorting
• TaskCache - SHA256-based result caching

---

🤝 Contributing

We welcome contributions! Here's how to get started:

🚀 Quick Contribution Setup

git clone https://github.com/azutoolkit/topia.git
cd topia
shards install
crystal spec  # Run tests

📋 Contribution Guidelines

1. Fork & Branch - Create feature branches from master
2. Test Coverage - Add specs for new features
3. Code Style - Follow Crystal Style Guide
4. Documentation - Update docs for new features
5. Performance - Consider performance impact

🧪 Running Tests

crystal spec                    # All tests
crystal spec spec/topia_spec.cr # Core functionality
crystal spec spec/new_features_spec.cr # New features

🔧 Development Commands

# Run examples
crystal run playground/example.cr
crystal run playground/complete_example.cr

# Build CLI
crystal build src/cli.cr -o topia

# Performance testing
crystal run playground/performance_demo.cr

---

📖 Documentation

📚 Additional Resources

• API Documentation - Complete API reference
• Examples - Working examples and demos
• Architecture Guide - Deep dive into Topia's design
• Plugin Development - Creating custom plugins

🎓 Learning Path

1. Start - Quick Start guide above
2. Explore - Run playground examples
3. Build - Create your first custom plugin
4. Scale - Use advanced features (dependencies, caching, parallel execution)
5. Contribute - Add features or plugins

---

📊 Benchmarks

🏎️ Performance Comparison

# Before Topia optimizations
build_time: 45s
cpu_usage: 15% (spinner)
memory: Growing over time
cache_hits: 0%

# After Topia optimizations
build_time: 12s (with parallelism + caching)
cpu_usage: <1% (async spinner)
memory: Stable with cleanup
cache_hits: 85%+

📈 Real-World Results

• Medium project (50 files): 40s → 8s (5x faster)
• Large project (200+ files): 3min → 45s (4x faster)
• CI pipeline: 8min → 2min (4x faster)

---

🙏 Acknowledgments

• Crystal Language - For providing an amazing language
• Gulp.js - Inspiration for the task runner concept
• Community Contributors - For plugins, feedback, and improvements

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🌟 Show Your Support

Give a ⭐️ if this project helped you!

Built with ❤️ and Crystal

---