create-win-project 1.4.0 → 2.0.0

package/library/optional-features/concerns/zod.md

@@ -1,174 +0,0 @@
-# Zod + React Hook Form — Validation
-
-> **When to use:** Any project with forms or untrusted input (API responses, URL params, env vars).
-
----
-
-# 1. Schema First, Always
-
-Write the Zod schema before writing the form component or service. The schema is the source of truth.
-
-```ts
-// features/auth/schemas/login.schema.ts
-import { z } from 'zod'
-
-export const loginSchema = z.object({
-  email: z.string().email('Invalid email address'),
-  password: z.string().min(8, 'Password must be at least 8 characters'),
-})
-
-export type LoginInput = z.infer<typeof loginSchema>
-```
-
-Never write a separate TypeScript type for form data — infer it from the schema.
-
----
-
-# 2. Schema Placement
-
-```text
-Feature-specific form?           → features/[name]/schemas/[name].schema.ts
-Shared across multiple features? → src/schemas/[name].schema.ts  (web)
-                                   schemas/[name].schema.ts       (RN)
-API response shape?              → features/[name]/types.ts (type only, no runtime parse needed)
-                                   OR parse with z.safeParse() at the API boundary if strict
-```
-
----
-
-# 3. Web Form (React Hook Form)
-
-```tsx
-// features/auth/components/LoginForm.tsx
-'use client' // Next.js only — omit for React Vite
-import { useForm } from 'react-hook-form'
-import { zodResolver } from '@hookform/resolvers/zod'
-import { loginSchema, type LoginInput } from '../schemas/login.schema'
-
-export function LoginForm({ onSubmit }: { onSubmit: (data: LoginInput) => void }) {
-  const {
-    register,
-    handleSubmit,
-    formState: { errors, isSubmitting },
-  } = useForm<LoginInput>({ resolver: zodResolver(loginSchema) })
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <input {...register('email')} placeholder="Email" />
-      {errors.email && <span>{errors.email.message}</span>}
-
-      <input type="password" {...register('password')} placeholder="Password" />
-      {errors.password && <span>{errors.password.message}</span>}
-
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? 'Submitting...' : 'Login'}
-      </button>
-    </form>
-  )
-}
-```
-
----
-
-# 4. React Native Form (React Hook Form + Controller)
-
-React Native has no native `<input>` — use `Controller` to bridge RHF with RN's `TextInput`.
-
-```tsx
-// features/auth/components/LoginForm.tsx  (React Native)
-import { Controller, useForm } from 'react-hook-form'
-import { zodResolver } from '@hookform/resolvers/zod'
-import { loginSchema, type LoginInput } from '../schemas/login.schema'
-
-export function LoginForm({ onSubmit }: { onSubmit: (data: LoginInput) => void }) {
-  const {
-    control,
-    handleSubmit,
-    formState: { errors, isSubmitting },
-  } = useForm<LoginInput>({ resolver: zodResolver(loginSchema) })
-
-  return (
-    <View className="gap-4">
-      <Controller
-        control={control}
-        name="email"
-        render={({ field }) => (
-          <TextInput
-            value={field.value}
-            onChangeText={field.onChange}
-            placeholder="Email"
-            keyboardType="email-address"
-            autoCapitalize="none"
-          />
-        )}
-      />
-      {errors.email && <Text>{errors.email.message}</Text>}
-
-      <Controller
-        control={control}
-        name="password"
-        render={({ field }) => (
-          <TextInput
-            value={field.value}
-            onChangeText={field.onChange}
-            placeholder="Password"
-            secureTextEntry
-          />
-        )}
-      />
-      {errors.password && <Text>{errors.password.message}</Text>}
-
-      <PrimaryButton
-        title={isSubmitting ? 'Submitting...' : 'Login'}
-        onPress={handleSubmit(onSubmit)}
-        disabled={isSubmitting}
-      />
-    </View>
-  )
-}
-```
-
----
-
-# 5. Validating API Responses
-
-Parse untrusted data at the boundary, not deep in hooks or components.
-
-```ts
-// features/products/services/productService.ts
-import { z } from 'zod'
-
-const productSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  price: z.number(),
-})
-
-export async function getProduct(id: string) {
-  const raw = await apiClient.get(`/products/${id}`)
-  return productSchema.parse(raw) // throws if shape is wrong
-}
-```
-
----
-
-# 6. Rules
-
-- Schema first — always write the schema before the form.
-- Never write a separate TypeScript type for form input — use `z.infer<typeof schema>`.
-- Validate on the server too (or in the service) — never trust client-only validation.
-- Use `z.string().min(1)` not `z.string().nonempty()` — better cross-platform compatibility.
-- Route on `error.code` after submission, never on `error.message`.
-
----
-
-# 7. Agent Quick Reference
-
-```text
-New form?                    → schema first in features/[name]/schemas/
-                             → useForm + zodResolver
-                             → web: register(); RN: Controller + TextInput
-New type for form data?      → z.infer<typeof schema> instead
-Validate API response?       → z.safeParse() or schema.parse() in service
-Shared schema?               → src/schemas/ or schemas/ (not in features/)
-```

package/library/optional-features/styling/css-modules/css-modules-extensions.md

@@ -1,267 +0,0 @@
-# Styling: CSS Modules — Extensions
-
-Extends your existing CSS Modules playbook with missing patterns.
-
----
-
-## Dark Mode with CSS Variables
-```css
-/* styles/tokens.css — single source of truth */
-:root {
-  /* Colors */
-  --color-background: #ffffff;
-  --color-foreground: #0a0a0a;
-  --color-primary: #1a1a2e;
-  --color-primary-foreground: #f0f0f0;
-  --color-muted: #f5f5f5;
-  --color-muted-foreground: #737373;
-  --color-border: #e5e5e5;
-  --color-error: #dc2626;
-  --color-success: #16a34a;
-
-  /* Typography */
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.125rem;
-  --font-size-xl: 1.25rem;
-  --font-size-2xl: 1.5rem;
-
-  /* Spacing */
-  --space-1: 0.25rem;
-  --space-2: 0.5rem;
-  --space-3: 0.75rem;
-  --space-4: 1rem;
-  --space-6: 1.5rem;
-  --space-8: 2rem;
-
-  /* Radius */
-  --radius-sm: 0.25rem;
-  --radius-md: 0.375rem;
-  --radius-lg: 0.5rem;
-
-  /* Transitions */
-  --transition-fast: 100ms ease;
-  --transition-base: 200ms ease;
-  --transition-slow: 500ms ease;
-}
-
-[data-theme="dark"] {
-  --color-background: #0a0a0a;
-  --color-foreground: #f0f0f0;
-  --color-primary: #e0e0f0;
-  --color-primary-foreground: #1a1a2e;
-  --color-muted: #1a1a1a;
-  --color-muted-foreground: #a3a3a3;
-  --color-border: #262626;
-}
-```
-
-```typescript
-// app/providers.tsx — apply theme to root
-import { useEffect, useState } from 'react'
-
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setTheme] = useState<'light' | 'dark'>('light')
-
-  useEffect(() => {
-    document.documentElement.setAttribute('data-theme', theme)
-  }, [theme])
-
-  return <>{children}</>
-}
-```
-
----
-
-## Component Pattern with Tokens
-```css
-/* components/ui/Button/Button.module.css */
-.button {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: var(--space-2) var(--space-4);
-  font-size: var(--font-size-base);
-  border-radius: var(--radius-md);
-  transition: background-color var(--transition-base);
-  cursor: pointer;
-}
-
-.primary {
-  background-color: var(--color-primary);
-  color: var(--color-primary-foreground);
-}
-
-.primary:hover {
-  opacity: 0.9;
-}
-
-.ghost {
-  background-color: transparent;
-  color: var(--color-foreground);
-  border: 1px solid var(--color-border);
-}
-
-.ghost:hover {
-  background-color: var(--color-muted);
-}
-
-.disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-  pointer-events: none;
-}
-```
-
----
-
-## clsx for Class Composition
-```typescript
-// Install: npm install clsx
-import clsx from 'clsx'
-import styles from './Button.module.css'
-
-export function Button({ variant = 'primary', disabled, className }: ButtonProps) {
-  return (
-    <button
-      className={clsx(
-        styles.button,
-        styles[variant],
-        disabled && styles.disabled,
-        className   // allow external class override
-      )}
-      disabled={disabled}
-    >
-      {children}
-    </button>
-  )
-}
-```
-
----
-
-## Responsive in Module File
-```css
-/* UserCard.module.css */
-.card {
-  display: flex;
-  flex-direction: column;
-  padding: var(--space-4);
-}
-
-/* Responsive stays in the component's own module file */
-@media (min-width: 768px) {
-  .card {
-    flex-direction: row;
-    padding: var(--space-6);
-  }
-}
-
-@media (min-width: 1024px) {
-  .card {
-    max-width: 800px;
-  }
-}
-```
-
----
-
-## Animation
-```css
-/* Define @keyframes in component module if component-specific */
-/* Define in global.css if reused across components */
-
-/* Component-specific */
-@keyframes fadeIn {
-  from { opacity: 0; transform: translateY(-8px); }
-  to   { opacity: 1; transform: translateY(0); }
-}
-
-.dropdown {
-  animation: fadeIn var(--transition-base);
-}
-
-/* Reused animation → globals.css */
-@keyframes spin {
-  to { transform: rotate(360deg); }
-}
-```
-
----
-
-## Never Mix Tailwind + CSS Modules on Same Element
-```typescript
-// ❌ mixing both on same element
-<div className={clsx(styles.card, 'flex items-center')} />
-
-// ✅ pick one strategy per project (defined at init)
-// CSS Modules project → all styling via modules
-<div className={styles.card} />
-
-// Tailwind project → all styling via Tailwind
-<div className="flex items-center gap-4 rounded-md" />
-```
-
----
-
-## Global Styles Structure
-```
-src/styles/
-  tokens.css      → CSS variables (colors, space, type, radius)
-  globals.css     → reset, base elements, @import tokens
-  animations.css  → reusable @keyframes (optional)
-```
-
-```css
-/* globals.css */
-@import './tokens.css';
-
-*, *::before, *::after {
-  box-sizing: border-box;
-  margin: 0;
-  padding: 0;
-}
-
-body {
-  background-color: var(--color-background);
-  color: var(--color-foreground);
-  font-size: var(--font-size-base);
-  line-height: 1.5;
-}
-
-a {
-  color: inherit;
-  text-decoration: none;
-}
-```
-
----
-
-## Agent Quick Reference (Extended)
-```
-Dark mode?
-  → [data-theme="dark"] on html element
-  → CSS variables in tokens.css, overrides in [data-theme="dark"]
-  → Toggle via data-theme attribute, not class swap
-
-Conditional classes?
-  → clsx(styles.base, condition && styles.variant)
-  → Never string template literals
-
-Responsive?
-  → @media queries in component's own .module.css
-  → Mobile styles first (no query), then @media (min-width: ...)
-
-Animation?
-  → Component-specific: @keyframes in component module
-  → Reused: @keyframes in globals.css or animations.css
-  → Duration: always use --transition-* tokens
-
-New token needed?
-  → Add to tokens.css under correct section
-  → Never hardcode values in component modules
-
-External class override allowed?
-  → Accept className prop, pass to clsx as last arg
-  → Allows parent to extend without modifying component
-```

package/library/universal/coding-rules/coding-rules.md

@@ -1,281 +0,0 @@
-# Coding Rules (Universal)
-
-Applies to every project regardless of stack.
-
----
-
-## Core Principle
-```
-simple + explicit + consistent
-over
-complex + abstract + theoretically pure
-```
-
-Complexity must earn abstraction. Start simple. Add layers only when justified.
-
----
-
-## Naming
-
-### Files
-```
-React components:   PascalCase    UserCard.tsx
-Hooks:              camelCase     useUserData.ts
-Utilities:          camelCase     formatDate.ts
-Constants:          camelCase     apiEndpoints.ts
-Types:              camelCase     userTypes.ts
-CSS Modules:        PascalCase    UserCard.module.css
-Java classes:       PascalCase    UserService.java
-SQL migrations:     snake_case    V1__create_users_table.sql
-```
-
-### Variables and Functions
-```
-Variables:          camelCase     userName, isLoading, hasError
-Functions:          camelCase     getUser(), createOrder(), formatDate()
-Constants:          SCREAMING     MAX_RETRIES, API_BASE_URL
-React components:   PascalCase    UserCard, LoginForm
-Types/Interfaces:   PascalCase    UserResponse, ApiError
-Enums:              PascalCase    UserRole, OrderStatus
-```
-
-### Name for what it does, not what it is
-```
-❌ getData(), handleThing(), doStuff(), temp, x
-✅ getUserById(), handleLoginSubmit(), formatCurrency()
-```
-
-### Boolean naming
-```
-❌ user, loading, error
-✅ isLoading, hasError, isAuthenticated, canEdit
-```
-
----
-
-## Functions
-- One responsibility per function
-- Max 3 parameters — if more, use an options object
-- Return early to avoid deep nesting
-
-```typescript
-// ❌
-function processUser(user, role, permissions, sendEmail, notify) { ... }
-
-// ✅
-function processUser(user: User, options: ProcessUserOptions) { ... }
-
-// ❌ deep nesting
-function getUser(id) {
-  if (id) {
-    if (isValid(id)) {
-      // logic
-    }
-  }
-}
-
-// ✅ early return
-function getUser(id) {
-  if (!id) return null
-  if (!isValid(id)) return null
-  // logic
-}
-```
-
----
-
-## Imports
-
-### Frontend
-- Always use absolute imports with `@/` prefix
-- Never use relative `../../` imports
-- Barrel exports (`index.ts`) for public API of a feature only
-
-```typescript
-// ❌
-import { UserCard } from '../../../components/ui/UserCard'
-
-// ✅
-import { UserCard } from '@/components/ui/UserCard'
-```
-
-### Import Order (enforced by ESLint)
-```
-1. External libraries
-2. Internal absolute (@/)
-3. Types
-4. Styles / assets
-```
-
----
-
-## Constants
-- No magic numbers or strings in logic
-- All constants in `src/constants/index.ts` or feature-level constants file
-
-```typescript
-// ❌
-if (role === 'ADMIN') { ... }
-setTimeout(fn, 900000)
-
-// ✅
-import { ROLES, TOKEN_EXPIRY } from '@/constants'
-if (role === ROLES.ADMIN) { ... }
-setTimeout(fn, TOKEN_EXPIRY.ACCESS)
-```
-
----
-
-## Async / Error Handling
-
-### Frontend
-- Always async/await — never `.then()` chains
-- Always handle errors at the hook level, not component level
-- Never swallow errors silently
-
-```typescript
-// ❌
-fetchUser().then(data => setUser(data)).catch(e => console.log(e))
-
-// ✅
-try {
-  const user = await fetchUser()
-  setUser(user)
-} catch (error) {
-  logger.error('fetchUser failed:', error)
-  throw error
-}
-```
-
-### Backend
-- Always throw `AppException` — never raw `RuntimeException`
-- Never expose stack traces in API responses
-- Always catch at the `GlobalExceptionHandler` level
-
-```java
-// ❌
-throw new RuntimeException("User not found");
-
-// ✅
-throw new AppException("USER_NOT_FOUND", HttpStatus.NOT_FOUND);
-```
-
----
-
-## Logging
-- NEVER use `console.log` directly
-- Always use `lib/logger.ts` on frontend
-- Always use SLF4J logger on backend
-
-```typescript
-// ❌
-console.log('user:', user)
-console.error('error:', error)
-
-// ✅
-import { logger } from '@/lib/logger'
-logger.info('user fetched:', user)
-logger.error('fetch failed:', error)
-```
-
-```java
-// ❌
-System.out.println("user: " + user);
-
-// ✅
-private static final Logger log = LoggerFactory.getLogger(UserService.class);
-log.info("user fetched: {}", userId);
-log.error("fetch failed for userId: {}", userId, e);
-```
-
----
-
-## Comments
-- Comment WHY, not WHAT
-- Code should be readable enough to not need WHAT comments
-- Remove all debug/TODO comments before committing
-
-```typescript
-// ❌ explains what (obvious from code)
-// increment counter
-count++
-
-// ✅ explains why (not obvious from code)
-// Retry once — server returns 503 on cold start for ~200ms
-await retry(fetchUser, { times: 1, delay: 300 })
-```
-
----
-
-## No Debug Code in Commits
-```
-❌ console.log
-❌ debugger
-❌ TODO comments
-❌ hardcoded test values
-❌ commented-out code blocks
-```
-
-ESLint and Husky enforce this — build fails if present.
-
----
-
-## One Thing Per File
-```
-❌ UserCardAndForm.tsx — two components in one file
-❌ userUtils.ts — 30 unrelated utility functions
-
-✅ UserCard.tsx
-✅ UserForm.tsx
-✅ formatDate.ts
-✅ formatCurrency.ts
-```
-
-Exception: small helper types or constants directly related to the file.
-
----
-
-## Exports
-
-### Frontend
-- Named exports everywhere except page/route components
-- Page components use default export (Next.js / React Router requirement)
-
-```typescript
-// ❌ default export for reusable components
-export default function UserCard() { ... }
-
-// ✅ named export
-export function UserCard() { ... }
-
-// ✅ default export for pages only
-export default function UserPage() { ... }
-```
-
-### Backend
-- Spring-managed beans: `@Service`, `@Repository`, `@RestController` — Spring handles export
-- Utility classes: `public static` methods
-
----
-
-## Agent Rules
-```
-Before writing any code:
-  1. Check if the functionality already exists
-  2. Check which layer owns this responsibility
-  3. Choose the simplest correct implementation
-  4. Follow existing patterns in the codebase — don't introduce new ones
-
-Before creating a new file:
-  1. Check if an existing file should be extended instead
-  2. Follow the selected stack's structure playbook and current feature ownership
-
-Before adding a dependency:
-  1. Check if existing tools already solve it
-  2. Prefer what the playbook recommends over personal preference
-
-Naming:
-  1. Name things for what they do
-  2. Booleans start with is/has/can
-  3. No abbreviations unless universally understood (id, url, dto)
-```