@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/flutter-feature/references/testing-patterns.md

@@ -0,0 +1,218 @@
+# Testing Patterns Reference
+
+## Layer 1: Repository Test (in-memory Drift + mocktail)
+```dart
+void main() {
+  late AppDatabase db;
+  late Mock<N>Api mockApi;
+  late MockOutboxService mockOutbox;
+  late MockConnectivityService mockConnectivity;
+  late <N>Repository sut;
+
+  setUp(() {
+    db = AppDatabase(NativeDatabase.memory());
+    mockApi = Mock<N>Api();
+    mockOutbox = MockOutboxService();
+    mockConnectivity = MockConnectivityService();
+    when(() => mockConnectivity.isOnline).thenAnswer((_) async => false);
+    sut = <N>Repository(
+      dao: <N>Dao(db),
+      api: mockApi,
+      outbox: mockOutbox,
+      connectivity: mockConnectivity,
+    );
+  });
+
+  tearDown(() => db.close());
+
+  group('create', () {
+    test('writes to local DB immediately', () async {
+      await sut.create(fake<N>Input());
+      final items = await db.<n>Dao.getAll();
+      expect(items.length, 1);
+    });
+
+    test('enqueues in outbox with operationId', () async {
+      await sut.create(fake<N>Input());
+      verify(() => mockOutbox.enqueue(
+        operationId: any(named: 'operationId'),
+        feature: '<n>',
+        operation: 'create',
+        payload: any(named: 'payload'),
+      )).called(1);
+    });
+
+    test('does NOT call API directly', () async {
+      await sut.create(fake<N>Input());
+      verifyNever(() => mockApi.create(any()));
+    });
+  });
+
+  group('syncFromRemote', () {
+    test('upserts all remote records into local DB', () async {
+      when(() => mockApi.getAll()).thenAnswer((_) async => [fake<N>Dto()]);
+      await sut.syncFromRemote();
+      final items = await db.<n>Dao.getAll();
+      expect(items.length, 1);
+    });
+  });
+}
+```
+
+## Layer 2: Service Test (pure Dart — no Flutter, no Riverpod)
+```dart
+void main() {
+  late <N>Service sut;
+  late Mock<N>Repository mockRepo;
+
+  setUp(() {
+    mockRepo = Mock<N>Repository();
+    sut = <N>Service(repository: mockRepo, /* other deps */);
+  });
+
+  group('<operation>', () {
+    test('returns Left when <failure condition>', () async {
+      // Arrange: set up conditions that trigger failure
+      final result = await sut.<operation>(/* bad input */);
+      expect(result.isLeft(), true);
+      result.fold(
+        (err) => expect(err, isA<ClientError>()),
+        (_) => fail('should have been Left'),
+      );
+    });
+
+    test('returns Right on success', () async {
+      when(() => mockRepo.<action>(any())).thenAnswer((_) async => fake<N>());
+      final result = await sut.<operation>(/* valid input */);
+      expect(result.isRight(), true);
+    });
+  });
+}
+```
+
+## Layer 3: Notifier Test (ProviderContainer)
+```dart
+void main() {
+  late ProviderContainer container;
+
+  ProviderContainer makeContainer({List<Override> overrides = const []}) =>
+    ProviderContainer(overrides: [
+      <n>RepositoryProvider.overrideWith((_) => Fake<N>Repository()),
+      ...overrides,
+    ]);
+
+  tearDown(() => container.dispose());
+
+  test('initial state is AppState.loading()', () {
+    container = makeContainer();
+    expect(container.read(<n>NotifierProvider), const AppState.loading());
+  });
+
+  test('transitions to AppState.data when items exist', () async {
+    container = makeContainer();
+    await container.pump(); // allow stream to emit
+    expect(container.read(<n>NotifierProvider), isA<_Data>());
+  });
+
+  test('transitions to AppState.empty when no items', () async {
+    container = makeContainer(overrides: [
+      <n>RepositoryProvider.overrideWith((_) => Empty<N>Repository()),
+    ]);
+    await container.pump();
+    expect(container.read(<n>NotifierProvider), const AppState.empty());
+  });
+
+  test('error state contains non-empty requestId', () async {
+    container = makeContainer(overrides: [
+      <n>RepositoryProvider.overrideWith((_) => Failing<N>Repository()),
+    ]);
+    await container.pump();
+    final state = container.read(<n>NotifierProvider);
+    expect(state, isA<_Error>());
+    expect((state as _Error).error.requestId, isNotEmpty);
+  });
+}
+```
+
+## Layer 4: Widget Test (all 5 AppState variants)
+```dart
+void main() {
+  Widget buildSubject(AppState<List<<N>>> state) =>
+    ProviderScope(
+      overrides: [
+        <n>NotifierProvider.overrideWith((_) => FixedState<N>Notifier(state)),
+      ],
+      child: const MaterialApp(home: <N>ListPage()),
+    );
+
+  testWidgets('shows LoadingView in loading state', (tester) async {
+    await tester.pumpWidget(buildSubject(const AppState.loading()));
+    expect(find.byType(LoadingView), findsOneWidget);
+  });
+
+  testWidgets('shows EmptyView in empty state', (tester) async {
+    await tester.pumpWidget(buildSubject(const AppState.empty()));
+    expect(find.byType(EmptyView), findsOneWidget);
+  });
+
+  testWidgets('shows data in data state', (tester) async {
+    await tester.pumpWidget(buildSubject(AppState.data([fake<N>()])));
+    expect(find.byType(<N>Card), findsOneWidget);
+  });
+
+  testWidgets('shows ErrorView with selectable requestId', (tester) async {
+    final err = AppError.network(requestId: 'test-req-id', userMessage: 'Oops');
+    await tester.pumpWidget(buildSubject(AppState.error(err)));
+    expect(find.byType(ErrorView), findsOneWidget);
+    expect(find.textContaining('test-req-id'), findsOneWidget);
+  });
+
+  testWidgets('shows DeadLetterView with retry button', (tester) async {
+    final err = AppError.syncDead(requestId: 'dlq-id', feature: '<n>',
+      operation: 'create', userMessage: 'Failed', errorLog: []);
+    await tester.pumpWidget(buildSubject(
+      AppState.deadLetter(error: err, requestId: 'dlq-id'),
+    ));
+    expect(find.byType(DeadLetterView), findsOneWidget);
+    expect(find.text('Retry'), findsOneWidget);
+  });
+}
+```
+
+## Layer 5: Golden Test (shared widgets)
+```dart
+void main() {
+  testGoldens('ErrorView renders correctly', (tester) async {
+    await loadAppFonts();
+    await tester.pumpWidgetBuilder(
+      ErrorView(
+        error: AppError.network(requestId: 'abc-123', userMessage: 'No connection'),
+        onRetry: () {},
+      ),
+      surfaceSize: const Size(400, 300),
+    );
+    await screenMatchesGolden(tester, 'error_view');
+  });
+}
+```
+
+## Fake Repository Helpers
+```dart
+// Always create typed fakes — never use mocks for repositories in widget tests
+class Fake<N>Repository implements <N>Repository {
+  final List<<N>> items;
+  Fake<N>Repository({this.items = const []});
+
+  @override Stream<List<<N>>> watchAll() => Stream.value(items);
+  @override Future<bool> isEmpty() async => items.isEmpty;
+  @override Future<<N>> create(Create<N>Input input) async => fake<N>();
+  @override Future<void> syncFromRemote() async {}
+}
+
+class Failing<N>Repository implements <N>Repository {
+  @override Stream<List<<N>>> watchAll() => Stream.error(
+    Exception('DB error'), StackTrace.empty,
+  );
+  // ... other methods throw
+}
+```

package/workflows/powers/flutter-go-router/POWER.md

@@ -0,0 +1,64 @@
+````markdown
+---
+inclusion: manual
+name: flutter-go-router
+description: "Use when adding or refactoring typed GoRouter navigation, guards, shell routes, deep links, or notification-driven routing in Flutter. Do not use for state management or feature business logic."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter GoRouter
+
+## Purpose
+
+Guide typed Flutter navigation architecture with safe redirects, deep-link
+handling, and predictable shell-route behavior.
+
+## When to Use
+
+- Adding a route or nested route
+- Introducing auth or init guards
+- Adding a bottom-nav shell
+- Handling deep links or FCM notification taps
+- Fixing redirect loops or back-stack issues
+
+## Instructions
+
+1. Define the route map and parameter shape first.
+2. Choose the right route type for the navigation behavior.
+3. Use typed route classes instead of raw string paths in widgets.
+4. Keep `redirect` and `onEnter` pure, fast, and loop-safe.
+5. Validate deep-link inputs before building pages.
+6. Preserve branch stacks intentionally when using shell navigation.
+7. Add tests for guards, deep links, and shell-route behavior where the flow is non-trivial.
+
+## Output Format
+
+Produce navigation guidance or code that:
+
+- uses typed routes intentionally,
+- explains guard and deep-link decisions,
+- identifies shell-route versus standard-route boundaries,
+- includes edge cases for invalid params or redirect loops.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/typed-routes.md` | Defining route files, params, query handling, or typed route usage patterns. |
+| `references/guards-and-deeplinks.md` | Adding auth guards, splash/init gates, notification routing, or shell-route preservation. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add a typed detail route and deep-link handling for products."
+- "Set up a stateful shell route for Flutter bottom navigation."
+````

package/workflows/powers/flutter-go-router/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: flutter-go-router
+description: "Use when adding or refactoring typed GoRouter navigation, guards, shell routes, deep links, or notification-driven routing in Flutter. Do not use for state management or feature business logic."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter GoRouter
+
+## Purpose
+
+Guide typed Flutter navigation architecture with safe redirects, deep-link
+handling, and predictable shell-route behavior.
+
+## When to Use
+
+- Adding a route or nested route
+- Introducing auth or init guards
+- Adding a bottom-nav shell
+- Handling deep links or FCM notification taps
+- Fixing redirect loops or back-stack issues
+
+## Instructions
+
+1. Define the route map and parameter shape first.
+2. Choose the right route type for the navigation behavior.
+3. Use typed route classes instead of raw string paths in widgets.
+4. Keep `redirect` and `onEnter` pure, fast, and loop-safe.
+5. Validate deep-link inputs before building pages.
+6. Preserve branch stacks intentionally when using shell navigation.
+7. Add tests for guards, deep links, and shell-route behavior where the flow is non-trivial.
+
+## Output Format
+
+Produce navigation guidance or code that:
+
+- uses typed routes intentionally,
+- explains guard and deep-link decisions,
+- identifies shell-route versus standard-route boundaries,
+- includes edge cases for invalid params or redirect loops.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/typed-routes.md` | Defining route files, params, query handling, or typed route usage patterns. |
+| `references/guards-and-deeplinks.md` | Adding auth guards, splash/init gates, notification routing, or shell-route preservation. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add a typed detail route and deep-link handling for products."
+- "Set up a stateful shell route for Flutter bottom navigation."

package/workflows/powers/flutter-go-router/references/guards-and-deeplinks.md

@@ -0,0 +1,20 @@
+# Guards and Deep Links
+
+## Guard Rules
+
+- Redirect functions stay pure and deterministic.
+- Check the current matched location before redirecting to avoid loops.
+- Preserve user intent with a `from` query when redirecting to auth.
+- Keep init/auth guards separate when they represent different state machines.
+
+## Deep-Link Rules
+
+- Validate required IDs and query params before building the page.
+- Route invalid or incomplete links to a safe fallback or error screen.
+- Keep notification payload parsing outside widgets when possible.
+
+## Shell Navigation
+
+- Use stateful shell navigation when each tab needs its own stack.
+- Give each branch its own navigator key.
+- Test back navigation and tab switching explicitly.

package/workflows/powers/flutter-go-router/references/typed-routes.md

@@ -0,0 +1,27 @@
+# Typed Routes
+
+## Route File Layout
+
+Prefer a dedicated routing area such as:
+
+- `lib/core/routing/app_router.dart`
+- `lib/core/routing/routes/<feature>_route.dart`
+
+## Route Type Choice
+
+- `GoRouteData` for normal screen routes
+- `ShellRouteData` for shared wrappers with one navigator
+- stateful shell route for persistent tabs with independent stacks
+
+## Parameter Rules
+
+- Required path params for canonical resource identity
+- Optional query params for filters, search, and non-identity state
+- Use `extra` sparingly and avoid relying on it for deep-linkable flows
+
+## Widget Usage
+
+- `ProductListRoute().go(context)`
+- `ProductDetailRoute(id: id).push(context)`
+
+Do not call `context.go('/products')` from widgets when typed routes exist.

package/workflows/powers/flutter-offline-sync/POWER.md

@@ -0,0 +1,62 @@
+````markdown
+---
+inclusion: manual
+name: flutter-offline-sync
+description: "Use when implementing or auditing offline-first sync in Flutter with a local database, outbox queue, retry policy, conflict handling, and dead-letter behavior. Do not use for simple online-only CRUD."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Offline Sync
+
+## Purpose
+
+Guide local-first write flows that reconcile with the server later through an
+outbox queue, retry policy, and explicit conflict handling.
+
+## When to Use
+
+- Adding offline-first writes to a feature
+- Designing or auditing outbox behavior
+- Handling retry, dead-letter, or conflict states
+- Wiring connectivity-driven background draining
+
+## Instructions
+
+1. Identify the feature and write operations that need offline behavior.
+2. Choose a conflict strategy per feature.
+3. Ensure the outbox infrastructure exists once per project.
+4. Persist locally first, then enqueue sync work.
+5. Never block UI completion on network success.
+6. Surface sync status and dead-letter behavior clearly in the UI.
+7. Keep retry policy bounded and explicit.
+
+## Output Format
+
+Produce offline-sync guidance or code that:
+
+- shows the local-write then outbox-enqueue contract,
+- names the retry, dead-letter, and conflict decisions,
+- separates one-time infrastructure from per-feature integration,
+- includes sync-status UI expectations when relevant.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/outbox-full.md` | Setting up the outbox table or service, connectivity listeners, feature handlers, retry logic, or dead-letter UI. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add offline-first create and update support to this Flutter repository."
+- "Review this outbox flow for retry and dead-letter mistakes."
+````

package/workflows/powers/flutter-offline-sync/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: flutter-offline-sync
+description: "Use when implementing or auditing offline-first sync in Flutter with a local database, outbox queue, retry policy, conflict handling, and dead-letter behavior. Do not use for simple online-only CRUD."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Offline Sync
+
+## Purpose
+
+Guide local-first write flows that reconcile with the server later through an
+outbox queue, retry policy, and explicit conflict handling.
+
+## When to Use
+
+- Adding offline-first writes to a feature
+- Designing or auditing outbox behavior
+- Handling retry, dead-letter, or conflict states
+- Wiring connectivity-driven background draining
+
+## Instructions
+
+1. Identify the feature and write operations that need offline behavior.
+2. Choose a conflict strategy per feature.
+3. Ensure the outbox infrastructure exists once per project.
+4. Persist locally first, then enqueue sync work.
+5. Never block UI completion on network success.
+6. Surface sync status and dead-letter behavior clearly in the UI.
+7. Keep retry policy bounded and explicit.
+
+## Output Format
+
+Produce offline-sync guidance or code that:
+
+- shows the local-write then outbox-enqueue contract,
+- names the retry, dead-letter, and conflict decisions,
+- separates one-time infrastructure from per-feature integration,
+- includes sync-status UI expectations when relevant.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/outbox-full.md` | Setting up the outbox table or service, connectivity listeners, feature handlers, retry logic, or dead-letter UI. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add offline-first create and update support to this Flutter repository."
+- "Review this outbox flow for retry and dead-letter mistakes."

package/workflows/powers/flutter-offline-sync/references/outbox-full.md

@@ -0,0 +1,44 @@
+# Outbox Full
+
+## One-Time Infrastructure
+
+- Outbox table persisted in Drift
+- Outbox service responsible for dequeue, dispatch, retry, and dead-letter transitions
+- Connectivity service that triggers draining when the device comes back online
+- Optional app-init seeding for empty local stores
+
+## Repository Write Contract
+
+1. Generate an operation ID.
+2. Persist the local change.
+3. Enqueue the serialized operation.
+4. Trigger a non-blocking drain when online.
+5. Return the local result immediately.
+
+## Feature Handler Contract
+
+Each queued feature operation needs a handler that:
+
+- decodes the payload,
+- calls the correct API operation,
+- marks success or updates retry/dead-letter state,
+- applies conflict policy when the server rejects the write semantically.
+
+## Sync Status Contract
+
+Offline-capable records should expose a sync field such as:
+
+- `pendingSync`
+- `synced`
+- `failed`
+- `dead`
+- `conflict`
+
+## Conflict Strategies
+
+- `clientWins`
+- `serverWins`
+- `lastWriteWins`
+- `manualResolve`
+
+Pick one per feature. Safety-critical data should not default to silent overwrite.

package/workflows/powers/flutter-repository/POWER.md

@@ -0,0 +1,64 @@
+````markdown
+---
+inclusion: manual
+name: flutter-repository
+description: "Use when building or refactoring a Flutter feature data layer: Drift tables and DAOs, DTOs, mappers, Retrofit APIs, and repository orchestration. Do not use when the task needs a full feature scaffold across presentation and routing."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Repository
+
+## Purpose
+
+Generate or review one Flutter feature's data layer while keeping persistence,
+transport, mapping, and orchestration properly separated.
+
+## When to Use
+
+- Adding a new repository
+- Adding local tables or DAOs
+- Adding DTOs and network API interfaces
+- Wiring local-first read/write behavior
+- Updating sync logic in an existing repository
+
+## Instructions
+
+1. Define the local table and DAO contract first.
+2. Define DTOs and the remote API interface separately.
+3. Keep mapping logic outside large repository methods where possible.
+4. Let repositories own local and remote coordination.
+5. Keep DAOs persistence-focused and DTOs transport-focused.
+6. If offline sync exists, persist locally and enqueue sync work instead of blocking on the network.
+7. Add tests for local-first reads, writes, and sync behavior.
+
+## Output Format
+
+Produce repository-layer guidance or code that:
+
+- separates table, DAO, DTO, mapper, API, and repository responsibilities,
+- explains any offline-sync behavior,
+- identifies test points for read, write, and sync flows,
+- avoids collapsing the whole data layer into a single file.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/drift-patterns.md` | Designing local tables, DAO helpers, sync-status fields, or Drift-side read and write helpers. |
+| `references/retrofit-patterns.md` | Designing DTOs, Retrofit interfaces, mapper boundaries, or repository orchestration. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Create the Flutter repository layer for a new offline-capable entity."
+- "Refactor this feature repository so DAO, DTO, and mapping logic are separated."
+````

package/workflows/powers/flutter-repository/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: flutter-repository
+description: "Use when building or refactoring a Flutter feature data layer: Drift tables and DAOs, DTOs, mappers, Retrofit APIs, and repository orchestration. Do not use when the task needs a full feature scaffold across presentation and routing."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Repository
+
+## Purpose
+
+Generate or review one Flutter feature's data layer while keeping persistence,
+transport, mapping, and orchestration properly separated.
+
+## When to Use
+
+- Adding a new repository
+- Adding local tables or DAOs
+- Adding DTOs and network API interfaces
+- Wiring local-first read/write behavior
+- Updating sync logic in an existing repository
+
+## Instructions
+
+1. Define the local table and DAO contract first.
+2. Define DTOs and the remote API interface separately.
+3. Keep mapping logic outside large repository methods where possible.
+4. Let repositories own local and remote coordination.
+5. Keep DAOs persistence-focused and DTOs transport-focused.
+6. If offline sync exists, persist locally and enqueue sync work instead of blocking on the network.
+7. Add tests for local-first reads, writes, and sync behavior.
+
+## Output Format
+
+Produce repository-layer guidance or code that:
+
+- separates table, DAO, DTO, mapper, API, and repository responsibilities,
+- explains any offline-sync behavior,
+- identifies test points for read, write, and sync flows,
+- avoids collapsing the whole data layer into a single file.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/drift-patterns.md` | Designing local tables, DAO helpers, sync-status fields, or Drift-side read and write helpers. |
+| `references/retrofit-patterns.md` | Designing DTOs, Retrofit interfaces, mapper boundaries, or repository orchestration. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Create the Flutter repository layer for a new offline-capable entity."
+- "Refactor this feature repository so DAO, DTO, and mapping logic are separated."