@levironexe/architect 0.1.0

package/skills/patterns/clerk-auth.skill.yaml

@@ -0,0 +1,349 @@
+schema_version: "2.0.0"
+id: clerk-auth
+name: "Clerk Auth"
+version: "2.0.0"
+description: "Managed authentication with Clerk — middleware route protection, server/client user access patterns, webhook database sync, and organization-based multi-tenancy."
+category: pattern
+language: javascript
+frameworks:
+  - clerk
+dependencies:
+  none:
+    - next-auth
+    - "@supabase/ssr"
+    - lucia
+detection:
+  dependencies:
+    any:
+      - "@clerk/nextjs"
+      - "@clerk/clerk-sdk-node"
+      - "@clerk/clerk-react"
+  source_indicators:
+    - "ClerkProvider"
+    - "clerkMiddleware"
+    - "auth()"
+    - "currentUser()"
+    - "useUser()"
+    - "useAuth()"
+structure:
+  required_dirs:
+    - path: app/api/webhooks/clerk
+      purpose: "Clerk webhook handler route — receives user.created, user.updated, and user.deleted events pushed by Clerk's servers. Must verify the Svix signature on every incoming request before touching the database — no signature check means attackers can forge any user lifecycle event."
+  recommended_dirs:
+    - path: src/lib
+      purpose: "Server-only Clerk helpers — auth() call wrappers, organization guard functions, and backend Clerk SDK calls (e.g., clerkClient().users.updateUserMetadata). Never import from here in Client Components ('use client' files)."
+    - path: middleware.ts
+      purpose: "Project root middleware file — clerkMiddleware() runs before every page render and API call, enforcing public vs. protected route separation. Only one middleware.ts is allowed per Next.js project; it must be at the root alongside app/."
+separation:
+  rules:
+    - concern: route_protection
+      belongs_in: middleware.ts
+      rule_text: "Use clerkMiddleware() in middleware.ts to protect routes. Define public routes with createRouteMatcher — every other route is protected by default and redirects to sign-in. Never add per-page auth checks in layout.tsx or page.tsx as a substitute for middleware."
+      example: |
+        // middleware.ts — runs before every request
+        import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+        const isPublicRoute = createRouteMatcher([
+          '/sign-in(.*)',
+          '/sign-up(.*)',
+          '/api/webhooks/(.*)',
+          '/',
+        ]);
+
+        export default clerkMiddleware(async (auth, req) => {
+          if (!isPublicRoute(req)) await auth.protect();
+        });
+
+        export const config = {
+          matcher: [
+            '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+            '/(api|trpc)(.*)',
+          ],
+        };
+      indicators:
+        - "clerkMiddleware"
+        - "createRouteMatcher"
+        - "auth.protect()"
+        - "isPublicRoute"
+    - concern: server_user_access
+      belongs_in: app
+      rule_text: "In Server Components and API route handlers, use auth() from @clerk/nextjs/server to get the current session (userId, orgId). For full user profile data (name, email, imageUrl), use currentUser() — it makes a network call to Clerk's API so only call it when the profile data is actually needed."
+      example: |
+        // app/dashboard/page.tsx — Server Component
+        import { auth, currentUser } from '@clerk/nextjs/server';
+        import { redirect } from 'next/navigation';
+
+        export default async function DashboardPage() {
+          const { userId } = await auth();
+          if (!userId) redirect('/sign-in');
+
+          // Only call currentUser() when you need profile fields beyond userId
+          const user = await currentUser();
+          return <h1>Welcome, {user?.firstName}</h1>;
+        }
+
+        // app/api/user/route.ts — API route
+        import { auth } from '@clerk/nextjs/server';
+        export async function GET() {
+          const { userId } = await auth();
+          if (!userId) return new Response('Unauthorized', { status: 401 });
+          const userData = await db.user.findUnique({ where: { clerkId: userId } });
+          return Response.json(userData);
+        }
+      indicators:
+        - "from '@clerk/nextjs/server'"
+        - "auth()"
+        - "currentUser()"
+        - "userId"
+    - concern: client_user_access
+      belongs_in: components
+      rule_text: "In Client Components, use useUser(), useAuth(), or useClerk() hooks from @clerk/nextjs. These hooks read from the ClerkProvider context — they work only inside components rendered below <ClerkProvider> in the tree. Use for display-only UI (avatars, names, role badges) — never for access control decisions."
+      example: |
+        // components/user-avatar.tsx — Client Component
+        'use client';
+        import { useUser } from '@clerk/nextjs';
+
+        export function UserAvatar() {
+          const { user, isLoaded, isSignedIn } = useUser();
+
+          // isLoaded prevents hydration mismatch
+          if (!isLoaded) return <div className="h-8 w-8 rounded-full bg-gray-200 animate-pulse" />;
+          if (!isSignedIn) return null;
+
+          return (
+            <img
+              src={user.imageUrl}
+              alt={user.fullName ?? 'User avatar'}
+              className="h-8 w-8 rounded-full"
+            />
+          );
+        }
+      indicators:
+        - "useUser()"
+        - "useAuth()"
+        - "useClerk()"
+        - "from '@clerk/nextjs'"
+    - concern: webhook_sync
+      belongs_in: app/api/webhooks/clerk
+      rule_text: "Verify the Svix signature before processing any webhook event. Sync user lifecycle events (user.created, user.updated, user.deleted) to your database. Store Clerk's userId as a NOT NULL UNIQUE 'clerkId' column in your users table — never store email alone because users can change their email in Clerk's dashboard."
+      example: |
+        // app/api/webhooks/clerk/route.ts
+        import { Webhook } from 'svix';
+        import { headers } from 'next/headers';
+        import type { WebhookEvent } from '@clerk/nextjs/server';
+
+        export async function POST(req: Request) {
+          const body = await req.text();
+          const h = await headers();
+
+          const wh = new Webhook(process.env.CLERK_WEBHOOK_SECRET!);
+          // wh.verify() throws WebhookVerificationError on invalid signature
+          const event = wh.verify(body, {
+            'svix-id': h.get('svix-id')!,
+            'svix-timestamp': h.get('svix-timestamp')!,
+            'svix-signature': h.get('svix-signature')!,
+          }) as WebhookEvent;
+
+          switch (event.type) {
+            case 'user.created':
+              await db.user.create({
+                data: {
+                  clerkId: event.data.id,
+                  email: event.data.email_addresses[0].email_address,
+                  name: `${event.data.first_name} ${event.data.last_name}`.trim(),
+                },
+              });
+              break;
+            case 'user.updated':
+              await db.user.update({
+                where: { clerkId: event.data.id },
+                data: { email: event.data.email_addresses[0].email_address },
+              });
+              break;
+            case 'user.deleted':
+              await db.user.delete({ where: { clerkId: event.data.id! } });
+              break;
+          }
+
+          return new Response('OK', { status: 200 });
+        }
+      indicators:
+        - "Webhook"
+        - "svix"
+        - "CLERK_WEBHOOK_SECRET"
+        - "WebhookEvent"
+        - "svix-signature"
+    - concern: organization_access
+      belongs_in: app
+      rule_text: "For multi-tenant apps, read orgId from auth() and filter every database query by it. Switching organizations in Clerk's UI rotates the orgId in the session — your database queries automatically see only the new org's data. Never derive the organization from user metadata or a custom header."
+      example: |
+        // app/projects/page.tsx — scoped to active organization
+        import { auth } from '@clerk/nextjs/server';
+        import { redirect } from 'next/navigation';
+
+        export default async function ProjectsPage() {
+          const { userId, orgId } = await auth();
+          if (!userId) redirect('/sign-in');
+          if (!orgId) redirect('/select-org'); // user hasn't selected an org yet
+
+          // Every query filtered by orgId — no cross-tenant data leaks
+          const projects = await db.project.findMany({
+            where: { orgId },
+            orderBy: { createdAt: 'desc' },
+          });
+
+          return <ProjectList projects={projects} />;
+        }
+      indicators:
+        - "orgId"
+        - "orgRole"
+        - "useOrganization()"
+        - "useOrganizationList()"
+        - "orgSlug"
+patterns:
+  data_flow:
+    direction: "HTTP Request → clerkMiddleware (protect or allow) → Server Component (auth()) → Service/DB"
+    rules:
+      - "Middleware runs first — protected routes redirect to sign-in before any page code executes."
+      - "Server Components call auth() for session (userId, orgId) and currentUser() for profile data — currentUser() costs an extra network call so only call it when needed."
+      - "Client Components use useUser()/useAuth() hooks — they read from ClerkProvider context already in the page, zero extra network call."
+      - "Webhooks are the bridge from Clerk's managed user store to your relational database — sync on user.created/updated/deleted events."
+      - "For multi-tenant apps: auth() → { userId, orgId } → every DB query includes orgId in WHERE clause."
+      - "publicMetadata and privateMetadata must only be mutated from Server Actions or API routes, never from Client Components."
+  error_handling:
+    recommended: "Use auth.protect() in middleware for route-level protection. For API routes not covered by middleware, check auth().userId and return 401 when null. For org-scoped routes, check auth().orgId and redirect to /select-org when null."
+  naming:
+    middleware: "middleware.ts at project root — clerkMiddleware() must be the outermost and only middleware"
+    webhook_handler: "app/api/webhooks/clerk/route.ts — POST handler with Svix signature verification"
+    server_helper: "src/lib/auth.ts — reusable server-side auth wrappers (requireAuth, requireOrg)"
+    db_field: "clerkId — NOT NULL UNIQUE column in users table; stores Clerk's userId string (format: user_XXXX)"
+    org_db_field: "orgId — NOT NULL column on organization-scoped tables; stores Clerk's orgId string (format: org_XXXX)"
+anti_patterns:
+  - id: manual_token_handling
+    severity: critical
+    description: "Manually reading, parsing, or verifying Clerk JWTs or __session cookies instead of using Clerk's auth() helper. This breaks when Clerk rotates signing keys (which happens automatically), and bypasses session freshness checks, leaving stale or forged tokens accepted."
+    bad_example: |
+      // ❌ Manual JWT parsing — breaks on key rotation, bypasses Clerk's checks
+      import jwt from 'jsonwebtoken';
+      const token = req.headers.authorization?.split(' ')[1];
+      const decoded = jwt.verify(token, process.env.CLERK_PEM_KEY!);
+      const userId = (decoded as any).sub;
+      // This will silently break the next time Clerk rotates its signing key
+    good_example: |
+      // ✓ Clerk's auth() handles verification, key rotation, and session refresh automatically
+      import { auth } from '@clerk/nextjs/server';
+      const { userId } = await auth();
+      if (!userId) return new Response('Unauthorized', { status: 401 });
+  - id: unverified_webhook
+    severity: critical
+    description: "Processing Clerk webhook payloads without verifying the Svix HMAC signature. Any attacker who discovers your webhook endpoint URL can POST fabricated user.created or user.deleted events — creating phantom users, deleting real users, or granting admin roles without ever touching Clerk's dashboard."
+    bad_example: |
+      // ❌ No signature verification — endpoint is open to forgery
+      export async function POST(req: Request) {
+        const payload = await req.json();
+        // Blindly trusting the payload type and data
+        if (payload.type === 'user.created') {
+          await db.user.create({
+            data: { clerkId: payload.data.id, role: 'admin' }, // forged!
+          });
+        }
+        return new Response('OK');
+      }
+    good_example: |
+      // ✓ Svix verification throws WebhookVerificationError on tampered requests
+      import { Webhook } from 'svix';
+      const wh = new Webhook(process.env.CLERK_WEBHOOK_SECRET!);
+      const event = wh.verify(body, svixHeaders) as WebhookEvent;
+      // Only reaches here if signature is valid
+      if (event.type === 'user.created') {
+        await db.user.create({ data: { clerkId: event.data.id } });
+      }
+  - id: client_component_auth_check
+    severity: warning
+    description: "Using useUser() or useAuth() to gate protected content or navigation in Client Components. Client-side auth can be bypassed by disabling JavaScript, using browser DevTools to modify React state, or navigating directly via URL. Always enforce access control in middleware or Server Components."
+    bad_example: |
+      // ❌ Client-side guard — content flashes and is bypassable with DevTools
+      'use client';
+      import { useAuth } from '@clerk/nextjs';
+      export function AdminPanel() {
+        const { isSignedIn } = useAuth();
+        if (!isSignedIn) return null; // briefly visible during hydration; bypassable
+        return <DangerousAdminActions />;
+      }
+    good_example: |
+      // ✓ Server Component — auth check happens before any HTML is sent
+      import { auth } from '@clerk/nextjs/server';
+      import { redirect } from 'next/navigation';
+      export default async function AdminPage() {
+        const { userId } = await auth();
+        if (!userId) redirect('/sign-in');
+        return <DangerousAdminActions />;
+      }
+      // OR: add /admin to isPublicRoute exclusion in middleware.ts (simplest)
+  - id: missing_clerk_provider
+    severity: critical
+    description: "Not wrapping the root layout with <ClerkProvider>. All Clerk client hooks (useUser, useAuth, useClerk, SignInButton, UserButton) throw a React context error at runtime because they expect to find ClerkProvider as an ancestor in the component tree."
+    bad_example: |
+      // app/layout.tsx — missing ClerkProvider
+      export default function RootLayout({ children }: { children: React.ReactNode }) {
+        return (
+          <html lang="en">
+            <body>{children}</body>
+            {/* Any child that calls useUser() crashes:
+                Error: useUser() called outside <ClerkProvider> */}
+          </html>
+        );
+      }
+    good_example: |
+      // app/layout.tsx — ClerkProvider wraps the entire app
+      import { ClerkProvider } from '@clerk/nextjs';
+      export default function RootLayout({ children }: { children: React.ReactNode }) {
+        return (
+          <ClerkProvider>
+            <html lang="en">
+              <body>{children}</body>
+            </html>
+          </ClerkProvider>
+        );
+      }
+  - id: org_id_not_enforced
+    severity: warning
+    description: "In multi-tenant apps, querying the database without filtering by orgId. Users authenticated to organization A can read or modify organization B's data because the tenant boundary is not applied to the query."
+    bad_example: |
+      // ❌ Returns ALL projects regardless of the user's current organization
+      const { userId } = await auth();
+      // orgId is available but ignored — org B members see org A's data
+      const projects = await db.project.findMany({ where: { createdBy: userId } });
+    good_example: |
+      // ✓ Scope every query to the authenticated user's active organization
+      const { userId, orgId } = await auth();
+      if (!orgId) redirect('/select-organization');
+      const projects = await db.project.findMany({
+        where: { orgId }, // org boundary enforced at query level
+      });
+  - id: metadata_mutation_on_client
+    severity: warning
+    description: "Updating Clerk publicMetadata from a Client Component via the browser SDK. The client-side user.update() call is made with the user's own session, meaning any user can call it with arbitrary values — including promoting themselves to 'admin'. All metadata writes must go through a Server Action that validates permissions first."
+    bad_example: |
+      // ❌ Client-side metadata write — user can call update() with any role value
+      'use client';
+      import { useUser } from '@clerk/nextjs';
+      export function UpgradeButton() {
+        const { user } = useUser();
+        const upgrade = () => user?.update({ unsafeMetadata: { plan: 'enterprise' } });
+        return <button onClick={upgrade}>Upgrade</button>;
+      }
+    good_example: |
+      // ✓ Server Action validates the request before mutating metadata
+      'use server';
+      import { auth, clerkClient } from '@clerk/nextjs/server';
+      export async function upgradePlan(targetUserId: string) {
+        const { sessionClaims } = await auth();
+        // Only admins can upgrade other users
+        if (sessionClaims?.publicMetadata?.role !== 'admin') {
+          throw new Error('Forbidden');
+        }
+        await (await clerkClient()).users.updateUserMetadata(targetUserId, {
+          publicMetadata: { plan: 'enterprise' },
+        });
+      }

package/skills/patterns/docker-deploy.skill.yaml

@@ -0,0 +1,214 @@
+schema_version: "2.0.0"
+id: docker-deploy
+name: "Docker"
+version: "2.0.0"
+description: "Docker containerization with multi-stage builds, non-root user, runtime-injected secrets, HEALTHCHECK, pinned base image tags, and correct COPY order to maximize layer cache."
+category: pattern
+language: javascript
+frameworks: []
+dependencies:
+  none: []
+detection:
+  files:
+    - Dockerfile
+    - docker-compose.yml
+    - docker-compose.yaml
+  source_indicators:
+    - "FROM node:"
+    - "COPY --from=builder"
+    - "docker-compose"
+    - "AS builder"
+    - "AS production"
+structure:
+  required_dirs: []
+  recommended_dirs:
+    - path: docker
+      purpose: "Docker support files — entrypoint.sh (startup script that runs migrations before the app), healthcheck.sh (custom health probe script), and any docker-compose overrides. Keep these out of the project root to avoid clutter."
+    - path: .docker
+      purpose: "Alternative location for Docker configuration scripts — entrypoints, init scripts, and environment templates. Use one consistent location across the project."
+separation:
+  rules:
+    - concern: multi_stage_build
+      belongs_in: Dockerfile
+      rule_text: "Use a two-stage Dockerfile — a `builder` stage installs all dependencies (including devDependencies) and compiles the TypeScript source, and a `production` stage copies only the compiled output. Never copy the entire source or node_modules from the builder if you can reinstall with --omit=dev."
+      example: |
+        # Dockerfile
+        # Stage 1: build
+        FROM node:20-alpine AS builder
+        WORKDIR /app
+        # Copy package files first — layer is cached until package.json changes
+        COPY package*.json ./
+        RUN npm ci
+        COPY . .
+        RUN npm run build  # produces dist/
+
+        # Stage 2: production — only compiled output, no devDependencies
+        FROM node:20-alpine AS production
+        WORKDIR /app
+        COPY package*.json ./
+        RUN npm ci --omit=dev  # install only runtime deps — ~70% smaller image
+        COPY --from=builder /app/dist ./dist
+        # Run health checks, switch user, start app
+        HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+          CMD node -e "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"
+        USER node
+        CMD ["node", "dist/index.js"]
+      indicators:
+        - "FROM node:"
+        - "AS builder"
+        - "AS production"
+        - "COPY --from=builder"
+    - concern: non_root_user
+      belongs_in: Dockerfile
+      rule_text: "Switch to the built-in `node` user before the CMD or ENTRYPOINT instruction. Running as root in a container gives an attacker full host access if the container runtime is misconfigured or the app has a code execution vulnerability."
+      example: |
+        # ✓ Switch to non-root user — applied in the production stage
+        # Ensure the app directory is owned by node before switching
+        COPY --chown=node:node --from=builder /app/dist ./dist
+        USER node
+        CMD ["node", "dist/index.js"]
+      anti_indicators:
+        - "USER root"
+    - concern: env_injection
+      belongs_in: docker-compose.yml
+      rule_text: "Inject all secrets via environment variables at container runtime — never bake secrets into the image with ENV or ARG instructions. Use docker-compose's env_file directive to load from .env. Commit .env.example with placeholder values; add .env to .gitignore."
+      example: |
+        # docker-compose.yml — runtime environment injection
+        services:
+          app:
+            build: .
+            ports:
+              - "3000:3000"
+            env_file: .env          # loads DATABASE_URL, JWT_SECRET, etc. from .env
+            environment:
+              NODE_ENV: production  # non-secret config can be inline
+            restart: unless-stopped
+      indicators:
+        - "env_file:"
+        - "environment:"
+    - concern: layer_cache_order
+      belongs_in: Dockerfile
+      rule_text: "Order COPY instructions to maximize Docker's layer cache — copy package files (package.json, package-lock.json) and run npm ci BEFORE copying application source. Since package files change rarely, the npm ci layer is cached for the majority of builds."
+      example: |
+        # ✓ Package files first — npm ci layer cached unless package.json changes
+        COPY package*.json ./
+        RUN npm ci  # cached on most builds
+        COPY . .    # application source last — invalidates only subsequent layers
+        RUN npm run build
+
+        # ❌ WRONG ORDER — invalidates npm ci on every source file change:
+        # COPY . .         # copies everything including src/
+        # RUN npm ci       # re-runs on every code change — no cache benefit
+        # RUN npm run build
+      indicators:
+        - "COPY package*.json"
+    - concern: healthcheck
+      belongs_in: Dockerfile
+      rule_text: "Add a HEALTHCHECK instruction to every production Dockerfile. Without it, Docker and Kubernetes cannot distinguish between a starting container and a broken one — they keep routing traffic to unhealthy instances."
+      example: |
+        # Option 1: HTTP health check via node inline script (no extra dependencies)
+        HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+          CMD node -e "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"
+
+        # Option 2: wget (available in alpine)
+        HEALTHCHECK --interval=30s --timeout=5s CMD wget --quiet --tries=1 --spider http://localhost:3000/health || exit 1
+
+        # In docker-compose, override start-period for slow-starting apps:
+        # healthcheck:
+        #   test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/health"]
+        #   start_period: 30s
+      indicators:
+        - "HEALTHCHECK"
+        - "/health"
+patterns:
+  data_flow:
+    direction: "Source → Builder Stage (npm ci + tsc) → Production Stage (npm ci --omit=dev + dist copy) → Container Runtime (env vars injected)"
+    rules:
+      - "Builder stage: install all deps + compile TypeScript to dist/."
+      - "Production stage: reinstall only runtime deps (--omit=dev) + copy dist/ from builder."
+      - "Secrets injected at runtime via env_file — never in Dockerfile ENV or ARG."
+      - "COPY package files before COPY . . to maximize layer cache reuse."
+      - "HEALTHCHECK enables orchestrators to detect unhealthy containers automatically."
+  error_handling:
+    recommended: "Add a /health endpoint that returns 200 when the app is ready (DB connected, etc.) and 503 during startup or degraded state. HEALTHCHECK uses this to report container health to Docker/Kubernetes."
+  naming:
+    dockerfile: "Dockerfile at project root — multi-stage: AS builder then AS production"
+    compose: "docker-compose.yml (development) + docker-compose.prod.yml (production overrides)"
+    env_template: ".env.example committed to git with placeholder values; .env in .gitignore"
+    health_endpoint: "GET /health — returns { status: 'ok', uptime: number } with 200, or 503 during degraded state"
+anti_patterns:
+  - id: secrets_in_image
+    severity: critical
+    description: "Baking secrets into Docker images with ENV or ARG instructions. Secrets persist in image layers and are visible via `docker history` — anyone with pull access to the image registry can read them."
+    bad_example: |
+      # ❌ Secrets baked into the image — visible in docker history
+      ARG DATABASE_URL
+      ENV DATABASE_URL=${DATABASE_URL}
+      ENV JWT_SECRET=hardcoded-secret-key
+      # docker history myapp → shows JWT_SECRET value in the layer
+    good_example: |
+      # ✓ Inject secrets at runtime, not build time
+      # docker-compose.yml: env_file: .env
+      # Or: docker run --env-file .env myapp
+      # Image contains no secrets — safe to push to any registry
+  - id: single_stage_build
+    severity: warning
+    description: "Using a single-stage Dockerfile that includes all devDependencies, TypeScript source, and build tools in the production image. A typical Next.js project: single-stage = ~1.5 GB image, multi-stage = ~300 MB. Larger images mean slower deployments and a larger attack surface."
+    bad_example: |
+      # ❌ Single stage — devDependencies + source + build tools in production
+      FROM node:20
+      WORKDIR /app
+      COPY . .            # includes src/, tests/, .env.example
+      RUN npm install     # installs ALL deps including jest, ts-node, etc.
+      RUN npm run build
+      CMD ["node", "dist/index.js"]
+    good_example: |
+      # ✓ Multi-stage — production image has only what's needed to run
+      FROM node:20-alpine AS builder
+      RUN npm ci && npm run build
+      FROM node:20-alpine AS production
+      COPY package*.json ./
+      RUN npm ci --omit=dev  # runtime deps only
+      COPY --from=builder /app/dist ./dist
+  - id: running_as_root
+    severity: warning
+    description: "Not switching to a non-root user before CMD — Docker containers run as root by default. If the application has an RCE vulnerability, the attacker has root-level access inside the container."
+    bad_example: |
+      # ❌ No USER instruction — process runs as root inside container
+      COPY --from=builder /app/dist ./dist
+      CMD ["node", "dist/index.js"]
+    good_example: |
+      # ✓ Switch to the built-in non-root node user
+      COPY --chown=node:node --from=builder /app/dist ./dist
+      USER node
+      CMD ["node", "dist/index.js"]
+  - id: using_latest_tag
+    severity: warning
+    description: "Using `FROM node:latest` — the `latest` tag is a moving target that resolves to a different version on each build. When a new Node.js major is released, `latest` jumps to it and your build may fail with breaking changes. Pin to a specific LTS version."
+    bad_example: |
+      # ❌ Non-deterministic — breaks when node:latest jumps to a new major
+      FROM node:latest
+      # Today: node 22. After next LTS release: could be node 24 — breaking
+    good_example: |
+      # ✓ Pinned to a specific LTS version — predictable builds
+      FROM node:20-alpine AS builder
+      FROM node:20-alpine AS production
+      # To upgrade, explicitly change the version and test
+  - id: copying_node_modules
+    severity: warning
+    description: "Running COPY . . before npm ci causes local node_modules to be copied into the image. node_modules built on macOS are not compatible with the Linux container — native addons fail, symlinks break, and the image includes dev dependencies."
+    bad_example: |
+      # ❌ COPY . . copies local node_modules into the image
+      FROM node:20-alpine
+      WORKDIR /app
+      COPY . .           # copies node_modules from macOS host!
+      RUN npm ci         # may use or be confused by the already-copied modules
+      CMD ["node", "dist/index.js"]
+    good_example: |
+      # ✓ Add node_modules to .dockerignore, copy package files first
+      # .dockerignore: node_modules, dist, .env
+      FROM node:20-alpine
+      WORKDIR /app
+      COPY package*.json ./  # package files only — no local node_modules
+      RUN npm ci             # fresh install in the Linux container
+      COPY . .               # source files only (node_modules excluded by .dockerignore)