{"id":29867183,"url":"https://github.com/timewarpengineering/timewarp-nuru","last_synced_at":"2026-01-25T17:01:00.506Z","repository":{"id":306356630,"uuid":"1024635367","full_name":"TimeWarpEngineering/timewarp-nuru","owner":"TimeWarpEngineering","description":"Route-based CLI framework for .NET - Nuru means 'light' in Swahili","archived":false,"fork":false,"pushed_at":"2026-01-20T19:51:53.000Z","size":30653,"stargazers_count":107,"open_issues_count":6,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-21T00:35:05.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimeWarpEngineering.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-23T02:57:13.000Z","updated_at":"2026-01-20T19:51:58.000Z","dependencies_parsed_at":"2025-07-25T07:38:42.489Z","dependency_job_id":"cf50dded-f679-40ac-a76a-305de4bd610d","html_url":"https://github.com/TimeWarpEngineering/timewarp-nuru","commit_stats":null,"previous_names":["timewarpengineering/timewarp-nuru"],"tags_count":73,"template":false,"template_full_name":null,"purl":"pkg:github/TimeWarpEngineering/timewarp-nuru","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeWarpEngineering%2Ftimewarp-nuru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeWarpEngineering%2Ftimewarp-nuru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeWarpEngineering%2Ftimewarp-nuru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeWarpEngineering%2Ftimewarp-nuru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimeWarpEngineering","download_url":"https://codeload.github.com/TimeWarpEngineering/timewarp-nuru/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeWarpEngineering%2Ftimewarp-nuru/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28755561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T16:32:25.380Z","status":"ssl_error","status_checked_at":"2026-01-25T16:32:09.189Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-30T13:22:33.345Z","updated_at":"2026-01-25T17:01:00.478Z","avatar_url":"https://github.com/TimeWarpEngineering.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TimeWarp.Nuru\n\n\u003cdiv align=\"center\"\u003e\n\n[![NuGet Version](https://img.shields.io/nuget/v/TimeWarp.Nuru.svg)](https://www.nuget.org/packages/TimeWarp.Nuru/)\n[![NuGet Downloads](https://img.shields.io/nuget/dt/TimeWarp.Nuru.svg)](https://www.nuget.org/packages/TimeWarp.Nuru/)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/TimeWarpEngineering/timewarp-nuru/build.yml?branch=master)](https://github.com/TimeWarpEngineering/timewarp-nuru/actions)\n[![License](https://img.shields.io/github/license/TimeWarpEngineering/timewarp-nuru.svg)](https://github.com/TimeWarpEngineering/timewarp-nuru/blob/master/LICENSE)\n\n**Route-based CLI framework for .NET - bringing web-style routing to command-line applications**\n\n\u003c/div\u003e\n\n\u003e **Nuru** means \"light\" in Swahili - illuminating the path to your commands with clarity and simplicity.\n\n## 📦 Installation\n\n```bash\ndotnet add package TimeWarp.Nuru\n```\n\n## 🚀 Quick Start\n\nTimeWarp.Nuru offers two first-class patterns for defining CLI commands:\n\n### Fluent DSL\n\nDefine routes inline with a fluent builder API:\n\n```csharp\nusing TimeWarp.Nuru;\n\nNuruApp app = NuruApp.CreateBuilder(args)\n  .Map(\"add {x:double} {y:double}\")\n    .WithHandler((double x, double y) =\u003e Console.WriteLine($\"{x} + {y} = {x + y}\"))\n    .AsCommand()\n    .Done()\n  .Build();\n\nreturn await app.RunAsync(args);\n```\n\n### Endpoints Routes\n\nDefine routes as classes with `[NuruRoute]` attributes:\n\n```csharp\nusing TimeWarp.Nuru;\n\n// Program.cs - minimal setup\nNuruApp app = NuruApp.CreateBuilder(args)\n  .Build();\n\nreturn await app.RunAsync(args);\n\n// AddCommand.cs - auto-discovered by source generator\n[NuruRoute(\"add\", Description = \"Add two numbers together\")]\npublic sealed class AddCommand : ICommand\u003cUnit\u003e\n{\n  [Parameter(Order = 0)]\n  public double X { get; set; }\n\n  [Parameter(Order = 1)]\n  public double Y { get; set; }\n\n  public sealed class Handler : ICommandHandler\u003cAddCommand, Unit\u003e\n  {\n    public ValueTask\u003cUnit\u003e Handle(AddCommand command, CancellationToken ct)\n    {\n      Console.WriteLine($\"{command.X} + {command.Y} = {command.X + command.Y}\");\n      return default;\n    }\n  }\n}\n```\n\n```bash\ndotnet run -- add 15 25\n# Output: 15 + 25 = 40\n```\n\n**→ [Full Getting Started Guide](documentation/user/getting-started.md)**\n\n## ✨ Key Features\n\n| Feature | Description | Learn More |\n|---------|-------------|------------|\n| 🎯 **Web-Style Routing** | Familiar `\"deploy {env} --version {tag}\"` syntax | [Routing Guide](documentation/user/features/routing.md) |\n| ⚡ **Dual Approach** | Mix Direct (fast) + Mediator (structured) | [Architecture Choices](documentation/user/guides/architecture-choices.md) |\n| 🛡️ **Roslyn Analyzer** | Catch route errors at compile-time | [Analyzer Docs](documentation/user/features/analyzer.md) |\n| ⌨️ **Shell Completion** | Tab completion for bash, zsh, PowerShell, fish | [Shell Completion](#-shell-completion) |\n| 🤖 **MCP Server** | AI-assisted development with Claude | [MCP Server Guide](documentation/user/tools/mcp-server.md) |\n| 📊 **Logging Package** | Zero-overhead structured logging | [Logging Docs](documentation/user/features/logging.md) |\n| 🚀 **Native AOT** | Zero warnings, 3.3 MB binaries, instant startup | [Deployment Guide](documentation/user/guides/deployment.md#native-aot-compilation) |\n| 🔒 **Type-Safe Parameters** | Automatic type conversion and validation | [Supported Types](documentation/user/reference/supported-types.md) |\n| 📖 **Auto-Help** | Generate help from route patterns | [Auto-Help Feature](documentation/user/features/auto-help.md) |\n| 🎨 **Colored Output** | Fluent ANSI colors without Spectre.Console | [Terminal Abstractions](documentation/user/features/terminal-abstractions.md) |\n\n## 📚 Documentation\n\n### Getting Started\n- **[Getting Started Guide](documentation/user/getting-started.md)** - Build your first CLI app in 5 minutes\n- **[Use Cases](documentation/user/use-cases.md)** - Greenfield apps \u0026 progressive enhancement patterns\n- **[Architecture Choices](documentation/user/guides/architecture-choices.md)** - Choose Direct, Mediator, or Mixed\n\n### Core Features\n- **[Routing Patterns](documentation/user/features/routing.md)** - Complete route syntax reference\n- **[Roslyn Analyzer](documentation/user/features/analyzer.md)** - Compile-time validation\n- **[Logging System](documentation/user/features/logging.md)** - Structured logging setup\n- **[Auto-Help](documentation/user/features/auto-help.md)** - Automatic help generation\n- **[Output Handling](documentation/user/features/output-handling.md)** - stdout/stderr best practices\n- **[Terminal Abstractions](documentation/user/features/terminal-abstractions.md)** - Testable I/O \u0026 colored output\n\n### Tools \u0026 Deployment\n- **[MCP Server](documentation/user/tools/mcp-server.md)** - AI-powered development assistance\n- **[Deployment Guide](documentation/user/guides/deployment.md)** - Native AOT, runfiles, distribution\n- **[Best Practices](documentation/user/guides/best-practices.md)** - Patterns for maintainable CLIs\n\n### Reference\n- **[Performance Benchmarks](documentation/user/reference/performance.md)** - Detailed performance metrics\n- **[Supported Types](documentation/user/reference/supported-types.md)** - Complete type reference\n- **[API Documentation](documentation/user/reference/)** - Technical reference\n\n## 🎯 Two Powerful Use Cases\n\n### 🆕 Greenfield CLI Applications\nBuild modern command-line tools from scratch:\n\n```csharp\nNuruApp app = NuruApp.CreateBuilder(args)\n  .Map(\"deploy {env} --version {tag?}\")\n    .WithHandler((string env, string? tag) =\u003e Deploy(env, tag))\n    .AsCommand()\n    .Done()\n  .Map(\"backup {source} {dest?} --compress\")\n    .WithHandler((string source, string? dest, bool compress) =\u003e Backup(source, dest, compress))\n    .AsCommand()\n    .Done()\n  .Build();\n```\n\n### 🔄 Progressive Enhancement\nWrap existing CLIs to add auth, logging, or validation:\n\n```csharp\nNuruApp app = NuruApp.CreateBuilder(args)\n  .Map(\"deploy prod\")\n    .WithHandler(async () =\u003e\n    {\n      if (!await ValidateAccess()) return 1;\n      return await Shell.ExecuteAsync(\"existing-cli\", \"deploy\", \"prod\");\n    })\n    .AsCommand()\n    .Done()\n  .Map(\"{*args}\")\n    .WithHandler(async (string[] args) =\u003e await Shell.ExecuteAsync(\"existing-cli\", args))\n    .AsCommand()\n    .Done()\n  .Build();\n```\n\n**→ [Detailed Use Cases with Examples](documentation/user/use-cases.md)**\n\n## 🌟 Working Examples\n\n**[Calculator Samples](samples/02-calculator/)** - Three complete implementations you can run now:\n- **[01-calc-delegate.cs](samples/02-calculator/01-calc-delegate.cs)** - Fluent DSL approach (inline handlers)\n- **[02-calc-commands.cs](samples/02-calculator/02-calc-commands.cs)** - Endpoints routes pattern (testable, DI)\n- **[03-calc-mixed.cs](samples/02-calculator/03-calc-mixed.cs)** - Mixed approach (both patterns together)\n\n```bash\n./samples/02-calculator/03-calc-mixed.cs add 10 20        # Fluent DSL: inline\n./samples/02-calculator/03-calc-mixed.cs factorial 5      # Endpoints: structured\n```\n\n**[AOT Example](samples/05-aot-example/)** - Native AOT compilation with source generators\n\n## ⚡ Performance\n\n| Implementation | Memory | Speed (37 tests) | Binary Size |\n|----------------|--------|------------------|-------------|\n| Direct (JIT) | ~4 KB | 2.49s | N/A |\n| Direct (AOT) | ~4 KB | **0.30s** 🚀 | 3.3 MB |\n| Mediator (AOT) | Moderate | **0.42s** 🚀 | 4.8 MB |\n\n**Native AOT is 88-93% faster than JIT** → [Full Performance Benchmarks](documentation/user/reference/performance.md)\n\n## 🤖 AI-Powered Development\n\nInstall the MCP server for AI assistance:\n\n```bash\ndotnet tool install --global TimeWarp.Nuru.Mcp\n```\n\nGet instant help in Claude Code, Roo Code, or Continue:\n- Validate route patterns before writing code\n- Generate handler code automatically\n- Get syntax examples on demand\n- Real-time error guidance\n\n**→ [MCP Server Setup Guide](documentation/user/tools/mcp-server.md)**\n\n## ⌨️ Shell Completion\n\nEnable tab completion for your CLI with one line of code:\n\n```csharp\nNuruApp app = NuruApp.CreateBuilder(args)\n  .Map(\"deploy {env} --version {tag}\")\n    .WithHandler((string env, string tag) =\u003e Deploy(env, tag))\n    .AsCommand()\n    .Done()\n  .Map(\"status\")\n    .WithHandler(() =\u003e ShowStatus())\n    .AsQuery()\n    .Done()\n  .EnableStaticCompletion()  // ← Add this\n  .Build();\n```\n\nGenerate completion scripts for your shell:\n\n```bash\n# Bash\n./myapp --generate-completion bash \u003e\u003e ~/.bashrc\n\n# Zsh\n./myapp --generate-completion zsh \u003e\u003e ~/.zshrc\n\n# PowerShell\n./myapp --generate-completion powershell \u003e\u003e $PROFILE\n\n# Fish\n./myapp --generate-completion fish \u003e ~/.config/fish/completions/myapp.fish\n```\n\n**Supports:**\n- ✅ Command completion (`deploy`, `status`)\n- ✅ Option completion (`--version`, `--force`)\n- ✅ Short option aliases (`-v`, `-f`)\n- ✅ All 4 major shells (bash, zsh, PowerShell, fish)\n\n**See [completion-example](samples/15-completion/) for a complete working example.**\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n**For Contributors:**\n- **[Developer Documentation](documentation/developer/overview.md)** - Architecture and design\n- **[Standards](documentation/developer/standards/)** - Coding conventions\n\n## 📄 License\n\nThis project is licensed under the Unlicense - see the [license](license) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Ready to build powerful CLI applications?**\n\n**[Get Started in 5 Minutes](documentation/user/getting-started.md)** • **[View Examples](samples/02-calculator/)** • **[Read the Docs](documentation/user/overview.md)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimewarpengineering%2Ftimewarp-nuru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimewarpengineering%2Ftimewarp-nuru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimewarpengineering%2Ftimewarp-nuru/lists"}