create-tigra 2.7.2 → 3.0.0

package/README.md

@@ -44,7 +44,7 @@ Includes `.claude/` rules for Claude Code with project-specific conventions, arc
 
 ## Prerequisites
 
-- **Node.js** 18+
+- **Node.js** 22.12+
 - **Docker** (for MySQL and Redis)
 
 ## After Scaffolding
@@ -72,8 +72,15 @@ npm run dev
 
 - Server: http://localhost:8000
 - Client: http://localhost:3000
-- phpMyAdmin: http://localhost:8080
-- Redis Commander: http://localhost:8081
+- phpMyAdmin: http://localhost:8080 (optional — see below)
+- Redis Commander: http://localhost:8081 (optional — see below)
+
+The admin UIs (phpMyAdmin, Redis Commander) are behind the docker-compose `tools` profile and do **not** start with plain `docker compose up -d`. Start them with:
+
+```bash
+cd my-app/server
+docker compose --profile tools up -d
+```
 
 ## License
 

package/bin/create-tigra.js

@@ -17,6 +17,10 @@ const VERSION = packageJson.version;
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
 
+// Non-secret placeholder written into the COMMITTED server/.env.example.
+// The real secret replaces it only in the git-ignored server/.env.
+const JWT_SECRET_PLACEHOLDER = 'CHANGE_ME_generate_with_openssl_rand_hex_48';
+
 // Files that contain template variables and need replacement
 const FILES_TO_REPLACE = [
   'server/package.json',
@@ -24,6 +28,7 @@ const FILES_TO_REPLACE = [
   'server/docker-compose.yml',
   'client/package.json',
   'client/.env.example',
+  'client/.env.example.production',
   'server/postman/collection.json',
   'server/postman/environment.json',
 ];
@@ -123,6 +128,43 @@ function replaceVariables(content, variables) {
   return result;
 }
 
+// When stdin is closed/non-interactive, `prompts` never settles its promise:
+// the event loop drains and Node exits 0 mid-await — no scaffold, no error.
+// That silently "succeeds" in CI. Track the in-flight prompt and fail loudly.
+let activePromptMessage = null;
+
+process.on('exit', (code) => {
+  if (activePromptMessage !== null && code === 0) {
+    // writeSync: stderr writes via console.error can be lost in an 'exit'
+    // handler when stderr is a pipe (async on Windows).
+    fs.writeSync(
+      2,
+      `\n  Aborted: the prompt "${activePromptMessage}" was not answered ` +
+        `(stdin is closed or non-interactive).\n` +
+        `  Run in an interactive terminal, or pipe answers via stdin.\n\n`,
+    );
+    process.exitCode = 1;
+  }
+});
+
+async function ask(question) {
+  activePromptMessage = question.message;
+  const response = await prompts(question, {
+    onCancel: () => {
+      console.error(chalk.red('\n  Cancelled.\n'));
+      process.exit(1);
+    },
+  });
+  activePromptMessage = null;
+  if (response[question.name] === undefined) {
+    console.error(
+      chalk.red(`\n  Aborted: no answer received for "${question.message}".\n`),
+    );
+    process.exit(1);
+  }
+  return response;
+}
+
 function registerAddCommand(program) {
   program
     .command('add <module>')
@@ -248,20 +290,12 @@ async function main() {
       let projectName = projectNameArg;
 
       if (!projectName) {
-        const response = await prompts(
-          {
-            type: 'text',
-            name: 'projectName',
-            message: 'What is your project name?',
-            validate: validateProjectName,
-          },
-          {
-            onCancel: () => {
-              console.log(chalk.red('\n  Cancelled.\n'));
-              process.exit(1);
-            },
-          }
-        );
+        const response = await ask({
+          type: 'text',
+          name: 'projectName',
+          message: 'What is your project name?',
+          validate: validateProjectName,
+        });
         projectName = response.projectName;
       }
 
@@ -286,34 +320,30 @@ async function main() {
       }
 
       // Ask about email verification
-      const { enableVerification } = await prompts(
-        {
-          type: 'toggle',
-          name: 'enableVerification',
-          message: 'Enable email verification for new users?',
-          initial: false,
-          active: 'Yes',
-          inactive: 'No',
-          hint: 'Users must verify email before accessing the app',
-        },
-        {
-          onCancel: () => {
-            console.log(chalk.red('\n  Cancelled.\n'));
-            process.exit(1);
-          },
-        }
-      );
+      const { enableVerification } = await ask({
+        type: 'toggle',
+        name: 'enableVerification',
+        message: 'Enable email verification for new users?',
+        initial: false,
+        active: 'Yes',
+        inactive: 'No',
+        hint: 'Users must verify email before accessing the app',
+      });
 
       // Generate random port offset (1-200) so multiple projects don't conflict
       const portOffset = crypto.randomInt(1, 201);
 
-      // Derive all variables
+      // Derive all variables.
+      // SECURITY: everything in this map is written into COMMITTED files
+      // (.env.example, docker-compose.yml, ...) — never put a real secret here.
+      // JWT_SECRET gets an instructional placeholder; the real secret is
+      // generated below and written ONLY to the git-ignored .env.
       const variables = {
         PROJECT_NAME: projectName,
         PROJECT_NAME_SNAKE: toSnakeCase(projectName),
         PROJECT_DISPLAY_NAME: toTitleCase(projectName),
         DATABASE_NAME: `${toSnakeCase(projectName)}_db`,
-        JWT_SECRET: crypto.randomBytes(48).toString('hex'),
+        JWT_SECRET: JWT_SECRET_PLACEHOLDER,
         MYSQL_PORT: String(3306 + portOffset),
         PHPMYADMIN_PORT: String(8080 + portOffset),
         REDIS_PORT: String(6379 + portOffset),
@@ -337,12 +367,21 @@ async function main() {
           }
         }
 
-        // Generate .env from .env.example (so users don't have to copy manually)
+        // Generate .env from .env.example (so users don't have to copy manually).
+        // The real JWT secret is injected HERE and only here — .env is
+        // git-ignored, while .env.example is committed and must keep the
+        // CHANGE_ME placeholder.
+        const jwtSecret = crypto.randomBytes(48).toString('hex');
         for (const envExample of ['server/.env.example', 'client/.env.example']) {
           const examplePath = path.join(targetDir, envExample);
           const envPath = path.join(targetDir, envExample.replace('.env.example', '.env'));
           if (await fs.pathExists(examplePath)) {
-            await fs.copy(examplePath, envPath);
+            const content = await fs.readFile(examplePath, 'utf-8');
+            await fs.writeFile(
+              envPath,
+              content.replaceAll(JWT_SECRET_PLACEHOLDER, jwtSecret),
+              'utf-8',
+            );
           }
         }
 
@@ -423,8 +462,9 @@ async function main() {
       console.log();
       console.log(dim('  App           ') + cyan('http://localhost:3000'));
       console.log(dim('  API           ') + cyan('http://localhost:8000'));
-      console.log(dim('  phpMyAdmin    ') + cyan(`http://localhost:${variables.PHPMYADMIN_PORT}`));
-      console.log(dim('  Redis CMD     ') + cyan(`http://localhost:${variables.REDIS_COMMANDER_PORT}`));
+      console.log(dim('  DB/Redis UIs  ') + 'optional — start with ' + cyan('npm run docker:tools'));
+      console.log(dim('    phpMyAdmin  ') + cyan(`http://localhost:${variables.PHPMYADMIN_PORT}`));
+      console.log(dim('    Redis CMD   ') + cyan(`http://localhost:${variables.REDIS_COMMANDER_PORT}`));
       console.log();
       console.log(line);
       console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tigra",
-    "version": "2.7.2",
+  "version": "3.0.0",
   "type": "module",
   "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
   "bin": {
@@ -13,7 +13,7 @@
     "template"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "keywords": [
     "create",
@@ -46,10 +46,10 @@
   },
   "dependencies": {
     "chalk": "^5.4.1",
-    "commander": "^13.1.0",
+    "commander": "^15.0.0",
     "fs-extra": "^11.3.0",
-    "ora": "^8.2.0",
+    "ora": "^9.0.0",
     "prompts": "^2.4.2",
-    "ts-morph": "^27.0.2"
+    "ts-morph": "^28.0.0"
   }
 }

package/template/_claude/commands/create-server.md

@@ -134,12 +134,18 @@ Include: node_modules, dist, .env, .env.local, .env*.local, *.log, .prisma
 #### `docker-compose.yml`
 Create a Docker Compose file with these services:
 1. **mysql** - MySQL 8.0, port 3306, database name = `$ARGUMENTS`, root password = `rootpassword`, volume for data persistence, healthcheck
-2. **phpmyadmin** - Latest, port 8080, linked to mysql
+2. **phpmyadmin** - Latest, port 8080, linked to mysql, behind the `tools` profile
 3. **redis** - Redis 7 Alpine, port 6379, volume for data persistence, healthcheck
-4. **redis-commander** - Redis Commander UI, port 8081, linked to redis
+4. **redis-commander** - Redis Commander UI, port 8081, linked to redis, behind the `tools` profile
 
 Use a named network for all services. Add restart policies.
 
+**Security requirements (dev attack surface):**
+- Bind ALL published ports to localhost (`127.0.0.1:<port>:<container-port>`), never `0.0.0.0` — these are dev credentials (root password, unpassworded Redis).
+- Put the admin UIs (**phpmyadmin**, **redis-commander**) behind `profiles: ["tools"]` so they do NOT start by default:
+  - `docker compose up -d` → MySQL + Redis only
+  - `docker compose --profile tools up -d` → also starts phpMyAdmin + Redis Commander
+
 ---
 
 ### Step 2: Source Code Structure

package/template/_claude/rules/client/01-project-structure.md

@@ -133,3 +133,15 @@ export const CURRENCIES = { USD: 'USD', EUR: 'EUR' } as const;
 
 Protected paths: `/dashboard`, `/profile`, `/admin` — redirect to `/login` if no token.
 Auth paths: `/login`, `/register` — redirect to `/dashboard` if already authenticated.
+
+When creating a new page, always add it to `protectedPaths` and `config.matcher` in `middleware.ts` if it requires authentication. If you are unsure whether a page should be protected, **ask the user** — do not guess.
+
+### Deleting a Route
+
+When removing a page/route, you MUST update **all three** locations:
+
+1. **Delete the page file**: `app/<route>/page.tsx` (and the folder if empty)
+2. **Remove from `routes.ts`**: Delete the entry in `lib/constants/routes.ts`
+3. **Remove from `middleware.ts`**: Delete from `protectedPaths` array AND `config.matcher` array
+
+Missing any of these leaves dead references or broken middleware matches.

package/template/_claude/rules/client/03-data-and-state.md

@@ -25,12 +25,15 @@
 Defaults in `app/providers.tsx`:
 
 ```typescript
-staleTime: 5 * 60 * 1000    // 5 min
-gcTime: 10 * 60 * 1000      // 10 min
-refetchOnWindowFocus: false
+staleTime: 30 * 1000         // 30s — short enough that back-navigation refetches
+gcTime: 5 * 60 * 1000        // 5 min
+refetchOnWindowFocus: true   // catch cross-tab edits
+refetchOnMount: true         // always refetch stale data on mount
 retry: 1
 ```
 
+**Why these values matter**: With a long `staleTime` (e.g. 5 min) and `refetchOnWindowFocus: false`, navigating back to a list page after editing a record on another page will show stale data until the user hard-refreshes. Keep `staleTime` short and let invalidation + remount refetch do their job.
+
 ### Query Key Factory Pattern
 
 ```typescript
@@ -45,9 +48,35 @@ export const itemKeys = {
 
 ### Mutations
 
-On success: invalidate related queries, show toast, navigate if needed.
+On success:
+1. **`queryClient.invalidateQueries({ queryKey: ... })`** — refreshes any client-fetched data (React Query).
+2. **`router.refresh()`** — refreshes any Server-Component-rendered data on the next route the user navigates to. Without this, the Next.js Router Cache will serve stale RSC payloads on back-navigation, and your edit will not appear until a hard refresh.
+3. Show a toast.
+4. Navigate if needed.
+
 On error: `toast.error(getErrorMessage(error))`.
 
+**Always call both `invalidateQueries` AND `router.refresh()`** unless you are 100% certain no Server Component on any reachable route reads the mutated data. The two caches are independent — invalidating one does not touch the other.
+
+```typescript
+const router = useRouter();
+const queryClient = useQueryClient();
+
+const mutation = useMutation({
+  mutationFn: (data) => itemService.updateItem(id, data),
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: itemKeys.all });
+    router.refresh();
+    toast.success('Item updated');
+  },
+  onError: (error) => toast.error(getErrorMessage(error)),
+});
+```
+
+### Next.js Router Cache
+
+`next.config.ts` sets `experimental.staleTimes: { dynamic: 0, static: 30 }` to minimize client-side Router Cache reuse. `static: 30` is the **Next 16.2+ minimum** — the config schema rejects values below 30, and an invalid value is silently ignored (re-enabling the default Router Cache). `dynamic: 0` is what protects data pages. **Never raise these values above these minimums** — doing so reintroduces the back-navigation stale-data bug across every page that uses Server Components for data fetching.
+
 ---
 
 ## Redux
@@ -61,7 +90,17 @@ State shape:
 { user: IUser | null; isAuthenticated: boolean; isInitializing: boolean; isLoggingOut: boolean }
 ```
 
-**Not persisted to localStorage** — auth state is hydrated on page load by `AuthInitializer` calling `getMe()`. Tokens are stored in httpOnly cookies (not accessible from JS).
+**Not persisted to localStorage** — auth state is hydrated by `AuthInitializer`, which calls the `useCurrentUser()` hook. `useCurrentUser()` is a React Query wrapper around `authService.getMe()` that syncs the result into Redux via a side effect. Tokens are stored in httpOnly cookies (not accessible from JS).
+
+**Refreshing the current user**: any mutation that changes the logged-in user's own data (profile update, role change, avatar upload, email verification, subscription change, etc.) MUST invalidate the auth query so Redux picks up the new values:
+
+```typescript
+import { authKeys } from '@/features/auth/hooks/useCurrentUser';
+
+queryClient.invalidateQueries({ queryKey: authKeys.me() });
+```
+
+Without this, Redux will hold the stale snapshot from initial page load until the next window-focus refetch (30s staleTime), or until logout/hard refresh. Never write directly to the auth slice from outside the auth feature — always go through invalidation.
 
 ---
 

package/template/_claude/rules/client/04-design-system.md

@@ -339,6 +339,28 @@ Link:    transition-colors duration-150 active:opacity-70 md:hover:text-primary
 - **Sticky action bars**: Form submit buttons, checkout CTAs — `sticky bottom-0` on mobile.
 - **No hamburger menus** for ≤5 items. Use bottom tab bar instead.
 
+### BottomNav Overlap — Fixed Bottom Elements
+
+When a page has its own `fixed bottom-0` element (e.g., sticky order bar, floating CTA), it **will be hidden behind BottomNav** on mobile. The BottomNav is `fixed bottom-0 z-50` with a height of `4rem` (64px).
+
+**Define the CSS variable** in the BottomNav component:
+```css
+:root {
+  --bottom-nav-height: 4rem;
+}
+```
+
+**Every fixed bottom element on a page** must offset itself above BottomNav on mobile:
+```
+bottom-[var(--bottom-nav-height)] md:bottom-0
+```
+Or the shorthand equivalent:
+```
+bottom-16 md:bottom-0
+```
+
+This is not optional — without it, BottomNav covers the element and users cannot tap it on mobile.
+
 ---
 
 ## Images
@@ -383,3 +405,4 @@ Link:    transition-colors duration-150 active:opacity-70 md:hover:text-primary
 - Reduce shadow visibility in dark mode (use subtle light borders instead).
 - Consider `brightness-90` on images in dark mode.
 - Add `suppressHydrationWarning` to `<html>` tag.
+- **Hydration guard for conditional theme renders**: `useTheme()` returns `undefined` on the server. Any component that renders *different JSX* based on `theme` (e.g. showing a Sun icon OR a Moon icon — not both) will throw a hydration mismatch. Either render both icons and style the active one (see `components/common/ThemeToggle.tsx`), or add a `mounted` guard: `const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []);` and return `null`/a placeholder until `mounted` is true.

package/template/_claude/rules/client/05-security.md

@@ -37,7 +37,7 @@ X-XSS-Protection: 1; mode=block
 default-src 'self';
 script-src 'self' 'unsafe-eval' 'unsafe-inline';
 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';

package/template/_claude/rules/client/07-deployment.md

@@ -0,0 +1,99 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# 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 client uses a **3-stage multi-stage build** with Next.js `standalone` output:
+
+```
+Stage 1 (dependencies)  → Installs all node_modules (cached layer)
+Stage 2 (builder)        → Copies deps, builds Next.js with standalone output
+Stage 3 (production)     → Alpine + dumb-init, non-root user, copies standalone + static + public
+```
+
+**Entry point**: `node server.js` (generated by Next.js standalone output in `.next/standalone/`)
+**Health check**: `GET /` — returns 200 if the Next.js server is running.
+
+### Critical Config Requirement
+
+`next.config.ts` **must** have `output: "standalone"`. Without it, the Dockerfile will fail because `.next/standalone/` won't be generated. Never remove this setting.
+
+---
+
+## Build Arguments (NEXT_PUBLIC_* Variables)
+
+Next.js **inlines** all `NEXT_PUBLIC_*` values into the JavaScript bundle at build time. They are NOT read from the environment at runtime. This means:
+
+- Every `NEXT_PUBLIC_*` variable must be declared as `ARG` + `ENV` in the **builder stage** of the Dockerfile.
+- They must be passed via `--build-arg` during `docker build` (or via Coolify's Build Arguments UI).
+- **If you add a new `NEXT_PUBLIC_*` env var, you MUST add it to the Dockerfile builder stage.**
+
+```dockerfile
+# In the builder stage:
+ARG NEXT_PUBLIC_NEW_VAR
+ENV NEXT_PUBLIC_NEW_VAR=$NEXT_PUBLIC_NEW_VAR
+```
+
+Current build arguments:
+- `NEXT_PUBLIC_API_BASE_URL` — Backend API URL (e.g., `https://api.yourdomain.com/api/v1`)
+- `NEXT_PUBLIC_APP_NAME` — App display name
+
+---
+
+## When to Update the Dockerfile
+
+| You did this... | Update Dockerfile? | What to change |
+|---|---|---|
+| Added a new npm dependency | No | Automatic — installed during build |
+| Added a native/system dependency (e.g., `sharp` for image optimization) | **Yes** | Add `apk add` in the production stage |
+| Added a new `NEXT_PUBLIC_*` env var | **Yes** | Add `ARG` + `ENV` in the builder stage |
+| Changed the public directory structure | No | Automatic — `COPY /app/public ./public` |
+| Added server-only env vars (no `NEXT_PUBLIC_` prefix) | No | Injected at runtime via Coolify |
+| Changed the default port | **Yes** | Update `ENV PORT`, `EXPOSE`, and `HEALTHCHECK` |
+| Added custom `next.config.ts` rewrites/redirects | No | Baked into the build automatically |
+| Added API routes (`app/api/`) | No | Included in standalone output |
+| Removed `output: "standalone"` from next.config.ts | **BREAKING** | Entire Dockerfile depends on standalone output |
+
+---
+
+## Critical Rules
+
+1. **Never remove `output: "standalone"`** from `next.config.ts`. The entire Docker build depends on it. Without it, the standalone server won't be generated and the Dockerfile will fail.
+
+2. **Every `NEXT_PUBLIC_*` var needs a Dockerfile `ARG`.** Next.js inlines these at build time. If you add one to `.env.example` but forget the Dockerfile, the value will be `undefined` in production.
+
+3. **Static assets and public files are separate.** The standalone output does NOT include `.next/static/` or `public/`. The Dockerfile copies them explicitly. If you add a new top-level directory that must be available at runtime (unlikely), add a `COPY` line.
+
+4. **Non-root user.** The app runs as `nextjs:nodejs` (UID 1001). Next.js standalone doesn't write to disk at runtime, so this is straightforward.
+
+5. **No secrets in the image.** Server-only env vars (without `NEXT_PUBLIC_` prefix) are injected at runtime. Never hardcode secrets or use `ENV` for sensitive values in the Dockerfile.
+
+6. **Keep `.dockerignore` in sync.** When adding directories that should NOT be in the build context (test fixtures, docs, Storybook), add them to `.dockerignore`. When adding files needed at build time, ensure they're not ignored.
+
+7. **`HOSTNAME="0.0.0.0"`** is required. Without it, Next.js standalone only listens on `127.0.0.1` inside the container, making it unreachable from outside.
+
+---
+
+## Coolify-Specific Notes
+
+- **Build Arguments**: Set `NEXT_PUBLIC_API_BASE_URL` and `NEXT_PUBLIC_APP_NAME` in Coolify's "Build Arguments" section (not environment variables — those are runtime only).
+- **Environment Variables**: Server-only vars (database URLs, API keys used in Server Components/Route Handlers) go in Coolify's "Environment Variables" section — available at runtime.
+- **Port**: Default `3000`. Override via `PORT` environment variable in Coolify.
+- **No volume mounts needed**: Next.js client apps are stateless — no uploads, no local file writes.
+
+---
+
+## Files That Matter for Deployment
+
+| File | Purpose | Must exist? |
+|---|---|---|
+| `Dockerfile` | Production build instructions | Yes |
+| `.dockerignore` | Excludes files from Docker build context | Yes |
+| `next.config.ts` | Must have `output: "standalone"` | Yes |
+| `package.json` | Dependencies and build script | Yes |
+| `public/` | Static assets (favicon, images) | Yes |

package/template/_claude/rules/client/08-lockfile-cross-platform.md

@@ -0,0 +1,79 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Lockfile — Cross-Platform Regeneration
+
+`client/package-lock.json` has burned us — and bots — multiple times in projects scaffolded from this template. Read this before touching it.
+
+## The trap
+
+`client/package-lock.json` is consumed by **three different environments**:
+
+| Environment | OS / libc | npm |
+|---|---|---|
+| Local dev (most contributors) | Windows / macOS | npm 11.x |
+| GitHub Actions CI (`server-ci.yml`, `client-ci.yml`) | `ubuntu-latest` (Debian glibc) | npm 10.x (ships with Node 20) |
+| Coolify / production deploy (`client/Dockerfile`) | `node:20-alpine` (musl) | npm 10.x |
+
+`npm ci` is **strict** — it refuses to install if the lockfile is even slightly out of sync with `package.json`, AND it only installs the platform-specific `optionalDependencies` whose top-level `node_modules/<pkg>` entries exist in the lockfile. If you regenerate on Windows with `npm install`, you get a Windows-leaning lockfile that:
+
+1. May be missing entries the newer npm 10 (CI) considers required (`Missing: @swc/helpers@0.5.21 from lock file` — common failure mode).
+2. Lacks `*-linux-x64-gnu` / `*-linuxmusl-x64` entries → CI's `next build` fails with `Cannot find module '../lightningcss.linux-x64-gnu.node'` or `No prebuild or local build of @parcel/watcher found.`
+
+Affected native packages (Next 16 + Tailwind v4 dep tree): `@parcel/watcher`, `lightningcss`, `@img/sharp`, `@next/swc`, `@swc/core`, `@tailwindcss/oxide`, `@unrs/resolver-binding`, `@rolldown/binding`.
+
+## Canonical fix (use this exactly)
+
+Whenever you regenerate `client/package-lock.json` — even just because `package.json` changed by one dep — run **all three** steps. They are additive (`--package-lock-only` doesn't touch `node_modules`).
+
+```bash
+cd client
+
+# 0. (Optional) Start fresh if the existing lockfile is already broken:
+rm -rf node_modules package-lock.json
+
+# 1. Sync the lockfile against package.json (fixes the "Missing: foo from lock file" class).
+npx -y npm@10 install --package-lock-only
+
+# 2. Add Linux/glibc native variants (GitHub Actions Ubuntu).
+npx -y npm@10 install --os=linux --cpu=x64 --libc=glibc --package-lock-only
+
+# 3. Add Linux/musl native variants (Coolify Alpine deploy).
+npx -y npm@10 install --os=linux --cpu=x64 --libc=musl --package-lock-only
+```
+
+### Required choices
+
+- **`npx -y npm@10` explicitly.** Local default npm 11.x resolves a tree npm 10 strict-checks reject. Match CI's npm version or you'll push a lockfile that fails immediately.
+- **`--package-lock-only`** keeps each command at ~1 sec (no install, no audit).
+- **Three platforms.** Even if you only intend to fix CI, do the musl pass too — Coolify deploy will fail otherwise.
+- **Skip darwin** unless a team member dev's on macOS and reports `npm ci` failing. Not worth the lockfile churn pre-emptively.
+
+## Verify before committing
+
+```bash
+cd client
+
+# A. Strict install passes with CI's npm version (this is the exact check CI runs):
+npx -y npm@10 ci --include=optional --no-audit --no-fund 2>&1 | tail -3
+# Expect: "added N packages in Xs". Any "EUSAGE" / "Missing:" means step 1 didn't take.
+
+# B. All native deps have glibc + musl entries:
+for pkg in '@next/swc' '@swc/core' '@parcel/watcher' '@rolldown/binding' \
+           '@tailwindcss/oxide' '@unrs/resolver-binding' 'lightningcss'; do
+  g=$(grep -cE "node_modules/${pkg}.*-linux-x64-(gnu|glibc)\"" package-lock.json)
+  m=$(grep -cE "node_modules/${pkg}-linux-x64-musl\"" package-lock.json)
+  echo "$pkg glibc=$g musl=$m"
+done
+# Expect every line: glibc=1 musl=1. (sharp uses different naming — check separately:
+# grep -oE 'node_modules/@img/sharp[-a-z0-9]*' package-lock.json | sort -u)
+```
+
+If either check fails, the lockfile is not ready — do not commit.
+
+## Anti-patterns (don't do these — every one has burned us)
+
+1. **Plain `npm install` on Windows/macOS.** Uses local npm 11; produces lockfiles CI rejects.
+2. **Whack-a-mole pinning** in `package.json` `optionalDependencies` (e.g., adding only `@parcel/watcher-linux-x64-glibc` and hoping it fixes everything). It doesn't — there are 7+ such native deps and you'll bounce through them one CI failure at a time.
+3. **Disabling `npm ci` in CI** by switching to `npm install` to "fix" the symptom. That makes builds non-reproducible.
+4. **Bypassing the husky pre-commit hook** with `--no-verify` to push a broken lockfile fast.
+5. **Generating inside Docker on a hung Docker daemon** without verifying the daemon is healthy first — the run silently buffers and you wait 10+ minutes. (The non-Docker `npx npm@10 install --package-lock-only` chain above is faster and equally correct.)

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

@@ -12,6 +12,7 @@
 | Choosing colors, styling, typography, spacing, motion, **theme colors**, **font presets** | `04-design-system.md` |
 | Auth tokens, env vars, security headers | `05-security.md` |
 | UX psychology, cognitive load, a11y, performance | `06-ux-checklist.md` |
+| Regenerating `client/package-lock.json`, fixing CI `npm ci` failures, cross-platform native binaries (`@parcel/watcher`, `lightningcss`, `@img/sharp`, etc.) | `08-lockfile-cross-platform.md` |
 
 ---
 

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

@@ -51,7 +51,7 @@ When the user asks to create, scaffold, or start a new server or client project,
 - **`.env` files are never committed.** Use `.env.example` as the template with placeholder values.
 - **Adding a new env var**: Add it to `.env.example` with a comment, and document where it's used.
 - **Keep `.env` and `.env.example` in sync**: Any change to `.env` (adding, removing, or renaming a variable) must be reflected in `.env.example`, and vice versa. They must always have the same set of variables.
-- **Keep `.env.example.production` in sync**: Every time `.env` or `.env.example` changes (variable added, removed, or renamed), also update `.env.example.production` in the same directory. If the file does not exist, create it. This file uses the same variable names but with **production-appropriate placeholder values** and comments (e.g., secure passwords, real domain URLs, SSL-enabled connection strings, stricter timeouts). This applies to both `server/` and `client/` directories.
+- **Keep `.env.example.production` in sync**: Every time `.env` or `.env.example` changes (variable added, removed, or renamed), also update `.env.example.production` in the same directory. If the file does not exist, create it. This file uses the same variable names but with **production-appropriate placeholder values** and comments (e.g., secure passwords, real domain URLs, SSL-enabled connection strings, stricter timeouts). See the server's `.env.example.production` for the expected style. This applies to both `server/` and `client/` directories.
 - **Secrets** (DB URLs, JWT secrets, API keys) must never be prefixed with `NEXT_PUBLIC_` and must never appear in client-side code.
 - **Public values only** (API base URL, app name) get the `NEXT_PUBLIC_` prefix.
 
@@ -63,6 +63,23 @@ When the user asks to create, scaffold, or start a new server or client project,
 - **Test naming**: `describe('<ModuleName>')` → `it('should <expected behavior>')`.
 - **Tests must be deterministic**: No reliance on real time, network, or random values. Mock external dependencies.
 - **Don't test implementation details** — test behavior and outputs.
+- **No "mock-echo" tests**: Don't mock a dependency (Prisma/ORM, HTTP client) and then only assert it was called with the same arguments the code passes straight through — that restates the implementation and verifies no behavior. A "was-called-with" assertion is valid only when the layer *transformed* the input first (filtering, pagination math, conditional queries) or when you ALSO assert on the returned value / observable result.
+- **Don't test logic-free layers**: If a unit only forwards to a dependency with no logic of its own (a thin repository/passthrough), don't test it — put the test on the service/behavior layer, where the branches and bugs are.
+
+---
+
+## Deployment Awareness
+
+Both server and client are deployed via **Docker on Coolify**. The `Dockerfile` in each directory is the production deployment contract. Code changes must never silently break the Docker build.
+
+**Always check deployment impact when you:**
+- Add a native/system npm dependency (needs `apk add` in Dockerfile)
+- Add, remove, or rename a `NEXT_PUBLIC_*` env var (needs `ARG` + `ENV` in client Dockerfile)
+- Change the build output directory, entry point file, or default port
+- Add runtime file dependencies (templates, static assets not in `public/`)
+- Change or remove a health check endpoint
+
+**See the deployment rules** in `server/deployment.md` and `client/07-deployment.md` for full details.
 
 ---
 
@@ -83,3 +100,5 @@ Before considering work done, verify:
 - [ ] Inputs validated with Zod.
 - [ ] Error cases handled (not just the happy path).
 - [ ] Existing tests still pass.
+- [ ] No "mock-echo" tests (asserting only that a mock was called, without asserting behavior/output or testing a real transform).
+- [ ] Dockerfile still compatible with changes (see Deployment Awareness above).