.cursorrules

## Protect.js Cursor Rules

These rules guide agents when creating or updating example apps under `examples/*` in this repository.

### Example App Prompt (for agents)

- **Goals**
  - Show end-to-end usage of Protect.js with clear, minimal code.
  - Demonstrate schema, encrypt/decrypt, and (when relevant) searchable encryption on PostgreSQL.

- **Hard guardrails (do not violate)**
  - Do not log plaintext at any time.
  - Preserve the Result contract: operations return `{ data }` or `{ failure }` with stable error `type` strings.
  - Do not change EQL payload shapes or keys (e.g., `c`).
  - `@cipherstash/protect-ffi` is a native Node-API module and must be externalized by bundlers (loaded via runtime `require`).
  - Keep both ESM and CJS exports working; do not break `require`.

- **Prerequisites and workflow**
  - Use Node.js >= 22 and pnpm 9.x.
  - Install/build/test:
    - `pnpm install`
    - `pnpm --filter <example> dev|build|test`
  - Environment variables for examples/tests that talk to CipherStash:
    - `CS_WORKSPACE_CRN`, `CS_CLIENT_ID`, `CS_CLIENT_KEY`, `CS_CLIENT_ACCESS_KEY`
    - Optional for identity-aware encryption: `USER_JWT`, `USER_2_JWT`

- **Docs to reference**
  - `docs/how-to/nextjs-external-packages.md`
  - `docs/how-to/sst-external-packages.md`
  - `docs/how-to/npm-lockfile-v3.md`
  - `docs/reference/schema.md`
  - `docs/concepts/searchable-encryption.md`

- **Deliverables checklist for a new example**
  - A `protect.ts` (or equivalent) that initializes `protect({ schemas })` using `csTable`/`csColumn`.
  - If targeting Postgres searchable encryption, include `.freeTextSearch().equality().orderAndRange()` on appropriate columns.
  - A minimal script or route/handler that encrypts and decrypts at least one value.
  - A README covering:
    - Setup (env vars, install, run commands)
    - Notes on native module externalization if the framework builds/bundles (e.g., Next.js, SST)
    - How to run tests (if included)
  - Optional: demonstrate identity-aware encryption via `LockContext` and chaining `.withLockContext()` for both encrypt and decrypt.

- **Quality bar**
  - Prefer bulk operations to demonstrate performance where appropriate.
  - Keep examples small, idiomatic, and runnable as-is with documented env vars.
  - Never leak secrets in code or logs; avoid any plaintext logging.