create-tigra 1.1.0 → 2.0.1

package/template/.agent/rules/server/02-general-rules.md

@@ -1,111 +0,0 @@
----
-trigger: always_on
----
-
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-You are a senior backend engineer helping build a high-traffic API server.
-
-### PROJECT CONTEXT
-
-- Stack:
-
-  - Node.js (LTS, 20+)
-  - Fastify as HTTP framework
-  - TypeScript
-  - MySQL as the primary relational database
-  - Redis for caching, sessions, and rate limiting
-  - Zod for runtime validation and type inference
-  - Drizzle ORM (or Prisma) for DB access and migrations
-  - Jest/Vitest for tests
-
-- Domain:
-
-  - Users & Roles
-  - Core Business Entities
-  - Locations & Mapping
-  - Media (images, galleries)
-  - Resources Availability & Pricing
-  - Transactions & Bookings
-  - Payments (integration with external providers)
-  - Messaging & Communications
-
-- Goals:
-  - Clean, layered architecture: Routes → Controllers → Services → Repositories → DB
-  - High performance (Fastify, Redis, proper indexes)
-  - Easy to maintain and scale
-  - Secure (auth, input validation, rate limiting)
-  - Clear separation of concerns
-
-### ARCHITECTURE & CODE STYLE
-
-1. Use TypeScript everywhere. Always type function parameters and return types.
-2. Organize by domain/module:
-
-   src/modules/<domain>/
-
-   - <domain>.routes.ts (Fastify route definitions)
-   - <domain>.controller.ts (HTTP handlers only; no business logic)
-   - <domain>.service.ts (business logic)
-   - <domain>.repo.ts (DB queries)
-   - <domain>.schemas.ts (Zod schemas for input/output)
-
-3. Fastify:
-
-   - Use plugins and route registration with prefixes (e.g., /api/v1/<resource>).
-   - Use schemas for validation & serialization.
-   - Implement centralized error handling.
-
-4. Database:
-
-   - Use migrations (via Drizzle/Prisma) for schema changes.
-   - Add proper indexes for search-heavy fields (identifiers, price, date, type).
-   - Avoid N+1 queries; prefer joins or batched queries.
-
-5. Redis:
-
-   - Use for caching frequently accessed data.
-   - Use for rate limiting and potentially for background task signaling.
-
-6. Auth:
-
-   - Use JWT with HS256 or RS256.
-   - Store only minimal user info in the token (id, role).
-   - Implement role-based access control.
-
-7. Security:
-
-   - Validate all inputs with Zod and Fastify schemas.
-   - Never interpolate raw values into SQL; always use the ORM query builder.
-   - Implement sane rate limiting for public endpoints.
-   - Sanitize outputs where necessary.
-
-8. Coding constraints:
-
-   - Do NOT break existing exports or types unless explicitly asked.
-   - When modifying existing files, keep changes focused and minimal.
-   - Reuse existing helpers (db, logger, env) instead of re-creating them.
-   - Add TODO comments for non-trivial follow-up tasks.
-
-9. When asked to implement a feature:
-
-   - First, summarize what needs to be done.
-   - Then list files to be created/modified.
-   - Then provide code for each file in separate code blocks.
-   - Ensure imports between files are correct and consistent with the project structure.
-
-10. Testing:
-
-- For core logic (calculations, transactions, payment callbacks), provide Jest/Vitest tests.
-- Tests should be deterministic and not hit external APIs directly (use mocks).
-
-### RESPONSE FORMAT
-
-Whenever you make changes:
-
-1. Briefly explain the approach (1–2 paragraphs).
-2. Show updated/created files with full content in code blocks.
-3. Mention any migrations or environment variables that must be added.
-4. If you are unsure, state your assumptions clearly.
-
-If instructions from earlier parts of the prompt conflict with the user’s new message, follow the user’s latest explicit instructions.

package/template/.agent/rules/server/03-migrations.md

@@ -1,20 +0,0 @@
----
-trigger: always_on
----
-
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-# Migration Rules for AI Agent
-
-CRITICAL: When user asks for schema changes:
-
-1. ALWAYS edit `prisma/schema.prisma` first
-2. THEN run: `npm run prisma:migrate dev --name descriptive_name`
-3. IF migration fails with conflicts:
-   - DON'T try to fix manually
-   - DO run: `npm run prisma:reset`
-   - Then: `npm run prisma:seed`
-4. NEVER use `prisma db push` unless explicitly asked
-
-Development = use prisma:reset freely
-Production = ONLY use prisma:migrate deploy

package/template/.agent/rules/server/04-pagination.md

@@ -1,130 +0,0 @@
----
-trigger: always_on
----
-
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-## Pagination Contract (MANDATORY)
-
-All paginated API responses MUST follow a unified structure. No exceptions are allowed.
-
-### Paginated Response Format
-
-Every paginated response MUST follow this exact structure:
-```json
-{
-  "success": true,
-  "message": "string",
-  "data": {
-    "items": [],
-    "pagination": {
-      "page": 1,
-      "limit": 10,
-      "totalItems": 237,
-      "totalPages": 24,
-      "hasNextPage": true,
-      "hasPreviousPage": false
-    }
-  }
-}
-```
-
-### Response Rules
-
-- `success` is always `true`
-- `message` is REQUIRED and must be human-readable
-- `data.items` contains the array of results (can be empty array)
-- `data.pagination` is REQUIRED and contains:
-  - `page` – current page number (starts at 1)
-  - `limit` – items per page
-  - `totalItems` – total count of items across all pages
-  - `totalPages` – calculated as `Math.ceil(totalItems / limit)`
-  - `hasNextPage` – boolean, `true` if `page < totalPages`
-  - `hasPreviousPage` – boolean, `true` if `page > 1`
-
-### Shared Pagination Helper (REQUIRED)
-
-Controllers MUST use a shared `paginatedResponse` helper:
-```typescript
-function paginatedResponse<T>(
-  message: string,
-  items: T[],
-  page: number,
-  limit: number,
-  totalItems: number
-)
-```
-
-**Allowed example:**
-```typescript
-return reply.send(paginatedResponse("Resources retrieved successfully", items, page, limit, totalCount));
-```
-
-**Forbidden examples:**
-```typescript
-reply.send({ items, page, total });
-reply.send({ success: true, data: items, pagination: {...} });
-reply.send({ items: items, meta: {...} });
-```
-
-### Pagination Input Validation (REQUIRED)
-
-All endpoints accepting pagination MUST validate using a 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)
-});
-```
-
-**Rules:**
-- `page` defaults to `1`, must be positive integer
-- `limit` defaults to `10`, must be between 1 and 100
-- Use `z.coerce.number()` to handle query string conversion
-- Controllers MUST validate pagination inputs before calling services
-
-### Service Layer Requirements
-
-Services handling pagination MUST:
-- Accept `page` and `limit` as parameters
-- Return both the `items` array AND `totalItems` count
-- NOT construct pagination metadata (controller responsibility)
-- Calculate offset as: `(page - 1) * limit`
-
-**Service return pattern:**
-```typescript
-return {
-  items: results,
-  totalItems: count
-};
-```
-
-### Filter & Sort with Pagination
-
-When combining filters/sorting with pagination:
-- Filters come BEFORE pagination in query parameters
-- Pagination params (`page`, `limit`) are separate from filters
-- Apply filters/sorting to query BEFORE applying `limit` and `offset`
-- Count total items AFTER filters but BEFORE pagination
-
-**Example query string:**
-```
-?category=active&minPrice=100&sortBy=price&order=asc&page=2&limit=20
-```
-
-### Strict Prohibitions
-
-These patterns are NOT allowed:
-- Multiple pagination formats across endpoints
-- Returning raw arrays without pagination wrapper
-- Custom pagination field names (e.g., `pageNumber`, `perPage`, `count`)
-- Including pagination in query results instead of metadata
-- Zero-indexed pages (always start at 1)
-- Omitting `totalItems` or `totalPages`
-
-### Enforcement Rule
-
-If a user instruction conflicts with this pagination contract:
-- Follow the user instruction ONLY if explicitly stated
-- Otherwise, this pagination contract is non-negotiable
-- Pagination structure MUST be consistent across ALL endpoints

package/template/.agent/rules/server/05-project-conventions.md

@@ -1,71 +0,0 @@
----
-trigger: always_on
----
-
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-# API Server – Project Conventions
-
-## Package manager
-
-- Detect the package manager from the lockfile:
-  - If `pnpm-lock.yaml` exists → use `pnpm`
-  - If `yarn.lock` exists → use `yarn`
-  - Else → use `npm`
-
-## File & folder structure
-
-- Keep everything under `src/`.
-- Prefer this layout:
-
-  - `src/app.ts` → Fastify instance and plugin registration
-  - `src/server.ts` → actual `listen()` call, no app logic
-  - `src/config/` → env, config, constants
-  - `src/libs/` → shared libraries (db, redis, logger, auth)
-  - `src/modules/<domain>/` → domain modules:
-    - `<domain>.routes.ts`
-    - `<domain>.controller.ts`
-    - `<domain>.service.ts`
-    - `<domain>.repo.ts`
-    - `<domain>.schemas.ts`
-    - `<domain>.types.ts` (if needed)
-
-- When adding new modules, stick to `src/modules/<name>/` and keep the exact naming pattern.
-
-## Coding style
-
-- Use TypeScript with `strict` mode ON.
-- Prefer `async/await` over `.then()`.
-- Prefer named exports over default exports, except for:
-  - `src/app.ts` → default export is the Fastify instance
-  - Frontend components (if any).
-- Use consistent import paths:
-  - Use relative imports inside a module: `./user.service`
-  - Use aliased imports for cross-module paths if configured (e.g. `@modules/users/...`).
-
-## Error handling
-
-- Controllers must never throw raw errors; they should:
-  - Either use a shared error helper, or
-  - Let Fastify’s error handler handle typed errors.
-- Never `console.log` for production logic:
-  - Use the shared `logger` from `src/libs/logger`.
-
-## API versioning & routes
-
-- All API routes must be prefixed with `/api/v1`.
-- Group routes by domain:
-  - `/api/v1/auth/...`
-  - `/api/v1/users/...`
-  - `/api/v1/<domain_resource>/...`
-- When adding new routes, register them in a Fastify plugin under `src/modules/<domain>/<domain>.routes.ts`.
-
-## Service Layer Rules
-
-- Every domain module must include a `<domain>.service.ts` file.
-- Services contain all business logic and must NOT depend on Fastify, reply, request, or HTTP-specific concepts.
-- Controllers must call services instead of performing logic directly.
-- Services may call repositories for DB operations.
-- Services must throw typed AppError instances for failures.
-- Services must not return success or error responses; they only return data or throw errors.
-- Services must be stateless and reusable.

package/template/.agent/rules/server/06-response-handling.md

@@ -1,173 +0,0 @@
----
-trigger: always_on
----
-
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-API Server – Error & Success Response Rules
-
-These rules define the ONLY allowed way to return success and error responses from the API. All AI assistants MUST follow this contract strictly.
-
-Unified Response Contract (MANDATORY)
-The API uses a single, stable response structure for all endpoints. No exceptions are allowed.
-
-Success Response Format
-Every successful response MUST follow this exact structure:
-
-{
-"success": true,
-"message": "string",
-"data": {}
-}
-
-Rules:
-
-success is always true
-
-message is REQUIRED and must be human-readable
-
-data can be an object, array, or null
-
-Controllers MUST use a shared success helper (for example successResponse)
-
-Controllers MUST NOT return raw values or custom-shaped JSON
-
-Allowed example:
-return reply.send(successResponse("Resource created successfully", data));
-
-Forbidden examples:
-reply.send(data);
-reply.send({ data: data });
-reply.send({ success: true, data });
-
-Error Response Format
-Every error response MUST follow this exact structure:
-
-{
-"success": false,
-"error": {
-"code": "ERROR_CODE",
-"message": "Human readable message"
-}
-}
-
-Rules:
-
-success is always false
-
-code must be a stable machine-readable string (for example RESOURCE_NOT_FOUND)
-
-message must be safe for end users
-
-Internal details, stack traces, or SQL errors MUST NOT be exposed
-
-Controllers MUST NOT manually send error responses
-
-Global Error Handling Architecture
-The server MUST define ONE global Fastify error handler using fastify.setErrorHandler(...).
-This global handler is responsible for:
-
-Mapping errors to HTTP status codes
-
-Formatting the unified error response
-
-Logging internal error details on server side only
-
-Error Throwing Rules (CRITICAL)
-Controllers and services MUST throw typed errors ONLY.
-They MUST NOT throw:
-
-raw Error
-
-strings
-
-unstructured objects
-
-Required Error Base Class
-All custom errors MUST extend a shared AppError class which defines:
-
-code
-
-message
-
-statusCode
-
-Allowed Error Types
-Allowed subclasses:
-
-BadRequestError
-
-ValidationError
-
-UnauthorizedError
-
-ForbiddenError
-
-NotFoundError
-
-ConflictError
-
-InternalError
-
-Each subclass MUST:
-
-extend AppError
-
-set a meaningful code
-
-set an appropriate statusCode
-
-Controller Responsibilities
-Controllers MUST:
-
-Validate input using Zod schemas
-
-Call service-layer logic only
-
-Return success responses using the shared success helper
-
-Throw typed errors when something fails
-
-Controllers MUST NOT:
-
-Set HTTP status codes for errors
-
-Build custom error JSON structures
-
-Catch errors unless rethrowing typed errors
-
-Service Layer Responsibilities
-Services MUST:
-
-Contain business logic
-
-Throw typed AppError errors when needed
-
-NEVER depend on Fastify reply or HTTP objects
-
-Logging Rules
-Logging MUST occur only inside:
-
-The global error handler
-
-Shared logging utilities
-
-Controllers MUST NOT log unless explicitly instructed. Internal logs MUST NOT be sent to the client.
-
-Strict Prohibitions
-These patterns are NOT allowed anywhere:
-
-Multiple response formats
-
-reply.send({ error: "text" })
-
-throw new Error("message")
-
-Returning raw errors from services
-
-Leaking stack traces or database internals to users
-
-Final Enforcement Rule
-If a user instruction conflicts with this document:
-Follow the user instruction ONLY if explicitly stated.
-Otherwise, this response contract is non-negotiable.