@tekyzinc/gsd-t 2.46.11 → 2.50.10

package/templates/stacks/supabase.md

@@ -0,0 +1,188 @@
+# Supabase Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Row Level Security (RLS)
+
+```
+MANDATORY:
+  ├── Enable RLS on EVERY table — no exceptions
+  ├── Default-deny: tables with RLS enabled and no policies block all access
+  ├── Write policies per role: anon, authenticated, service_role
+  ├── Use auth.uid() for user-scoped policies — NEVER trust client-sent user IDs
+  ├── Test policies with different roles before deploying
+  └── Service role bypasses RLS — only use server-side, NEVER expose the service key
+```
+
+**GOOD**
+```sql
+ALTER TABLE user_profiles ENABLE ROW LEVEL SECURITY;
+
+-- Users can read their own profile
+CREATE POLICY "Users read own profile"
+  ON user_profiles FOR SELECT
+  USING (auth.uid() = user_id);
+
+-- Users can update their own profile
+CREATE POLICY "Users update own profile"
+  ON user_profiles FOR UPDATE
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+```
+
+---
+
+## 2. Auth Patterns
+
+```
+MANDATORY:
+  ├── Use Supabase Auth — don't build custom auth alongside it
+  ├── Store user metadata in a separate profiles table — not in auth.users
+  ├── Create profile on signup via database trigger or auth hook
+  ├── Use auth.uid() in RLS policies — it's the trusted source of identity
+  ├── Handle auth state changes with onAuthStateChange listener
+  └── NEVER store the service_role key in client code — it bypasses RLS
+```
+
+**GOOD** — trigger to create profile:
+```sql
+CREATE OR REPLACE FUNCTION handle_new_user()
+RETURNS TRIGGER AS $$
+BEGIN
+  INSERT INTO user_profiles (user_id, email, display_name)
+  VALUES (NEW.id, NEW.email, COALESCE(NEW.raw_user_meta_data->>'display_name', ''));
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+CREATE TRIGGER on_auth_user_created
+  AFTER INSERT ON auth.users
+  FOR EACH ROW EXECUTE FUNCTION handle_new_user();
+```
+
+---
+
+## 3. Client Usage
+
+```
+MANDATORY:
+  ├── Initialize client once — export from a shared module
+  ├── Use typed client with generated types: supabase-js + supabase gen types
+  ├── Handle errors from every Supabase call — check { data, error } response
+  ├── Use .select() with specific columns — NEVER .select('*') in production
+  ├── Use .single() when expecting one row — throws if 0 or 2+ rows
+  └── Regenerate types after every migration: npx supabase gen types typescript
+```
+
+**GOOD**
+```typescript
+const { data, error } = await supabase
+  .from('user_profiles')
+  .select('id, email, display_name, role')
+  .eq('user_id', userId)
+  .single();
+
+if (error) throw new DatabaseError('Failed to fetch profile', error);
+```
+
+---
+
+## 4. Edge Functions
+
+```
+MANDATORY:
+  ├── Use for server-side logic that needs secrets or external API calls
+  ├── Validate ALL inputs — edge functions are public endpoints
+  ├── Use Zod or manual validation at the entry point
+  ├── Set CORS headers explicitly
+  ├── Handle errors with proper HTTP status codes
+  └── Keep functions focused — one concern per function
+```
+
+---
+
+## 5. Realtime
+
+```
+WHEN USING REALTIME:
+  ├── Enable realtime only on tables that need it — not all tables
+  ├── Subscribe with filters to reduce message volume
+  ├── Unsubscribe on component unmount — prevent memory leaks
+  ├── Handle reconnection gracefully
+  └── RLS applies to realtime — users only receive rows they can SELECT
+```
+
+**GOOD**
+```typescript
+const channel = supabase
+  .channel('user-orders')
+  .on('postgres_changes',
+    { event: 'INSERT', schema: 'public', table: 'orders', filter: `user_id=eq.${userId}` },
+    (payload) => handleNewOrder(payload.new)
+  )
+  .subscribe();
+
+// Cleanup
+return () => { supabase.removeChannel(channel); };
+```
+
+---
+
+## 6. Storage
+
+```
+MANDATORY:
+  ├── Create separate buckets per use case (avatars, documents, uploads)
+  ├── Set bucket-level access policies (public vs private)
+  ├── Validate file type and size before upload — client AND server side
+  ├── Use signed URLs for private file access — not public URLs
+  ├── Set file size limits per bucket
+  └── NEVER store sensitive documents in public buckets
+```
+
+---
+
+## 7. Migrations
+
+```
+MANDATORY:
+  ├── Use supabase db diff or manual SQL files for migrations
+  ├── One migration per change — don't combine unrelated changes
+  ├── Test migrations locally: supabase db reset
+  ├── Always regenerate types after migration: supabase gen types typescript
+  ├── Include RLS policies in migration files — not applied manually
+  └── Seed data in a separate seed.sql file
+```
+
+---
+
+## 8. Anti-Patterns
+
+```
+NEVER:
+  ├── Expose service_role key to client — it bypasses RLS
+  ├── Tables without RLS enabled
+  ├── .select('*') in production queries
+  ├── Trusting client-sent user IDs — use auth.uid()
+  ├── Storing user data in auth.users metadata instead of a profiles table
+  ├── Realtime on all tables — enable selectively
+  ├── Ignoring { error } from Supabase calls
+  └── Manual SQL in Supabase dashboard instead of migration files
+```
+
+---
+
+## Supabase Verification Checklist
+
+- [ ] RLS enabled on every table with explicit policies
+- [ ] auth.uid() used in policies — no client-sent user IDs trusted
+- [ ] Service role key only used server-side
+- [ ] Typed client with generated types (supabase gen types)
+- [ ] Specific column selects — no .select('*')
+- [ ] Error handling on every Supabase call
+- [ ] Realtime subscriptions cleaned up on unmount
+- [ ] Storage buckets have access policies and file limits
+- [ ] Migrations in version control — not manual dashboard SQL
+- [ ] Types regenerated after every migration

package/templates/stacks/tailwind.md

@@ -0,0 +1,169 @@
+# Tailwind CSS Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Class-Only Styling
+
+```
+MANDATORY:
+  ├── Tailwind utility classes ONLY — no inline styles, no CSS modules, no styled-components
+  ├── Exception: CSS variables for theme tokens (e.g., bg-[var(--brand-primary)])
+  ├── Exception: Animations that require @keyframes — define in tailwind.config or globals.css
+  └── NEVER mix Tailwind with other CSS methodologies in the same project
+```
+
+**BAD** — `<div style={{ padding: '16px', color: 'red' }}>`
+
+**GOOD** — `<div className="p-4 text-red-500">`
+
+---
+
+## 2. Responsive Design — Mobile First
+
+```
+MANDATORY:
+  ├── Default styles target mobile — add breakpoints for larger screens
+  ├── Breakpoint order: base → sm: → md: → lg: → xl: → 2xl:
+  ├── NEVER use max-width breakpoints — always min-width (Tailwind default)
+  └── Test at each breakpoint — don't assume intermediate sizes work
+```
+
+**BAD** — Desktop-first: `<div className="flex lg:flex max-lg:block">`
+
+**GOOD** — Mobile-first: `<div className="block md:flex">`
+
+---
+
+## 3. Component Extraction Over @apply
+
+```
+MANDATORY:
+  ├── Extract repeated utility patterns into components — NOT @apply classes
+  ├── @apply is allowed ONLY in global base styles (body, headings, links)
+  ├── Use a cn() helper for conditional classes
+  └── NEVER create .btn, .card, etc. utility classes — make components instead
+```
+
+**BAD** — `@apply` in CSS:
+```css
+.btn-primary { @apply px-4 py-2 bg-blue-500 text-white rounded; }
+```
+
+**GOOD** — React component:
+```tsx
+function Button({ children, variant = 'primary', className }: ButtonProps) {
+  return (
+    <button className={cn(
+      'px-4 py-2 rounded font-medium transition-colors',
+      variant === 'primary' && 'bg-blue-500 text-white hover:bg-blue-600',
+      variant === 'ghost' && 'bg-transparent hover:bg-gray-100',
+      className
+    )}>
+      {children}
+    </button>
+  );
+}
+```
+
+---
+
+## 4. The cn() Helper
+
+```
+MANDATORY:
+  ├── Use a cn() or clsx() utility for conditional and merged classes
+  ├── For Tailwind merge conflicts, use tailwind-merge (twMerge)
+  └── Standard pattern: cn = (...classes) => twMerge(clsx(...classes))
+```
+
+```typescript
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+---
+
+## 5. Color and Theme System
+
+```
+MANDATORY:
+  ├── Define colors as CSS variables — not hardcoded Tailwind colors
+  ├── Use semantic names (--color-primary, --color-surface) — not visual (--blue-500)
+  ├── Support dark mode via CSS variables or Tailwind dark: prefix
+  ├── NEVER use arbitrary color values ([#ff6b35]) — add to theme config
+  └── Opacity modifiers via Tailwind (text-primary/80) — not rgba
+```
+
+**GOOD** — `tailwind.config.js`:
+```js
+theme: {
+  extend: {
+    colors: {
+      primary: 'var(--color-primary)',
+      surface: 'var(--color-surface)',
+      border: 'var(--color-border)',
+    },
+  },
+}
+```
+
+---
+
+## 6. Spacing and Layout
+
+```
+MANDATORY:
+  ├── Use Tailwind spacing scale (p-4, gap-3, m-2) — not arbitrary values
+  ├── Use Flexbox (flex) or Grid (grid) for layout — not floats or absolute positioning
+  ├── gap-* for spacing between flex/grid children — not margins on children
+  ├── Consistent spacing: pick a scale (4px base) and stick to it
+  └── Arbitrary values ([17px]) only when matching a design spec exactly
+```
+
+---
+
+## 7. Dark Mode
+
+```
+WHEN SUPPORTING DARK MODE:
+  ├── Use class strategy (darkMode: 'class') for user-controlled toggling
+  ├── Apply dark: variants alongside base styles — not in separate files
+  ├── Test both modes — don't assume dark is just "invert colors"
+  └── Ensure sufficient contrast in both modes (WCAG AA: 4.5:1 for text)
+```
+
+**GOOD** — `<div className="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">`
+
+---
+
+## 8. Anti-Patterns
+
+```
+NEVER:
+  ├── Inline styles alongside Tailwind classes
+  ├── @apply for component-level styles — make components instead
+  ├── Arbitrary values when a Tailwind scale value exists (p-[16px] → p-4)
+  ├── !important via ! prefix — fix specificity instead
+  ├── Overly long class strings (15+ utilities) — extract a component
+  ├── Hardcoded colors ([#hex]) — add to theme config
+  └── Margin on grid/flex children for spacing — use gap-* on parent
+```
+
+---
+
+## Tailwind Verification Checklist
+
+- [ ] No inline styles — Tailwind classes only
+- [ ] Mobile-first responsive (base → sm → md → lg)
+- [ ] Repeated patterns extracted to components — not @apply
+- [ ] cn() helper used for conditional classes
+- [ ] Colors defined as CSS variables / theme config — no hardcoded hex
+- [ ] Spacing uses Tailwind scale — minimal arbitrary values
+- [ ] Dark mode tested (if applicable)
+- [ ] No class strings longer than ~15 utilities — component extracted

package/templates/stacks/typescript.md

@@ -0,0 +1,176 @@
+# TypeScript Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Strict Mode
+
+`tsconfig.json` MUST have `"strict": true`. Never disable strict flags to silence errors — fix the code.
+
+```
+MANDATORY:
+  ├── "strict": true in tsconfig.json
+  ├── Never use `any` — use `unknown` for truly unknown types, then narrow
+  ├── Never use the `object` type — use a specific interface or Record<K, V>
+  └── Never leave function params or return values untyped (no implicit any)
+```
+
+```ts
+// BAD
+function process(data: any) { return data.value; }
+
+// GOOD — unknown forces narrowing before use
+function process(data: unknown): string {
+  if (typeof data === 'object' && data !== null && 'value' in data) {
+    return String((data as { value: unknown }).value);
+  }
+  throw new Error('Unexpected data shape');
+}
+```
+
+---
+
+## 2. Interface vs Type
+
+```
+USE INTERFACE: object shapes, extendable contracts, class implementations
+USE TYPE:      unions, intersections, utility types, mapped/conditional types
+```
+
+```ts
+// GOOD
+interface User { id: string; name: string; email: string; }
+interface AdminUser extends User { permissions: string[]; }
+type UserRole = 'admin' | 'editor' | 'viewer';
+type UserSummary = Pick<User, 'id' | 'name'>;
+```
+
+---
+
+## 3. Generic Components
+
+```ts
+// GOOD — reusable generic table avoids per-type duplication
+interface DataTableProps<T> {
+  data: T[];
+  columns: Array<{ key: keyof T; label: string }>;
+  onRowClick: (row: T) => void;
+}
+function DataTable<T>({ data, columns, onRowClick }: DataTableProps<T>) { /* ... */ }
+```
+
+---
+
+## 4. Zod Schema-Driven Validation
+
+Zod schemas are the single source of truth for runtime validation AND TypeScript types. Never define a type separately when a Zod schema already defines the shape.
+
+```ts
+import { z } from 'zod';
+
+// GOOD — schema drives both validation and type
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'editor', 'viewer']),
+});
+type User = z.infer<typeof UserSchema>;  // derive — never duplicate
+
+// BAD — separate type diverges from schema over time
+type User = { id: string; email: string; role: string };
+```
+
+Use Zod for: form validation, API response parsing, env variable validation, config files.
+
+---
+
+## 5. Error Typing
+
+```ts
+// BAD
+try { /* ... */ } catch (e: any) { console.log(e.message); }
+
+// GOOD — narrow unknown before use
+try { /* ... */ } catch (error: unknown) {
+  if (error instanceof Error) console.error(error.message);
+  else console.error('Unknown error', error);
+}
+```
+
+---
+
+## 6. Enums for Fixed Option Sets
+
+```ts
+// GOOD — union for simple status flags
+type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';
+
+// GOOD — enum when iteration or key mapping is needed
+enum Direction { Up = 'UP', Down = 'DOWN', Left = 'LEFT', Right = 'RIGHT' }
+
+// BAD — magic strings scattered through codebase (typos never caught)
+if (status === 'pndng') { /* ... */ }
+```
+
+---
+
+## 7. Import Ordering
+
+```ts
+// 1. React / framework
+import React, { useState } from 'react';
+// 2. Third-party libraries
+import { z } from 'zod';
+// 3. Shared / internal aliases
+import { Button } from '@/components/ui/Button';
+// 4. Local / relative
+import { formatDate } from './utils';
+import type { UserFilters } from './types';
+```
+
+---
+
+## 8. Naming Conventions
+
+| Item                  | Convention              | Example              |
+|-----------------------|-------------------------|----------------------|
+| React components      | PascalCase              | `UserList.tsx`       |
+| Hooks                 | camelCase + `use`       | `useAuth.ts`         |
+| Services              | camelCase + `Service`   | `userService.ts`     |
+| Types / Interfaces    | PascalCase              | `User`, `UserFilters`|
+| Constants             | UPPER_SNAKE_CASE        | `API_BASE_URL`       |
+| Non-component files   | camelCase               | `helpers.ts`         |
+| Folders               | kebab-case              | `user-profile/`      |
+| CSS classes           | kebab-case              | `.user-card`         |
+| Boolean props/state   | `is`/`has`/`can` prefix | `isLoading`          |
+| Event handler fns     | `handle` prefix         | `handleSubmit`       |
+| Callback props        | `on` prefix             | `onSuccess`          |
+
+```ts
+// GOOD
+const isLoading = true;
+function handleSubmit(e: React.FormEvent) { /* ... */ }
+<Form onSubmit={handleSubmit} />
+
+// BAD
+const loading = true;
+function submitForm() { /* ... */ }
+<Form submitHandler={submitForm} />
+```
+
+---
+
+## Pre-Commit TypeScript Checklist
+
+- [ ] `"strict": true` in `tsconfig.json`
+- [ ] No `any` — `unknown` with narrowing used instead
+- [ ] No bare `object` type — specific interfaces or `Record<K,V>` only
+- [ ] Interfaces for object shapes; types for unions/utilities
+- [ ] Zod schemas drive both validation and types via `z.infer`
+- [ ] Caught errors narrowed before access (`instanceof Error` check)
+- [ ] Enums or union types for all fixed option sets — no magic strings
+- [ ] Imports ordered: React → third-party → shared → local
+- [ ] Boolean props/state use `is`/`has`/`can` prefix
+- [ ] Event handlers use `handle` prefix; callback props use `on` prefix
+- [ ] All files, components, hooks, and services follow naming conventions

package/templates/stacks/vite.md

@@ -0,0 +1,176 @@
+# Vite Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Environment Variables
+
+```
+MANDATORY:
+  ├── Prefix ALL client-exposed env vars with VITE_ — Vite strips others
+  ├── Access via import.meta.env.VITE_* — NEVER process.env (that's Node, not Vite)
+  ├── Commit .env.development and .env.production — no secrets in either
+  ├── Add .env.local to .gitignore — developer-specific overrides only
+  └── NEVER put API keys or secrets in VITE_ vars — they're bundled into client code
+```
+
+**BAD**
+```typescript
+const url = process.env.API_URL;           // undefined in browser
+const key = import.meta.env.VITE_API_KEY;  // secret exposed to client!
+```
+
+**GOOD**
+```typescript
+// .env.development
+// VITE_API_BASE_URL=http://localhost:4000/api
+
+// src/lib/constants.ts
+export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:4000/api';
+```
+
+---
+
+## 2. Config File
+
+```
+MANDATORY:
+  ├── vite.config.ts (TypeScript) — not .js
+  ├── Define resolve.alias for clean imports (@/ → src/)
+  ├── Configure server.proxy for API calls in dev — avoid CORS issues
+  ├── Set build.sourcemap to true for staging, false for production
+  └── Keep plugins list minimal — each plugin adds build time
+```
+
+**GOOD**
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: { '@': path.resolve(__dirname, 'src') },
+  },
+  server: {
+    proxy: {
+      '/api': { target: 'http://localhost:4000', changeOrigin: true },
+    },
+  },
+});
+```
+
+---
+
+## 3. Build Optimization
+
+```
+MANDATORY:
+  ├── Code-split route-level components with React.lazy (or framework equivalent)
+  ├── Configure manualChunks for large vendor libs (react, lodash, chart libs)
+  ├── Check bundle size: npx vite-bundle-visualizer after build
+  ├── Tree-shaking: use named imports — not default imports from barrel files
+  └── Set chunk size warning limit in config if needed
+```
+
+**GOOD** — manual chunks:
+```typescript
+build: {
+  rollupOptions: {
+    output: {
+      manualChunks: {
+        vendor: ['react', 'react-dom'],
+        query: ['@tanstack/react-query'],
+      },
+    },
+  },
+},
+```
+
+---
+
+## 4. Path Aliases and Imports
+
+```
+MANDATORY:
+  ├── Configure @/ alias in vite.config.ts AND tsconfig.json (both must match)
+  ├── Use @/ for cross-feature imports — relative for same-directory
+  ├── NEVER use deep relative paths (../../../shared/lib/helpers)
+  └── Barrel exports (index.ts) for feature public APIs — not for internal modules
+```
+
+**tsconfig.json** must match:
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  }
+}
+```
+
+---
+
+## 5. Dev Server
+
+```
+MANDATORY:
+  ├── Use server.proxy for backend API — NEVER hardcode localhost URLs in fetch calls
+  ├── Enable server.open only if desired — don't force it
+  ├── HMR should work — if it doesn't, check file naming (PascalCase components)
+  └── For HTTPS in dev: use @vitejs/plugin-basic-ssl — not self-signed certs
+```
+
+---
+
+## 6. Testing Integration
+
+```
+MANDATORY:
+  ├── Use Vitest (not Jest) — it shares Vite's config and transform pipeline
+  ├── Configure test block in vite.config.ts or vitest.config.ts
+  ├── Set environment: 'jsdom' for component tests
+  ├── Use the same path aliases in tests — Vitest inherits from vite.config
+  └── Happy-dom is faster than jsdom — use if no compatibility issues
+```
+
+**GOOD**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: './src/test-setup.ts',
+  },
+});
+```
+
+---
+
+## 7. Anti-Patterns
+
+```
+NEVER:
+  ├── process.env in client code (use import.meta.env)
+  ├── Secrets in VITE_ env vars — they're in the bundle
+  ├── Jest when Vitest is available — Vitest is faster and shares config
+  ├── Deep relative imports (../../..) — use @/ alias
+  ├── Importing entire libraries (import _ from 'lodash') — use named (import { debounce })
+  └── Disabling HMR to "fix" issues — find the root cause
+```
+
+---
+
+## Vite Verification Checklist
+
+- [ ] All client env vars prefixed with VITE_
+- [ ] No secrets in VITE_ variables
+- [ ] import.meta.env used — not process.env
+- [ ] Path alias @/ configured in both vite.config.ts and tsconfig.json
+- [ ] server.proxy configured for API calls
+- [ ] Bundle analyzed — no oversized chunks
+- [ ] Vitest configured (not Jest)
+- [ ] .env.local in .gitignore