@cubis/foundry 0.3.67 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/csharp-pro/references/testing-and-analyzers.md

@@ -0,0 +1,214 @@
+# Testing and Analyzers
+
+## Testing Stack
+
+```xml
+<!-- Common test project dependencies -->
+<PackageReference Include="Microsoft.NET.Test.Sdk" />
+<PackageReference Include="xunit" />
+<PackageReference Include="xunit.runner.visualstudio" />
+<PackageReference Include="FluentAssertions" />
+<PackageReference Include="NSubstitute" />
+<PackageReference Include="Testcontainers.PostgreSql" />
+<PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" />
+```
+
+## Unit Test Patterns
+
+```csharp
+public class OrderServiceTests
+{
+    private readonly IOrderRepository _repo = Substitute.For<IOrderRepository>();
+    private readonly ILogger<OrderService> _logger = Substitute.For<ILogger<OrderService>>();
+    private readonly OrderService _sut;
+
+    public OrderServiceTests()
+    {
+        _sut = new OrderService(_repo, _logger);
+    }
+
+    [Fact]
+    public async Task GetAsync_ExistingOrder_ReturnsOrder()
+    {
+        // Arrange
+        var expected = new Order { Id = 1, CustomerName = "Alice" };
+        _repo.FindAsync(1, Arg.Any<CancellationToken>()).Returns(expected);
+
+        // Act
+        var result = await _sut.GetAsync(1, CancellationToken.None);
+
+        // Assert
+        result.Should().Be(expected);
+        await _repo.Received(1).FindAsync(1, Arg.Any<CancellationToken>());
+    }
+
+    [Fact]
+    public async Task GetAsync_MissingOrder_ThrowsNotFound()
+    {
+        _repo.FindAsync(99, Arg.Any<CancellationToken>()).Returns((Order?)null);
+
+        var act = () => _sut.GetAsync(99, CancellationToken.None);
+
+        await act.Should().ThrowAsync<OrderNotFoundException>()
+            .WithMessage("*99*");
+    }
+
+    [Theory]
+    [InlineData(0)]
+    [InlineData(-1)]
+    public async Task GetAsync_InvalidId_ThrowsArgument(int id)
+    {
+        var act = () => _sut.GetAsync(id, CancellationToken.None);
+        await act.Should().ThrowAsync<ArgumentOutOfRangeException>();
+    }
+}
+```
+
+## Integration Testing with WebApplicationFactory
+
+```csharp
+public class OrderApiTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+
+    public OrderApiTests(WebApplicationFactory<Program> factory)
+    {
+        _client = factory.WithWebHostBuilder(builder =>
+        {
+            builder.ConfigureServices(services =>
+            {
+                // Replace real DB with in-memory or testcontainer
+                services.RemoveAll<DbContextOptions<AppDbContext>>();
+                services.AddDbContext<AppDbContext>(opt =>
+                    opt.UseInMemoryDatabase("TestDb"));
+            });
+        }).CreateClient();
+    }
+
+    [Fact]
+    public async Task CreateOrder_ValidPayload_Returns201()
+    {
+        var payload = new { CustomerName = "Alice", Items = new[] { new { Name = "Widget", Qty = 2 } } };
+        var response = await _client.PostAsJsonAsync("/api/orders", payload);
+
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+        var order = await response.Content.ReadFromJsonAsync<OrderDto>();
+        order!.CustomerName.Should().Be("Alice");
+    }
+}
+```
+
+## Testcontainers for Real Dependencies
+
+```csharp
+public class PostgresOrderTests : IAsyncLifetime
+{
+    private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()
+        .WithImage("postgres:16-alpine")
+        .Build();
+
+    public async Task InitializeAsync()
+    {
+        await _postgres.StartAsync();
+    }
+
+    public async Task DisposeAsync()
+    {
+        await _postgres.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Repository_SaveAndRetrieve_RoundTrips()
+    {
+        var options = new DbContextOptionsBuilder<AppDbContext>()
+            .UseNpgsql(_postgres.GetConnectionString())
+            .Options;
+
+        await using var ctx = new AppDbContext(options);
+        await ctx.Database.MigrateAsync();
+
+        var repo = new EfOrderRepository(ctx);
+        var order = new Order { CustomerName = "Alice" };
+        await repo.SaveAsync(order, CancellationToken.None);
+
+        var loaded = await repo.FindAsync(order.Id, CancellationToken.None);
+        loaded.Should().NotBeNull();
+        loaded!.CustomerName.Should().Be("Alice");
+    }
+}
+```
+
+## Roslyn Analyzer Configuration
+
+```ini
+# .editorconfig — enforce code quality rules
+
+[*.cs]
+# Nullable warnings as errors
+dotnet_diagnostic.CS8600.severity = error  # Converting null literal
+dotnet_diagnostic.CS8602.severity = error  # Dereference of a possibly null reference
+dotnet_diagnostic.CS8603.severity = error  # Possible null reference return
+
+# Async best practices
+dotnet_diagnostic.CA2007.severity = warning  # ConfigureAwait
+dotnet_diagnostic.CA2008.severity = error    # Do not create tasks without passing a TaskScheduler
+dotnet_diagnostic.CA2012.severity = error    # Use ValueTasks correctly
+
+# Reliability
+dotnet_diagnostic.CA2000.severity = warning  # Dispose objects before losing scope
+dotnet_diagnostic.CA2213.severity = warning  # Disposable fields should be disposed
+
+# Security
+dotnet_diagnostic.CA2100.severity = error    # Review SQL queries for security vulnerabilities
+dotnet_diagnostic.CA3001.severity = error    # Review code for SQL injection vulnerabilities
+dotnet_diagnostic.CA5351.severity = error    # Do not use broken cryptographic algorithms
+```
+
+## BenchmarkDotNet
+
+```csharp
+[MemoryDiagnoser]         // track allocations
+[SimpleJob(RuntimeMoniker.Net90)]
+public class SerializationBenchmarks
+{
+    private readonly Order _order = CreateSampleOrder();
+
+    [Benchmark(Baseline = true)]
+    public string SystemTextJson()
+        => JsonSerializer.Serialize(_order);
+
+    [Benchmark]
+    public string NewtonsoftJson()
+        => JsonConvert.SerializeObject(_order);
+
+    [Benchmark]
+    public byte[] MessagePack()
+        => MessagePackSerializer.Serialize(_order);
+}
+
+// Run: dotnet run -c Release --project Benchmarks
+```
+
+## Test Organization
+
+```
+tests/
+├── Unit/                      # Fast, isolated
+│   ├── Domain/
+│   │   └── OrderTests.cs
+│   └── Services/
+│       └── OrderServiceTests.cs
+├── Integration/               # Real dependencies
+│   ├── Repositories/
+│   │   └── EfOrderRepoTests.cs
+│   └── Api/
+│       └── OrderApiTests.cs
+└── Benchmarks/                # Performance
+    └── SerializationBenchmarks.cs
+```
+
+| Layer       | Speed | Dependencies    | When to use                                |
+| ----------- | ----- | --------------- | ------------------------------------------ |
+| Unit        | <1ms  | Mocks only      | Business logic, validation, pure functions |
+| Integration | <5s   | DB, HTTP, cache | Repository, API, cross-service             |
+| Benchmark   | N/A   | Real workload   | Before/after optimization                  |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/dart-pro/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: "dart-pro"
+description: "Use for modern Dart engineering across Flutter, server, and CLI code with Dart 3.11-era language features, package hygiene, isolates, and testing discipline."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "2.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Dart Pro
+
+## Purpose
+
+Expert-level guidance for modern Dart development across Flutter app logic, server applications, and CLI tooling. Covers null safety, sealed classes with pattern matching, async and isolate patterns, package hygiene, and testing discipline using current Dart language features.
+
+## When to Use
+
+- Designing Dart libraries, Flutter app logic, or Dart CLI tooling.
+- Refactoring null-safety, sealed classes, records, or pattern matching.
+- Improving package structure, async correctness, and testability.
+
+## Instructions
+
+1. **Confirm runtime context** — identify whether the code targets Flutter UI, server, or CLI. This determines available APIs, isolate patterns, and testing approaches.
+
+2. **Keep null safety and type intent explicit** — prefer non-nullable types by default. Use `?` only when null is a valid domain value. Use `late` only when initialization is guaranteed before access. Target sound null safety with no `// ignore: null_check` suppressions without justification. Do not use `!` (null assertion) in production code without a preceding null check because it crashes at runtime.
+
+3. **Use sealed models, records, and pattern matching** — use sealed classes for closed type hierarchies with exhaustive `switch` that catches missing cases at compile time. Use records `(int, String)` for lightweight grouped returns. Use `switch` expressions with pattern matching for state machines. Prefer destructuring in `if-case` and `switch` over manual `is` checks and casts.
+
+4. **Design async flows with proper lifecycle** — use `async`/`await` for I/O-bound work. Keep `Future` chains flat. Use `Stream` for event-driven data with `StreamController.broadcast()` only when multiple listeners are needed. Cancel subscriptions and close controllers in `dispose()` to prevent memory leaks. Do not block the main isolate with synchronous I/O or heavy computation because it freezes the UI.
+
+5. **Offload compute to isolates when needed** — use `Isolate.run()` or `compute()` in Flutter for CPU-heavy work. Keep the main isolate responsive for UI and event handling.
+
+6. **Maintain package hygiene** — keep `pubspec.yaml` dependencies minimal. Use `dart pub outdated` to identify stale dependencies. Export only the public API from `lib/src/` via a barrel file. Pin SDK constraint to the minimum required version. Keep `pubspec.lock` in version control for applications (not for libraries). Do not import implementation files from `lib/src/` directly in other packages because it breaks encapsulation.
+
+7. **Run analysis before committing** — run `dart analyze` with zero warnings. Treat analyzer warnings as defects. Use `dart format` for consistent style. Do not override formatter rules per-file. Do not ignore analyzer warnings with `// ignore:` comments without a justification comment because it hides real defects.
+
+8. **Test business logic independently** — use `package:test` for unit tests, `package:mocktail` or `package:mockito` for mocking. Test logic in plain Dart classes independent of Flutter widgets. Run tests with `--coverage` and review uncovered branches. Do not mix business logic into widget `build()` methods because it prevents isolated testing.
+
+9. **Do not use `dynamic` as a type** because it disables all static checking — use `Object` or generics instead.
+
+## Output Format
+
+Produces Dart code with sound null safety, sealed class hierarchies, pattern matching, and clean async patterns. Includes barrel exports and analyzer-clean output with proper package structure.
+
+## References
+
+| File                                           | Load when                                                                                                           |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `references/null-safety-and-async-patterns.md` | Null safety migration, sealed class patterns, async/isolate architecture, or stream lifecycle management is needed. |
+| `references/sealed-records-patterns.md`        | You need sealed class hierarchies, records, destructuring, or exhaustive switch patterns for state modeling.        |
+| `references/isolate-and-concurrency.md`        | You need isolate architecture, compute offload, port communication, or Flutter isolate integration patterns.        |
+| `references/package-structure-and-linting.md`  | You need pub workspace layout, barrel exports, analysis_options rules, or dependency audit workflow.                |
+| `references/testing-and-mocking.md`            | You need test patterns with mockito/mocktail, widget testing, golden tests, or coverage-driven CI.                  |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Refactor this state management code to use sealed classes with exhaustive pattern matching instead of enum flags."
+- "Design the isolate architecture for this image processing pipeline in a Flutter app."
+- "Set up the package structure for this shared Dart library with proper barrel exports and analysis_options."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/dart-pro/references/isolate-and-concurrency.md

@@ -0,0 +1,180 @@
+# Isolate and Concurrency Patterns
+
+## Isolate.run — Simple Compute Offload
+
+```dart
+// Isolate.run for one-shot heavy computation (Dart 3.0+)
+Future<List<SearchResult>> searchIndex(String query) async {
+  final data = await loadIndexData();
+
+  // Runs in a new isolate — no main-isolate jank
+  return await Isolate.run(() {
+    return performSearch(data, query); // data is copied to isolate
+  });
+}
+
+// In Flutter, use compute() for the same purpose
+final results = await compute(performSearch, (data, query));
+```
+
+## Long-Lived Isolates with Ports
+
+```dart
+// Long-lived worker for continuous processing
+class ImageProcessor {
+  late final Isolate _isolate;
+  late final SendPort _sendPort;
+  final ReceivePort _receivePort = ReceivePort();
+  final Map<int, Completer<Uint8List>> _pending = {};
+  int _nextId = 0;
+
+  Future<void> start() async {
+    _isolate = await Isolate.spawn(_workerEntryPoint, _receivePort.sendPort);
+
+    // First message from worker is its SendPort
+    final completer = Completer<SendPort>();
+    _receivePort.listen((message) {
+      if (message is SendPort) {
+        completer.complete(message);
+      } else if (message is (int, Uint8List)) {
+        final (id, result) = message;
+        _pending.remove(id)?.complete(result);
+      }
+    });
+    _sendPort = await completer.future;
+  }
+
+  Future<Uint8List> processImage(Uint8List imageData) {
+    final id = _nextId++;
+    final completer = Completer<Uint8List>();
+    _pending[id] = completer;
+    _sendPort.send((id, imageData));
+    return completer.future;
+  }
+
+  void dispose() {
+    _isolate.kill(priority: Isolate.immediate);
+    _receivePort.close();
+  }
+
+  static void _workerEntryPoint(SendPort mainPort) {
+    final workerPort = ReceivePort();
+    mainPort.send(workerPort.sendPort);
+
+    workerPort.listen((message) {
+      if (message is (int, Uint8List)) {
+        final (id, data) = message;
+        final result = _applyFilters(data); // heavy work
+        mainPort.send((id, result));
+      }
+    });
+  }
+
+  static Uint8List _applyFilters(Uint8List data) {
+    // ... image processing
+    return data;
+  }
+}
+```
+
+## Stream-Based Concurrency
+
+```dart
+// StreamController for event-driven architecture
+class EventBus {
+  final _controller = StreamController<AppEvent>.broadcast();
+
+  Stream<AppEvent> get events => _controller.stream;
+
+  // Type-filtered streams
+  Stream<T> on<T extends AppEvent>() =>
+      _controller.stream.whereType<T>();
+
+  void emit(AppEvent event) => _controller.add(event);
+
+  void dispose() => _controller.close();
+}
+
+// Usage
+final bus = EventBus();
+bus.on<OrderCreated>().listen((event) {
+  notifyUser(event.orderId);
+});
+bus.emit(OrderCreated(orderId: 42));
+```
+
+## Stream Transformations
+
+```dart
+// Debounce search input
+Stream<String> debounce(Stream<String> input, Duration delay) async* {
+  Timer? timer;
+  String? lastValue;
+
+  await for (final value in input) {
+    lastValue = value;
+    timer?.cancel();
+    timer = Timer(delay, () {});
+    await Future.delayed(delay);
+    if (lastValue == value) yield value;
+  }
+}
+
+// Rate limiting with Stream.asyncMap
+Stream<Response> rateLimited(
+  Stream<Request> requests, {
+  Duration interval = const Duration(milliseconds: 100),
+}) {
+  return requests.asyncMap((request) async {
+    await Future.delayed(interval);
+    return await processRequest(request);
+  });
+}
+
+// Cancellation pattern
+class DataFetcher {
+  StreamSubscription? _subscription;
+
+  void startListening(Stream<Update> updates) {
+    // Cancel previous subscription before starting new one
+    _subscription?.cancel();
+    _subscription = updates.listen(
+      (update) => handleUpdate(update),
+      onError: (e) => handleError(e),
+      onDone: () => handleDone(),
+    );
+  }
+
+  void dispose() {
+    _subscription?.cancel(); // always cancel in dispose
+    _subscription = null;
+  }
+}
+```
+
+## Zones for Error Handling
+
+```dart
+// Run code in a zone to catch uncaught async errors
+void main() {
+  runZonedGuarded(
+    () => runApp(const MyApp()),
+    (error, stackTrace) {
+      // Catches uncaught errors from async code
+      reportError(error, stackTrace);
+    },
+  );
+}
+```
+
+## Concurrency Rules
+
+| Rule                                                       | Reason                                         |
+| ---------------------------------------------------------- | ---------------------------------------------- |
+| Never do heavy compute on main isolate                     | Causes UI jank (>16ms blocks drop frames)      |
+| Use `Isolate.run` for one-shot work                        | Simpler than managing ports                    |
+| Use persistent isolates for ongoing work                   | Avoids spawn/teardown overhead per task        |
+| Cancel stream subscriptions in `dispose()`                 | Prevents memory leaks and ghost listeners      |
+| Don't share mutable state across isolates                  | Isolates have separate heaps — send copies     |
+| Use `TransferableTypedData` for large buffers              | Avoids copying overhead for byte arrays        |
+| Use `StreamController.broadcast()` only for multi-listener | Single-listener controllers are more efficient |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/dart-pro/references/null-safety-and-async-patterns.md

@@ -0,0 +1,133 @@
+# Null Safety and Async Patterns
+
+## Null safety rules
+
+### Non-nullable by default
+
+- `String name` means name is never null. `String? name` means null is a valid value.
+- Use `?` only when null carries domain meaning (e.g., "no value selected"), not as a lazy default.
+- Avoid `late` unless the variable is guaranteed to be initialized before use and you cannot restructure to avoid it.
+
+### Null assertion (`!`) usage
+
+- **Never** use `!` without a preceding null check or guard in the same scope in production code.
+- In tests, `!` is acceptable after assertions: `expect(result, isNotNull); result!.doSomething();`
+- Prefer `if-case` or null-aware operators (`?.`, `??`) over `!`.
+
+### Null-aware operators cheatsheet
+
+| Operator | Meaning                      | Example                    |
+| -------- | ---------------------------- | -------------------------- |
+| `?.`     | Call method only if non-null | `user?.name`               |
+| `??`     | Default if null              | `name ?? 'Unknown'`        |
+| `??=`    | Assign if null               | `cache ??= compute()`      |
+| `?..`    | Cascade only if non-null     | `list?..add(item)..sort()` |
+
+## Sealed classes and pattern matching
+
+### Defining sealed hierarchies
+
+```dart
+sealed class AuthState {}
+class Unauthenticated extends AuthState {}
+class Authenticating extends AuthState {}
+class Authenticated extends AuthState {
+  final User user;
+  Authenticated(this.user);
+}
+```
+
+- Sealed classes enable **exhaustive switch** — the compiler errors if a subtype is missing.
+- Adding a new subtype immediately surfaces all locations that need updating.
+
+### Exhaustive switch
+
+```dart
+Widget build(AuthState state) => switch (state) {
+  Unauthenticated() => const LoginPage(),
+  Authenticating()  => const LoadingSpinner(),
+  Authenticated(:final user) => HomePage(user: user),
+};
+```
+
+- Use destructuring (`:final field`) to extract values in switch arms.
+- Prefer switch expressions over if/else chains for sealed types.
+
+## Records
+
+```dart
+(int, String) parseHeader(String line) {
+  final parts = line.split(':');
+  return (int.parse(parts[0]), parts[1].trim());
+}
+
+final (code, message) = parseHeader('200: OK');
+```
+
+- Use records for lightweight grouped returns — no need to create single-use classes.
+- Name fields for clarity: `({int id, String name}) getUserInfo()`.
+- Records are value types: equality is structural, not referential.
+
+## Async patterns
+
+### Future best practices
+
+- Always `await` Futures. Never fire-and-forget unless you explicitly handle errors with `.catchError` or a zone.
+- Use `Future.wait` for concurrent independent operations, not sequential `await` calls.
+- Handle errors with try/catch around `await`, not `.catchError` chains.
+
+### Stream lifecycle management
+
+```dart
+class EventManager {
+  final _controller = StreamController<Event>.broadcast();
+  Stream<Event> get events => _controller.stream;
+
+  void emit(Event e) => _controller.add(e);
+
+  void dispose() {
+    _controller.close(); // Always close controllers
+  }
+}
+```
+
+- Use `StreamController` (not broadcast) when only one listener is expected.
+- Use `.broadcast()` only when multiple listeners must receive the same events.
+- Always cancel `StreamSubscription` in `dispose()` or `deactivate()`.
+- Prefer `async*` generator functions for producing streams from iteration or polling.
+
+### Isolate patterns
+
+```dart
+// Simple isolate for CPU-heavy work
+final result = await Isolate.run(() {
+  return heavyComputation(data);
+});
+```
+
+- Use `Isolate.run()` (Dart 2.19+) for one-shot CPU work. It handles spawning and result transfer.
+- In Flutter, use `compute()` for the same pattern with simpler API.
+- For long-lived isolates, use `ReceivePort`/`SendPort` for bidirectional communication.
+- Only `Sendable` objects can cross isolate boundaries. Classes with closures or raw pointers cannot be sent.
+
+## Error handling in async code
+
+```dart
+Future<User> fetchUser(int id) async {
+  try {
+    final response = await http.get(Uri.parse('/users/$id'));
+    if (response.statusCode != 200) {
+      throw HttpException('Failed to fetch user: ${response.statusCode}');
+    }
+    return User.fromJson(jsonDecode(response.body));
+  } on SocketException {
+    throw NetworkException('No network connection');
+  } on FormatException {
+    throw ParseException('Invalid response format');
+  }
+}
+```
+
+- Catch specific exceptions. Avoid bare `catch (e)` unless you re-throw.
+- Transform low-level exceptions into domain-specific exceptions at service boundaries.
+- Use `Zone.current.handleUncaughtError` or `runZonedGuarded` for global error handling in Flutter.