@tekyzinc/gsd-t 2.46.11 → 2.50.11

package/templates/stacks/postgresql.md

@@ -0,0 +1,225 @@
+# PostgreSQL Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Naming Conventions
+
+```
+MANDATORY:
+  ├── Tables: snake_case, plural (users, order_items)
+  ├── Columns: snake_case, singular (first_name, created_at)
+  ├── Primary keys: id (UUID preferred over serial for distributed systems)
+  ├── Foreign keys: {referenced_table_singular}_id (user_id, order_id)
+  ├── Indexes: idx_{table}_{columns} (idx_users_email)
+  ├── Constraints: {type}_{table}_{columns} (uq_users_email, fk_orders_user_id)
+  ├── Enums: snake_case singular (user_role, order_status)
+  └── Boolean columns: is_ or has_ prefix (is_active, has_verified_email)
+```
+
+---
+
+## 2. Schema Design
+
+```
+MANDATORY:
+  ├── Every table has: id (PK), created_at (timestamptz DEFAULT now()), updated_at
+  ├── Use timestamptz — NEVER timestamp without time zone
+  ├── Use UUID for primary keys in distributed or API-exposed systems
+  ├── Use appropriate types: text (not varchar), numeric (not float for money)
+  ├── Add NOT NULL constraints by default — allow NULL only with explicit reason
+  ├── Foreign keys with ON DELETE policy (CASCADE, SET NULL, or RESTRICT — choose deliberately)
+  └── NEVER store JSON when a proper relational schema exists — use jsonb only for truly unstructured data
+```
+
+**GOOD**
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  role user_role NOT NULL DEFAULT 'viewer',
+  is_active BOOLEAN NOT NULL DEFAULT true,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT uq_users_email UNIQUE (email)
+);
+```
+
+---
+
+## 3. Migrations
+
+```
+MANDATORY:
+  ├── One migration per change — never combine unrelated schema changes
+  ├── Migrations are forward-only in production — NEVER edit a deployed migration
+  ├── Name format: {timestamp}_{description}.sql (20260325_add_users_table.sql)
+  ├── Every migration must be reversible — include a down/rollback section
+  ├── Test migrations on a copy of production data before deploying
+  └── NEVER use DROP COLUMN or DROP TABLE without user approval (Destructive Action Guard)
+```
+
+---
+
+## 4. Indexing
+
+```
+MANDATORY:
+  ├── Index every foreign key column
+  ├── Index columns used in WHERE, JOIN, and ORDER BY
+  ├── Use partial indexes for common filter patterns: WHERE is_active = true
+  ├── Use composite indexes in query column order (leftmost prefix rule)
+  ├── GIN indexes for jsonb, array, and full-text search columns
+  ├── NEVER create indexes speculatively — profile queries first (EXPLAIN ANALYZE)
+  └── Monitor unused indexes and remove them
+```
+
+**GOOD**
+```sql
+-- Foreign key index
+CREATE INDEX idx_orders_user_id ON orders (user_id);
+
+-- Composite for common query pattern
+CREATE INDEX idx_orders_user_status ON orders (user_id, status);
+
+-- Partial index — only active users
+CREATE INDEX idx_users_active_email ON users (email) WHERE is_active = true;
+
+-- GIN for jsonb queries
+CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
+```
+
+---
+
+## 5. Query Patterns
+
+```
+MANDATORY:
+  ├── Use parameterized queries — NEVER string concatenation for SQL
+  ├── SELECT only the columns you need — NEVER SELECT *
+  ├── Use LIMIT on all user-facing queries — prevent unbounded result sets
+  ├── Use EXISTS instead of COUNT(*) > 0 for existence checks
+  ├── Use CTEs (WITH) for readability — but not for performance (CTEs can be optimization fences)
+  ├── Prefer JOIN over subquery where equivalent
+  └── Always include ORDER BY when results must be deterministic
+```
+
+**BAD**
+```sql
+SELECT * FROM users WHERE name LIKE '%' || $1 || '%';
+SELECT COUNT(*) FROM orders WHERE user_id = $1;  -- just to check existence
+```
+
+**GOOD**
+```sql
+SELECT id, email, display_name FROM users WHERE name ILIKE '%' || $1 || '%' LIMIT 50;
+SELECT EXISTS(SELECT 1 FROM orders WHERE user_id = $1);
+```
+
+---
+
+## 6. Connection Management
+
+```
+MANDATORY:
+  ├── Use connection pooling (PgBouncer, or built-in pool in your ORM/driver)
+  ├── Set pool size based on workload — not unlimited
+  ├── Close/release connections after use — never leak
+  ├── Set statement_timeout on application connections (e.g., 30s)
+  ├── Use read replicas for heavy read workloads
+  └── Serverless: use Supabase connection pooler or PgBouncer — not direct connections
+```
+
+---
+
+## 7. Transactions
+
+```
+MANDATORY:
+  ├── Wrap multi-statement operations in transactions
+  ├── Keep transactions short — don't hold locks while doing I/O
+  ├── Use appropriate isolation level (READ COMMITTED is default — sufficient for most cases)
+  ├── Handle deadlocks with retry logic (up to 3 retries)
+  └── NEVER leave transactions open — always COMMIT or ROLLBACK
+```
+
+---
+
+## 8. Graph-in-SQL Patterns
+
+When implementing graph structures in PostgreSQL (adjacency lists, knowledge graphs, hierarchies):
+
+```
+PATTERNS:
+  ├── Node tables: one table per entity type with UUID primary keys
+  ├── Edge tables (junction): {source}_id + {target}_id + metadata columns
+  │     Add relevance_score, weight, or edge_count for weighted graphs
+  ├── Hierarchies: parent_id self-referencing FK + recursive CTE for traversal
+  ├── Index both sides of every edge table FK
+  ├── Stable seed UUIDs for reproducible deploys (deterministic UUID format)
+  └── In-memory cache (LRU, 5-min TTL) for frequently traversed paths
+```
+
+**Hierarchy traversal — recursive CTE:**
+```sql
+WITH RECURSIVE ancestors AS (
+  SELECT id, name, parent_id, 0 AS depth
+  FROM graph_business_types
+  WHERE id = $1
+  UNION ALL
+  SELECT t.id, t.name, t.parent_id, a.depth + 1
+  FROM graph_business_types t
+  JOIN ancestors a ON t.id = a.parent_id
+)
+SELECT * FROM ancestors ORDER BY depth;
+```
+
+**Weighted edge query:**
+```sql
+SELECT w.id, w.name, e.relevance_score
+FROM graph_edges_bt_workflow e
+JOIN graph_workflows w ON w.id = e.workflow_id
+WHERE e.business_type_id = $1
+ORDER BY e.relevance_score DESC
+LIMIT 8;
+```
+
+**Rules:**
+- Index edge tables on both FK columns
+- Use ON DELETE CASCADE for edges when the node is deleted
+- Consider materialized views for expensive multi-hop traversals
+- For deep graphs (5+ hops), evaluate whether Neo4j is more appropriate
+
+---
+
+## 9. Anti-Patterns
+
+```
+NEVER:
+  ├── SELECT * in application queries
+  ├── String concatenation for SQL — parameterized queries only
+  ├── Unbounded queries without LIMIT
+  ├── timestamp without time zone — always timestamptz
+  ├── float/double for money — use numeric or integer (cents)
+  ├── Storing structured relational data in jsonb
+  ├── Missing indexes on foreign keys
+  ├── Long-running transactions holding locks
+  └── Direct connections from serverless without pooling
+```
+
+---
+
+## PostgreSQL Verification Checklist
+
+- [ ] Naming follows conventions (snake_case, plural tables, singular columns)
+- [ ] Every table has id, created_at, updated_at
+- [ ] timestamptz used — not timestamp
+- [ ] All foreign keys indexed
+- [ ] Parameterized queries only — no string concatenation
+- [ ] All user-facing queries have LIMIT
+- [ ] Connection pooling configured
+- [ ] Migrations are forward-only and reversible
+- [ ] No SELECT * in application code
+- [ ] Graph edges indexed on both FK columns (if applicable)

package/templates/stacks/python.md

@@ -0,0 +1,243 @@
+# Python Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Type Hints
+
+```
+MANDATORY:
+  ├── Type hints on ALL function signatures (params + return)
+  ├── Use built-in generics (list, dict, tuple) — not typing.List etc. (Python 3.9+)
+  ├── Use | for unions — not typing.Union (Python 3.10+)
+  ├── Use dataclasses or Pydantic models for structured data — NEVER raw dicts
+  └── Run mypy or pyright in CI — no untyped public functions
+```
+
+**BAD**
+```python
+def get_users(filters):
+    result = {"users": [], "total": 0}
+    return result
+```
+
+**GOOD**
+```python
+@dataclass
+class UserList:
+    users: list[User]
+    total: int
+
+def get_users(filters: UserFilters) -> UserList:
+    ...
+```
+
+---
+
+## 2. Project Structure
+
+```
+MANDATORY:
+  ├── Use src/ layout for packages — src/{package_name}/
+  ├── Tests mirror source: tests/{module}/test_{file}.py
+  ├── One class per file for major classes — small helpers can share
+  ├── __init__.py exports only the public API
+  └── Config in environment variables or .env — NEVER hardcoded
+```
+
+---
+
+## 3. Data Models
+
+```
+MANDATORY:
+  ├── Use dataclasses for internal data structures
+  ├── Use Pydantic BaseModel for API input/output and validation
+  ├── Use Enums for fixed option sets — NEVER magic strings
+  ├── Frozen dataclasses for immutable value objects
+  └── NEVER pass raw dicts between functions — define a model
+```
+
+**BAD** — `def create_user(data: dict) -> dict:`
+
+**GOOD**
+```python
+class CreateUserRequest(BaseModel):
+    name: str = Field(min_length=2)
+    email: EmailStr
+    role: UserRole  # Enum
+
+class UserResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+    role: UserRole
+    created_at: datetime
+
+def create_user(request: CreateUserRequest) -> UserResponse:
+    ...
+```
+
+---
+
+## 4. Error Handling
+
+```
+MANDATORY:
+  ├── Define custom exception hierarchy per domain — NEVER raise bare Exception
+  ├── Catch specific exceptions — NEVER bare except: or except Exception:
+  ├── Use try/except at boundaries (API handlers, CLI entry) — not deep in logic
+  ├── Log exceptions with context (structlog or logging) before re-raising
+  └── Return error types or raise — NEVER return None to signal failure
+```
+
+**BAD**
+```python
+try:
+    result = do_something()
+except:
+    return None
+```
+
+**GOOD**
+```python
+class UserNotFoundError(DomainError):
+    def __init__(self, user_id: str):
+        super().__init__(f"User {user_id} not found")
+        self.user_id = user_id
+
+try:
+    user = user_repo.get(user_id)
+except UserNotFoundError:
+    logger.warning("user_not_found", user_id=user_id)
+    raise
+```
+
+---
+
+## 5. Functions and Methods
+
+```
+MANDATORY:
+  ├── Max 30 lines per function — split if longer
+  ├── Max 200 lines per file — create new modules if needed
+  ├── Single responsibility — one function does one thing
+  ├── Use keyword arguments for functions with 3+ parameters
+  ├── Default mutable arguments are FORBIDDEN — use None + factory
+  └── Docstrings on public functions only — skip for obvious private methods
+```
+
+**BAD** — `def register(name, email, role, send_email=True, template=[], notify=[]):`
+
+**GOOD**
+```python
+def register(
+    *,
+    name: str,
+    email: str,
+    role: UserRole,
+    send_email: bool = True,
+    template: list[str] | None = None,
+    notify: list[str] | None = None,
+) -> User:
+    template = template or []
+    notify = notify or []
+    ...
+```
+
+---
+
+## 6. Async Patterns
+
+```
+WHEN USING ASYNC:
+  ├── async def for I/O-bound operations (HTTP, DB, file) — not CPU-bound
+  ├── Use asyncio.gather for concurrent I/O — not sequential awaits
+  ├── NEVER mix sync and async — use run_in_executor for sync libraries
+  ├── Always set timeouts on external calls (httpx, aiohttp)
+  └── Use async context managers for connections and sessions
+```
+
+**BAD** — sequential awaits for independent calls:
+```python
+users = await get_users()
+orders = await get_orders()  # waits for users to finish first
+```
+
+**GOOD**
+```python
+users, orders = await asyncio.gather(get_users(), get_orders())
+```
+
+---
+
+## 7. Testing
+
+```
+MANDATORY:
+  ├── pytest as the test runner — not unittest
+  ├── Use fixtures for setup/teardown — not setUp/tearDown methods
+  ├── Use parametrize for testing multiple inputs
+  ├── Test file naming: test_{module}.py
+  ├── Test function naming: test_{behavior}_when_{condition}
+  └── Assert with plain assert — not self.assertEqual
+```
+
+**GOOD**
+```python
+@pytest.fixture
+def user_service(db_session: Session) -> UserService:
+    return UserService(db_session)
+
+@pytest.mark.parametrize("role,expected", [
+    (UserRole.ADMIN, True),
+    (UserRole.VIEWER, False),
+])
+def test_can_delete_when_role(user_service: UserService, role: UserRole, expected: bool):
+    assert user_service.can_delete(role) == expected
+```
+
+---
+
+## 8. Dependencies and Imports
+
+```
+MANDATORY:
+  ├── Use virtual environments (venv, poetry, uv) — NEVER install globally
+  ├── Pin dependencies in requirements.txt or pyproject.toml
+  ├── Import order: stdlib → third-party → local (enforced by isort/ruff)
+  ├── Use absolute imports for cross-module — relative for same-package
+  └── NEVER import * — explicit imports only
+```
+
+---
+
+## 9. Anti-Patterns
+
+```
+NEVER:
+  ├── Bare except: or except Exception: without re-raise
+  ├── Mutable default arguments (def f(items=[]))
+  ├── Global mutable state — use dependency injection
+  ├── String concatenation for SQL — use parameterized queries
+  ├── print() for logging — use logging/structlog
+  ├── Raw dicts as function params or return types
+  ├── Nested functions deeper than 2 levels
+  └── Type: ignore without explanation comment
+```
+
+---
+
+## Python Verification Checklist
+
+- [ ] Type hints on all function signatures
+- [ ] Pydantic or dataclass for all structured data — no raw dicts
+- [ ] Custom exceptions — no bare Exception raises
+- [ ] Functions under 30 lines, files under 200 lines
+- [ ] No mutable default arguments
+- [ ] pytest with fixtures — no unittest patterns
+- [ ] Import order enforced (stdlib → third-party → local)
+- [ ] No print() in committed code — use logging
+- [ ] Virtual environment with pinned dependencies
+- [ ] No string-formatted SQL — parameterized queries only

package/templates/stacks/react-native.md

@@ -0,0 +1,216 @@
+# React Native Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. State Management — React Query + Zustand
+
+```
+MANDATORY:
+  ├── React Query (TanStack Query) for ALL server data — NEVER useEffect + fetch
+  ├── Zustand for client-side global state (auth, theme, navigation state)
+  ├── useState for local UI state only (toggles, form inputs)
+  ├── NEVER store server data in useState or Zustand — it belongs in the query cache
+  └── Set staleTime explicitly on all queries
+```
+
+**GOOD**
+```tsx
+// Server data → React Query
+const { data: users } = useQuery({
+  queryKey: ['users'],
+  queryFn: api.getUsers,
+  staleTime: 5 * 60 * 1000,
+});
+
+// Client state → Zustand
+const useAuthStore = create<AuthState>((set) => ({
+  token: null,
+  setToken: (token) => set({ token }),
+  logout: () => set({ token: null }),
+}));
+```
+
+---
+
+## 2. Component Design
+
+```
+MANDATORY:
+  ├── Max 150 lines per component — extract sub-components
+  ├── Use FlatList for all dynamic lists — NEVER ScrollView with .map()
+  ├── Separate screen components (screens/) from reusable components (components/)
+  ├── One component per file
+  ├── No business logic in JSX — compute above the return
+  └── Use custom hooks for complex logic (useXxx)
+```
+
+**BAD**
+```tsx
+<ScrollView>
+  {items.map(item => <ItemRow key={item.id} item={item} />)}
+</ScrollView>
+```
+
+**GOOD**
+```tsx
+<FlatList
+  data={items}
+  keyExtractor={(item) => item.id}
+  renderItem={({ item }) => <ItemRow item={item} />}
+  ListEmptyComponent={<EmptyState />}
+/>
+```
+
+---
+
+## 3. Navigation — React Navigation
+
+```
+MANDATORY:
+  ├── Use React Navigation (not react-native-router-flux, not expo-router for bare RN)
+  ├── Type all navigation params with RootStackParamList
+  ├── Define all routes in a central navigation config
+  ├── Deep linking config in the navigator — not hardcoded in components
+  └── Handle auth flow with conditional navigator (logged in → app, else → auth)
+```
+
+**GOOD**
+```tsx
+type RootStackParamList = {
+  Home: undefined;
+  UserDetail: { userId: string };
+  Settings: undefined;
+};
+
+const Stack = createNativeStackNavigator<RootStackParamList>();
+
+function AppNavigator() {
+  const { isLoggedIn } = useAuth();
+  return (
+    <Stack.Navigator>
+      {isLoggedIn ? (
+        <>
+          <Stack.Screen name="Home" component={HomeScreen} />
+          <Stack.Screen name="UserDetail" component={UserDetailScreen} />
+        </>
+      ) : (
+        <Stack.Screen name="Login" component={LoginScreen} />
+      )}
+    </Stack.Navigator>
+  );
+}
+```
+
+---
+
+## 4. Styling
+
+```
+MANDATORY:
+  ├── Use StyleSheet.create for all styles — NEVER inline style objects
+  ├── Co-locate styles at the bottom of the component file
+  ├── Use a theme object for colors, spacing, typography — NEVER hardcode
+  ├── Responsive: use useWindowDimensions or percentage-based layouts
+  └── Platform-specific styles via Platform.select or .ios.tsx/.android.tsx files
+```
+
+**BAD** — `<View style={{ padding: 16, backgroundColor: '#f5f5f5' }}>`
+
+**GOOD**
+```tsx
+const styles = StyleSheet.create({
+  container: {
+    padding: theme.spacing.md,
+    backgroundColor: theme.colors.surface,
+  },
+});
+```
+
+---
+
+## 5. Performance
+
+```
+MANDATORY:
+  ├── FlatList with keyExtractor — NEVER ScrollView for lists
+  ├── Use React.memo on list item components
+  ├── useCallback for renderItem and event handlers passed to FlatList
+  ├── Avoid anonymous functions in props of list items
+  ├── Use react-native-fast-image for image caching
+  ├── Minimize bridge calls — batch state updates
+  └── Profile with Flipper or React DevTools before optimizing
+```
+
+---
+
+## 6. Platform Differences
+
+```
+MANDATORY:
+  ├── Test on BOTH iOS and Android before marking complete
+  ├── Use Platform.OS checks sparingly — prefer cross-platform components
+  ├── Handle safe areas with SafeAreaView or useSafeAreaInsets
+  ├── Handle keyboard: KeyboardAvoidingView (behavior differs per platform)
+  ├── Permissions: request at point of use, explain why, handle denial gracefully
+  └── Status bar: manage with StatusBar component — don't assume default
+```
+
+---
+
+## 7. Offline and Networking
+
+```
+WHEN APPLICABLE:
+  ├── React Query's built-in cache for offline reads
+  ├── Use @react-native-community/netinfo for connectivity detection
+  ├── Show offline indicator — don't silently fail
+  ├── Queue mutations when offline, replay when online
+  └── Set reasonable timeouts on all network requests
+```
+
+---
+
+## 8. Error Handling
+
+```
+MANDATORY:
+  ├── Global error boundary at the app root — never a blank crash screen
+  ├── Per-screen error boundaries for isolated failures
+  ├── Handle loading, error, and empty states for every data fetch
+  ├── Crash reporting (Sentry, Bugsnag) in production builds
+  └── User-friendly error messages — not raw error strings
+```
+
+---
+
+## 9. Anti-Patterns
+
+```
+NEVER:
+  ├── ScrollView with .map() for dynamic lists (use FlatList)
+  ├── Inline style objects (use StyleSheet.create)
+  ├── useEffect for data fetching (use React Query)
+  ├── Hardcoded colors/spacing — use theme
+  ├── console.log in committed code
+  ├── Ignoring platform differences — test on both
+  ├── Ignoring keyboard avoidance — forms become unusable
+  └── Large images without caching — use FastImage
+```
+
+---
+
+## React Native Verification Checklist
+
+- [ ] React Query for server data — no useEffect + fetch
+- [ ] FlatList for all dynamic lists — no ScrollView + map
+- [ ] Components under 150 lines
+- [ ] StyleSheet.create for all styles — no inline objects
+- [ ] Theme object for colors/spacing — no hardcoded values
+- [ ] React Navigation with typed params
+- [ ] Loading, error, and empty states handled
+- [ ] Tested on both iOS and Android
+- [ ] Safe areas and keyboard avoidance handled
+- [ ] No console.log in committed code
+- [ ] Error boundaries at root and per-screen