The Open Source DocuSign Alternative.
TypeScript digital-signaturedocument-signingdocusign-alternativee-signatureesignesignaturenext-authnextjsopen-sourcepades-standardpdfpdf-signpdf-signaturepostgresqlprismaself-hostedsigningtypescript
chore: update AGENTS.md (#3471)
Lucas Smith1971ddd2472b
diff --git a/AGENTS.md b/AGENTS.mdindex 43915ef56..ce8cf551d 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -6,12 +6,14 @@- `npm run lint` - Lint all packages- `npm run lint:fix` - Auto-fix linting issues- `npm run test:e2e` - Run E2E tests with Playwright-- `npm run test:dev -w @documenso/app-tests` - Run single E2E test in dev mode+- `CI=true npm run test:dev -w @documenso/app-tests -- e2e/path/to/file.spec.ts` - Run a single E2E test against a running dev server- `npm run test-ui:dev -w @documenso/app-tests` - Run E2E tests with UI- `npm run format` - Format code with Biome-- `npm run dev` - Start development server for Remix app+- `npm run dev` - Start development server for the React Router app (`apps/remix`)-**Important:** Do not run `npm run build` to verify changes unless explicitly asked. Builds take a long time (~2 minutes). Use `npx tsc --noEmit` for type checking specific packages if needed.+**Important:** Do not run `npm run build` to verify changes unless explicitly asked. Builds take a long time (~2 minutes). Use `npm run typecheck -w @documenso/remix` for the app (it runs `react-router typegen` first) or `npx tsc --noEmit` inside other packages.++**Important:** Always set `CI=true` when running Playwright. Without it the browser runs headfully.## Code Style Guidelines@@ -21,7 +23,6 @@- Use descriptive variable names with auxiliary verbs (isLoading, hasError)- Directory names: lowercase with dashes (auth-wizard)- Use named exports for components-- Never use 'use client' directive- Never use 1-line if statements- Structure files: exported component, subcomponents, helpers, static content, types@@ -50,10 +51,50 @@- "create" routes request schema should have the ID and data in the top level- "update" routes request schema should have the ID in the top level and the data in a nested "data" object-## Translations & Remix+## Translations & React Router- Use `<Trans>string</Trans>` for JSX translations from `@lingui/react/macro`- Use `t\`string\`` macro for TypeScript translations- Use `(params: Route.Params)` and `(loaderData: Route.LoaderData)` for routes- Directly return data from loaders, don't use `json()`- Use `superLoaderJson` when sending complex data through loaders such as dates or prisma decimals++## Testing++- Write few tests, each high value. One test per behaviour, not one per line of code+- Cover the happy path and the adversarial path: wrong user, wrong team, expired token, missing permission, malformed input+- Never mock. If a test would need a mock, write a Playwright E2E test in `packages/app-tests` against the real database and server instead+- Vitest (`packages/lib`, `packages/signing`) is only for pure functions with no I/O+- Every assertion must be able to fail. Never write `expect(true).toBe(true)`, assert on a value you just hard-coded, or assert only that a function "was called"+- A test that only confirms the code runs without throwing is not a test; delete it+- Do not add tests for trivial code (getters, pass-through wrappers, type-only changes)++## Comments++- Default to no comment. Clear naming and small functions should make the code readable on its own+- A comment must explain something the code cannot: the why, a constraint, a non-obvious consequence, a trap for the next person+- Never narrate what the next line does (`// loop over the users`, `// return the result`)+- Never leave section-header comments, TODO notes for work you are doing now, or commented-out code+- JSDoc on exported functions only when the signature alone is not enough++Good comment, from `packages/lib/server-only/rate-limit/rate-limits.ts`:++```ts+// IP only: the nonce must never be a rate limit key (it would be persisted in plaintext).+// The client polls every 2s, so this allows ~40 concurrent flows behind one IP.+export const embedAuthRedeemRateLimit = createRateLimit({+ action: 'auth.embed-redeem',+ max: 1200,+ window: '1m',+});+```++It states a security constraint and the arithmetic behind a magic number. Neither is recoverable from the code.++## Communication++- Lead with the answer or the action. No preamble ("I'll now...", "Great question"), no closing pleasantries+- Keep responses short. Say what changed, where, and what to do next. Skip recaps of work the reader just watched happen+- Number multi-step instructions; one bounded action per step+- Finish the task at hand before raising a tangent. Raise it once, at the end, as a separate question+- For errors, state cause and fix plainly. No "uh oh", no hedging that carries no information