@tsfpp/agents 1.2.3 → 1.3.1

package/copilot/copilot-instructions.md

@@ -1,89 +1,166 @@
----
-applyTo: "{**/routes/**,**/handlers/**,**/api/**}/*.ts"
----
-
-# TSF++ API rules
-
-Full standard: `node_modules/@tsfpp/standard/spec/API_CODING_STANDARD.md`
-Boundary API: `node_modules/@tsfpp/boundary/README.md`
-Extends: tsfpp-base.instructions.md (all base rules apply)
-
-## Handler shape
-
-Handlers are thin. The only permitted steps are: parse → call use-case → map response.
+# TSF++ coding standard — v1.1.0
+
+This repository follows the TSF++ coding standard.
+Canonical source: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md` — when this file and the standard conflict, the standard wins.
+
+## Axioms (non-negotiable)
+
+1. Referential transparency is the norm; effects are reified as `Promise<Result<T, E>>`.
+2. Total functions — partiality is typed via `Option<A>` or `Result<T, E>`. Never concealed.
+3. Algebraic data types are the primary modelling language: sum types via tagged discriminated unions, product types via readonly records.
+4. Compiler first, property tests second, documentation third.
+
+## Never
+
+- `class` `this` `new` `instanceof` `namespace` `enum`
+- `interface` without `// DEVIATION(1.4): <reason>`
+- `any` — use `unknown` at I/O boundaries, narrow in scope
+- `as` outside a smart constructor body
+- `!` (non-null assertion)
+- `let` `var`
+- `for` `while` `do..while`
+- `.push` `.pop` `.splice` `.sort` `.reverse` `.fill` `delete` (mutating methods)
+- `throw` in core — return `err(...)` instead
+- `==` `!=` or truthiness checks on non-booleans (`if (str)`, `if (value)`)
+- Optional params `?` — use `Option<T>` or a defaults record
+- `default:` in an exhaustive switch — use `absurd(x)` instead
+- `import from 'ramda'` — use `@tsfpp/prelude`
+- `new Map()` `new Set()` — use `intoMap` / `intoSet` from `@tsfpp/prelude`
+- `if (x === null)` `if (x === undefined)` `x ?? y` — use `fromNullable` / `getOrElse`
+- `try/catch` in core — use `tryCatch` / `tryCatchAsync` from `@tsfpp/prelude`
+
+## Always
+
+- `const` for every binding
+- `readonly` on every record field and `ReadonlyArray<T>` for arrays
+- Explicit return type on every exported function
+- Sum-type dispatch via `switch` ending in `default: return absurd(x)`
+- Errors as data: `Result<T, E>` — never `throw` in core
+- Pipelines via `pipe` from `@tsfpp/prelude`
+- JSDoc on every exported symbol (`@param`, `@returns`, `@law` where applicable)
+- `// DEVIATION(N.M): <reason>` immediately before any necessary rule violation
+
+## Size limits
+
+| Metric | Limit |
+|--------|-------|
+| Function body | ≤ 40 lines (excl. blank lines and comments) |
+| Cyclomatic complexity | ≤ 10 |
+| Nesting depth | ≤ 4 |
+| Positional arity | ≤ 3 — use a readonly record for ≥ 3 |
+
+## Canonical idioms
 
 ```ts
-const createTrackHandler = async (req: Request): Promise<Response> => {
-  const ctx    = extractContext(req)                        // 1. context
-  const body   = CreateTrackSchema.safeParse(await req.json())
-  if (!body.success) return fromZodError(body.error, ctx.traceId)  // 2. validate
-
-  const result = await createTrack(body.data)              // 3. use-case
-  return pipe(result, fold(apiErrorToResponse, createdResponse))    // 4. map
+// Sum type — domain ADT uses `kind`
+type Shape =
+  | { readonly kind: 'circle'; readonly radius: number }
+  | { readonly kind: 'rect';   readonly width: number; readonly height: number }
+
+// Exhaustive match with totality witness
+import { absurd } from '@tsfpp/prelude'
+
+const area = (s: Shape): number => {
+  switch (s.kind) {
+    case 'circle': return Math.PI * s.radius ** 2
+    case 'rect':   return s.width * s.height
+    default:       return absurd(s)
+  }
 }
+
+// Branded type — smart constructor only; `as` only inside the guard body
+import { type Brand, some, none, type Option } from '@tsfpp/prelude'
+
+type UserId = Brand<string, 'UserId'>
+const mkUserId = (raw: string): Option<UserId> =>
+  raw.length > 0
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- DEVIATION(1.6): smart-constructor body
+    ? some(raw as UserId)
+    : none
+
+// Total function via Option
+const head = <A>(xs: ReadonlyArray<A>): Option<A> =>
+  xs.length > 0 ? some(xs[0] as A) : none
+
+// Pipeline
+import { pipe, map, flatMap, tap, tapErr } from '@tsfpp/prelude'
+
+pipe(
+  parseInput(raw),
+  flatMap(validate),
+  tap(v  => log.debug({ v })),
+  tapErr(e => log.warn({ e })),
+)
 ```
 
-## Boundary imports
+## Import discipline
 
-All HTTP primitives come from `@tsfpp/boundary`:
+All ADT constructors, combinators, and utilities come from `@tsfpp/prelude`. Never import from `ramda` directly.
 
 ```ts
 import {
-  extractContext, fromZodError, apiErrorToResponse,
-  okResponse, createdResponse, noContentResponse, acceptedResponse,
-  problemResponse, mkProblem,
-} from '@tsfpp/boundary'
+  some, none, ok, err, unit,
+  isSome, isNone, isOk, isErr,
+  map, flatMap, flatMapAsync, tap, tapErr,
+  mapO, flatMapO, orElse, getOrElse, fromNullable,
+  tryCatch, tryCatchAsync,
+  traverseArray, traverseArrayO, sequenceArrayO,
+  intoMap, assoc, dissoc, lookup, entriesOfMap,
+  intoSet, conj, disj, member,
+  isRecord, getStringField, getNumberField, getTypedField,
+  pipe, flow, absurd,
+  type Option, type Result, type Unit, type Brand,
+} from '@tsfpp/prelude'
 ```
 
-Never construct `new Response(...)` directly in a handler.
+## Prelude-first
 
-## Validation
+Before writing any implementation, check if `@tsfpp/prelude` already provides what you need:
 
-All input validated with Zod at the boundary. Schema lives next to the route:
+| If you need… | Use… |
+|---|---|
+| Nullable → Option | `fromNullable` |
+| Fallible operation | `tryCatch` / `tryCatchAsync` |
+| No-value success | `ok(unit)` — never `ok(undefined)` |
+| Map over array that can fail | `traverseArray` |
+| Key/value store | `intoMap`, `lookup`, `assoc`, `dissoc` |
+| Deduplication / membership | `intoSet`, `conj`, `disj`, `member` |
+| Decode unknown record | `isRecord` + `getStringField` / `getNumberField` / `getTypedField` |
+
+## Code markers
 
 ```ts
-const CreateTrackSchema = z.object({
-  title:    z.string().min(1).max(255),
-  artistId: z.string().uuid(),
-})
+// TODO(author, YYYY-MM-DD[, TICKET]): description
+// FIXME(author, YYYY-MM-DD): description
+// HACK(author, YYYY-MM-DD): description
+// NOTE(author, YYYY-MM-DD): description
+// OPTIMIZE(author, YYYY-MM-DD): description
+// BUG(author, YYYY-MM-DD): description
+// XXX(author, YYYY-MM-DD): description
 ```
 
-Never pass unvalidated `req.body` or `req.json()` into the domain.
+## Generation workflow
 
-## Errors
+1. **Types first** — model the domain as sum and product types before writing any function.
+2. **Make it total** — every function returns `Option`/`Result` if it can fail or be absent.
+3. **Pure vs effectful** — `T` means pure; `Promise<Result<T, E>>` means effectful.
+4. **Test the laws** — fast-check property tests for every pure function.
 
-```ts
-// Yes — Result propagates; mapped once at the boundary
-const result: Result<Track, ApiError> = await createTrack(input)
-return pipe(result, fold(apiErrorToResponse, createdResponse))
+## Editing existing code
 
-// No — throw crosses the boundary untyped
-throw new Error('not found')
-```
+- Never weaken a signature (e.g. do not replace `Option<T>` with `T | undefined`).
+- Preserve `readonly`-ness transitively.
+- Do not introduce forbidden constructs to fix a type error — rethink the types.
+- Deviation: `// DEVIATION(N.M): <one-line justification>` at the violation site.
 
-## Context
+## When a task is ambiguous
 
-```ts
-const { traceId, principalId } = extractContext(req)
-// Never: req.headers.get('x-trace-id') in business logic
-```
+Ask one focused question rather than guessing. Do not invent types, error cases, or effect boundaries.
+
+## Agents and tooling
 
-## Status codes
-
-| Situation | Code | Builder |
-|-----------|------|---------|
-| Read success | 200 | `okResponse` |
-| Created | 201 | `createdResponse` |
-| Accepted (async) | 202 | `acceptedResponse` |
-| No content | 204 | `noContentResponse` |
-| Validation failure | 422 | `fromZodError` |
-| Not found | 404 | `problemResponse(mkProblem(404, ...))` |
-| Conflict | 409 | `problemResponse(mkProblem(409, ...))` |
-| Server error | 500 | `problemResponse(mkProblem(500, ...))` |
-
-## Security
-
-- All routes require authentication unless explicitly marked `// PUBLIC`
-- Never log `principalId`, credentials, or request bodies at `info` level
-- Never reflect user input in error messages without sanitisation
-- Idempotency keys required on mutating operations — use `withIdempotency`
+- TSF++ compliance audit: `.github/agents/tsfpp-audit.agent.md`
+- Guarded implementation: `.github/agents/tsfpp-guarded-coding.agent.md`
+- Refactoring: `.github/agents/tsfpp-refactor-engineer.agent.md`
+- Annotation: `.github/agents/tsfpp-annotate.agent.md`
+- Trunk workflow: `.github/instructions/trunk.instructions.md`

package/copilot/instructions/tsfpp-api.instructions.md

@@ -6,84 +6,149 @@ applyTo: "{**/routes/**,**/handlers/**,**/api/**}/*.ts"
 
 Full standard: `node_modules/@tsfpp/standard/spec/API_CODING_STANDARD.md`
 Boundary API: `node_modules/@tsfpp/boundary/README.md`
-Extends: tsfpp-base.instructions.md (all base rules apply)
+Extends: `tsfpp-base.instructions.md` (all base rules apply)
 
 ## Handler shape
 
-Handlers are thin. The only permitted steps are: parse → call use-case → map response.
+Handlers are thin. The only permitted steps are: **parse → call use-case → map response**.
 
 ```ts
-const createTrackHandler = async (req: Request): Promise<Response> => {
-  const ctx    = extractContext(req)                        // 1. context
-  const body   = CreateTrackSchema.safeParse(await req.json())
-  if (!body.success) return fromZodError(body.error, ctx.traceId)  // 2. validate
+import {
+  extractContext, fromZodError, apiErrorToResponse,
+  createdResponse, okResponse, noContentResponse, acceptedResponse,
+  withIdempotency, withRequestLog,
+} from '@tsfpp/boundary'
+import { isErr, pipe } from '@tsfpp/prelude'
+
+const createTrackHandler: RawHandler = async (req) => {
+  const ctx = extractContext(req, '/v1/tracks')           // 1. context — always first
 
-  const result = await createTrack(body.data)              // 3. use-case
-  return pipe(result, fold(apiErrorToResponse, createdResponse))    // 4. map
+  const raw    = await req.json().catch(() => null)
+  const parsed = CreateTrackSchema.safeParse(raw)
+  if (!parsed.success)                                    // 2. validate
+    return apiErrorToResponse(fromZodError(parsed.error), ctx)
+
+  const result = await createTrack(parsed.data)           // 3. use-case
+  if (isErr(result)) return apiErrorToResponse(result.error, ctx)
+
+  return createdResponse(result.value, `/v1/tracks/${result.value.id}`, {
+    'X-Request-Id': ctx.traceId,
+  })                                                      // 4. respond
 }
 ```
 
 ## Boundary imports
 
-All HTTP primitives come from `@tsfpp/boundary`:
+All HTTP primitives come from `@tsfpp/boundary`. Never construct `new Response()` directly.
 
 ```ts
 import {
-  extractContext, fromZodError, apiErrorToResponse,
-  okResponse, createdResponse, noContentResponse, acceptedResponse,
-  problemResponse, mkProblem,
+  // Context
+  extractContext,
+  // Validation
+  fromZodError, mkValidationError,
+  // Error mapping
+  apiErrorToResponse, apiErrorToProblem,
+  // Response builders
+  okResponse, createdResponse, noContentResponse,
+  acceptedResponse, redirectResponse, jsonResponse, problemResponse, mkProblem,
+  // Pagination
+  mkPaginated, parsePaginationQuery, encodeCursor, decodeCursor,
+  // LRO
+  mkRunningOp, mkSucceededOp, mkFailedOp,
+  // Bulk
+  bulkResponse, mkBulkOkItem, mkBulkErrorItem,
+  // Security
+  baselineSecurityHeaders, corsHeaders, rateLimitHeaders,
+  // Middleware
+  withIdempotency, withRequestLog,
+  // Webhooks
+  signWebhook, verifyWebhook,
+  // Types
+  type RawHandler, type HandlerFactory, type RequestContext,
 } from '@tsfpp/boundary'
 ```
 
-Never construct `new Response(...)` directly in a handler.
-
 ## Validation
 
-All input validated with Zod at the boundary. Schema lives next to the route:
+All input validated with Zod at the boundary via `safeParse` — never `parse` (throws):
 
 ```ts
-const CreateTrackSchema = z.object({
-  title:    z.string().min(1).max(255),
-  artistId: z.string().uuid(),
-})
+const parsed = CreateTrackSchema.safeParse(raw)
+if (!parsed.success) return apiErrorToResponse(fromZodError(parsed.error), ctx)
 ```
 
-Never pass unvalidated `req.body` or `req.json()` into the domain.
+Never pass unvalidated `req.json()` into the domain.
 
-## Errors
+## Error mapping
 
 ```ts
 // Yes — Result propagates; mapped once at the boundary
-const result: Result<Track, ApiError> = await createTrack(input)
-return pipe(result, fold(apiErrorToResponse, createdResponse))
+const result = await createTrack(input)
+if (isErr(result)) return apiErrorToResponse(result.error, ctx)
 
 // No — throw crosses the boundary untyped
 throw new Error('not found')
 ```
 
-## Context
+`dependency` and `internal` ApiError variants contain a `cause` — **log `cause` before calling `apiErrorToResponse`**, it is stripped from the response.
+
+## Middleware composition
+
+Compose via `pipe`, outermost-last. `withRequestLog` must always be outermost:
 
 ```ts
-const { traceId, principalId } = extractContext(req)
-// Never: req.headers.get('x-trace-id') in business logic
+const handler: RawHandler = pipe(
+  createTrackHandler,           // business logic
+  withIdempotency(store),       // replay / in-flight guard
+  withRequestLog(logger, '/v1/tracks'), // outermost — logs every outcome
+)
 ```
 
-## Status codes
+## Pagination
 
-| Situation | Code | Builder |
-|-----------|------|---------|
-| Read success | 200 | `okResponse` |
-| Created | 201 | `createdResponse` |
-| Accepted (async) | 202 | `acceptedResponse` |
-| No content | 204 | `noContentResponse` |
-| Validation failure | 422 | `fromZodError` |
-| Not found | 404 | `problemResponse(mkProblem(404, ...))` |
-| Conflict | 409 | `problemResponse(mkProblem(409, ...))` |
-| Server error | 500 | `problemResponse(mkProblem(500, ...))` |
+```ts
+const pageQuery = parsePaginationQuery(req.url, 100) // Result<PageQuery, ValidationError>
+if (isErr(pageQuery)) return apiErrorToResponse(pageQuery.error, ctx)
+
+const page = mkPaginated(items, nextCursor)           // totalCount omitted unless precomputed
+return okResponse(page)
+```
+
+## Rate limiting
+
+Attach `rateLimitHeaders` to **all** responses on rate-limited endpoints, not only 429s:
+
+```ts
+return okResponse(body, rateLimitHeaders(state))
+```
 
 ## Security
 
+```ts
+// Merge baseline headers into every response
+return okResponse(body, { ...baselineSecurityHeaders, ...rateLimitHeaders(state) })
+
+// CORS — never reflect Origin blindly; allowedOrigins from config only
+return okResponse(body, corsHeaders(allowedOrigins, requestOrigin))
+```
+
 - All routes require authentication unless explicitly marked `// PUBLIC`
-- Never log `principalId`, credentials, or request bodies at `info` level
+- Never log `principalId`, credentials, or full request bodies at `info` level
 - Never reflect user input in error messages without sanitisation
-- Idempotency keys required on mutating operations — use `withIdempotency`
+- Idempotency keys required on state-mutating operations — use `withIdempotency`
+
+## Status codes
+
+| Situation | Code | Builder |
+|---|---|---|
+| Read success | 200 | `okResponse` |
+| Created | 201 | `createdResponse(body, location)` |
+| Accepted (async / LRO) | 202 | `acceptedResponse(operation, pollUrl)` |
+| No content | 204 | `noContentResponse` |
+| Multi-status (bulk) | 207 | `bulkResponse(items)` |
+| Validation failure | 422 | `apiErrorToResponse(fromZodError(e), ctx)` |
+| Not found | 404 | `apiErrorToResponse({ kind: 'not_found', ... }, ctx)` |
+| Conflict | 409 | `apiErrorToResponse({ kind: 'conflict', ... }, ctx)` |
+| Rate limited | 429 | `apiErrorToResponse({ kind: 'rate_limit', ... }, ctx)` |
+| Server error | 500 | `apiErrorToResponse({ kind: 'internal', cause }, ctx)` |

package/copilot/instructions/tsfpp-base.instructions.md

@@ -21,6 +21,9 @@ Full standard: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md`
 - Optional params `?` — use `Option<T>` or a defaults record
 - `default:` in an exhaustive switch — use `absurd(x)` instead
 - `import from 'ramda'` — use `@tsfpp/prelude`
+- `new Map()` `new Set()` — use `intoMap` / `intoSet` from `@tsfpp/prelude`
+- `if (x === null)` `if (x === undefined)` `x ?? y` — use `fromNullable` / `getOrElse`
+- `try/catch` in core — use `tryCatch` / `tryCatchAsync` from `@tsfpp/prelude`
 
 ## Always
 
@@ -46,7 +49,7 @@ Full standard: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md`
 ## ADT patterns
 
 ```ts
-// Sum type
+// Sum type — domain ADTs use `kind`
 type Shape =
   | { readonly kind: 'circle'; readonly radius: number }
   | { readonly kind: 'rect';   readonly width: number; readonly height: number }
@@ -58,21 +61,29 @@ switch (shape.kind) {
   default:       return absurd(shape)
 }
 
-// Branded type
+// Branded type — `as` only inside the smart constructor guard body
 type UserId = Brand<string, 'UserId'>
-const mkUserId = brand<string, 'UserId'>(
-  s => /^[a-z0-9-]+$/.test(s),
-  s => `Invalid UserId: ${s}`,
-)
+const mkUserId = (raw: string): Option<UserId> =>
+  raw.length > 0
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- DEVIATION(1.6): smart-constructor body
+    ? some(raw as UserId)
+    : none
 
 // Total function
 const head = <A>(xs: ReadonlyArray<A>): Option<A> =>
   xs.length > 0 ? some(xs[0] as A) : none
 ```
 
+## Discriminant convention
+
+| ADT origin | Field | Example |
+|---|---|---|
+| `@tsfpp/prelude` (Result, Option) | `_tag` | accessed via guards only — never `x._tag === 'Ok'` |
+| Domain ADTs | `kind` | `{ kind: 'pending'; ... }` |
+
 ## Imports
 
-All ADT constructors (`some`, `none`, `ok`, `err`), combinators (`map`, `flatMap`, `pipe`, `prop`, …), and Ramda re-exports come from `@tsfpp/prelude`. Never import from `ramda` directly.
+All ADT constructors, combinators, and utilities come from `@tsfpp/prelude`. Never import from `ramda` directly.
 
 ## Markers