agent-flutter 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-flutter",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Portable Flutter skill/rule pack initializer for multiple AI IDEs.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -697,8 +697,7 @@ Use local instructions from \`.cursor\`.
 Priority:
 1. \`.cursor/rules/shared/ui.md\`
 2. \`.cursor/rules/shared/integration-api.md\`
-3. \`.cursor/rules/shared/document-workflow-function.md\`
-4. \`.cursor/rules/shared/unit-test.md\` and \`.cursor/rules/shared/widget-test.md\`
+3. \`.cursor/rules/shared/unit-test.md\` and \`.cursor/rules/shared/widget-test.md\`
 
 When a task matches a skill, load the corresponding \`SKILL.md\` under:
 \`.cursor/skills/<skill>/SKILL.md\`

package/templates/shared/rules/integration-api.md

@@ -1,3 +1,153 @@
 ---
 alwaysApply: false
 ---
+# API Integration Rules & Workflow
+
+## 1. Goal
+Standardize how to integrate backend APIs into this project using the current architecture:
+- Transport: `lib/src/api/api.dart`
+- Endpoint mapping: `lib/src/api/api_url.dart`
+- Flavor config: `lib/src/utils/app_api_config.dart`
+- Persistence/token: `lib/src/utils/app_shared.dart`
+- State/UI: `lib/src/ui/**` with `Bloc + PageState`
+
+The rule is designed to prevent common violations: hardcoded URLs, mixed model layers, missing flavor handling, and inconsistent error behavior.
+
+## 1.1 Skill References (Required)
+When executing this rule, apply these skills together:
+- Architecture: [flutter-standard-lib-src-architecture](../skills/flutter-standard-lib-src-architecture/SKILL.md)
+- Dependency flow: [flutter-standard-lib-src-architecture-dependency-rules](../skills/flutter-standard-lib-src-architecture-dependency-rules/SKILL.md)
+- State management: [flutter-bloc-state-management](../skills/flutter-bloc-state-management/SKILL.md)
+- DI: [flutter-dependency-injection-injectable](../skills/flutter-dependency-injection-injectable/SKILL.md)
+- Error handling: [flutter-error-handling](../skills/flutter-error-handling/SKILL.md)
+- Localization: [getx-localization-standard](../skills/getx-localization-standard/SKILL.md)
+- Model reuse: [dart-model-reuse](../skills/dart-model-reuse/SKILL.md)
+
+## 2. Definition of Ready (P1 - Required Before Coding)
+API integration must not start until all items are clear:
+- Feature scope (function flow) is explicit.
+- API contract is explicit: method, path, request body/query, response schema, error schema.
+- Database-side behavior is understood from backend contract (field semantics, nullable rules, pagination/sort semantics).
+- Target flavor is explicit for testing (`staging` or `prod`).
+
+If any item is missing, stop implementation and request contract clarification first.
+
+## 3. Project Conventions (Current Repo)
+
+### A. Endpoint Source of Truth
+- Base URL must come from `AppApiConfig.baseApiUrl`.
+- Endpoint paths must be defined in `api_url.dart` interfaces (`IAuthApiUrl`, future groups).
+- Do not hardcode endpoint strings inside bloc/page/widget.
+
+### B. Transport Layer
+- Reuse `Api.request()` in `lib/src/api/api.dart`.
+- Use `useIDToken: true` by default for authenticated APIs.
+- Use `useIDToken: false` only for anonymous APIs (login/register/...).
+- Do not duplicate Dio setup in feature code.
+
+### C. Model Layer Separation
+- Request models: `lib/src/core/model/request/`
+- Response models: `lib/src/core/model/response/`
+- UI/domain-only models: `lib/src/core/model/`
+- Never pass raw `Map<String, dynamic>` across UI layers for non-trivial APIs.
+- Reuse-first: check existing models before creating new ones.
+
+### D. Repository Boundary
+- All remote calls must be wrapped by repository classes in `lib/src/core/repository/`.
+- Bloc/Controller must call repository methods, not `Api.request()` directly.
+- Repository owns request/response mapping and token persistence side effects when needed.
+- New repository methods should prefer `Result<T, E>` style returns for predictable error flow.
+
+### E. State/Error Handling
+- Use `PageState` (`initial/loading/failure/success`) for request lifecycle.
+- User-facing messages must be localized via `LocaleKey.*.tr` (no hardcoded text in bloc).
+- Network/server errors should be normalized in repository before bubbling to UI state.
+- Token invalid flow should be handled consistently with existing dialog flow (`showDialogErrorToken`).
+- Do not throw raw exceptions into UI layer for new integrations; map to typed error/result first.
+
+## 4. Standard Workflow for New API Integration
+
+### Step 1: Confirm Contract + Flavor
+- Confirm endpoint contract and sample payloads.
+- Confirm test flavor command:
+  - `fvm flutter run --flavor staging --dart-define=FLAVOR=staging`
+  - `fvm flutter run --flavor prod --dart-define=FLAVOR=prod`
+
+### Step 2: Add Endpoint Mapping
+- Extend `api_url.dart` by feature group interface.
+- Keep path builders centralized (no duplicated string fragments).
+- Follow structure constraints from [flutter-standard-lib-src-architecture](../skills/flutter-standard-lib-src-architecture/SKILL.md).
+
+### Step 3: Create Models
+- Add request/response models in correct folders.
+- Prefer typed fields and safe nullability.
+- Add parser methods (`fromJson/toJson`) consistently.
+- Apply reuse/evolution checklist from [dart-model-reuse](../skills/dart-model-reuse/SKILL.md).
+
+### Step 4: Implement Repository Method
+- Repository extends/reuses `Api`.
+- Use endpoint from `apiUrl.<group>`.
+- Map response to typed model.
+- Handle auth token persistence/refresh responsibilities in repository only.
+- Follow mapping strategy from [flutter-error-handling](../skills/flutter-error-handling/SKILL.md).
+
+### Step 5: Wire DI
+- Register repository through binding/module with `Get` injection.
+- UI layer resolves repository through bloc/controller, not directly in widgets.
+- Follow module boundaries from [flutter-dependency-injection-injectable](../skills/flutter-dependency-injection-injectable/SKILL.md).
+
+### Step 6: Integrate into Bloc
+- Add event(s): trigger API use case.
+- Emit `PageState.loading` before call.
+- On success: emit `PageState.success` with typed data.
+- On failure: emit `PageState.failure` with localized error key/message.
+- Keep event/state modeling aligned with [flutter-bloc-state-management](../skills/flutter-bloc-state-management/SKILL.md).
+
+### Step 7: UI Consumption
+- UI reads bloc state and renders loading/error/success.
+- No API parsing logic in widget tree.
+- All strings shown from API errors must pass localization policy in [getx-localization-standard](../skills/getx-localization-standard/SKILL.md).
+
+## 5. Minimal Reference Pattern
+
+```dart
+class FeatureRepository extends Api {
+  final IFeatureApiUrl _url;
+  FeatureRepository(this._url);
+
+  Future<FeatureResponse> fetchFeature(FeatureRequest req) async {
+    final res = await request<Map<String, dynamic>>(
+      _url.fetchFeature,
+      Method.post,
+      body: req.toJson(),
+      useIDToken: true,
+    );
+    return FeatureResponse.fromJson(res.data ?? <String, dynamic>{});
+  }
+}
+```
+
+## 6. Anti-Patterns (Do Not)
+- Do not call `Dio()` directly inside bloc/controller.
+- Do not put endpoint string literals in UI layer.
+- Do not mix request/response classes in one generic model file.
+- Do not hardcode user-facing error strings.
+- Do not bypass flavor config by using fixed base URL.
+
+## 7. Verification Checklist Before PR
+- [ ] Endpoint added in `api_url.dart` and consumed from repository only.
+- [ ] Request/response models are separated and typed.
+- [ ] Bloc uses `PageState` lifecycle correctly.
+- [ ] All displayed text/error is localized via `LocaleKey`.
+- [ ] Flavor run verified at least on staging command.
+- [ ] `fvm flutter analyze` passes.
+- [ ] Existing behavior (auth/token/toast/dialog flow) is not regressed.
+
+## 8. Prompt Template for AI
+Use this when asking AI to implement integration:
+
+> Integrate API for `<feature>` using project rule `integration-api.md`.
+> Contract: `<method/path/request/response/errors>`.
+> Use `api_url.dart` + repository layer + typed models + bloc `PageState`.
+> No hardcoded endpoint/message. Localize all user text.
+> Validate with `analyze` and staging flavor run command.

package/templates/shared/rules/document-workflow-function.md

@@ -1,98 +0,0 @@
----
-alwaysApply: false
----
-# AI Documentation Workflow (Function)
-
-## **Goal**
-To automatically generate and maintain detailed functional documentation in `spec/function-workflow.md`. This documentation bridges the gap between the high-level UI flow (from `ui-workflow.md`) and the technical implementation, focusing on **API integrations, Data Transformations, and State Management logic**.
-
-## **Trigger**
-This workflow is triggered when:
-1.  The `spec/ui-workflow.md` has been updated (Prerequisite).
-2.  Backend integration (API) is implemented for a feature.
-3.  Complex business logic is added (e.g., data validation, caching, error handling).
-4.  The user requests: "Update function workflow for [feature]".
-
-## **Workflow Steps**
-
-### **Step 1: Analyze the Implementation**
-- **Input**: The feature folder (`lib/src/ui/<feature>`) and `spec/ui-workflow.md`.
-- **Action**: Deep dive into the following files:
-    - `bloc/*_bloc.dart`: Identify Events, States, and Side Effects.
-    - `repository/*_repository.dart`: Identify API endpoints, Request/Response models.
-    - `model/*`: Analyze data structures.
-    - `core/managers/*`: Check for global state usage (e.g., Auth, Permission).
-
-### **Step 2: Format the Documentation**
-- **Output File**: `spec/function-workflow.md`
-- **Format**: Append (or Update) a section for EACH feature using the following template:
-
-```markdown
-## [Feature Name] (e.g., Login)
-**Ref UI**: [Link to UI Spec Section]
-
-### **1. Data Model**
-**Request**: `LoginRequest`
-- `email` (String): Required, valid email format.
-- `password` (String): Required, min 6 chars.
-
-**Response**: `LoginResponse`
-- `token` (String): JWT Token.
-- `user` (UserDto): User profile info.
-
-### **2. State Management (BLoC)**
-**Events**:
-- `LoginEvent(email, password)`: Triggers the login process.
-- `LoginReset()`: Resets state to initial.
-
-**States**:
-- `LoginInitial`: Form inputs enabled.
-- `LoginLoading`: Inputs disabled, loading spinner active.
-- `LoginSuccess(user)`: Navigation trigger.
-- `LoginFailure(error)`: Error message display.
-
-### **3. Functional Logic**
-1.  **Validation**:
-    - Check `email` via Regex.
-    - Check `password.length >= 6`.
-    - *If invalid*: Emit `LoginFailure(ValidationError)`.
-
-2.  **API Call**:
-    - Call `AuthRepository.login(request)`.
-    - **Endpoint**: `POST /api/v1/auth/login`
-    - **Headers**: `Content-Type: application/json`
-
-3.  **Error Handling**:
-    - **401 Unauthorized**: "Incorrect credentials".
-    - **500 Server Error**: "System error, try again".
-    - **Network Error**: "Check connection".
-
-4.  **Post-Process**:
-    - Save `token` to `SecureStorage`.
-    - Update `UserManager.currentUser`.
-    - Emit `LoginSuccess`.
-
-### **4. Dependencies & Services**
-- `AuthRepository`: API communication.
-- `SecureStorage`: Token persistence.
-- `UserManager`: Global user state.
-
-### **5. Technical Debt / Optimization**
-- [ ] Add rate limiting on login attempts.
-- [ ] Cache last used email for convenience.
-```
-
-### **Step 3: Verification**
-- **Consistency Check**: Ensure the "Functional Logic" aligns with the "User Flow" in `spec/ui-workflow.md`.
-- **API Check**: Verify that the documented Endpoint and Request/Response models match the actual code in `Repository` and `Retrofit` clients.
-- **Edge Cases**: Ensure error handling (Network, Validation, Server) is documented.
-
----
-
-## **Prompt for AI**
-
-### **Case 1: Single Feature**
-> "Analyze `lib/src/ui/<feature>` and update `spec/function-workflow.md` based on the UI spec."
-
-### **Case 2: Sync with UI Spec**
-> "Read `spec/ui-workflow.md` and generate the corresponding functional specs in `spec/function-workflow.md`."

package/templates/shared/rules/new-template-project.md

@@ -1,51 +0,0 @@
----
-alwaysApply: false
----
-# New Template Project (Script-first)
-
-Use the bootstrap script instead of generating the full workflow text.
-
-## Script path
-- Trae: `.trae/scripts/bootstrap_flutter_template.sh`
-- Codex: `.codex/scripts/bootstrap_flutter_template.sh`
-- Cursor: `.cursor/scripts/bootstrap_flutter_template.sh`
-- Windsurf: `.windsurf/scripts/bootstrap_flutter_template.sh`
-- Cline: `.clinerules/scripts/bootstrap_flutter_template.sh`
-- GitHub: `.github/scripts/bootstrap_flutter_template.sh`
-
-## Run
-Interactive mode:
-```bash
-bash .codex/scripts/bootstrap_flutter_template.sh
-```
-
-Non-interactive mode:
-```bash
-bash .codex/scripts/bootstrap_flutter_template.sh \
-  --name link_home_mobile \
-  --org com.company \
-  --flutter-version stable \
-  --dir ~/workspace \
-  --force \
-  --non-interactive
-```
-
-## Inputs
-- `--name`: project folder name (required in non-interactive mode).
-- `--org`: reverse-domain org id (default: `com.example`).
-- `--flutter-version`: Flutter version for FVM (default: `stable`).
-- `--dir`: parent folder to create project in (default: current directory).
-- `--force`: allow overwrite in an existing non-empty directory.
-
-## What the script does
-1. Ensures FVM exists (auto-installs with `dart pub global activate fvm` if needed).
-2. Creates Flutter project with FVM and selected version.
-3. Adds core dependencies and dev dependencies.
-4. Creates architecture folders and starter files (`main`, DI, locale, routing, home feature).
-5. Creates `.env`, `.env.staging`, `.env.prod` and updates `.gitignore`.
-
-## Validation
-```bash
-cd <project_name>
-fvm flutter run
-```