npm - @tsfpp/agents - Versions diffs - 1.3.5 → 1.5.0 - Mend

@tsfpp/agents 1.3.5 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/CHANGELOG.md +30 -0
package/README.md +218 -31
package/bin/bootstrap.sh +0 -0
package/copilot/agents/tsfpp-annotate.agent.md +99 -119
package/copilot/agents/tsfpp-audit.agent.md +123 -32
package/copilot/agents/tsfpp-guarded-coding.agent.md +25 -0
package/copilot/instructions/tsfpp-base.instructions.md +5 -0
package/copilot/prompts/trunk-changelog.prompt.md +160 -0
package/copilot/skills/annotation-standard/SKILL.md +196 -0
package/copilot/skills/config-standard/SKILL.md +205 -0
package/copilot/skills/log-standard/SKILL.md +148 -0
package/init.mjs +4 -0
package/package.json +6 -6

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

@@ -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 ADDED Viewed

@@ -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 |

package/copilot/skills/config-standard/SKILL.md ADDED Viewed

@@ -0,0 +1,205 @@
+---
+name: config-standard
+description: >
+  Normative TSF++ configuration management rules. Load when writing or reviewing
+  any code that loads environment variables, defines a Config type, calls
+  loadConfig, accesses process.env, implements a config loader, or writes
+  .env.example: loadConfig from @tsfpp/boundary, Config as typed readonly record,
+  Zod validation at the startup boundary, injection pattern, test factories.
+---
+# TSF++ config standard
+Full standard: `node_modules/@tsfpp/standard/spec/CONFIG_CODING_STANDARD.md`
+---
+## The pattern in one picture
+```
+process.env (string | undefined)
+    ↓
+loadConfig(schema, env)   ← @tsfpp/boundary — validates all vars at once
+    ↓
+Result<Config, ConfigError>
+    ↓ exit on Err at startup
+Config (typed readonly record)
+    ↓ injected into every module that needs it
+```
+`process.env` is only touched at the entry point. Everything downstream receives a typed `Config`.
+---
+## Imports
+```ts
+// In the config loader
+import { loadConfig, type ConfigError } from '@tsfpp/boundary'
+import { isErr, ok, type Result }       from '@tsfpp/prelude'
+// In application modules — inject Config as a dependency, never import process.env
+import { type Config } from '../shared/config'
+```
+---
+## Config type — project-defined, not from a package
+```ts
+// src/shared/config.ts
+export type Config = {
+  readonly server: {
+    readonly port:     number
+    readonly host:     string
+    readonly logLevel: 'debug' | 'info' | 'warn' | 'error'
+  }
+  readonly database: {
+    readonly url:            string
+    readonly poolMin:        number
+    readonly poolMax:        number
+    readonly queryTimeoutMs: number
+  }
+  readonly auth: {
+    readonly jwtSecret:       string
+    readonly tokenTtlSeconds: number
+  }
+  readonly features: {
+    readonly maintenanceMode: boolean
+  }
+}
+```
+All fields are required. Optional config uses `Option<T>`, not `T | undefined`.
+---
+## Config loader
+```ts
+// src/infrastructure/config-loader.ts
+import { z } from 'zod'
+import { loadConfig, type ConfigError } from '@tsfpp/boundary'
+import { isErr, ok, type Result }       from '@tsfpp/prelude'
+import { type Config }                  from '../shared/config'
+const schema = z.object({
+  PORT:                z.coerce.number().int().min(1).max(65535).default(3000),
+  HOST:                z.string().default('0.0.0.0'),
+  LOG_LEVEL:           z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  DATABASE_URL:        z.string().url(),
+  DATABASE_POOL_MIN:   z.coerce.number().int().min(1).default(2),
+  DATABASE_POOL_MAX:   z.coerce.number().int().min(1).default(10),
+  DATABASE_TIMEOUT_MS: z.coerce.number().int().min(100).default(5000),
+  JWT_SECRET:          z.string().min(32),
+  TOKEN_TTL_SECONDS:   z.coerce.number().int().min(60).default(3600),
+  MAINTENANCE_MODE:    z.coerce.boolean().default(false),
+})
+export const parseConfig = (
+  env: Record<string, string | undefined>
+): Result<Config, ConfigError> => {
+  const raw = loadConfig(schema, env)
+  if (isErr(raw)) return raw
+  const e = raw.value
+  return ok({
+    server:   { port: e.PORT, host: e.HOST, logLevel: e.LOG_LEVEL },
+    database: { url: e.DATABASE_URL, poolMin: e.DATABASE_POOL_MIN,
+                poolMax: e.DATABASE_POOL_MAX, queryTimeoutMs: e.DATABASE_TIMEOUT_MS },
+    auth:     { jwtSecret: e.JWT_SECRET, tokenTtlSeconds: e.TOKEN_TTL_SECONDS },
+    features: { maintenanceMode: e.MAINTENANCE_MODE },
+  })
+}
+```
+---
+## Entry point — fail at startup
+```ts
+// src/main.ts
+import { parseConfig } from './infrastructure/config-loader'
+const configResult = parseConfig(process.env)
+if (isErr(configResult)) {
+  console.error(configResult.error.summary)
+  process.exit(1)
+}
+const config = configResult.value
+// wire up the application with config
+```
+---
+## Injection — never import process.env in modules
+```ts
+// Good — Config injected as part of Deps
+type Deps = {
+  readonly db:     Database
+  readonly logger: Logger
+  readonly config: Pick<Config, 'auth'>
+}
+// Bad — reads process.env inside a module
+const ttl = parseInt(process.env.TOKEN_TTL_SECONDS ?? '3600', 10)
+// Bad — imports a config singleton
+import { config } from '../config'
+```
+Use `Pick<Config, 'auth'>` to declare precisely which slice of config a module needs.
+---
+## Zod schema conventions
+```ts
+// Required — no default; missing = startup failure
+DATABASE_URL: z.string().url()
+JWT_SECRET:   z.string().min(32)   // enforce minimum entropy for secrets
+// Optional with sensible default
+PORT:         z.coerce.number().int().default(3000)
+LOG_LEVEL:    z.enum(['debug', 'info', 'warn', 'error']).default('info')
+// Boolean — coerce from 'true' / 'false' string
+MAINTENANCE_MODE: z.coerce.boolean().default(false)
+```
+All coercion (`string → number`, `string → boolean`) happens in the schema. Never parse in application code.
+---
+## Testing
+```ts
+// Never mutate process.env in tests
+// Bad
+process.env.DATABASE_URL = 'postgres://localhost/test'
+// Good — pass a plain record to the loader
+const result = parseConfig({ DATABASE_URL: 'postgres://localhost/test', JWT_SECRET: 'a'.repeat(32), ... })
+// Config factory for use-case and integration tests
+// tests/helpers/config.factory.ts
+export const makeConfig = (overrides: Partial<Config> = {}): Config => ({
+  server:   { port: 3000, host: '127.0.0.1', logLevel: 'error', ...overrides.server },
+  database: { url: 'postgres://localhost/test', poolMin: 1, poolMax: 2,
+              queryTimeoutMs: 1000, ...overrides.database },
+  auth:     { jwtSecret: 'a'.repeat(32), tokenTtlSeconds: 3600, ...overrides.auth },
+  features: { maintenanceMode: false, ...overrides.features },
+  ...overrides,
+})
+```
+---
+## Never
+- Access `process.env` outside the config loader
+- Import a config singleton in application modules
+- Coerce types (parseInt, parseFloat) inside application code
+- Log config values or `process.env` at any level
+- Commit `.env` — only `.env.example` is committed

package/copilot/skills/log-standard/SKILL.md ADDED Viewed

@@ -0,0 +1,148 @@
+---
+name: log-standard
+description: >
+  Normative TSF++ logging rules. Load when writing or reviewing any code that
+  logs, uses the Logger port, implements a logger adapter, or calls tap/tapErr
+  for side effects: Logger port from @tsfpp/prelude, LogEntry field conventions,
+  log level semantics, structured message format, what never to log (PII,
+  secrets, stack traces), withRequestLog for HTTP, silentLogger for tests.
+---
+# TSF++ log standard
+Full standard: `node_modules/@tsfpp/standard/spec/LOG_CODING_STANDARD.md`
+---
+## Import
+```ts
+import { type Logger, type LogEntry, type LogLevel } from '@tsfpp/prelude'
+```
+Never import `pino`, `winston`, or `console` in core, use-case, or DAL code.
+---
+## Logger port
+```ts
+// Infrastructure adapter — inject this; never the library directly
+import pino from 'pino'
+import { type Logger } from '@tsfpp/prelude'
+export const logger: Logger = {
+  debug: (entry) => pinoInstance.debug(entry, entry.message),
+  info:  (entry) => pinoInstance.info(entry, entry.message),
+  warn:  (entry) => pinoInstance.warn(entry, entry.message),
+  error: (entry) => pinoInstance.error(entry, entry.message),
+}
+// Tests — always use silentLogger, never the production logger
+export const silentLogger: Logger = {
+  debug: () => undefined,
+  info:  () => undefined,
+  warn:  () => undefined,
+  error: () => undefined,
+}
+```
+---
+## Log levels
+| Level | Use when |
+|---|---|
+| `debug` | Diagnostic detail — disabled in production by default. Never log PII even at debug. |
+| `info` | A significant, expected business event occurred. One entry per meaningful outcome. |
+| `warn` | Unexpected but recoverable — retry triggered, rate limit approached, deprecated path called. |
+| `error` | Failure requiring attention — operation failed, dependency unreachable, unhandled `Err` at boundary. |
+`info` is for **business events**, not execution steps. Never log "calling repository", "repository returned".
+---
+## LogEntry field conventions
+```ts
+// message — dot-separated event name, machine-readable
+{ message: 'user.created' }
+{ message: 'payment.charge.failed' }
+{ message: 'session.expired' }
+// Always include traceId in request-scoped logs
+{ message: 'user.created', traceId: ctx.traceId, userId: user.id }
+// Always include code on error-level logs
+{ message: 'db.query.failed', code: 'db_timeout', traceId }
+// duration for operations with performance budgets (milliseconds)
+{ message: 'payment.charge.completed', duration: Date.now() - start, traceId }
+```
+Flat structure only — no nested objects. Log aggregators cannot query nested fields.
+---
+## Logging in pipelines — tap / tapErr
+Never break a `pipe` chain to log. Use `tap` / `tapErr`:
+```ts
+// Good
+pipe(
+  validateInput(input),
+  flatMap(createUser(deps.users)),
+  tap(user  => deps.logger.info({ message: 'user.created', userId: user.id, traceId })),
+  tapErr(err => deps.logger.error({ message: 'user.create.failed', code: err.code, traceId })),
+)
+// Bad — breaks the pipeline
+const result = await createUser(deps.users)(input)
+if (isOk(result)) deps.logger.info(...)  // separate from the pipeline
+```
+---
+## Log `cause` before discarding it
+`dependency` and `internal` `ApiError` variants carry a `cause` that is stripped by `apiErrorToResponse`. Log it first:
+```ts
+if (isErr(result) && result.error.kind === 'dependency') {
+  deps.logger.error({
+    message: 'payment.gateway.unreachable',
+    code:    'dependency_error',
+    error:   String(result.error.cause),
+    traceId: ctx.traceId,
+  })
+  return apiErrorToResponse(result.error, ctx)
+}
+```
+---
+## HTTP request logging
+Use `withRequestLog` from `@tsfpp/boundary` — never add manual logging to handler bodies.
+```ts
+const handler = pipe(
+  createUserHandler(deps),
+  withIdempotency(store),
+  withRequestLog(logger, '/v1/users'),  // always outermost; routeTemplate not resolved URL
+)
+```
+`routeTemplate` must be the parameterised path (`/v1/users/:id`), never the resolved URL.
+---
+## Never log
+- PII — names, emails, phone numbers, addresses, national IDs
+- Credentials — passwords, tokens, API keys, session IDs
+- Full request or response bodies at `info` or above
+- Stack traces in production — log `err.message`, not `err.stack`
+- `process.env` or config values — they may contain secrets
+- `console.*` anywhere except `main.ts` / `server.ts` startup boundary