@tekyzinc/gsd-t 2.45.11 → 2.50.10

package/templates/stacks/firebase.md

@@ -0,0 +1,166 @@
+# Firebase Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Firestore Security Rules
+
+```
+MANDATORY:
+  ├── Default-deny: rules start with allow read, write: if false;
+  ├── Write granular rules per collection and operation (read, create, update, delete)
+  ├── Use request.auth.uid for user-scoped access — NEVER trust client-sent IDs
+  ├── Validate data shape in rules: request.resource.data.field is string
+  ├── Test rules with the Firebase Emulator before deploying
+  └── NEVER use allow read, write: if true in production
+```
+
+**GOOD**
+```
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId} {
+      allow read: if request.auth != null && request.auth.uid == userId;
+      allow update: if request.auth != null && request.auth.uid == userId
+        && request.resource.data.keys().hasOnly(['displayName', 'avatar', 'updatedAt'])
+        && request.resource.data.displayName is string
+        && request.resource.data.displayName.size() <= 100;
+      allow create, delete: if false;
+    }
+  }
+}
+```
+
+---
+
+## 2. Firestore Data Modeling
+
+```
+MANDATORY:
+  ├── Denormalize for read performance — Firestore charges per read, not per field
+  ├── Subcollections for large or unbounded lists (messages, orders)
+  ├── Embedded objects for small, bounded data that's always read together
+  ├── Store document IDs as fields when needed for queries
+  ├── Use server timestamps: serverTimestamp() — not client Date.now()
+  └── NEVER create deeply nested subcollection hierarchies (max 2-3 levels)
+```
+
+**GOOD**
+```typescript
+// User document — embedded small data
+{
+  id: "user-123",
+  displayName: "Jane Doe",
+  email: "jane@example.com",
+  settings: { theme: "dark", notifications: true },  // embedded — always read together
+  createdAt: serverTimestamp(),
+}
+
+// Orders — subcollection (unbounded, queried separately)
+// /users/user-123/orders/{orderId}
+```
+
+---
+
+## 3. Cloud Functions
+
+```
+MANDATORY:
+  ├── Use v2 functions (onRequest, onCall, onDocumentWritten) — not v1
+  ├── Validate ALL inputs in onCall functions — they're public endpoints
+  ├── Set memory and timeout limits per function
+  ├── Use secrets manager for API keys — not environment config
+  ├── Idempotent design — functions may retry on failure
+  └── Keep functions focused — one responsibility per function
+```
+
+**GOOD**
+```typescript
+import { onCall, HttpsError } from 'firebase-functions/v2/https';
+import { z } from 'zod';
+
+const schema = z.object({ orderId: z.string().uuid() });
+
+export const cancelOrder = onCall({ memory: '256MiB', timeoutSeconds: 30 }, async (request) => {
+  if (!request.auth) throw new HttpsError('unauthenticated', 'Must be logged in');
+
+  const parsed = schema.safeParse(request.data);
+  if (!parsed.success) throw new HttpsError('invalid-argument', 'Invalid input');
+
+  await db.collection('orders').doc(parsed.data.orderId).update({ status: 'cancelled' });
+  return { success: true };
+});
+```
+
+---
+
+## 4. Authentication
+
+```
+MANDATORY:
+  ├── Use Firebase Auth — don't build custom auth alongside it
+  ├── Store additional user data in Firestore — not in Auth custom claims (limited to 1KB)
+  ├── Custom claims for roles/permissions only (admin, moderator)
+  ├── Handle auth state with onAuthStateChanged listener
+  ├── Sign out clears local state — don't leave stale data
+  └── NEVER store Firebase API keys as secrets — they're meant to be public (security rules protect data)
+```
+
+---
+
+## 5. Storage Rules
+
+```
+MANDATORY:
+  ├── Restrict uploads by file type and size in rules
+  ├── User-scoped paths: /users/{userId}/avatar — match in rules
+  ├── Validate content type: request.resource.contentType.matches('image/.*')
+  ├── Set max file size in rules: request.resource.size < 5 * 1024 * 1024
+  └── NEVER allow public write access to storage
+```
+
+---
+
+## 6. Emulator and Local Development
+
+```
+MANDATORY:
+  ├── Use Firebase Emulator Suite for local development
+  ├── Test security rules against the emulator before deploying
+  ├── Seed data via emulator import — not manual dashboard entry
+  ├── CI runs tests against emulators — not production
+  └── Never connect to production from local development
+```
+
+---
+
+## 7. Anti-Patterns
+
+```
+NEVER:
+  ├── allow read, write: if true in production rules
+  ├── Trusting client-sent user IDs — use request.auth.uid
+  ├── Deep subcollection nesting (4+ levels)
+  ├── Large documents (> 1MB) — split into subcollections
+  ├── Reading entire collections without query limits
+  ├── v1 Cloud Functions for new code — use v2
+  ├── Storing secrets in Firebase config — use Secret Manager
+  └── Testing against production — use emulators
+```
+
+---
+
+## Firebase Verification Checklist
+
+- [ ] Security rules default-deny with granular per-collection policies
+- [ ] request.auth.uid used for access control — no client IDs trusted
+- [ ] Data model optimized for reads (denormalized where appropriate)
+- [ ] Subcollections for unbounded lists
+- [ ] Cloud Functions v2 with input validation
+- [ ] Functions are idempotent
+- [ ] Storage rules restrict file type and size
+- [ ] All rules tested against emulator
+- [ ] serverTimestamp() used — not client timestamps
+- [ ] No allow read, write: if true in production

package/templates/stacks/flutter.md

@@ -0,0 +1,205 @@
+# Flutter Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. State Management — Riverpod
+
+```
+MANDATORY:
+  ├── Use Riverpod for state management — not setState for anything beyond local UI
+  ├── Provider for each data source (API, local storage, computed)
+  ├── AsyncNotifierProvider for server data with loading/error states
+  ├── StateProvider for simple toggles/filters
+  ├── NEVER store server data in StatefulWidget setState
+  └── ref.watch for reactive reads, ref.read for one-shot actions (onTap)
+```
+
+**BAD**
+```dart
+class _MyState extends State<MyWidget> {
+  List<User> users = [];
+  void initState() {
+    super.initState();
+    fetchUsers().then((u) => setState(() => users = u));
+  }
+}
+```
+
+**GOOD**
+```dart
+@riverpod
+class UsersNotifier extends _$UsersNotifier {
+  @override
+  Future<List<User>> build() => userRepository.getAll();
+}
+
+// In widget:
+final users = ref.watch(usersNotifierProvider);
+users.when(
+  data: (list) => UserListView(users: list),
+  loading: () => const LoadingSkeleton(),
+  error: (e, _) => ErrorView(message: e.toString()),
+);
+```
+
+---
+
+## 2. Widget Design
+
+```
+MANDATORY:
+  ├── Max 150 lines per widget file — extract sub-widgets
+  ├── Prefer StatelessWidget — use ConsumerWidget with Riverpod
+  ├── Extract build method sub-trees into separate widgets (not methods)
+  ├── One widget per file for major widgets
+  ├── Use const constructors wherever possible
+  └── No business logic in build() — move to providers/notifiers
+```
+
+**BAD** — `Widget _buildHeader()` methods that return widget trees.
+
+**GOOD** — Extract `HeaderWidget` as its own `ConsumerWidget`.
+
+---
+
+## 3. Navigation
+
+```
+MANDATORY:
+  ├── Use go_router for declarative routing
+  ├── Define all routes in a single router config file
+  ├── Use named routes — NEVER hardcode path strings in widgets
+  ├── Handle deep links in the router config
+  └── Redirect unauthenticated users in router guards — not in widgets
+```
+
+**GOOD**
+```dart
+final router = GoRouter(
+  routes: [
+    GoRoute(path: '/', builder: (_, __) => const HomePage()),
+    GoRoute(path: '/users/:id', builder: (_, state) =>
+      UserDetailPage(id: state.pathParameters['id']!)),
+  ],
+  redirect: (context, state) {
+    final isLoggedIn = ref.read(authProvider).isLoggedIn;
+    if (!isLoggedIn) return '/login';
+    return null;
+  },
+);
+```
+
+---
+
+## 4. Data Models
+
+```
+MANDATORY:
+  ├── Use freezed for immutable data classes with copyWith, ==, and serialization
+  ├── JSON serialization via json_serializable or freezed's fromJson/toJson
+  ├── NEVER use raw Map<String, dynamic> between layers
+  ├── Separate models: API DTO → Domain Model → UI ViewModel (if needed)
+  └── Use sealed classes (Dart 3) for state unions
+```
+
+**GOOD**
+```dart
+@freezed
+class User with _$User {
+  const factory User({
+    required String id,
+    required String name,
+    required String email,
+    required UserRole role,
+  }) = _User;
+
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+```
+
+---
+
+## 5. Repository Pattern
+
+```
+MANDATORY:
+  ├── All API/DB calls go through repository classes — widgets never call HTTP directly
+  ├── Repository returns domain models — not raw JSON or Response objects
+  ├── Handle errors in repository — throw typed exceptions
+  ├── Abstract repository interface for testability
+  └── Use dio or http package — configure interceptors for auth/logging
+```
+
+---
+
+## 6. Platform-Specific Code
+
+```
+MANDATORY:
+  ├── Use Platform.isAndroid/isIOS checks sparingly — prefer adaptive widgets
+  ├── Platform channels: define a clear Dart interface, handle errors on both sides
+  ├── Test on both platforms before marking task complete
+  ├── Use device_info_plus for runtime capability detection
+  └── Handle permissions gracefully — explain why before requesting
+```
+
+---
+
+## 7. Performance
+
+```
+MANDATORY:
+  ├── Use const widgets wherever possible — prevents unnecessary rebuilds
+  ├── Use ListView.builder for long lists — NEVER ListView with children for 20+ items
+  ├── Cache images with CachedNetworkImage — not Image.network
+  ├── Avoid rebuilding entire widget trees — use granular providers
+  ├── Profile with Flutter DevTools before optimizing
+  └── Minimize widget depth — deep nesting kills readability and performance
+```
+
+---
+
+## 8. Testing
+
+```
+MANDATORY:
+  ├── Unit tests for providers, notifiers, and business logic
+  ├── Widget tests for UI components with pumpWidget
+  ├── Integration tests for critical user flows
+  ├── Use mocktail for mocking — not mockito (null-safety friendly)
+  ├── Test loading, error, and empty states — not just happy path
+  └── Golden tests for complex custom widgets (optional but recommended)
+```
+
+---
+
+## 9. Anti-Patterns
+
+```
+NEVER:
+  ├── setState for server data (use Riverpod)
+  ├── Raw Map<String, dynamic> between layers — use typed models
+  ├── Build methods over 80 lines — extract widgets
+  ├── Hardcoded strings — use constants or l10n
+  ├── Nested callbacks deeper than 2 levels — use async/await
+  ├── context.read in build() — use ref.watch
+  ├── Ignoring dispose() — always clean up controllers and streams
+  └── print() for logging — use logger package
+```
+
+---
+
+## Flutter Verification Checklist
+
+- [ ] Riverpod for state management — no setState for server data
+- [ ] Widgets under 150 lines with const constructors
+- [ ] go_router with named routes — no hardcoded path strings
+- [ ] freezed models for all data — no raw Maps
+- [ ] Repository pattern — widgets never call HTTP
+- [ ] Loading, error, and empty states handled in every async widget
+- [ ] ListView.builder for dynamic lists
+- [ ] Tests cover providers, widgets, and critical flows
+- [ ] Tested on both iOS and Android
+- [ ] No print() in committed code

package/templates/stacks/github-actions.md

@@ -0,0 +1,201 @@
+# GitHub Actions Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Workflow Structure
+
+```
+MANDATORY:
+  ├── One workflow per concern: ci.yml, deploy.yml, release.yml
+  ├── Name workflows clearly: name: "CI — Lint, Test, Build"
+  ├── Trigger on specific events — NEVER use on: push without branch filters
+  ├── Use workflow_dispatch for manual triggers on deploy/release workflows
+  └── Keep workflows under 200 lines — extract reusable logic to composite actions
+```
+
+**GOOD**
+```yaml
+name: CI — Lint, Test, Build
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+```
+
+---
+
+## 2. Job Design
+
+```
+MANDATORY:
+  ├── Name jobs descriptively: jobs: lint:, jobs: test-unit:, jobs: build:
+  ├── Use needs: for job dependencies — parallelize independent jobs
+  ├── Set timeout-minutes on every job (default 360 is too long)
+  ├── Use matrix strategy for multi-version/multi-platform testing
+  └── Fail fast by default — set fail-fast: false only when you need all results
+```
+
+**GOOD**
+```yaml
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps: ...
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        node-version: [18, 20]
+    steps: ...
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps: ...
+```
+
+---
+
+## 3. Caching
+
+```
+MANDATORY:
+  ├── Cache dependencies (node_modules, pip, gradle) — saves minutes per run
+  ├── Use actions/cache or setup-node with cache: 'npm'
+  ├── Cache key must include lock file hash — invalidates on dependency changes
+  ├── Cache Playwright browsers separately (they're large)
+  └── Set restore-keys for partial cache hits
+```
+
+**GOOD**
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 20
+    cache: 'npm'
+
+# Or explicit caching:
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: ${{ runner.os }}-npm-
+```
+
+---
+
+## 4. Secrets Management
+
+```
+MANDATORY:
+  ├── NEVER hardcode secrets, tokens, or API keys in workflow files
+  ├── Use GitHub repository or environment secrets
+  ├── Use environment-scoped secrets for deploy workflows (staging vs production)
+  ├── Limit secret access: only jobs that need them should reference them
+  ├── NEVER echo or log secrets — even accidentally via debug output
+  └── Rotate secrets periodically — set reminders
+```
+
+**BAD**
+```yaml
+env:
+  API_KEY: sk-abc123  # NEVER DO THIS
+```
+
+**GOOD**
+```yaml
+env:
+  API_KEY: ${{ secrets.API_KEY }}
+```
+
+---
+
+## 5. Actions Versioning
+
+```
+MANDATORY:
+  ├── Pin actions to major version: uses: actions/checkout@v4
+  ├── For security-critical workflows, pin to SHA: uses: actions/checkout@abc123
+  ├── NEVER use @latest or @main for third-party actions
+  ├── Review third-party actions before use — check the source
+  └── Prefer official actions (actions/*, github/*) over community ones
+```
+
+---
+
+## 6. Deployment Workflows
+
+```
+MANDATORY:
+  ├── Require manual approval for production deploys (environment protection rules)
+  ├── Deploy to staging first — production only after staging passes
+  ├── Include a rollback step or document the rollback procedure
+  ├── Tag releases with version numbers after successful deploy
+  ├── Use concurrency groups to prevent parallel deploys
+  └── Post-deploy: run smoke tests against the deployed environment
+```
+
+**GOOD**
+```yaml
+deploy-production:
+  needs: deploy-staging
+  runs-on: ubuntu-latest
+  environment:
+    name: production
+    url: https://app.example.com
+  concurrency:
+    group: deploy-production
+    cancel-in-progress: false
+```
+
+---
+
+## 7. Notifications and Artifacts
+
+```
+RECOMMENDED:
+  ├── Upload test results and coverage as artifacts
+  ├── Notify on failure (Slack, email) — don't notify on every success
+  ├── Upload build artifacts for deploy jobs to download
+  ├── Set artifact retention days (default 90 is often too long)
+  └── Use job summaries (echo >> $GITHUB_STEP_SUMMARY) for key metrics
+```
+
+---
+
+## 8. Anti-Patterns
+
+```
+NEVER:
+  ├── on: push without branch filters (triggers on every branch)
+  ├── Hardcoded secrets in workflow files
+  ├── @latest or @main for actions — pin versions
+  ├── Jobs without timeout-minutes
+  ├── Skipping cache — wastes minutes on every run
+  ├── Deploy to production without staging gate
+  ├── Single monolithic workflow file (500+ lines)
+  └── Running expensive jobs on PRs from forks without approval
+```
+
+---
+
+## GitHub Actions Verification Checklist
+
+- [ ] Workflows named descriptively with specific triggers
+- [ ] Branch filters on push triggers
+- [ ] Jobs have timeout-minutes set
+- [ ] Dependencies cached (npm, pip, etc.)
+- [ ] Secrets in GitHub Secrets — never hardcoded
+- [ ] Actions pinned to major version or SHA
+- [ ] Deploy requires staging → production progression
+- [ ] Production deploy has environment protection
+- [ ] Concurrency groups prevent parallel deploys
+- [ ] Test artifacts uploaded