# Enterprise AI Developer Platform OS Blueprint ==================================================================== MODULE 1: AGENT PERMISSION BOUNDARIES & `.cursorrules` / `CLAUDE.md` ==================================================================== - Agent Sandboxing & Execution Perimeter: * Writable Directory Whitelist: `src/`, `tests/`, `prisma/schema.prisma`. * Read-Only System Zones: `.github/workflows/`, `.husky/`, `package.json`, `pnpm-lock.yaml`, `.env*`, `.gitleaks.toml`. * Terminal Command Whitelist: `pnpm test`, `pnpm test:run`, `pnpm tsc --noEmit`, `pnpm lint`, `pnpm prisma validate`. * Banned Destructive Operations: `rm -rf`, `pnpm install <new-package>` (requires human approval), `git push --force`, `pnpm prisma migrate reset`. * Dependency Modification Policy: Autonomous package additions or major version bumps are strictly forbidden without explicit human architect sign-off. - Complete `.cursorrules` Configuration File: ```text You are an elite Staff Platform Engineer operating within a hardened enterprise Next.js 15 codebase (TypeScript 5.5, Prisma ORM, Tailwind CSS v4). AGENT CONSTRAINTS & PERMISSIONS: 1. STRICT BOUNDARY ENFORCEMENT: - You are permitted to modify files ONLY in `src/` and `tests/`. - NEVER attempt to edit `.github/workflows/`, `.husky/`, or `.env*` files. - NEVER install new npm packages autonomously. If a new library is required, provide the rationale and pause for human confirmation. 2. ZERO LAZY CODE: - Never emit comments like "// rest of code goes here", "// TODO", or placeholder stubs. - Output 100% complete, compilable, and type-checked implementations. 3. NEXT.JS 15 & REACT 19 ARCHITECTURE: - Default to React Server Components (RSC). Use `'use client'` only when client-side state hooks or browser event listeners are strictly necessary. - Asynchronous runtime APIs: Always `await cookies()`, `await headers()`, and `await params`. Synchronous access is forbidden. - Data mutations must reside exclusively in isolated Server Actions (`src/actions/`) protected by Zod schemas. 4. ARCHITECTURAL ISOLATION: - UI Components (`src/components/`) MUST NEVER import `@/lib/db` or `@prisma/client` directly. All database access must flow through `src/services/`. ``` - Complete `CLAUDE.md` CLI Agent Directive File: ```markdown # CLAUDE.md - Enterprise Platform Directives ## Build & Verification Commands - Development: `pnpm dev` - Type Check: `pnpm tsc --noEmit` - Linting: `pnpm eslint src/ --max-warnings 0` - Architectural Verification: `pnpm depcruise src --config .dependency-cruiser.js` - Secret Scan: `gitleaks detect --no-git --source . -c .gitleaks.toml` - SAST Security Scan: `semgrep scan --config .semgrep/custom-rules.yml src/` - Unit & Integration Tests: `pnpm vitest run --coverage` ## Code Style Guidelines - Strict Typing: `any` is banned. Use `unknown` with Zod type narrowing. - Error Handling: Server Actions must return standard discriminated unions: `{ success: true; data: T } | { success: false; error: string }`. - Immutability: Treat all input arguments as immutable. Do not mutate parameters in place. ## Refactoring Protocol - When altering domain models, update sequentially: 1. `prisma/schema.prisma` -> 2. `src/types/` -> 3. `src/services/` -> 4. `src/actions/` -> 5. `tests/`. module.exports = { forbidden: [ { name: "no-direct-db-access-from-ui", comment: "UI components must not directly import the database client.", severity: "error", from: { path: "^src/components" }, to: { path: "^src/lib/db" } }, { name: "no-client-component-importing-server-actions", comment: "Client-side utilities must not import server-side infrastructure.", severity: "error", from: { path: "^src/lib/utils" }, to: { path: "^src/actions" } }, { name: "no-circular-dependencies", comment: "Circular dependencies are strictly forbidden across all modules.", severity: "error", from: {}, to: { circular: true } } ], options: { doNotFollow: { path: "node_modules" }, tsConfig: { fileName: "tsconfig.json" } } }; [extend] useDefault = true [allowlist] description = "Global allowlisted paths" paths = [ '''pnpm-lock\.yaml''', '''tests/fixtures/.*''' ] [[rules]] id = "custom-jwt-secret" description = "Hardcoded JWT Secret detected" regex = '''(?i)(jwt[_-]?secret|jwt[_-]?key)\s*[:=]\s*['"][a-zA-Z0-9_\-+=]{16,}['"]''' tags = ["secret", "jwt"] [[rules]] id = "custom-database-connection-string" description = "Hardcoded PostgreSQL Connection String detected" regex = '''postgresql:\/\/[a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+@[a-zA-Z0-9_.-]+:[0-9]+\/[a-zA-Z0-9_-]+''' tags = ["secret", "database"] rules: - id: no-raw-sql-concatenation patterns: - pattern-either: - pattern: db.$queryRawUnsafe(`...${...}...`) - pattern: db.$executeRawUnsafe(`...${...}...`) message: "Detected raw SQL query concatenation in Prisma. Use parameterized queries via $queryRaw to prevent SQL injection." languages: [typescript, javascript] severity: ERROR - id: no-dangerously-set-inner-html-without-sanitizer patterns: - pattern: <$TAG dangerouslySetInnerHTML={{ __html:$VAL }} /> - pattern-not: <$TAG dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize($VAL) }} /> message: "Unsanitized dangerouslySetInnerHTML detected. All HTML injections must be sanitized with DOMPurify to prevent XSS." languages: [typescript, javascript] severity: ERROR # Step 1: Validate lockfile integrity in CI pnpm install --frozen-lockfile # Step 2: Audit dependencies for known CVEs pnpm audit --audit-level=high # Step 3: Generate CycloneDX SBOM (Software Bill of Materials) pnpm dlx @cyclonedx/cyclonedx-npm --output-format JSON --output-file ./bom.json #!/usr/bin/env bash set -e echo "=== EXECUTING PRE-COMMIT GATES ===" # 1. Scan staged changes for secrets gitleaks protect --staged --verbose -c .gitleaks.toml # 2. Run lint-staged for format and type verification pnpm lint-staged # 3. Verify architectural boundaries pnpm depcruise src --config .dependency-cruiser.js echo "PRE-COMMIT VALIDATION PASSED: COMMITTING." { "*.{ts,tsx}": [ "eslint --fix --max-warnings 0", "prettier --write" ], "*.json": [ "prettier --write" ] } name: Enterprise Production Quality & Security Gate on: push: branches: [main, develop] pull_request: branches: [main, develop] permissions: contents: read security-events: write jobs: devsecops-pipeline: runs-on: ubuntu-latest timeout-minutes: 15 steps: - name: Checkout Repository uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Node.js & PNPM uses: pnpm/action-setup@v4 with: version: 9.15.0 - uses: actions/setup-node@v4 with: node-version: 22 cache: 'pnpm' - name: Install Dependencies (Frozen Lockfile) run: pnpm install --frozen-lockfile - name: Gate 1: Gitleaks Secret Scanning uses: gitleaks/gitleaks-action@v2 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITLEAKS_CONFIG: .gitleaks.toml - name: Gate 2: Static Type Check run: pnpm tsc --noEmit - name: Gate 3: ESLint Strict Verification run: pnpm eslint src/ --max-warnings 0 - name: Gate 4: Semgrep SAST Analysis run: pnpm dlx semgrep scan --config .semgrep/custom-rules.yml --error src/ - name: Gate 5: Architectural Boundary Test run: pnpm dlx depcruise src --config .dependency-cruiser.js - name: Gate 6: Generate CycloneDX SBOM run: pnpm dlx @cyclonedx/cyclonedx-npm --output-format JSON --output-file ./bom.json - name: Gate 7: Automated Sandbox Tests run: pnpm vitest run --coverage --reporter=verbose import { z } from "zod"; export const CreateOrganizationSchema = z.object({ name: z.string().trim().min(2, "Name must be at least 2 characters").max(50), billingEmail: z.string().trim().email("Invalid corporate email format"), plan: z.enum(["STARTER", "PROFESSIONAL", "ENTERPRISE"]).default("STARTER"), }); export type CreateOrganizationInput = z.infer<typeof CreateOrganizationSchema>; export type OrganizationActionResponse = | { success: true; data: { id: string; name: string; billingEmail: string; createdAt: Date } } | { success: false; error: string }; model Organization { id String @id @default(cuid()) name String billingEmail String @unique plan String @default("STARTER") createdAt DateTime @default(now()) updatedAt DateTime @updatedAt @@index([billingEmail]) } import { db } from "@/lib/db"; import { CreateOrganizationInput } from "@/types/organization"; export async function registerOrganization(input: CreateOrganizationInput) { const existingOrg = await db.organization.findUnique({ where: { billingEmail: input.billingEmail }, select: { id: true }, }); if (existingOrg) { throw new Error("BILLING_EMAIL_ALREADY_EXISTS"); } return db.organization.create({ data: { name: input.name, billingEmail: input.billingEmail, plan: input.plan, }, select: { id: true, name: true, billingEmail: true, createdAt: true, }, }); } "use server"; import { CreateOrganizationSchema, OrganizationActionResponse } from "@/types/organization"; import { registerOrganization } from "@/services/organization"; export async function createOrganizationAction( rawInput: unknown ): Promise<OrganizationActionResponse> { try { const validation = CreateOrganizationSchema.safeParse(rawInput); if (!validation.success) { return { success: false, error: validation.error.errors[0].message, }; } const newOrg = await registerOrganization(validation.data); return { success: true, data: newOrg, }; } catch (err: unknown) { if (err instanceof Error && err.message === "BILLING_EMAIL_ALREADY_EXISTS") { return { success: false, error: "An organization with this billing email already exists.", }; } console.error("[ORGANIZATION_CREATION_FAILURE]:", err); return { success: false, error: "Internal service error occurred while processing registration.", }; } } import { describe, it, expect, vi, beforeEach } from "vitest"; import { registerOrganization } from "@/services/organization"; import { db } from "@/lib/db"; vi.mock("@/lib/db", () => ({ db: { organization: { findUnique: vi.fn(), create: vi.fn(), }, }, })); describe("Organization Domain Service", () => { beforeEach(() => { vi.clearAllMocks(); }); it("throws structured domain error when email exists", async () => { vi.mocked(db.organization.findUnique).mockResolvedValue({ id: "org_exists" } as any); await expect( registerOrganization({ name: "Stark Industries", billingEmail: "tony@stark.com", plan: "ENTERPRISE", }) ).rejects.toThrow("BILLING_EMAIL_ALREADY_EXISTS"); expect(db.organization.create).not.toHaveBeenCalled(); }); it("successfully persists organization when valid", async () => { const mockResult = { id: "org_abc123", name: "Wayne Enterprises", billingEmail: "bruce@wayne.com", createdAt: new Date("2026-03-01T12:00:00Z"), }; vi.mocked(db.organization.findUnique).mockResolvedValue(null); vi.mocked(db.organization.create).mockResolvedValue(mockResult as any); const result = await registerOrganization({ name: "Wayne Enterprises", billingEmail: "bruce@wayne.com", plan: "STARTER", }); expect(result).toEqual(mockResult); expect(db.organization.create).toHaveBeenCalledWith({ data: { name: "Wayne Enterprises", billingEmail: "bruce@wayne.com", plan: "STARTER", }, select: { id: true, name: true, billingEmail: true, createdAt: true, }, }); }); });