cursor_gen/README.md

# 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. Install the CLI globally

From pub.dev:

```bash
dart pub global activate cursor_gen
```

From this repository:

```bash
cd flutter-cursor-templates/generator
dart pub global activate --source path .
```

From Git:

```bash
dart pub global activate --source git https://github.com/company/flutter-cursor-templates --git-path generator
```

If `cursor_gen` is not found after activation, add Dart's global bin directory to your shell:

```bash
export PATH="$PATH":"$HOME/.pub-cache/bin"
```

### 2. Create your brief (interactive wizard)

```bash
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
cursor_gen --validate
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
cursor_gen                   # First-time setup
cursor_gen --wizard          # Interactive brief creator
cursor_gen --validate        # Validate brief without generating
cursor_gen --refresh         # Re-generate (preserves custom/ + CURSOR:CUSTOM blocks)
cursor_gen --diff            # Preview changes before refresh
cursor_gen --check-updates   # Check for template version updates
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
```