Add CLI utilities as native commands with multiple distribution methods

[StevenTCramer]

Summary

Add common CLI utilities as native commands in Amuru with multiple distribution methods to support different use cases across TimeWarp projects.

Background

Several small CLI utilities are currently used across multiple TimeWarp repositories:

• convert-timestamp - Converts Unix timestamps to human-readable dates
• generate-avatar - Generates avatar images
• generate-color - Generates color values/schemes
• multiavatar - Multi-style avatar generation
• post - Blog/blip posting tool
• ssh-key-helper - SSH key management utility

These tools are currently:

• Living in private repos (limiting CI/CD usage)
• Duplicated across projects
• Deployed as individual executables from PATH locally

Problem

Build agents and CI/CD pipelines need access to these tools, but:

• Can't access private repos
• Don't have the executables in PATH
• Duplicating source across repos is a maintenance burden

Use Cases to Support

1. Library Usage in C# Scripts

Developers writing .NET 10 single-file apps want to call these utilities as static methods via native commands pattern:

#:package TimeWarp.Amuru@1.0.0

using TimeWarp.Amuru.Native.Utilities;

var timestamp = 1234567890;
string date = ConvertTimestamp.FromUnix(timestamp);
string avatar = GenerateAvatar.FromEmail("user@example.com");

2. Command-Line Usage

Developers and CI/CD need command-line access:

timewarp convert-timestamp --GitCommitTimestamp 1234567890
timewarp generate-avatar --email user@example.com
timewarp ssh-key-helper --generate
timewarp post --title "New Release" --content "content.md"

3. Standalone Binary Usage

CI/CD pipelines that need minimal dependencies:

# Download just what's needed, no .NET SDK required
curl -L https://github.com/TimeWarpEngineering/timewarp-amuru/releases/latest/download/convert-timestamp-linux-x64 -o convert-timestamp
./convert-timestamp --GitCommitTimestamp $TIMESTAMP

4. MSBuild Integration

Build scripts need to call these during compilation:

<Exec Command="convert-timestamp --GitCommitTimestamp $(GitCommitTimestamp)" ConsoleToMSBuild="true">
  <Output TaskParameter="ConsoleOutput" PropertyName="CommitDate"/>
</Exec>

Proposed Approach

1. Extend Amuru library with these utilities as native commands following the existing pattern (e.g., TimeWarp.Amuru.Native.Utilities namespace)
2. Create a separate .NET tool package TimeWarp.Amuru.Tool to avoid library/tool conflicts
3. Publish standalone executables for each command for zero-dependency usage
4. Single source of truth in the public Amuru repository

Benefits

• Public accessibility for CI/CD pipelines
• Multiple consumption patterns for different scenarios
• Single maintenance point instead of duplicating across repos
• Natural fit - Amuru is already a shell/CLI utility library with native commands pattern
• Versioned distribution via NuGet and GitHub releases
• Consistent with existing Amuru patterns for native commands

Success Criteria

• Can install via dotnet tool install TimeWarp.Amuru.Tool for command-line usage
• Can reference via NuGet package for library usage with static method calls
• Can download individual executables for minimal CI/CD usage
• All tools work cross-platform (Windows, Linux, macOS)
• Build agents can easily access these tools without private repo access