@tekyzinc/gsd-t 2.46.11 → 2.50.10

package/templates/stacks/react.md

@@ -0,0 +1,293 @@
+# React Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Server State — React Query
+
+```
+MANDATORY:
+  ├── Use React Query for ALL server data fetching — NEVER useEffect + fetch
+  ├── NEVER store server data in useState — it belongs in the query cache
+  ├── useQuery for reads, useMutation for writes
+  └── Set staleTime explicitly — do not rely on defaults
+```
+
+**BAD** — `useEffect(() => { fetch(...).then(setUsers); }, []);`
+
+**GOOD**
+```tsx
+const { data: users } = useQuery({
+  queryKey: ['users'],
+  queryFn: api.getUsers,
+  staleTime: 5 * 60 * 1000,
+});
+```
+
+---
+
+## 2. Component Design
+
+```
+MANDATORY:
+  ├── Max 150 lines per component file — extract if longer
+  ├── Container/Presenter split: containers fetch data, presenters render UI
+  ├── Extract complex logic into custom hooks (useXxx)
+  ├── One component per file
+  └── No business logic in JSX — compute values above the return statement
+```
+
+**BAD** — 300-line component mixing fetch, transform, and render logic.
+
+**GOOD**
+```tsx
+// Container fetches; Presenter renders
+function UserListContainer() {
+  const { data } = useQuery({ queryKey: ['users'], queryFn: api.getUsers });
+  return <UserList users={data ?? []} />;
+}
+function UserList({ users }: { users: User[] }) {
+  return <ul>{users.map(u => <UserRow key={u.id} user={u} />)}</ul>;
+}
+```
+
+---
+
+## 3. Props Rules
+
+```
+MANDATORY:
+  ├── Define props as TypeScript interfaces
+  ├── Destructure props in the function signature
+  ├── NEVER use defaultProps — use default parameter values instead
+  └── Avoid prop drilling beyond 2 levels — use Context or composition
+```
+
+**GOOD**
+```tsx
+interface ButtonProps { label: string; variant?: 'primary' | 'secondary'; }
+function Button({ label, variant = 'primary' }: ButtonProps) { ... }
+```
+
+---
+
+## 4. Key Prop Rules
+
+```
+MANDATORY:
+  ├── NEVER use array index as key on dynamic (add/remove/reorder) lists
+  ├── Use stable unique IDs from data (item.id, item.slug)
+  └── Never generate keys at render time (Math.random(), Date.now())
+```
+
+**BAD** — `items.map((item, i) => <Row key={i} />)`
+
+**GOOD** — `items.map(item => <Row key={item.id} />)`
+
+---
+
+## 5. Hooks Rules
+
+```
+MANDATORY:
+  ├── Only call hooks at the top level — NEVER inside conditionals or loops
+  ├── NEVER call a hook conditionally — restructure using early JSX returns
+  ├── Custom hooks MUST start with "use" prefix
+  └── One concern per custom hook
+```
+
+**BAD** — `if (isLoggedIn) { const data = useUserData(); }`
+
+**GOOD** — Call `useUserData()` unconditionally; return early in JSX if not logged in.
+
+---
+
+## 6. Memoization
+
+```
+USE SPARINGLY — profile first, optimize second:
+  ├── React.memo: only when parent re-renders often AND child props rarely change
+  ├── useMemo: only for computationally expensive operations (not string/array literals)
+  └── useCallback: only when the function is passed to a memoized child or is a
+        useEffect dependency
+```
+
+**BAD** — `const label = useMemo(() => \`Hello, ${name}\`, [name]);` (trivial — no benefit)
+
+**GOOD** — `const sorted = useMemo(() => items.sort(expensiveSort), [items]);`
+
+---
+
+## 7. Lazy Loading
+
+```
+MANDATORY for route-level components:
+  ├── Wrap with React.lazy() + Suspense
+  ├── Always provide a Suspense fallback (skeleton or spinner — not null)
+  └── Group related routes in one lazy chunk to minimize round trips
+```
+
+```tsx
+const Dashboard = React.lazy(() => import('./Dashboard'));
+<Suspense fallback={<DashboardSkeleton />}><Dashboard /></Suspense>
+```
+
+---
+
+## 8. Error Boundaries
+
+```
+MANDATORY:
+  ├── Wrap every route and major feature section in an ErrorBoundary
+  ├── Display a user-friendly fallback UI — never a blank screen
+  ├── Log to error tracking (Sentry) in componentDidCatch
+  └── Use granular boundaries — one top-level boundary is not enough
+```
+
+---
+
+## 9. Accessibility (a11y)
+
+```
+MANDATORY:
+  ├── Use semantic HTML (button, nav, main, header, section)
+  ├── All interactive elements MUST be keyboard-navigable (Tab, Enter, Escape)
+  ├── Images require alt text (alt="" for decorative)
+  ├── Form inputs MUST have associated <label> (htmlFor + id)
+  ├── Modals: trap focus inside, restore on close, Escape closes
+  ├── Icon-only buttons require aria-label
+  └── NEVER remove focus outlines — style them, never hide them
+```
+
+**BAD** — `<div onClick={del}>Delete</div>` / `<img src={x} />`
+
+**GOOD** — `<button onClick={del} aria-label="Delete">Delete</button>` / `<img src={x} alt="Profile photo" />`
+
+---
+
+## 10. State Management — When to Use What
+
+```
+MANDATORY — choose the right tool for the data type:
+  ├── UI toggles, form inputs          → useState
+  ├── Complex local state (multi-step)  → useReducer
+  ├── Server/API data                   → React Query (NEVER useState)
+  ├── Auth session, permissions         → React Context
+  ├── Theme preference                  → React Context + localStorage
+  └── URL state (page, filters)         → React Router (useSearchParams)
+```
+
+**Rules:**
+- Never duplicate server state in local state — React Query is the single source of truth for API data
+- Lift state only when needed — if two siblings need the same state, lift to parent, not a global store
+- Derive, don't store — if a value can be computed from existing state, compute it
+
+**BAD** — storing derived state:
+```tsx
+const [users, setUsers] = useState(allUsers);
+const [filteredUsers, setFilteredUsers] = useState([]);
+const [userCount, setUserCount] = useState(0);
+```
+
+**GOOD** — derive from source:
+```tsx
+const [filter, setFilter] = useState('all');
+const filteredUsers = useMemo(
+  () => users.filter(u => filter === 'all' || u.status === filter),
+  [users, filter]
+);
+const userCount = filteredUsers.length;
+```
+
+---
+
+## 11. Form Management — react-hook-form + Zod
+
+```
+MANDATORY when project uses forms:
+  ├── One Zod schema per form — schema is the single source of truth for validation
+  ├── Use react-hook-form with zodResolver — NEVER validate in event handlers
+  ├── Show field-level errors below the field — not in a toast
+  ├── Disable submit button while submitting
+  ├── Use noValidate on <form> — browser validation conflicts with custom validation
+  └── Use setError('root', ...) for server-side errors
+```
+
+**GOOD**
+```tsx
+const schema = z.object({
+  email: z.string().email('Enter a valid email'),
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+});
+type FormData = z.infer<typeof schema>;
+
+function MyForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} noValidate>
+      <label htmlFor="email">Email</label>
+      <input id="email" {...register('email')} />
+      {errors.email && <span className="error">{errors.email.message}</span>}
+      <button type="submit" disabled={isSubmitting}>Save</button>
+    </form>
+  );
+}
+```
+
+---
+
+## 12. React Naming Conventions
+
+```
+MANDATORY:
+  ├── Components:      PascalCase          (UserList.tsx, DataTable.tsx)
+  ├── Hooks:           camelCase + use      (useAuth.ts, useUsers.ts)
+  ├── Services:        camelCase + Service  (userService.ts)
+  ├── Event handlers:  handle prefix        (handleClick, handleSubmit)
+  ├── Callback props:  on prefix            (onClick, onClose, onChange)
+  ├── Boolean state:   is/has/can prefix    (isOpen, hasError, canEdit)
+  ├── Folders:         kebab-case           (user-settings/, danger-window/)
+  └── Non-component files: camelCase        (helpers.ts, permissions.ts)
+```
+
+---
+
+## 13. Anti-Patterns
+
+```
+NEVER:
+  ├── useEffect for data fetching (use React Query — Section 1)
+  ├── Prop drilling beyond 2 levels
+  ├── Array index as key on dynamic lists (Section 4)
+  ├── Conditional hook calls (Section 5)
+  ├── Direct state mutation: state.list.push(x) — return new objects/arrays
+  ├── console.log in committed code
+  ├── Derived state in useState when it can be computed (Section 10)
+  ├── Validate forms in event handlers (use react-hook-form + zod — Section 11)
+  └── dangerouslySetInnerHTML without sanitization — see _security.md
+```
+
+---
+
+## React Verification Checklist
+
+- [ ] Server data fetched with React Query — no `useEffect` + fetch
+- [ ] No component exceeds 150 lines
+- [ ] Container/Presenter pattern applied to data-fetching components
+- [ ] All props typed with TypeScript interfaces
+- [ ] No array index as key on dynamic lists
+- [ ] No conditional hook calls
+- [ ] Memoization justified — not preemptive
+- [ ] Route components use `React.lazy` + `Suspense` with a fallback
+- [ ] `ErrorBoundary` wraps each major feature section
+- [ ] All interactive elements keyboard-accessible with ARIA labels
+- [ ] No `console.log` in committed code
+- [ ] No direct state mutations — always return new objects/arrays
+- [ ] `dangerouslySetInnerHTML` usage reviewed against `_security.md`
+- [ ] State tool matches data type (useState/useReducer/Context/React Query/Router)
+- [ ] No derived state in useState — compute from source
+- [ ] Forms use react-hook-form + zod — no manual validation in handlers
+- [ ] React naming conventions followed (handle*, on*, is/has/can)

package/templates/stacks/redux.md

@@ -0,0 +1,193 @@
+# Redux Toolkit Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. RTK Only — No Legacy Redux
+
+```
+MANDATORY:
+  ├── Use @reduxjs/toolkit (RTK) — NEVER raw redux with manual action creators/reducers
+  ├── Use createSlice for all state slices
+  ├── Use configureStore — NEVER createStore
+  ├── Use RTK Query for server data — NEVER manual async thunks for API calls
+  └── Use TypeScript with typed hooks (useAppSelector, useAppDispatch)
+```
+
+---
+
+## 2. Slice Design
+
+```
+MANDATORY:
+  ├── One slice per domain: userSlice, cartSlice, uiSlice
+  ├── Name slices clearly: name: 'auth', name: 'cart'
+  ├── Define state interface with TypeScript
+  ├── Reducers handle one concern — keep them focused
+  ├── Use prepare callbacks for action payload shaping
+  └── Export actions and reducer separately
+```
+
+**GOOD**
+```typescript
+interface AuthState {
+  user: User | null;
+  status: 'idle' | 'loading' | 'succeeded' | 'failed';
+  error: string | null;
+}
+
+const initialState: AuthState = {
+  user: null,
+  status: 'idle',
+  error: null,
+};
+
+const authSlice = createSlice({
+  name: 'auth',
+  initialState,
+  reducers: {
+    setUser: (state, action: PayloadAction<User>) => {
+      state.user = action.payload;
+      state.status = 'succeeded';
+    },
+    logout: (state) => {
+      state.user = null;
+      state.status = 'idle';
+    },
+  },
+});
+
+export const { setUser, logout } = authSlice.actions;
+export default authSlice.reducer;
+```
+
+---
+
+## 3. RTK Query — Server Data
+
+```
+MANDATORY:
+  ├── Use RTK Query for ALL API calls — NEVER createAsyncThunk for data fetching
+  ├── Define one API slice per backend service
+  ├── Use tag-based cache invalidation — not manual cache updates
+  ├── Type all endpoints with request/response types
+  ├── Handle loading, error, and empty states using hook results
+  └── Set keepUnusedDataFor to control cache lifetime
+```
+
+**GOOD**
+```typescript
+export const usersApi = createApi({
+  reducerPath: 'usersApi',
+  baseQuery: fetchBaseQuery({ baseUrl: '/api/v1' }),
+  tagTypes: ['User'],
+  endpoints: (builder) => ({
+    getUsers: builder.query<User[], UserFilters>({
+      query: (filters) => ({ url: '/users', params: filters }),
+      providesTags: ['User'],
+    }),
+    getUser: builder.query<User, string>({
+      query: (id) => `/users/${id}`,
+      providesTags: (result, error, id) => [{ type: 'User', id }],
+    }),
+    createUser: builder.mutation<User, CreateUserInput>({
+      query: (body) => ({ url: '/users', method: 'POST', body }),
+      invalidatesTags: ['User'],
+    }),
+  }),
+});
+
+export const { useGetUsersQuery, useGetUserQuery, useCreateUserMutation } = usersApi;
+```
+
+---
+
+## 4. Store Configuration
+
+```
+MANDATORY:
+  ├── configureStore with typed RootState and AppDispatch
+  ├── Add RTK Query middleware for cache management
+  ├── Create typed hooks: useAppSelector, useAppDispatch
+  ├── Redux DevTools enabled by default in development
+  └── Keep store configuration in a single store.ts file
+```
+
+**GOOD**
+```typescript
+// store.ts
+export const store = configureStore({
+  reducer: {
+    auth: authReducer,
+    cart: cartReducer,
+    [usersApi.reducerPath]: usersApi.reducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().concat(usersApi.middleware),
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+
+// hooks.ts
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+export const useAppDispatch: () => AppDispatch = useDispatch;
+```
+
+---
+
+## 5. Selectors
+
+```
+MANDATORY:
+  ├── Use createSelector (reselect) for derived/computed state
+  ├── Select minimal state — NEVER select the entire slice
+  ├── Co-locate selectors with their slice file
+  ├── Name selectors: select{Thing} (selectActiveUsers, selectCartTotal)
+  └── Memoized selectors for filtered/sorted/computed data
+```
+
+**GOOD**
+```typescript
+// In authSlice.ts
+export const selectUser = (state: RootState) => state.auth.user;
+export const selectIsAuthenticated = (state: RootState) => !!state.auth.user;
+
+// Memoized computed selector
+export const selectActiveUsers = createSelector(
+  [(state: RootState) => state.users.list],
+  (users) => users.filter(u => u.isActive)
+);
+```
+
+---
+
+## 6. Anti-Patterns
+
+```
+NEVER:
+  ├── Raw redux (createStore, manual action types, switch reducers)
+  ├── createAsyncThunk for API calls — use RTK Query
+  ├── Selecting entire slice in a component
+  ├── Storing server data in slices — use RTK Query
+  ├── Mutating state outside of createSlice reducers (Immer only works inside)
+  ├── String action types — use createSlice auto-generated types
+  ├── Dispatching in useEffect for data fetching — use RTK Query hooks
+  └── console.log in reducers
+```
+
+---
+
+## Redux Toolkit Verification Checklist
+
+- [ ] RTK only — no legacy redux patterns
+- [ ] createSlice for all state management
+- [ ] RTK Query for all API calls — no createAsyncThunk for fetching
+- [ ] Tag-based cache invalidation on mutations
+- [ ] Typed store (RootState, AppDispatch, typed hooks)
+- [ ] Selectors with createSelector for computed state
+- [ ] Minimal state selected — no full-slice subscriptions
+- [ ] Store configured with RTK Query middleware
+- [ ] Loading, error, empty states handled via hook results
+- [ ] No console.log in reducers or slices

package/templates/stacks/rest-api.md

@@ -0,0 +1,202 @@
+# REST API Design Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. URL Design
+
+```
+MANDATORY:
+  ├── Nouns, not verbs: /users, /orders — NEVER /getUsers, /createOrder
+  ├── Plural collection names: /users, /products, /orders
+  ├── Nested resources for relationships: /users/{id}/orders
+  ├── Max 2 levels of nesting — flatten beyond that
+  ├── Kebab-case for multi-word paths: /order-items — not /orderItems or /order_items
+  ├── API version in URL path: /api/v1/users — not in headers
+  └── NEVER expose internal IDs or database structure in URLs
+```
+
+**BAD** — `/api/getUserById?id=123`, `/api/v1/order_items`
+
+**GOOD** — `/api/v1/users/123`, `/api/v1/order-items`
+
+---
+
+## 2. HTTP Methods
+
+```
+MANDATORY:
+  ├── GET: Read (no side effects, cacheable)
+  ├── POST: Create new resource (returns 201 + Location header)
+  ├── PUT: Full replace of a resource
+  ├── PATCH: Partial update of a resource
+  ├── DELETE: Remove a resource (returns 204 or 200)
+  ├── GET must NEVER modify data
+  └── POST is not a catch-all — use the correct method
+```
+
+---
+
+## 3. Response Format
+
+```
+MANDATORY — consistent envelope for all responses:
+  ├── Success: { "data": {...} } or { "data": [...] }
+  ├── Collection: { "data": [...], "meta": { "total": N, "page": 1, "pageSize": 20 } }
+  ├── Error: { "error": { "code": "NOT_FOUND", "message": "User not found" } }
+  ├── Use camelCase for JSON keys — matches JavaScript conventions
+  ├── Include timestamps as ISO 8601 strings with timezone (2026-03-25T10:00:00Z)
+  └── Null fields: include with null value — don't omit the key
+```
+
+**GOOD**
+```json
+{
+  "data": {
+    "id": "abc-123",
+    "email": "user@example.com",
+    "displayName": "Jane Doe",
+    "createdAt": "2026-03-25T10:00:00Z",
+    "avatar": null
+  }
+}
+```
+
+---
+
+## 4. Pagination
+
+```
+MANDATORY for all list endpoints:
+  ├── Offset-based: ?page=1&pageSize=20 (simple, good for UI pages)
+  ├── Cursor-based: ?cursor=abc&limit=20 (better for large/realtime datasets)
+  ├── Default pageSize: 20, max pageSize: 100
+  ├── Include pagination metadata in response: total, page, pageSize, hasMore
+  ├── NEVER return unbounded lists — always paginate or limit
+  └── Support sorting: ?sort=createdAt&order=desc
+```
+
+**GOOD**
+```json
+{
+  "data": [...],
+  "meta": {
+    "total": 342,
+    "page": 2,
+    "pageSize": 20,
+    "hasMore": true
+  }
+}
+```
+
+---
+
+## 5. Error Responses
+
+```
+MANDATORY:
+  ├── Use standard HTTP status codes correctly (see table below)
+  ├── Error body includes: code (machine-readable), message (human-readable)
+  ├── Validation errors include field-level details
+  ├── NEVER expose stack traces, SQL errors, or internal paths to clients
+  └── Log the full error server-side — return a safe summary to the client
+```
+
+| Status | Meaning | When to use |
+|--------|---------|------------|
+| 200 | OK | Successful GET, PUT, PATCH, DELETE |
+| 201 | Created | Successful POST (include Location header) |
+| 204 | No Content | Successful DELETE with no response body |
+| 400 | Bad Request | Invalid input, malformed JSON, validation error |
+| 401 | Unauthorized | Missing or invalid authentication |
+| 403 | Forbidden | Authenticated but insufficient permissions |
+| 404 | Not Found | Resource doesn't exist |
+| 409 | Conflict | Duplicate resource, optimistic lock failure |
+| 422 | Unprocessable Entity | Valid JSON but semantic errors |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Unexpected server failure |
+
+**Validation error example:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Must be a valid email address" },
+      { "field": "name", "message": "Must be at least 2 characters" }
+    ]
+  }
+}
+```
+
+---
+
+## 6. Filtering and Search
+
+```
+MANDATORY:
+  ├── Filter via query params: ?status=active&role=admin
+  ├── Search via query param: ?search=jane (server decides which fields to search)
+  ├── Date ranges: ?createdAfter=2026-01-01&createdBefore=2026-03-01
+  ├── Multiple values: ?status=active,pending (comma-separated)
+  ├── NEVER accept raw SQL or query expressions from the client
+  └── Validate and whitelist all filter parameters
+```
+
+---
+
+## 7. Versioning
+
+```
+MANDATORY:
+  ├── Version in URL path: /api/v1/, /api/v2/
+  ├── Bump major version only for breaking changes
+  ├── Support previous version for a deprecation period (minimum 3 months)
+  ├── Document breaking changes in a changelog
+  └── New fields are NOT breaking changes — clients should ignore unknown fields
+```
+
+---
+
+## 8. Rate Limiting
+
+```
+MANDATORY for public APIs:
+  ├── Implement rate limiting per client/API key
+  ├── Return 429 with Retry-After header
+  ├── Include rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
+  └── Different limits per tier (free vs paid) if applicable
+```
+
+---
+
+## 9. Anti-Patterns
+
+```
+NEVER:
+  ├── Verbs in URLs (/getUser, /deleteOrder)
+  ├── GET requests that modify data
+  ├── Exposing internal errors, stack traces, or SQL to clients
+  ├── Unbounded list responses without pagination
+  ├── Inconsistent response shapes between endpoints
+  ├── Accepting raw query expressions from clients
+  ├── Breaking changes without version bump
+  └── 200 OK with error body — use proper status codes
+```
+
+---
+
+## REST API Verification Checklist
+
+- [ ] URLs use nouns, plural, kebab-case
+- [ ] Correct HTTP methods (GET reads, POST creates, etc.)
+- [ ] Consistent response envelope (data, error, meta)
+- [ ] All list endpoints paginated with metadata
+- [ ] Error responses include code + message, no internals exposed
+- [ ] Validation errors include field-level details
+- [ ] API versioned in URL path
+- [ ] Rate limiting with proper headers (if public)
+- [ ] Timestamps in ISO 8601 with timezone
+- [ ] Filtering via whitelisted query params only