create-win-project 1.3.0 → 2.0.0

package/playbooks/universal/git-conventions.md

@@ -1,186 +0,0 @@
-# Git Conventions (Universal)
-
-Applies to every project regardless of stack.
-
----
-
-## Branch Structure
-| Branch       | Purpose                                       |
-|--------------|-----------------------------------------------|
-| `main`       | Production — always stable, always deployable |
-| `dev`        | Integration — all features merge here first   |
-| `feature/*`  | New capability                                |
-| `fix/*`      | Bug fix                                       |
-| `refactor/*` | Restructure without behavior change           |
-| `chore/*`    | Dependencies, config, tooling                 |
-| `docs/*`     | Documentation only                            |
-| `test/*`     | Adding or updating tests only                 |
-
-## Branch Rules
-- NEVER commit directly to `main` or `dev`
-- ALWAYS branch off `dev` — never off `main`
-- NEVER merge or create PRs unless explicitly asked
-- NEVER push to remote unless explicitly asked
-- One logical change per branch — keep branches small and focused
-
-## Starting a Branch
-```bash
-git checkout dev
-git pull origin dev
-git checkout -b <type>/<short-description>
-```
-
-### Examples
-```bash
-git checkout -b feature/user-profile-page
-git checkout -b fix/token-expiry-race
-git checkout -b refactor/auth-feature-module
-git checkout -b chore/update-dependencies
-git checkout -b docs/update-api-endpoints
-```
-
----
-
-## Commit Convention
-
-### Format
-```
-type(scope): short description
-```
-
-### Rules
-- Lowercase only — no uppercase anywhere
-- No period at the end
-- Present tense — "add" not "added", "fix" not "fixed"
-- Under 72 characters
-- One logical change per commit
-
-### Types
-| Type       | When to use                                       |
-|------------|---------------------------------------------------|
-| `feat`     | New feature or capability                         |
-| `fix`      | Bug fix                                           |
-| `refactor` | Restructure without behavior change               |
-| `chore`    | Deps, config, tooling — no production code change |
-| `docs`     | Documentation only                                |
-| `test`     | Adding or updating tests                          |
-| `ci`       | GitHub Actions or CI/CD workflow changes          |
-| `style`    | Formatting, whitespace — no logic change          |
-
-### Scopes (React + Spring Boot)
-| Scope      | When to use                        |
-|------------|------------------------------------|
-| `frontend` | Anything inside /frontend          |
-| `backend`  | Anything inside /backend           |
-| `docker`   | Dockerfile or docker-compose       |
-| `ci`       | GitHub Actions workflows           |
-| `docs`     | Anything inside /docs              |
-| `deps`     | Dependency updates (either side)   |
-
-### Scopes (Next.js projects)
-| Scope      | When to use                        |
-|------------|------------------------------------|
-| `app`      | Next.js app router, pages, layouts |
-| `api`      | API routes or server actions       |
-| `db`       | Database schema, migrations        |
-| `auth`     | Authentication logic               |
-| `ci`       | GitHub Actions workflows           |
-| `docs`     | Anything inside /docs              |
-| `deps`     | Dependency updates                 |
-
-### Examples
-```bash
-feat(frontend): add user profile page
-feat(backend): add paper download endpoint
-fix(backend): resolve token expiry race condition
-fix(frontend): correct redirect after logout
-refactor(backend): move auth logic into feature module
-refactor(frontend): restructure features folder
-chore(deps): update spring boot to 3.5.1
-chore(docker): add maven cache volume
-docs(api): update error contract with traceId field
-test(backend): add unit tests for auth service
-test(frontend): add vitest tests for useAuth hook
-ci(backend): add postgresql service to ci workflow
-```
-
----
-
-## Daily Workflow
-```bash
-# 1. Always start from updated dev
-git checkout dev
-git pull origin dev
-
-# 2. Create your branch
-git checkout -b <type>/<description>
-
-# 3. Work in small, logical commits
-git add .
-git commit -m "type(scope): description"
-
-# 4. Push your branch
-git push origin <branch-name>
-
-# 5. Open PR → dev (only when explicitly asked)
-# 6. Merge dev → main (only when explicitly asked)
-```
-
----
-
-## .gitignore — Always Include
-```
-# Environment
-.env
-.env.local
-.env.production
-
-# Dependencies
-node_modules/
-.mvn/
-
-# Build outputs
-dist/
-build/
-target/
-.next/
-
-# IDE
-.idea/
-.vscode/
-*.iml
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-logs/
-
-# Docker volumes (if local)
-postgres-data/
-```
-
----
-
-## Agent Rules
-```
-Never:
-  → commit directly to main or dev
-  → branch off main
-  → push or create PRs unless explicitly asked
-  → put multiple logical changes in one commit
-  → use vague commit messages ("fix stuff", "update code")
-
-Always:
-  → branch off dev
-  → one logical change per commit
-  → follow type(scope): description format
-  → present tense in commit messages
-
-When asked to commit:
-  → Stage only files relevant to the current task
-  → Write a precise commit message following the convention
-  → Do not push unless explicitly asked
-```

package/playbooks/universal/typescript.manifest.json

@@ -1,11 +0,0 @@
-{
-  "id": "typescript",
-  "kind": "universal",
-  "label": "TypeScript",
-  "required": true,
-  "folders": [],
-  "concerns": [
-    { "id": "typescript-strict", "required": true, "sections": ["Strict Mode — Always On", "No any", "Type vs Interface"] },
-    { "id": "validation", "required": false, "when": "Project validates external/runtime input", "sections": ["Zod for Runtime Validation"] }
-  ]
-}

package/playbooks/universal/typescript.md

@@ -1,272 +0,0 @@
-# TypeScript Rules (Universal)
-
-Applies to every TypeScript project.
-
----
-
-## Strict Mode — Always On
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "exactOptionalPropertyTypes": true
-  }
-}
-```
-
-These flags catch real bugs. Never disable them.
-
----
-
-## No `any`
-- Never use `any` unless absolutely unavoidable
-- When unavoidable: add `// reason:` comment explaining why
-
-```typescript
-// ❌
-const data: any = fetchUser()
-function process(input: any) { ... }
-
-// ✅
-const data: unknown = fetchUser()
-function process(input: UserInput) { ... }
-
-// ✅ justified any with comment
-// reason: third-party library has no types and @types package doesn't exist
-const chart = new (window as any).ChartLib()
-```
-
-### Alternatives to `any`
-| Instead of `any` | Use                     |
-|------------------|-------------------------|
-| Unknown data     | `unknown`               |
-| Flexible object  | `Record<string, unknown>` |
-| Multiple types   | Union `string \| number` |
-| Optional         | `T \| undefined`        |
-| Nullable         | `T \| null`             |
-
----
-
-## Type vs Interface
-```typescript
-// Interface — for objects that may be extended or implemented
-interface User {
-  id: string
-  name: string
-  email: string
-}
-
-// Type — for unions, intersections, primitives, tuples
-type UserId = string
-type UserRole = 'ADMIN' | 'USER' | 'MODERATOR'
-type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
-type UserWithRole = User & { role: UserRole }
-```
-
-### Rule
-- Objects → `interface` (extends naturally, better error messages)
-- Everything else → `type`
-- Never use `I` prefix for interfaces (`IUser` → `User`)
-
----
-
-## Discriminated Unions for State
-```typescript
-// ❌ scattered boolean flags
-type State = {
-  isLoading: boolean
-  isError: boolean
-  isSuccess: boolean
-  data?: User
-  error?: Error
-}
-
-// ✅ discriminated union — mutually exclusive states
-type State =
-  | { status: 'idle' }
-  | { status: 'loading' }
-  | { status: 'success'; data: User }
-  | { status: 'error'; error: Error }
-```
-
----
-
-## Unknown Over Any for Errors
-```typescript
-// ❌
-} catch (error: any) {
-  console.log(error.message)
-}
-
-// ✅
-} catch (error: unknown) {
-  const message = error instanceof Error ? error.message : 'Unknown error'
-  logger.error(message)
-}
-```
-
----
-
-## Generics
-Use when genuinely reusable — not for ceremony.
-
-```typescript
-// ✅ genuinely reusable
-function first<T>(array: T[]): T | undefined {
-  return array[0]
-}
-
-// ✅ reusable operation result inside the application
-type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
-
-// ❌ unnecessary generic
-function getUserName<T extends User>(user: T): string {
-  return user.name
-  // just use: function getUserName(user: User): string
-}
-```
-
----
-
-## Zod for Runtime Validation
-
-Use Zod for runtime validation **when** this project has runtime validation needs (form input, API responses, external data). If the project has no such need, this section does not apply — the rules are optional.
-
-TypeScript types are compile-time only. Use Zod at runtime boundaries.
-
-```typescript
-// Define schema
-const UserSchema = z.object({
-  id: z.string().uuid(),
-  name: z.string().min(1),
-  email: z.string().email(),
-  role: z.enum(['ADMIN', 'USER']),
-})
-
-// Infer type from schema — single source of truth
-type User = z.infer<typeof UserSchema>
-
-// Validate at runtime
-const user = UserSchema.parse(apiResponse.data)
-```
-
-### When to use Zod
-- Form validation (via React Hook Form resolver)
-- API response parsing
-- Environment variable validation (t3-env)
-- Any external data entering the system
-
----
-
-## Where Types Live
-
-### Decision tree
-```
-Is this type used across multiple features?
-  → src/types/[name].ts
-
-Is this type specific to one feature?
-  → src/features/[name]/types/index.ts
-
-Is this type a Zod schema + inferred type?
-  → src/features/[name]/schemas/[name].schema.ts
-
-Is this type shared by several transport clients?
-  → src/types/transport.ts
-```
-
-### Global types (src/types/)
-```typescript
-// src/types/transport.ts
-// Successful endpoints return their normal DTO. Model only genuinely shared shapes.
-export type ProblemDetails = { type: string; title: string; status: number; detail?: string; traceId?: string }
-
-// src/types/pagination.ts
-export type PaginatedResponse<T> = {
-  data: T[]
-  total: number
-  page: number
-  limit: number
-}
-```
-
----
-
-## Type Assertions
-Avoid `as` unless justified.
-
-```typescript
-// ❌ lying to TypeScript
-const user = data as User
-
-// ✅ validate first, then trust
-const user = UserSchema.parse(data)
-
-// ✅ justified assertion with comment
-// reason: DOM ref is always set before this handler fires
-const input = inputRef.current as HTMLInputElement
-```
-
----
-
-## Enums vs Union Types
-Prefer union types over enums for most cases.
-
-```typescript
-// ❌ enum (compiles to weird JS, harder to iterate)
-enum UserRole {
-  ADMIN = 'ADMIN',
-  USER = 'USER',
-}
-
-// ✅ const object + union type (tree-shakeable, readable compiled output)
-export const ROLES = {
-  ADMIN: 'ADMIN',
-  USER: 'USER',
-} as const
-
-export type UserRole = typeof ROLES[keyof typeof ROLES]
-// → 'ADMIN' | 'USER'
-```
-
----
-
-## Null vs Undefined
-```typescript
-// Use null: explicitly absent (API returns null, user cleared a field)
-type User = { avatar: string | null }
-
-// Use undefined: optionally present (optional function param, optional object key)
-type Options = { timeout?: number }
-
-// Never mix without reason — pick one for each case and be consistent
-```
-
----
-
-## Agent Rules
-```
-strict: true — never disable, never add ts-ignore without // reason:
-
-Type a new variable?
-  → Use the most specific type possible
-  → Infer from Zod schema if validating external data
-  → Use unknown for error catch blocks
-
-New shared type?
-  → If used in 2+ features → src/types/
-  → If feature-specific → features/[name]/types/
-
-New form?
-  → Zod schema first → infer type → pass to React Hook Form
-
-Avoid:
-  → any (use unknown)
-  → type assertions without reason comment
-  → enums (use const object + union type)
-  → I prefix on interfaces
-```

package/scripts/compatibility-matrix.mjs

@@ -1,48 +0,0 @@
-import fs from 'fs-extra'
-
-const catalog = await fs.readJson(new URL('../compatibility/profiles.json', import.meta.url))
-const scope = process.argv.find((arg) => arg.startsWith('--scope='))?.split('=')[1] || 'smoke'
-if (!['smoke', 'full'].includes(scope)) throw new Error('--scope must be smoke or full')
-
-const cases = [
-  'nextjs-none', 'nextjs-supabase', 'nextjs-springboot', 'nextjs-postgres', 'nextjs-laravel',
-  'react-none', 'react-supabase', 'react-springboot', 'react-laravel',
-  'react-native-none', 'react-native-supabase', 'react-native-springboot', 'react-native-laravel',
-  'laravel-api', 'laravel-blade', 'laravel-livewire', 'laravel-inertia-react',
-]
-
-function authChoices(caseName) {
-  const mobile = caseName.startsWith('react-native')
-  const nonBrowser = mobile || caseName === 'laravel-api'
-  const base = ['not-yet', 'none'].map((authentication) => ({ authentication, audience: nonBrowser ? 'multi-client' : 'website' }))
-  if (caseName.includes('supabase')) base.push({ authentication: 'yes', audience: mobile ? 'multi-client' : 'website' })
-  if (caseName.includes('springboot') || caseName.includes('laravel')) {
-    if (caseName.startsWith('laravel-') && caseName !== 'laravel-api') base.push({ authentication: 'yes', audience: 'website' })
-    else if (mobile || caseName === 'laravel-api') base.push({ authentication: 'yes', audience: 'multi-client' })
-    else base.push({ authentication: 'yes', audience: 'website' }, { authentication: 'yes', audience: 'multi-client' })
-  }
-  return base
-}
-
-const current = catalog.defaultProfile
-const full = Object.entries(catalog.profiles).filter(([profile]) => profile === current).flatMap(([profile, versions]) =>
-  cases.flatMap((caseName) => ['small', 'medium', 'large'].flatMap((architecture) =>
-    authChoices(caseName).map((auth) => ({ profile, case: caseName, architecture, ...auth, node: versions.runtimes.node, java: versions.runtimes.java, php: versions.runtimes.php })))),
-)
-
-const smokeSelections = [
-  ['nextjs-none', 'small', 'not-yet', 'website'],
-  ['nextjs-supabase', 'medium', 'yes', 'website'],
-  ['react-springboot', 'large', 'yes', 'website'],
-  ['react-native-supabase', 'medium', 'yes', 'multi-client'],
-  ['react-native-springboot', 'small', 'yes', 'multi-client'],
-  ['laravel-api', 'medium', 'not-yet', 'multi-client'],
-  ['laravel-blade', 'small', 'yes', 'website'],
-  ['laravel-livewire', 'medium', 'none', 'website'],
-  ['laravel-inertia-react', 'large', 'yes', 'website'],
-  ['react-laravel', 'medium', 'yes', 'website'],
-]
-const smoke = full.filter((entry) => entry.profile === current && smokeSelections.some(([caseName, architecture, authentication, audience]) =>
-  entry.case === caseName && entry.architecture === architecture && entry.authentication === authentication && entry.audience === audience))
-
-process.stdout.write(JSON.stringify(scope === 'full' ? full : smoke))