@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/bloc-state.md

@@ -0,0 +1,259 @@
+# Bloc State Management
+
+## When to Use Bloc
+
+Use **Bloc/Cubit** when you need:
+
+* Explicit event → state transitions
+* Complex business logic
+* Predictable, testable flows
+* Clear separation between UI and logic
+
+| Use Case               | Recommended |
+| ---------------------- | ----------- |
+| Simple mutable state   | Riverpod    |
+| Event-driven workflows | Bloc        |
+| Forms, auth, wizards   | Bloc        |
+| Feature modules        | Bloc        |
+
+---
+
+## Core Concepts
+
+| Concept | Description            |
+| ------- | ---------------------- |
+| Event   | User/system input      |
+| State   | Immutable UI state     |
+| Bloc    | Event → State mapper   |
+| Cubit   | State-only (no events) |
+
+---
+
+## Basic Bloc Setup
+
+### Event
+
+```dart
+sealed class CounterEvent {}
+
+final class CounterIncremented extends CounterEvent {}
+
+final class CounterDecremented extends CounterEvent {}
+```
+
+### State
+
+```dart
+class CounterState {
+  final int value;
+
+  const CounterState({required this.value});
+
+  CounterState copyWith({int? value}) {
+    return CounterState(value: value ?? this.value);
+  }
+}
+```
+
+### Bloc
+
+```dart
+import 'package:flutter_bloc/flutter_bloc.dart';
+
+class CounterBloc extends Bloc<CounterEvent, CounterState> {
+  CounterBloc() : super(const CounterState(value: 0)) {
+    on<CounterIncremented>((event, emit) {
+      emit(state.copyWith(value: state.value + 1));
+    });
+
+    on<CounterDecremented>((event, emit) {
+      emit(state.copyWith(value: state.value - 1));
+    });
+  }
+}
+```
+
+---
+
+## Cubit (Recommended for Simpler Logic)
+
+```dart
+class CounterCubit extends Cubit<int> {
+  CounterCubit() : super(0);
+
+  void increment() => emit(state + 1);
+  void decrement() => emit(state - 1);
+}
+```
+
+---
+
+## Providing Bloc to the Widget Tree
+
+```dart
+BlocProvider(
+  create: (_) => CounterBloc(),
+  child: const CounterScreen(),
+);
+```
+
+Multiple blocs:
+
+```dart
+MultiBlocProvider(
+  providers: [
+    BlocProvider(create: (_) => AuthBloc()),
+    BlocProvider(create: (_) => ProfileBloc()),
+  ],
+  child: const AppRoot(),
+);
+```
+
+---
+
+## Using Bloc in Widgets
+
+### BlocBuilder (UI rebuilds)
+
+```dart
+class CounterScreen extends StatelessWidget {
+  const CounterScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<CounterBloc, CounterState>(
+      buildWhen: (prev, curr) => prev.value != curr.value,
+      builder: (context, state) {
+        return Text(
+          state.value.toString(),
+          style: Theme.of(context).textTheme.displayLarge,
+        );
+      },
+    );
+  }
+}
+```
+
+---
+
+### BlocListener (Side Effects)
+
+```dart
+BlocListener<AuthBloc, AuthState>(
+  listenWhen: (prev, curr) => curr is AuthFailure,
+  listener: (context, state) {
+    if (state is AuthFailure) {
+      ScaffoldMessenger.of(context)
+          .showSnackBar(SnackBar(content: Text(state.message)));
+    }
+  },
+  child: const LoginForm(),
+);
+```
+
+---
+
+### BlocConsumer (Builder + Listener)
+
+```dart
+BlocConsumer<FormBloc, FormState>(
+  listener: (context, state) {
+    if (state.status == FormStatus.success) {
+      context.pop();
+    }
+  },
+  builder: (context, state) {
+    return ElevatedButton(
+      onPressed: state.isValid
+          ? () => context.read<FormBloc>().add(FormSubmitted())
+          : null,
+      child: const Text('Submit'),
+    );
+  },
+);
+```
+
+---
+
+## Accessing Bloc Without Rebuilds
+
+```dart
+context.read<CounterBloc>().add(CounterIncremented());
+```
+
+⚠️ **Never use `watch` inside callbacks**
+
+---
+
+## Async Bloc Pattern (API Calls)
+
+```dart
+on<UserRequested>((event, emit) async {
+  emit(const UserState.loading());
+
+  try {
+    final user = await repository.fetchUser();
+    emit(UserState.success(user));
+  } catch (e) {
+    emit(UserState.failure(e.toString()));
+  }
+});
+```
+
+---
+
+## Bloc + GoRouter (Auth Guard Example)
+
+```dart
+redirect: (context, state) {
+  final authState = context.read<AuthBloc>().state;
+
+  if (authState is Unauthenticated) {
+    return '/login';
+  }
+  return null;
+}
+```
+
+---
+
+## Testing Bloc
+
+```dart
+blocTest<CounterBloc, CounterState>(
+  'emits incremented value',
+  build: () => CounterBloc(),
+  act: (bloc) => bloc.add(CounterIncremented()),
+  expect: () => [
+    const CounterState(value: 1),
+  ],
+);
+```
+
+---
+
+## Best Practices (MUST FOLLOW)
+
+✅ Immutable states
+✅ Small, focused blocs
+✅ One feature = one bloc
+✅ Use Cubit when possible
+✅ Test all blocs
+
+❌ No UI logic inside blocs
+❌ No context usage inside blocs
+❌ No mutable state
+❌ No massive “god blocs”
+
+---
+
+## Quick Reference
+
+| Widget            | Purpose              |
+| ----------------- | -------------------- |
+| BlocBuilder       | UI rebuild           |
+| BlocListener      | Side effects         |
+| BlocConsumer      | Both                 |
+| BlocProvider      | Dependency injection |
+| MultiBlocProvider | Multiple blocs       |
+

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/engineering-principles.md

@@ -0,0 +1,82 @@
+# Engineering Principles
+
+## Core Principles
+
+### SOLID
+
+- **S**ingle Responsibility: One reason to change per class/module
+- **O**pen/Closed: Open for extension, closed for modification
+- **L**iskov Substitution: Subtypes must be substitutable for base types
+- **I**nterface Segregation: Many specific interfaces > one general interface
+- **D**ependency Inversion: Depend on abstractions, not concretions
+
+### KISS — Keep It Simple
+
+- Prefer straightforward solutions over clever ones
+- If it's hard to explain, it's probably too complex
+- Complexity is the enemy of reliability
+
+### DRY — Don't Repeat Yourself
+
+- Extract shared logic into reusable functions/modules
+- Single source of truth for business rules
+- But: don't over-abstract prematurely (see YAGNI)
+
+### YAGNI — You Aren't Gonna Need It
+
+- Build only what's needed now
+- No speculative features or "just in case" code
+- Requirements change; premature abstraction wastes effort
+
+### Separation of Concerns
+
+- Each module handles one aspect of functionality
+- UI, business logic, data access in separate layers
+- Clear boundaries between packages
+
+### Dependency Inversion
+
+- High-level modules don't depend on low-level modules
+- Both depend on abstractions (interfaces)
+- Inject dependencies, don't instantiate them
+
+### Explicit > Implicit
+
+- Favor explicit configuration over magic
+- Clear naming over clever shortcuts
+- Readable code over terse code
+
+### Fail Fast
+
+- Validate inputs at boundaries
+- Throw early on invalid state
+- Don't silently swallow errors
+
+### Boring Architecture Wins
+
+- Proven patterns over trendy solutions
+- Standard libraries over custom implementations
+- Maintainability over cleverness
+
+---
+
+## Applying These Principles
+
+### When Writing Code
+
+1. Ask: "Does this class/function do one thing?"
+2. Ask: "Is this the simplest solution that works?"
+3. Ask: "Am I building something I actually need right now?"
+4. Ask: "Would a new team member understand this?"
+
+### When Reviewing Code
+
+- Flag violations of these principles
+- Suggest simpler alternatives
+- Question speculative features
+
+### When Designing
+
+- Start simple, add complexity only when proven necessary
+- Prefer composition over inheritance
+- Design for change, but don't over-engineer

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/gorouter-navigation.md

@@ -0,0 +1,157 @@
+# GoRouter Navigation
+
+## Route Constants (Required Pattern)
+
+```dart
+// lib/core/routes/routes.dart
+abstract class Routes {
+  static const home = '/home';
+  static const profile = '/profile';
+  static const settings = '/settings';
+  static const login = '/auth/login';
+  static const todoDetails = '/todos/:id';
+  static const userProfile = '/users/:userId';
+  
+  // Helper for parameterized routes
+  static String todoDetailsPath(String id) => '/todos/$id';
+  static String userProfilePath(String userId) => '/users/$userId';
+}
+```
+
+## Basic Setup
+
+```dart
+import 'package:go_router/go_router.dart';
+
+final goRouter = GoRouter(
+  initialLocation: Routes.home,
+  redirect: (context, state) {
+    final isLoggedIn = /* check auth */;
+    if (!isLoggedIn && !state.matchedLocation.startsWith('/auth')) {
+      return Routes.login;
+    }
+    return null;
+  },
+  routes: [
+    GoRoute(
+      path: Routes.home,
+      builder: (context, state) => const HomeScreen(),
+    ),
+    GoRoute(
+      path: Routes.todoDetails,
+      builder: (context, state) {
+        final id = state.pathParameters['id']!;
+        return TodoDetailsScreen(id: id);
+      },
+    ),
+    GoRoute(
+      path: Routes.login,
+      builder: (context, state) => const LoginScreen(),
+    ),
+  ],
+);
+```
+
+## Navigation Methods
+
+```dart
+// Navigate and replace history
+context.go(Routes.home);
+
+// Navigate with params
+context.go(Routes.todoDetailsPath('123'));
+
+// Navigate and add to stack
+context.push(Routes.profile);
+
+// Go back
+context.pop();
+
+// Replace current route
+context.pushReplacement(Routes.home);
+
+// Navigate with extra data
+context.push(Routes.todoDetailsPath('123'), extra: {'title': 'My Todo'});
+
+// Access extra in destination
+final extra = GoRouterState.of(context).extra as Map<String, dynamic>?;
+```
+
+## Shell Routes (Persistent UI)
+
+```dart
+final goRouter = GoRouter(
+  routes: [
+    ShellRoute(
+      builder: (context, state, child) {
+        return ScaffoldWithNavBar(child: child);
+      },
+      routes: [
+        GoRoute(path: Routes.home, builder: (_, __) => const HomeScreen()),
+        GoRoute(path: Routes.profile, builder: (_, __) => const ProfileScreen()),
+        GoRoute(path: Routes.settings, builder: (_, __) => const SettingsScreen()),
+      ],
+    ),
+  ],
+);
+```
+
+## Query Parameters
+
+```dart
+abstract class Routes {
+  static const search = '/search';
+  
+  static String searchPath({String? query, int? page}) {
+    final params = <String, String>{};
+    if (query != null) params['q'] = query;
+    if (page != null) params['page'] = page.toString();
+    return Uri(path: search, queryParameters: params.isEmpty ? null : params).toString();
+  }
+}
+
+// Usage
+context.go(Routes.searchPath(query: 'flutter', page: 2));
+
+// In route
+GoRoute(
+  path: Routes.search,
+  builder: (context, state) {
+    final query = state.uri.queryParameters['q'] ?? '';
+    final page = int.tryParse(state.uri.queryParameters['page'] ?? '1') ?? 1;
+    return SearchScreen(query: query, page: page);
+  },
+),
+```
+
+## ✅ DO's
+
+```dart
+// ✅ Use route constants
+context.go(Routes.home);
+context.push(Routes.todoDetailsPath(todo.id));
+
+// ✅ Type-safe params with helper methods
+static String todoDetailsPath(String id) => '/todos/$id';
+```
+
+## ❌ DON'Ts
+
+```dart
+// ❌ NEVER use raw strings
+context.go('/home');
+context.push('/todos/123');
+
+// ❌ NEVER hardcode paths in routes
+GoRoute(path: '/home', ...);  // Use Routes.home
+```
+
+## Quick Reference
+
+| Method | Behavior |
+|--------|----------|
+| `context.go(Routes.x)` | Navigate, replace stack |
+| `context.push(Routes.x)` | Navigate, add to stack |
+| `context.pop()` | Go back |
+| `context.pushReplacement()` | Replace current |
+| `Routes.xPath(id)` | Parameterized route helper |

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/performance.md

@@ -0,0 +1,99 @@
+# Performance Optimization
+
+## Profiling Commands
+
+```bash
+# Run in profile mode
+flutter run --profile
+
+# Analyze performance
+flutter analyze
+
+# DevTools
+flutter pub global activate devtools
+flutter pub global run devtools
+```
+
+## Common Optimizations
+
+### Const Widgets
+```dart
+// ❌ Rebuilds every time
+Widget build(BuildContext context) {
+  return Container(
+    padding: EdgeInsets.all(16),  // Creates new object
+    child: Text('Hello'),
+  );
+}
+
+// ✅ Const prevents rebuilds
+Widget build(BuildContext context) {
+  return Container(
+    padding: const EdgeInsets.all(16),
+    child: const Text('Hello'),
+  );
+}
+```
+
+### Selective Provider Watching
+```dart
+// ❌ Rebuilds on any user change
+final user = ref.watch(userProvider);
+return Text(user.name);
+
+// ✅ Only rebuilds when name changes
+final name = ref.watch(userProvider.select((u) => u.name));
+return Text(name);
+```
+
+### RepaintBoundary
+```dart
+// Isolate expensive widgets
+RepaintBoundary(
+  child: ComplexAnimatedWidget(),
+)
+```
+
+### Image Optimization
+```dart
+// Use cached_network_image
+CachedNetworkImage(
+  imageUrl: url,
+  placeholder: (_, __) => const CircularProgressIndicator(),
+  errorWidget: (_, __, ___) => const Icon(Icons.error),
+)
+
+// Resize images
+Image.network(
+  url,
+  cacheWidth: 200,  // Resize in memory
+  cacheHeight: 200,
+)
+```
+
+### Compute for Heavy Operations
+```dart
+// ❌ Blocks UI thread
+final result = heavyComputation(data);
+
+// ✅ Runs in isolate
+final result = await compute(heavyComputation, data);
+```
+
+## Performance Checklist
+
+| Check | Solution |
+|-------|----------|
+| Unnecessary rebuilds | Add `const`, use `select()` |
+| Large lists | Use `ListView.builder` |
+| Image loading | Use `cached_network_image` |
+| Heavy computation | Use `compute()` |
+| Jank in animations | Use `RepaintBoundary` |
+| Memory leaks | Dispose controllers |
+
+## DevTools Metrics
+
+- **Frame rendering time**: < 16ms for 60fps
+- **Widget rebuilds**: Minimize unnecessary rebuilds
+- **Memory usage**: Watch for leaks
+- **CPU profiler**: Identify bottlenecks

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/project-structure.md

@@ -0,0 +1,77 @@
+# Project Structure
+
+## Feature-Based Structure (Pragmatic Architecture)
+
+```
+lib/
+├── main.dart
+├── app.dart
+├── core/
+│   ├── config/             # Environment config
+│   ├── design_system/      # OneUp Design System (One* components)
+│   ├── network/            # Dio client, interceptors, Result type
+│   ├── providers/          # Session, auth, environment
+│   ├── router/             # GoRouter config, guards
+│   ├── cache/              # Cache service
+│   └── utils/              # Extensions, validators, logger
+├── features/
+│   └── <feature>/
+│       ├── data/
+│       │   ├── <feature>_api.dart          # Retrofit client
+│       │   ├── <feature>_cache.dart        # Local cache (optional)
+│       │   └── <feature>_repository.dart   # Conductor + inline DI provider
+│       ├── models/
+│       │   └── <feature>.dart              # ONE Freezed class (entity + fromJson)
+│       ├── <feature>_controller.dart       # ONE AsyncNotifier — reads + writes
+│       ├── <feature>_state.dart            # Freezed state (optional)
+│       ├── views/                          # Screens
+│       └── widgets/                        # Feature-specific widgets
+├── shared/
+│   ├── widgets/            # Shared UI components
+│   ├── models/             # Shared models
+│   └── utils/              # Shared utilities
+└── routes/
+    └── app_router.dart
+```
+
+## Feature Layer Responsibilities
+
+| Layer | Responsibility |
+|-------|----------------|
+| **data/** | API client, cache, repository (conductor) |
+| **models/** | Freezed models with fromJson (one class, not entity+model) |
+| **controller** | AsyncNotifier — reads + writes, owns feature state |
+| **views/** | UI screens |
+| **widgets/** | Feature-specific UI components |
+
+## Key Rules
+
+- No `domain/` folder unless feature has complex business rules
+- No `usecases/` folder — controller calls repo directly
+- No separate `providers/` folder — DI lives inline in repository file
+- No entity/model split — one Freezed class serves both
+- Each feature is self-contained (earn_point is its own feature, not nested in profile)
+
+## Main Entry Point
+
+```dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  runApp(const ProviderScope(child: MyApp()));
+}
+
+class MyApp extends ConsumerWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final router = ref.watch(routerProvider);
+    return MaterialApp.router(
+      routerConfig: router,
+      theme: AppTheme.light,
+      darkTheme: AppTheme.dark,
+      themeMode: ThemeMode.system,
+    );
+  }
+}
+```