TimeWarpEngineering / timewarp-nuru

TimeWarp.Nuru **Route-based CLI framework for .NET - bringing web-style routing to command-line applications** > **Nuru** means "light" in Swahili - illuminating the path to your commands with clarity and simplicity. 📦 Installation 🚀 Quick Start TimeWarp.Nuru offers two patterns for defining CLI commands. Start with the Endpoint DSL for structured apps, or Fluent DSL for quick scripts. Endpoint DSL Define routes as classes with attributes: Fluent DSL Define routes inline with a fluent builder API: **→ Full Getting Started Guide** ✨ Key Features | Feature | Description | Learn More | |---------|-------------|------------| | 🎯 **Web-Style Routing** | Familiar syntax | Routing Guide | | 📦 **Endpoint DSL** | Class-based commands with auto-discovery | Architecture Choices | | 🔧 **Fluent DSL** | Inline routes with chain | Architecture Choices | | 🛡️ **Roslyn Analyzer** | Catch route errors at compile-time | Analyzer Docs | | ⌨️ **Shell Completion** | Tab completion for bash, zsh, PowerShell, fish | Shell Completion | | 🤖 **MCP Server** | AI-assisted development with Claude | MCP Server Guide | | 📊 **Logging Package** | Zero-overhead structured logging | Logging Docs | | 🚀 **Native AOT** | Zero warnings, 3.3 MB binaries, instant startup | Deployment Guide | | 🔒 **Type-Safe Parameters** | Automatic type conversion and validation | Supported Types | | 📖 **Auto-Help** | Generate help from route patterns | Auto-Help Feature | | 🎨 **Rich Terminal** | Colors, tables, panels, rules via TimeWarp.Terminal | Terminal Guide | 📚 Documentation Getting Started • **Getting Started Guide** - Build your first CLI app in 5 minutes • **Use Cases** - Greenfield apps & progressive enhancement patterns • **Architecture Choices** - Choose Endpoint DSL or Fluent DSL Core Features • **Routing Patterns** - Complete route syntax reference • **Roslyn Analyzer** - Compile-time validation • **Logging System** - Structured logging setup • **Auto-Help** - Automatic help generation • **Output Handling** - stdout/stderr best practices • **Terminal Abstractions** - Testable I/O & colored output Tools & Deployment • **MCP Server** - AI-powered development assistance • **Deployment Guide** - Native AOT, runfiles, distribution • **Best Practices** - Patterns for maintainable CLIs Reference • **Performance Benchmarks** - Detailed performance metrics • **Supported Types** - Complete type reference • **API Documentation** - Technical reference 🎯 Two Powerful Use Cases 🆕 Greenfield CLI Applications Build modern command-line tools from scratch: **Endpoint DSL approach** (class-based, organized by file): **Fluent DSL approach** (inline definitions): 🔄 Progressive Enhancement Wrap existing CLIs to add auth, logging, or validation: **→ Detailed Use Cases with Examples** 🌟 Working Examples **Calculator Samples** - Three complete implementations you can run now: • **01-calc-endpoints.cs** - Endpoint DSL pattern (testable, DI) • **02-calc-fluent.cs** - Fluent DSL approach (inline handlers) • **03-calc-mixed.cs** - Mixed approach (both patterns together) **AOT Example** - Native AOT compilation with source generators ⚡ Performance | Implementation | Memory | Speed (37 tests) | Binary Size | |----------------|--------|------------------|-------------| | Direct (JIT) | ~4 KB | 2.49s | N/A | | Direct (AOT) | ~4 KB | **0.30s** 🚀 | 3.3 MB | | Endpoints (AOT) | Moderate | **0.42s** 🚀 | 4.8 MB | **Native AOT is 88-93% faster than JIT** → Full Performance Benchmarks 🤖 AI-Powered Development **For AI agents:** Load the built-in Nuru Skill for instant access to: • Complete DSL syntax and patterns • Testing with TestTerminal • Route examples and type conversion > 💡 **Tip:** No MCP installation needed - the skill provides all essential patterns. **For MCP Server:** Install for Claude Code, Roo Code, or Continue: Get instant help: • Validate route patterns before writing code • Generate handler code automatically • Get syntax examples on demand • Real-time error guidance **→ MCP Server Setup Guide** ⌨️ Shell Completion Enable tab completion for your CLI with one line of code: Generate completion scripts for your shell: **Supports:** • ✅ Command completion ( , ) • ✅ Option completion ( , ) • ✅ Short option aliases ( , ) • ✅ All 4 major shells (bash, zsh, PowerShell, fish) **See completion-example for a complete working example.** 🤝 Contributing We welcome contributions! See CONTRIBUTING.md for details. **For Contributors:** • **Developer Documentation** - Architecture and design • **Standards** - Coding conventions 📄 License This project is licensed under the Unlicense - see the license file for details. --- **Ready to build powerful CLI applications?** **Get Started in 5 Minutes** • **View Examples** • **Read the Docs**