oh-my-customcodex 0.1.0

package/templates/guides/fastapi/best-practices.md

@@ -0,0 +1,232 @@
+# FastAPI Best Practices
+
+> Source: https://fastapi.tiangolo.com/ and community patterns
+
+## Project Structure
+
+Organize by domain, not by file type:
+
+```
+src/
+├── auth/
+│   ├── router.py       # API endpoints
+│   ├── schemas.py      # Pydantic models
+│   ├── models.py       # Database models
+│   ├── service.py      # Business logic
+│   ├── dependencies.py # Route validators
+│   └── exceptions.py   # Custom exceptions
+├── users/
+│   └── ...
+├── config.py
+└── main.py
+```
+
+## Async Best Practices
+
+### I/O-Intensive Tasks
+
+```python
+# Use async def with await for non-blocking I/O
+async def fetch_user(user_id: int) -> User:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"/api/users/{user_id}")
+        return User(**response.json())
+```
+
+### Sync I/O Operations
+
+```python
+# Use regular def - FastAPI offloads to threadpool
+def read_config() -> dict:
+    with open("config.yaml") as f:
+        return yaml.safe_load(f)
+```
+
+### CPU-Intensive Tasks
+
+```python
+# Use separate worker processes
+from celery import Celery
+
+celery_app = Celery("tasks", broker="redis://localhost")
+
+@celery_app.task
+def process_data(data: dict) -> dict:
+    # Heavy computation
+    return result
+```
+
+### Never Do This
+
+```python
+# WRONG: Blocks event loop
+async def bad_example():
+    time.sleep(5)  # Never use time.sleep in async!
+
+# CORRECT: Use asyncio.sleep
+async def good_example():
+    await asyncio.sleep(5)
+```
+
+## Pydantic Models
+
+### Custom Base Model
+
+```python
+from pydantic import BaseModel
+from datetime import datetime
+
+class AppBaseModel(BaseModel):
+    class Config:
+        from_attributes = True
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+class UserResponse(AppBaseModel):
+    id: int
+    email: str
+    created_at: datetime
+```
+
+### Validation
+
+```python
+from pydantic import BaseModel, EmailStr, Field, validator
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+    age: int = Field(..., ge=18, le=120)
+
+    @validator("password")
+    def password_strength(cls, v):
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain uppercase")
+        return v
+```
+
+## Dependencies
+
+### Authentication
+
+```python
+from fastapi import Depends, HTTPException
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db)
+) -> User:
+    user = await verify_token(token, db)
+    if not user:
+        raise HTTPException(status_code=401)
+    return user
+
+async def get_active_user(
+    user: User = Depends(get_current_user)
+) -> User:
+    if not user.is_active:
+        raise HTTPException(status_code=403)
+    return user
+```
+
+### Database Session
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+```
+
+## Error Handling
+
+```python
+# Custom exceptions
+class AuthException(Exception):
+    pass
+
+class InvalidCredentials(AuthException):
+    pass
+
+# Exception handler
+@app.exception_handler(AuthException)
+async def auth_exception_handler(request, exc):
+    return JSONResponse(
+        status_code=401,
+        content={"detail": str(exc)}
+    )
+
+# In router
+@router.post("/login")
+async def login(credentials: LoginSchema):
+    try:
+        return await auth_service.login(credentials)
+    except InvalidCredentials:
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+```
+
+## API Design
+
+```python
+from fastapi import APIRouter
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users"]
+)
+
+@router.get(
+    "/{user_id}",
+    response_model=UserResponse,
+    summary="Get user by ID",
+    responses={
+        404: {"model": ErrorResponse, "description": "User not found"}
+    }
+)
+async def get_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+) -> UserResponse:
+    """
+    Get a specific user by their ID.
+
+    - **user_id**: The unique identifier of the user
+    """
+    user = await user_service.get(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+## Testing
+
+```python
+import pytest
+from httpx import AsyncClient
+from main import app
+
+@pytest.fixture
+async def client():
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient):
+    response = await client.post(
+        "/users/",
+        json={"email": "test@example.com", "password": "Password123"}
+    )
+    assert response.status_code == 201
+    assert response.json()["email"] == "test@example.com"
+```

package/templates/guides/fastapi/index.yaml

@@ -0,0 +1,21 @@
+# FastAPI Guide
+
+metadata:
+  name: fastapi
+  description: FastAPI framework reference documentation
+
+source:
+  type: external
+  origin: fastapi.tiangolo.com
+  urls:
+    - https://fastapi.tiangolo.com/
+    - https://github.com/zhanymkanov/fastapi-best-practices
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: best-practices
+    path: ./best-practices.md
+    description: FastAPI best practices and patterns
+
+used_by:
+  - be-fastapi-expert

package/templates/guides/flutter/architecture.md

@@ -0,0 +1,141 @@
+# Flutter Architecture
+
+> Reference: docs.flutter.dev/app-architecture
+
+## Official MVVM Pattern
+
+```
+UI Layer
+  ├─ View (Widget)           — display only, no business logic
+  └─ ViewModel (ChangeNotifier / Notifier) — state + commands
+
+Data Layer
+  ├─ Repository              — single source of truth per domain
+  └─ Service                 — stateless external API wrapper
+
+Domain Layer (optional)
+  └─ UseCase                 — cross-repository business logic
+```
+
+### Dependency Rules
+
+- View knows only its ViewModel
+- ViewModel knows Repositories (private)
+- Repository knows Services (private)
+- **Direction always inward** — UI depends on data, never reverse
+
+### ViewModel with Commands
+
+```dart
+class HomeViewModel extends ChangeNotifier {
+  HomeViewModel({required BookingRepository bookingRepository})
+      : _bookingRepository = bookingRepository {
+    load = Command0(_load)..execute();
+  }
+
+  final BookingRepository _bookingRepository;
+  late final Command0 load;
+
+  List<BookingSummary> _bookings = [];
+  UnmodifiableListView<BookingSummary> get bookings =>
+      UnmodifiableListView(_bookings);
+
+  Future<Result> _load() async {
+    final result = await _bookingRepository.getBookingsList();
+    if (result case Ok(:final value)) _bookings = value;
+    notifyListeners();
+    return result;
+  }
+}
+```
+
+## Project Structure
+
+### Medium Apps (Official MVVM)
+
+```
+lib/
+├── ui/
+│   ├── core/
+│   │   ├── themes/app_theme.dart
+│   │   └── widgets/loading_indicator.dart
+│   └── home/
+│       ├── home_screen.dart
+│       └── home_viewmodel.dart
+├── data/
+│   ├── repositories/booking_repository.dart
+│   └── services/api_service.dart
+└── domain/ (optional)
+    └── use_cases/get_bookings_usecase.dart
+```
+
+### Large Apps (Clean Architecture)
+
+```
+lib/
+├── core/
+│   ├── error/failures.dart
+│   ├── network/api_client.dart
+│   └── utils/extensions.dart
+└── features/
+    └── auth/
+        ├── data/
+        │   ├── datasources/auth_remote_datasource.dart
+        │   ├── models/user_model.dart
+        │   └── repositories/auth_repository_impl.dart
+        ├── domain/
+        │   ├── entities/user.dart
+        │   ├── repositories/auth_repository.dart
+        │   └── use_cases/login_usecase.dart
+        └── presentation/
+            ├── bloc/auth_bloc.dart
+            ├── pages/login_page.dart
+            └── widgets/login_form.dart
+```
+
+## Navigation (go_router)
+
+```dart
+final router = GoRouter(
+  initialLocation: '/',
+  routes: [
+    GoRoute(
+      path: '/',
+      builder: (context, state) => const HomeScreen(),
+    ),
+    GoRoute(
+      path: '/product/:id',
+      builder: (context, state) {
+        final id = state.pathParameters['id']!;
+        return ProductDetailScreen(id: id);
+      },
+    ),
+    ShellRoute(
+      builder: (context, state, child) => ScaffoldWithNavBar(child: child),
+      routes: [/* nested tab routes */],
+    ),
+  ],
+  redirect: (context, state) {
+    final isLoggedIn = /* check auth */;
+    if (!isLoggedIn && state.matchedLocation != '/login') return '/login';
+    return null;
+  },
+);
+```
+
+## Data Models (freezed)
+
+```dart
+@freezed
+class Product with _$Product {
+  const factory Product({
+    required int id,
+    required String name,
+    required double price,
+    @Default('') String description,
+  }) = _Product;
+
+  factory Product.fromJson(Map<String, dynamic> json) =>
+      _$ProductFromJson(json);
+}
+```

package/templates/guides/flutter/fundamentals.md

@@ -0,0 +1,119 @@
+# Flutter Fundamentals
+
+> Reference: Flutter Official Documentation (docs.flutter.dev)
+
+## Widget System
+
+Flutter's UI is built with a composition of widgets. Everything is a widget — including padding, alignment, and decoration.
+
+### Widget Types
+
+| Type | Use Case | State |
+|------|----------|-------|
+| `StatelessWidget` | Pure rendering, no mutable state | Immutable |
+| `StatefulWidget` | Local ephemeral state (animations, forms) | Mutable via `State<T>` |
+| `InheritedWidget` | Data propagation down widget tree | Foundation of Provider |
+
+### Widget Lifecycle
+
+```dart
+// StatefulWidget lifecycle
+class MyWidget extends StatefulWidget {
+  @override
+  State<MyWidget> createState() => _MyWidgetState();
+}
+
+class _MyWidgetState extends State<MyWidget> {
+  @override
+  void initState() { super.initState(); /* one-time setup */ }
+
+  @override
+  void didChangeDependencies() { super.didChangeDependencies(); /* InheritedWidget changed */ }
+
+  @override
+  void didUpdateWidget(MyWidget oldWidget) { super.didUpdateWidget(oldWidget); /* parent rebuilt */ }
+
+  @override
+  Widget build(BuildContext context) { return Container(); /* called on every rebuild */ }
+
+  @override
+  void dispose() { /* cleanup controllers, subscriptions */ super.dispose(); }
+}
+```
+
+## Three-Tree Architecture
+
+Flutter maintains three parallel trees:
+
+```
+Widget Tree (immutable descriptions)
+    ↓ createElement()
+Element Tree (persistent, mutable handles)
+    ↓ createRenderObject()
+RenderObject Tree (layout + paint primitives)
+```
+
+- **Widget**: Lightweight, immutable configuration. Rebuilt frequently.
+- **Element**: Persistent handle that manages widget lifecycle. Enables efficient diffing.
+- **RenderObject**: Expensive layout/paint primitives. Only updated when properties change.
+
+### Layout Algorithm
+
+**Constraints go down, sizes go up, parent decides position.**
+
+```dart
+// Parent passes BoxConstraints to child
+// Child returns its chosen Size within those constraints
+// Parent positions child at an Offset
+```
+
+Common layout errors:
+- Unbounded height/width in `Column`/`Row` → wrap with `Expanded` or `Flexible`
+- `Viewport was given unbounded height` → provide explicit height or use `SliverList`
+
+## BuildContext
+
+`BuildContext` is a handle to the widget's location in the Element tree.
+
+```dart
+// Access inherited data
+final theme = Theme.of(context);
+final mediaQuery = MediaQuery.of(context);
+
+// NEVER store context across async gaps
+// ALWAYS check mounted before using context after await
+if (!mounted) return;
+Navigator.of(context).push(...);
+```
+
+## Keys
+
+| Key Type | When to Use |
+|----------|-------------|
+| `ValueKey` | Items with unique business identity (user ID, product SKU) |
+| `ObjectKey` | Items without natural key (use the object itself) |
+| `UniqueKey` | Force new Element every build (rare, expensive) |
+| `GlobalKey` | Cross-widget state access (use sparingly — breaks encapsulation) |
+
+```dart
+// Reorderable list MUST use keys
+ListView(
+  children: items.map((item) => ListTile(
+    key: ValueKey(item.id),
+    title: Text(item.name),
+  )).toList(),
+);
+```
+
+## Package Recommendations
+
+| Category | Package | Notes |
+|----------|---------|-------|
+| State (default) | `flutter_riverpod` | Compile-time safe, built-in DI |
+| State (enterprise) | `flutter_bloc` | Event-driven, audit trails |
+| Navigation | `go_router` | Official, deep linking, web |
+| Models | `freezed` + `json_serializable` | Immutable, code-gen |
+| HTTP | `dio` | Interceptors, cancellation |
+| Linting | `very_good_analysis` | Community standard rules |
+| Testing | `mocktail` | Null-safe mocking, no codegen |
+| Secure Storage | `flutter_secure_storage` | Keychain/Keystore |

package/templates/guides/flutter/index.yaml

@@ -0,0 +1,44 @@
+# Flutter Guide
+
+metadata:
+  name: flutter
+  description: Flutter cross-platform development reference documentation
+
+source:
+  type: external
+  origin: flutter.dev
+  urls:
+    - https://docs.flutter.dev/
+    - https://docs.flutter.dev/app-architecture
+    - https://riverpod.dev/docs/introduction/getting_started
+    - https://bloclibrary.dev/
+    - https://dart.dev/effective-dart
+  last_fetched: "2026-03-11"
+
+documents:
+  - name: fundamentals
+    path: ./fundamentals.md
+    description: Flutter widget system, BuildContext, rendering pipeline
+
+  - name: state-management
+    path: ./state-management.md
+    description: Riverpod 3.0, BLoC 9.0, Provider patterns and selection guide
+
+  - name: architecture
+    path: ./architecture.md
+    description: MVVM structure, project organization, go_router, freezed
+
+  - name: performance
+    path: ./performance.md
+    description: DevTools, const optimization, RepaintBoundary, Isolate
+
+  - name: testing
+    path: ./testing.md
+    description: Widget tests, golden tests, integration tests, mocking
+
+  - name: security
+    path: ./security.md
+    description: OWASP Mobile Top 10, secure storage, certificate pinning, platform security
+
+used_by:
+  - fe-flutter-agent

package/templates/guides/flutter/performance.md

@@ -0,0 +1,119 @@
+# Flutter Performance
+
+> Reference: docs.flutter.dev/perf/best-practices
+
+## Frame Budget
+
+- Target: **<8ms build + <8ms render = 16.67ms** (60fps)
+- Profile with: `flutter run --profile` (not debug mode)
+- Tool: DevTools Performance view → identify jank frames
+
+## Build-Time Optimization
+
+### const Constructors
+
+```dart
+// GOOD — zero rebuild cost
+const Text('Hello');
+const SizedBox(height: 8);
+const Icon(Icons.star);
+
+// BAD — new instance every build
+Text('Hello');
+SizedBox(height: 8);
+```
+
+### Localize setState
+
+```dart
+// BAD — rebuilds entire screen
+class _ScreenState extends State<Screen> {
+  int count = 0;
+  Widget build(BuildContext context) {
+    return Column(children: [
+      ExpensiveHeader(), // rebuilt unnecessarily
+      Text('$count'),
+      ElevatedButton(onPressed: () => setState(() => count++), child: Text('+'))
+    ]);
+  }
+}
+
+// GOOD — only counter rebuilds
+class _ScreenState extends State<Screen> {
+  Widget build(BuildContext context) {
+    return Column(children: [
+      const ExpensiveHeader(), // not rebuilt
+      CounterWidget(), // isolated StatefulWidget
+    ]);
+  }
+}
+```
+
+### Extract Widgets (not methods)
+
+```dart
+// BAD — no Element identity, always rebuilds
+Widget _buildHeader() => Container(...);
+
+// GOOD — has Element identity, diffed efficiently
+class HeaderWidget extends StatelessWidget {
+  const HeaderWidget({super.key});
+  @override
+  Widget build(BuildContext context) => Container(...);
+}
+```
+
+## Rendering Optimization
+
+### RepaintBoundary
+
+```dart
+// Wrap frequently repainting subtrees
+RepaintBoundary(
+  child: AnimatedWidget(...), // only this subtree repaints
+)
+```
+
+Detect with: DevTools → Rendering → "Highlight repaints"
+
+### Avoid Expensive Widgets
+
+| Avoid | Use Instead | Reason |
+|-------|-------------|--------|
+| `Opacity` widget | `color.withValues(alpha: 0.5)` | Opacity widget triggers saveLayer |
+| `ClipRRect` in animations | Pre-clip static content | saveLayer per frame |
+| `Container` for sizing | `SizedBox` | Lighter, no decoration |
+
+## List Performance
+
+```dart
+// GOOD — lazy construction, O(visible) not O(total)
+ListView.builder(
+  itemCount: items.length,
+  itemExtent: 72.0, // skip intrinsic layout passes
+  itemBuilder: (context, index) => ProductTile(items[index]),
+);
+
+// BAD — builds ALL children upfront
+ListView(children: items.map((i) => ProductTile(i)).toList());
+```
+
+## Compute Offloading
+
+```dart
+// CPU-intensive work (>16ms) on isolate
+final result = await Isolate.run(() {
+  return heavyJsonParsing(rawData);
+});
+
+// Web-compatible alternative
+final result = await compute(heavyJsonParsing, rawData);
+```
+
+## DevTools Workflow
+
+1. **Inspector** → identify widget causing rebuild
+2. **Performance view** → identify jank frames (>16ms)
+3. **CPU Profiler** → identify expensive Dart methods
+4. **Memory view** → detect object leaks
+5. **Network** → monitor API call timing