Add CLAUDE.md for project guidance and documentation

Author: matt-edmondson

CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ktsu.RunCommand is a .NET library that provides an easy way to execute shell commands and handle output via delegates. It supports both synchronous and asynchronous execution with customizable output handling.
+
+## Build and Test Commands
+
+### Building
+```bash
+dotnet build
+```
+
+### Running Tests
+```bash
+# Run all tests
+dotnet test
+
+# Run a single test
+dotnet test --filter "FullyQualifiedName~RunCommandTests.ExecuteShouldExecuteCommandAndReturnExitCode"
+```
+
+### Creating NuGet Package
+```bash
+dotnet pack
+```
+
+### Using the Build Automation
+The project uses a custom PowerShell build module (PSBuild) for CI/CD:
+```powershell
+Import-Module ./scripts/PSBuild.psm1
+$buildConfig = Get-BuildConfiguration ...
+Invoke-CIPipeline -BuildConfiguration $buildConfig
+```
+
+## Architecture
+
+### Core Components
+
+**[RunCommand.cs](RunCommand/RunCommand.cs)** - Main static class providing the public API:
+- `Execute(string command)` - Synchronous command execution
+- `Execute(string command, OutputHandler outputHandler)` - Synchronous with output handling
+- `ExecuteAsync(string command)` - Asynchronous command execution
+- `ExecuteAsync(string command, OutputHandler outputHandler)` - Asynchronous with output handling
+- All methods return process exit codes
+- Commands are parsed by splitting on first space: filename and arguments
+
+**[OutputHandler.cs](RunCommand/OutputHandler.cs)** - Base class for handling command output:
+- Processes output in raw, undelimited chunks as they arrive from the process
+- Provides `OnStandardOutput` and `OnStandardError` delegates
+- Supports custom encoding (defaults to UTF-8)
+- Virtual methods `HandleStandardOutputData` and `HandleStandardErrorData` for extensibility
+
+**[LineOutputHandler.cs](RunCommand/LineOutputHandler.cs)** - Derived output handler for line-by-line processing:
+- Inherits from OutputHandler
+- Buffers incoming chunks and splits by newlines
+- Maintains separate buffers (`outputBuffer`, `errorBuffer`) for incomplete lines
+- Uses `Environment.NewLine` after normalizing line endings with `ReplaceLineEndings()`
+- Invokes delegates for each complete line
+
+**[AsyncProcessStreamReader.cs](RunCommand/AsyncProcessStreamReader.cs)** - Internal async stream reader:
+- Reads from both stdout and stderr concurrently using 4096-character buffers
+- Continuously reads while process is running, then performs final read after exit
+- Uses `Task.WhenAny` to poll streams efficiently
+- Invokes OutputHandler methods for each chunk of data received
+
+### Key Design Patterns
+
+1. **Async Over Sync**: The synchronous `Execute` methods call `ExecuteAsync().Result`, making the async implementation the source of truth.
+
+2. **Strategy Pattern**: OutputHandler and LineOutputHandler allow different output processing strategies to be plugged in.
+
+3. **Template Method**: OutputHandler provides virtual methods that LineOutputHandler overrides to customize behavior.
+
+4. **Buffering Strategy**: LineOutputHandler demonstrates how to buffer incomplete data across multiple chunk reads to reconstruct complete lines.
+
+### Multi-Targeting
+
+The library targets multiple .NET versions:
+- .NET 9.0
+- .NET 8.0
+- .NET 7.0
+- .NET 6.0
+- .NET 5.0
+- .NET Standard 2.1
+- .NET Standard 2.0
+
+Uses `ktsu.Sdk` for standardized project configuration.
+
+## Testing
+
+Tests are located in [RunCommand.Test/](RunCommand.Test/) using MSTest framework:
+- [RunCommandTests.cs](RunCommand.Test/RunCommandTests.cs) - Tests for main execution methods
+- [LineOutputHandlerTests.cs](RunCommand.Test/LineOutputHandlerTests.cs) - Tests for line buffering logic
+- Tests target .NET 9.0 only
+- Uses MSTest.Sdk for test execution
+
+## Version Management
+
+The project uses semantic versioning with git-based version calculation:
+- Version tags in commit messages: `[major]`, `[minor]`, `[patch]`, `[pre]`
+- Public API changes are automatically detected and trigger minor version bumps
+- VERSION.md, CHANGELOG.md, and other metadata files are auto-generated by PSBuild module
+
+## Important Implementation Notes
+
+### Command Parsing
+Commands are split on the first space character. The first part becomes the filename, the rest becomes arguments. Be aware this simple parsing doesn't handle quoted strings specially.
+
+### Process Configuration
+On Windows, `LoadUserProfile` is set to true for proper environment variable expansion.
+
+### Stream Reading
+The AsyncProcessStreamReader performs a final read after process exit to ensure all buffered data is captured. This is crucial for short-lived processes.
+
+### Encoding
+All input/output streams use UTF-8 by default but can be customized via OutputHandler constructor.