Merge pull request #34 from tui-cs/release/v0.3.0

Release v0.3.0

Author: tig

Directory.Build.props

@@ -8,13 +8,13 @@
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
 
-    <Authors>gui-cs</Authors>
-    <Company>gui-cs</Company>
-    <Copyright>Copyright (c) gui-cs and contributors</Copyright>
+    <Authors>tui-cs</Authors>
+    <Company>tui-cs</Company>
+    <Copyright>Copyright (c) tui-cs and contributors</Copyright>
 
     <Version>0.2.1-develop</Version>
-    <PackageProjectUrl>https://github.com/gui-cs/cli</PackageProjectUrl>
-    <RepositoryUrl>https://github.com/gui-cs/cli</RepositoryUrl>
+    <PackageProjectUrl>https://github.com/tui-cs/cli</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/tui-cs/cli</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
     <PackageLicenseFile>LICENSE</PackageLicenseFile>
 

README.md

@@ -3,7 +3,7 @@
 [![NuGet](https://img.shields.io/nuget/vpre/Terminal.Gui.Cli)](https://www.nuget.org/packages/Terminal.Gui.Cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-> A .NET library that turns [Terminal.Gui](https://github.com/gui-cs/Terminal.Gui) apps into scriptable CLI tools — with typed JSON output, POSIX exit codes, and built-in AI-agent discoverability.
+> A .NET library that turns [Terminal.Gui](https://github.com/tui-cs/Terminal.Gui) apps into scriptable CLI tools — with typed JSON output, POSIX exit codes, and built-in AI-agent discoverability.
 
 ![Terminal.Gui.Cli in action](docs/images/hero.gif)
 

scripts/HERO-GIF.md

@@ -4,7 +4,7 @@ Produces `docs/images/hero.gif` — an animated GIF demonstrating the example ap
 
 ## Prerequisites
 
-- [tuirec](https://github.com/gui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/gui-cs/tuirec/cmd/tuirec@latest`)
+- [tuirec](https://github.com/tui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/tui-cs/tuirec/cmd/tuirec@latest`)
 - .NET 10 SDK (for building the example app)
 - PowerShell 7+ (`pwsh`) on PATH
 - `agg` is auto-downloaded by tuirec on first use

specs/constitution.md

@@ -1,8 +1,8 @@
-# gui-cs/cli Constitution
+# tui-cs/cli Constitution
 
 **Version**: 1.1 | **Ratified**: 2026-05-23 | **Last Amended**: 2026-05-23
 
-This constitution governs all contributions to `gui-cs/cli`. It is the highest-authority engineering document in this repository.
+This constitution governs all contributions to `tui-cs/cli`. It is the highest-authority engineering document in this repository.
 
 ## I. Purpose & Scope
 

specs/library-spec.md

@@ -38,8 +38,13 @@ resolve to a registered command. When set, `CliHost` routes to that command in t
 - The leading token is not a recognized command alias.
 
 In each case the host re-parses `[DefaultCommand, ..args]` against the resolved default
-command, so bare positional args and unrecognized options are retried as args to it. If
-`DefaultCommand` names an alias that is not registered, the host emits
+command, so bare positional args and unrecognized options are retried as args to it. The
+reparse uses `ArgParser.Parse(args, command, unknownOptionsAsArguments: true)`: dash-prefixed
+tokens that match no framework, global, or default-command option pass through verbatim as
+positional arguments (e.g. `app --literal` and `app Alice --suffix` reach the default command
+as positionals), while recognized options still parse as options. If the default command does
+not accept positional args, leftover tokens still produce the usual positional-args usage
+error. If `DefaultCommand` names an alias that is not registered, the host emits
 `Default command '<name>' is not registered.` and returns a usage error. When
 `DefaultCommand` is null, the original parse/usage-error behavior is preserved.
 

src/Terminal.Gui.Cli/ArgParser.cs

@@ -29,7 +29,22 @@ public ArgParser (List<GlobalOptionDescriptor> globalOptions, int maxInitialChar
     }
 
     /// <summary>Parses command-line arguments, optionally validating against a resolved command.</summary>
+    /// <param name="args">The raw command-line arguments.</param>
+    /// <param name="command">The resolved command to validate options against, when known.</param>
     public ParseResult Parse (string[] args, ICliCommand? command = null)
+    {
+        return Parse (args, command, false);
+    }
+
+    /// <summary>Parses command-line arguments, optionally validating against a resolved command.</summary>
+    /// <param name="args">The raw command-line arguments.</param>
+    /// <param name="command">The resolved command to validate options against, when known.</param>
+    /// <param name="unknownOptionsAsArguments">
+    ///     When true, dash-prefixed tokens that match no framework, global, or command option are passed
+    ///     through verbatim as positional arguments instead of failing the parse. Used by the
+    ///     default-command fallback so original tokens reach the default command (issue #30).
+    /// </param>
+    public ParseResult Parse (string[] args, ICliCommand? command, bool unknownOptionsAsArguments)
     {
         ArgumentNullException.ThrowIfNull (args);
 
@@ -130,6 +145,13 @@ public ParseResult Parse (string[] args, ICliCommand? command = null)
                 continue;
             }
 
+            if (unknownOptionsAsArguments)
+            {
+                arguments.Add (token);
+                index++;
+                continue;
+            }
+
             return ParseResult.Fail ($"Unknown option '{token}'.");
         }
 

src/Terminal.Gui.Cli/CliHost.cs

@@ -90,7 +90,11 @@ private async Task<int> RunWithDefaultCommandAsync (
         }
 
         string[] adjusted = [_options.DefaultCommand!, .. args];
-        ArgParser.ParseResult parse = _parser.Parse (adjusted, defaultCmd);
+
+        // The fallback fires precisely because the original tokens didn't resolve to a known
+        // command/options, so unknown dash-prefixed tokens must pass through verbatim as
+        // positional arguments rather than failing the reparse (issue #30).
+        ArgParser.ParseResult parse = _parser.Parse (adjusted, defaultCmd, true);
 
         if (!parse.Success || parse.Options is null)
         {

tests/Terminal.Gui.Cli.IntegrationTests/GreetExampleTests.cs

@@ -94,6 +94,54 @@ public async Task DefaultCommand_NoArgs_GreetsWorld ()
         Assert.Equal (ExitCodes.Ok, exitCode);
     }
 
+    [Fact]
+    public async Task DefaultCommand_DashPrefixedToken_PassesThroughAsPositionalArg ()
+    {
+        CliHost host = CreateGreetHost ();
+        using StringWriter stdout = new ();
+        using StringWriter stderr = new ();
+
+        // "--literal" is not a recognized option anywhere; the default-command fallback
+        // must pass it through verbatim as a positional argument (issue #30).
+        var exitCode = await host.RunAsync (["--literal"], TestContext.Current.CancellationToken, stdout, stderr);
+
+        Assert.Equal (ExitCodes.Ok, exitCode);
+        Assert.Contains ("Hello, --literal!", stdout.ToString ());
+        Assert.Equal (string.Empty, stderr.ToString ());
+    }
+
+    [Fact]
+    public async Task DefaultCommand_PositionalThenUnknownOption_PassesBothThroughAsArgs ()
+    {
+        CliHost host = CreateGreetHost ();
+        using StringWriter stdout = new ();
+        using StringWriter stderr = new ();
+
+        var exitCode = await host.RunAsync (["Alice", "--suffix"], TestContext.Current.CancellationToken, stdout,
+            stderr);
+
+        Assert.Equal (ExitCodes.Ok, exitCode);
+        Assert.Contains ("Hello, Alice --suffix!", stdout.ToString ());
+        Assert.Equal (string.Empty, stderr.ToString ());
+    }
+
+    [Fact]
+    public async Task DefaultCommand_RecognizedOptionInFallback_StillParsesAsOption ()
+    {
+        CliHost host = CreateGreetHost ();
+        using StringWriter stdout = new ();
+        using StringWriter stderr = new ();
+
+        // "--formal" is a declared option of the default command; the fallback must
+        // still parse it as an option, not a positional argument.
+        var exitCode = await host.RunAsync (["Alice", "--formal"], TestContext.Current.CancellationToken, stdout,
+            stderr);
+
+        Assert.Equal (ExitCodes.Ok, exitCode);
+        Assert.Contains ("Good day, Alice.", stdout.ToString ());
+        Assert.Equal (string.Empty, stderr.ToString ());
+    }
+
     [Fact]
     public async Task HelpCat_RendersAnsiForRootHelp ()
     {

tests/Terminal.Gui.Cli.Tests/ArgParserTests.cs

@@ -38,6 +38,52 @@ public void TryParseTimeout_WithOverflowValue_ReturnsFalse ()
         Assert.False (ArgParser.TryParseTimeout ("1e999999h", out _));
     }
 
+    [Fact]
+    public void Parse_UnknownDashToken_FailsByDefault ()
+    {
+        ArgParser parser = new ([]);
+
+        ArgParser.ParseResult result =
+            parser.Parse (["pick", "--name", "value", "--literal"], new TestCommand (true));
+
+        Assert.False (result.Success);
+        Assert.Contains ("--literal", result.Error);
+    }
+
+    [Fact]
+    public void Parse_UnknownOptionsAsArguments_TreatsUnknownDashTokensAsPositionals ()
+    {
+        ArgParser parser = new ([]);
+
+        ArgParser.ParseResult result = parser.Parse (
+            ["pick", "--literal", "Alice", "--name", "value", "--json"],
+            new TestCommand (true),
+            true);
+
+        Assert.True (result.Success, result.Error);
+        Assert.NotNull (result.Options);
+
+        // Unknown dash tokens pass through verbatim as positionals; recognized
+        // command and framework options still parse normally.
+        Assert.Equal (["--literal", "Alice"], result.Options.Arguments);
+        Assert.Equal ("value", result.Options.CommandOptions["name"]);
+        Assert.True (result.Options.JsonOutput);
+    }
+
+    [Fact]
+    public void Parse_UnknownOptionsAsArguments_StillRejectedWhenCommandForbidsPositionals ()
+    {
+        ArgParser parser = new ([]);
+
+        ArgParser.ParseResult result = parser.Parse (
+            ["pick", "--name", "value", "--literal"],
+            new TestCommand (false),
+            true);
+
+        Assert.False (result.Success);
+        Assert.Contains ("positional", result.Error);
+    }
+
     [Fact]
     public void Parse_RejectsMissingRequiredCommandOption ()
     {