@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/riverpod-3/steering/refresh-cache-paging.md

@@ -0,0 +1,106 @@
+# Refresh + paging + caching patterns (Riverpod 3)
+
+## 1) Refresh
+
+Controller pattern:
+
+```dart
+Future<void> refresh() async {
+  ref.invalidateSelf();
+  await future;
+}
+```
+
+UI pattern:
+
+```dart
+RefreshIndicator(
+  onRefresh: () => ref.read(itemsControllerProvider(query: query).notifier).refresh(),
+  child: ItemsList(items: items),
+)
+```
+
+Notes:
+- `invalidateSelf` marks provider stale and recomputes on next read.
+- Use `ref.refresh(provider)` when you need an immediate fresh value in imperative code.
+
+## 2) Paging
+
+Represent load-more state separately from initial AsyncValue:
+
+```dart
+@freezed
+class PagedState<T> with _$PagedState<T> {
+  const factory PagedState({
+    @Default(<T>[]) List<T> items,
+    String? nextCursor,
+    @Default(true) bool hasMore,
+    @Default(false) bool isLoadingMore,
+    String? loadMoreError,
+  }) = _PagedState<T>;
+}
+```
+
+Rules:
+- guard parallel `loadMore` calls,
+- append immutably,
+- reset cursor/items on refresh.
+
+## 3) Caching strategy
+
+### In-memory (provider cache)
+- Provider values are cached while alive.
+- Families cache by parameter instance.
+- Default auto-dispose is safer for high-cardinality families.
+
+### Persistent (storage-agnostic)
+Cache belongs in repository/data layer, not widget layer.
+Storage can be Drift/SQLite/Isar/Hive/etc.
+
+Recommended read flow:
+1. return fresh local cache if available,
+2. fetch remote when needed,
+3. persist new data,
+4. emit updated state.
+
+## 4) KeepAlive guidance
+
+### Static keepAlive
+Use annotation-level keepAlive for truly app-wide state:
+
+```dart
+@Riverpod(keepAlive: true)
+SessionState sessionState(Ref ref) => const SessionState.unknown();
+```
+
+### Fine-grained keepAlive on auto-disposed providers
+Use `ref.keepAlive()` when you only want to keep successful/fresh results:
+
+```dart
+@riverpod
+Future<List<Item>> cachedItems(Ref ref) async {
+  final link = ref.keepAlive();
+
+  // Example TTL: re-enable auto-dispose after 5 minutes
+  final timer = Timer(const Duration(minutes: 5), link.close);
+  ref.onDispose(timer.cancel);
+
+  return ref.read(itemsRepositoryProvider).fetch();
+}
+```
+
+Use keepAlive for:
+- low-cardinality app-level state,
+- expensive state reused across routes.
+
+Avoid keepAlive for:
+- parameterized search/list/detail families,
+- route-scoped temporary state.
+
+## 5) Stale-while-revalidate UX
+
+Pattern:
+- show cached data immediately,
+- show subtle loading indicator during background refresh,
+- update list when fresh data arrives,
+- keep explicit retry path on error.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/riverpod-3/steering/testing.md

@@ -0,0 +1,159 @@
+# Riverpod 3 testing
+
+This guide focuses on provider/controller tests and widget tests for Riverpod 3 + codegen.
+
+## Core idea
+
+- In tests, control dependencies via `ProviderContainer(overrides: ...)` or `ProviderScope(overrides: ...)`.
+- Never hit real network/db in unit tests.
+- Prefer fakes over heavy mocks when practical.
+
+## 1) Unit test a simple provider
+
+```dart
+test('counter defaults to 0', () {
+  final container = ProviderContainer();
+  addTearDown(container.dispose);
+
+  expect(container.read(counterProvider), 0);
+});
+```
+
+## 2) Unit test an AsyncNotifier (happy path)
+
+```dart
+class FakeOrdersRepository implements OrdersRepository {
+  @override
+  Future<List<Order>> getOrders() async => [Order(id: '1')];
+}
+
+test('OrdersController loads data', () async {
+  final container = ProviderContainer(
+    overrides: [
+      ordersRepositoryProvider.overrideWithValue(FakeOrdersRepository()),
+    ],
+  );
+  addTearDown(container.dispose);
+
+  final state = await container.read(ordersControllerProvider.future);
+  expect(state.items, isNotEmpty);
+});
+```
+
+## 3) Unit test error path
+
+```dart
+class FakeFailOrdersRepository implements OrdersRepository {
+  @override
+  Future<List<Order>> getOrders() async => throw Exception('network');
+}
+
+test('OrdersController exposes error on failure', () async {
+  final container = ProviderContainer(
+    overrides: [
+      ordersRepositoryProvider.overrideWithValue(FakeFailOrdersRepository()),
+    ],
+  );
+  addTearDown(container.dispose);
+
+  expect(
+    () => container.read(ordersControllerProvider.future),
+    throwsException,
+  );
+});
+```
+
+## 4) Unit test `refresh()`
+
+```dart
+class CountingOrdersRepository implements OrdersRepository {
+  int calls = 0;
+
+  @override
+  Future<List<Order>> getOrders() async {
+    calls++;
+    return [Order(id: '$calls')];
+  }
+}
+
+test('refresh re-runs build()', () async {
+  final repo = CountingOrdersRepository();
+  final container = ProviderContainer(
+    overrides: [ordersRepositoryProvider.overrideWithValue(repo)],
+  );
+  addTearDown(container.dispose);
+
+  final first = await container.read(ordersControllerProvider.future);
+  expect(first.items.single.id, '1');
+  expect(repo.calls, 1);
+
+  await container.read(ordersControllerProvider.notifier).refresh();
+
+  final second = await container.read(ordersControllerProvider.future);
+  expect(second.items.single.id, '2');
+  expect(repo.calls, 2);
+});
+```
+
+## 5) Family parameter stability test
+
+```dart
+test('family parameter equality reuses provider instance', () {
+  final container = ProviderContainer();
+  addTearDown(container.dispose);
+
+  final q1 = OrdersQuery(status: 'open', page: 1);
+  final q2 = OrdersQuery(status: 'open', page: 1);
+
+  final a = container.read(ordersListProvider(q1));
+  final b = container.read(ordersListProvider(q2));
+
+  expect(identical(a, b), isTrue);
+});
+```
+
+## 6) Paging controller test
+
+```dart
+class FakePagedRepo implements OrdersRepository {
+  int page = 0;
+
+  @override
+  Future<OrderPage> fetchPage({String? cursor}) async {
+    page++;
+    if (page == 1) return OrderPage(items: [Order(id: 'a')], nextCursor: 'c2');
+    if (page == 2) return OrderPage(items: [Order(id: 'b')], nextCursor: null);
+    return OrderPage(items: const [], nextCursor: null);
+  }
+}
+```
+
+Validate:
+- first page loads,
+- `loadMore` appends immutably,
+- `hasMore` flips to false when no cursor.
+
+## 7) Widget test (loading -> data)
+
+```dart
+testWidgets('shows list when data loaded', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        ordersRepositoryProvider.overrideWithValue(FakeOrdersRepository()),
+      ],
+      child: const MaterialApp(home: OrdersView()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+});
+```
+
+## 8) Loop regression test
+
+If a screen previously had rebuild loops:
+- pump widget,
+- call `pumpAndSettle` with timeout,
+- assert it settles.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/riverpod-3/templates/cache_policy.dart.md

@@ -0,0 +1,17 @@
+```dart
+// templates/cache_policy.dart.tmpl
+//
+// Minimal TTL helper you can use in repositories.
+
+class CachePolicy {
+  const CachePolicy({
+    required this.ttl,
+    this.allowStaleWhileRevalidate = true,
+  });
+
+  final Duration ttl;
+  final bool allowStaleWhileRevalidate;
+
+  bool isFresh(DateTime cachedAt, DateTime now) => now.difference(cachedAt) <= ttl;
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/riverpod-3/templates/paged_controller.dart.md

@@ -0,0 +1,54 @@
+# Paged Controller Template
+
+Infinite scroll controller with clean initial/refresh/load-more separation.
+
+## Usage
+
+1. Copy `paged_controller.dart.tmpl` to your feature root (e.g., `features/<feature>/`)
+2. Rename file and update part directives
+3. Replace `Item` with your entity type
+4. Replace `itemRepositoryProvider` with your repository provider
+5. Run `flutter pub run build_runner build`
+
+## Key Features
+
+- **Initial load**: `build()` fetches first page
+- **Refresh**: `refresh()` invalidates and re-fetches from scratch
+- **Load more**: `loadNextPage()` appends without losing current items
+- **Error handling**: `loadMoreError` captures pagination errors separately
+
+## State Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `items` | `List<Item>` | All loaded items (immutable) |
+| `nextCursor` | `String?` | Cursor for next page |
+| `hasMore` | `bool` | Whether more pages exist |
+| `isLoadingMore` | `bool` | Loading indicator for pagination |
+| `loadMoreError` | `String?` | Error from load more (not initial) |
+
+## View Integration
+
+```dart
+NotificationListener<ScrollNotification>(
+  onNotification: (notification) {
+    if (notification is ScrollEndNotification &&
+        notification.metrics.extentAfter < 200 &&
+        state.hasMore && !state.isLoadingMore) {
+      ref.read(provider.notifier).loadNextPage();
+    }
+    return false;
+  },
+  child: RefreshIndicator(
+    onRefresh: () => ref.read(provider.notifier).refresh(),
+    child: ListView.builder(...),
+  ),
+)
+```
+
+## Notes
+
+- Uses `ref.watch` in `build()` for repository (establishes dependency)
+- Uses `ref.read` in `loadNextPage()` (no rebuild needed)
+- Build params accessible via `this.orgId` in methods
+- State is always immutable (`List.unmodifiable`)

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/riverpod-3/templates/riverpod_controller_test.md

@@ -0,0 +1,30 @@
+```dart
+// templates/riverpod_controller_test.tmpl
+//
+// Copy into: test/unit/<feature>/<feature>_controller_test.dart
+// Adjust providers + fakes.
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+void main() {
+  test('controller loads data', () async {
+    final container = ProviderContainer(
+      overrides: [
+        // repositoryProvider.overrideWithValue(FakeRepo()),
+      ],
+    );
+    addTearDown(container.dispose);
+
+    // final state = await container.read(controllerProvider(args...).future);
+    // expect(state, ...);
+  });
+
+  test('refresh re-runs build', () async {
+    final container = ProviderContainer();
+    addTearDown(container.dispose);
+
+    // await container.read(controllerProvider(args...).notifier).refresh();
+  });
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/rust-engineer/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: rust-engineer
+description: "Compatibility alias skill. Deprecated: use rust-pro."
+metadata:
+  deprecated: true
+  replaced_by: rust-pro
+  removal_target: v0.6.0
+---
+
+# Rust Engineer
+
+## Compatibility Alias
+
+This skill is deprecated and kept for backward compatibility.
+
+Use `rust-pro` as the canonical skill.
+
+## Migration
+
+1. Replace direct references to `rust-engineer` with `rust-pro`.
+2. Apply the full workflow from `rust-pro` for new work.