Merge feature/ai-help: Phase 3 --help-ai YAML help

Author: Peter

Examples/CurlAi/CurlAi.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <AssemblyName>CurlAi</AssemblyName>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.6" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\KingpinNet\KingpinNet.csproj" />
+  </ItemGroup>
+
+</Project>

Examples/CurlAi/Program.cs

@@ -0,0 +1,115 @@
+using System;
+using KingpinNet;
+using Microsoft.Extensions.Configuration;
+
+namespace CurlAi;
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        Kingpin
+            .Version("1.0")
+            .Author("Peter Andersen")
+            .ApplicationName("curl-ai")
+            .Help("An example implementation of curl exercising the AI-friendly help surface.")
+            .ExitOnHelp()
+            .ExitOnParseErrors()
+            .ShowHelpOnParsingErrors();
+
+        // Global flags — each value-taking flag declares a `unit`.
+        Kingpin.Flag("timeout", "Set connection timeout.")
+            .Short('t').IsInt().Unit("seconds").Default("5");
+        Kingpin.Flag("headers", "Add HTTP headers to the request.")
+            .Short('H').Unit("header");
+        Kingpin.Flag("verbose", "Verbose request/response logging.")
+            .Short('v').IsBool();
+        // Destructive flag carries a `caution` describing the risk and root requirement.
+        Kingpin.Flag("insecure", "Skip TLS certificate verification.")
+            .Short('k').IsBool()
+            .Caution("Disables TLS verification; only use against trusted hosts you control.");
+
+        var getCategory = Kingpin.Category("Get", "Category for all the GET commands:");
+        var get = getCategory.Command("get", "GET a resource.").IsDefault();
+        var getUrl = get.Command("url", "Retrieve a URL.").IsDefault();
+        // Required positional argument — exercises required: true in the YAML.
+        getUrl.Argument("url", "URL to GET.").IsRequired().IsUrl();
+
+        var getFile = get.Command("file", "Retrieve a file.");
+        getFile.Argument("file", "File to retrieve.").IsRequired();
+
+        var post = getCategory.Command("post", "POST a resource.");
+        post.Flag("data", "Key-value data to POST.").Short('d');
+        post.Flag("retries", "Number of retries on failure.")
+            .IsInt().Unit("count").Default("3");
+        post.Argument("url", "URL to POST to.").IsRequired().IsUrl();
+
+        var list = Kingpin.Command("list", "LIST a resource.");
+        list.Flag("interval", "Polling interval between LIST calls.")
+            .IsFloat().Unit("seconds").Default("1.0");
+        list.Argument("url", "URL to LIST.").IsRequired().IsUrl();
+
+        // Global AI-help sections (root-only by design).
+        Kingpin
+            .ExitCode(0, "Success")
+            .ExitCode(1, "Network or protocol error")
+            .ExitCode(2, "Invalid argument or unknown URL scheme");
+
+        Kingpin
+            .Example("Fetch a URL", "curl-ai get url https://example.com")
+            .Example("POST JSON to an endpoint",
+                "curl-ai post --data=@payload.json https://api.example.com/v1/items")
+            .Example("Poll a list endpoint every 2s",
+                "curl-ai list --interval=2.0 https://example.com/items");
+
+        Kingpin
+            .Note("All commands accept --timeout to bound network operations.")
+            .Note("HTTP/HTTPS are supported; other schemes are rejected at parse time.");
+
+        Kingpin
+            .Prefer("Always pass --timeout explicitly",
+                "Non-interactive or scripted invocations",
+                "Without --timeout, curl-ai will block indefinitely on dead peers and stall calling agents.")
+            .Prefer("Quote URLs that contain & or ?",
+                "Any invocation involving a query string",
+                "Bare query strings are interpreted by the shell, not curl-ai.");
+
+        Kingpin
+            .Avoid("Don't use --insecure",
+                "Hitting a trusted endpoint with a known-bad certificate during development",
+                "Disables TLS verification globally; opens the request to MITM attacks.")
+            .Avoid("Don't pass shell-expanded glob patterns as URLs",
+                "Genuinely fetching multiple URLs",
+                "curl-ai accepts exactly one URL per invocation; globs become noise.");
+
+        ParseResult result;
+        try
+        {
+            result = Kingpin.Parse(args);
+        }
+        catch (ParseException)
+        {
+            return;
+        }
+
+        if (result.ParsingFailed)
+            return;
+
+        var configuration = new ConfigurationBuilder().AddKingpinNetCommandLine(args).Build();
+        switch (configuration["command"])
+        {
+            case "get:url":
+                Console.WriteLine($"Getting URL {configuration["get:url:url"]}");
+                break;
+            case "post":
+                Console.WriteLine($"Posting to URL {configuration["post:url"]}");
+                break;
+            case "list":
+                Console.WriteLine($"Listing URL {configuration["list:url"]}");
+                break;
+            default:
+                Console.WriteLine("Use --help or --help-ai to see available commands.");
+                break;
+        }
+    }
+}

KingpinNet.slnx

@@ -5,6 +5,7 @@
   </Folder>
   <Folder Name="/Examples/">
     <Project Path="Examples/Curl/Curl.csproj" />
+    <Project Path="Examples/CurlAi/CurlAi.csproj" />
     <Project Path="Examples/Motif/Motif.csproj" />
     <Project Path="Examples/Ping/Ping.csproj" />
     <Project Path="Examples/TestKingpinNet/TestKingpinNet.csproj" />

README.md

@@ -130,8 +130,111 @@ iex "$({Your-tool-executable} --suggestion-script-pwsh)"
 
 After you run the script, you are able to have TAB auto complete on your tool.
 
+## AI-friendly help (`--help-ai`)
+
+KingpinNet apps emit a YAML description of their command tree designed for LLM agents to consume directly, alongside the human-rendered `--help`. Two global flags are registered automatically (parallel to `--help`) once `Initialize()` runs:
+
+- `--help-ai` — writes the YAML to stdout.
+- `--help-ai-file` — writes a Markdown-wrapped copy to `<exename>-ai-help.md` next to the executable. Pass an explicit path with `--help-ai-file=/path/to/file.md` to override.
+
+Both flags are available at the root and on every subcommand; invoking on a subcommand scopes the output to that subtree. The human `--help` output gains a single footer line — `For agents: run with --help-ai for a machine-readable description.` — so an LLM that reads `--help` first can discover the AI variant without external docs.
+
+### Authoring the global sections
+
+Five fluent methods on `KingpinApplication` (and the static `Kingpin` facade) populate the root-level sections of the YAML — each is emitted only when non-empty:
+
+```csharp
+Kingpin
+    .ExitCode(0, "Success")
+    .ExitCode(1, "Network or protocol error")
+
+    .Example("Fetch a URL", "curl-ai get url https://example.com")
+
+    .Note("All commands accept --timeout to bound network operations.")
+
+    .Prefer(
+        rule:  "Always pass --timeout explicitly",
+        when:  "Non-interactive or scripted invocations",
+        why:   "Without --timeout, curl-ai blocks indefinitely on dead peers.")
+
+    .Avoid(
+        rule:    "Don't use --insecure",
+        unless:  "Hitting a trusted endpoint with a known-bad certificate during dev",
+        why:     "Disables TLS verification globally; opens the request to MITM.");
+```
+
+Per-flag/argument, `.Unit("seconds")` declares what a value means and `.Caution("...")` surfaces destructive-flag warnings inline:
+
+```csharp
+Kingpin.Flag("timeout", "Set connection timeout.")
+    .Short('t').IsInt().Unit("seconds").Default("5");
+
+Kingpin.Flag("insecure", "Skip TLS certificate verification.")
+    .Short('k').IsBool()
+    .Caution("Disables TLS verification; only use against trusted hosts you control.");
+```
+
+### Sample output
+
+Running the bundled `Examples/CurlAi` with `--help-ai` produces, in part:
+
+```yaml
+command: curl-ai
+summary: An example implementation of curl exercising the AI-friendly help surface.
+synopsis: "curl-ai [commands] [flags]"
+
+global_flags:
+  - long: --timeout
+    short: "-t"
+    type: int
+    takes_value: true
+    unit: seconds
+    default: "5"
+    required: false
+    help: Set connection timeout.
+  - long: --insecure
+    short: "-k"
+    type: bool
+    takes_value: false
+    required: false
+    help: Skip TLS certificate verification.
+    caution: Disables TLS verification; only use against trusted hosts you control.
+
+commands:
+  - path: [get, url]
+    summary: Retrieve a URL.
+    synopsis: "curl-ai get url <arguments>"
+    argument:
+      - type: url
+        takes_value: true
+        required: true
+        help: URL to GET.
+
+exit_codes:
+  0: Success
+  1: Network or protocol error
+
+prefer:
+  - rule: Always pass --timeout explicitly
+    when: Non-interactive or scripted invocations
+    why: Without --timeout, curl-ai blocks indefinitely on dead peers.
+
+conventions:
+  flag_form: "--flag=value preferred; bare for booleans"
+  inheritance: Commands inherit flags from each ancestor and from global_flags
+```
+
+The full set of fields, the inheritance rule, and the format of every section are documented in `specs/roadmap.md` under "Phase 3 — AI-Friendly Help".
+
 ## What's New
 
+### Phase 3 — AI-friendly help
+ - New `--help-ai` and `--help-ai-file` global flags emit a YAML description of the command tree
+ - Fluent API for declaring `ExitCode`, `Example`, `Note`, `Prefer`, and `Avoid` sections
+ - Per-flag/argument `.Unit(...)` and `.Caution(...)` for machine-readable hints
+ - Hand-rolled, trim/AOT-safe YAML emitter (no `YamlDotNet` runtime dependency)
+ - `Examples/CurlAi/` exercises the full surface end-to-end
+
 ### Phase 2 — Modern .NET compatibility
  - Replaced DotLiquid with Scriban for trimming-safe help rendering
  - Library is now marked `IsAotCompatible` with trim, AOT, and single-file analyzers enabled

specs/2026-05-12-ai-help/plan.md

@@ -0,0 +1,79 @@
+# Plan — AI-Friendly Help (`--help-ai`)
+
+Branch: `feature/ai-help`
+Spec dir: `specs/2026-05-12-ai-help/`
+
+Task groups are ordered by dependency. Do not start a group until every step in the preceding group is complete (or explicitly stubbed and tracked).
+
+## Group 1 — Model & metadata surface
+
+Foundation for the emitter. Adds the new fields and the author-facing fluent API for global sections, but does not yet emit anything.
+
+1.1 Add `Unit` (`string?`) and `Caution` (`string?`) to `FlagItem` and `ArgumentItem`. Default to null. Wire fluent setters: `.Unit("seconds")`, `.Caution("Requires root.")` on both flag and argument builders.
+1.2 Introduce a `GlobalSections` record on `KingpinApplication` holding five lists: `ExitCodes`, `Examples`, `Notes`, `Prefer`, `Avoid`, each of a small strongly-typed record:
+   - `ExitCode(int code, string description)`
+   - `Example(string intent, string command)`
+   - `Note(string text)`
+   - `Prefer(string rule, string when, string why)`
+   - `Avoid(string rule, string unless, string why)`
+1.3 Add fluent extension methods on `KingpinApplication` so apps can declare each section. Pattern: `app.ExitCode(0, "OK").Example("intent", "cmd").Prefer(rule: …, when: …, why: …)`. Keep chainable.
+1.4 Add basic xUnit coverage in `test/UnitTests/` for the new fluent setters: setting `Unit` and `Caution` round-trips into the model; each global-section setter appends an entry.
+
+## Group 2 — YAML emitter
+
+The trim/AOT-safe writer. No flag wiring yet; all tests drive it directly with a constructed `KingpinApplication`.
+
+2.1 Add `src/KingpinNet/Help/AiHelpYamlWriter.cs`. `internal sealed class` accepting a `TextWriter`. Single public entry point `Write(KingpinApplication app, CommandItem? scope = null)` — when `scope` is set, only the subtree rooted at that command is emitted.
+2.2 Implement YAML primitives: indented scalar emission, list emission, block-scalar (`|`) for help text containing newlines, double-quoted scalar for strings containing `:`, `#`, leading `-`, or other YAML-significant characters. Centralise quoting in one private `WriteScalar(string key, string value)` helper.
+2.3 Implement command/flag/argument walkers: `WriteRoot`, `WriteGlobalFlags`, `WriteCommand` (recursive), `WriteFlag`, `WriteArgument`. Emit fields in the order documented in `specs/roadmap.md`'s Format reference. Suppress fields that are null/empty (especially `short`, `unit`, `default`, `help`, `caution`).
+2.4 Implement global-section emitters: `WriteExitCodes`, `WriteExamples`, `WriteNotes`, `WritePrefer`, `WriteAvoid`. Each writes its top-level key only if its source list is non-empty.
+2.5 Emit the fixed `conventions` block at the root with:
+   - `flag_form: --flag=value preferred; bare for booleans`
+   - `inheritance: Commands inherit flags from each ancestor in \`inherits\` and from \`global_flags\``
+2.6 Unit tests in `test/UnitTests/` covering, at minimum: scalar quoting per edge case (`:`, `#`, leading `-`, embedded newline), block-scalar selection, nested `commands:` indentation, omission of empty optional fields, omission of empty global sections, `scope` parameter restricting output to the subtree.
+
+## Group 3 — `--help-ai` flag
+
+Wire the emitter into the parser.
+
+3.1 Register a built-in global flag `--help-ai` on every `KingpinApplication` and on every `CommandItem` (mirroring how `--help` is registered today; consult existing registration in `KingpinApplication.cs` / `Parser.cs`).
+3.2 In the parser, intercept `--help-ai` before normal handler dispatch (same point in the pipeline as the existing `--help` short-circuit). Resolve the scope (root vs. specific subcommand based on which node the flag was attached to).
+3.3 Default destination is stdout via the existing `IConsole` abstraction. Construct the writer, call `AiHelpYamlWriter.Write(app, scope)`, exit cleanly (do not invoke a command handler).
+3.4 Integration test: a small in-process `KingpinApplication` invoked with `--help-ai` produces non-empty output that begins with `command:` and contains the expected subcommand names.
+
+## Group 4 — File output mode + discovery hint
+
+Adds the second flag and the human-help footer.
+
+4.1 Register `--help-ai-file` as a built-in global flag that optionally takes a path. With no value, the destination is `<exename>-ai-help.md` resolved next to the running executable (use `Environment.ProcessPath` / `AppContext.BaseDirectory`).
+4.2 Implement the Markdown wrapper: write `# <exename> help`, blank line, fenced ` ```yaml ` block containing the same YAML payload `--help-ai` emits, closing fence, trailing newline. Reuse `AiHelpYamlWriter` unchanged — the wrapper is purely outside the writer.
+4.3 Append the single-line footer to the human-rendered help output (the existing Scriban template surface in `src/KingpinNet/Help/`). Wording: `For agents: run with --help-ai for a machine-readable description.`
+4.4 Integration test: invoking the flag with no value creates the expected file in a temp directory; invoking it with an explicit path writes there. Assert the file starts with `# ` and contains a `\`\`\`yaml` fence.
+
+## Group 5 — Test reinforcement
+
+The validation gates that prevent regressions and authored-content drift.
+
+5.1 Add `YamlDotNet` (or an equivalent .NET YAML parser) to the test project only — never to `src/KingpinNet/KingpinNet.csproj`. Verify with `dotnet list test/UnitTests package`.
+5.2 Round-trip validity test: for a representative `KingpinApplication` fixture, emit YAML to a string, parse it with `YamlDotNet`, assert no exceptions and that a handful of expected keys (`command`, `commands`, `conventions`) are present.
+5.3 Golden/snapshot test(s): one or two representative apps (one trivial, one with nested commands + all global sections) emit YAML compared against checked-in `.expected.yaml` files under `test/UnitTests/`.
+5.4 `examples[].command` parse-check: a test iterates every `Example` declared on the fixture app, splits the command line, and feeds it through `Parser` / the existing token + parse pipeline. Asserts it resolves to a valid command + flag set without errors.
+
+## Group 6 — Documentation & example app
+
+User-facing surface.
+
+6.1 Create `Examples/CurlAi/` by copying `Examples/Curl/`. Rename `csproj` to `CurlAi.csproj`. Update assembly name / namespace as appropriate.
+6.2 Extend the program to populate every Phase 3 surface: declare at least one `caution` on a destructive flag (e.g. `--force` or `--insecure`), make at least one positional `required: true`, declare a `unit` on every value-taking flag, and call the fluent API for all five global sections.
+6.3 Add `Examples/CurlAi/CurlAi.csproj` to `KingpinNet.slnx` so it builds in CI.
+6.4 Update `README.md` with a new section titled "AI-friendly help (`--help-ai`)". Cover: what the flag emits, how to invoke it, file mode behavior and default location, the fluent API for the five global sections, and a short (~20-line) YAML excerpt taken from CurlAi's actual output.
+
+## Group 7 — Final validation pass
+
+Runs the merge checklist before the PR is raised. See `validation.md` for the exact commands.
+
+7.1 `dotnet build` clean.
+7.2 `dotnet test` clean (all existing + new tests pass).
+7.3 AOT publish gate green for a sample project; no new trim warnings introduced.
+7.4 Manual smoke: build CurlAi, run `--help-ai` to stdout (eyeball YAML), run `--help-ai-file` (verify `curl-ai-ai-help.md` written next to the binary with the expected wrapper).
+7.5 Tick the Phase 3 checkboxes in `specs/roadmap.md` as each is satisfied. Do not tick them speculatively before the validation gates pass.