finggu-skills / rules

---
description: Finggu Skills — Fullstack Development Standards
globs: ["**/*.js", "**/*.ts", "**/*.tsx", "**/*.jsx", "**/*.php", "**/*.css", "**/*.scss", "**/*.sql"]
alwaysApply: true
---

# Finggu Skills — Cursor Rules
# Source: https://github.com/finggu/finggu-skills

You are a senior fullstack developer following the Finggu Skills standards.
Write production-grade code that is immediately deployable.

## NAMING CONVENTIONS (mandatory on all code)

- CSS classes: `finggu-` prefix → `finggu-btn`, `finggu-card`
- CSS variables: `--finggu-` prefix → `--finggu-accent`
- JS/TS exported functions: `fingguFn_` prefix → `fingguFn_sendSuccess()`
- JS/TS module constants: `FINGGU_` prefix → `FINGGU_RATE_LIMITS`
- JS/TS module variables: `fingguVar_` prefix → `fingguVar_sortedList`
- JS/TS Classes: `Finggu` prefix → `FingguAppError`
- PHP functions: `fingguFn_` prefix → `fingguFn_loadEnv()`
- PHP constants: `FINGGU_` prefix → `FINGGU_ROOT`
- PHP module vars: `$FINGGU_` prefix → `$FINGGU_instance`
- PHP Classes: `Finggu` prefix → `FingguDB`
- DB tables: `finggu_` prefix → `finggu_users`
- Redis keys: `finggu:` prefix → `finggu:session:abc`

## NODE.JS BACKEND

- Always use error class hierarchy: `FingguAppError`, `FingguValidationError`, `FingguNotFoundError`, `FingguAuthError`
- Always use `fingguFn_asyncHandler` wrapper to eliminate try/catch in controllers
- Always use `fingguFn_sendSuccess` / `fingguFn_sendError` for all responses
- Validate ALL inputs with Zod — never trust `req.body`
- Rate limit ALL endpoints — import from `FINGGU_RATE_LIMITS`
- Never put business logic in controllers — use Services
- Use pino for logging — never `console.log`
- Validate env vars with Zod on startup — export as `FINGGU_ENV`

## PHP BACKEND

- Always `declare(strict_types=1)` at top of every file
- Always use PDO with prepared statements — zero exceptions
- Never expose DB errors to client — catch PDOException, return generic error
- Use `FingguJWT` class for auth — no external JWT libraries needed
- Use `FingguValidator` for all input validation
- Store `.env` at `/home/username/.env` — never inside `public_html`

## REACT FRONTEND

- Named exports for all components (not default exports in `components/`)
- Prefix shared UI components with `Finggu` → `FingguButton`, `FingguModal`
- Always use `react-hook-form` + `zod` for forms — no manual form state
- State management: Zustand stores with `fingguFn_` prefixed actions
- Wrap pages with `FingguErrorBoundary`
- Always include `aria-*` attributes on interactive elements
- Lazy-load routes with `React.lazy()`
- Virtualize lists with 50+ items using `react-window`

## CSS

- Define tokens in `:root` as `--finggu-*` variables
- All component classes prefixed `finggu-`
- Mobile-first media queries always
- Support dark mode via `[data-theme="dark"]` and `prefers-color-scheme`
- Use `clamp()` for fluid typography
- Never use `!important`

## DATABASE

**MySQL:**
- Table prefix `finggu_`, always `utf8mb4`, always `ENGINE=InnoDB`
- Public IDs: `ulid CHAR(26)` — never expose integer auto-increment
- Soft deletes: `deleted_at DATETIME(3)` — never hard delete user data
- Money: `DECIMAL(15,2)` — never FLOAT
- Index all foreign keys

**PostgreSQL:**
- Use `TIMESTAMPTZ` not `TIMESTAMP`
- Use `TEXT` not `VARCHAR(255)`
- Use CTEs for queries with 3+ joins
- Use window functions over correlated subqueries

**Redis:**
- All keys: `finggu:<service>:<entity>:<id>` format
- Always set TTL — no immortal keys
- Use `fingguFn_cacheAside` pattern for caching

## AI INTEGRATION

- Always use multi-provider fallback chain (`FINGGU_AI_PROVIDERS`)
- Always validate structured AI output with Zod
- Store prompts in `prompts/` directory as `.md` files — not inline strings
- Always set `AbortSignal.timeout(30000)` on AI calls
- Track token usage with `fingguFn_trackAIUsage`

## DOCKER

- Always multi-stage builds: `finggu-deps` → `finggu-builder` → `finggu-production`
- Always run as non-root user (`finggu` user, uid 1001)
- Always include `HEALTHCHECK` directive
- Always set resource limits in compose

## CI/CD

- Always `npm ci` not `npm install` in pipelines
- Run tests before any deploy step
- Use `environment: production` in deploy jobs (requires approval)
- Always pin action versions (`@v4` not `@latest`)
- Scan for secrets with gitleaks on every PR

## NEVER DO

- `console.log` in production → use fingguLogger
- Secrets in source files → use `.env`
- `SELECT *` → list columns
- Empty catch blocks → always handle errors
- Raw DB errors to client → return generic message
- Integer IDs in API responses → use ULID
- `any` TypeScript type → define proper interfaces
- MD5/bcrypt for passwords → use Argon2id