@tsfpp/agents 1.2.3 → 1.3.0

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

@@ -12,23 +12,33 @@ Recipes: `node_modules/@tsfpp/prelude/RECIPES.md`
 ```ts
 import {
   // ADT constructors
-  some, none, ok, err,
+  some, none, ok, err, unit,
   // Type guards
   isSome, isNone, isOk, isErr,
   // Option combinators
-  mapO, flatMapO, orElse, getOrElse, fromNullable,
+  mapO, flatMapO, orElse, getOrElse, fromNullable, toNullable,
   // Result combinators
-  map, flatMap, flatMapAsync, mapErr, tap, tapErr,
+  map, flatMap, flatMapAsync, tap, tapErr,
   // Async adapters
   tryCatch, tryCatchAsync,
   // Traversal
   traverseArray, traverseArrayO, sequenceArrayO,
+  // Unknown decoding
+  isRecord, fromUnknownString, fromUnknownArray, fromUnknownArrayOf, fromNonEmptyString,
+  getStringField, getNumberField, getBooleanField, getTypedField,
+  // ReadonlyMap
+  intoMap, entriesOfMap, assoc, dissoc, lookup,
+  // ReadonlySet
+  intoSet, conj, disj, member,
+  // List
+  fromArray, toArray, cons, nil, isCons, isNil,
   // Pipe
   pipe, flow, comp, complement,
   // Utilities
-  absurd, unit,
+  absurd, unique,
   // Types
   type Option, type Result, type Unit, type Brand,
+  type UnknownRecord,
 } from '@tsfpp/prelude'
 ```
 
@@ -37,7 +47,6 @@ Never `import from 'ramda'`.
 ## Option\<A\>
 
 ```ts
-// Construct
 const a: Option<number> = some(42)
 const b: Option<number> = none
 
@@ -48,17 +57,16 @@ if (isNone(opt)) return ...  // early exit
 // Transform
 pipe(opt, mapO(n => n + 1))
 pipe(opt, flatMapO(n => n > 0 ? some(n) : none))
-pipe(opt, getOrElse(() => 0))
-pipe(opt, orElse(() => some(defaultValue)))
+pipe(opt, getOrElse(() => 0))          // collapse to value
+pipe(opt, orElse(() => some(fallback))) // keep Option context
 
-// Lift from nullable
+// Lift from nullable — never use if (x === null) directly
 const opt = fromNullable(maybeNull)  // null | undefined → Option<T>
 ```
 
 ## Result\<T, E\>
 
 ```ts
-// Construct
 const r: Result<number, string> = ok(42)
 const e: Result<number, string> = err('oops')
 
@@ -69,73 +77,113 @@ if (isErr(r)) r.error   // E
 // Transform
 pipe(r, map(v => v + 1))
 pipe(r, flatMap(v => v > 0 ? ok(v) : err('non-positive')))
-pipe(r, mapErr(e => `Wrapped: ${e}`))
 
-// Side effects without breaking the chain
-pipe(r, tap(v  => log.debug({ v })))
-pipe(r, tapErr(e => log.warn({ e })))
-
-// Async adapter — wraps throwing code
-const result = await tryCatchAsync(
-  () => db.findById(id),
-  e  => mkDbError(e),
+// Side effects — never break the pipe chain for logging
+pipe(r,
+  tap(v  => log.debug({ v })),
+  tapErr(e => log.warn({ e })),
 )
 
-// Sync adapter
+// Wrapping throwing code — never use raw try/catch in core
 const result = tryCatch(
   () => JSON.parse(raw),
-  e  => `parse error: ${e}`,
+  e  => `parse error: ${String(e)}`,
+)
+const result = await tryCatchAsync(
+  () => db.findById(id),
+  e  => mkDbError(e),
 )
 ```
 
-## pipe
+## Result\<Unit, E\> for no-value success
 
 ```ts
-const result = pipe(
-  input,
-  mapO(transform),
-  flatMapO(validate),
-  getOrElse(() => fallback),
-)
+// Never Result<void, E>
+const save = (): Result<Unit, DbError> => ok(unit)
 ```
 
-## Unit
+## pipe vs flow
 
 ```ts
-// Success with no meaningful value — use ok(unit), not ok(undefined)
-const save = (): Result<Unit, DbError> => ok(unit)
+// pipe — value at hand
+const result = pipe(input, mapO(transform), getOrElse(() => fallback))
+
+// flow — reusable pipeline, returns a function
+const process = flow(mapO(transform), getOrElse(() => fallback))
+const result  = process(input)
 ```
 
-## absurd
+## absurd — exhaustiveness witness
 
 ```ts
-// Exhaustiveness witness — type error if a union variant is unhandled
-default: return absurd(x)
+switch (result._tag) {
+  case 'Ok':  return result.value
+  case 'Err': return result.error
+  default:    return absurd(result)
+}
 ```
 
-## Brand
+## Unknown record decoding
 
 ```ts
-type TrackId = Brand<string, 'TrackId'>
+import { isRecord, getStringField, getNumberField, getTypedField } from '@tsfpp/prelude'
+
+const decode = (raw: unknown): Result<Foo, string> => {
+  if (!isRecord(raw)) return err('not an object')
+  const name = getStringField(raw, 'name')        // Option<string> — rejects empty/whitespace
+  const age  = getNumberField(raw, 'age')         // Option<number> — rejects NaN/Infinity
+  const id   = getTypedField(raw, 'id', isFooId)  // Option<FooId> — custom guard
+  return isSome(name) && isSome(age) && isSome(id)
+    ? ok({ name: name.value, age: age.value, id: id.value })
+    : err('missing or invalid fields')
+}
+```
 
-const mkTrackId = brand<string, 'TrackId'>(
-  s => s.length > 0,
-  s => `Invalid TrackId: "${s}"`,
-)
+## Array traversal
+
+```ts
+// Fallible map — short-circuits on first Err
+const all = traverseArray(parseFoo)(rawItems) // Result<ReadonlyArray<Foo>, E>
+// Never: rawItems.map(parseFoo) — produces ReadonlyArray<Result<Foo,E>>
+
+// Option traversal — None if any element is None
+traverseArrayO(fromNullable)([1, 2, 3])    // Some([1, 2, 3])
+traverseArrayO(fromNullable)([1, null, 3]) // None
+
+// Already have ReadonlyArray<Option<A>>?
+sequenceArrayO([some(1), some(2)]) // Some([1, 2])
+sequenceArrayO([some(1), none])    // None
+
+// Guard typed arrays from unknown
+const strings = fromUnknownArrayOf(
+  (v): v is string => typeof v === 'string'
+)(raw) // Option<ReadonlyArray<string>>
 ```
 
-## Traversal
+## ReadonlyMap
 
 ```ts
-// ReadonlyArray<A> → (A → Result<B, E>) → Result<ReadonlyArray<B>, E>
-const results = traverseArray(validate)(items)
+// Never new Map()
+const m  = intoMap([['a', 1], ['b', 2]])  // ReadonlyMap<string, number>
+const v  = pipe(m, lookup('a'))           // Some(1)
+const m2 = pipe(m, assoc('c', 3))         // insert / replace
+const m3 = pipe(m2, dissoc('a'))          // remove
+const es = entriesOfMap(m)                // ReadonlyArray<readonly [string, number]>
+```
 
-// ReadonlyArray<A> → (A → Option<B>) → Option<ReadonlyArray<B>>
-const options = traverseArrayO(lookup)(items)
+## ReadonlySet
+
+```ts
+// Never new Set()
+const s   = intoSet([1, 2, 2, 3])  // ReadonlySet<number> — {1, 2, 3}
+const s2  = pipe(s, conj(4))       // add
+const s3  = pipe(s2, disj(2))      // remove (no-op when absent)
+const has = pipe(s, member(1))     // true
 ```
 
 ## Discriminant convention
 
-- Prelude ADTs use `_tag` internally — **never access it directly**
-- Use exported guards: `isSome`, `isNone`, `isOk`, `isErr`
-- Domain ADTs use `kind` as discriminant
+| ADT origin | Field | Access |
+|---|---|---|
+| `@tsfpp/prelude` (Result, Option) | `_tag` | **via guards only** — never `x._tag === 'Ok'` |
+| Domain ADTs | `kind` | `switch (x.kind)` with `absurd` |

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

@@ -5,83 +5,195 @@ applyTo: "**/*.tsx"
 # TSF++ React rules
 
 Full standard: `node_modules/@tsfpp/standard/spec/REACT_CODING_STANDARD.md`
-Extends: tsfpp-base.instructions.md (all base rules apply to `.tsx` too)
+Extends: `tsfpp-base.instructions.md` (all base rules apply to `.tsx` too)
 
 ## Component shape
 
 ```ts
-// Props: readonly record, no optional fields — use Option<T>
+// Props: type alias, Props suffix, all fields readonly, no optional fields
 type TrackCardProps = {
-  readonly track: Track
+  readonly track:    Track
   readonly onSelect: Option<(id: TrackId) => void>
 }
 
-// Component: pure function, explicit return type
-const TrackCard = ({ track, onSelect }: TrackCardProps): React.ReactElement => { ... }
+// Component: arrow const, explicit return type
+const TrackCard = ({ track, onSelect }: TrackCardProps): React.ReactElement => (
+  <article className="rounded-lg border p-4">
+    <h2>{track.title}</h2>
+  </article>
+)
 ```
 
-## State
+One public exported component per file. `.tsx` only when the file contains JSX.
 
-Model state as a discriminated union — never boolean soup:
+## State elimination ladder
+
+Exhaust top-to-bottom before introducing state:
+
+1. Derivable from props? → compute during render
+2. Derivable from existing state? → compute during render or `useMemo` if expensive
+3. Belongs in URL? → router search/path params
+4. Server data? → TanStack Query
+5. Form state? → React Hook Form
+6. Ephemeral UI state, one component? → `useState` / `useReducer`
+7. Shared between siblings? → lift to nearest common ancestor
+8. Shared across distant subtrees, low-frequency? → Context
+9. Shared across distant subtrees, high-frequency? → Zustand / Jotai
+
+Model multi-field or state-machine state with `useReducer` over multiple `useState`:
 
 ```ts
 // Yes
-type LoadState =
+type EditorState =
   | { readonly kind: 'idle' }
-  | { readonly kind: 'loading' }
-  | { readonly kind: 'success'; readonly data: ReadonlyArray<Track> }
-  | { readonly kind: 'error';   readonly message: string }
+  | { readonly kind: 'saving' }
+  | { readonly kind: 'saved';  readonly at: Date }
+  | { readonly kind: 'error';  readonly message: string }
 
 // No
 const [isLoading, setIsLoading] = useState(false)
-const [hasError, setHasError] = useState(false)
-const [data, setData] = useState(null)
+const [hasError,  setHasError]  = useState(false)
+```
+
+## Effect discipline
+
+`useEffect` is reserved exclusively for synchronising with systems **outside React**: subscriptions, browser APIs, imperative third-party libraries.
+
+```ts
+// Yes — external subscription with cleanup
+useEffect(() => {
+  // NOTE(author, date): Syncing to ResizeObserver — no React equivalent
+  const observer = new ResizeObserver(onResize)
+  observer.observe(ref.current)
+  return () => observer.disconnect()
+}, [onResize])
+
+// No — use TanStack Query
+useEffect(() => { fetch('/api/tracks').then(setTracks) }, [])
+
+// No — use event handler
+useEffect(() => { if (submitted) navigate('/done') }, [submitted])
+
+// No — compute during render
+useEffect(() => { setFullName(`${first} ${last}`) }, [first, last])
 ```
 
-## Data fetching
+Never disable `react-hooks/exhaustive-deps`. Every subscribing effect returns a cleanup.
 
-Use TanStack Query. Never `useEffect` for fetching:
+## Data fetching — TanStack Query
 
 ```ts
 // Yes
-const { data, isPending, isError } = useQuery({ queryKey: ['tracks'], queryFn: fetchTracks })
+const { data, isPending, isError } = useQuery({
+  queryKey: trackKeys.byId(id),
+  queryFn:  () => fetchTrack(id),
+})
+
+// Query key factory — typed, never inline string arrays
+const trackKeys = {
+  all:  ['tracks'] as const,
+  byId: (id: TrackId) => [...trackKeys.all, id] as const,
+}
+```
 
-// No
-useEffect(() => { fetch('/api/tracks').then(...) }, [])
+## Forms — React Hook Form + Zod
+
+```ts
+const schema = z.object({ title: z.string().min(1), artistId: z.string().uuid() })
+type FormData = z.infer<typeof schema>
+
+const form = useForm<FormData>({ resolver: zodResolver(schema) })
+
+// Submit returns Result<T, E> — never throw
+const onSubmit = async (data: FormData): Promise<Result<Track, ApiError>> => { ... }
 ```
 
-## useEffect
+## Routing — TanStack Router
 
-Allowed only for genuine external synchronisation (DOM events, third-party library lifecycle, WebSocket). Must include a comment explaining why `useEffect` is the only option:
+```ts
+// Yes — typed navigate
+navigate({ to: '/tracks/$id', params: { id } })
+
+// No — hand-built URL string
+navigate(`/tracks/${id}`)
+```
+
+Search params validated by Zod at the route definition.
+
+## Global state — Zustand / Jotai
 
 ```ts
-useEffect(() => {
-  // NOTE(author, date): Syncing to external ResizeObserver — no React equivalent
-  const observer = new ResizeObserver(...)
-  return () => observer.disconnect()
-}, [ref])
+// Yes — narrow selection
+const title = useTrackStore((s) => s.track.title)
+
+// No — whole-store selection
+const store = useTrackStore((s) => s)
 ```
 
-## Forbidden in React
+Store actions are pure `(state, payload) => state` — no I/O inside.
+
+## Styling — Tailwind + cva
+
+```ts
+// Variants via cva — never if/else string concatenation
+const buttonVariants = cva('rounded-lg px-3 py-2', {
+  variants: {
+    variant: {
+      primary:     'bg-primary text-primary-foreground',
+      destructive: 'bg-destructive text-destructive-foreground',
+    },
+  },
+})
+
+// Conditional classes via cn
+const cls = cn('rounded-lg p-4', active && 'ring-2', disabled && 'opacity-50')
+
+// Design tokens only — no hex codes or magic pixel values
+// Good: className="bg-background text-foreground gap-4"
+// Bad:  className="bg-[#0a0a0a] gap-[17px]"
+```
 
-- `useEffect` for data fetching or derived state
-- Prop drilling > 2 levels — lift state or use context/Jotai
-- `any` in prop types or event handlers
-- Mutable refs as state (`useRef` for values that drive rendering)
-- Inline object/array literals in JSX props without `useMemo`
+## Memoization
 
-## Event handlers
+Add memoization only after a profiler measurement identifies re-renders as the bottleneck. Document the reason inline.
 
 ```ts
-// Yes — named, explicit type
-const handleSelect = (id: TrackId): void => { ... }
+// Only when passed to a memoized consumer or genuinely expensive
+const sorted = useMemo(() => sortTracks(tracks), [tracks])
+// Reason: passed to memoized VirtualList
 
-// No — inline arrow in JSX prop recreated every render
-<Button onClick={() => doSomething(id)} />
+// Only when passed to memoized component or in another hook's dep array
+const handleSelect = useCallback((id: TrackId) => onSelect(id), [onSelect])
 ```
 
-## Memoisation
+Never add speculative `useMemo` / `useCallback` / `React.memo`.
+
+## Accessibility
+
+- Interactive elements use semantic HTML — never `div` with `onClick`
+- Forms: associated `label`; icon-buttons: `aria-label`; images: `alt`
+- Keyboard navigation complete; focus order logical and visible
+
+## Testing
+
+```ts
+// Yes — query by accessible role
+screen.getByRole('button', { name: /save/i })
+
+// No — data-testid
+screen.getByTestId('save-button')
+```
+
+Network mocked with MSW — never stub `fetch` directly.
+
+## Forbidden in React
 
-- Wrap expensive computations in `useMemo`
-- Wrap callbacks passed to child components in `useCallback`
-- Do not memoize everything — only when a profiler or render trace shows it matters
+- `useEffect` for data fetching, derived state, or user-event reactions
+- Prop drilling beyond 2 levels
+- `useState` for server state
+- `useStore((s) => s)` whole-store selection
+- Inline `if/else` string concatenation for Tailwind variants — use `cva`
+- `div` with `onClick` for an action — use `button`
+- `data-testid` queries in tests
+- Per-field `useState` in forms — use React Hook Form
+- Hand-built URL strings for navigation — use typed router API

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

@@ -0,0 +1,154 @@
+---
+applyTo: "**/*.{test,spec}.{ts,tsx}"
+---
+
+# TSF++ test rules
+
+Full standard: `node_modules/@tsfpp/standard/spec/TEST_CODING_STANDARD.md`
+Extends: `tsfpp-base.instructions.md` (all base TSF++ rules apply to test code)
+
+## Toolchain
+
+| Layer | Runner | Property tests | Network | DB |
+|---|---|---|---|---|
+| Core | Vitest | fast-check | — | — |
+| Use-case | Vitest | fast-check (optional) | — | In-memory stub |
+| API / handler | Vitest | — | MSW | In-memory stub |
+| DAL | Vitest | — | — | Real / containerised |
+| React | Vitest + RTL | — | MSW | — |
+
+## Test structure — AAA
+
+```ts
+it('returns None when the input string is empty', () => {
+  const raw = ''                  // Arrange
+
+  const result = mkTrackId(raw)   // Act
+
+  expect(result).toEqual(none)    // Assert
+})
+```
+
+One blank line between phases. One logical assertion per test. No branching or loops in test bodies.
+
+## Describe block structure
+
+```ts
+describe('mkTrackId', () => {
+  describe('when the input is valid', () => {
+    it('returns Some containing a branded TrackId', () => { ... })
+  })
+  describe('when the input is empty', () => {
+    it('returns None', () => { ... })
+  })
+})
+```
+
+Max two levels of nesting. Test descriptions are full sentences describing behaviour.
+
+## Property-based tests — fast-check
+
+Required for every pure function and combinator. Laws in `@law` JSDoc must have a corresponding property test.
+
+```ts
+import * as fc from 'fast-check'
+
+it('satisfies the identity law: map(id) ≡ id', () => {
+  fc.assert(
+    fc.property(fc.integer(), (n) => {
+      expect(pipe(ok(n), map(x => x))).toEqual(ok(n))
+    }),
+  )
+})
+```
+
+## React components — RTL
+
+```ts
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+it('calls onSelect with the track id when the row is clicked', async () => {
+  const onSelect = vi.fn()
+  render(<TrackRow track={makeTrack()} onSelect={onSelect} />)
+
+  await userEvent.click(screen.getByRole('row', { name: /test track/i }))
+
+  expect(onSelect).toHaveBeenCalledWith(expect.any(String))
+})
+```
+
+Query hierarchy (use the first that works):
+1. `getByRole` — always preferred
+2. `getByLabelText`
+3. `getByText`
+4. `getByPlaceholderText`
+
+Never `getByTestId`.
+
+## Network mocking — MSW
+
+```ts
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+
+const server = setupServer(
+  http.get('/api/tracks', () => HttpResponse.json(trackFixtures)),
+)
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+
+Never stub `fetch`, `axios`, or any HTTP client directly.
+
+## Port stubs — in-memory implementations
+
+```ts
+// Good — typed in-memory implementation of the port
+const repo = mkInMemoryTrackRepository()
+
+// Bad — partial vi.fn() mock
+const repo = { findById: vi.fn().mockResolvedValue(track) }
+```
+
+`vi.fn()` is permitted only for standalone callbacks (`onClose`, `onSelect`, etc.).
+
+## Factories
+
+```ts
+// tests/factories/track.factory.ts
+const makeTrack = (overrides: Partial<Track> = {}): Track => ({
+  id:       mkTrackId('test-track-001'),
+  title:    'Default Title',
+  artistId: mkArtistId('test-artist-001'),
+  ...overrides,
+})
+```
+
+- Factories live in `tests/factories/` — never inline raw object literals
+- Fixture IDs are deterministic strings that cannot collide with real data
+- Never copy IDs from production or staging environments
+
+## What to cover
+
+| Layer | Must cover |
+|---|---|
+| Core | Every export · every smart constructor boundary · every error path · laws via fast-check |
+| Use-case | Success path · each distinct `Err` variant · any enforced invariant |
+| API handler | Each missing required field (422) · success status + headers · each `ApiError` variant · auth failure |
+| DAL | Insert+read round-trip · not-found → `None` · constraint violation → typed `DataError` |
+| React | Renders · user interactions · loading state · error state · keyboard/ARIA |
+
+## Never
+
+- `data-testid` queries
+- `vi.fn()` to implement a port interface
+- Assert that an internal function was called — assert on the observable outcome
+- `any` in test code
+- `setTimeout` delays — use `waitFor` or `findBy*`
+- `beforeAll` for state that mutates between tests
+- Snapshot tests for component structure or API response shape
+- Direct access to non-exported symbols or internal state
+- `shallow` rendering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsfpp/agents",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Workspace AI tooling for TSF++ projects: scoped instructions, coding agents, and reusable prompts",
   "keywords": [
     "tsfpp",