@tekyzinc/gsd-t 2.46.11 → 2.50.11

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

package/templates/stacks/graphql.md

@@ -0,0 +1,216 @@
+# GraphQL Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Schema Design
+
+```
+MANDATORY:
+  ├── Schema-first design — define the schema, then implement resolvers
+  ├── Use PascalCase for types: User, OrderItem
+  ├── Use camelCase for fields: firstName, createdAt
+  ├── Use UPPER_SNAKE_CASE for enum values: ACTIVE, PENDING_REVIEW
+  ├── Input types for mutations: CreateUserInput, UpdateOrderInput
+  ├── Every mutation returns the affected type (not just Boolean)
+  └── Add descriptions to all types and fields — they power documentation
+```
+
+**GOOD**
+```graphql
+"""A registered user in the system."""
+type User {
+  id: ID!
+  """User's display name."""
+  displayName: String!
+  email: String!
+  role: UserRole!
+  orders(first: Int = 20, after: String): OrderConnection!
+  createdAt: DateTime!
+}
+
+enum UserRole {
+  ADMIN
+  MEMBER
+  VIEWER
+}
+
+input CreateUserInput {
+  displayName: String!
+  email: String!
+  role: UserRole = MEMBER
+}
+```
+
+---
+
+## 2. Query Design
+
+```
+MANDATORY:
+  ├── Singular for single resource: user(id: ID!): User
+  ├── Plural for collections: users(first: Int, after: String, filter: UserFilter): UserConnection!
+  ├── Use connection pattern (Relay) for paginated lists
+  ├── Accept filter input types — not individual filter args
+  ├── NEVER return unbounded lists — always require pagination args
+  └── Nullable return for single lookups (user may not exist)
+```
+
+**GOOD**
+```graphql
+type Query {
+  user(id: ID!): User
+  users(first: Int = 20, after: String, filter: UserFilter): UserConnection!
+}
+
+input UserFilter {
+  role: UserRole
+  isActive: Boolean
+  search: String
+}
+
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  endCursor: String
+}
+```
+
+---
+
+## 3. Mutation Design
+
+```
+MANDATORY:
+  ├── Verb-first naming: createUser, updateOrder, deleteComment
+  ├── Accept a single input argument: createUser(input: CreateUserInput!): User!
+  ├── Return the mutated object — not Boolean or generic status
+  ├── Use union types for error handling (preferred) or throw errors
+  ├── Validate inputs in resolvers — schema types are not sufficient
+  └── Mutations must be idempotent where possible
+```
+
+**GOOD**
+```graphql
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): User!
+  deleteUser(id: ID!): DeleteUserPayload!
+}
+
+type CreateUserPayload {
+  user: User
+  errors: [ValidationError!]
+}
+
+type ValidationError {
+  field: String!
+  message: String!
+}
+```
+
+---
+
+## 4. Resolver Patterns
+
+```
+MANDATORY:
+  ├── Thin resolvers — delegate to service/data layer, don't put business logic in resolvers
+  ├── Use DataLoader for N+1 prevention — batch and cache database lookups
+  ├── Auth checks in resolvers or middleware — not in the service layer
+  ├── Return null for not-found, throw for unauthorized/forbidden
+  └── Log errors with context (query name, variables, user ID)
+```
+
+**GOOD**
+```typescript
+const resolvers = {
+  Query: {
+    user: async (_, { id }, { dataSources, user }) => {
+      if (!user) throw new AuthenticationError('Must be logged in');
+      return dataSources.userService.getById(id);
+    },
+  },
+  User: {
+    orders: (parent, args, { dataSources }) =>
+      dataSources.orderLoader.load({ userId: parent.id, ...args }),
+  },
+};
+```
+
+---
+
+## 5. N+1 Prevention — DataLoader
+
+```
+MANDATORY:
+  ├── Use DataLoader for any field that resolves per-item in a list
+  ├── Create loaders per request (new instance in context factory)
+  ├── Batch function receives array of keys, returns array of results in same order
+  └── Cache is request-scoped — not shared between requests
+```
+
+**GOOD**
+```typescript
+const userLoader = new DataLoader<string, User>(async (ids) => {
+  const users = await db.query('SELECT * FROM users WHERE id = ANY($1)', [ids]);
+  const userMap = new Map(users.map(u => [u.id, u]));
+  return ids.map(id => userMap.get(id) ?? new Error(`User ${id} not found`));
+});
+```
+
+---
+
+## 6. Client-Side Patterns
+
+```
+MANDATORY:
+  ├── Co-locate queries with components — query file next to the component
+  ├── Use fragments for shared field selections
+  ├── Name all operations: query GetUser, mutation CreateOrder
+  ├── Use generated types (graphql-codegen) — NEVER manually type query results
+  ├── Handle loading, error, and empty states for every query
+  └── Cache update after mutations: refetch or update cache directly
+```
+
+---
+
+## 7. Anti-Patterns
+
+```
+NEVER:
+  ├── Unbounded list queries without pagination
+  ├── Business logic in resolvers — delegate to services
+  ├── N+1 queries — use DataLoader
+  ├── Anonymous operations (unnamed queries/mutations)
+  ├── Deeply nested queries without depth limiting
+  ├── Returning Boolean from mutations — return the affected type
+  ├── Over-fetching: requesting all fields when you need two
+  └── Manually typing query results — use codegen
+```
+
+---
+
+## GraphQL Verification Checklist
+
+- [ ] Schema-first with descriptions on all types/fields
+- [ ] Connection pattern for paginated lists
+- [ ] All mutations return affected type (not Boolean)
+- [ ] DataLoader used for N+1 prevention
+- [ ] Input validation in resolvers
+- [ ] Auth checks in resolvers or middleware
+- [ ] Operations named (query GetUser, not anonymous)
+- [ ] Generated types via codegen
+- [ ] Loading, error, empty states handled client-side
+- [ ] Query depth limiting configured