Initial commit of the Flutter Cursor Generator project, including the core generator tool, project brief schema, example project setup, and CI configuration. Added README documentation outlining repository structure, quick start guide, and detailed descriptions of features and architecture pillars.
This commit is contained in:
@@ -0,0 +1,171 @@
|
||||
# Flutter Cursor Generator — Complete Implementation
|
||||
|
||||
> AI-powered, project-specific Cursor configuration generator for Flutter teams.
|
||||
> Implements all 6 pillars from the architecture review.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
flutter-cursor-gen/
|
||||
├── flutter-cursor-templates/ ← Shared template repo (hosted internally)
|
||||
│ ├── generator/ ← Dart CLI tool
|
||||
│ │ ├── bin/cursor_gen.dart ← Entry point
|
||||
│ │ ├── src/ ← Core modules
|
||||
│ │ │ ├── brief_loader.dart ← Parses project-brief.yaml
|
||||
│ │ │ ├── resolver.dart ← Maps brief → template files
|
||||
│ │ │ ├── renderer.dart ← Substitutes {{PLACEHOLDERS}}
|
||||
│ │ │ ├── validator.dart ← Schema validation
|
||||
│ │ │ ├── version_manager.dart ← Pillar 1: version locking
|
||||
│ │ │ ├── override_manager.dart ← Pillar 2: custom/ preservation
|
||||
│ │ │ ├── wizard.dart ← Interactive brief creator
|
||||
│ │ │ └── telemetry.dart ← Pillar 6: opt-in analytics
|
||||
│ │ ├── test/
|
||||
│ │ │ ├── generator_test.dart ← Pillar 3: full test suite
|
||||
│ │ │ └── golden/ ← Golden output files per stack combo
|
||||
│ │ ├── brief-schema.json ← IDE autocomplete for project-brief.yaml
|
||||
│ │ └── pubspec.yaml
|
||||
│ ├── templates/
|
||||
│ │ ├── rules/
|
||||
│ │ │ ├── universal/ ← Always included (flutter-core, ui-ux, project-context)
|
||||
│ │ │ ├── security/ ← Pillar 5: always-on security rules
|
||||
│ │ │ ├── error-handling/ ← Always-on error handling
|
||||
│ │ │ ├── state-management/ ← bloc | riverpod | getx | hooks_riverpod
|
||||
│ │ │ ├── architecture/ ← clean | feature_first | mvvm | mvc | layered
|
||||
│ │ │ ├── backend/ ← firebase | supabase | rest | realtime
|
||||
│ │ │ ├── routing/ ← gorouter | getx_nav | auto_route
|
||||
│ │ │ ├── testing/ ← testing-{sm} + testing-e2e-{tool}
|
||||
│ │ │ ├── platform/ ← Pillar 4: ios | android | web | desktop
|
||||
│ │ │ ├── codegen/ ← Pillar 4: freezed | json_serializable | injectable | retrofit
|
||||
│ │ │ └── i18n/ ← localization rules
|
||||
│ │ ├── skills/ ← scaffold-feature | scaffold-screen | generate-tests | ...
|
||||
│ │ ├── agents/ ← code-reviewer | test-writer | ui-validator | migration | security
|
||||
│ │ └── hooks/ ← arch-guard.ts | flutter-analyze.ts | hooks.json
|
||||
│ ├── .github/workflows/
|
||||
│ │ └── template-ci.yml ← Pillar 3: CI for templates
|
||||
│ ├── VERSION
|
||||
│ └── CHANGELOG.md
|
||||
│
|
||||
└── example-project/ ← One reference app: commented project-brief.yaml + custom/ demo
|
||||
├── project-brief.yaml ← All stack options documented in-file
|
||||
└── .cursor/custom/ ← Pillar 2: never overwritten by the generator
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Add to your Flutter project
|
||||
|
||||
```yaml
|
||||
# pubspec.yaml (dev dependency)
|
||||
dev_dependencies:
|
||||
cursor_gen:
|
||||
git:
|
||||
url: https://github.com/company/flutter-cursor-templates
|
||||
path: generator
|
||||
```
|
||||
|
||||
### 2. Create your brief (interactive wizard)
|
||||
|
||||
```bash
|
||||
dart run cursor_gen --wizard
|
||||
```
|
||||
|
||||
Or copy the single reference brief (every option is explained in comments):
|
||||
|
||||
```bash
|
||||
cp path/to/flutter-cursor-gen/example-project/project-brief.yaml .
|
||||
```
|
||||
|
||||
### 3. Generate your .cursor/ directory
|
||||
|
||||
```bash
|
||||
dart run cursor_gen
|
||||
```
|
||||
|
||||
### 4. Commit and share with your team
|
||||
|
||||
```bash
|
||||
git add .cursor/ project-brief.yaml
|
||||
git commit -m "chore: add cursor AI config for this project"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## All CLI commands
|
||||
|
||||
```bash
|
||||
dart run cursor_gen # First-time setup
|
||||
dart run cursor_gen --wizard # Interactive brief creator
|
||||
dart run cursor_gen --validate # Validate brief without generating
|
||||
dart run cursor_gen --refresh # Re-generate (preserves custom/ + CURSOR:CUSTOM blocks)
|
||||
dart run cursor_gen --diff # Preview changes before refresh
|
||||
dart run cursor_gen --check-updates # Check for template version updates
|
||||
dart run cursor_gen --telemetry # Show usage analytics report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Six Pillars — What Was Built
|
||||
|
||||
### 🔴 Pillar 1 — Template Versioning & Update Propagation
|
||||
- `cursor_templates_version` field in `project-brief.yaml` locks the version
|
||||
- `version_manager.dart` writes `.cursor-gen-lock.json` after every generation
|
||||
- `--check-updates` shows diff between locked and latest version
|
||||
- `--diff` previews what would change before `--refresh`
|
||||
- `CHANGELOG.md` documents all template changes
|
||||
|
||||
### 🔴 Pillar 2 — Override / Customization Layer
|
||||
- `.cursor/custom/` folder is **never touched** by the generator
|
||||
- `CURSOR:CUSTOM` / `CURSOR:CUSTOM:END` markers preserve inline customizations on `--refresh`
|
||||
- `override_manager.dart` snapshots and restores custom content around every generation
|
||||
- `custom/README.md` explains the system to new team members
|
||||
|
||||
### 🔴 Pillar 3 — Generator Testing & Output Quality Gates
|
||||
- `generator_test.dart`: full test suite covering resolver, renderer, validator
|
||||
- Golden file tests for all 3 stack combinations (BLoC+Clean, Riverpod+FF, GetX+MVC)
|
||||
- `--check-updates` validates no unreplaced `{{PLACEHOLDER}}` patterns survive
|
||||
- CI pipeline in `.github/workflows/template-ci.yml` runs all combinations on every PR
|
||||
- Lint step detects duplicate `alwaysApply: true` conflicts
|
||||
|
||||
### 🟠 Pillar 4 — Multi-Platform & Code Generation Awareness
|
||||
- `platforms` field in brief: `[ios, android, web, desktop]` → generates platform-specific rules
|
||||
- Web: warns about `dart:io`, PWA requirements, renderer differences
|
||||
- Desktop: window management, keyboard shortcuts, context menus
|
||||
- `codegen` field: `[freezed, json_serializable, injectable, retrofit]` → generates tool-specific rules
|
||||
- Each codegen template explains "never edit `.g.dart`" and build_runner usage
|
||||
|
||||
### 🟠 Pillar 5 — Security as Rules, Not Just an Agent
|
||||
- `security-standards.mdc` has `alwaysApply: true` — enforced on EVERY file write
|
||||
- Covers: secure storage, certificate pinning, no hardcoded secrets, PII logging rules, obfuscation
|
||||
- `error-handling.mdc` also always-on: global error boundaries, crash reporters, typed errors
|
||||
- Security _agent_ still exists for deep consultation — but is a second layer, not the only layer
|
||||
|
||||
### 🟡 Pillar 6 — Observability & Feedback Loop
|
||||
- `telemetry_opt_in: true` in brief enables local telemetry (never sent anywhere)
|
||||
- `telemetry.dart` logs generation history to `.cursor/telemetry.json`
|
||||
- `--telemetry` command prints report + quarterly review checklist
|
||||
- Feedback loop questions built into the report: which rules most violated, which agents ignored
|
||||
|
||||
### Additional fixes (lower priority gaps)
|
||||
- **Brief discovery UX**: `--wizard` interactive CLI, `brief-schema.json` for IDE autocomplete
|
||||
- **arch-guard documented**: `arch-guard.ts.tmpl` fully implemented with per-architecture rules
|
||||
- **i18n rules**: `localization.mdc.tmpl` — ARB format, ICU plurals, never-hardcode-strings rule
|
||||
- **Error handling**: `error-handling.mdc.tmpl` — FlutterError.onError, AppError sealed class, crash reporters
|
||||
|
||||
---
|
||||
|
||||
## Running Tests (Pillar 3)
|
||||
|
||||
```bash
|
||||
cd flutter-cursor-templates/generator
|
||||
dart pub get
|
||||
dart test test/generator_test.dart
|
||||
```
|
||||
|
||||
Update golden files after intentional template changes:
|
||||
```bash
|
||||
# Delete the golden you want to update, then run:
|
||||
dart test test/generator_test.dart --name "Golden"
|
||||
# The test will create new goldens on first run
|
||||
```
|
||||
Reference in New Issue
Block a user