## 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.