clispark 1.14.0 → 1.16.0

package/templates/dotnet/README.md

@@ -0,0 +1,45 @@
+# {{projectName}}
+
+Generated with [clispark](https://github.com/martinwichner/clispark).
+
+## Requirements
+
+.NET SDK **10.0** or later.
+
+## Building and running
+
+```bash
+dotnet build Cli.slnx
+dotnet run --project src -- hello World
+```
+
+Or install it as a global tool on your own machine:
+
+```bash
+dotnet pack src -c Release -o ./nupkg
+dotnet tool install -g {{projectName}} --add-source ./nupkg
+{{projectName}} hello World
+```
+
+## Example commands
+
+Four example commands ship in `src/Commands/` as copy-paste starting points:
+
+- **`hello`** (`src/Commands/HelloCommand.cs`) — the minimal case: one required string argument.
+  ```bash
+  dotnet run --project src -- hello World
+  ```
+- **`task`** / **`task list`** / **`task complete`** (`src/Commands/TaskCommand.cs`, `TaskListCommand.cs`, `TaskCompleteCommand.cs`) — a reference for `System.CommandLine`'s argument and subcommand patterns: an optional allowed-values argument, a nested subcommand with a string + boolean pair, and a required integer argument that demonstrates the `CliUserException` error path.
+  ```bash
+  dotnet run --project src -- task open
+  dotnet run --project src -- task list groceries true
+  dotnet run --project src -- task complete 1
+  ```
+  See `ARCHITECTURE.md`'s "Argument Types" section for details.
+
+## Logging & debugging
+
+Every command run writes a structured log file (one per invocation, in an OS-appropriate log directory — see `ARCHITECTURE.md`'s "Logging" section). By default the terminal only shows a clean `Error: <message>` on failure, or nothing on success.
+
+- **`DEBUG=1`** — streams the raw log lines to stdout live as the command runs, and prints `Details: <path>` to the log file on both success and failure (normally that line only appears on failure).
+- Fields that look like secrets (`password`, `token`, `apiKey`, etc. — see `SensitiveKeys` in `src/Logging/CliLoggerFactory.cs`) are redacted from log output automatically; edit that list directly in your own copy if you log other sensitive fields.

package/templates/dotnet/gitignore

@@ -0,0 +1,4 @@
+bin/
+obj/
+*.user
+.vs/

package/templates/dotnet/src/Cli.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <RootNamespace>Cli</RootNamespace>
+    <AssemblyName>{{projectName}}</AssemblyName>
+    <Version>0.0.0</Version>
+    <PackAsTool>true</PackAsTool>
+    <ToolCommandName>{{projectName}}</ToolCommandName>
+    <PackageId>{{projectName}}</PackageId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.CommandLine" Version="2.0.10" />
+    <PackageReference Include="Serilog" Version="4.4.0" />
+    <PackageReference Include="Serilog.Sinks.File" Version="7.0.0" />
+    <PackageReference Include="Serilog.Sinks.Console" Version="6.1.1" />
+    <PackageReference Include="Xdg.Directories" Version="0.1.2" />
+  </ItemGroup>
+
+</Project>

package/templates/dotnet/src/CliUserException.cs

@@ -0,0 +1,4 @@
+namespace Cli;
+
+/// <summary>An expected, user-fixable failure — distinct from an unexpected crash. Mirrors clispark's own UserError.</summary>
+public sealed class CliUserException(string message) : Exception(message);

package/templates/dotnet/src/CommandDiscovery.cs

@@ -0,0 +1,48 @@
+using System.CommandLine;
+using System.Reflection;
+
+namespace Cli;
+
+public static class CommandDiscovery
+{
+    /// <summary>
+    /// Scans the given assembly for every ICliCommand, reads its CommandPathAttribute,
+    /// and attaches it to the tree rooted at <paramref name="root"/> — creating bare
+    /// container commands for any missing intermediate path segments.
+    /// </summary>
+    public static void RegisterAll(RootCommand root, Assembly assembly)
+    {
+        var commandTypes = assembly
+            .GetTypes()
+            .Where(t => t is { IsClass: true, IsAbstract: false } && typeof(ICliCommand).IsAssignableFrom(t));
+
+        foreach (var type in commandTypes)
+        {
+            var attribute = type.GetCustomAttribute<CommandPathAttribute>()
+                ?? throw new InvalidOperationException($"{type.FullName} implements ICliCommand but has no [CommandPath].");
+
+            var instance = (ICliCommand)Activator.CreateInstance(type)!;
+            var command = instance.Build();
+
+            var segments = attribute.Path.Split(' ', StringSplitOptions.RemoveEmptyEntries);
+            var parent = FindOrCreateParent(root, segments[..^1]);
+            parent.Subcommands.Add(command);
+        }
+    }
+
+    private static Command FindOrCreateParent(RootCommand root, string[] parentSegments)
+    {
+        Command current = root;
+        foreach (var segment in parentSegments)
+        {
+            var existing = current.Subcommands.FirstOrDefault(c => c.Name == segment);
+            if (existing is null)
+            {
+                existing = new Command(segment);
+                current.Subcommands.Add(existing);
+            }
+            current = existing;
+        }
+        return current;
+    }
+}

package/templates/dotnet/src/CommandPathAttribute.cs

@@ -0,0 +1,12 @@
+namespace Cli;
+
+/// <summary>
+/// Declares the full, space-separated invocation path for an <see cref="ICliCommand"/>
+/// (e.g. "task list" for a "list" subcommand nested under "task"). The class name alone
+/// cannot express nesting, so this is required on every discovered command.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class)]
+public sealed class CommandPathAttribute(string path) : Attribute
+{
+    public string Path { get; } = path;
+}

package/templates/dotnet/src/Commands/HelloCommand.cs

@@ -0,0 +1,28 @@
+using System.CommandLine;
+using Serilog;
+
+namespace Cli.Commands;
+
+/// <summary>Required string argument.</summary>
+[CommandPath("hello")]
+public sealed class HelloCommand : ICliCommand
+{
+    public Command Build()
+    {
+        var nameArgument = new Argument<string>("name")
+        {
+            Description = "Who to greet",
+        };
+
+        var command = new Command("hello", "Says hello to someone");
+        command.Arguments.Add(nameArgument);
+        command.SetAction(parseResult =>
+        {
+            var name = parseResult.GetValue(nameArgument);
+            Log.Information("Greeting {Name}", name);
+            Console.WriteLine($"Hello, {name}!");
+        });
+
+        return command;
+    }
+}

package/templates/dotnet/src/Commands/TaskCommand.cs

@@ -0,0 +1,28 @@
+using System.CommandLine;
+
+namespace Cli.Commands;
+
+/// <summary>Optional argument constrained to a fixed set of allowed values.</summary>
+[CommandPath("task")]
+public sealed class TaskCommand : ICliCommand
+{
+    public Command Build()
+    {
+        var statusArgument = new Argument<string?>("status")
+        {
+            Description = "Filter by status",
+            Arity = ArgumentArity.ZeroOrOne,
+        };
+        statusArgument.AcceptOnlyFromAmong("open", "done");
+
+        var command = new Command("task", "Shows tasks, optionally filtered by status");
+        command.Arguments.Add(statusArgument);
+        command.SetAction(parseResult =>
+        {
+            var status = parseResult.GetValue(statusArgument);
+            Console.WriteLine(status is null ? "Showing all tasks" : $"Showing {status} tasks");
+        });
+
+        return command;
+    }
+}

package/templates/dotnet/src/Commands/TaskCompleteCommand.cs

@@ -0,0 +1,30 @@
+using System.CommandLine;
+
+namespace Cli.Commands;
+
+/// <summary>Nested subcommand ("task complete") with a required integer argument. Demonstrates CliUserException.</summary>
+[CommandPath("task complete")]
+public sealed class TaskCompleteCommand : ICliCommand
+{
+    public Command Build()
+    {
+        var idArgument = new Argument<int>("id")
+        {
+            Description = "Task ID to complete",
+        };
+
+        var command = new Command("complete", "Marks a task as complete");
+        command.Arguments.Add(idArgument);
+        command.SetAction(parseResult =>
+        {
+            var id = parseResult.GetValue(idArgument);
+            if (id <= 0)
+            {
+                throw new CliUserException($"Task {id} does not exist.");
+            }
+            Console.WriteLine($"Completed task {id}");
+        });
+
+        return command;
+    }
+}

package/templates/dotnet/src/Commands/TaskListCommand.cs

@@ -0,0 +1,34 @@
+using System.CommandLine;
+
+namespace Cli.Commands;
+
+/// <summary>Nested subcommand ("task list") with two optional arguments: string + boolean.</summary>
+[CommandPath("task list")]
+public sealed class TaskListCommand : ICliCommand
+{
+    public Command Build()
+    {
+        var labelArgument = new Argument<string?>("label")
+        {
+            Description = "Filter by label",
+            Arity = ArgumentArity.ZeroOrOne,
+        };
+        var allArgument = new Argument<bool?>("all")
+        {
+            Description = "Include completed tasks",
+            Arity = ArgumentArity.ZeroOrOne,
+        };
+
+        var command = new Command("list", "Lists tasks");
+        command.Arguments.Add(labelArgument);
+        command.Arguments.Add(allArgument);
+        command.SetAction(parseResult =>
+        {
+            var label = parseResult.GetValue(labelArgument);
+            var all = parseResult.GetValue(allArgument) ?? false;
+            Console.WriteLine($"Listing tasks (label={label ?? "any"}, all={all})");
+        });
+
+        return command;
+    }
+}

package/templates/dotnet/src/ICliCommand.cs

@@ -0,0 +1,8 @@
+using System.CommandLine;
+
+namespace Cli;
+
+public interface ICliCommand
+{
+    Command Build();
+}

package/templates/dotnet/src/Logging/CliLoggerFactory.cs

@@ -0,0 +1,70 @@
+using Serilog;
+using Serilog.Core;
+using Xdg.Directories;
+
+namespace Cli.Logging;
+
+public static class CliLoggerFactory
+{
+    private static readonly string[] SensitiveKeys = ["password", "secret", "token", "apiKey", "registryUrl"];
+    private const int RetentionDays = 14;
+    private const string SweepMarkerFile = ".last-sweep";
+    private static readonly TimeSpan SweepThrottle = TimeSpan.FromHours(24);
+
+    public static (Logger Logger, string LogFilePath) Create(string commandName, string appName)
+    {
+        var logDir = Path.Combine(BaseDirectory.StateHome, appName, "Log");
+        Directory.CreateDirectory(logDir);
+        SweepOldLogs(logDir);
+
+        var timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH-mm-ss-fffZ");
+        var suffix = Guid.NewGuid().ToString("N")[..6];
+        var logFilePath = Path.Combine(logDir, $"{commandName}-{timestamp}-{suffix}.log");
+
+        var config = new LoggerConfiguration()
+            .Enrich.With(new SensitivePropertyEnricher(SensitiveKeys))
+            .WriteTo.File(logFilePath);
+
+        if (Environment.GetEnvironmentVariable("DEBUG") is not null)
+        {
+            config = config.WriteTo.Console();
+        }
+
+        var logger = config.CreateLogger();
+
+        if (!OperatingSystem.IsWindows())
+        {
+            File.SetUnixFileMode(logFilePath, UnixFileMode.UserRead | UnixFileMode.UserWrite);
+        }
+
+        return (logger, logFilePath);
+    }
+
+    private static void SweepOldLogs(string logDir)
+    {
+        try
+        {
+            var markerPath = Path.Combine(logDir, SweepMarkerFile);
+            if (File.Exists(markerPath) && DateTime.UtcNow - File.GetLastWriteTimeUtc(markerPath) < SweepThrottle)
+            {
+                return;
+            }
+
+            var cutoff = DateTime.UtcNow.AddDays(-RetentionDays);
+            foreach (var file in Directory.GetFiles(logDir))
+            {
+                if (Path.GetFileName(file) == SweepMarkerFile) continue;
+                if (File.GetLastWriteTimeUtc(file) < cutoff)
+                {
+                    File.Delete(file);
+                }
+            }
+
+            File.WriteAllText(markerPath, string.Empty);
+        }
+        catch
+        {
+            // best-effort; a sweep failure must never affect the surrounding command
+        }
+    }
+}

package/templates/dotnet/src/Logging/SensitivePropertyEnricher.cs

@@ -0,0 +1,19 @@
+using Serilog.Core;
+using Serilog.Events;
+
+namespace Cli.Logging;
+
+/// <summary>Masks known sensitive property names before they reach any sink. Mirrors the Node template's SENSITIVE_LOG_KEYS/pino redact.</summary>
+public sealed class SensitivePropertyEnricher(IReadOnlyCollection<string> sensitiveKeys) : ILogEventEnricher
+{
+    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
+    {
+        foreach (var actualKey in logEvent.Properties.Keys.ToList())
+        {
+            if (sensitiveKeys.Any(k => string.Equals(k, actualKey, StringComparison.OrdinalIgnoreCase)))
+            {
+                logEvent.AddOrUpdateProperty(propertyFactory.CreateProperty(actualKey, "***REDACTED***"));
+            }
+        }
+    }
+}

package/templates/dotnet/src/Program.cs

@@ -0,0 +1,35 @@
+using System.CommandLine;
+using System.Reflection;
+using Cli;
+using Cli.Logging;
+using Serilog;
+
+var commandName = args.Length > 0 ? args[0] : "cli";
+var (logger, logFilePath) = CliLoggerFactory.Create(commandName, "{{projectName}}");
+Log.Logger = logger;
+
+var root = new RootCommand("Interactive scaffolded CLI project");
+CommandDiscovery.RegisterAll(root, Assembly.GetExecutingAssembly());
+
+var config = new InvocationConfiguration { EnableDefaultExceptionHandler = false };
+
+try
+{
+    var exitCode = root.Parse(args).Invoke(config);
+    if (Environment.GetEnvironmentVariable("DEBUG") is not null)
+    {
+        Console.WriteLine($"Details: {logFilePath}");
+    }
+    return exitCode;
+}
+catch (CliUserException ex)
+{
+    Log.Error(ex, "Command failed");
+    Console.Error.WriteLine($"\nError: {ex.Message}");
+    Console.Error.WriteLine($"Details: {logFilePath}");
+    return 1;
+}
+finally
+{
+    Log.CloseAndFlush();
+}

package/templates/dotnet/tests/Cli.Tests.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\src\Cli.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/dotnet/tests/HelloCommandTests.cs

@@ -0,0 +1,28 @@
+using Cli.Commands;
+
+namespace Cli.Tests;
+
+public class HelloCommandTests
+{
+    [Fact]
+    public void SucceedsWithARequiredNameArgument()
+    {
+        var command = new HelloCommand().Build();
+        var parseResult = command.Parse(["World"]);
+
+        var exitCode = parseResult.Invoke();
+
+        Assert.Equal(0, exitCode);
+    }
+
+    [Fact]
+    public void FailsWhenNameArgumentIsMissing()
+    {
+        var command = new HelloCommand().Build();
+        var parseResult = command.Parse([]);
+
+        var exitCode = parseResult.Invoke();
+
+        Assert.NotEqual(0, exitCode);
+    }
+}

package/templates/dotnet/tests/TaskCompleteCommandTests.cs

@@ -0,0 +1,34 @@
+using System.CommandLine;
+using Cli;
+using Cli.Commands;
+
+namespace Cli.Tests;
+
+public class TaskCompleteCommandTests
+{
+    // Mirrors Program.cs: the default InvocationConfiguration silently swallows
+    // exceptions thrown from a command's action, so tests exercising that
+    // behavior must disable it the same way production wiring does.
+    private static readonly InvocationConfiguration NonSwallowingConfig = new() { EnableDefaultExceptionHandler = false };
+
+    [Fact]
+    public void ThrowsCliUserExceptionForNonPositiveId()
+    {
+        var command = new TaskCompleteCommand().Build();
+        var parseResult = command.Parse(["-1"]);
+
+        var ex = Assert.Throws<CliUserException>(() => parseResult.Invoke(NonSwallowingConfig));
+        Assert.Equal("Task -1 does not exist.", ex.Message);
+    }
+
+    [Fact]
+    public void SucceedsForPositiveId()
+    {
+        var command = new TaskCompleteCommand().Build();
+        var parseResult = command.Parse(["5"]);
+
+        var exitCode = parseResult.Invoke(NonSwallowingConfig);
+
+        Assert.Equal(0, exitCode);
+    }
+}