@tsfpp/agents 1.3.4 → 1.4.0

package/copilot/agents/tsfpp-tdd.agent.md

@@ -36,6 +36,13 @@ Full coding standard: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md`
 
 ---
 
+## Before writing any test
+
+Load and apply the `/test-standard` skill. Every test you write must conform to
+all rules in that skill. Do not write a single test before the skill is loaded.
+
+---
+
 ## Session start
 
 Infer the layer per task from the user's message:
@@ -153,6 +160,36 @@ All rules from `TEST_CODING_STANDARD.md` apply. The most critical during test au
 
 ---
 
+## Factories
+
+Always use typed factory functions from `tests/factories/` for test data.
+Never write raw object literals inline.
+
+```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,
+})
+```
+
+Import and use with overrides for the specific case under test:
+
+```ts
+// Specific case — override only what matters for this test
+const track = makeTrack({ title: 'Blue Flame' })
+
+// Default case — the specific values don't matter
+const track = makeTrack()
+```
+
+Never hard-code raw objects like `{ id: 'abc', title: 'Test', artistId: 'xyz' }` in test bodies.
+Never use production or staging IDs in fixtures.
+
+---
+
 ## Layer-specific test patterns
 
 ### `core`
@@ -164,14 +201,21 @@ import { isSome, isNone, isOk, isErr } from '@tsfpp/prelude'
 describe('mkTrackId', () => {
   describe('when the input is a non-empty string', () => {
     it('returns Some containing a branded TrackId', () => {
-      const result = mkTrackId('abc')
+      const raw = 'abc'
+
+      const result = mkTrackId(raw)
+
       expect(isSome(result)).toBe(true)
     })
   })
 
   describe('when the input is empty', () => {
     it('returns None', () => {
-      expect(mkTrackId('')).toEqual(none)
+      const raw = ''
+
+      const result = mkTrackId(raw)
+
+      expect(result).toEqual(none)
     })
   })
 
@@ -200,11 +244,13 @@ describe('POST /v1/tracks', () => {
   describe('when the request body is valid', () => {
     it('responds with 201 and a Location header', async () => {
       const req = new Request('http://localhost/v1/tracks', {
-        method: 'POST',
-        body: JSON.stringify({ title: 'Test', artistId: 'a1' }),
+        method:  'POST',
+        body:    JSON.stringify({ title: 'Test', artistId: 'a1' }),
         headers: { 'Content-Type': 'application/json' },
       })
+
       const res = await handler(req)
+
       expect(res.status).toBe(201)
       expect(res.headers.get('Location')).toMatch(/\/v1\/tracks\//)
     })
@@ -212,12 +258,16 @@ describe('POST /v1/tracks', () => {
 
   describe('when title is missing', () => {
     it('responds with 422', async () => {
+      const input = makeCreateTrackInput({ title: undefined })  // override to trigger validation failure
+
       const req = new Request('http://localhost/v1/tracks', {
-        method: 'POST',
-        body: JSON.stringify({ artistId: 'a1' }),
+        method:  'POST',
+        body:    JSON.stringify(input),
         headers: { 'Content-Type': 'application/json' },
       })
+
       const res = await handler(req)
+
       expect(res.status).toBe(422)
     })
   })
@@ -266,7 +316,9 @@ describe('TrackRepository', () => {
       it('returns Some containing the track', async () => {
         const track = makeTrack()
         await repo.save(track)
+
         const result = await repo.findById(track.id)
+
         expect(isSome(result)).toBe(true)
       })
     })
@@ -274,6 +326,7 @@ describe('TrackRepository', () => {
     describe('when the track does not exist', () => {
       it('returns None', async () => {
         const result = await repo.findById(mkTrackId('nonexistent'))
+
         expect(isNone(result)).toBe(true)  // will fail — findById not implemented
       })
     })

package/copilot/prompts/trunk-changelog.prompt.md

@@ -0,0 +1,160 @@
+# Write changelog entry
+
+Inspect the current working tree, derive the correct conventional commit message,
+and append a matching entry to the `## [Unreleased]` section of `CHANGELOG.md`.
+
+---
+
+## Step 1 — Inspect changes
+
+Run the following to see what has changed:
+
+```bash
+git diff --stat HEAD
+git status --short
+```
+
+For each changed or added file, read enough of its diff to understand **what
+changed and why** — not just which lines moved.
+
+```bash
+git diff HEAD -- <file>
+```
+
+If files are staged but not committed, use:
+
+```bash
+git diff --cached --stat
+git diff --cached -- <file>
+```
+
+---
+
+## Step 2 — Classify changes
+
+Map each change to a Conventional Commits type:
+
+| Type | Use when |
+|---|---|
+| `feat` | New behaviour or capability visible to a consumer |
+| `fix` | Corrects incorrect behaviour |
+| `perf` | Improves performance without changing behaviour |
+| `refactor` | Internal restructuring; no behaviour change, no bug fix |
+| `test` | Adds or fixes tests; no production code change |
+| `docs` | Documentation only |
+| `chore` | Tooling, config, dependencies, release machinery |
+| `build` | Build system or external dependency changes |
+| `ci` | CI configuration changes |
+
+**Breaking change:** any change that removes or renames a public export, changes
+a function signature, or alters a type in a way that requires consumer updates.
+Mark with `!` after the type (e.g. `feat!`) and add a `BREAKING CHANGE:` footer.
+
+**Scope:** the package or module affected — e.g. `prelude`, `boundary`, `agents`,
+`react`, `dal`. Omit if the change is cross-cutting.
+
+---
+
+## Step 3 — Write the commit message
+
+Produce a conventional commit message following this format exactly:
+
+```
+<type>(<scope>): <imperative summary in sentence case, ≤ 72 chars>
+
+<optional body — what changed and why, not how, wrapped at 72 chars>
+
+<optional footers>
+BREAKING CHANGE: <description if applicable>
+Closes #<issue> (if applicable)
+```
+
+Rules:
+- Summary is imperative mood: "add", "fix", "remove" — not "added", "fixes"
+- Summary does not end with a period
+- Body explains the **why**, not the **what** (the diff is the what)
+- One commit per logical change; if the diff contains multiple unrelated changes,
+  produce one message per change and say so
+
+---
+
+## Step 4 — Update CHANGELOG.md
+
+Find or create the `## [Unreleased]` section at the top of `CHANGELOG.md`.
+If `CHANGELOG.md` does not exist, create it with this header:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+This file is maintained automatically by [release-please](https://github.com/googleapis/release-please)
+and supplemented during development via the `/trunk-changelog` prompt.
+
+<!-- do not remove this comment — release-please uses it as an anchor -->
+<!-- RELEASE-PLEASE-INSERTION-POINT -->
+
+## [Unreleased]
+```
+
+Append the new entry under `## [Unreleased]`, grouped by type in this order:
+
+```markdown
+## [Unreleased]
+
+### Breaking changes
+- `feat!(boundary)!: remove legacy `fold` export` — consumers must migrate to `map`/`flatMap`
+
+### Features
+- `feat(prelude): add ReadonlyMap combinators` — `intoMap`, `assoc`, `dissoc`, `lookup`, `entriesOfMap`
+
+### Bug fixes
+- `fix(agents): init.mjs fails with ReferenceError when run with --yes`
+
+### Performance
+- ...
+
+### Refactoring
+- ...
+
+### Tests
+- ...
+
+### Documentation
+- ...
+
+### Chores
+- ...
+```
+
+Only include sections that have entries. Do not add empty sections.
+
+Each entry is a single line:
+- Backtick-quoted commit summary
+- Em dash
+- One-sentence plain-English explanation of the user-visible impact
+
+---
+
+## Step 5 — Output
+
+Print the proposed commit message in a code block so it can be copied directly
+into the terminal or used with `git commit`:
+
+```
+git commit -m "<type>(<scope>): <summary>" \
+           -m "<body paragraph if needed>"
+```
+
+If there are multiple logical changes, list each message separately and recommend
+committing them individually with `git add -p` to stage per-change.
+
+---
+
+## Rules
+
+- Never invent changes that are not visible in the diff
+- Never write a changelog entry for a change that has no user-visible impact
+  (internal renaming, comment edits) — use `chore` or `refactor` in the commit
+  message but omit from `## [Unreleased]`
+- Do not modify any section of `CHANGELOG.md` other than `## [Unreleased]`
+- release-please owns every versioned section (`## [1.2.3]`) — never touch those

package/copilot/skills/annotation-standard/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: annotation-standard
+description: >
+  Normative TSF++ annotation rules for all comments, JSDoc blocks, module
+  headers, code markers, and deviation records. Load when writing, reviewing,
+  or adding annotations to any TypeScript file: the "why not what" principle,
+  JSDoc body content (invariants, rejected alternatives, external contracts,
+  accepted imprecision, performance trade-offs), marker taxonomy with format,
+  DEVIATION pairing, and what must never be annotated.
+---
+
+# TSF++ annotation standard
+
+Full standard: `node_modules/@tsfpp/standard/spec/ANNOTATION_CODING_STANDARD.md`
+
+---
+
+## The single deciding question
+
+> Does this tell the reader something they cannot confidently derive from the code and its types?
+
+If no — do not add the comment. If yes — write it.
+
+---
+
+## What only a comment can tell you
+
+| Category | Example |
+|---|---|
+| **Why this approach** over the natural alternative | Why linear scan instead of `Map` lookup |
+| **Rejected alternatives** | What was considered and why it was ruled out |
+| **Non-obvious invariants** | Preconditions the type cannot express |
+| **Domain knowledge** | Business rules that live in the problem space |
+| **External contracts** | Field names / values dictated by a third party |
+| **Accepted imprecision** | Known limitations that are intentional |
+| **Performance trade-offs** | Why a non-obvious implementation was chosen |
+| **Temporal context** | Why a workaround exists, when to revisit it |
+
+---
+
+## JSDoc body: the why, not the what
+
+The first sentence is the purpose. Everything after is the reasoning.
+
+```ts
+/**
+ * Constructs a validated `UserId` from a raw string.
+ *
+ * Returns `None` if the input is empty. The empty case is excluded rather
+ * than mapped to an error because an empty ID indicates a caller bug, not
+ * a domain error — the type system prevents this at compile time in
+ * internal code; this guard exists for boundary inputs only.
+ *
+ * @param raw - The raw string to validate. Must be non-empty.
+ * @returns `Some(UserId)` if valid; `None` if empty.
+ *
+ * @example
+ * mkUserId('usr-00123') // => some(UserId('usr-00123'))
+ * mkUserId('')          // => none
+ */
+```
+
+`@param` describes the domain constraint, not the type. `@returns` describes the meaning, not the type. Both are already in the signature.
+
+---
+
+## Module header
+
+Required on every file with public exports:
+
+```ts
+/**
+ * @module user-account
+ *
+ * Domain model for user accounts. Provides the `UserAccount` sum type,
+ * its smart constructors, and the combinators for working with account
+ * state and identity.
+ *
+ * All functions are pure and total. Error cases are modelled via
+ * `Option<A>` (absent value) or `Result<T, E>` (fallible computation).
+ *
+ * @packageDocumentation
+ */
+```
+
+First sentence: what the module provides. Second paragraph: key design constraints a consumer needs to know. Never describe the implementation.
+
+---
+
+## Inline comment patterns
+
+### Rejected alternative
+
+```ts
+// NOTE(rob, 2026-05-18): Linear scan rather than `ReadonlyMap` lookup.
+// The active session list is always ≤10 items per user; the allocation
+// overhead of a map outweighs the O(1) lookup benefit at this scale.
+const found = sessions.find(s => s.id === id)
+```
+
+### Non-obvious invariant
+
+```ts
+// Invariant: `handlers` must be registered before this is called.
+// The runtime guarantees registration order; do not call from a module
+// initialiser that may run before the framework bootstraps.
+```
+
+### External contract
+
+```ts
+// IMPORTANT: The field name `client_id` is specified by OAuth2 RFC 6749
+// and must not be renamed despite the camelCase convention.
+// DEVIATION(1.8): Field name required by external protocol.
+```
+
+### Accepted imprecision
+
+```ts
+// NOTE(rob, 2026-05-18): Timestamp comparison has ≤1 s imprecision due
+// to clock drift between service instances. Acceptable for audit logs;
+// not acceptable for financial ordering.
+```
+
+---
+
+## Code markers
+
+Required format — no exceptions:
+
+```ts
+// MARKER(author, YYYY-MM-DD[, TICKET]): description
+```
+
+| Marker | Use when | Blocks merge? |
+|---|---|---|
+| `TODO` | Work required before next release | Soft — needs ticket |
+| `FIXME` | Known bug the author is aware of | Yes |
+| `HACK` | Temporary workaround with a deferred correct solution | Yes — needs ticket + revisit condition |
+| `NOTE` | Context a reader needs to understand the code | No |
+| `OPTIMIZE` | Correct but with a known performance concern at scale | No — needs scale threshold |
+| `BUG` | Confirmed bug not yet in a ticket | Yes — convert to FIXME + ticket |
+| `XXX` | Fragile or load-bearing — must not be casually changed | No — use sparingly |
+
+```ts
+// TODO(rjansen, 2026-05-18, ARCH-44): Replace with Result-based validation
+//   once the boundary refactor lands in v2.0.
+// HACK(rjansen, 2026-05-18, INFRA-12): Forced cast — third-party type
+//   definition is wrong. Fixed upstream in v4.x — remove after upgrade.
+// NOTE(rjansen, 2026-05-18): Rate-limit window resets at midnight UTC,
+//   not relative to first request. Contractual requirement — do not change.
+// XXX(rjansen, 2026-05-18): Initialisation order is load-bearing. The
+//   store must be hydrated before any handler is registered.
+```
+
+Author = GitHub handle or initials. Never an AI. If unknown, use `unknown`.
+
+---
+
+## DEVIATION format
+
+```ts
+// DEVIATION(N.M): <reason the violation could not be avoided>
+```
+
+The justification explains why no alternative was feasible — not what the violation is.
+
+Every `eslint-disable` must be paired:
+
+```ts
+// DEVIATION(1.5): Legacy adapter — raw type narrowed to unknown immediately below.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const payload: any = deserialise(raw)
+```
+
+The `as` in a smart constructor body:
+
+```ts
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- DEVIATION(1.6): smart-constructor body
+return some(raw as UserId)
+```
+
+---
+
+## Never annotate
+
+| Forbidden | Example |
+|---|---|
+| Paraphrasing the code | `// Check if user is admin` above `if (user.role === 'admin')` |
+| Restating the type | `// Returns a string` on `: string` |
+| Commented-out code | `// const old = legacyParse(raw)` |
+| Section dividers | `// ─────────────` with nothing meaningful |
+| Stale comments | Any comment that no longer matches the code |
+| AI attribution | `// Generated by Claude` |
+| `@throws` on Result functions | Error is in the return type, not thrown |
+| Apologetic comments | `// This is a bit hacky but...` — use `HACK` properly |