@tekyzinc/gsd-t 2.46.11 → 2.50.10

package/templates/stacks/vue.md

@@ -0,0 +1,189 @@
+# Vue Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Composition API
+
+```
+MANDATORY:
+  ├── Use <script setup> (Composition API) — NEVER Options API for new code
+  ├── Use ref() for primitives, reactive() for objects
+  ├── Use computed() for derived values — NEVER store derived data in ref
+  ├── Use composables (useXxx) for reusable logic — extract from components
+  └── NEVER use this. — Composition API doesn't use it
+```
+
+**BAD** — Options API:
+```vue
+<script>
+export default {
+  data() { return { count: 0 }; },
+  methods: { increment() { this.count++; } },
+};
+</script>
+```
+
+**GOOD** — Composition API:
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+const count = ref(0);
+const increment = () => count.value++;
+</script>
+```
+
+---
+
+## 2. State Management — Pinia
+
+```
+MANDATORY:
+  ├── Pinia for global state — not Vuex
+  ├── One store per domain (useUserStore, useCartStore)
+  ├── Use Setup Stores syntax (function-based) — matches Composition API
+  ├── Server data: prefer VueQuery (@tanstack/vue-query) — not Pinia
+  └── NEVER mutate store state directly from components — use actions
+```
+
+**GOOD**
+```typescript
+export const useAuthStore = defineStore('auth', () => {
+  const user = ref<User | null>(null);
+  const isLoggedIn = computed(() => !!user.value);
+
+  async function login(credentials: LoginCredentials) {
+    user.value = await authService.login(credentials);
+  }
+
+  function logout() {
+    user.value = null;
+  }
+
+  return { user, isLoggedIn, login, logout };
+});
+```
+
+---
+
+## 3. Component Design
+
+```
+MANDATORY:
+  ├── Max 150 lines per SFC — extract sub-components
+  ├── <script setup> → <template> → <style scoped> order
+  ├── One component per .vue file
+  ├── Props: use defineProps with TypeScript interface
+  ├── Emits: use defineEmits with TypeScript
+  ├── Use v-bind shorthand (:prop) and v-on shorthand (@event)
+  └── No business logic in templates — compute in <script setup>
+```
+
+**GOOD**
+```vue
+<script setup lang="ts">
+interface Props {
+  title: string;
+  variant?: 'primary' | 'secondary';
+}
+const props = withDefaults(defineProps<Props>(), {
+  variant: 'primary',
+});
+const emit = defineEmits<{
+  (e: 'close'): void;
+  (e: 'submit', data: FormData): void;
+}>();
+</script>
+```
+
+---
+
+## 4. Routing — Vue Router
+
+```
+MANDATORY:
+  ├── Centralized route definitions in router/index.ts
+  ├── Lazy load route components — () => import('./views/XxxView.vue')
+  ├── Use named routes for navigation — NEVER hardcode paths in components
+  ├── Navigation guards for auth in router.beforeEach — not in components
+  ├── Type route params with defineProps or useRoute().params
+  └── Always have a catch-all 404 route: { path: '/:pathMatch(.*)*' }
+```
+
+---
+
+## 5. Template Rules
+
+```
+MANDATORY:
+  ├── v-if over v-show for rarely toggled content (v-show for frequent toggles)
+  ├── NEVER use v-if and v-for on the same element — wrap in <template v-if>
+  ├── Use :key on all v-for — stable unique IDs, not array index
+  ├── Emit events up, pass props down — NEVER mutate props
+  ├── Use <slot> for composable component APIs — not excessive props
+  └── Use <Teleport> for modals/toasts — not DOM hacks
+```
+
+**BAD** — v-if + v-for on same element:
+```vue
+<li v-for="user in users" v-if="user.active" :key="user.id">
+```
+
+**GOOD**
+```vue
+<template v-for="user in users" :key="user.id">
+  <li v-if="user.active">{{ user.name }}</li>
+</template>
+```
+
+Or better — use a computed:
+```typescript
+const activeUsers = computed(() => users.value.filter(u => u.active));
+```
+
+---
+
+## 6. Composables (Custom Hooks)
+
+```
+MANDATORY:
+  ├── Name: useXxx (useAuth, useUsers, useDebounce)
+  ├── File location: composables/ directory
+  ├── Return reactive refs and functions — consumers decide how to use them
+  ├── Handle cleanup in onUnmounted — don't leak timers or listeners
+  └── One concern per composable
+```
+
+---
+
+## 7. Anti-Patterns
+
+```
+NEVER:
+  ├── Options API in new code (use Composition API + <script setup>)
+  ├── Vuex in new code (use Pinia)
+  ├── v-if + v-for on the same element
+  ├── Mutating props — emit events instead
+  ├── $refs for parent-child communication — use props/emits
+  ├── Direct DOM manipulation (document.querySelector) — use template refs
+  ├── Watchers for derived data — use computed()
+  ├── console.log in committed code
+  └── this. in <script setup> — it doesn't exist
+```
+
+---
+
+## Vue Verification Checklist
+
+- [ ] Composition API with `<script setup>` — no Options API
+- [ ] Pinia for global state — no Vuex
+- [ ] VueQuery for server data (if applicable)
+- [ ] Props defined with TypeScript interfaces via defineProps
+- [ ] Emits defined with TypeScript via defineEmits
+- [ ] Components under 150 lines
+- [ ] Route components lazy loaded
+- [ ] No v-if + v-for on same element
+- [ ] Stable :key on all v-for — no array index
+- [ ] Auth handled in router guards — not components
+- [ ] No console.log in committed code

package/templates/stacks/zustand.md

@@ -0,0 +1,203 @@
+# Zustand Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Store Structure
+
+```
+MANDATORY:
+  ├── One store per domain: useAuthStore, useCartStore, useUIStore
+  ├── Zustand for CLIENT state only — use React Query for server data
+  ├── Define store interface with TypeScript
+  ├── Group related state and actions together
+  ├── Export a single custom hook per store
+  └── NEVER create a single global store for everything
+```
+
+**GOOD**
+```typescript
+interface AuthState {
+  user: User | null;
+  token: string | null;
+  isAuthenticated: boolean;
+  login: (credentials: LoginCredentials) => Promise<void>;
+  logout: () => void;
+  setUser: (user: User) => void;
+}
+
+export const useAuthStore = create<AuthState>()((set, get) => ({
+  user: null,
+  token: null,
+  isAuthenticated: false,
+
+  login: async (credentials) => {
+    const { user, token } = await authService.login(credentials);
+    set({ user, token, isAuthenticated: true });
+  },
+
+  logout: () => {
+    set({ user: null, token: null, isAuthenticated: false });
+  },
+
+  setUser: (user) => set({ user }),
+}));
+```
+
+---
+
+## 2. Selectors — Minimize Re-renders
+
+```
+MANDATORY:
+  ├── Select only what the component needs — NEVER use the entire store
+  ├── Use individual selectors for each piece of state
+  ├── Create reusable selector hooks for common patterns
+  └── Use shallow equality for object selections
+```
+
+**BAD** — triggers re-render on ANY store change:
+```typescript
+const store = useAuthStore();
+```
+
+**GOOD** — only re-renders when user changes:
+```typescript
+const user = useAuthStore((state) => state.user);
+const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
+
+// For multiple values, use shallow:
+import { useShallow } from 'zustand/react/shallow';
+const { user, isAuthenticated } = useAuthStore(
+  useShallow((state) => ({ user: state.user, isAuthenticated: state.isAuthenticated }))
+);
+```
+
+---
+
+## 3. Actions and Updates
+
+```
+MANDATORY:
+  ├── Actions defined inside create() — not as external functions
+  ├── Use set() for state updates — NEVER mutate state directly
+  ├── Use get() to read current state inside actions
+  ├── Async actions: handle loading/error inside the action
+  └── Partial updates: set() merges by default — only pass changed fields
+```
+
+**GOOD**
+```typescript
+addItem: (item) => set((state) => ({
+  items: [...state.items, item],
+  total: state.total + item.price,
+})),
+
+removeItem: (itemId) => set((state) => ({
+  items: state.items.filter(i => i.id !== itemId),
+})),
+```
+
+---
+
+## 4. Middleware
+
+```
+WHEN NEEDED:
+  ├── persist: for localStorage/sessionStorage persistence
+  ├── devtools: for Redux DevTools integration (dev only)
+  ├── immer: for mutable-style updates on complex nested state
+  ├── Stack middleware with proper TypeScript: create<State>()(devtools(persist(...)))
+  └── Configure persist with a unique name and version for migration support
+```
+
+**GOOD**
+```typescript
+export const useCartStore = create<CartState>()(
+  devtools(
+    persist(
+      (set, get) => ({
+        items: [],
+        addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+        clear: () => set({ items: [] }),
+      }),
+      {
+        name: 'cart-storage',
+        version: 1,
+      }
+    ),
+    { name: 'CartStore' }
+  )
+);
+```
+
+---
+
+## 5. Slices Pattern (Large Stores)
+
+```
+WHEN A STORE GROWS BEYOND 10 ACTIONS:
+  ├── Split into slices — each slice manages a subset of state
+  ├── Combine slices in a single create() call
+  ├── Each slice has its own interface
+  └── Slices can read other slices via get()
+```
+
+**GOOD**
+```typescript
+interface UserSlice {
+  user: User | null;
+  setUser: (user: User) => void;
+}
+
+interface SettingsSlice {
+  theme: 'light' | 'dark';
+  toggleTheme: () => void;
+}
+
+const createUserSlice: StateCreator<UserSlice & SettingsSlice, [], [], UserSlice> = (set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+});
+
+const createSettingsSlice: StateCreator<UserSlice & SettingsSlice, [], [], SettingsSlice> = (set) => ({
+  theme: 'light',
+  toggleTheme: () => set((state) => ({ theme: state.theme === 'light' ? 'dark' : 'light' })),
+});
+
+export const useAppStore = create<UserSlice & SettingsSlice>()((...args) => ({
+  ...createUserSlice(...args),
+  ...createSettingsSlice(...args),
+}));
+```
+
+---
+
+## 6. Anti-Patterns
+
+```
+NEVER:
+  ├── Store server data in Zustand — use React Query
+  ├── Use the entire store without selectors — causes unnecessary re-renders
+  ├── One mega-store for the whole app — split by domain
+  ├── Mutate state directly (state.items.push(x)) without immer middleware
+  ├── Access store outside React without getState() (useStore.getState())
+  ├── Derive state that could be computed — compute in selectors
+  └── console.log in store actions
+```
+
+---
+
+## Zustand Verification Checklist
+
+- [ ] One store per domain — no mega-stores
+- [ ] Client state only — server data in React Query
+- [ ] Typed with TypeScript interfaces
+- [ ] Selectors used — no full-store subscriptions
+- [ ] useShallow for multi-value selections
+- [ ] Actions defined inside create()
+- [ ] persist middleware configured with name and version
+- [ ] devtools enabled in development
+- [ ] No direct state mutation without immer
+- [ ] No console.log in store code