create-flutterinit 0.1.0

package/bin/index.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import { main } from '../src/main'
+main()

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "create-flutterinit",
+  "version": "0.1.0",
+  "description": "Scaffold production-ready Flutter projects from your terminal",
+  "bin": {
+    "create-flutterinit": "./bin/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run bin/index.ts",
+    "test": "bun test",
+    "build": "bun build ./bin/index.ts --outdir ./dist --target node",
+    "sync-templates": "bash ../scripts/sync-templates.sh"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "bin/"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "handlebars": "latest",
+    "picocolors": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/handlebars": "latest",
+    "typescript": "latest"
+  },
+  "keywords": [
+    "flutter",
+    "scaffold",
+    "cli",
+    "boilerplate",
+    "clean-architecture",
+    "riverpod",
+    "bloc",
+    "flutterinit"
+  ],
+  "author": "Arjun Mahar <https://github.com/Arjun544>",
+  "license": "MIT",
+  "homepage": "https://flutterinit.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Arjun544/flutter_init"
+  }
+}

package/templates/base/.cursor/rules/flutter-project.mdc.hbs

@@ -0,0 +1,132 @@
+---
+description: {{appName}} — FlutterInit stack, architecture, design conventions, and agent zones
+alwaysApply: true
+---
+
+# {{appName}} — Cursor project context
+
+{{#if description}}{{description}}{{/if}}
+
+Generated by FlutterInit. Package: `{{packageId}}`.
+
+**Extended docs (read when changing setup or deep UI):**
+
+- **[AGENTS.md](AGENTS.md)** — full agent guide (duplicate of sections below + packages list)
+- **[DESIGN.md](DESIGN.md)** — complete design system
+- **[SETUP.md](SETUP.md)** — env, Firebase/Supabase/Appwrite, native config, permissions
+
+---
+
+{{> llm/stack-summary}}
+
+---
+
+{{> llm/architecture-rules}}
+
+---
+
+{{> llm/state-management-rules}}
+
+---
+
+{{> llm/navigation-rules}}
+
+---
+
+{{#unless (eq backend.provider "none")}}
+{{> llm/backend-rules}}
+
+---
+{{/unless}}
+
+{{> llm/networking-rules}}
+
+---
+
+{{> llm/services-conventions}}
+
+---
+
+{{> llm/design-quick-reference}}
+
+---
+
+{{> llm/add-feature-workflow}}
+
+---
+
+## File zones
+
+### Safe to modify
+
+| Path | Guidance |
+|------|----------|
+{{#if (or (eq architecture "clean") (eq architecture "feature-first"))}}| `lib/src/features/**` | Feature screens, widgets, domain/data/presentation |{{/if}}
+{{#if (eq architecture "mvc")}}| `lib/src/views/**`, `lib/src/controllers/**` | UI and controllers |{{/if}}
+{{#if (eq architecture "mvvm")}}| `lib/src/ui/**`, `lib/src/data/**` | UI and data for features |{{/if}}
+{{#if (eq architecture "layer-first")}}| `lib/src/presentation/**`, `lib/src/domain/**`, `lib/src/data/**` | Layer slices |{{/if}}
+| `lib/src/shared/widgets/**` | Shared UI components |
+| `test/**` | Tests |
+
+### Modify with caution
+
+| Path | Why |
+|------|-----|
+| `lib/src/routing/app_router.dart` | All navigation |
+| `lib/main.dart` | Init order (SDKs, dotenv, l10n) |
+| `lib/src/config/app_config.dart` | Dio / SDK clients |
+| `lib/src/theme/**` | Global design tokens |
+| `lib/src/imports/**` | Barrel exports |
+| `pubspec.yaml` | Dependencies |
+{{#if flags.usesDotenv}}| `.env` | Secrets |{{/if}}
+
+### Do not touch
+
+| Path | Why |
+|------|-----|
+| `android/`, `ios/`, `web/`, desktop native trees | Platform config |
+{{#if flags.usesDotenv}}| `.env` with production secrets | Security |{{/if}}
+{{#if flags.usesFirebase}}| `google-services.json`, `GoogleService-Info.plist` | Firebase credentials |{{/if}}
+
+---
+
+{{> llm/packages-list}}
+
+---
+
+## Quick rules (always enforce)
+
+- Import: `package:{{flags.appSlug}}/src/imports/imports.dart`
+- Services: `ClassName.instance` + `runTask()` → `FutureEither<T>`; use `rootContext`, not `BuildContext` in services
+- UI: `context.colors`, `context.textTheme`, `AppSpacing`, `AppBorders` — no hardcoded hex or magic padding
+- Routes: only `lib/src/routing/app_router.dart`
+- Network/backend: `lib/src/services/` + `app_config.dart` — never from widgets
+- No second state-management or routing library
+- No business logic in `build()`; no empty `catch` blocks
+{{#if flags.isRiverpod}}- Riverpod: `ref.watch` in build only; `ref.read` in callbacks; no `@riverpod` codegen{{/if}}
+{{#if flags.isBloc}}- Bloc: immutable state/events; delegate logic out of handlers{{/if}}
+{{#if flags.isProvider}}- Provider: `watch` in build, `read` in callbacks{{/if}}
+{{#if flags.isGetX}}- GetX: bindings; no GoRouter/AutoRoute mix{{/if}}
+{{#if flags.isMobX}}- MobX: mutate via `@action`; run `build_runner` after store edits{{/if}}
+{{#if flags.supportsLocalization}}- Copy: `easy_localization` + `assets/translations/*.json`{{/if}}
+
+---
+
+## Verify after changes
+
+```bash
+flutter pub get
+flutter analyze
+```
+
+{{> llm/build-runner-note}}
+
+{{#if flags.supportsLocalization}}
+```bash
+flutter pub run easy_localization:generate -S assets/translations -O lib/src/core/i18n -o locale_keys.g.dart
+```
+{{/if}}
+
+```bash
+flutter test
+```

package/templates/base/AGENTS.md.hbs

@@ -0,0 +1,137 @@
+# Agent guide — {{appName}}
+
+{{> llm/stack-summary}}
+
+---
+
+{{> llm/architecture-rules}}
+
+---
+
+{{> llm/state-management-rules}}
+
+---
+
+{{> llm/navigation-rules}}
+
+---
+
+{{#unless (eq backend.provider "none")}}
+{{> llm/backend-rules}}
+
+---
+{{/unless}}
+
+{{> llm/networking-rules}}
+
+---
+
+{{> llm/services-conventions}}
+
+---
+
+{{> llm/packages-list}}
+
+---
+
+{{> llm/add-feature-workflow}}
+
+---
+
+## Safe to modify
+
+| Path | Guidance |
+|------|----------|
+{{#if (or (eq architecture "clean") (eq architecture "feature-first"))}}| `lib/src/features/**` | Feature screens, widgets, domain/data/presentation code |{{/if}}
+{{#if (eq architecture "mvc")}}| `lib/src/views/**`, `lib/src/controllers/**` | UI and controllers for your features |{{/if}}
+{{#if (eq architecture "mvvm")}}| `lib/src/ui/**`, `lib/src/data/**` | UI and data layer for your features |{{/if}}
+{{#if (eq architecture "layer-first")}}| `lib/src/presentation/**`, `lib/src/domain/**`, `lib/src/data/**` | Layer slices for new behavior |{{/if}}
+| `lib/src/shared/widgets/**` | Reusable UI components |
+| `lib/src/shared/helpers/**` | App-wide helpers (when not generated-only) |
+| `test/**` | Unit and widget tests |
+| `README.md` | Project documentation |
+
+## Modify with caution
+
+| Path | Why |
+|------|-----|
+| `lib/src/routing/app_router.dart` | Central navigation — breaks deep links if wrong |
+| `lib/main.dart` | Initialization order (Firebase, dotenv, localization, flavors) |
+| `lib/src/config/app_config.dart` | SDK and HTTP client setup |
+| `lib/src/theme/**` | Global visual system |
+| `lib/src/imports/**` | Barrel exports — keep pattern consistent |
+| `pubspec.yaml` | Dependency graph for the whole app |
+{{#if flags.usesDotenv}}| `.env` | Secrets — never commit real values |{{/if}}
+
+## Do not touch
+
+| Path | Why |
+|------|-----|
+| `android/`, `ios/`, `web/`, desktop folders | Native project configuration |
+{{#if flags.usesDotenv}}| `.env` with real secrets | Security |{{/if}}
+{{#if flags.usesFirebase}}| `google-services.json`, `GoogleService-Info.plist` | Environment-specific credentials |{{/if}}
+
+---
+
+## Verification after changes
+
+```bash
+flutter pub get
+flutter analyze
+```
+
+{{> llm/build-runner-note}}
+
+{{#if flags.supportsLocalization}}
+### Localization
+
+After editing `assets/translations/*.json`:
+
+```bash
+flutter pub run easy_localization:generate -S assets/translations -O lib/src/core/i18n -o locale_keys.g.dart
+```
+{{/if}}
+
+```bash
+flutter test
+```
+
+---
+
+{{#if flags.usesPermissionHandler}}
+## Native Permissions
+
+This project uses `permission_handler` to manage runtime permissions.
+
+Configured permissions:
+{{#if flags.usesCamera}}- Camera and photo library (Android + iOS){{/if}}
+{{#if flags.usesImagePicker}}- Image picker (camera + gallery access){{/if}}
+{{#if flags.usesFilePicker}}- File system / document picker{{/if}}
+{{#if flags.usesGeolocator}}- Location (fine + coarse on Android, WhenInUse + Always on iOS){{/if}}
+{{#if flags.usesNotifications}}- Local notifications (POST_NOTIFICATIONS on Android 13+){{/if}}
+
+### Permission Request Pattern
+
+Always check permission status before requesting:
+
+```dart
+final status = await Permission.camera.status;
+if (status.isDenied) {
+  await Permission.camera.request();
+}
+```
+
+Never request permissions on app launch. Request contextually — when the
+user triggers the feature that needs the permission.
+
+---
+
+{{/if}}
+## Hard limits
+
+- Do not disable `flutter_lints` rules without an explanatory comment.
+- Do not call backend or networking code directly from widgets.
+- Do not commit `.env` files containing production secrets.
+- Do not introduce a second state-management or routing library.
+- For platform setup and API keys, use **[SETUP.md](SETUP.md)**.
+- For UI tokens and spacing, use **[DESIGN.md](DESIGN.md)**.

package/templates/base/DESIGN.md.hbs

@@ -0,0 +1,149 @@
+# Design system — {{appName}}
+
+This file documents the design conventions established at generation time. Consult it before changing UI code.
+
+---
+
+## Theme overview
+
+- **Preset:** `{{theme.preset}}`{{#if flags.isCupertino}} (Cupertino-style widgets where applicable){{/if}}
+- **Material 3:** {{#unless flags.isCupertino}}Primary app chrome uses Material 3 theming in `lib/src/theme/theme.dart`.{{else}}Cupertino preset — still uses shared tokens from `lib/src/theme/`.{{/unless}}
+- **Dark mode:** {{#if flags.hasDarkMode}}Light and dark themes are supported{{#if theme.darkMode.system}}; app can follow system brightness{{/if}}. Use semantic colors — do not branch on brightness in widgets for basic surfaces.{{else}}Light mode only — avoid hardcoded colors that will not adapt if dark mode is added later.{{/if}}
+- **Customization:** Global `ThemeData` lives in `lib/src/theme/theme.dart` — avoid one-off `ThemeData` overrides in feature widgets.
+
+{{#if theme.primaryColor}}
+- **Seed color:** `{{theme.primaryColor}}` (used to derive `ColorScheme` via `ColorScheme.fromSeed` where applicable).
+{{/if}}
+
+---
+
+## Color system
+
+- Use `context.colors` (`ColorScheme`) for standard Material roles: `primary`, `onPrimary`, `secondary`, `surface`, `onSurface`, `error`, etc.
+- Use `context.appColors` for semantic extensions: `success`, `warning`, `info`, and their `on*` / container variants (see `lib/src/theme/color_schemes.dart`).
+- Definitions: `lib/src/theme/color_schemes.dart`, applied through `lib/src/theme/theme.dart`.
+- **Do not** hardcode hex colors in widgets — use theme roles or `appColors`.
+
+---
+
+## Typography
+
+- Use `context.textTheme` (alias `context.typography`) for all text styles.
+- Roles follow Material 3: `display*`, `headline*`, `title*`, `body*`, `label*`.
+{{#if flags.hasCustomFonts}}
+### Custom fonts
+
+Primary family: **{{flags.primaryFontFamily}}**
+
+{{#each flags.fontFamilies}}
+- **{{family}}** — {{fonts.length}} file(s) configured in `pubspec.yaml`{{#if @first}} (app-wide `fontFamily` when primary){{/if}}
+{{/each}}
+
+Do not set raw `fontFamily:` strings in widgets — use `textTheme` roles or theme configuration in `lib/src/theme/text_theme.dart`.
+{{else}}
+- No custom fonts uploaded — platform default typography (Roboto / SF Pro) via Material/Cupertino theme.
+{{/if}}
+
+---
+
+## Spacing, borders, motion
+
+Import tokens via `package:{{flags.appSlug}}/src/theme/theme_constants.dart`.
+
+| Token class | Purpose |
+|-------------|---------|
+| `AppSpacing` | Padding, gaps (`xxs` … `xxxl`, plus `pagePadding`, `itemGap`, `cardPadding`) |
+| `AppBorders` | Border radii (`xs` … `xl`, `button`, `card`, `input`, `dialog`, …) |
+| `AppShadows` | Elevation shadows (`none`, `subtle`, `card`, `elevated`, `modal`) |
+| `AppDurations` | Animation durations (`fast`, `normal`, `medium`, `slow`, …) |
+| `AppCurves` | Standard curves (`standard`, `emphasized`, `pageEnter`, …) |
+
+**Rules**
+
+- Do not use magic numbers for padding — use `AppSpacing`.
+- Do not use inline `BorderRadius.circular(n)` — use `AppBorders`.
+- Prefer Material 3 tonal elevation on `Card` / `Surface` — custom shadows only via `AppShadows`.
+
+{{#if flags.usesScreenutil}}
+---
+
+## Responsive scaling (ScreenUtil)
+
+- `ScreenUtilInit` is already applied in the app wrapper — do not add another.
+- Design size baseline: **390×844** (iPhone 14 class).
+- In templates and new code, use the `res` convention: widths `.w`, heights `.h`, radius `.r`, font sizes `.sp` when ScreenUtil is enabled.
+- ScreenUtil values are runtime — avoid `const` widgets that depend on `.w` / `.sp`.
+{{else}}
+---
+
+## Responsive layout (no ScreenUtil)
+
+- Use `MediaQuery`, `LayoutBuilder`, `Flexible`, and `Expanded` for responsiveness.
+- Fixed pixel sizes are acceptable only for elements that should not scale (e.g. icon touch targets defined by tokens).
+{{/if}}
+
+---
+
+## Context extensions
+
+Defined in `lib/src/extensions/context_extension.dart`:
+
+| Member | Use |
+|--------|-----|
+| `context.colors` | `ColorScheme` |
+| `context.textTheme` / `context.typography` | Text styles |
+| `context.appColors` | Semantic success/warning/info |
+| `context.designTokens` | Theme extension tokens |
+| `context.isDarkMode` | Brightness check |
+| `context.width` / `context.height` | Screen size |
+| `context.showAppDialog` | Dialog helper |
+| `context.showTypedSnackBar` | Status snackbars |
+
+Prefer these shortcuts over repeating `Theme.of(context)` in widgets.
+
+---
+
+## Component conventions
+
+- Reusable widgets belong in `lib/src/shared/widgets/`.
+- Default style parameters to theme values, not hardcoded colors.
+- Widget file names match the widget class (`primary_button.dart` → `PrimaryButton`).
+- Do not read theme inside `const` constructors.
+
+{{#if flags.hasDarkMode}}
+### Dark mode checklist
+
+- No raw `Colors.white` / `Colors.black` for surfaces — use `colorScheme` roles.
+- Verify new screens in both light and dark theme.
+{{/if}}
+
+{{#if flags.supportsLocalization}}
+---
+
+## Localization
+
+- User-visible strings use `easy_localization` — files in `assets/translations/`.
+- Do not hardcode display strings in widgets.
+- Add keys to JSON translation files, then run the generate command in **SETUP.md**.
+- Use interpolation in JSON — do not concatenate translated strings in Dart.
+{{/if}}
+
+---
+
+## Do / Don't
+
+**Do**
+
+- `context.colors` / `context.appColors` for color
+- `context.textTheme` for typography
+- `AppSpacing`, `AppBorders`, `AppShadows`, `AppDurations`, `AppCurves` for layout and motion
+- `showAppDialog` and shared widgets for consistent UX
+
+**Don't**
+
+- Hardcode hex colors or arbitrary font families in widgets
+- Magic padding/radius numbers
+- Duplicate theme definitions per screen
+- Bypass design tokens for one-off “quick” UI
+
+For agent workflows and architecture boundaries, see **[AGENTS.md](AGENTS.md)**.

package/templates/base/README.md.hbs

@@ -0,0 +1,19 @@
+# {{appName}}
+
+Generated with the Flutter Scaffolding Wizard.
+
+## What's inside
+- Opinionated theme with Material 3
+- Onboarding presentation starter
+- Routing scaffold {{#if flags.routerPackage}}using `{{flags.routerPackage}}`{{else}}with `MaterialApp` routes{{/if}}
+- {{> state_label}}
+- Backend: {{backend.provider}}
+
+## Getting started
+```bash
+flutter pub get
+{{#if (or flags.usesJsonSerializable (or flags.isMobX (eq flags.routerPackage "auto_route")))}}
+flutter pub run build_runner build --delete-conflicting-outputs
+{{/if}}
+flutter run
+```