Initial TimeWarp.Builder repository setup with dev CLI and CI workflow

.agent/workspace/2026-02-23T00-00-00_code-review-release-readiness.md

@@ -0,0 +1,234 @@
+# TimeWarp.Builder — Code Review & Release Readiness Assessment
+
+**Date:** 2026-02-23  
+**Reviewer:** claude-sonnet-4-6 (automated analysis)  
+**Branch:** Cramer-2025-12-22-dev  
+**Version:** 1.0.0-beta.1
+
+---
+
+## Executive Summary
+
+TimeWarp.Builder is a small, focused NuGet library providing two fluent builder interfaces (`IBuilder<T>`, `INestedBuilder<TParent>`) and four Kotlin-inspired scope extension methods. The code quality is **excellent** — clean, well-documented, AOT-compatible, and enforced by an aggressive analyzer stack. **The library is functionally ready for a v1.0.0 release**, but several issues must be resolved first: a stale repository reference in `msbuild/repository.props`, zero automated tests, and a thin README that leaves real consumers without enough guidance.
+
+---
+
+## Scope
+
+This review covers:
+
+- All 4 C# source files in `source/timewarp-builder/`
+- Project configuration: `timewarp-builder.csproj`, `Directory.Build.props`, `Directory.Packages.props`
+- MSBuild props: `msbuild/repository.props`
+- Developer tooling: `.editorconfig`, `.gitignore`, `timewarp-builder.slnx`
+- Documentation: `README.md`
+- Kanban board state
+- Repo structure and packaging completeness
+
+---
+
+## Methodology
+
+- Full read of every source file and configuration file in the repository
+- Cross-reference of `msbuild/repository.props` against actual repo layout
+- Analysis of NuGet packaging metadata in the `.csproj`
+- Review of `.editorconfig` for consistency with `AGENTS.md` coding standards
+- Review of `Directory.Packages.props` for unused/mismatched dependencies
+- Comparison of README documentation against actual public API surface
+
+---
+
+## Findings
+
+### 1. Source Code Quality — ✅ Excellent
+
+**Files reviewed:** `i-builder.cs`, `i-nested-builder.cs`, `scope-extensions.cs`, `global-usings.cs`
+
+All four source files are clean and correct. Specific observations:
+
+#### `i-builder.cs`
+- Interface `IBuilder<out TBuilt>` uses `out` covariance correctly — this is the right choice for a producer-only interface.
+- XML documentation is thorough: summary, `<typeparam>`, `<returns>`, and a working `<code>` example.
+- File-scoped namespace used correctly per project standards.
+- No issues.
+
+#### `i-nested-builder.cs`
+- `INestedBuilder<out TParent> where TParent : class` — the `class` constraint is correct and necessary; value types cannot be returned by reference in a builder chain.
+- `out` covariance is appropriate.
+- XML docs clearly explain the difference between this and `IBuilder<T>` and include a realistic chained example.
+- No issues.
+
+#### `scope-extensions.cs`
+- All four methods (`Also`, `Apply`, `Let`, `Run`) are correctly implemented.
+- `ArgumentNullException.ThrowIfNull(action)` is used everywhere — correct modern pattern.
+- `Also` and `Apply` are **functionally identical** (both execute an `Action<T>` and return the original object). This is documented as intentional ("semantically ... clearer intent for configuration"), which is acceptable for a public API. Consider whether consumers will find this intuitive or confusing long-term.
+- Return types are consistent: `Also`/`Apply` return `T`, `Let` returns `TResult`, `Run` returns `void`.
+- Generic constraints are minimal and correct — no unnecessary constraints.
+- XML documentation is complete on all four methods.
+
+#### `global-usings.cs`
+- Contains exactly one global using: `global using System;`
+- `System` is needed for `Action<T>`, `Func<T, TResult>`, and `ArgumentNullException`.
+- Minimal and correct per project standards.
+
+---
+
+### 2. Project Configuration — ⚠️ One Blocker Found
+
+#### `timewarp-builder.csproj`
+- `<Version>1.0.0-beta.1</Version>` — still on beta. This is what needs to be bumped for official release.
+- `<IsAotCompatible>true</IsAotCompatible>`, `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>`, `<EnableAotAnalyzer>true</EnableAotAnalyzer>` — all set correctly.
+- `<Description>` and `<PackageTags>` are present and sensible.
+- `README.md` is included as a NuGet package README via `<None Include="../../README.md" Pack="true" PackagePath="" />` — good.
+- **Missing NuGet metadata:** Several standard fields are absent:
+  - `<Authors>` — not set
+  - `<PackageProjectUrl>` — not set
+  - `<RepositoryUrl>` — not set
+  - `<PackageLicenseExpression>` — not set (LICENSE file exists but is not referenced)
+  - `<PackageIcon>` — `assets/timewarp-builder-avatar.svg` exists but is not wired up
+  - These gaps affect discoverability and trustworthiness on NuGet.org
+
+#### `msbuild/repository.props` — 🔴 BLOCKER
+```xml
+<RepositoryName>timewarp-nuru</RepositoryName>
+<SolutionFile>$(RepositoryRoot)timewarp-nuru.slnx</SolutionFile>
+```
+These values reference **timewarp-nuru**, not **timewarp-builder**. This file was clearly copied from another repository and never updated. The actual solution file is `timewarp-builder.slnx`, not `timewarp-nuru.slnx`.
+
+While this does not break the build today (the `SolutionFile` property is defined but not consumed by any project), it is misleading, will cause confusion for contributors, and signals the repo was not fully set up from scratch.
+
+#### `Directory.Build.props`
+- `TreatWarningsAsErrors`, `AnalysisMode=All`, `AnalysisLevel=latest-all` — excellent, high-quality defaults.
+- AOT warning suppressions (`IL2026`, `IL2067`, etc.) are suppressed globally with a comment. These are listed as "not yet implemented" — this is acceptable for beta, but for a v1.0.0 release targeting AOT, these suppressions should ideally be resolved or scoped to specific files.
+- `EmitCompilerGeneratedFiles=true` — good for debugging; no generated files currently exist for this library (no source generators in use).
+
+#### `Directory.Packages.props`
+- Central Package Management is enabled — correct approach.
+- **Contains many packages this library does not use** (Serilog, OpenTelemetry, Aspire, benchmarking frameworks, MCP, Mediator, etc.). These are almost certainly inherited from the timewarp-nuru monorepo and not relevant to this standalone library. While they don't cause a build problem (packages are only downloaded when referenced), they add noise and maintenance burden.
+- `TimeWarp.Builder Version="1.0.0-beta.1"` references itself — this is only meaningful if some other project in the solution consumes the package. In the current single-project solution it is harmless but confusing.
+
+---
+
+### 3. Documentation — ⚠️ Needs Improvement Before Release
+
+#### `README.md`
+- Covers all 4 scope functions and both interfaces with code examples.
+- **Does not include:**
+  - Installation instructions (`dotnet add package TimeWarp.Builder`)
+  - Target framework requirements (.NET 10 / .NET 5+?)
+  - License information
+  - A badge row (version, license, build status) — standard for NuGet libraries
+  - Any design rationale explaining when to choose `Also` vs `Apply`
+  - Link to NuGet.org or GitHub releases
+  - Contribution guidelines or link to them
+
+#### XML Documentation
+- All public API surface is fully documented with `<summary>`, `<typeparam>`, `<param>`, `<returns>`, `<exception>`, and `<example>` — this is a strong point and will generate good IDE tooltips.
+
+---
+
+### 4. Testing — 🔴 BLOCKER
+
+**There are zero tests in this repository.** No test project exists, and no test files were found.
+
+For a library of this size and simplicity, the risk of behavioral bugs is low. However:
+- Without tests, there is no regression safety net.
+- Publishing a v1.0.0 without any tests sets a poor precedent.
+- The scope extension methods have subtle behavioral nuances (`Also` vs `Apply`, `null` guard on action, `Let` returning nullable results) that are worth specifying in tests.
+
+A minimal test suite covering the following would be sufficient:
+- `Also` executes the action and returns the original object
+- `Apply` executes the action and returns the original object
+- `Let` transforms to a new type/value
+- `Run` executes the action (terminal, no return)
+- All four methods throw `ArgumentNullException` when `action`/`transform` is `null`
+- `IBuilder<T>` and `INestedBuilder<TParent>` are implementable (integration-style tests using a concrete builder)
+
+---
+
+### 5. API Design — ✅ Good, with Minor Considerations
+
+#### `Also` vs `Apply` semantic overlap
+Both methods are identical in implementation. This is a documented design choice — `Also` is for side-effects (logging, debugging), `Apply` is for configuration. The distinction is useful but requires clear docs (currently present). Consider whether a single `Tap` method would serve the same purpose with less ambiguity, though changing this now would break the established naming from Kotlin conventions.
+
+#### `Run` terminal method
+`Run` is void-returning and acts as a terminal operation. It is safe and well-designed. One edge case worth noting: if `obj` is `null`, the method still calls `action(obj)` which may throw a NullReferenceException inside the action. A guard for `null` obj could be considered on `Also`/`Apply`/`Let`/`Run`, but this would change the semantics for value types (structs) and nullable reference types, so the current behavior (no guard on `obj`) is likely correct.
+
+#### Covariance on interfaces
+`IBuilder<out TBuilt>` and `INestedBuilder<out TParent>` both use `out` correctly, enabling useful polymorphic scenarios (e.g., `IBuilder<Animal>` can hold a `IBuilder<Dog>`).
+
+#### No async builder interface
+There is no `IBuildAsync<T>` or async variant of the scope extensions. Whether this is needed depends on consumer use cases. Not blocking for v1.0.0 but worth tracking for v1.1.
+
+---
+
+### 6. Repo Housekeeping — ⚠️ Minor Issues
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `.gitignore` | ✅ | Comprehensive Visual Studio standard gitignore |
+| `LICENSE` | ✅ | File exists |
+| `kanban/` | ✅ | All lanes empty — clean state |
+| `assets/timewarp-builder-avatar.svg` | ⚠️ | Not referenced in `.csproj` as package icon |
+| `msbuild/repository.props` | 🔴 | Wrong `RepositoryName` and `SolutionFile` (timewarp-nuru) |
+| Solution file name | ✅ | `timewarp-builder.slnx` — correctly named |
+| Single project in solution | ✅ | Clean, no extraneous projects |
+
+---
+
+## Release Readiness Checklist
+
+### Blockers (must fix before v1.0.0)
+
+- [ ] **Fix `msbuild/repository.props`** — change `RepositoryName` to `timewarp-builder` and `SolutionFile` to `timewarp-builder.slnx`
+- [ ] **Add automated tests** — even a minimal test project covering all public API methods
+- [ ] **Add required NuGet metadata** — `<Authors>`, `<PackageProjectUrl>`, `<RepositoryUrl>`, `<PackageLicenseExpression>` to `timewarp-builder.csproj`
+- [ ] **Bump version** — change `1.0.0-beta.1` to `1.0.0` in `timewarp-builder.csproj`
+
+### High Priority (strongly recommended before v1.0.0)
+
+- [ ] **Improve README** — add installation instructions, target framework info, license, and badges
+- [ ] **Wire up package icon** — add `<PackageIcon>timewarp-builder-avatar.svg</PackageIcon>` and include the asset in the `.csproj`
+- [ ] **Prune `Directory.Packages.props`** — remove packages not relevant to this library (Serilog, OpenTelemetry, benchmarking, MCP, etc.)
+- [ ] **Resolve or scope AOT warning suppressions** — either implement AOT compatibility fully or add `#pragma warning disable` at call sites rather than globally suppressing in `Directory.Build.props`
+
+### Low Priority (nice to have for v1.x)
+
+- [ ] Add `#region Purpose` / `#region Design` context regions to source files (per project csharp skill conventions)
+- [ ] Consider `IBuildAsync<T>` interface for async build scenarios
+- [ ] Consider adding `CHANGELOG.md` or release notes for v1.0.0
+- [ ] Consider XML doc comment suppression is turned off (`RCS1139`–`RCS1142`, `RCS1181` all set to `none`) — this means missing doc comments won't be flagged. Since all current public API is documented, this is fine now but could regress.
+
+---
+
+## Positive Highlights
+
+These are genuinely strong practices that should be preserved:
+
+1. **Aggressive analyzer stack** — Roslynator + NetAnalyzers + CodeStyle analyzers with `TreatWarningsAsErrors=true` is exceptional. Very few .NET libraries enforce this level of quality at build time.
+2. **Full XML documentation** — Every public method, parameter, type parameter, and exception is documented. Code examples are included and accurate.
+3. **AOT flags set correctly** — `IsAotCompatible`, `EnableTrimAnalyzer`, `EnableAotAnalyzer` are all enabled. The actual code has no reflection or dynamic patterns, so AOT compatibility should be genuine.
+4. **Covariance used correctly** — `out` on both generic interfaces is the right design.
+5. **Null guards via `ArgumentNullException.ThrowIfNull`** — modern, concise, and consistent across all four extension methods.
+6. **Central Package Management** — `ManagePackageVersionsCentrally=true` is the right approach for a multi-project repo.
+7. **File naming convention** — kebab-case source file names (`i-builder.cs`, `scope-extensions.cs`) are consistent throughout.
+8. **Minimal `global-usings.cs`** — only `System` is imported globally, keeping the namespace surface tight.
+
+---
+
+## Summary Verdict
+
+| Category | Status |
+|----------|--------|
+| Code correctness | ✅ No bugs found |
+| Code style/conventions | ✅ Fully compliant |
+| API design | ✅ Clean and well-reasoned |
+| AOT compatibility | ✅ Declared and structurally sound |
+| Documentation (XML) | ✅ Complete |
+| Documentation (README) | ⚠️ Thin — needs installation guide |
+| Automated tests | 🔴 Missing entirely |
+| NuGet packaging | ⚠️ Missing required metadata fields |
+| Build configuration | ⚠️ `repository.props` has wrong repo name |
+| Overall release readiness | **Not yet — 3 blockers to resolve** |
+
+The library itself is high quality. The blockers are all in tooling, packaging, and testing — not in the core logic. With focused effort on the four blockers above, this is ready for a clean v1.0.0 release.

.editorconfig

@@ -26,7 +26,7 @@ insert_final_newline = true
 
 # ReSharper properties
 resharper_html_attribute_indent = single_indent
-resharper_convert_to_primary_constructor_highlighting = false
+resharper_convert_to_primary_constructor_highlighting = do_not_show
 
 # Development files
 [*.{cs,csx,cshtml,csproj,razor,sln,props,targets,json,yml,gitignore,}]
@@ -142,7 +142,7 @@ csharp_prefer_braces = when-multiline:suggestion
 csharp_prefer_simple_using_statement = true:suggestion
 csharp_style_namespace_declarations = file_scoped:error
 csharp_style_prefer_method_group_conversion = true
-csharp_style_prefer_primary_constructors = false
+csharp_style_prefer_primary_constructors = false:none
 csharp_style_prefer_top_level_statements = false
 
 # Expression-level preferences

.envrc

@@ -0,0 +1 @@
+PATH_add bin

.github/workflows/workflow.yml

@@ -0,0 +1,67 @@
+name: CI/CD Workflow
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'source/**'
+      - 'tools/**'
+      - '.github/workflows/**'
+      - 'Directory.Build.props'
+      - 'Directory.Packages.props'
+      - 'source/Directory.Build.props'
+  pull_request:
+    branches:
+      - master
+    paths:
+      - 'source/**'
+      - 'tools/**'
+      - '.github/workflows/**'
+      - 'Directory.Build.props'
+      - 'Directory.Packages.props'
+      - 'source/Directory.Build.props'
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # Required for NuGet Trusted Publishing (OIDC)
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for version detection
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: NuGet login (OIDC Trusted Publishing)
+        if: github.event_name == 'release'
+        id: nuget-login
+        uses: nuget/login@v1
+        with:
+          user: TimeWarp.Enterprises
+
+      - name: Run CI Pipeline
+        run: |
+          if [ "${{ github.event_name }}" == "release" ]; then
+            dotnet run tools/dev-cli/dev.cs -- workflow --api-key "${{ steps.nuget-login.outputs.NUGET_API_KEY }}"
+          else
+            dotnet run tools/dev-cli/dev.cs -- workflow
+          fi
+
+      - name: Upload Artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: Packages-${{ github.run_number }}
+          path: artifacts/packages/*.nupkg
+          if-no-files-found: ignore

.timewarp/dev.jsonc

@@ -0,0 +1,6 @@
+{
+  "checkVersionConfig": {
+    "checkVersionStrategy": "nuget-search",
+    "packages": "TimeWarp.Builder"
+  }
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "peacock.remoteColor": "#F61D1F",
+  "timewarp.blurImagePath": "assets/timewarp-builder-avatar.svg",
+  "workbench.colorCustomizations": {
+    "activityBar.activeBackground": "#f84e50",
+    "activityBar.background": "#f84e50",
+    "activityBar.foreground": "#15202b",
+    "activityBar.inactiveForeground": "#15202b99",
+    "activityBarBadge.background": "#0cf50a",
+    "activityBarBadge.foreground": "#15202b",
+    "commandCenter.border": "#e7e7e799",
+    "sash.hoverBorder": "#f84e50",
+    "statusBar.background": "#f61d1f",
+    "statusBar.foreground": "#e7e7e7",
+    "statusBarItem.hoverBackground": "#f84e50",
+    "statusBarItem.remoteBackground": "#f61d1f",
+    "statusBarItem.remoteForeground": "#e7e7e7",
+    "titleBar.activeBackground": "#f61d1f",
+    "titleBar.activeForeground": "#e7e7e7",
+    "titleBar.inactiveBackground": "#f61d1f99",
+    "titleBar.inactiveForeground": "#e7e7e799"
+  }
+}

AGENTS.md

@@ -0,0 +1,30 @@
+# TimeWarp.Builder - Agent Development Guidelines
+
+## Build & Test Commands
+```bash
+dotnet build                    # Build all projects
+dotnet build source/timewarp-builder/timewarp-builder.csproj  # Build main project
+dotnet pack                     # Create NuGet packages
+dotnet test                     # Run all tests (if any test projects exist)
+```
+
+## Code Style Guidelines
+- **Explicit types only**: Never use `var` - warnings enforced
+- **Naming**: PascalCase for types, methods, properties; camelCase for parameters/locals; Interfaces start with 'I'
+- **Fields**: PascalCase (NO underscore prefixes)
+- **File-scoped namespaces**: `namespace TimeWarp.Builder;`
+- **Using statements**: Inside namespace, not at file level
+- **Nullability**: Enabled everywhere - use nullable reference types
+- **AOT compatible**: All code must be AOT-compatible
+- **Target framework**: .NET 10.0
+
+## Project Structure
+- Main library: `source/timewarp-builder/`
+- Global usings in `global-usings.cs` (keep minimal)
+- Fluent builder interfaces: `IBuilder<TBuilt>` for standalone, `INestedBuilder<TParent>` for nested
+- Scope extensions for Kotlin-inspired chaining methods
+
+## Error Handling
+- Use pattern matching (`is null` instead of `== null`)
+- Prefer null propagation and coalescing expressions
+- All warnings are treated as errors in build

BannedSymbols.txt

@@ -0,0 +1 @@
+T:System.Console;Use TimeWarp.Terminal.Terminal static class or inject ITerminal instead