create-tigra 3.0.5 → 3.1.0

package/template/_claude/rules/server/deployment.md

@@ -1,78 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-# Deployment & Docker
-
-This project is deployed via **Docker** on **Coolify** (or any Docker-based platform). The `Dockerfile` is the production deployment contract. Every code change must remain compatible with it.
-
----
-
-## Dockerfile Architecture
-
-The server uses a **3-stage multi-stage build**:
-
-```
-Stage 1 (dependencies)  → Installs prod-only node_modules (cached layer)
-Stage 2 (builder)        → Installs all deps, generates Prisma client, compiles TypeScript
-Stage 3 (production)     → Alpine + dumb-init, non-root user, copies dist + prod node_modules + Prisma
-```
-
-**Entry point**: the container `CMD` runs `npx prisma migrate deploy` and then starts `node dist/server.js` — pending migrations are applied automatically on every container boot (migrate-on-boot).
-**Health check**: `GET /api/v1/live` — this endpoint MUST always exist and return 200.
-
----
-
-## When to Update the Dockerfile
-
-| You did this... | Update Dockerfile? | What to change |
-|---|---|---|
-| Added a new npm dependency | No | Automatic — `npm ci` installs from `package.json` |
-| Added a native/system dependency (e.g., `sharp`, `bcrypt`) | **Yes** | Add `apk add` in the production stage for required system libraries |
-| Changed the build command or output directory | **Yes** | Update the `RUN npm run build` or `COPY` paths in stage 2/3 |
-| Changed the entry point file (e.g., renamed `server.ts`) | **Yes** | Update the `CMD` to run `dist/<new-name>.js` (keep the `prisma migrate deploy` step before it) |
-| Changed the default port | **Yes** | Update `EXPOSE` and the `HEALTHCHECK` port |
-| Added/renamed a health check endpoint | **Yes** | Update the `HEALTHCHECK` URL path |
-| Added files needed at runtime (e.g., templates, static assets) | **Yes** | Add a `COPY` line in stage 3 |
-| Changed Prisma schema | No | Automatic — `npx prisma generate` runs in stage 2 |
-| Added a new env var | Maybe | If it's needed at **build time**, add `ARG` + `ENV` in the builder stage |
-| Added file upload functionality | **Yes** | Add a `VOLUME` directive or ensure the upload directory is writable |
-
----
-
-## Critical Rules
-
-1. **Health endpoint is sacred.** The route `GET /api/v1/live` must always exist and return HTTP 200. Coolify, Docker, and load balancers use it to determine if the container is alive. Never remove, rename, or gate it behind auth.
-
-2. **Never break the build chain.** If you rename the build output directory, the entry file, or change `tsconfig.json` `outDir`, update the Dockerfile `COPY` paths and `CMD` accordingly.
-
-3. **System dependencies must be explicit.** If a new npm package requires native binaries (e.g., `sharp` needs `libvips`, `bcrypt` needs `build-base`), add `apk add --no-cache <package>` in the production stage. The build will succeed locally but fail in Docker without this.
-
-4. **Non-root user.** The app runs as `nodejs:nodejs` (UID 1001). Any files the app needs to write (uploads, logs) must be in directories owned by this user. Add `RUN mkdir -p /app/<dir> && chown nodejs:nodejs /app/<dir>` if needed.
-
-5. **No secrets in the image.** Environment variables are injected at runtime via Coolify/Docker. Never hardcode secrets, never `COPY .env`, never use `ENV` for sensitive values. Only use `ARG`/`ENV` for non-secret build-time config.
-
-6. **Keep `.dockerignore` in sync.** When adding new directories or file types that should NOT be in the Docker build context (test fixtures, docs, local scripts), add them to `.dockerignore`. When adding files that ARE needed at build time, make sure they're not ignored.
-
-7. **Port consistency.** The default port is `8000`. If you change the port in `src/config/env.ts`, also update `EXPOSE` and the `HEALTHCHECK` in the Dockerfile.
-
----
-
-## Coolify-Specific Notes
-
-- **Environment variables**: Set in Coolify's UI, injected at container runtime. No `.env` file needed.
-- **Build arguments**: For build-time vars, use Coolify's "Build Arguments" section → maps to `docker build --build-arg`.
-- **Persistent storage**: For file uploads, mount a volume in Coolify to `/app/uploads`. Add to Dockerfile: `RUN mkdir -p /app/uploads && chown nodejs:nodejs /app/uploads` before `USER nodejs`.
-- **Database migrations**: Applied automatically at container startup — the Dockerfile `CMD` runs `npx prisma migrate deploy` before starting the server, so no Coolify configuration is needed. (Alternative: remove the migrate step from the `CMD` and run `npx prisma migrate deploy` as a pre-deploy command in Coolify instead.)
-
----
-
-## Files That Matter for Deployment
-
-| File | Purpose | Must exist? |
-|---|---|---|
-| `Dockerfile` | Production build instructions | Yes |
-| `.dockerignore` | Excludes files from Docker build context | Yes |
-| `package.json` | Dependencies and build script | Yes |
-| `tsconfig.json` | TypeScript compilation config | Yes |
-| `prisma/schema.prisma` | Database schema (copied to runtime) | Yes |
-| `prisma/migrations/` | Migration files (copied to runtime) | Yes |
-| `src/server.ts` | Entry point (compiled to `dist/server.js`) | Yes |

package/template/_claude/rules/server/project-conventions.md

@@ -1,254 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-# Project Conventions
-
-## Stack
-
-| Technology | Purpose |
-|------------|---------|
-| Node.js 20+ LTS | Runtime |
-| Fastify | HTTP framework (plugins, route prefixes, centralized error handling) |
-| TypeScript (strict) | Language — always type parameters and return types |
-| MySQL 8.0+ | Primary database |
-| Prisma 6.x | ORM, migrations, schema source of truth |
-| Redis | Caching (frequently accessed data, lookups), rate limiting, background task signaling |
-| Zod | Runtime validation and type inference |
-| JWT (HS256/RS256) | Auth — minimal token payload (id, role), role-based access control |
-| axios | Outbound HTTP client (external API calls) |
-| PM2 + Nginx | Production deployment (cluster mode) |
-| Jest / Vitest | Testing — deterministic, mock external APIs |
-
-## Package Manager
-
-Detect from lockfile: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else → npm.
-
-## Folder Structure
-
-```
-src/
-├── app.ts              # Fastify instance and plugin registration
-├── server.ts           # listen() call only, no app logic
-├── config/             # env, config, constants
-├── libs/               # shared libraries (db, redis, logger, auth)
-└── modules/<domain>/   # domain modules
-    ├── <domain>.routes.ts
-    ├── <domain>.controller.ts
-    ├── <domain>.service.ts
-    ├── <domain>.repo.ts
-    ├── <domain>.schemas.ts
-    └── <domain>.types.ts  (if needed)
-```
-
-New modules MUST follow `src/modules/<name>/` with the exact naming pattern above.
-
-## API Routes
-
-All routes prefixed with `/api/v1`. Grouped by domain: `/api/v1/<domain>/...`
-
-Register routes as Fastify plugins in `<domain>.routes.ts`.
-
-## Coding Style
-
-- TypeScript `strict` mode ON
-- `async/await` over `.then()`
-- Named exports (except `src/app.ts` which default-exports the Fastify instance)
-- Relative imports within a module (`./user.service`), aliased imports cross-module (`@modules/users/...`)
-- Use `logger` from `src/libs/logger` — never `console.log`
-
-## Layer Responsibilities
-
-| Layer | MUST | MUST NOT |
-|-------|------|----------|
-| **Routes** | Register Fastify plugins, define HTTP method + path | Contain any logic |
-| **Controllers** | Validate input (Zod), call services, return via `successResponse`/`paginatedResponse`, throw typed `AppError` | Business logic, direct DB access, manual error JSON, set HTTP status codes for errors |
-| **Services** | All business logic, throw `AppError` subclasses, call repos for DB ops, be stateless | Touch Fastify (request/reply), format responses, return HTTP status codes |
-| **Repositories** | Prisma queries, return raw data | Business logic, error formatting |
-
-## Postman Collection
-
-When API endpoints are created or modified, **always update the Postman collection** (`postman/collection.json`). If the collection does not exist, create it.
-
-### Collection Structure
-
-```
-postman/
-├── collection.json        # Postman v2.1 collection
-└── environment.json       # Environment variables template
-```
-
-### Environment Variables
-
-Use variables so requests are connected and portable:
-
-```json
-{
-  "variables": [
-    { "key": "baseUrl", "value": "http://localhost:3000/api/v1" },
-    { "key": "accessToken", "value": "" },
-    { "key": "refreshToken", "value": "" },
-    { "key": "userId", "value": "" }
-  ]
-}
-```
-
-- **`{{baseUrl}}`** — all request URLs use this prefix, never hardcoded hosts.
-- **`{{accessToken}}`** / **`{{refreshToken}}`** — set automatically via login/register test scripts.
-- **`{{userId}}`** and other IDs — captured from responses so subsequent requests can reference them.
-
-### Auto-set Tokens via Test Scripts
-
-The **Login** and **Register** requests MUST include a `Tests` script that stores tokens and user data into collection variables:
-
-```javascript
-if (pm.response.code === 200 || pm.response.code === 201) {
-  const res = pm.response.json();
-  pm.collectionVariables.set("accessToken", res.data.tokens.accessToken);
-  pm.collectionVariables.set("refreshToken", res.data.tokens.refreshToken);
-  pm.collectionVariables.set("userId", res.data.user.id);
-}
-```
-
-### Auth Header
-
-All authenticated requests use a collection-level or folder-level **Bearer Token** auth set to `{{accessToken}}`. Do not duplicate the auth header on every request — inherit from the parent folder.
-
-### Folder Organization
-
-Organize requests into folders matching domain modules:
-
-```
-Collection Root (Bearer Token: {{accessToken}})
-├── Auth (No Auth)
-│   ├── Register        → POST {{baseUrl}}/auth/register
-│   ├── Login           → POST {{baseUrl}}/auth/login    [sets tokens]
-│   ├── Refresh Token   → POST {{baseUrl}}/auth/refresh
-│   └── Logout          → POST {{baseUrl}}/auth/logout
-├── Users
-│   ├── Get Me          → GET {{baseUrl}}/users/me
-│   ├── Update Me       → PATCH {{baseUrl}}/users/me
-│   └── Delete Me       → DELETE {{baseUrl}}/users/me
-└── <Domain>            → One folder per module
-    ├── List            → GET {{baseUrl}}/<domain>
-    ├── Get by ID       → GET {{baseUrl}}/<domain>/{{<domain>Id}}
-    ├── Create          → POST {{baseUrl}}/<domain>
-    ├── Update          → PATCH {{baseUrl}}/<domain>/{{<domain>Id}}
-    └── Delete          → DELETE {{baseUrl}}/<domain>/{{<domain>Id}}
-```
-
-### Rules
-
-1. **Every route gets a request.** No endpoint should exist without a matching Postman request.
-2. **Include example request bodies** for POST/PATCH/PUT with realistic placeholder data.
-3. **Capture IDs from create responses** — add a `Tests` script that sets `{{<domain>Id}}` so Get/Update/Delete requests work without manual copy-paste.
-4. **Auth folder uses "No Auth"** — login and register don't need tokens. All other folders inherit Bearer Token from the collection root.
-5. **Keep it importable** — the collection must be valid Postman v2.1 JSON that anyone can import and run immediately after setting `baseUrl`.
-
-## Security
-
-- Validate all inputs with Zod schemas
-- Never interpolate raw values into SQL — always use Prisma query builder
-- Rate limit public endpoints
-- Avoid N+1 queries — prefer joins or batched queries
-
-## Outbound HTTP
-
-Use `httpClient` from `src/libs/http.ts` for ALL outbound HTTP calls. Never use native `fetch`, `node:http`, or a new `axios.create()` at the call site — the singleton provides consistent logging, 30s timeout, and automatic error conversion.
-
-### Import
-
-```typescript
-import { httpClient } from '@libs/http.js';
-```
-
-### Wrapping pattern (service layer)
-
-Outbound HTTP calls belong in the **service layer**. The interceptor converts `AxiosError` to `InternalError` automatically — services only deal with `AppError` subclasses:
-
-```typescript
-class WeatherService {
-  async getCurrentWeather(city: string): Promise<WeatherData> {
-    const response = await httpClient.get<WeatherApiResponse>(
-      `https://api.weather.example.com/v1/current`,
-      { params: { q: city } },
-    );
-    return response.data.result;
-  }
-}
-export const weatherService = new WeatherService();
-```
-
-### Auth headers
-
-Do NOT add auth headers to the `httpClient` singleton — it is shared. Pass per-request headers at the call site:
-
-```typescript
-await httpClient.post(url, body, {
-  headers: { Authorization: `Bearer ${token}` },
-});
-```
-
-### Fine-grained error mapping
-
-The interceptor always throws `InternalError`. If you need a more specific error (e.g., a 404 from an external API should surface as `NotFoundError`), catch and rethrow:
-
-```typescript
-try {
-  return await httpClient.get(url);
-} catch {
-  throw new NotFoundError('External resource not found');
-}
-```
-
-### Fixed-base-URL services
-
-If a service always calls the same external API, create a private derived instance **inside the service file only** (never exported):
-
-```typescript
-const apiClient = axios.create({ ...httpClient.defaults, baseURL: 'https://api.example.com/v2' });
-```
-
-### Rules
-
-- Always use `httpClient` — never `fetch`, `node:http`, or inline `axios.create()`.
-- Never add auth headers, cookies, or credentials to the singleton itself.
-- Never log response bodies (may contain PII or secrets).
-
-## File Storage
-
-### Directory Structure Principles
-
-Upload folders must be **scalable and manageable**. Never dump all files into a single flat directory (e.g., all product images under `/uploads/products/`). Instead, organize by **owner/entity ID** so each entity's files are isolated and easy to find, move, or delete.
-
-**Pattern**: `uploads/<domain>/{entityId}/<media-type>/`
-
-### User Uploads
-
-Structure: `uploads/users/{userId}/<media-type>/`
-
-| Media type | Path | Example |
-|---|---|---|
-| Avatar | `uploads/users/{userId}/avatar/` | `uploads/users/abc123/avatar/john-doe-avatar.webp` |
-
-- All user media lives under `uploads/users/{userId}/` for easy per-user cleanup.
-- On account purge, delete the entire `uploads/users/{userId}/` directory via `deleteUserMedia()`.
-- Public URL pattern: `/uploads/users/{userId}/<media-type>/{filename}`
-- New media types follow the same pattern: add a subfolder under the user directory.
-
-### Domain Entity Uploads (Products, Articles, etc.)
-
-Structure: `uploads/<domain>/{entityId}/<media-type>/`
-
-| Domain | Media type | Path | Example |
-|---|---|---|---|
-| Products | Images | `uploads/products/{productId}/images/` | `uploads/products/prod-456/images/front-view.webp` |
-| Products | Thumbnails | `uploads/products/{productId}/thumbnails/` | `uploads/products/prod-456/thumbnails/front-view-thumb.webp` |
-| Articles | Cover | `uploads/articles/{articleId}/cover/` | `uploads/articles/art-789/cover/hero.webp` |
-| Articles | Content images | `uploads/articles/{articleId}/content/` | `uploads/articles/art-789/content/diagram-1.webp` |
-
-### Rules
-
-1. **Never use flat directories** — `uploads/products/img1.jpg, img2.jpg, ...` is forbidden. Always namespace by entity ID.
-2. **One folder per entity instance** — makes deletion, migration, and backup trivial (`rm -rf uploads/products/{id}/`).
-3. **Separate media types into subfolders** — don't mix avatars, thumbnails, and full-size images in the same folder.
-4. **Entity cleanup** — when an entity is deleted, remove its entire upload directory (e.g., `uploads/products/{productId}/`).
-5. **Consistent naming** — use kebab-case for filenames, domain plural for top-level folders (`products`, `articles`, `users`).

package/template/_claude/rules/server/response-handling.md

@@ -1,144 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-# Response Handling
-
-All API responses follow a unified contract. No exceptions.
-
----
-
-## Success Response
-
-```json
-{
-  "success": true,
-  "message": "Human-readable message",
-  "data": {}
-}
-```
-
-- `data` can be an object, array, or null
-- Controllers MUST use the shared `successResponse()` helper
-
-```typescript
-// Allowed
-return reply.send(successResponse("Item created successfully", item));
-
-// Forbidden — never send raw values or custom shapes
-reply.send(item);
-reply.send({ data: item });
-reply.send({ success: true, item });
-```
-
----
-
-## Error Response
-
-```json
-{
-  "success": false,
-  "error": {
-    "code": "MACHINE_READABLE_CODE",
-    "message": "Human-readable, user-safe message"
-  }
-}
-```
-
-- `code`: stable machine-readable string (e.g. `RESOURCE_NOT_FOUND`, `VALIDATION_FAILED`)
-- Never expose internal details, stack traces, or SQL errors
-- Controllers MUST NOT manually construct error responses
-
----
-
-## Paginated Response
-
-```json
-{
-  "success": true,
-  "message": "string",
-  "data": {
-    "items": [],
-    "pagination": {
-      "page": 1,
-      "limit": 10,
-      "totalItems": 237,
-      "totalPages": 24,
-      "hasNextPage": true,
-      "hasPreviousPage": false
-    }
-  }
-}
-```
-
-Controllers MUST use the shared `paginatedResponse()` helper:
-
-```typescript
-function paginatedResponse<T>(message: string, items: T[], page: number, limit: number, totalItems: number)
-
-// Allowed
-return reply.send(paginatedResponse("Items retrieved successfully", items, page, limit, totalCount));
-```
-
-### Pagination Input Validation
-
-All paginated endpoints MUST validate with this shared Zod schema:
-
-```typescript
-const PaginationSchema = z.object({
-  page: z.coerce.number().int().min(1).default(1),
-  limit: z.coerce.number().int().min(1).max(100).default(10)
-});
-```
-
-### Service Return Pattern for Pagination
-
-Services return `{ items, totalItems }`. Controllers build the pagination metadata.
-
-```typescript
-// Service returns:
-return { items, totalItems: count };
-// Offset calculation: (page - 1) * limit
-```
-
-### Filters with Pagination
-
-- Apply filters/sorting BEFORE `limit` and `offset`
-- Count total items AFTER filters but BEFORE pagination
-- Pages start at 1 (never 0)
-
----
-
-## Error Architecture
-
-ONE global Fastify error handler via `fastify.setErrorHandler(...)`:
-- Maps `AppError` subclasses to HTTP status codes
-- Formats the unified error JSON structure
-- Logs internal details server-side only — never sends to client
-
-### AppError Subclasses
-
-All errors MUST extend `AppError` (which defines `code`, `message`, `statusCode`). Only throw these typed subclasses — never raw `Error`, strings, or plain objects.
-
-| Class | Status | Example Code |
-|-------|--------|--------------|
-| `BadRequestError` | 400 | `INVALID_INPUT` |
-| `ValidationError` | 422 | `VALIDATION_FAILED` |
-| `UnauthorizedError` | 401 | `UNAUTHORIZED` |
-| `ForbiddenError` | 403 | `FORBIDDEN` |
-| `NotFoundError` | 404 | `RESOURCE_NOT_FOUND` |
-| `ConflictError` | 409 | `EMAIL_ALREADY_EXISTS` |
-| `InternalError` | 500 | `INTERNAL_ERROR` |
-
----
-
-## Controller Response Rules
-
-**ALWAYS:**
-- Use `successResponse()` or `paginatedResponse()` for all responses
-- Validate input with Zod before calling services
-- Throw typed `AppError` subclasses on failure
-
-**NEVER:**
-- Send raw values or custom JSON shapes
-- Set HTTP status codes for errors (global handler does this)
-- Catch errors unless rethrowing as typed `AppError`
-- Manually construct error response JSON

package/template/_claude/settings.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/restrict-paths.sh\""
-          }
-        ]
-      }
-    ]
-  }
-}

package/template/_claude/skills/clean-ui/SKILL.md

@@ -1,63 +0,0 @@
----
-name: clean-ui
-description: Remove the starter welcome page UI and replace with a blank canvas, preserving all client-side functionality (auth, hooks, services, store, middleware, utils)
----
-
-The user wants to remove the starter/welcome UI from the scaffolded client and start with a blank page.
-
-## What this skill does
-
-Replaces the demo welcome page (`src/app/page.tsx`) with the absolute bare minimum — just a centered "Ready to build." text. **Nothing else is touched** — all functional infrastructure remains intact.
-
-## What gets replaced
-
-| File | Action | Reason |
-|------|--------|--------|
-| `src/app/page.tsx` | **Replace** with blank canvas | Remove ALL demo content — hero, ambient glow, GitHub links, buttons, everything |
-
-## What is NOT touched (preserved as-is)
-
-- `src/components/layout/` — Header, Footer, MainLayout
-- `src/app/layout.tsx` — root layout with providers
-- `src/app/providers.tsx` — Redux, React Query, themes, AuthInitializer
-- `src/app/error.tsx`, `src/app/not-found.tsx`, `src/app/loading.tsx`
-- `src/middleware.ts` — route protection
-- `src/features/auth/**` — entire auth system
-- `src/components/common/**` — ThemeToggle, EmptyState, LoadingSpinner, etc.
-- `src/components/ui/**` — all shadcn/ui components
-- `src/hooks/**`, `src/store/**`, `src/lib/**`, `src/styles/**`
-- All config files
-
-## Steps
-
-1. Read `src/app/page.tsx` to confirm it exists.
-2. Replace its contents with the clean page below. Use the **exact** template — do not add anything.
-3. Confirm to the user what was done.
-
-## Clean page template
-
-Replace `src/app/page.tsx` with **exactly** this — no additions, no modifications:
-
-```tsx
-import type React from 'react';
-
-export default function HomePage(): React.ReactElement {
-  return (
-    <main className="flex min-h-dvh items-center justify-center">
-      <p className="text-sm text-muted-foreground">Ready to build.</p>
-    </main>
-  );
-}
-```
-
-**CRITICAL**: Do NOT add anything beyond what is in the template above. No heading, no links, no buttons, no metadata, no imports beyond React. The entire point is a blank canvas.
-
-## Response format
-
-After completing, respond with:
-
-```
-Starter UI cleaned. `src/app/page.tsx` is now a blank canvas.
-
-Everything else is untouched — auth, hooks, services, store, middleware, components, and design system are all intact.
-```

package/template/_claude/skills/role/SKILL.md

@@ -1,39 +0,0 @@
----
-name: role
-description: Switch developer role to restrict Claude's access to frontend-only, backend-only, or full access
-argument-hint: "[frontend | backend | fullstack]"
-disable-model-invocation: true
-allowed-tools: Read, Write
----
-
-The user wants to switch their developer role. The argument is: $ARGUMENTS
-
-Read the file `.developer-role` in the project root to see the current role.
-
-## Rules
-
-- If the argument is `frontend`, `backend`, or `fullstack` — write that word to `.developer-role` and confirm the switch.
-- If no argument is given — read `.developer-role` and tell the user their current role, then ask which role they want.
-- If the argument is not one of the three valid roles — tell the user the valid options.
-
-## What each role does
-
-Claude can always READ all files for full project context. Only WRITE access is restricted.
-
-| Role | Can edit |
-|------|---------|
-| `frontend` | `client/` only. Cannot edit `server/` files. |
-| `backend` | `server/` only. Cannot edit `client/` files. |
-| `fullstack` | Everything. No restrictions. |
-
-## Response format
-
-After switching, confirm like this:
-
-```
-Role switched to **{role}**.
-
-- frontend → can edit client/ only (can read everything)
-- backend → can edit server/ only (can read everything)
-- fullstack → can edit everything
-```