coregen-cli 3.1.6__py3-none-any.whl

generators/static/cursor/skills/epic-delivery/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: epic-delivery
+description: Decompose a high-level project description into epics and orchestrate implementation via subagents. Use when the user describes features, product scope, or asks to plan and build new functionality.
+---
+
+# Epic delivery
+
+Turn a high-level product description into implemented DDD features.
+
+## Prerequisites
+
+Read before starting:
+
+- Root `AGENTS.md`
+- `docs/architecture/DDD_LAYERS.md`
+- `docs/architecture/FILE_TEMPLATES.md`
+- `docs/architecture/CARAVAGGIO_COMPONENTS.md` (when epic includes UI)
+- `docs/architecture/MOCK_AND_REMOTE_DATA.md` (when epic includes domain entities or API)
+
+## Workflow
+
+### 1. Analyze
+
+Understand the user's description. Identify domain entities, UI use cases, and dependencies between features.
+
+### 2. Decompose into epics
+
+Create one file per epic: `docs/epics/EPIC-NNN-<slug>.md` using template in `templates/epic.md`.
+
+Each epic should be atomic: typically **one domain aggregate + one UI use case**.
+
+Assign complexity tag:
+
+| Tag | When |
+|-----|------|
+| `small` | 1 entity, 1 UI use case, no new API endpoints |
+| `large` | Multiple entities, multiple screens, new Retrofit endpoints, or cross-feature components |
+
+### 3. Order epics
+
+Respect dependencies (e.g. auth before protected features). Implement independent epics sequentially or note parallelization in epic files.
+
+### 4. Implement each epic
+
+Delegate to subagent **`epic-orchestrator`** with:
+
+- Epic file path
+- Complexity tag (`small` | `large`)
+
+**small** pipeline (~4 subagents):
+
+```
+feature-implementer → integration-wiring → doc-writer → layer-guardian
+```
+
+**large** pipeline (~6–7 subagents):
+
+```
+layer-model → layer-infrastructure → layer-application → layer-presentation
+  → integration-wiring → doc-writer → layer-guardian
+```
+
+### 5. Close epic
+
+- Update epic file status (template: `templates/epic-status.md`)
+- Run `flutter analyze`
+- Address `layer-guardian` findings
+
+## Constraints
+
+- **Never** run `coregen` CLI — write Dart files directly.
+- Do not duplicate widget policy — use `docs/architecture/WIDGETS_AND_CARAVAGGIO.md` and `docs/architecture/CARAVAGGIO_COMPONENTS.md`.
+- For data layers use `docs/architecture/MOCK_AND_REMOTE_DATA.md` — default mock, create `assets/mock/<entity>.json`.
+- Use Explore subagent for codebase search; Bash for analyze and build_runner.

generators/static/cursor/skills/epic-delivery/templates/epic-status.md

@@ -0,0 +1,14 @@
+## Completion log
+
+| Step | Status | Notes |
+|------|--------|-------|
+| Domain model | | |
+| Infrastructure | | |
+| Application | | |
+| Presentation | | |
+| Integration wiring | | |
+| Documentation | | |
+| layer-guardian audit | | |
+
+**Completed at:** _ISO date_  
+**Analyzer:** pass | fail

generators/static/cursor/skills/epic-delivery/templates/epic.md

@@ -0,0 +1,36 @@
+# EPIC-[[epic_number]]: [[epic_title]]
+
+**Status:** pending  
+**Complexity:** small | large  
+**Depends on:** none | EPIC-XXX
+
+## Goal
+
+[[epic_goal]]
+
+## Domain
+
+- Entity: `[[entity_name]]` → `lib/domain/[[entity_name]]/`
+- Enums: [[enums_or_none]]
+
+## Feature UI
+
+- Feature: `[[feature_name]]` → `lib/features/[[feature_name]]/`
+- Screens/components: [[ui_description]]
+
+## API
+
+- New endpoints: yes | no
+- Details: [[api_details]]
+
+## Acceptance criteria
+
+- [ ] Domain model and infrastructure complete
+- [ ] BLoC and presentation complete
+- [ ] Router, DI, error_localizer updated
+- [ ] `flutter analyze` clean
+- [ ] `layer-guardian` audit passed
+
+## Files touched
+
+_(updated by doc-writer on completion)_

generators/static/templates/apis/common/constants_template.jinja

@@ -0,0 +1,48 @@
+/*
+ * API constants template for centralized configuration
+ * Provides a single place for all API-related constants:
+ * - Base API URL (configurable per environment)
+ * - Auth / token refresh base URL (often same as apiUrl or your IdP host)
+ * - Standard HTTP headers
+ * - API key management
+ *
+ * This ensures consistent API communication setup
+ * across all network requests in the application
+ */
+
+class Constants {
+  static const String _placeholderMarker = 'INSERT YOUR';
+
+  /// Main REST API base URL. Leave empty for mock-only development.
+  static String apiUrl = '';
+
+  /// Base URL for token refresh (e.g. Supabase auth). If empty, [AuthInterceptor] falls back to [dioBaseUrl].
+  static String authUrl = '';
+
+  /// True when [apiUrl] is a real URL (not empty or a generator placeholder).
+  static bool get isApiUrlConfigured {
+    final String url = apiUrl.trim();
+    if (url.isEmpty || url.contains(_placeholderMarker)) {
+      return false;
+    }
+    final Uri? uri = Uri.tryParse(url);
+    return uri != null && uri.hasScheme && uri.host.isNotEmpty;
+  }
+
+  /// Base URL for Dio / Retrofit construction.
+  ///
+  /// When [apiUrl] is not configured, returns a valid localhost URL so DI can
+  /// start while all entities use mock data (no HTTP calls are made).
+  static String get dioBaseUrl => isApiUrlConfigured ? apiUrl : 'http://127.0.0.1';
+
+  /// Sent as the `apikey` header on requests and refresh calls (set in your environment).
+  static const String apiKey = '';
+
+  static const String apiKeyHeader = "x-api-key";
+  /// Header name used by [AuthInterceptor] for the API key (matches common Supabase-style clients).
+  static const String apiKeyRequestHeader = "apikey";
+
+  static const String contentTypeHeader = "Content-type";
+  static const String acceptHeader = "Accept";
+  static const String authorizationHeader = "Authorization";
+}

generators/static/templates/apis/common/data_source_config_template.jinja

@@ -0,0 +1,47 @@
+/*
+ * Per-entity data source registry (mock vs remote).
+ *
+ * Change a single entry from DataSource.mock to DataSource.remote when the
+ * backend API for that entity is ready. New entities default to mock so the
+ * app runs without Constants.apiUrl.
+ */
+
+import 'package:[[project_name]]/apis/common/constants.dart';
+
+enum DataSource {
+  mock,
+  remote,
+}
+
+abstract class DataSourceConfig {
+  /// Keys: snake_case entity folder name; 'auth' when login is enabled.
+  static const Map<String, DataSource> entities = {
+[[entities_entries]]
+  };
+
+  static DataSource forEntity(String key) => entities[key] ?? DataSource.mock;
+
+  static bool useMock(String key) => forEntity(key) == DataSource.mock;
+
+  /// Throws if any non-auth entity uses remote but [Constants.apiUrl] is not configured.
+  static void validateRemoteRequiresApiUrl() {
+    if (Constants.isApiUrlConfigured) {
+      return;
+    }
+    final List<String> remoteWithoutUrl = entities.entries
+        .where(
+          (MapEntry<String, DataSource> e) =>
+              e.value == DataSource.remote && e.key != 'auth',
+        )
+        .map((MapEntry<String, DataSource> e) => e.key)
+        .toList();
+    if (remoteWithoutUrl.isEmpty) {
+      return;
+    }
+    throw StateError(
+      'DataSourceConfig: entity/entities ${remoteWithoutUrl.join(', ')} '
+      'use DataSource.remote but Constants.apiUrl is not configured. '
+      'Set apiUrl in initEnvironment() or switch to DataSource.mock.',
+    );
+  }
+}

generators/static/templates/apis/core/api_injectable_module_template.jinja

@@ -0,0 +1,14 @@
+import 'package:dio/dio.dart';
+import 'package:injectable/injectable.dart';
+import 'package:[[project_name]]/apis/common/constants.dart';
+import 'package:[[project_name]]/apis/interceptors/api_logger.dart';
+import 'package:[[project_name]]/apis/interceptors/auth_interceptor.dart';
+
+@module
+abstract class ApisInjectableModule {
+  @lazySingleton
+  Dio get dio => Dio()
+    ..options.baseUrl = Constants.dioBaseUrl
+    ..interceptors.add(ApiLogger())
+    ..interceptors.add(AuthInterceptor(Constants.dioBaseUrl));
+}

generators/static/templates/apis/interceptors/api_logger_template.jinja

@@ -0,0 +1,135 @@
+import 'package:dio/dio.dart';
+import 'package:[[project_name]]/injection.dart';
+import 'package:[[project_name]]/logging/logger.dart';
+
+{% raw %}
+/// Dio interceptor that logs requests/responses through [Logger] (apiReq / apiRes / warning / error).
+///
+/// Same idea as a classic OkHttp-style logger: toggles for request line, headers, body, response, errors.
+class ApiLogger extends Interceptor {
+  ApiLogger({
+    this.showRequest = false,
+    this.request = false,
+    this.requestHeader = false,
+    this.requestBody = false,
+    this.responseHeader = false,
+    this.responseBody = false,
+    this.error = true,
+  });
+
+  final bool showRequest;
+
+  /// Print request [Options]
+  bool request;
+
+  /// Print request header [Options.headers]
+  bool requestHeader;
+
+  /// Print request data [Options.data]
+  bool requestBody;
+
+  /// Print [Response.data] (via [Response.toString] when enabled)
+  bool responseBody;
+
+  /// Print [Response.headers]
+  bool responseHeader;
+
+  /// Print error message
+  bool error;
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    if (showRequest) {
+      _printKV(options.method, options.uri);
+    }
+    if (request) {
+      _printKV(options.method, options.uri);
+      _printKV('method', options.method);
+      _printKV('responseType', options.responseType.toString());
+      _printKV('followRedirects', options.followRedirects);
+      _printKV('connectTimeout', options.connectTimeout);
+      _printKV('sendTimeout', options.sendTimeout);
+      _printKV('receiveTimeout', options.receiveTimeout);
+      _printKV('receiveDataWhenStatusError', options.receiveDataWhenStatusError);
+      _printKV('extra', options.extra);
+    }
+    if (requestHeader) {
+      _println('headers:');
+      options.headers.forEach((String key, dynamic v) => _printKV(' $key', v));
+    }
+    if (requestBody) {
+      _println('data:');
+      _printAll(options.data);
+    }
+
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response<dynamic> response, ResponseInterceptorHandler handler) {
+    _printResponse(response);
+    handler.next(response);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    if (error) {
+      final String method = err.requestOptions.method;
+      _println('$method Dio error:', statusCode: err.response?.statusCode);
+      if (err.response != null) {
+        _printResponse(err.response!);
+      }
+      _println('$err', statusCode: err.response?.statusCode);
+    }
+
+    handler.next(err);
+  }
+
+  void _printResponse(Response<dynamic> response) {
+    final int? statusCode = response.statusCode;
+    final String method = response.requestOptions.method;
+    final String statusText = statusCode?.toString() ?? 'No status';
+    _printKV('$method $statusText', response.requestOptions.uri, statusCode: statusCode);
+    if (responseHeader) {
+      _printKV('statusCode', statusCode, statusCode: statusCode);
+      if (response.isRedirect == true) {
+        _printKV('redirect', response.realUri, statusCode: statusCode);
+      }
+
+      _println('headers:', statusCode: statusCode);
+      response.headers.forEach(
+        (String key, List<String> v) => _printKV(' $key', v.join('\r\n\t'), statusCode: statusCode),
+      );
+    }
+    if (responseBody) {
+      _println('Response Text:', statusCode: statusCode);
+      _printAll(response.toString(), statusCode: statusCode);
+    }
+  }
+
+  void _printKV(String key, Object? v, {int? statusCode}) {
+    _println('$key: $v', statusCode: statusCode);
+  }
+
+  void _println(String value, {int? statusCode}) {
+    final Logger logger = getIt<Logger>();
+    if (statusCode != null) {
+      if (statusCode > 399 && statusCode < 600) {
+        if (statusCode == 401) {
+          logger.logWarning(value);
+        } else {
+          logger.logError(value);
+        }
+      } else {
+        logger.logApiRes(value);
+      }
+    } else {
+      logger.logApiReq(value);
+    }
+  }
+
+  void _printAll(Object? msg, {int? statusCode}) {
+    msg.toString().split('\n').forEach((String x) => _println(x, statusCode: statusCode));
+  }
+}
+{% endraw %}

generators/static/templates/apis/interceptors/auth_interceptor_template.jinja

@@ -0,0 +1,207 @@
+/*
+ * Authentication interceptor for API requests (Potluck-style):
+ * - Guest mode: x-guest-token, clears Authorization
+ * - User mode: Bearer access token, clears x-guest-token
+ * - apikey + x-locale headers
+ * - On 401: refresh via POST to /token?grant_type=refresh_token (Supabase-style), retry once, persist tokens
+ * - Optional [AuthBloc] sign-out when refresh fails (generated only with `create --login`).
+ */
+
+import 'dart:ui';
+
+import 'package:dio/dio.dart';
+import 'package:[[project_name]]/apis/common/constants.dart';
+import 'package:[[project_name]]/injection.dart';
+import 'package:[[project_name]]/storage/storage_repository.dart';
+{% if has_login %}
+import 'package:[[project_name]]/features/auth/application/auth_bloc.dart';
+{% endif %}
+
+/// Queued interceptor: bearer / guest headers + refresh on 401.
+class AuthInterceptor extends QueuedInterceptor {
+  AuthInterceptor(String baseUrl)
+      : dioAuth = Dio()
+          ..options.baseUrl =
+              Constants.authUrl.isNotEmpty ? Constants.authUrl : baseUrl,
+        dio = Dio()..options.baseUrl = baseUrl;
+
+  final Dio dioAuth;
+  final Dio dio;
+
+{% if has_login %}
+  AuthBloc? _getAuthBloc() {
+    try {
+      return getIt<AuthBloc>();
+    } on Object catch (_) {
+      return null;
+    }
+  }
+
+  void _triggerSignOut() {
+    final AuthBloc? authBloc = _getAuthBloc();
+    if (authBloc != null) {
+      authBloc.add(const AuthEvent.signedOut());
+    } else {
+      Future<void>.delayed(const Duration(milliseconds: 100), () {
+        final AuthBloc? retry = _getAuthBloc();
+        retry?.add(const AuthEvent.signedOut());
+      });
+    }
+  }
+{% else %}
+  void _triggerSignOut() {
+    // Auth UI not generated (create without --login). Clear tokens only, or wire your own sign-out.
+  }
+{% endif %}
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
+    final StorageRepository storageRepo = getIt<StorageRepository>();
+    bool isGuest = await storageRepo.isGuestMode();
+    String? guestToken = await storageRepo.getGuestToken();
+
+    if (guestToken != null && guestToken.isNotEmpty && !isGuest) {
+      await storageRepo.saveGuestToken(guestToken);
+      isGuest = true;
+    }
+
+    final bool shouldUseGuestMode = isGuest || (guestToken != null && guestToken.isNotEmpty);
+
+    if (shouldUseGuestMode) {
+      options.headers.remove(Constants.authorizationHeader);
+      if (guestToken != null && guestToken.isNotEmpty) {
+        options.headers['x-guest-token'] = guestToken;
+      }
+    } else {
+      final String? accessToken = await storageRepo.getToken();
+      if (accessToken != null && accessToken.isNotEmpty) {
+        options.headers.remove('x-guest-token');
+        options.headers[Constants.authorizationHeader] = 'Bearer $accessToken';
+      } else {
+        options.headers.remove(Constants.authorizationHeader);
+        guestToken = await storageRepo.getGuestToken();
+        if (guestToken != null && guestToken.isNotEmpty) {
+          options.headers['x-guest-token'] = guestToken;
+        }
+      }
+    }
+
+    if (Constants.apiKey.isNotEmpty) {
+      options.headers[Constants.apiKeyRequestHeader] = Constants.apiKey;
+    }
+
+    final String deviceLocale = PlatformDispatcher.instance.locale.languageCode;
+    final String locale =
+        (deviceLocale == 'it' || deviceLocale == 'en') ? deviceLocale : 'en';
+    options.headers['x-locale'] = locale;
+
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response<dynamic> response, ResponseInterceptorHandler handler) {
+    response.extra = <String, dynamic>{};
+    handler.next(response);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (err.response?.statusCode == 401) {
+      final StorageRepository storage = getIt<StorageRepository>();
+      final bool isGuest = await storage.isGuestMode();
+      if (isGuest) {
+        handler.next(err);
+        return;
+      }
+
+      try {
+        final String? refreshToken = await storage.getRefreshToken();
+        if (refreshToken == null || refreshToken.isEmpty) {
+          await storage.removeToken();
+          _triggerSignOut();
+          handler.next(err);
+          return;
+        }
+
+        final Response<dynamic> refreshResponse = await dioAuth.post<dynamic>(
+          '/token?grant_type=refresh_token',
+          data: <String, dynamic>{'refresh_token': refreshToken},
+          options: Options(
+            headers: <String, dynamic>{
+              Constants.apiKeyRequestHeader: Constants.apiKey,
+              Constants.contentTypeHeader: 'application/json',
+            },
+          ),
+        );
+
+        final Object? refreshBodyRaw = refreshResponse.data;
+        if (refreshBodyRaw is! Map<dynamic, dynamic>) {
+          await storage.removeToken();
+          _triggerSignOut();
+          handler.next(err);
+          return;
+        }
+        final Map<String, dynamic> refreshBody =
+            Map<String, dynamic>.from(refreshBodyRaw);
+        final String? newToken = refreshBody['access_token'] as String?;
+        final String? newRefresh = refreshBody['refresh_token'] as String?;
+
+        if (newToken == null || newToken.isEmpty) {
+          await storage.removeToken();
+          _triggerSignOut();
+          handler.next(err);
+          return;
+        }
+
+        final Map<String, dynamic> headers =
+            Map<String, dynamic>.from(err.requestOptions.headers);
+        headers[Constants.authorizationHeader] = 'Bearer $newToken';
+        if (Constants.apiKey.isNotEmpty) {
+          headers[Constants.apiKeyRequestHeader] = Constants.apiKey;
+        }
+        headers[Constants.contentTypeHeader] = 'application/json';
+
+        final String deviceLocale = PlatformDispatcher.instance.locale.languageCode;
+        final String locale =
+            (deviceLocale == 'it' || deviceLocale == 'en') ? deviceLocale : 'en';
+        headers['x-locale'] = locale;
+
+        final Options options = Options(
+          method: err.requestOptions.method,
+          headers: headers,
+        );
+
+        final Response<dynamic> retryResponse = await dio.request<dynamic>(
+          err.requestOptions.path,
+          data: err.requestOptions.data,
+          queryParameters: err.requestOptions.queryParameters,
+          options: options,
+        );
+
+        if (retryResponse.statusCode != 401) {
+          await storage.saveToken(
+            TokenData(
+              token: newToken,
+              refreshToken: (newRefresh != null && newRefresh.isNotEmpty)
+                  ? newRefresh
+                  : refreshToken,
+            ),
+          );
+          handler.resolve(retryResponse);
+          return;
+        }
+
+        await storage.removeToken();
+        _triggerSignOut();
+        handler.reject(err);
+        return;
+      } on Object catch (_) {
+        await storage.removeToken();
+        _triggerSignOut();
+        handler.next(err);
+        return;
+      }
+    }
+    handler.next(err);
+  }
+}

generators/static/templates/auth/application/auth_bloc_template.jinja

@@ -0,0 +1,36 @@
+import 'package:bloc/bloc.dart';
+import 'package:freezed_annotation/freezed_annotation.dart';
+import 'package:[[project_name]]/domain/auth/model/user.dart';
+import 'package:[[project_name]]/domain/auth/model/i_auth_facade.dart';
+import 'package:dartz/dartz.dart';
+
+part 'auth_event.dart';
+part 'auth_state.dart';
+
+part 'auth_bloc.freezed.dart';
+
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  final IAuthFacade _authFacade;
+
+  AuthBloc(this._authFacade) : super(const AuthState.initial()) {
+    on<AuthCheckRequested>(_onAuthCheckRequested);
+    on<SignedOut>(_onSignedOut);
+  }
+
+  Future<void> _onAuthCheckRequested(AuthCheckRequested event, Emitter<AuthState> emit) async {
+    final Option<User> userOption = await _authFacade.getSignedInUser();
+    userOption.fold(
+      () {
+        emit(const AuthState.unauthenticated());
+      },
+      (User user) {
+        emit(AuthState.authenticated(user));
+      },
+    );
+  }
+
+  Future<void> _onSignedOut(SignedOut event, Emitter<AuthState> emit) async {
+    await _authFacade.signOut();
+    emit(const AuthState.unauthenticated());
+  }
+}

generators/static/templates/auth/application/auth_event_template.jinja

@@ -0,0 +1,7 @@
+part of 'auth_bloc.dart';
+
+@freezed
+abstract class AuthEvent with _$AuthEvent {
+  const factory AuthEvent.authCheckRequested() = AuthCheckRequested;
+  const factory AuthEvent.signedOut() = SignedOut;
+}

generators/static/templates/auth/application/auth_state_template.jinja

@@ -0,0 +1,8 @@
+part of 'auth_bloc.dart';
+
+@freezed
+abstract class AuthState with _$AuthState {
+  const factory AuthState.initial() = Initial;
+  const factory AuthState.authenticated(User user) = Authenticated;
+  const factory AuthState.unauthenticated() = Unauthenticated;
+}

generators/static/templates/auth/infrastructure/auth_facade_module_template.jinja

@@ -0,0 +1,16 @@
+import 'package:injectable/injectable.dart';
+import 'package:[[project_name]]/apis/common/data_source_config.dart';
+import 'package:[[project_name]]/domain/auth/infrastructure/auth_facade.dart';
+import 'package:[[project_name]]/domain/auth/infrastructure/mock_auth_facade.dart';
+import 'package:[[project_name]]/domain/auth/model/i_auth_facade.dart';
+
+@module
+abstract class AuthFacadeModule {
+  @lazySingleton
+  IAuthFacade authFacade(AuthFacade remote, MockAuthFacade mock) {
+    if (DataSourceConfig.useMock('auth')) {
+      return mock;
+    }
+    return remote;
+  }
+}