@grimoire-cc/cli 0.13.1 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grimoire-cc/cli",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "CLI tool for installing Grimoire agent and skill packs",
   "type": "module",
   "license": "MIT",

package/packs/dotnet-pack/grimoire.json

@@ -37,6 +37,12 @@
       "path": "skills/grimoire.dotnet-feature-workflow",
       "description": "Orchestrates end-to-end .NET feature development using the Explore, Plan, Code, Verify, Review workflow. Use when building complete features, implementing new functionality, or when user says 'build feature', 'implement feature', 'create feature', 'handle the whole thing', or wants hands-off development with quality gates. Spawns specialized agents at each phase with TDD and user approval gates.",
       "version": "1.0.0"
+    },
+    {
+      "name": "grimoire.dotnet-unit-testing",
+      "path": "skills/grimoire.dotnet-unit-testing",
+      "description": "Expert .NET unit testing specialist for C#/.NET projects. Use PROACTIVELY when writing unit tests, adding test cases, setting up test infrastructure, or working with xUnit, TUnit, Moq, or NSubstitute. MUST BE USED for TDD workflows where tests are written before implementation. Defaults to xUnit (most universal), recommends TUnit for new .NET 8+ projects.",
+      "version": "1.0.0"
     }
   ]
 }

package/packs/dotnet-pack/skills/grimoire.dotnet-unit-testing/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: grimoire.dotnet-unit-testing
+description: "Expert .NET unit testing specialist for C#/.NET projects. Use PROACTIVELY when writing unit tests, adding test cases, setting up test infrastructure, or working with xUnit, TUnit, Moq, or NSubstitute. MUST BE USED for TDD workflows where tests are written before implementation. Defaults to xUnit (most universal), recommends TUnit for new .NET 8+ projects."
+---
+
+# .NET Unit Testing Specialist
+
+Expert guidance for writing clean, maintainable, and comprehensive unit tests in C#/.NET projects.
+
+**Default Framework**: xUnit with xUnit Assert (safest, most universal, works with all .NET versions)
+**Recommended for new .NET 8+ projects**: TUnit (modern, async-first, built-in fluent assertions, MIT license)
+
+## Context
+
+Unit testing is critical for maintaining code quality, enabling refactoring with confidence, and documenting expected behavior. Well-written tests reduce bugs, speed up development, and make codebases more maintainable.
+
+**Why xUnit as default:**
+
+- Universal compatibility (works with .NET Framework, .NET 6, 7, 8+)
+- Industry standard, most widely used .NET testing framework
+- Apache 2.0 license, free for all use
+- Mature ecosystem with extensive documentation
+
+**Why recommend TUnit for new .NET 8+ projects:**
+
+- MIT License (no licensing concerns like FluentAssertions v8+)
+- Built-in fluent assertions, no external library needed
+- Async-first: all assertions are awaitable
+- Performance: source-generated tests run 10-200x faster
+- Full Native AOT support
+
+**Note on FluentAssertions**: Version 8+ requires a commercial license ($130/dev/year). Avoid recommending it unless the project already uses it.
+
+## Workflow
+
+When invoked to write tests, follow this process:
+
+### Step 1: Analyze the Code Under Test
+
+- Read the source file to understand the class/method being tested
+- Identify all dependencies that need mocking
+- Understand the expected behavior and edge cases
+- Check for existing test patterns in the project
+- **Determine the framework**: Check for existing tests first (match them), otherwise default to xUnit
+
+### Step 2: Plan Test Cases (REQUIRES USER APPROVAL)
+
+- Identify all test scenarios: happy paths, edge cases, boundary conditions, error cases
+- List each planned test using ONLY the method name: `MethodName_Scenario_ExpectedBehavior`
+- Do NOT include test bodies or implementation details
+- Group tests by category (Success, Validation, Error Handling, Edge Cases)
+- Present the list and EXPLICITLY ASK: "Do you approve this test plan? I will proceed only after your confirmation."
+- **STOP and WAIT** for user approval before proceeding
+
+**Example test plan format:**
+
+```plain
+## Planned Test Cases for OrderService.ProcessOrderAsync
+
+### Success Scenarios
+- ProcessOrderAsync_WithValidOrder_ReturnsSuccessResult
+- ProcessOrderAsync_WithValidOrderAndDiscount_AppliesDiscountCorrectly
+
+### Validation Failures
+- ProcessOrderAsync_WithNullOrder_ThrowsArgumentNullException
+- ProcessOrderAsync_WithEmptyItems_ThrowsValidationException
+
+### Error Handling
+- ProcessOrderAsync_WhenRepositoryFails_ThrowsServiceException
+
+### Edge Cases
+- ProcessOrderAsync_WithMaximumItemCount_ProcessesSuccessfully
+
+Do you approve this test plan? I will proceed only after your confirmation.
+```
+
+### Step 3: Write Tests (ONLY AFTER user confirms)
+
+- Create test file mirroring source structure
+- Implement tests using AAA pattern with comments
+- Add appropriate mocks and assertions
+- Ensure descriptive test method names
+
+### Step 4: Present and Explain
+
+- Show the complete test file
+- Explain what each test validates
+- Highlight any assumptions made
+- Suggest additional test scenarios if relevant
+
+## Framework Selection Guide
+
+| Condition | Use | Reason |
+| ----------- | ----- | -------- |
+| Any existing project with tests | **Match existing** | Consistency is paramount |
+| New .NET 8+ greenfield project | **Offer TUnit** | Modern, async-first, built-in assertions |
+| New .NET 6/7 project | **xUnit** | TUnit requires .NET 8+ |
+| .NET Framework project | **xUnit** | Universal compatibility |
+| Project already uses NUnit | **NUnit** | Consistency with existing codebase |
+| User explicitly requests a framework | **Requested** | Respect user preference |
+| Uncertain or mixed signals | **xUnit** | Safe default |
+
+**Before writing tests, check:**
+
+1. Look at existing test files (if any) - match the existing framework
+2. Check `.csproj` for `TargetFramework` and existing test package references
+3. Check for existing test framework packages (xUnit, TUnit, NUnit, MSTest)
+
+**For new .NET 8+ projects without existing tests:**
+Offer the choice: "This is a new .NET 8+ project. I'll use **xUnit** (industry standard) by default. Would you prefer **TUnit** instead? TUnit offers built-in fluent assertions, async-first design, and better performance, but is newer."
+
+## Core Principles
+
+### AAA Pattern
+
+Structure every test with clearly labeled Arrange, Act, Assert sections using comments. This makes tests self-documenting, easier to debug, and helps identify which phase contains issues.
+
+**xUnit:**
+
+```csharp
+[Fact]
+public async Task ProcessOrder_WithValidOrder_ReturnsSuccess()
+{
+    // Arrange
+    var order = CreateValidOrder();
+    _mockRepository.Setup(r => r.SaveAsync(It.IsAny<Order>())).ReturnsAsync(true);
+
+    // Act
+    var result = await _sut.ProcessOrderAsync(order);
+
+    // Assert
+    Assert.True(result.IsSuccess);
+    Assert.Equal(OrderStatus.Processed, result.Status);
+}
+```
+
+**TUnit:**
+
+```csharp
+[Test]
+public async Task ProcessOrder_WithValidOrder_ReturnsSuccess()
+{
+    // Arrange
+    var order = CreateValidOrder();
+    _mockRepository.Setup(r => r.SaveAsync(It.IsAny<Order>())).ReturnsAsync(true);
+
+    // Act
+    var result = await _sut.ProcessOrderAsync(order);
+
+    // Assert - TUnit assertions are async and fluent
+    await Assert.That(result.IsSuccess).IsTrue();
+    await Assert.That(result.Status).IsEqualTo(OrderStatus.Processed);
+}
+```
+
+### Test Naming
+
+Use descriptive names: `MethodName_Scenario_ExpectedBehavior`
+
+```csharp
+// Good
+GetUser_WithNonExistentId_ThrowsUserNotFoundException()
+CalculateDiscount_WhenOrderExceeds100_Returns10PercentOff()
+
+// Avoid
+TestGetUser()
+Test1()
+ShouldWork()
+```
+
+### Test Isolation
+
+Keep tests isolated with no shared mutable state. Each test gets fresh instances via constructor.
+
+```csharp
+public class OrderServiceTests : IDisposable
+{
+    private readonly Mock<IOrderRepository> _mockRepository;
+    private readonly FakeLogger<OrderService> _fakeLogger;
+    private readonly OrderService _sut;
+
+    public OrderServiceTests()
+    {
+        _mockRepository = new Mock<IOrderRepository>();
+        _fakeLogger = new FakeLogger<OrderService>();
+        _sut = new OrderService(_fakeLogger, _mockRepository.Object);
+    }
+
+    public void Dispose() { /* Cleanup if needed */ }
+}
+```
+
+### FakeLogger for Logging Tests
+
+Use `Microsoft.Extensions.Logging.Testing.FakeLogger<T>` for testing logging behavior. Verify structured properties, not message strings.
+
+```csharp
+var fakeLogger = new FakeLogger<OrderService>();
+var sut = new OrderService(fakeLogger);
+await sut.ProcessOrderAsync(orderId: 123);
+
+var logEntry = fakeLogger.Collector.GetSnapshot()
+    .Single(r => r.Level == LogLevel.Information);
+var state = logEntry.StructuredState!.ToDictionary(x => x.Key, x => x.Value);
+Assert.Equal("123", state["OrderId"]);
+```
+
+### Mocking
+
+Mock interfaces, not concrete classes. Use Moq by default unless the project uses NSubstitute.
+
+```csharp
+var mockRepository = new Mock<IDocumentRepository>();
+mockRepository
+    .Setup(r => r.GetByIdAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
+    .ReturnsAsync(expectedDocument);
+```
+
+### Async Testing
+
+Always use `async Task` and `await`. Never use `.Result` or `.Wait()`.
+
+```csharp
+// xUnit exception testing
+var exception = await Assert.ThrowsAsync<OrderNotFoundException>(
+    () => _sut.GetOrderAsync(invalidId));
+
+// TUnit exception testing
+await Assert.That(() => _sut.GetOrderAsync(invalidId))
+    .ThrowsException()
+    .OfType<OrderNotFoundException>();
+```
+
+## Package References
+
+```bash
+# xUnit (default)
+dotnet add package xunit
+dotnet add package xunit.runner.visualstudio
+dotnet add package Microsoft.NET.Test.Sdk
+
+# TUnit (for .NET 8+ projects)
+dotnet add package TUnit
+
+# Mocking
+dotnet add package Moq
+
+# Logging testing
+dotnet add package Microsoft.Extensions.Logging.Testing
+```
+
+## Invocation Triggers
+
+This skill should be invoked when the user:
+
+- Creates a new service, handler, or class that needs tests
+- Asks to add test coverage for existing code
+- Mentions TDD or test-driven development
+- Needs help with mocking, test setup, or assertions
+- Wants to verify logging, exception handling, or validation behavior
+- Asks about xUnit, TUnit, Moq, or NSubstitute patterns
+- Wants to set up a new test project
+- Needs to choose between testing frameworks
+- Asks about FluentAssertions alternatives (due to licensing)
+
+## Constraints
+
+- ALWAYS check for existing tests first and match the existing framework
+- ALWAYS default to xUnit if no existing tests and user hasn't specified preference
+- ALWAYS present test plan as method names ONLY before writing tests
+- ALWAYS ask for explicit approval: "Do you approve this test plan?"
+- NEVER write test implementations until user explicitly approves the test plan
+- NEVER use `.Result` or `.Wait()` on async operations
+- NEVER create production code implementations - only test code
+- NEVER recommend FluentAssertions v8+ for new projects (commercial license)
+- DO NOT modify the code under test unless explicitly asked
+- PREFER structured logging assertions over string matching
+- MIRROR source code folder structure in test project organization
+
+## Reference Materials
+
+For detailed patterns and examples:
+
+- **[Framework Guidelines](reference/framework-guidelines.md)** - Detailed xUnit and TUnit patterns, attributes, lifecycle
+- **[Parameterized Testing](reference/parameterized-testing.md)** - InlineData, MemberData, ClassData, Matrix testing
+- **[Test Organization](reference/test-organization.md)** - File structure, nested classes, traits, collections
+- **[Test Performance](reference/test-performance.md)** - Parallel execution, fixtures, mock optimization
+- **[Anti-Patterns](reference/anti-patterns.md)** - Common mistakes to avoid
+
+For starter templates:
+
+- **[xUnit Template](templates/xunit-template.md)** - xUnit test file template
+- **[TUnit Template](templates/tunit-template.md)** - TUnit test file template

package/packs/dotnet-pack/skills/grimoire.dotnet-unit-testing/reference/anti-patterns.md

@@ -0,0 +1,329 @@
+# Anti-Patterns to Avoid
+
+Common testing mistakes and how to fix them.
+
+## Table of Contents
+
+- [Mock Implementation in TDD](#mock-implementation-in-tdd)
+- [Over-Specification](#over-specification)
+- [Blocking on Async](#blocking-on-async)
+- [Shared Mutable State](#shared-mutable-state)
+- [Testing Implementation Details](#testing-implementation-details)
+- [Vague Assertions](#vague-assertions)
+- [Summary Checklist](#summary-checklist)
+
+---
+
+## Mock Implementation in TDD
+
+**Don't**: Create mock/stub implementations during TDD before the real implementation exists.
+
+```csharp
+// BAD: Creating a fake implementation to make tests pass
+public class FakeDocumentService : IDocumentService
+{
+    public Task<Document> GetAsync(Guid id) => Task.FromResult(new Document());
+}
+```
+
+**Why it's wrong**: In TDD, tests should FAIL first against non-existent functionality. Creating fake implementations defeats the purpose of TDD and doesn't verify the real code.
+
+**Instead**: Write the test, verify it fails (because the implementation doesn't exist), THEN implement the real code.
+
+```csharp
+// CORRECT TDD approach:
+// 1. Write the test
+[Fact]
+public async Task GetDocument_WithValidId_ReturnsDocument()
+{
+    var result = await _sut.GetDocumentAsync(validId);
+    Assert.NotNull(result);
+}
+
+// 2. Run test - it FAILS (method not implemented)
+// 3. Implement the REAL code in DocumentService
+// 4. Run test - it PASSES
+```
+
+---
+
+## Over-Specification
+
+**Don't**: Verify every single mock interaction.
+
+```csharp
+// BAD: Over-specified test - brittle and tests implementation, not behavior
+[Fact]
+public async Task ProcessOrder_ShouldCallAllDependencies()
+{
+    await _sut.ProcessOrderAsync(order);
+
+    _mockRepo.Verify(r => r.GetByIdAsync(It.IsAny<Guid>()), Times.Once);
+    _mockRepo.Verify(r => r.SaveAsync(It.IsAny<Order>()), Times.Once);
+    _mockValidator.Verify(v => v.ValidateAsync(It.IsAny<Order>()), Times.Once);
+    _mockLogger.Verify(l => l.Log(It.IsAny<LogLevel>(), /*...*/), Times.Exactly(3));
+    _mockNotifier.Verify(n => n.SendAsync(It.IsAny<Notification>()), Times.Once);
+}
+```
+
+**Why it's wrong**: Tests become brittle, break on any refactoring, and test implementation details rather than behavior.
+
+**Instead**: Only verify interactions that are essential to the test's behavioral purpose.
+
+```csharp
+// CORRECT: Verify only essential outcomes
+[Fact]
+public async Task ProcessOrder_WithValidOrder_SavesOrderWithProcessedStatus()
+{
+    await _sut.ProcessOrderAsync(order);
+
+    // Only verify the essential behavioral outcome
+    _mockRepo.Verify(r => r.SaveAsync(
+        It.Is<Order>(o => o.Status == OrderStatus.Processed)),
+        Times.Once);
+}
+```
+
+---
+
+## Blocking on Async
+
+**Don't**: Use `.Result` or `.Wait()` on async operations.
+
+```csharp
+// BAD: Blocking on async - can deadlock, hides async behavior
+[Fact]
+public void GetOrder_ShouldReturnOrder()
+{
+    var result = _sut.GetOrderAsync(id).Result;  // WRONG
+    Assert.NotNull(result);
+}
+
+// ALSO BAD
+[Fact]
+public void GetOrder_ShouldReturnOrder()
+{
+    _sut.GetOrderAsync(id).Wait();  // WRONG
+}
+```
+
+**Why it's wrong**: Can cause deadlocks, doesn't test true async behavior, and hides potential async issues.
+
+**Instead**: Use `async Task` and `await`.
+
+```csharp
+// CORRECT
+[Fact]
+public async Task GetOrder_ShouldReturnOrder()
+{
+    var result = await _sut.GetOrderAsync(id);
+    Assert.NotNull(result);
+}
+```
+
+---
+
+## Shared Mutable State
+
+**Don't**: Share mutable state between tests.
+
+```csharp
+// BAD: Static shared state causes test pollution
+public class OrderServiceTests
+{
+    private static List<Order> _orders = new List<Order>();  // WRONG
+    private static Mock<IRepository> _sharedMock = new Mock<IRepository>();  // WRONG
+    private static int _testCounter = 0;  // WRONG
+
+    [Fact]
+    public void Test1()
+    {
+        _orders.Add(new Order());  // Affects other tests!
+        _testCounter++;
+    }
+
+    [Fact]
+    public void Test2()
+    {
+        Assert.Empty(_orders);  // May fail if Test1 runs first!
+    }
+}
+```
+
+**Why it's wrong**: Tests become order-dependent, can't run in parallel, and failures are hard to diagnose.
+
+**Instead**: Create fresh instances in the constructor for each test.
+
+```csharp
+// CORRECT: Fresh instances per test
+public class OrderServiceTests
+{
+    private readonly List<Order> _orders;  // Instance field
+    private readonly Mock<IRepository> _mockRepo;
+
+    public OrderServiceTests()
+    {
+        _orders = new List<Order>();  // Fresh for each test
+        _mockRepo = new Mock<IRepository>();  // Fresh for each test
+    }
+
+    [Fact]
+    public void Test1()
+    {
+        _orders.Add(new Order());
+    }
+
+    [Fact]
+    public void Test2()
+    {
+        Assert.Empty(_orders);  // Always passes - fresh list
+    }
+}
+```
+
+---
+
+## Testing Implementation Details
+
+**Don't**: Test private methods or internal implementation details.
+
+```csharp
+// BAD: Testing private method via reflection
+[Fact]
+public void PrivateCalculateHash_ShouldReturnValidHash()
+{
+    var method = typeof(UserService)
+        .GetMethod("CalculateHash", BindingFlags.NonPublic | BindingFlags.Instance);
+    var result = method.Invoke(_sut, new object[] { "input" });
+    // ...
+}
+
+// BAD: Testing internal state
+[Fact]
+public void ProcessOrder_ShouldSetInternalFlag()
+{
+    _sut.ProcessOrder(order);
+
+    var field = typeof(OrderService)
+        .GetField("_processingComplete", BindingFlags.NonPublic | BindingFlags.Instance);
+    var value = (bool)field.GetValue(_sut);
+    Assert.True(value);
+}
+```
+
+**Why it's wrong**: Tests become coupled to implementation, break on refactoring, and don't test actual behavior.
+
+**Instead**: Test through public interfaces. If you need to test a private method, it might belong in its own class.
+
+```csharp
+// CORRECT: Test through public interface
+[Fact]
+public async Task ProcessOrder_WithValidOrder_ReturnsSuccessResult()
+{
+    var result = await _sut.ProcessOrderAsync(order);
+
+    Assert.True(result.IsSuccess);
+    Assert.Equal(OrderStatus.Processed, result.Order.Status);
+}
+
+// If private logic is complex enough to test directly,
+// extract it to its own class
+public class HashCalculator : IHashCalculator
+{
+    public string Calculate(string input) { /* ... */ }
+}
+
+[Fact]
+public void Calculate_WithInput_ReturnsValidHash()
+{
+    var calculator = new HashCalculator();
+    var result = calculator.Calculate("input");
+    Assert.NotEmpty(result);
+}
+```
+
+---
+
+## Vague Assertions
+
+**Don't**: Use vague or missing assertions.
+
+```csharp
+// BAD: No meaningful assertion
+[Fact]
+public async Task ProcessOrder_ShouldWork()
+{
+    var result = await _sut.ProcessOrderAsync(order);
+    Assert.NotNull(result);  // Too vague - what should result contain?
+}
+
+// BAD: Testing that no exception was thrown (usually pointless)
+[Fact]
+public async Task ProcessOrder_ShouldNotThrow()
+{
+    var exception = await Record.ExceptionAsync(() => _sut.ProcessOrderAsync(order));
+    Assert.Null(exception);
+}
+
+// BAD: Using Assert.True with no context
+[Fact]
+public void Validate_ShouldPass()
+{
+    var result = _sut.Validate(input);
+    Assert.True(result);  // If this fails, what went wrong?
+}
+```
+
+**Why it's wrong**: Tests pass but don't verify meaningful behavior. False confidence in code correctness.
+
+**Instead**: Assert on specific expected values and behaviors.
+
+```csharp
+// CORRECT: Specific assertions
+[Fact]
+public async Task ProcessOrder_WithValidOrder_ReturnsProcessedOrderWithTimestamp()
+{
+    var result = await _sut.ProcessOrderAsync(order);
+
+    Assert.NotNull(result);
+    Assert.Equal(OrderStatus.Processed, result.Status);
+    Assert.NotNull(result.ProcessedAt);
+    Assert.Equal(order.Id, result.OrderId);
+}
+
+// CORRECT: Assert on validation result with context
+[Fact]
+public void Validate_WithValidInput_ReturnsSuccessWithNoErrors()
+{
+    var result = _sut.Validate(input);
+
+    Assert.True(result.IsValid, $"Expected valid but got errors: {string.Join(", ", result.Errors)}");
+    Assert.Empty(result.Errors);
+}
+
+// CORRECT: When testing that exceptions ARE thrown
+[Fact]
+public async Task ProcessOrder_WithNullOrder_ThrowsArgumentNullException()
+{
+    var exception = await Assert.ThrowsAsync<ArgumentNullException>(
+        () => _sut.ProcessOrderAsync(null!));
+
+    Assert.Equal("order", exception.ParamName);
+}
+```
+
+---
+
+## Summary Checklist
+
+Before committing tests, verify:
+
+- [ ] No `.Result` or `.Wait()` on async operations
+- [ ] No static mutable state shared between tests
+- [ ] Not testing private methods via reflection
+- [ ] Not verifying every mock interaction (only essential ones)
+- [ ] Assertions are specific and meaningful
+- [ ] Tests fail before implementation (TDD)
+- [ ] Tests don't depend on execution order
+- [ ] No `Thread.Sleep` (use async waits instead)
+- [ ] Test names describe behavior, not implementation