compact-agent 1.10.1 → 1.11.0

package/resources/ecc/rules/dart/security.md

@@ -0,0 +1,135 @@
+---
+paths:
+  - "**/*.dart"
+  - "**/pubspec.yaml"
+  - "**/AndroidManifest.xml"
+  - "**/Info.plist"
+---
+# Dart/Flutter Security
+
+> This file extends [common/security.md](../common/security.md) with Dart, Flutter, and mobile-specific content.
+
+## Secrets Management
+
+- Never hardcode API keys, tokens, or credentials in Dart source
+- Use `--dart-define` or `--dart-define-from-file` for compile-time config (values are not truly secret — use a backend proxy for server-side secrets)
+- Use `flutter_dotenv` or equivalent, with `.env` files listed in `.gitignore`
+- Store runtime secrets in platform-secure storage: `flutter_secure_storage` (Keychain on iOS, EncryptedSharedPreferences on Android)
+
+```dart
+// BAD
+const apiKey = 'sk-abc123...';
+
+// GOOD — compile-time config (not secret, just configurable)
+const apiKey = String.fromEnvironment('API_KEY');
+
+// GOOD — runtime secret from secure storage
+final token = await secureStorage.read(key: 'auth_token');
+```
+
+## Network Security
+
+- Enforce HTTPS — no `http://` calls in production
+- Configure Android `network_security_config.xml` to block cleartext traffic
+- Set `NSAppTransportSecurity` in `Info.plist` to disallow arbitrary loads
+- Set request timeouts on all HTTP clients — never leave defaults
+- Consider certificate pinning for high-security endpoints
+
+```dart
+// Dio with timeout and HTTPS enforcement
+final dio = Dio(BaseOptions(
+  baseUrl: 'https://api.example.com',
+  connectTimeout: const Duration(seconds: 10),
+  receiveTimeout: const Duration(seconds: 30),
+));
+```
+
+## Input Validation
+
+- Validate and sanitize all user input before sending to API or storage
+- Never pass unsanitized input to SQL queries — use parameterized queries (sqflite, drift)
+- Sanitize deep link URLs before navigation — validate scheme, host, and path parameters
+- Use `Uri.tryParse` and validate before navigating
+
+```dart
+// BAD — SQL injection
+await db.rawQuery("SELECT * FROM users WHERE email = '$userInput'");
+
+// GOOD — parameterized
+await db.query('users', where: 'email = ?', whereArgs: [userInput]);
+
+// BAD — unvalidated deep link
+final uri = Uri.parse(incomingLink);
+context.go(uri.path); // could navigate to any route
+
+// GOOD — validated deep link
+final uri = Uri.tryParse(incomingLink);
+if (uri != null && uri.host == 'myapp.com' && _allowedPaths.contains(uri.path)) {
+  context.go(uri.path);
+}
+```
+
+## Data Protection
+
+- Store tokens, PII, and credentials only in `flutter_secure_storage`
+- Never write sensitive data to `SharedPreferences` or local files in plaintext
+- Clear auth state on logout: tokens, cached user data, cookies
+- Use biometric authentication (`local_auth`) for sensitive operations
+- Avoid logging sensitive data — no `print(token)` or `debugPrint(password)`
+
+## Android-Specific
+
+- Declare only required permissions in `AndroidManifest.xml`
+- Export Android components (`Activity`, `Service`, `BroadcastReceiver`) only when necessary; add `android:exported="false"` where not needed
+- Review intent filters — exported components with implicit intent filters are accessible by any app
+- Use `FLAG_SECURE` for screens displaying sensitive data (prevents screenshots)
+
+```xml
+<!-- AndroidManifest.xml — restrict exported components -->
+<activity android:name=".MainActivity" android:exported="true">
+    <!-- Only the launcher activity needs exported=true -->
+</activity>
+<activity android:name=".SensitiveActivity" android:exported="false" />
+```
+
+## iOS-Specific
+
+- Declare only required usage descriptions in `Info.plist` (`NSCameraUsageDescription`, etc.)
+- Store secrets in Keychain — `flutter_secure_storage` uses Keychain on iOS
+- Use App Transport Security (ATS) — disallow arbitrary loads
+- Enable data protection entitlement for sensitive files
+
+## WebView Security
+
+- Use `webview_flutter` v4+ (`WebViewController` / `WebViewWidget`) — the legacy `WebView` widget is removed
+- Disable JavaScript unless explicitly required (`JavaScriptMode.disabled`)
+- Validate URLs before loading — never load arbitrary URLs from deep links
+- Never expose Dart callbacks to JavaScript unless absolutely needed and carefully sandboxed
+- Use `NavigationDelegate.onNavigationRequest` to intercept and validate navigation requests
+
+```dart
+// webview_flutter v4+ API (WebViewController + WebViewWidget)
+final controller = WebViewController()
+  ..setJavaScriptMode(JavaScriptMode.disabled) // disabled unless required
+  ..setNavigationDelegate(
+    NavigationDelegate(
+      onNavigationRequest: (request) {
+        final uri = Uri.tryParse(request.url);
+        if (uri == null || uri.host != 'trusted.example.com') {
+          return NavigationDecision.prevent;
+        }
+        return NavigationDecision.navigate;
+      },
+    ),
+  );
+
+// In your widget tree:
+WebViewWidget(controller: controller)
+```
+
+## Obfuscation and Build Security
+
+- Enable obfuscation in release builds: `flutter build apk --obfuscate --split-debug-info=./debug-info/`
+- Keep `--split-debug-info` output out of version control (used for crash symbolication only)
+- Ensure ProGuard/R8 rules don't inadvertently expose serialized classes
+- Run `flutter analyze` and address all warnings before release

package/resources/ecc/rules/dart/testing.md

@@ -0,0 +1,215 @@
+---
+paths:
+  - "**/*.dart"
+  - "**/pubspec.yaml"
+  - "**/analysis_options.yaml"
+---
+# Dart/Flutter Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Dart and Flutter-specific content.
+
+## Test Framework
+
+- **flutter_test** / **dart:test** — built-in test runner
+- **mockito** (with `@GenerateMocks`) or **mocktail** (no codegen) for mocking
+- **bloc_test** for BLoC/Cubit unit tests
+- **fake_async** for controlling time in unit tests
+- **integration_test** for end-to-end device tests
+
+## Test Types
+
+| Type | Tool | Location | When to Write |
+|------|------|----------|---------------|
+| Unit | `dart:test` | `test/unit/` | All domain logic, state managers, repositories |
+| Widget | `flutter_test` | `test/widget/` | All widgets with meaningful behavior |
+| Golden | `flutter_test` | `test/golden/` | Design-critical UI components |
+| Integration | `integration_test` | `integration_test/` | Critical user flows on real device/emulator |
+
+## Unit Tests: State Managers
+
+### BLoC with `bloc_test`
+
+```dart
+group('CartBloc', () {
+  late CartBloc bloc;
+  late MockCartRepository repository;
+
+  setUp(() {
+    repository = MockCartRepository();
+    bloc = CartBloc(repository);
+  });
+
+  tearDown(() => bloc.close());
+
+  blocTest<CartBloc, CartState>(
+    'emits updated items when CartItemAdded',
+    build: () => bloc,
+    act: (b) => b.add(CartItemAdded(testItem)),
+    expect: () => [CartState(items: [testItem])],
+  );
+
+  blocTest<CartBloc, CartState>(
+    'emits empty cart when CartCleared',
+    seed: () => CartState(items: [testItem]),
+    build: () => bloc,
+    act: (b) => b.add(CartCleared()),
+    expect: () => [const CartState()],
+  );
+});
+```
+
+### Riverpod with `ProviderContainer`
+
+```dart
+test('usersProvider loads users from repository', () async {
+  final container = ProviderContainer(
+    overrides: [userRepositoryProvider.overrideWithValue(FakeUserRepository())],
+  );
+  addTearDown(container.dispose);
+
+  final result = await container.read(usersProvider.future);
+  expect(result, isNotEmpty);
+});
+```
+
+## Widget Tests
+
+```dart
+testWidgets('CartPage shows item count badge', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        cartNotifierProvider.overrideWith(() => FakeCartNotifier([testItem])),
+      ],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+  expect(find.byType(CartItemTile), findsOneWidget);
+});
+
+testWidgets('shows empty state when cart is empty', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier([]))],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('Your cart is empty'), findsOneWidget);
+});
+```
+
+## Fakes Over Mocks
+
+Prefer hand-written fakes for complex dependencies:
+
+```dart
+class FakeUserRepository implements UserRepository {
+  final _users = <String, User>{};
+  Object? fetchError;
+
+  @override
+  Future<User?> getById(String id) async {
+    if (fetchError != null) throw fetchError!;
+    return _users[id];
+  }
+
+  @override
+  Future<List<User>> getAll() async {
+    if (fetchError != null) throw fetchError!;
+    return _users.values.toList();
+  }
+
+  @override
+  Stream<List<User>> watchAll() => Stream.value(_users.values.toList());
+
+  @override
+  Future<void> save(User user) async {
+    _users[user.id] = user;
+  }
+
+  @override
+  Future<void> delete(String id) async {
+    _users.remove(id);
+  }
+
+  void addUser(User user) => _users[user.id] = user;
+}
+```
+
+## Async Testing
+
+```dart
+// Use fake_async for controlling timers and Futures
+test('debounce triggers after 300ms', () {
+  fakeAsync((async) {
+    final debouncer = Debouncer(delay: const Duration(milliseconds: 300));
+    var callCount = 0;
+    debouncer.run(() => callCount++);
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 1);
+  });
+});
+```
+
+## Golden Tests
+
+```dart
+testWidgets('UserCard golden test', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(home: UserCard(user: testUser)),
+  );
+
+  await expectLater(
+    find.byType(UserCard),
+    matchesGoldenFile('goldens/user_card.png'),
+  );
+});
+```
+
+Run `flutter test --update-goldens` when intentional visual changes are made.
+
+## Test Naming
+
+Use descriptive, behavior-focused names:
+
+```dart
+test('returns null when user does not exist', () { ... });
+test('throws NotFoundException when id is empty string', () { ... });
+testWidgets('disables submit button while form is invalid', (tester) async { ... });
+```
+
+## Test Organization
+
+```
+test/
+├── unit/
+│   ├── domain/
+│   │   └── usecases/
+│   └── data/
+│       └── repositories/
+├── widget/
+│   └── presentation/
+│       └── pages/
+└── golden/
+    └── widgets/
+
+integration_test/
+└── flows/
+    ├── login_flow_test.dart
+    └── checkout_flow_test.dart
+```
+
+## Coverage
+
+- Target 80%+ line coverage for business logic (domain + state managers)
+- All state transitions must have tests: loading → success, loading → error, retry
+- Run `flutter test --coverage` and inspect `lcov.info` with a coverage reporter
+- Coverage failures should block CI when below threshold

package/resources/ecc/rules/fsharp/coding-style.md

@@ -0,0 +1,112 @@
+---
+paths:
+  - "**/*.fs"
+  - "**/*.fsx"
+---
+# F# Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with F#-specific content.
+
+## Standards
+
+- Follow standard F# conventions and leverage the type system for correctness
+- Prefer immutability by default; use `mutable` only when justified by performance
+- Keep modules focused and cohesive
+
+## Types and Models
+
+- Prefer discriminated unions for domain modeling over class hierarchies
+- Use records for data with named fields
+- Use single-case unions for type-safe wrappers around primitives
+- Avoid classes unless interop or mutable state requires them
+
+```fsharp
+type EmailAddress = EmailAddress of string
+
+type OrderStatus =
+    | Pending
+    | Confirmed of confirmedAt: DateTimeOffset
+    | Shipped of trackingNumber: string
+    | Cancelled of reason: string
+
+type Order =
+    { Id: Guid
+      CustomerId: string
+      Status: OrderStatus
+      Items: OrderItem list }
+```
+
+## Immutability
+
+- Records are immutable by default; use `with` expressions for updates
+- Prefer `list`, `map`, `set` over mutable collections
+- Avoid `ref` cells and mutable fields in domain logic
+
+```fsharp
+let rename (profile: UserProfile) newName =
+    { profile with Name = newName }
+```
+
+## Function Style
+
+- Prefer small, composable functions over large methods
+- Use the pipe operator `|>` to build readable data pipelines
+- Prefer pattern matching over if/else chains
+- Use `Option` instead of null; use `Result` for operations that can fail
+
+```fsharp
+let processOrder order =
+    order
+    |> validateItems
+    |> Result.bind calculateTotal
+    |> Result.map applyDiscount
+    |> Result.mapError OrderError
+```
+
+## Async and Error Handling
+
+- Use `task { }` for interop with .NET async APIs
+- Use `async { }` for F#-native async workflows
+- Propagate `CancellationToken` through public async APIs
+- Prefer `Result` and railway-oriented programming over exceptions for expected failures
+
+```fsharp
+let loadOrderAsync (orderId: Guid) (ct: CancellationToken) =
+    task {
+        let! order = repository.FindAsync(orderId, ct)
+        return
+            order
+            |> Option.defaultWith (fun () ->
+                failwith $"Order {orderId} was not found.")
+    }
+```
+
+## Formatting
+
+- Use `fantomas` for automatic formatting
+- Prefer significant whitespace; avoid unnecessary parentheses
+- Remove unused `open` declarations
+
+### Open Declaration Order
+
+Group `open` statements into four sections separated by a blank line, each section sorted lexically within itself:
+
+1. `System.*`
+2. `Microsoft.*`
+3. Third-party namespaces
+4. First-party / project namespaces
+
+```fsharp
+open System
+open System.Collections.Generic
+open System.Threading.Tasks
+
+open Microsoft.AspNetCore.Http
+open Microsoft.Extensions.Logging
+
+open FsCheck.Xunit
+open Swensen.Unquote
+
+open MyApp.Domain
+open MyApp.Infrastructure
+```

package/resources/ecc/rules/fsharp/hooks.md

@@ -0,0 +1,26 @@
+---
+paths:
+  - "**/*.fs"
+  - "**/*.fsx"
+  - "**/*.fsproj"
+  - "**/*.sln"
+  - "**/*.slnx"
+  - "**/Directory.Build.props"
+  - "**/Directory.Build.targets"
+---
+# F# Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with F#-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **fantomas**: Auto-format edited F# files
+- **dotnet build**: Verify the solution or project still compiles after edits
+- **dotnet test --no-build**: Re-run the nearest relevant test project after behavior changes
+
+## Stop Hooks
+
+- Run a final `dotnet build` before ending a session with broad F# changes
+- Warn on modified `appsettings*.json` files so secrets do not get committed

package/resources/ecc/rules/fsharp/patterns.md

@@ -0,0 +1,111 @@
+---
+paths:
+  - "**/*.fs"
+  - "**/*.fsx"
+---
+# F# Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with F#-specific content.
+
+## Result Type for Error Handling
+
+Use `Result<'T, 'TError>` with railway-oriented programming instead of exceptions for expected failures.
+
+```fsharp
+type OrderError =
+    | InvalidCustomer of string
+    | EmptyItems
+    | ItemOutOfStock of sku: string
+
+let validateOrder (request: CreateOrderRequest) : Result<ValidatedOrder, OrderError> =
+    if String.IsNullOrWhiteSpace request.CustomerId then
+        Error(InvalidCustomer "CustomerId is required")
+    elif request.Items |> List.isEmpty then
+        Error EmptyItems
+    else
+        Ok { CustomerId = request.CustomerId; Items = request.Items }
+```
+
+## Option for Missing Values
+
+Prefer `Option<'T>` over null. Use `Option.map`, `Option.bind`, and `Option.defaultValue` to transform.
+
+```fsharp
+let findUser (id: Guid) : User option =
+    users |> Map.tryFind id
+
+let getUserEmail userId =
+    findUser userId
+    |> Option.map (fun u -> u.Email)
+    |> Option.defaultValue "unknown@example.com"
+```
+
+## Discriminated Unions for Domain Modeling
+
+Model business states explicitly. The compiler enforces exhaustive handling.
+
+```fsharp
+type PaymentState =
+    | AwaitingPayment of amount: decimal
+    | Paid of paidAt: DateTimeOffset * transactionId: string
+    | Refunded of refundedAt: DateTimeOffset * reason: string
+    | Failed of error: string
+
+let describePayment = function
+    | AwaitingPayment amount -> $"Awaiting payment of {amount:C}"
+    | Paid (at, txn) -> $"Paid at {at} (txn: {txn})"
+    | Refunded (at, reason) -> $"Refunded at {at}: {reason}"
+    | Failed error -> $"Payment failed: {error}"
+```
+
+## Computation Expressions
+
+Use computation expressions to simplify sequential operations that may fail.
+
+```fsharp
+let placeOrder request =
+    result {
+        let! validated = validateOrder request
+        let! inventory = checkInventory validated.Items
+        let! order = createOrder validated inventory
+        return order
+    }
+```
+
+## Module Organization
+
+- Group related functions in modules rather than classes
+- Use `[<RequireQualifiedAccess>]` to prevent name collisions
+- Keep modules small and focused on a single responsibility
+
+```fsharp
+[<RequireQualifiedAccess>]
+module Order =
+    let create customerId items = { Id = Guid.NewGuid(); CustomerId = customerId; Items = items; Status = Pending }
+    let confirm order = { order with Status = Confirmed(DateTimeOffset.UtcNow) }
+    let cancel reason order = { order with Status = Cancelled reason }
+```
+
+## Dependency Injection
+
+- Define dependencies as function parameters or record-of-functions
+- Use interfaces sparingly, primarily at the boundary with .NET libraries
+- Prefer partial application for injecting dependencies into pipelines
+
+```fsharp
+type OrderDeps =
+    { FindOrder: Guid -> Task<Order option>
+      SaveOrder: Order -> Task<unit>
+      SendNotification: Order -> Task<unit> }
+
+let processOrder (deps: OrderDeps) orderId =
+    task {
+        match! deps.FindOrder orderId with
+        | None -> return Error "Order not found"
+        | Some order ->
+            let confirmed = Order.confirm order
+            do! deps.SaveOrder confirmed
+            do! deps.SendNotification confirmed
+            return Ok confirmed
+    }
+```

package/resources/ecc/rules/fsharp/security.md

@@ -0,0 +1,76 @@
+---
+paths:
+  - "**/*.fs"
+  - "**/*.fsx"
+  - "**/*.fsproj"
+  - "**/appsettings*.json"
+---
+# F# Security
+
+> This file extends [common/security.md](../common/security.md) with F#-specific content.
+
+## Secret Management
+
+- Never hardcode API keys, tokens, or connection strings in source code
+- Use environment variables, user secrets for local development, and a secret manager in production
+- Keep `appsettings.*.json` free of real credentials
+
+```fsharp
+// BAD
+let apiKey = "sk-live-123"
+
+// GOOD
+let apiKey =
+    configuration["OpenAI:ApiKey"]
+    |> Option.ofObj
+    |> Option.defaultWith (fun () -> failwith "OpenAI:ApiKey is not configured.")
+```
+
+## SQL Injection Prevention
+
+- Always use parameterized queries with ADO.NET, Dapper, or EF Core
+- Never concatenate user input into SQL strings
+- Validate sort fields and filter operators before using dynamic query composition
+
+```fsharp
+let findByCustomer (connection: IDbConnection) customerId =
+    task {
+        let sql = "SELECT * FROM Orders WHERE CustomerId = @customerId"
+        return! connection.QueryAsync<Order>(sql, {| customerId = customerId |})
+    }
+```
+
+## Input Validation
+
+- Validate inputs at the application boundary using types
+- Use single-case discriminated unions for validated values
+- Reject invalid input before it enters domain logic
+
+```fsharp
+type ValidatedEmail = private ValidatedEmail of string
+
+module ValidatedEmail =
+    let create (input: string) =
+        if System.Text.RegularExpressions.Regex.IsMatch(input, @"^[^@]+@[^@]+\.[^@]+$") then
+            Ok(ValidatedEmail input)
+        else
+            Error "Invalid email address"
+
+    let value (ValidatedEmail v) = v
+```
+
+## Authentication and Authorization
+
+- Prefer framework auth handlers instead of custom token parsing
+- Enforce authorization policies at endpoint or handler boundaries
+- Never log raw tokens, passwords, or PII
+
+## Error Handling
+
+- Return safe client-facing messages
+- Log detailed exceptions with structured context server-side
+- Do not expose stack traces, SQL text, or filesystem paths in API responses
+
+## References
+
+See skill: `security-review` for broader application security review checklists.