@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/dart-pro/references/testing-and-mocking.md

@@ -0,0 +1,235 @@
+# Testing and Mocking
+
+## Test Structure
+
+```dart
+import 'package:test/test.dart';
+
+void main() {
+  group('OrderService', () {
+    late OrderService sut;
+    late MockOrderRepository mockRepo;
+
+    setUp(() {
+      mockRepo = MockOrderRepository();
+      sut = OrderService(repository: mockRepo);
+    });
+
+    test('getOrder returns order when exists', () async {
+      // Arrange
+      final expected = Order(id: 1, product: 'Widget');
+      when(() => mockRepo.findById(1)).thenAnswer((_) async => expected);
+
+      // Act
+      final result = await sut.getOrder(1);
+
+      // Assert
+      expect(result, equals(expected));
+      verify(() => mockRepo.findById(1)).called(1);
+    });
+
+    test('getOrder throws when not found', () {
+      when(() => mockRepo.findById(any())).thenAnswer((_) async => null);
+
+      expect(
+        () => sut.getOrder(999),
+        throwsA(isA<OrderNotFoundException>()),
+      );
+    });
+  });
+}
+```
+
+## Mocking with Mocktail
+
+```dart
+import 'package:mocktail/mocktail.dart';
+
+// Create mocks — no code generation needed
+class MockAuthService extends Mock implements AuthService {}
+class MockHttpClient extends Mock implements Client {}
+
+// Register fallback values for custom types
+void main() {
+  setUpAll(() {
+    registerFallbackValue(User(name: 'fallback', email: 'f@b.com'));
+    registerFallbackValue(Uri.parse('https://example.com'));
+  });
+
+  test('login calls API with credentials', () async {
+    final mockHttp = MockHttpClient();
+    final service = AuthService(client: mockHttp);
+
+    when(() => mockHttp.post(
+      any(),
+      body: any(named: 'body'),
+      headers: any(named: 'headers'),
+    )).thenAnswer((_) async => Response('{"token":"abc"}', 200));
+
+    final token = await service.login('user', 'pass');
+
+    expect(token, 'abc');
+    verify(() => mockHttp.post(
+      Uri.parse('https://api.example.com/login'),
+      body: '{"username":"user","password":"pass"}',
+      headers: any(named: 'headers'),
+    )).called(1);
+  });
+}
+```
+
+## Async Test Patterns
+
+```dart
+test('stream emits values in order', () async {
+  final controller = StreamController<int>();
+
+  // expectLater for async matchers
+  expectLater(
+    controller.stream,
+    emitsInOrder([1, 2, 3, emitsDone]),
+  );
+
+  controller
+    ..add(1)
+    ..add(2)
+    ..add(3)
+    ..close();
+});
+
+test('completes within timeout', () async {
+  final future = fetchData();
+  await expectLater(
+    future.timeout(const Duration(seconds: 5)),
+    completes,
+  );
+});
+
+// Fake async for timer-dependent code
+import 'package:fake_async/fake_async.dart';
+
+test('debounce fires after delay', () {
+  fakeAsync((async) {
+    var fired = false;
+    debounce(
+      duration: const Duration(milliseconds: 300),
+      callback: () => fired = true,
+    );
+
+    async.elapse(const Duration(milliseconds: 200));
+    expect(fired, isFalse); // not yet
+
+    async.elapse(const Duration(milliseconds: 150));
+    expect(fired, isTrue); // fired after 300ms total
+  });
+});
+```
+
+## Flutter Widget Testing
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+
+testWidgets('login button triggers auth flow', (tester) async {
+  final mockAuth = MockAuthService();
+  when(() => mockAuth.login(any(), any()))
+      .thenAnswer((_) async => AuthResult.success);
+
+  await tester.pumpWidget(
+    MaterialApp(
+      home: LoginScreen(authService: mockAuth),
+    ),
+  );
+
+  // Find and interact with widgets
+  await tester.enterText(find.byKey(const Key('email-field')), 'alice@test.com');
+  await tester.enterText(find.byKey(const Key('password-field')), 'secret');
+  await tester.tap(find.byKey(const Key('login-button')));
+  await tester.pumpAndSettle(); // wait for animations
+
+  // Verify navigation or state change
+  expect(find.text('Welcome, Alice'), findsOneWidget);
+  verify(() => mockAuth.login('alice@test.com', 'secret')).called(1);
+});
+
+testWidgets('shows error on failed login', (tester) async {
+  final mockAuth = MockAuthService();
+  when(() => mockAuth.login(any(), any()))
+      .thenThrow(AuthException('Invalid credentials'));
+
+  await tester.pumpWidget(
+    MaterialApp(home: LoginScreen(authService: mockAuth)),
+  );
+
+  await tester.tap(find.byKey(const Key('login-button')));
+  await tester.pumpAndSettle();
+
+  expect(find.text('Invalid credentials'), findsOneWidget);
+});
+```
+
+## Golden Tests
+
+```dart
+testWidgets('profile card matches golden', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(
+      home: Scaffold(
+        body: ProfileCard(
+          user: User(name: 'Alice', avatar: 'default.png'),
+        ),
+      ),
+    ),
+  );
+
+  await expectLater(
+    find.byType(ProfileCard),
+    matchesGoldenFile('goldens/profile_card.png'),
+  );
+});
+
+// Update goldens: flutter test --update-goldens
+// CI: flutter test (fails if pixels differ)
+```
+
+## Coverage-Driven CI
+
+```bash
+# Run with coverage
+dart test --coverage=coverage
+flutter test --coverage
+
+# Generate HTML report
+dart pub global activate coverage
+dart pub global run coverage:format_coverage \
+  --lcov --in=coverage --out=coverage/lcov.info \
+  --report-on=lib
+
+genhtml coverage/lcov.info -o coverage/html
+# Open coverage/html/index.html
+
+# CI enforcement — fail below threshold
+# In CI pipeline:
+# lcov --summary coverage/lcov.info | grep "lines" | awk -F'%' '{if ($1 < 80) exit 1}'
+```
+
+## Test Organization
+
+```
+test/
+├── unit/                    # Pure logic, fast, mocked dependencies
+│   ├── models/
+│   │   └── order_test.dart
+│   └── services/
+│       └── order_service_test.dart
+├── widget/                  # Flutter widget tests
+│   └── screens/
+│       └── login_screen_test.dart
+├── integration/             # Real dependencies, slower
+│   └── api/
+│       └── order_api_test.dart
+├── goldens/                 # Golden image files
+│   └── profile_card.png
+└── fixtures/                # Shared test data
+    └── sample_order.json
+```

package/workflows/powers/database-design/POWER.md

@@ -2,54 +2,68 @@
 ---
 inclusion: manual
 name: database-design
-description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
-allowed-tools: Read, Write, Edit, Glob, Grep
+description: "Use when designing schemas, relationships, indexes, ORM boundaries, and safe migration plans for relational or document-oriented workloads."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Database Design
 
-> **Learn to THINK, not copy SQL patterns.**
+## Purpose
 
-## 🎯 Selective Reading Rule
+Use when designing schemas, relationships, indexes, ORM boundaries, and safe migration plans for relational or document-oriented workloads.
 
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+## When to Use
 
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
-| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
-| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
-| `indexing.md` | Index types, composite indexes | Performance tuning |
-| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
-| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+- Designing or refactoring schemas, keys, and relationships.
+- Choosing relational vs document vs local-first structure.
+- Planning ORM and persistence boundaries.
+- Designing migrations and indexing strategy before rollout.
 
----
+## Instructions
 
-## ⚠️ Core Principle
+1. Model the workload and lifecycle constraints before choosing tables or collections.
+2. Define entities, ownership, keys, and read/write paths explicitly.
+3. Design indexes and pagination from real access patterns.
+4. Plan migrations, backfills, and rollback before implementation.
+5. Validate that the design lowers long-term change risk rather than hiding it.
 
-- ASK user for database preferences when unclear
-- Choose database/ORM based on CONTEXT
-- Don't default to PostgreSQL for everything
+### Baseline standards
 
----
+- Prefer schema decisions backed by access patterns.
+- Treat indexes as part of the model, not an afterthought.
+- Keep persistence models and transport models distinct when that lowers coupling.
+- Make migration safety explicit.
+- Choose normalization or denormalization deliberately.
 
-## Decision Checklist
+### Constraints
 
-Before designing schema:
+- Avoid modeling by ORM convenience alone.
+- Avoid deferring migration planning until after shipping.
+- Avoid adding indexes with no predicate or sort evidence.
+- Avoid using unstructured blobs to avoid real data modeling.
 
-- [ ] Asked user about database preference?
-- [ ] Chosen database for THIS context?
-- [ ] Considered deployment environment?
-- [ ] Planned index strategy?
-- [ ] Defined relationship types?
+## Output Format
 
----
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/schema-migration-checklist.md` | You need more explicit guidance for keys, indexes, pagination, ORM boundaries, backfills, and rollback-safe migration plans. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Anti-Patterns
+## Examples
 
-❌ Default to PostgreSQL for simple apps (SQLite may suffice)
-❌ Skip indexing
-❌ Use SELECT * in production
-❌ Store JSON when structured data is better
-❌ Ignore N+1 queries
+- "Help me with database design best practices in this project"
+- "Review my database design implementation for issues"
 ````

package/workflows/powers/database-design/SKILL.md

@@ -1,52 +1,66 @@
 ---
 name: database-design
-description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
-allowed-tools: Read, Write, Edit, Glob, Grep
+description: "Use when designing schemas, relationships, indexes, ORM boundaries, and safe migration plans for relational or document-oriented workloads."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Database Design
 
-> **Learn to THINK, not copy SQL patterns.**
+## Purpose
 
-## 🎯 Selective Reading Rule
+Use when designing schemas, relationships, indexes, ORM boundaries, and safe migration plans for relational or document-oriented workloads.
 
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+## When to Use
 
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
-| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
-| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
-| `indexing.md` | Index types, composite indexes | Performance tuning |
-| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
-| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+- Designing or refactoring schemas, keys, and relationships.
+- Choosing relational vs document vs local-first structure.
+- Planning ORM and persistence boundaries.
+- Designing migrations and indexing strategy before rollout.
 
----
+## Instructions
 
-## ⚠️ Core Principle
+1. Model the workload and lifecycle constraints before choosing tables or collections.
+2. Define entities, ownership, keys, and read/write paths explicitly.
+3. Design indexes and pagination from real access patterns.
+4. Plan migrations, backfills, and rollback before implementation.
+5. Validate that the design lowers long-term change risk rather than hiding it.
 
-- ASK user for database preferences when unclear
-- Choose database/ORM based on CONTEXT
-- Don't default to PostgreSQL for everything
+### Baseline standards
 
----
+- Prefer schema decisions backed by access patterns.
+- Treat indexes as part of the model, not an afterthought.
+- Keep persistence models and transport models distinct when that lowers coupling.
+- Make migration safety explicit.
+- Choose normalization or denormalization deliberately.
 
-## Decision Checklist
+### Constraints
 
-Before designing schema:
+- Avoid modeling by ORM convenience alone.
+- Avoid deferring migration planning until after shipping.
+- Avoid adding indexes with no predicate or sort evidence.
+- Avoid using unstructured blobs to avoid real data modeling.
 
-- [ ] Asked user about database preference?
-- [ ] Chosen database for THIS context?
-- [ ] Considered deployment environment?
-- [ ] Planned index strategy?
-- [ ] Defined relationship types?
+## Output Format
 
----
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/schema-migration-checklist.md` | You need more explicit guidance for keys, indexes, pagination, ORM boundaries, backfills, and rollback-safe migration plans. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Anti-Patterns
+## Examples
 
-❌ Default to PostgreSQL for simple apps (SQLite may suffice)
-❌ Skip indexing
-❌ Use SELECT * in production
-❌ Store JSON when structured data is better
-❌ Ignore N+1 queries
+- "Help me with database design best practices in this project"
+- "Review my database design implementation for issues"

package/workflows/powers/database-optimizer/POWER.md

@@ -1,90 +1,69 @@
 ````markdown
 ---
 inclusion: manual
-name: "database-optimizer"
-description: "Use for system-level database performance triage across engines: bottleneck analysis, indexing strategy, config tuning, partitioning, and lock contention."
+name: database-optimizer
+description: "Use for database performance triage across engines: query-plan analysis, indexing changes, wait and contention diagnosis, config tuning, and safe before/after validation."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-
 # Database Optimizer
 
-## Overview
-
-Senior database optimizer with expertise in performance tuning, query optimization, and scalability across multiple database systems.
-
-## Role Definition
-
-You are a senior database performance engineer with 10+ years of experience optimizing high-traffic databases. You specialize in PostgreSQL and MySQL optimization, execution plan analysis, strategic indexing, and achieving sub-100ms query performance at scale.
-
-## When to Use This Skill
+## Purpose
 
-- Analyzing slow queries and execution plans
-- Designing optimal index strategies
-- Tuning database configuration parameters
-- Optimizing schema design and partitioning
-- Reducing lock contention and deadlocks
-- Improving cache hit rates and memory usage
+Use for database performance triage across engines: query-plan analysis, indexing changes, wait and contention diagnosis, config tuning, and safe before/after validation.
 
-## Core Workflow
+## When to Use
 
-1. **Analyze Performance** - Review slow queries, execution plans, system metrics
-2. **Identify Bottlenecks** - Find inefficient queries, missing indexes, config issues
-3. **Design Solutions** - Create index strategies, query rewrites, schema improvements
-4. **Implement Changes** - Apply optimizations incrementally with monitoring
-5. **Validate Results** - Measure improvements, ensure stability, document changes
+- Investigating slow queries, bad plans, lock contention, or throughput collapse.
+- Choosing targeted indexing or query-shape fixes.
+- Deciding whether the bottleneck is query logic, schema, config, or concurrency.
+- Validating performance changes with before/after evidence.
 
-## Available Steering Files
+## Instructions
 
-Load detailed guidance on-demand:
+1. Establish the real symptom with timings, plans, waits, or metrics.
+2. Identify whether the bottleneck is query shape, indexing, contention, config, or workload pattern.
+3. Choose the smallest safe optimization with explicit tradeoffs.
+4. Apply one high-signal change at a time when isolating a root cause.
+5. Re-measure and report whether the change actually improved the bottleneck.
 
-| Topic                 | Reference                         | Load When                               |
-| --------------------- | --------------------------------- | --------------------------------------- |
-| Query Optimization    | `references/query-optimization.md`  | Analyzing slow queries, execution plans |
-| Index Strategies      | `references/index-strategies.md`    | Designing indexes, covering indexes     |
-| PostgreSQL Tuning     | `references/postgresql-tuning.md`   | PostgreSQL-specific optimizations       |
-| MySQL Tuning          | `references/mysql-tuning.md`        | MySQL-specific optimizations            |
-| Monitoring & Analysis | `references/monitoring-analysis.md` | Performance metrics, diagnostics        |
+### Baseline standards
 
-## Constraints
+- Explain before optimizing.
+- Measure before and after every proposed change.
+- Account for write amplification and operational cost of indexes.
+- Include rollback and monitoring in the optimization plan.
+- Prefer correctness and predictable operations over benchmark vanity.
 
-### MUST DO
+### Constraints
 
-- Analyze EXPLAIN plans before optimizing
-- Measure performance before and after changes
-- Create indexes strategically (avoid over-indexing)
-- Test changes in non-production first
-- Document all optimization decisions
-- Monitor impact on write performance
-- Consider replication lag for distributed systems
+- Avoid blind config churn.
+- Avoid index additions without real predicate evidence.
+- Avoid query rewrites that ignore semantics or maintenance cost.
+- Avoid treating every slowdown as a single-query problem.
 
-### MUST NOT DO
+## Output Format
 
-- Apply optimizations without measurement
-- Create redundant or unused indexes
-- Skip execution plan analysis
-- Ignore write performance impact
-- Make multiple changes simultaneously
-- Optimize without understanding query patterns
-- Neglect statistics updates (ANALYZE/VACUUM)
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-## Output Templates
+## References
 
-When optimizing database performance, provide:
+Load on demand. Do not preload all reference files.
 
-1. Performance analysis with baseline metrics
-2. Identified bottlenecks and root causes
-3. Optimization strategy with specific changes
-4. Implementation SQL/config changes
-5. Validation queries to measure improvement
-6. Monitoring recommendations
+| File | Load when |
+| --- | --- |
+| `references/query-triage-checklist.md` | You need a deeper performance triage checklist for plans, waits, index tradeoffs, rollback, and before/after evidence. |
 
-## Knowledge Reference
+## Scripts
 
-PostgreSQL (pg_stat_statements, EXPLAIN ANALYZE, indexes, VACUUM, partitioning), MySQL (slow query log, EXPLAIN, InnoDB, query cache), query optimization, index design, execution plans, configuration tuning, replication, sharding, caching strategies
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Related Powers
+## Examples
 
-- **Backend Developer** - Query pattern optimization
-- **DevOps Engineer** - Infrastructure and resource tuning
-- **Data Engineer** - ETL and analytical query optimization
+- "Help me with database optimizer best practices in this project"
+- "Review my database optimizer implementation for issues"
 ````