create-tigra 2.7.2 → 3.0.0

package/template/_claude/rules/global/investigation-before-conclusions.md

@@ -0,0 +1,57 @@
+> **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
+
+# Investigation Before Conclusions
+
+This project (create-tigra) generates starter templates for developers who may not have deep coding experience. They trust AI output without questioning it. **A wrong suggestion that "fixes" a non-existent problem can introduce real problems.** Every recommendation must be grounded in verified understanding of how the code actually works.
+
+---
+
+## The Rule
+
+**Never suggest fixes, changes, or improvements until you have fully traced how the relevant system works in this codebase.** Seeing a file, a config, or a pattern is not enough. You must follow the code path end-to-end before making any claim.
+
+---
+
+## Before Answering "Is This a Bug?" or "Does This Need Fixing?"
+
+1. **Trace the actual workflow.** If the question is about uploads, go read the upload service, follow where files are saved, how they're served, how they're deleted. If it's about auth, trace the full auth flow. Don't stop at the first file you find.
+
+2. **Understand the runtime environment.** Ask yourself: does this code run in Docker or locally? Is this a dev tool or a production path? Does docker-compose run the server or just infrastructure services (MySQL, Redis)? Don't assume — verify.
+
+3. **Verify the problem exists in the real workflow.** Not in theory, not in a hypothetical scenario — in the actual way developers use this project. If no one would ever hit the issue in normal usage, it's not a problem worth fixing.
+
+4. **Don't pattern-match to conclusions.** "Uploads + Docker + no volume = must fix" is pattern-matching, not investigation. The server runs locally with `npm run dev`, not inside Docker. The `docker-compose.yml` is for MySQL and Redis only. A volume for uploads in docker-compose would solve nothing.
+
+5. **If you're unsure, say so.** "I need to check how this works before I can answer" is always better than a confident wrong answer.
+
+---
+
+## What NOT to Do
+
+| Bad behavior | Why it's dangerous |
+|---|---|
+| See a Dockerfile, immediately suggest `VOLUME` | The server may not run in Docker locally |
+| See docker-compose.yml, suggest adding volumes | docker-compose may only run infrastructure, not the app |
+| Find a missing config and assume it's a bug | It may be intentionally absent because it's not needed |
+| Suggest "best practice" improvements unprompted | Unnecessary changes confuse beginners and can introduce real bugs |
+| Stop researching after finding the first related file | The first file is not the full picture — trace the complete flow |
+| Offer a fix before confirming the problem is real | Fixing non-existent problems wastes time and creates new problems |
+
+---
+
+## The Standard
+
+Before every suggestion, ask yourself:
+
+1. **Did I trace the full code path?** Not just one file — the whole flow.
+2. **Do I understand the runtime environment?** Where does this code actually run?
+3. **Would a real developer actually hit this problem?** In normal usage, not edge cases.
+4. **Am I solving a real problem or a theoretical one?**
+
+If the answer to any of these is "no" — keep investigating before responding.
+
+---
+
+## Why This Matters
+
+create-tigra exists to help developers who are learning to code with AI assistance. These developers will trust your suggestions without pushback. A confident but wrong suggestion — like adding a Docker volume for a service that doesn't run in Docker — will send them down a rabbit hole debugging something that was never broken. **Your job is to understand what actually works and why, not to guess based on patterns.**

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

@@ -17,6 +17,7 @@
 | Writing service or business logic | `project-conventions.md` (Layer Responsibilities) |
 | Changing DB schema, migrations, indexes | `database.md` |
 | Adding or changing API endpoints | `project-conventions.md` (Postman Collection) |
+| Adding dependencies, changing ports, entry points, or env vars | `deployment.md` |
 | Unsure where to start | This file |
 
 ---
@@ -48,3 +49,4 @@ Request
 5. **Logging**: Use `logger` from `src/libs/logger`. Never `console.log`.
 6. **Routes**: All prefixed with `/api/v1`. Registered as Fastify plugins.
 7. **Postman**: Every new or modified endpoint must be reflected in `postman/collection.json`. Create the collection if it doesn't exist.
+8. **Deployment**: Every change must remain compatible with the Dockerfile. Read `deployment.md` when adding system dependencies, changing ports, renaming entry points, or adding env vars.

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

@@ -0,0 +1,78 @@
+> **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/client/next.config.ts

@@ -9,8 +9,21 @@ const apiOrigin = (() => {
   }
 })();
 
+// 'unsafe-eval' is required by Next.js dev mode (HMR/react-refresh) but must
+// NOT ship to production. 'unsafe-inline' stays in both modes — the Next.js
+// inline runtime requires it unless a full nonce infrastructure is added.
+const isDev = process.env.NODE_ENV === "development";
+const scriptSrc = `script-src 'self'${isDev ? " 'unsafe-eval'" : ""} 'unsafe-inline'`;
+
 const nextConfig: NextConfig = {
   output: "standalone",
+  experimental: {
+    // Next 16.2+ rejects staleTimes.static below 30 (config schema enforces gte(30));
+    // an invalid value is ignored entirely, silently re-enabling the Router Cache.
+    // 30s is the closest allowed to "never serve stale RSC payloads on back-navigation".
+    // dynamic: 0 (still unconstrained) is what protects data pages — never raise it.
+    staleTimes: { dynamic: 0, static: 30 },
+  },
   async headers() {
     return [
       {
@@ -24,9 +37,9 @@ const nextConfig: NextConfig = {
             key: "Content-Security-Policy",
             value: [
               "default-src 'self'",
-              "script-src 'self' 'unsafe-eval' 'unsafe-inline'",
+              scriptSrc,
               "style-src 'self' 'unsafe-inline'",
-              "img-src 'self' blob: data: https:",
+              `img-src 'self' blob: data: https: ${apiOrigin}`,
               "font-src 'self'",
               "object-src 'none'",
               "base-uri 'self'",