Imported from UmutcanYilmaz/mopsepeti (AGENTS.md). Install upstream with npx skills add UmutcanYilmaz/mopsepeti. Copyright stays with the author.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Always use pnpm instead of npm.

🛠 Project Stack & Constraints

• Node.js: Enforced >=26.4.0 in package.json.
• Framework: Next.js 16.2.9 App Router (with Standalone build mode output).
• Styling: Tailwind CSS v4 & Framer Motion. Themes are configured directly inside globals.css @theme instead of standard config files.
• ORM: Prisma Client v7 generated at a custom path.
• Auth: NextAuth v5 integrated with Zitadel OIDC (PKCE flow, none auth method).
• Testing: Dual test runner (Node.js native runner + Vitest).

🔒 Security & Code Guardrails

1. CSV Macro Injection Defense:
   • When generating/exporting lead lists to CSV (e.g., in admin-leads.ts), sanitize cell values starting with formula markers (=, +, -, @) by prepending a single quote (').
2. Honeypot Verification:
   • Pre-registration forms must include a hidden user_website honeypot input. Silently drop submissions if this field is populated.
3. Rate Limiting:
   • Critical server actions (e.g. pre-registration submissions in submit-lead.ts) must be throttled using the client IP rate limiter in rate-limit.ts (e.g., maximum of 5 submissions per 10 minutes per IP).
4. Zitadel Email Verification:
   • Access to client panels is gated on Zitadel's real-time verification. When SMTP setups are failed or constrained, Zitadel API email verification fallbacks (zitadelVerifyEmailDirectly via /v2/users/{id}/email and SetEmail endpoint) must be used.
5. Private Content Gating:
   • For blog posts marked PRIVATE/ADMIN, dynamically strip post content/body server-side from both the serialized return payload and translation arrays if the requester is unauthenticated/unauthorized. Never rely solely on CSS/JS layout hidden layers.

💾 Prisma & Database Guidelines

1. Custom Imports Path:
   • CRITICAL: Never import from @prisma/client.
   • Always import from: @/generated/prisma/client/client.
   • For database JSON queries, use Prisma.DbNull instead of JS null.
2. ESM / tsx Seeding:
   • Prisma seeds via tsx under ESM mode. Command: pnpm exec prisma db seed.
3. Pre-push Database Updates:
   • In production Docker and Coolify environments, database schema changes are preceded by running pre-push.mjs (e.g. node prisma/pre-push.mjs) to dynamically migrate enum values (such as converting legacy visibility enums like 'PRIVATE' to 'ADMIN').
4. Mocking Prisma Client:
   • Prisma's dynamic JS Proxy implementation causes unit-testing mocks on prisma.lead.create etc. to fail when using node:test's mock.method. Temporarily replace the function references manually in beforeEach and restore them in afterEach.

🧪 Testing Guidelines

Ensure all tests pass before making pull requests.

1. Node.js Native Test Runner (node:test):
   • Runs fast unit/integration tests with zero external dependencies.
   • Command: node --import tsx --test $(find src -name "*.test.ts" -o -name "*.spec.ts")
2. Vitest Runner:
   • Handles React component tests and modules configured with @/* path mapping aliases.
   • Command: pnpm exec vitest run

🔀 Git & Integration Safety

• PR Conflict Resolution Warning: Do not flatly accept incoming changes during rebase or merge conflict resolutions. Accepting incoming files entirely can discard unique local branch features/tests.
• Always run visual validation and audit diffs against the branch parent using git diff <commit> HEAD -- <filepath> to guarantee that your features, sanitizations, and unit tests have not been dropped.

🤖 Google's Jules Coding Agent Guidelines

Google's Jules coding agent operates under specific guidelines to verify codebase health and maintain diagnostics:

1. Codebase Health & Diagnostics Suite

• Run the full diagnostics suite using the command: pnpm run audit-all.
• This execution automates checks for security vulnerabilities, static/dynamic performance criteria, type-checking, and the full test suite.
• Always ensure that audit_report.md is generated in the workspace root after diagnostic runs.

2. Security Boundaries & Guardrails

• CSV Macro Injection: Verify that cell values in CSV exports starting with =,+,-,@ are prepended with a single quote (').
• Honeypot Verification: Ensure forms contain the hidden user_website field and that submission endpoints silently discard inputs where it is populated.
• Rate Limiting: Critical operations (e.g. lead registration) must utilize checkRateLimit to prevent abuse.
• Private Content Gating: Strip private or administrative content/body server-side in API and rendering payloads before sending them to client components.

3. Performance Standards

• Image Optimization: Avoid raw <img> tags in .tsx files; always favor Next.js <Image> components.
• Static Page Generation: Configure Next.js ISR via revalidate flags (e.g. revalidate = 3600) where applicable.
• RSC vs Client Fetching: Verify client-side components ("use client") do not fetch data directly; data fetching should reside in Server Components.
• GSAP Memory Protection: Wrap GSAP timelines inside gsap.context() to ensure proper garbage collection during navigation.

4. Critical Metadata & Documentation Protection (Mandatory Compliance)

• Do Not Delete or Truncate: LLM agents must never delete, clear, or truncate any of the following project meta-files:
  • .antigravity/work-report.md
  • .antigravity/context.md
  • AGENTS.md
  • CLAUDE.md
• Changelog Chronology: For .antigravity/work-report.md, agents must only append new entries chronologically at the end of the file. History must never be overridden or collapsed.
• Context Preservation: For .antigravity/context.md, AGENTS.md, and CLAUDE.md, updates must only enrich, amend, or clarify context, rules, and commands, preserving the historical guidelines.
• Automated Validation: These rules are programmatically enforced via pnpm run audit-all. Truncating or deleting these files will cause the audit to fail.