Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (56 loc) · 5.52 KB

AGENTS.md

File metadata and controls

68 lines (56 loc) · 5.52 KB

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Repository: Sharpify.CommandLineInterface (C#/.NET library + tests)

Commands

  • Build (library only)
    • dotnet build src/Sharpify.CommandLineInterface/Sharpify.CommandLineInterface.csproj
  • Build (entire solution)
    • dotnet build Sharpify.CommandLineInterface.slnx
  • Format (respect .editorconfig)
    • dotnet format
  • Tests (Microsoft Testing Platform runner via dotnet run; pass arguments after --)
    • Run all tests: dotnet run --project tests/Sharpify.CommandLineInterface.Tests/Sharpify.CommandLineInterface.Tests.csproj
    • List tests: dotnet run --project tests/Sharpify.CommandLineInterface.Tests/Sharpify.CommandLineInterface.Tests.csproj --list-tests
    • Filter by type/method (examples)
      • By class: dotnet run --project tests/Sharpify.CommandLineInterface.Tests/Sharpify.CommandLineInterface.Tests.csproj --filter-class "ClassName"
      • By class: dotnet run --project tests/Sharpify.CommandLineInterface.Tests/Sharpify.CommandLineInterface.Tests.csproj --filter-method "MethodName"

Agent Workflow Requirements

  • Before running any test command, explicitly ask the user for permission to escalate out of the sandbox (if required) and wait for confirmation.

High-level architecture and structure

  • Solution layout
    • Sharpify.CommandLineInterface.slnx: solution that groups the library, shared test helpers, manual sample, and test runner projects
    • src/Sharpify.CommandLineInterface: core library (targets net9.0)
    • tests/Sharpify.CommandLineInterface.Tests.Common: shared fixtures and sample commands referenced by tests
    • tests/manual: manual harness for experimenting with the CLI (net9.0 console app)
    • tests/Sharpify.CommandLineInterface.Tests: xUnit v3 tests (net9.0), configured to run with Microsoft Testing Platform via dotnet run
  • Core concepts (library)
    • Commands and execution
      • Command and SynchronousCommand are the extensibility points for users to implement CLI commands. They expose compile-time metadata (Name, Description, Usage) and an execution entry point (ExecuteAsync for async ValueTask workflows; Execute for sync).
      • CliRunner orchestrates end-to-end invocation: parses input, routes to the correct command, handles help, and writes output. It is created via CliRunner.CreateBuilder().
      • CliBuilder provides a fluent builder to add commands, configure output writers, and modify global CLI metadata, producing a configured CliRunner instance.
      • HelpCommand and VersionCommand are appended automatically during Build() to service global --help/--version requests; OnVersionRequestedInvoke allows overriding the version command behavior.
    • Arguments and parsing
      • Parser converts raw args (string/ReadOnlySpan/IList) to an Arguments instance by tokenizing on spaces/quotes and mapping to a case-insensitive dictionary (default StringComparer.OrdinalIgnoreCase).
      • Arguments (implemented across ArgumentsCore/ArgumentsAccess/ArgumentsAccessMultiple) provides high-performance retrieval, validation, and parsing APIs:
        • Positional access by index; named access by key (dashes removed); flags as keys with empty values.
        • Typed getters/parsers (TryGetValue, GetValue), enum parsing helpers, multi-value retrieval (TryGetValues) with custom separators, and ForwardPositionalArguments to shift positions after command routing.
    • Output abstraction
      • OutputHelper centralizes returning exit codes while writing to a configurable TextWriter set on the CliRunner (no direct dependency on System.Console). This keeps the library embeddable and testable.
    • Metadata and configuration
      • CliMetadata captures global app identity (name, description, author, version, license) used for help text and presentation.
      • CliRunnerConfiguration and ConfigurationEnums provide structured configuration for runner behavior and modes.
    • Shell completions
      • Completions folder defines ICompletionProvider with concrete providers for Bash, Zsh, Fish, and PowerShell. These generate shell-specific completion data from the CLI metadata/commands.
    • Utilities
      • Extensions contains internal helper extensions used across the library.
      • Pooling defines a lightweight, concurrency-aware object pool used for frequently allocated types such as StringBuilder and HashSet.
  • Tests
    • Tests cover parsing (ParserArgumentsTests), argument access APIs, builder/runner behavior (CliBuilderTests), and completion providers for each shell.
    • tests/Sharpify.CommandLineInterface.Tests.Common hosts reusable fixture commands (AddCommand, EchoCommand, etc.) shared across unit and manual tests.
    • The test project references the library, targets net9.0, and is configured with Microsoft Testing Platform (UseMicrosoftTestingPlatformRunner=true). Execute tests with dotnet run as shown above.
    • tests/manual is a net9.0 console app that references the library and common fixtures for exploratory runs; keep it compiling when making API changes.

CI

  • .github/workflows/Tests.yaml runs tests on Ubuntu, Windows, and macOS with .NET 9.0 using a reusable workflow and the Microsoft Testing Platform runner.

Notes

  • The library enables Native AOT scenarios (IsAotCompatible=true, IsTrimmable=true) and intentionally avoids reflection in core paths; when consuming the library, prefer compile-time metadata and explicit parsing over reflection to keep AOT compatibility.
  • XML documentation is generated (GenerateDocumentationFile=True). Public APIs should be documented; prefer inheritdoc on members when appropriate.