@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/dart-pro/references/isolate-and-concurrency.md

@@ -0,0 +1,180 @@
+# Isolate and Concurrency Patterns
+
+## Isolate.run — Simple Compute Offload
+
+```dart
+// Isolate.run for one-shot heavy computation (Dart 3.0+)
+Future<List<SearchResult>> searchIndex(String query) async {
+  final data = await loadIndexData();
+
+  // Runs in a new isolate — no main-isolate jank
+  return await Isolate.run(() {
+    return performSearch(data, query); // data is copied to isolate
+  });
+}
+
+// In Flutter, use compute() for the same purpose
+final results = await compute(performSearch, (data, query));
+```
+
+## Long-Lived Isolates with Ports
+
+```dart
+// Long-lived worker for continuous processing
+class ImageProcessor {
+  late final Isolate _isolate;
+  late final SendPort _sendPort;
+  final ReceivePort _receivePort = ReceivePort();
+  final Map<int, Completer<Uint8List>> _pending = {};
+  int _nextId = 0;
+
+  Future<void> start() async {
+    _isolate = await Isolate.spawn(_workerEntryPoint, _receivePort.sendPort);
+
+    // First message from worker is its SendPort
+    final completer = Completer<SendPort>();
+    _receivePort.listen((message) {
+      if (message is SendPort) {
+        completer.complete(message);
+      } else if (message is (int, Uint8List)) {
+        final (id, result) = message;
+        _pending.remove(id)?.complete(result);
+      }
+    });
+    _sendPort = await completer.future;
+  }
+
+  Future<Uint8List> processImage(Uint8List imageData) {
+    final id = _nextId++;
+    final completer = Completer<Uint8List>();
+    _pending[id] = completer;
+    _sendPort.send((id, imageData));
+    return completer.future;
+  }
+
+  void dispose() {
+    _isolate.kill(priority: Isolate.immediate);
+    _receivePort.close();
+  }
+
+  static void _workerEntryPoint(SendPort mainPort) {
+    final workerPort = ReceivePort();
+    mainPort.send(workerPort.sendPort);
+
+    workerPort.listen((message) {
+      if (message is (int, Uint8List)) {
+        final (id, data) = message;
+        final result = _applyFilters(data); // heavy work
+        mainPort.send((id, result));
+      }
+    });
+  }
+
+  static Uint8List _applyFilters(Uint8List data) {
+    // ... image processing
+    return data;
+  }
+}
+```
+
+## Stream-Based Concurrency
+
+```dart
+// StreamController for event-driven architecture
+class EventBus {
+  final _controller = StreamController<AppEvent>.broadcast();
+
+  Stream<AppEvent> get events => _controller.stream;
+
+  // Type-filtered streams
+  Stream<T> on<T extends AppEvent>() =>
+      _controller.stream.whereType<T>();
+
+  void emit(AppEvent event) => _controller.add(event);
+
+  void dispose() => _controller.close();
+}
+
+// Usage
+final bus = EventBus();
+bus.on<OrderCreated>().listen((event) {
+  notifyUser(event.orderId);
+});
+bus.emit(OrderCreated(orderId: 42));
+```
+
+## Stream Transformations
+
+```dart
+// Debounce search input
+Stream<String> debounce(Stream<String> input, Duration delay) async* {
+  Timer? timer;
+  String? lastValue;
+
+  await for (final value in input) {
+    lastValue = value;
+    timer?.cancel();
+    timer = Timer(delay, () {});
+    await Future.delayed(delay);
+    if (lastValue == value) yield value;
+  }
+}
+
+// Rate limiting with Stream.asyncMap
+Stream<Response> rateLimited(
+  Stream<Request> requests, {
+  Duration interval = const Duration(milliseconds: 100),
+}) {
+  return requests.asyncMap((request) async {
+    await Future.delayed(interval);
+    return await processRequest(request);
+  });
+}
+
+// Cancellation pattern
+class DataFetcher {
+  StreamSubscription? _subscription;
+
+  void startListening(Stream<Update> updates) {
+    // Cancel previous subscription before starting new one
+    _subscription?.cancel();
+    _subscription = updates.listen(
+      (update) => handleUpdate(update),
+      onError: (e) => handleError(e),
+      onDone: () => handleDone(),
+    );
+  }
+
+  void dispose() {
+    _subscription?.cancel(); // always cancel in dispose
+    _subscription = null;
+  }
+}
+```
+
+## Zones for Error Handling
+
+```dart
+// Run code in a zone to catch uncaught async errors
+void main() {
+  runZonedGuarded(
+    () => runApp(const MyApp()),
+    (error, stackTrace) {
+      // Catches uncaught errors from async code
+      reportError(error, stackTrace);
+    },
+  );
+}
+```
+
+## Concurrency Rules
+
+| Rule                                                       | Reason                                         |
+| ---------------------------------------------------------- | ---------------------------------------------- |
+| Never do heavy compute on main isolate                     | Causes UI jank (>16ms blocks drop frames)      |
+| Use `Isolate.run` for one-shot work                        | Simpler than managing ports                    |
+| Use persistent isolates for ongoing work                   | Avoids spawn/teardown overhead per task        |
+| Cancel stream subscriptions in `dispose()`                 | Prevents memory leaks and ghost listeners      |
+| Don't share mutable state across isolates                  | Isolates have separate heaps — send copies     |
+| Use `TransferableTypedData` for large buffers              | Avoids copying overhead for byte arrays        |
+| Use `StreamController.broadcast()` only for multi-listener | Single-listener controllers are more efficient |

package/workflows/powers/dart-pro/references/null-safety-and-async-patterns.md

@@ -0,0 +1,133 @@
+# Null Safety and Async Patterns
+
+## Null safety rules
+
+### Non-nullable by default
+
+- `String name` means name is never null. `String? name` means null is a valid value.
+- Use `?` only when null carries domain meaning (e.g., "no value selected"), not as a lazy default.
+- Avoid `late` unless the variable is guaranteed to be initialized before use and you cannot restructure to avoid it.
+
+### Null assertion (`!`) usage
+
+- **Never** use `!` without a preceding null check or guard in the same scope in production code.
+- In tests, `!` is acceptable after assertions: `expect(result, isNotNull); result!.doSomething();`
+- Prefer `if-case` or null-aware operators (`?.`, `??`) over `!`.
+
+### Null-aware operators cheatsheet
+
+| Operator | Meaning                      | Example                    |
+| -------- | ---------------------------- | -------------------------- |
+| `?.`     | Call method only if non-null | `user?.name`               |
+| `??`     | Default if null              | `name ?? 'Unknown'`        |
+| `??=`    | Assign if null               | `cache ??= compute()`      |
+| `?..`    | Cascade only if non-null     | `list?..add(item)..sort()` |
+
+## Sealed classes and pattern matching
+
+### Defining sealed hierarchies
+
+```dart
+sealed class AuthState {}
+class Unauthenticated extends AuthState {}
+class Authenticating extends AuthState {}
+class Authenticated extends AuthState {
+  final User user;
+  Authenticated(this.user);
+}
+```
+
+- Sealed classes enable **exhaustive switch** — the compiler errors if a subtype is missing.
+- Adding a new subtype immediately surfaces all locations that need updating.
+
+### Exhaustive switch
+
+```dart
+Widget build(AuthState state) => switch (state) {
+  Unauthenticated() => const LoginPage(),
+  Authenticating()  => const LoadingSpinner(),
+  Authenticated(:final user) => HomePage(user: user),
+};
+```
+
+- Use destructuring (`:final field`) to extract values in switch arms.
+- Prefer switch expressions over if/else chains for sealed types.
+
+## Records
+
+```dart
+(int, String) parseHeader(String line) {
+  final parts = line.split(':');
+  return (int.parse(parts[0]), parts[1].trim());
+}
+
+final (code, message) = parseHeader('200: OK');
+```
+
+- Use records for lightweight grouped returns — no need to create single-use classes.
+- Name fields for clarity: `({int id, String name}) getUserInfo()`.
+- Records are value types: equality is structural, not referential.
+
+## Async patterns
+
+### Future best practices
+
+- Always `await` Futures. Never fire-and-forget unless you explicitly handle errors with `.catchError` or a zone.
+- Use `Future.wait` for concurrent independent operations, not sequential `await` calls.
+- Handle errors with try/catch around `await`, not `.catchError` chains.
+
+### Stream lifecycle management
+
+```dart
+class EventManager {
+  final _controller = StreamController<Event>.broadcast();
+  Stream<Event> get events => _controller.stream;
+
+  void emit(Event e) => _controller.add(e);
+
+  void dispose() {
+    _controller.close(); // Always close controllers
+  }
+}
+```
+
+- Use `StreamController` (not broadcast) when only one listener is expected.
+- Use `.broadcast()` only when multiple listeners must receive the same events.
+- Always cancel `StreamSubscription` in `dispose()` or `deactivate()`.
+- Prefer `async*` generator functions for producing streams from iteration or polling.
+
+### Isolate patterns
+
+```dart
+// Simple isolate for CPU-heavy work
+final result = await Isolate.run(() {
+  return heavyComputation(data);
+});
+```
+
+- Use `Isolate.run()` (Dart 2.19+) for one-shot CPU work. It handles spawning and result transfer.
+- In Flutter, use `compute()` for the same pattern with simpler API.
+- For long-lived isolates, use `ReceivePort`/`SendPort` for bidirectional communication.
+- Only `Sendable` objects can cross isolate boundaries. Classes with closures or raw pointers cannot be sent.
+
+## Error handling in async code
+
+```dart
+Future<User> fetchUser(int id) async {
+  try {
+    final response = await http.get(Uri.parse('/users/$id'));
+    if (response.statusCode != 200) {
+      throw HttpException('Failed to fetch user: ${response.statusCode}');
+    }
+    return User.fromJson(jsonDecode(response.body));
+  } on SocketException {
+    throw NetworkException('No network connection');
+  } on FormatException {
+    throw ParseException('Invalid response format');
+  }
+}
+```
+
+- Catch specific exceptions. Avoid bare `catch (e)` unless you re-throw.
+- Transform low-level exceptions into domain-specific exceptions at service boundaries.
+- Use `Zone.current.handleUncaughtError` or `runZonedGuarded` for global error handling in Flutter.

package/workflows/powers/dart-pro/references/package-structure-and-linting.md

@@ -0,0 +1,193 @@
+# Package Structure and Linting
+
+## Recommended Package Layout
+
+```
+my_package/
+├── lib/
+│   ├── my_package.dart          # Barrel file — public API exports
+│   └── src/
+│       ├── models/
+│       │   ├── user.dart
+│       │   └── order.dart
+│       ├── services/
+│       │   └── auth_service.dart
+│       └── utils/
+│           └── validators.dart
+├── test/
+│   ├── models/
+│   │   └── user_test.dart
+│   └── services/
+│       └── auth_service_test.dart
+├── example/                      # Usage examples (libraries)
+├── analysis_options.yaml
+├── pubspec.yaml
+└── pubspec.lock                  # Commit for apps, .gitignore for libraries
+```
+
+## Barrel File Pattern
+
+```dart
+// lib/my_package.dart — only export public API
+library my_package;
+
+export 'src/models/user.dart';
+export 'src/models/order.dart';
+export 'src/services/auth_service.dart';
+// DO NOT export implementation-only files
+
+// Use show/hide for selective exports
+export 'src/models/user.dart' show User, UserRole;
+export 'src/models/user.dart' hide InternalUserState;
+```
+
+## pubspec.yaml Best Practices
+
+```yaml
+name: my_package
+description: A concise description of what this package does.
+version: 1.2.3
+publish_to: none # Remove for pub.dev publishing
+
+environment:
+  sdk: ^3.9.0 # Pin to minimum required version
+
+dependencies:
+  http: ^1.2.0
+  riverpod: ^2.6.0
+
+dev_dependencies:
+  test: ^1.25.0
+  mocktail: ^1.0.0
+  very_good_analysis: ^7.0.0 # Or flutter_lints
+  build_runner: ^2.4.0
+  json_serializable: ^6.8.0
+
+# For monorepo workspaces (Dart 3.5+)
+workspace:
+  - packages/core
+  - packages/api
+  - packages/app
+```
+
+## analysis_options.yaml
+
+```yaml
+# Use a lint package as base
+include: package:very_good_analysis/analysis_options.yaml
+
+analyzer:
+  language:
+    strict-casts: true # No implicit casts from dynamic
+    strict-inference: true # No implicit dynamic types
+    strict-raw-types: true # No raw generic types
+
+  errors:
+    # Treat these as errors in CI
+    unused_import: error
+    unused_local_variable: warning
+    dead_code: warning
+    todo: ignore
+
+  exclude:
+    - "**/*.g.dart" # Generated code
+    - "**/*.freezed.dart"
+    - "build/**"
+
+linter:
+  rules:
+    # Additional rules beyond the base package
+    - prefer_single_quotes
+    - require_trailing_commas
+    - sort_constructors_first
+    - unawaited_futures # Catch missing awaits
+    - close_sinks # Catch unclosed StreamControllers
+    - cancel_subscriptions # Catch uncancelled subscriptions
+    - avoid_dynamic_calls # Prevent calls on dynamic
+    - prefer_const_constructors
+    - prefer_const_declarations
+```
+
+## Dependency Audit Workflow
+
+```bash
+# Check for outdated dependencies
+dart pub outdated
+
+# Upgrade to latest compatible versions
+dart pub upgrade
+
+# Upgrade to latest major versions (breaking changes)
+dart pub upgrade --major-versions
+
+# Audit dependency tree
+dart pub deps
+
+# Check for known vulnerabilities (if publishing)
+dart pub publish --dry-run
+
+# Run full analysis
+dart analyze
+dart format --set-exit-if-changed .
+dart test --coverage
+```
+
+## Part and Part-of Directives
+
+```dart
+// Use part files for code generation (json_serializable, freezed)
+// user.dart
+import 'package:json_annotation/json_annotation.dart';
+
+part 'user.g.dart'; // generated code
+
+@JsonSerializable()
+class User {
+  final String name;
+  final int age;
+
+  User({required this.name, required this.age});
+
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+  Map<String, dynamic> toJson() => _$UserToJson(this);
+}
+
+// DO NOT use part/part-of for manual code organization — use imports instead
+```
+
+## Library-Level Visibility
+
+```dart
+// src/ files are private to the package — not importable from outside
+// Only files exported via barrel file are public API
+
+// For package-internal but cross-file visibility, use @visibleForTesting
+import 'package:meta/meta.dart';
+
+class Cache {
+  @visibleForTesting
+  final Map<String, dynamic> store = {};
+
+  // ... public API
+}
+```
+
+## Monorepo with Pub Workspaces
+
+```yaml
+# Root pubspec.yaml
+name: my_workspace
+publish_to: none
+environment:
+  sdk: ^3.9.0
+workspace:
+  - packages/core
+  - packages/api_client
+  - packages/app
+
+# packages/app/pubspec.yaml
+dependencies:
+  core: # Resolved from workspace
+  api_client: # Resolved from workspace
+resolution: workspace # Use workspace resolution
+```

package/workflows/powers/dart-pro/references/sealed-records-patterns.md

@@ -0,0 +1,173 @@
+# Sealed Classes, Records, and Pattern Matching
+
+## Sealed Class Hierarchies
+
+```dart
+// Sealed classes define closed type sets — switch must be exhaustive
+sealed class AuthState {}
+
+class Unauthenticated extends AuthState {}
+class Authenticating extends AuthState {}
+class Authenticated extends AuthState {
+  final User user;
+  Authenticated(this.user);
+}
+class AuthError extends AuthState {
+  final String message;
+  AuthError(this.message);
+}
+
+// Exhaustive switch — compiler error if a variant is missing
+Widget buildAuth(AuthState state) => switch (state) {
+  Unauthenticated()  => const LoginScreen(),
+  Authenticating()   => const LoadingSpinner(),
+  Authenticated(:final user) => HomeScreen(user: user),
+  AuthError(:final message)  => ErrorScreen(message: message),
+};
+```
+
+## Records for Lightweight Data
+
+```dart
+// Positional records — unnamed fields
+(int, String) parseIdAndName(String input) {
+  final parts = input.split(':');
+  return (int.parse(parts[0]), parts[1]);
+}
+
+// Named fields
+({double lat, double lng}) parseCoordinate(String s) {
+  final parts = s.split(',');
+  return (lat: double.parse(parts[0]), lng: double.parse(parts[1]));
+}
+
+// Destructuring
+final (id, name) = parseIdAndName('42:Alice');
+final (:lat, :lng) = parseCoordinate('51.5,-0.1');
+
+// Records have value equality
+final a = (1, 'hello');
+final b = (1, 'hello');
+print(a == b); // true — structural equality
+```
+
+## Pattern Matching
+
+### If-case Patterns
+
+```dart
+// Replace is + cast with if-case
+// BAD
+if (response is Map<String, dynamic>) {
+  final name = response['name'] as String?;
+  if (name != null) {
+    processName(name);
+  }
+}
+
+// GOOD — destructuring in if-case
+if (response case {'name': String name}) {
+  processName(name); // name is already typed as String
+}
+
+// Nested patterns
+if (json case {'user': {'name': String name, 'age': int age}}) {
+  print('$name is $age years old');
+}
+```
+
+### Switch Expression Patterns
+
+```dart
+// Object patterns — match on properties
+String describe(Shape shape) => switch (shape) {
+  Circle(radius: var r) when r > 100 => 'large circle',
+  Circle(radius: var r)              => 'circle with radius $r',
+  Rectangle(width: var w, height: var h) when w == h => 'square ${w}x$h',
+  Rectangle(:var width, :var height) => 'rect ${width}x$height',
+};
+
+// Logical or patterns
+String httpCategory(int status) => switch (status) {
+  200 || 201 || 204 => 'success',
+  301 || 302        => 'redirect',
+  400 || 422        => 'client error',
+  500 || 502 || 503 => 'server error',
+  _                 => 'unknown',
+};
+
+// Guard clauses with when
+String classify(num value) => switch (value) {
+  < 0 => 'negative',
+  == 0 => 'zero',
+  > 0 && < 100 => 'small positive',
+  >= 100 => 'large positive',
+  _ => 'NaN', // for double.nan
+};
+```
+
+### Exhaustiveness Checking
+
+```dart
+// Sealed types + switch = compile-time exhaustiveness
+sealed class Result<T> {}
+class Success<T> extends Result<T> { final T value; Success(this.value); }
+class Failure<T> extends Result<T> { final Exception error; Failure(this.error); }
+
+// Compiler enforces both Success and Failure are handled
+T unwrap<T>(Result<T> result) => switch (result) {
+  Success(:final value) => value,
+  Failure(:final error) => throw error,
+  // No default needed — sealed class makes this exhaustive
+};
+
+// Adding a new variant (e.g., Loading) causes compile errors everywhere
+```
+
+## Extension Types (Dart 3.3+)
+
+```dart
+// Zero-cost type wrappers — compiled away at runtime
+extension type UserId(int value) {
+  // Only UserId-specific methods are available
+  bool get isValid => value > 0;
+}
+
+extension type Email(String value) {
+  factory Email.parse(String input) {
+    if (!input.contains('@')) throw FormatException('Invalid email: $input');
+    return Email(input.toLowerCase());
+  }
+}
+
+// Type safety without runtime overhead
+void sendEmail(Email to, UserId from) { /*...*/ }
+
+// Can't accidentally pass raw int/String where UserId/Email is expected
+sendEmail(Email.parse('alice@example.com'), UserId(42));
+```
+
+## Class Modifiers (Dart 3.0+)
+
+```dart
+// interface class — can implement but not extend
+interface class Serializable {
+  Map<String, dynamic> toJson();
+}
+
+// base class — can extend but not implement
+base class BaseRepository {
+  Future<void> connect() async { /*...*/ }
+}
+
+// final class — cannot be extended or implemented outside the library
+final class InternalConfig {
+  final String apiKey;
+  InternalConfig(this.apiKey);
+}
+
+// mixin class — can be used as both mixin and class
+mixin class Logging {
+  void log(String message) => print('[LOG] $message');
+}
+```