maxsim-flutter 1.0.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "maxsim-flutter",
+  "version": "1.0.0",
+  "description": "AI-powered Flutter app scaffolding with Clean Architecture, Riverpod, and autonomous development via Ralph",
+  "type": "module",
+  "bin": {
+    "maxsim-flutter": "./dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/",
+    "templates/",
+    "claude-plugin/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "validate:pack": "node scripts/validate-pack.mjs",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "execa": "^9.5.2",
+    "fs-extra": "^11.2.0",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "ora": "^8.1.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "conventional-changelog-cli": "^5.0.0",
+    "eslint": "^9.17.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.4.2",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.56.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "flutter",
+    "scaffold",
+    "cli",
+    "clean-architecture",
+    "riverpod",
+    "claude",
+    "ai",
+    "ralph"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maystudios/maxsim-flutter.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/core/analysis_options.yaml.hbs

@@ -0,0 +1,21 @@
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+  errors:
+    missing_required_param: error
+    missing_return: error
+
+linter:
+  rules:
+    - always_declare_return_types
+    - avoid_print
+    - prefer_const_constructors
+    - prefer_const_declarations
+    - prefer_final_fields
+    - prefer_single_quotes
+    - sort_child_properties_last
+    - use_super_parameters

package/templates/core/lib/app.dart.hbs

@@ -0,0 +1,20 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'core/router/app_router.dart';
+
+class App extends ConsumerWidget {
+  const App({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final router = ref.watch(routerProvider);
+    return MaterialApp.router(
+      title: '{{project.name}}',
+      theme: ThemeData(
+        colorSchemeSeed: Colors.blue,
+        useMaterial3: true,
+      ),
+      routerConfig: router,
+    );
+  }
+}

package/templates/core/lib/core/providers/app_providers.dart.hbs

@@ -0,0 +1,3 @@
+// Barrel file for shared application providers.
+// Export providers here to make them accessible across the app.
+export '../router/app_router.dart';

package/templates/core/lib/core/router/app_router.dart.hbs

@@ -0,0 +1,19 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../features/home/presentation/pages/home_page.dart';
+
+part 'app_router.g.dart';
+
+@riverpod
+GoRouter router(Ref ref) {
+  return GoRouter(
+    initialLocation: '/',
+    routes: [
+      GoRoute(
+        path: '/',
+        builder: (context, state) => const HomePage(),
+      ),
+    ],
+  );
+}

package/templates/core/lib/core/theme/app_theme.dart.hbs

@@ -0,0 +1,15 @@
+import 'package:flutter/material.dart';
+
+abstract final class AppTheme {
+  static ThemeData get light => ThemeData(
+    colorSchemeSeed: Colors.blue,
+    useMaterial3: true,
+    brightness: Brightness.light,
+  );
+
+  static ThemeData get dark => ThemeData(
+    colorSchemeSeed: Colors.blue,
+    useMaterial3: true,
+    brightness: Brightness.dark,
+  );
+}

package/templates/core/lib/features/home/presentation/pages/home_page.dart.hbs

@@ -0,0 +1,18 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+class HomePage extends ConsumerWidget {
+  const HomePage({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('{{project.name}}'),
+      ),
+      body: const Center(
+        child: Text('Welcome to {{project.name}}!'),
+      ),
+    );
+  }
+}

package/templates/core/lib/main.dart.hbs

@@ -0,0 +1,11 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'app.dart';
+
+void main() {
+  runApp(
+    const ProviderScope(
+      child: App(),
+    ),
+  );
+}

package/templates/core/pubspec.yaml.hbs

@@ -0,0 +1,30 @@
+name: {{project.name}}
+description: {{project.description}}
+publish_to: 'none'
+version: 1.0.0+1
+
+environment:
+  sdk: ^3.5.0
+  flutter: ^3.24.0
+
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_riverpod: ^2.6.1
+  riverpod_annotation: ^2.6.1
+  go_router: ^14.6.2
+  freezed_annotation: ^2.4.4
+  json_annotation: ^4.9.0
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  flutter_lints: ^5.0.0
+  build_runner: ^2.4.13
+  riverpod_generator: ^2.6.3
+  go_router_builder: ^2.7.1
+  freezed: ^2.5.7
+  json_serializable: ^6.8.0
+
+flutter:
+  uses-material-design: true

package/templates/core/test/widget_test.dart.hbs

@@ -0,0 +1,16 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:{{project.name}}/app.dart';
+
+void main() {
+  testWidgets('App renders without errors', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const ProviderScope(
+        child: App(),
+      ),
+    );
+
+    expect(find.byType(MaterialApp), findsOneWidget);
+  });
+}

package/templates/modules/analytics/lib/features/analytics/data/observers/analytics_route_observer.dart.hbs

@@ -0,0 +1,53 @@
+import 'package:flutter/widgets.dart';
+import 'package:go_router/go_router.dart';
+import '../../domain/services/analytics_service.dart';
+
+/// A [NavigatorObserver] that automatically logs screen views to analytics
+/// whenever the user navigates to a new route via go_router.
+class AnalyticsRouteObserver extends NavigatorObserver {
+  final AnalyticsService _analytics;
+
+  AnalyticsRouteObserver(this._analytics);
+
+  String? _extractRouteName(Route<dynamic>? route) {
+    if (route == null) return null;
+    final settings = route.settings;
+    return settings.name;
+  }
+
+  @override
+  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
+    super.didPush(route, previousRoute);
+    final name = _extractRouteName(route);
+    if (name != null) {
+      _analytics.logScreenView(
+        screenName: name,
+        screenClass: route.runtimeType.toString(),
+      );
+    }
+  }
+
+  @override
+  void didReplace({Route<dynamic>? newRoute, Route<dynamic>? oldRoute}) {
+    super.didReplace(newRoute: newRoute, oldRoute: oldRoute);
+    final name = _extractRouteName(newRoute);
+    if (name != null) {
+      _analytics.logScreenView(
+        screenName: name,
+        screenClass: newRoute?.runtimeType.toString(),
+      );
+    }
+  }
+
+  @override
+  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) {
+    super.didPop(route, previousRoute);
+    final name = _extractRouteName(previousRoute);
+    if (name != null) {
+      _analytics.logScreenView(
+        screenName: name,
+        screenClass: previousRoute?.runtimeType.toString(),
+      );
+    }
+  }
+}

package/templates/modules/analytics/lib/features/analytics/data/services/firebase_analytics_service.dart.hbs

@@ -0,0 +1,39 @@
+import 'package:firebase_analytics/firebase_analytics.dart';
+import '../../domain/services/analytics_service.dart';
+
+class FirebaseAnalyticsService implements AnalyticsService {
+  final FirebaseAnalytics _analytics;
+
+  FirebaseAnalyticsService({FirebaseAnalytics? analytics})
+      : _analytics = analytics ?? FirebaseAnalytics.instance;
+
+  @override
+  Future<void> logScreenView({
+    required String screenName,
+    String? screenClass,
+  }) =>
+      _analytics.logScreenView(
+        screenName: screenName,
+        screenClass: screenClass,
+      );
+
+  @override
+  Future<void> logEvent({
+    required String name,
+    Map<String, Object>? parameters,
+  }) =>
+      _analytics.logEvent(name: name, parameters: parameters);
+
+  @override
+  Future<void> setUserProperty({
+    required String name,
+    required String? value,
+  }) =>
+      _analytics.setUserProperty(name: name, value: value);
+
+  @override
+  Future<void> setUserId(String? id) => _analytics.setUserId(id: id);
+
+  @override
+  Future<void> resetAnalyticsData() => _analytics.resetAnalyticsData();
+}

package/templates/modules/analytics/lib/features/analytics/domain/services/analytics_service.dart.hbs

@@ -0,0 +1,25 @@
+abstract class AnalyticsService {
+  /// Log a screen view event.
+  Future<void> logScreenView({
+    required String screenName,
+    String? screenClass,
+  });
+
+  /// Log a custom event with optional parameters.
+  Future<void> logEvent({
+    required String name,
+    Map<String, Object>? parameters,
+  });
+
+  /// Set a user property.
+  Future<void> setUserProperty({
+    required String name,
+    required String? value,
+  });
+
+  /// Set the current user ID (e.g. after login).
+  Future<void> setUserId(String? id);
+
+  /// Reset analytics data (e.g. after logout).
+  Future<void> resetAnalyticsData();
+}

package/templates/modules/analytics/lib/features/analytics/presentation/providers/analytics_provider.dart.hbs

@@ -0,0 +1,17 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../data/services/firebase_analytics_service.dart';
+import '../../data/observers/analytics_route_observer.dart';
+import '../../domain/services/analytics_service.dart';
+
+part 'analytics_provider.g.dart';
+
+@riverpod
+AnalyticsService analyticsService(Ref ref) {
+  return FirebaseAnalyticsService();
+}
+
+@riverpod
+AnalyticsRouteObserver analyticsRouteObserver(Ref ref) {
+  return AnalyticsRouteObserver(ref.watch(analyticsServiceProvider));
+}

package/templates/modules/analytics/pubspec.partial.yaml

@@ -0,0 +1,2 @@
+dependencies:
+  firebase_analytics: ^11.3.6

package/templates/modules/api/lib/features/api/data/datasources/api_client.dart.hbs

@@ -0,0 +1,171 @@
+import 'package:dio/dio.dart';
+import '../../domain/exceptions/api_exception.dart';
+
+/// Central API client built on Dio.
+///
+/// Provides a pre-configured [Dio] instance with:
+/// - Base URL from project configuration
+/// - Request/response logging interceptor
+/// - Error-mapping interceptor that converts [DioException] to [ApiException]
+/// - Configurable request timeout
+class ApiClient {
+  final Dio dio;
+
+  ApiClient({Dio? dio}) : dio = dio ?? _createDio();
+
+  static Dio _createDio() {
+    final dio = Dio(
+      BaseOptions(
+        baseUrl: const String.fromEnvironment(
+          'API_BASE_URL',
+          defaultValue: '{{#if modules.api.baseUrl}}{{{modules.api.baseUrl}}}{{else}}https://api.example.com{{/if}}',
+        ),
+        connectTimeout: const Duration(seconds: 15),
+        receiveTimeout: const Duration(seconds: 15),
+        sendTimeout: const Duration(seconds: 15),
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+        },
+      ),
+    );
+
+    dio.interceptors.addAll([
+      _LoggingInterceptor(),
+      _ErrorInterceptor(),
+    ]);
+
+    return dio;
+  }
+
+  /// Perform a GET request.
+  Future<Response<T>> get<T>(
+    String path, {
+    Map<String, dynamic>? queryParameters,
+    Options? options,
+  }) {
+    return dio.get<T>(path, queryParameters: queryParameters, options: options);
+  }
+
+  /// Perform a POST request.
+  Future<Response<T>> post<T>(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    Options? options,
+  }) {
+    return dio.post<T>(path, data: data, queryParameters: queryParameters, options: options);
+  }
+
+  /// Perform a PUT request.
+  Future<Response<T>> put<T>(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    Options? options,
+  }) {
+    return dio.put<T>(path, data: data, queryParameters: queryParameters, options: options);
+  }
+
+  /// Perform a PATCH request.
+  Future<Response<T>> patch<T>(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    Options? options,
+  }) {
+    return dio.patch<T>(path, data: data, queryParameters: queryParameters, options: options);
+  }
+
+  /// Perform a DELETE request.
+  Future<Response<T>> delete<T>(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    Options? options,
+  }) {
+    return dio.delete<T>(path, data: data, queryParameters: queryParameters, options: options);
+  }
+}
+
+/// Interceptor that logs request and response details in debug mode.
+class _LoggingInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    assert(() {
+      // ignore: avoid_print
+      print('[API] ${options.method} ${options.uri}');
+      return true;
+    }());
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    assert(() {
+      // ignore: avoid_print
+      print('[API] ${response.statusCode} ${response.requestOptions.uri}');
+      return true;
+    }());
+    handler.next(response);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    assert(() {
+      // ignore: avoid_print
+      print('[API] ERROR ${err.type}: ${err.message}');
+      return true;
+    }());
+    handler.next(err);
+  }
+}
+
+/// Interceptor that maps [DioException] to typed [ApiException].
+class _ErrorInterceptor extends Interceptor {
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    final apiException = _mapDioException(err);
+    handler.reject(
+      DioException(
+        requestOptions: err.requestOptions,
+        response: err.response,
+        type: err.type,
+        error: apiException,
+      ),
+    );
+  }
+
+  ApiException _mapDioException(DioException err) {
+    switch (err.type) {
+      case DioExceptionType.connectionTimeout:
+      case DioExceptionType.sendTimeout:
+      case DioExceptionType.receiveTimeout:
+        return ApiException(
+          message: 'Request timed out. Please try again.',
+        );
+      case DioExceptionType.badResponse:
+        return ApiException(
+          statusCode: err.response?.statusCode,
+          message: _extractMessage(err.response),
+          data: err.response?.data,
+        );
+      case DioExceptionType.cancel:
+        return const ApiException(message: 'Request was cancelled.');
+      case DioExceptionType.connectionError:
+        return const ApiException(
+          message: 'No internet connection. Please check your network.',
+        );
+      default:
+        return ApiException(message: err.message ?? 'An unexpected error occurred.');
+    }
+  }
+
+  String _extractMessage(Response? response) {
+    if (response?.data is Map) {
+      final data = response!.data as Map;
+      return (data['message'] ?? data['error'] ?? 'Request failed').toString();
+    }
+    return 'Request failed with status ${response?.statusCode}';
+  }
+}

package/templates/modules/api/lib/features/api/data/interceptors/auth_interceptor.dart.hbs

@@ -0,0 +1,25 @@
+import 'package:dio/dio.dart';
+
+/// Interceptor that attaches authentication tokens to requests.
+///
+/// Override [getToken] with your token retrieval logic
+/// (e.g., reading from secure storage or a Riverpod provider).
+class AuthInterceptor extends Interceptor {
+  /// Override this to return the current auth token.
+  Future<String?> getToken() async {
+    // TODO: Implement token retrieval from your auth/storage solution.
+    return null;
+  }
+
+  @override
+  void onRequest(
+    RequestOptions options,
+    RequestInterceptorHandler handler,
+  ) async {
+    final token = await getToken();
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    handler.next(options);
+  }
+}

package/templates/modules/api/lib/features/api/data/interceptors/retry_interceptor.dart.hbs

@@ -0,0 +1,42 @@
+import 'package:dio/dio.dart';
+
+/// Interceptor that retries failed requests with exponential backoff.
+///
+/// Retries on connection errors and 5xx server errors up to [maxRetries] times.
+class RetryInterceptor extends Interceptor {
+  final Dio dio;
+  final int maxRetries;
+
+  RetryInterceptor({
+    required this.dio,
+    this.maxRetries = 3,
+  });
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (_shouldRetry(err)) {
+      final retryCount = (err.requestOptions.extra['retryCount'] as int?) ?? 0;
+      if (retryCount < maxRetries) {
+        final delay = Duration(milliseconds: 200 * (retryCount + 1));
+        await Future<void>.delayed(delay);
+
+        err.requestOptions.extra['retryCount'] = retryCount + 1;
+        try {
+          final response = await dio.fetch(err.requestOptions);
+          handler.resolve(response);
+          return;
+        } on DioException catch (e) {
+          handler.reject(e);
+          return;
+        }
+      }
+    }
+    handler.next(err);
+  }
+
+  bool _shouldRetry(DioException err) {
+    return err.type == DioExceptionType.connectionError ||
+        err.type == DioExceptionType.connectionTimeout ||
+        (err.response?.statusCode != null && err.response!.statusCode! >= 500);
+  }
+}

package/templates/modules/api/lib/features/api/data/repositories/api_repository_impl.dart.hbs

@@ -0,0 +1,21 @@
+import '../../domain/exceptions/api_exception.dart';
+import '../../domain/repositories/api_repository.dart';
+import '../datasources/api_client.dart';
+
+class ApiRepositoryImpl implements ApiRepository {
+  final ApiClient _client;
+
+  const ApiRepositoryImpl(this._client);
+
+  @override
+  Future<bool> healthCheck() async {
+    try {
+      final response = await _client.get<dynamic>('/health');
+      return response.statusCode == 200;
+    } on ApiException {
+      return false;
+    } catch (_) {
+      return false;
+    }
+  }
+}