@cubis/foundry 0.3.70 → 0.3.72

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

@@ -0,0 +1,65 @@
+````markdown
+---
+inclusion: manual
+name: flutter-drift
+description: "Use when implementing or refactoring Flutter local persistence with Drift: tables, DAOs, typed queries, indexes, transactions, and migrations. Do not use for simple key-value storage or remote-only networking work."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Drift
+
+## Purpose
+
+Guide project-local SQLite persistence through Drift while keeping persistence
+details in the data layer and repositories above the DAO boundary.
+
+## When to Use
+
+- Adding a new table or DAO
+- Changing schema or indexes
+- Writing a migration
+- Adding typed multi-table queries
+- Wiring repositories to local persistence
+
+## Instructions
+
+1. Define or update the table schema first.
+2. Add indexes only for real filter, join, or sort paths.
+3. Keep DAOs typed and persistence-focused.
+4. Expose Drift through repositories instead of letting UI code call DAOs directly.
+5. Use transactions for multi-table consistency.
+6. Use explicit schema version bumps and migration steps for every persisted change.
+7. Never drop or rewrite user data silently.
+8. Test migration behavior from at least the previous production schema.
+
+## Output Format
+
+Produce Drift guidance or code that:
+
+- keeps one app database entrypoint,
+- uses typed DAOs and query helpers,
+- explains index or migration choices when they matter,
+- includes migration-test expectations for schema changes.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/migrations.md` | Changing schema version, adding columns or tables, or planning upgrade safety. |
+| `references/query-patterns.md` | Designing tables, indexes, DAOs, joins, transactions, or repository integration. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add a Drift table and DAO for offline product notes."
+- "Plan a safe migration for a new required column in this Flutter database."
+````

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

@@ -0,0 +1,62 @@
+---
+name: flutter-drift
+description: "Use when implementing or refactoring Flutter local persistence with Drift: tables, DAOs, typed queries, indexes, transactions, and migrations. Do not use for simple key-value storage or remote-only networking work."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Drift
+
+## Purpose
+
+Guide project-local SQLite persistence through Drift while keeping persistence
+details in the data layer and repositories above the DAO boundary.
+
+## When to Use
+
+- Adding a new table or DAO
+- Changing schema or indexes
+- Writing a migration
+- Adding typed multi-table queries
+- Wiring repositories to local persistence
+
+## Instructions
+
+1. Define or update the table schema first.
+2. Add indexes only for real filter, join, or sort paths.
+3. Keep DAOs typed and persistence-focused.
+4. Expose Drift through repositories instead of letting UI code call DAOs directly.
+5. Use transactions for multi-table consistency.
+6. Use explicit schema version bumps and migration steps for every persisted change.
+7. Never drop or rewrite user data silently.
+8. Test migration behavior from at least the previous production schema.
+
+## Output Format
+
+Produce Drift guidance or code that:
+
+- keeps one app database entrypoint,
+- uses typed DAOs and query helpers,
+- explains index or migration choices when they matter,
+- includes migration-test expectations for schema changes.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/migrations.md` | Changing schema version, adding columns or tables, or planning upgrade safety. |
+| `references/query-patterns.md` | Designing tables, indexes, DAOs, joins, transactions, or repository integration. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add a Drift table and DAO for offline product notes."
+- "Plan a safe migration for a new required column in this Flutter database."

package/workflows/powers/flutter-drift/references/migrations.md

@@ -0,0 +1,22 @@
+# Migrations
+
+## Migration Rules
+
+- Increment `schemaVersion` every time persisted structure changes.
+- Use `onCreate` for first-install setup only.
+- Use `onUpgrade` for stepwise migrations from older versions.
+- Backfill new required columns safely with defaults or staged rollout.
+- Enable pragmas such as foreign keys intentionally in `beforeOpen`.
+
+## Safe Upgrade Checklist
+
+- Existing rows stay readable after upgrade.
+- New nullable columns start nullable unless a safe default exists.
+- New indexes are created during migration or through `createAll` only when safe.
+- Data transforms are deterministic and reversible enough for debugging.
+
+## Tests
+
+- Test opening a fresh database.
+- Test upgrading from the last production schema.
+- Test representative old data through the upgrade path.

package/workflows/powers/flutter-drift/references/query-patterns.md

@@ -0,0 +1,26 @@
+# Query Patterns
+
+## Table Design
+
+- Use stable IDs with clear ownership rules.
+- Add indexes for foreign keys, frequent filters, and common sort columns.
+- Keep sync-related columns explicit when offline behavior exists.
+
+## DAO Design
+
+- Expose streams for UI-facing reactive reads.
+- Expose one-shot reads for detail fetches or background work.
+- Keep write methods small and composable.
+- Return typed data or typed companions, not maps.
+
+## Repository Integration
+
+- Read flow: local-first, then optional remote refresh.
+- Write flow: persist locally first, then reconcile sync policy.
+- Mapper code belongs in the data layer, not in widgets.
+
+## Use Raw SQL Only When
+
+- a partial index or special SQLite feature needs it,
+- a complex query is materially clearer in SQL,
+- Drift's typed API cannot express the operation cleanly.

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

@@ -0,0 +1,65 @@
+````markdown
+---
+inclusion: manual
+name: flutter-feature
+description: "Use when scaffolding a full Flutter feature across data, domain, presentation, routing, offline sync, and tests. Do not use for isolated single-layer work when a narrower Flutter skill already fits."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Feature Scaffold
+
+## Purpose
+
+Generate a complete, architecture-compliant Flutter feature instead of shipping
+partial stubs across disconnected layers.
+
+## When to Use
+
+- Adding a new feature with UI, state, data, and tests
+- Scaffolding a feature that spans multiple layers
+- Defining a feature that needs routing or offline support
+- Generating a consistent feature folder structure
+
+## Instructions
+
+1. Clarify or infer the feature name, data fields, operations, cross-feature dependencies, business-logic needs, and offline conflict strategy.
+2. Stop and resolve missing requirements before generating files.
+3. Keep naming and folder structure consistent across data, domain, presentation, routing, and tests.
+4. Add a domain service only when business rules justify it.
+5. Add composite providers only when a screen composes multiple features.
+6. Keep repository, service, notifier, and widget responsibilities separate.
+7. Ship tests with the feature instead of leaving verification for later.
+
+## Output Format
+
+Produce feature scaffolding guidance or code that:
+
+- names the expected files and layer ownership,
+- calls out optional pieces such as domain services or composite providers,
+- keeps offline writes on the outbox path when needed,
+- includes the test surface that should ship with the feature.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/architecture-rules.md` | Checking layer boundaries, naming, app-state rules, and design-system constraints. |
+| `references/composite-provider.md` | A screen depends on multiple features and needs provider-layer composition. |
+| `references/testing-patterns.md` | Generating repository, service, notifier, or widget tests. |
+| `references/outbox-pattern.md` | The feature writes offline, syncs later, or needs conflict or dead-letter behavior. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Scaffold a Flutter inventory feature with offline edits and tests."
+- "Generate the full feature structure for a new sales module."
+````

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

@@ -0,0 +1,62 @@
+---
+name: flutter-feature
+description: "Use when scaffolding a full Flutter feature across data, domain, presentation, routing, offline sync, and tests. Do not use for isolated single-layer work when a narrower Flutter skill already fits."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Feature Scaffold
+
+## Purpose
+
+Generate a complete, architecture-compliant Flutter feature instead of shipping
+partial stubs across disconnected layers.
+
+## When to Use
+
+- Adding a new feature with UI, state, data, and tests
+- Scaffolding a feature that spans multiple layers
+- Defining a feature that needs routing or offline support
+- Generating a consistent feature folder structure
+
+## Instructions
+
+1. Clarify or infer the feature name, data fields, operations, cross-feature dependencies, business-logic needs, and offline conflict strategy.
+2. Stop and resolve missing requirements before generating files.
+3. Keep naming and folder structure consistent across data, domain, presentation, routing, and tests.
+4. Add a domain service only when business rules justify it.
+5. Add composite providers only when a screen composes multiple features.
+6. Keep repository, service, notifier, and widget responsibilities separate.
+7. Ship tests with the feature instead of leaving verification for later.
+
+## Output Format
+
+Produce feature scaffolding guidance or code that:
+
+- names the expected files and layer ownership,
+- calls out optional pieces such as domain services or composite providers,
+- keeps offline writes on the outbox path when needed,
+- includes the test surface that should ship with the feature.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/architecture-rules.md` | Checking layer boundaries, naming, app-state rules, and design-system constraints. |
+| `references/composite-provider.md` | A screen depends on multiple features and needs provider-layer composition. |
+| `references/testing-patterns.md` | Generating repository, service, notifier, or widget tests. |
+| `references/outbox-pattern.md` | The feature writes offline, syncs later, or needs conflict or dead-letter behavior. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Scaffold a Flutter inventory feature with offline edits and tests."
+- "Generate the full feature structure for a new sales module."

package/workflows/powers/flutter-feature/references/architecture-rules.md

@@ -0,0 +1,85 @@
+# Architecture Rules Reference
+
+## Layer Boundaries (NEVER cross these)
+- Repository knows: Drift DAO + Retrofit API + OutboxService. Nothing else.
+- Service knows: repositories and other services. Zero Flutter, zero Riverpod.
+- Notifier knows: providers, services. Calls service/repo. Updates AppState.
+- Widget knows: notifier. Renders AppState. Calls notifier methods.
+- Cross-feature data: compose at the Riverpod provider layer ONLY (never repo→repo imports).
+
+## File Rules
+- One public class per file. Filename = class name in snake_case.
+- Private helpers used only by that class may colocate.
+- Extension methods on the class may colocate.
+- If a helper is used by 2+ classes → give it its own file.
+
+## Naming
+- Files: `<feature>_<suffix>.dart` (e.g. `product_repository.dart`)
+- Classes: `<Feature><Suffix>` (e.g. `ProductRepository`)
+- Provider variables: `<feature><Suffix>Provider` (e.g. `productRepositoryProvider`)
+- All codegen annotations: `@riverpod` (lowercase) on provider functions and Notifier classes
+
+## AppState<T> — All 5 cases must be handled
+```dart
+sealed class AppState<T> {
+  const factory AppState.loading()                                      = _Loading;
+  const factory AppState.data(T value)                                  = _Data;
+  const factory AppState.empty()                                        = _Empty;
+  const factory AppState.error(AppError error)                          = _Error;
+  const factory AppState.deadLetter({required AppError error, required String requestId}) = _DeadLetter;
+}
+```
+
+## AppError — Every error must carry a requestId
+```dart
+sealed class AppError {
+  const factory AppError.client({required String requestId, required int statusCode, required String userMessage, String? developerMessage}) = ClientError;
+  const factory AppError.server({required String requestId, required int statusCode, required String userMessage}) = ServerError;
+  const factory AppError.network({required String requestId, required String userMessage, int retryCount}) = NetworkError;
+  const factory AppError.database({required String requestId, required String userMessage, required Object cause}) = DatabaseError;
+  const factory AppError.syncDead({required String requestId, required String feature, required String operation, required String userMessage, required List<String> errorLog}) = SyncDeadError;
+  const factory AppError.conflict({required String requestId, required String userMessage, required Map<String, dynamic> localData, required Map<String, dynamic> serverData}) = ConflictError;
+}
+```
+
+## Repository Write Pattern (always)
+```dart
+Future<T> create(CreateInput input) async {
+  final operationId = const Uuid().v4();
+  final local = await dao.insert(input.toCompanion(operationId));
+  await outbox.enqueue(operationId: operationId, feature: '<n>', operation: 'create', payload: input.toJson());
+  if (await connectivity.isOnline) outbox.drainNow().ignore();
+  return local;
+}
+```
+
+## Notifier Pattern (always thin)
+```dart
+@riverpod
+class <N>Notifier extends _$<N>Notifier {
+  @override
+  AppState<List<T>> build() {
+    ref.listen(<n>StreamProvider, (_, next) {
+      next.when(
+        data: (items) => state = items.isEmpty ? const AppState.empty() : AppState.data(items),
+        loading: () => state = const AppState.loading(),
+        error: (e, _) => state = AppState.error(_mapError(e)),
+      );
+    });
+    return const AppState.loading();
+  }
+  AppError _mapError(Object e) => ref.read(errorHandlerProvider).map(e);
+}
+```
+
+## Design System — NEVER hardcode
+- Colors: `AppColors.<name>` only
+- Spacing: `AppSpacing.xs/sm/md/lg/xl/xxl` (4/8/16/24/32/48)
+- Radius: `AppRadius.sm/md/lg/full`
+- Text: `AppTypography.<style>` only
+- SyncStatusBadge: required on any widget displaying a record with syncStatus
+
+## Auth Storage Rules
+- Access token + refresh token → `FlutterSecureStorage` only
+- Non-sensitive (userId, locale, theme) → `SharedPreferences`
+- NEVER store tokens in SharedPreferences

package/workflows/powers/flutter-feature/references/composite-provider.md

@@ -0,0 +1,58 @@
+# Composite Provider Pattern
+
+## The Rule
+When a screen needs data from multiple features (e.g. product + category +
+inventory), NEVER import one repository from another repository. Compose at
+the Riverpod provider layer only.
+
+## Pattern
+```dart
+// Result type — freezed sealed class
+@freezed
+class ProductDetailState with _$ProductDetailState {
+  const factory ProductDetailState({
+    required Product product,
+    required Category category,
+    required InventoryStock inventory,
+  }) = _ProductDetailState;
+}
+
+// Composite provider — each repo stays independent
+@riverpod
+Future<ProductDetailState> productDetail(Ref ref, String productId) async {
+  final product = await ref.watch(productRepositoryProvider).getById(productId);
+  if (product == null) throw AppError.client(
+    requestId: const Uuid().v4(),
+    statusCode: 404,
+    userMessage: 'Product not found',
+  );
+  final category  = await ref.watch(categoryRepositoryProvider).getById(product.categoryId);
+  final inventory = await ref.watch(inventoryRepositoryProvider).getByProduct(productId);
+
+  return ProductDetailState(
+    product:   product,
+    category:  category!,
+    inventory: inventory,
+  );
+}
+```
+
+## Test
+```dart
+test('composes all three repos', () async {
+  final container = ProviderContainer(overrides: [
+    productRepositoryProvider.overrideWith((_) => FakeProductRepository()),
+    categoryRepositoryProvider.overrideWith((_) => FakeCategoryRepository()),
+    inventoryRepositoryProvider.overrideWith((_) => FakeInventoryRepository()),
+  ]);
+  final state = await container.read(productDetailProvider('p1').future);
+  expect(state.category.name, isNotEmpty);
+  expect(state.inventory, isNotNull);
+});
+```
+
+## When to use
+- Screen needs data from 2+ features
+- Provider function (not a Notifier) — it's read-only composition
+- State type is a dedicated `<Feature>DetailState` freezed class
+- File goes in: `features/<main-feature>/presentation/providers/<n>_detail_provider.dart`

package/workflows/powers/flutter-feature/references/outbox-pattern.md

@@ -0,0 +1,87 @@
+# Outbox Pattern Reference
+
+## The Rule
+Every write = local Drift first → outbox enqueue → return immediately.
+Never await the network before returning to UI.
+
+## Outbox Table (in AppDatabase)
+```dart
+class OutboxTable extends Table {
+  IntColumn  get id            => integer().autoIncrement()();
+  TextColumn get operationId   => text()();   // UUID v4 — dedup key for server
+  TextColumn get feature       => text()();   // e.g. 'product', 'sale'
+  TextColumn get operation     => text()();   // 'create' | 'update' | 'delete'
+  TextColumn get payload       => text()();   // jsonEncode(input.toJson())
+  IntColumn  get retryCount    => integer().withDefault(const Constant(0))();
+  IntColumn  get maxRetries    => integer().withDefault(const Constant(3))();
+  TextColumn get status        => text().withDefault(const Constant('pending'))();
+  // pending → processing → done | failed → dead
+  DateTimeColumn get createdAt     => dateTime()();
+  DateTimeColumn get lastAttemptAt => dateTime().nullable()();
+  TextColumn     get errorLog      => text().nullable()();
+}
+```
+
+## Repository Write Template
+```dart
+Future<T> create(Create<T>Input input) async {
+  final operationId = const Uuid().v4();
+
+  // 1. Write locally — always succeeds even offline
+  final local = await dao.insert(
+    input.toCompanion(operationId: operationId),
+  );
+
+  // 2. Queue for sync
+  await outbox.enqueue(
+    operationId: operationId,
+    feature:     '<feature>',
+    operation:   'create',
+    payload:     input.toJson(),
+  );
+
+  // 3. Try immediate sync if online (fire-and-forget)
+  if (await connectivity.isOnline) outbox.drainNow().ignore();
+
+  // 4. Return local result — UI never waits for server
+  return local;
+}
+```
+
+## Sync Status on Drift Table
+Every table that participates in offline sync adds:
+```dart
+TextColumn get syncStatus => text()
+  .withDefault(const Constant('pendingSync'))();
+// Values: pendingSync | synced | failed | dead | conflict
+```
+
+## Conflict Strategies
+Declare per-feature in the repository or service:
+```dart
+static const conflictStrategy = ConflictStrategy.clientWins;
+// clientWins     — offline action wins (sales, POS)
+// serverWins     — server is truth (pricing, master data)
+// lastWriteWins  — compare updatedAt timestamps
+// manualResolve  — surface ConflictError to user (safety-critical)
+```
+
+## OutboxService (auto-drain on reconnect)
+The outbox service watches connectivity and auto-drains:
+```dart
+@override
+AppState<OutboxState> build() {
+  ref.listen(connectivityProvider, (_, next) {
+    if (next == ConnectivityStatus.online) drainNow();
+  });
+  return const AppState.idle();
+}
+```
+
+## SyncStatusBadge Usage
+Show on any ListTile or Card that displays a record with syncStatus:
+```dart
+SyncStatusBadge(status: item.syncStatus)
+// Renders: 🕐 grey (pendingSync) | ✅ green (synced)
+//          ⚠️ amber (failed) | ❌ red (dead) | ⚡ orange (conflict)
+```