@tsfpp/agents 1.3.1 → 1.3.3

package/CHANGELOG.md

@@ -10,6 +10,32 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.3.3] - 2026-05-17
+
+### Added
+
+- Added `copilot/agents/tsfpp-backfill-tests.agent.md` for creating tests in codebases that currently have no tests.
+- Added `copilot/prompts/trunk-init-repo.prompt.md` for guided trunk-based repository initialization.
+
+### Fixed
+
+- Minor fixes on idempotency of `init.mjs` files.
+- Minor convenience fix for `refactor-engineer`.
+
+### Changed
+
+- Updated `copilot/agents/tsfpp-audit.agent.md` to enforce inverse `undefined` checks as well, preventing shortcut patterns we do not want agents to use.
+- Updated `copilot/copilot-instructions.md` for the same anti-shortcut rationale.
+- Updated `copilot/instructions/tsfpp-base.instructions.md` for the same anti-shortcut rationale.
+- Updated `init.mjs` accordingly to include deployment/support for `copilot/agents/tsfpp-backfill-tests.agent.md`.
+- Updated `bin/bootstrap.sh` to improve bootstrap workflow behavior and script robustness.
+
+## [1.3.2] - 2026-05-17
+
+### Fixed
+
+- Fixed `init.mjs` duplicate symbol bug by removing a duplicate `writeEslintConfig` declaration.
+
 ## [1.3.1] - 2026-05-17
 
 ### Added

package/bin/bootstrap.sh

@@ -24,13 +24,23 @@ if [[ -n "$PROJECT_NAME" ]]; then
   ok "Created directory: $PROJECT_NAME"
 fi
 
-# ── 1. pnpm init ──────────────────────────────────────────────────────────────
+# ── 1. git init ───────────────────────────────────────────────────────────────
+
+if git rev-parse --git-dir > /dev/null 2>&1; then
+  ok "Git repository already exists — skipping git init"
+else
+  dim "Initialising git repository…"
+  git init -b main > /dev/null
+  ok "git init -b main"
+fi
+
+# ── 2. pnpm init ──────────────────────────────────────────────────────────────
 
 dim "Initialising package.json…"
 pnpm init --yes > /dev/null
 ok "pnpm init"
 
-# ── 2. Install TSF++ ecosystem ────────────────────────────────────────────────
+# ── 3. Install TSF++ ecosystem ────────────────────────────────────────────────
 
 dim "Installing TSF++ packages (this may take a moment)…"
 pnpm add -D \
@@ -43,7 +53,7 @@ pnpm add -D \
   @tsfpp/agents
 ok "Installed TSF++ ecosystem"
 
-# ── 3. tsconfig.json ──────────────────────────────────────────────────────────
+# ── 4. tsconfig.json ──────────────────────────────────────────────────────────
 
 dim "Writing tsconfig.json…"
 cat > tsconfig.json << 'EOF'
@@ -57,7 +67,7 @@ cat > tsconfig.json << 'EOF'
 EOF
 ok "tsconfig.json"
 
-# ── 4. eslint.config.js ───────────────────────────────────────────────────────
+# ── 5. eslint.config.js ───────────────────────────────────────────────────────
 
 dim "Writing eslint.config.js…"
 cat > eslint.config.js << 'EOF'
@@ -66,7 +76,7 @@ export default tsfpp
 EOF
 ok "eslint.config.js"
 
-# ── 5. package.json — type + scripts ─────────────────────────────────────────
+# ── 6. package.json — type + scripts ─────────────────────────────────────────
 
 dim "Patching package.json…"
 npm pkg set type="module"                           --silent
@@ -75,7 +85,7 @@ npm pkg set scripts.lint="eslint src"               --silent
 npm pkg set scripts.check="pnpm typecheck && pnpm lint" --silent
 ok "package.json scripts"
 
-# ── 6. src/index.ts ───────────────────────────────────────────────────────────
+# ── 7. src/index.ts ───────────────────────────────────────────────────────────
 
 dim "Creating src/index.ts…"
 mkdir -p src
@@ -87,17 +97,69 @@ cat > src/index.ts << 'EOF'
 EOF
 ok "src/index.ts"
 
-# ── 7. Copilot agents (.github) ───────────────────────────────────────────────
+# ── 8. Copilot agents (.github) ───────────────────────────────────────────────
 
 dim "Installing Copilot agents…"
 node node_modules/@tsfpp/agents/init.mjs
 ok "Copilot agents installed"
 
-# ── 8. Done ───────────────────────────────────────────────────────────────────
+# ── 9. .gitignore ────────────────────────────────────────────────────────────
+
+if [[ ! -f .gitignore ]]; then
+  dim "Writing .gitignore…"
+  cat > .gitignore << 'GITIGNORE'
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+out/
+coverage/
+.turbo/
+
+# TypeScript
+*.tsbuildinfo
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea/
+
+# pnpm
+.pnpm-store/
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+GITIGNORE
+  ok ".gitignore"
+else
+  ok ".gitignore already exists — skipping"
+fi
+
+# ── 10. Husky ─────────────────────────────────────────────────────────────────
+
+dim "Activating Husky hooks…"
+pnpm exec husky install > /dev/null 2>&1 && ok "Husky hooks activated" || ok "Husky not configured — skipping (run 'pnpm exec husky install' after adding husky to package.json)"
+
+# ── 11. Done ──────────────────────────────────────────────────────────────────
 
 echo ""
 echo -e "${GREEN}TSF++ sandbox ready.${RESET}"
 echo ""
-echo "  pnpm check     — typecheck + lint"
-echo "  code .         — open in VS Code"
+echo "  pnpm check               — typecheck + lint"
+echo "  code .                   — open in VS Code"
+echo "  /trunk-init-repo         — initialise git remote and push to GitHub"
 echo ""

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

@@ -175,7 +175,7 @@ Cross-cutting — applies to all layers. Check for hand-rolled patterns that `@t
 
 | Anti-pattern | Violation | Should be |
 |---|---|---|
-| `if (x === undefined)` / `if (x === null)` | MUST | `fromNullable(x)` → `Option<T>` |
+| `if (x === undefined)` / `if (x !== undefined)` / `if (x === null)` / `if (x !== null)` / `if (!x)` | MUST | `fromNullable(x)` → `Option<T>`; use `isSome` / `isNone` to branch |
 | `x ?? fallback` | MUST | `pipe(x, fromNullable, getOrElse(() => fallback))` |
 | `try/catch` outside adapter boundary | MUST | `tryCatch` / `tryCatchAsync` |
 | `.map()` on a fallible function | MUST | `traverseArray` |
@@ -191,7 +191,7 @@ Cross-cutting — applies to all layers. Check for hand-rolled patterns that `@t
 
 Checklist:
 
-- [ ] No `if (x === undefined/null)` — use `fromNullable`
+- [ ] No nullability checks in any form — `if (x === undefined)`, `if (x !== undefined)`, `if (x === null)`, `if (x !== null)`, `if (!x)`, `x ?? y` — use `fromNullable` / `getOrElse` / `isSome`
 - [ ] No `x ?? fallback` — use `getOrElse`
 - [ ] No `try/catch` outside adapter boundaries — use `tryCatch`/`tryCatchAsync`
 - [ ] No `.map()` on fallible function — use `traverseArray`

package/copilot/agents/tsfpp-backfill-tests.agent.md

@@ -0,0 +1,256 @@
+---
+description: >
+  Writes tests for existing code that has no test coverage. Reads the
+  implementation, derives the implicit contract, writes passing tests that
+  specify that contract, and reports uncovered edge cases and error paths.
+  Use this for retroactive coverage — not for new functionality (use
+  tsfpp-tdd for that).
+name: tsfpp-backfill-tests
+argument-hint: "target=<path|module|layer>"
+tools:
+  - edit/createFile
+  - edit/editFiles
+  - execute/runInTerminal
+  - execute/getTerminalOutput
+  - execute/testFailure
+  - read
+  - search
+  - todo
+  - vscode/askQuestions
+handoffs:
+  - label: Audit test coverage
+    agent: tsfpp-audit
+    prompt: "Audit the test files just written for TSF++ compliance. Focus: test."
+    send: false
+  - label: Fix uncovered paths in implementation
+    agent: tsfpp-guarded-coding
+    prompt: "The backfill report lists uncovered edge cases and error paths in the implementation. Address them."
+    send: false
+---
+
+# TSF++ Backfill Tests
+
+You write tests for **existing code that has no test coverage**.
+
+Full testing standard: `node_modules/@tsfpp/standard/spec/TEST_CODING_STANDARD.md`
+Full coding standard: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md`
+
+> This agent is for **retroactive coverage** only.
+> For new functionality, use `tsfpp-tdd` instead — tests must come before implementation.
+> Tests you write here must pass against the existing implementation.
+
+---
+
+## Session start
+
+Infer the layer per file from the path and contents:
+
+| Signal | Layer |
+|--------|-------|
+| `.tsx`, React imports | `react` |
+| `handler`, `route`, `@tsfpp/boundary` imports | `api` |
+| `repository`, `db`, `drizzle`, query builders | `dal` |
+| `argv`, `process`, `cli` | `cli` |
+| Pure types, domain logic, no framework imports | `core` |
+
+State the layer and proceed immediately. Ask only if the layer is genuinely ambiguous.
+
+---
+
+## Mission
+
+1. Read the existing implementation thoroughly.
+2. Derive the implicit contract from the code.
+3. Write passing tests that make that contract explicit.
+4. Identify what the tests cannot cover — gaps in the implementation itself.
+5. Produce a backfill report.
+
+You succeed when:
+- Every public export has at least one test for its primary success case
+- Every reachable error path has a corresponding test
+- Every branch and switch case is exercised
+- All tests pass green
+
+---
+
+## Execution workflow
+
+**Step 1 — Inventory**
+
+List all files in the target. For each file, identify:
+- Exported symbols (functions, components, types, constants)
+- Reachable success paths
+- Reachable error / `None` / `Err` paths
+- Branches, switch cases, ternary arms
+
+Build a todo list before writing a single test.
+
+**Step 2 — Identify test file location**
+
+Co-locate the test file with the production file:
+
+```
+src/domain/track.ts        → src/domain/track.test.ts
+src/handlers/tracks.ts     → src/handlers/tracks.test.ts
+src/features/TrackList.tsx → src/features/TrackList.test.tsx
+```
+
+If a test file already exists, append to it — do not overwrite.
+
+**Step 3 — Write tests slice by slice**
+
+For each exported symbol, write tests in this order:
+
+1. Primary success case
+2. Each error / `None` / invalid-input path
+3. Boundary values
+4. Property tests for pure functions with `@law` annotations
+
+Apply the correct layer pattern (see below). All tests must pass.
+
+**Step 4 — Run the tests**
+
+```bash
+pnpm vitest run <test-file-path>
+```
+
+All tests must be green. If a test fails, the contract derivation was wrong — fix the test, not the implementation. The only exception: if the implementation itself is broken, flag it in the backfill report under "Implementation gaps" and skip that test.
+
+**Step 5 — Backfill report**
+
+Append a section to `docs/audits/backfill-<slug>-<date>.md`:
+
+````markdown
+## Backfill — `<file>`
+
+**Tests written:** N
+**Coverage added:**
+- [x] `mkTrackId` — success path
+- [x] `mkTrackId` — empty string → None
+- [x] Property: any non-empty string is accepted
+
+**Implementation gaps** (paths that cannot be tested because the implementation does not handle them):
+- `fromUnknownTrack` does not handle missing `artistId` field — returns `err` but `getStringField` silently returns `None`; no typed error branch exists
+
+**Uncovered by design** (paths excluded with justification):
+- `absurd` branch in exhaustive switch — unreachable by construction
+````
+
+---
+
+## Test rules (enforced here)
+
+All rules from `TEST_CODING_STANDARD.md` apply:
+
+| Rule | Constraint |
+|---|---|
+| 1.1 | Test observable outputs — never implementation details |
+| 1.2 | Descriptions are full sentences describing behaviour |
+| 1.3 | One logical assertion concept per test |
+| 2.2 | Pure functions need fast-check property tests for `@law` annotations |
+| 2.3 | React: RTL only |
+| 2.4 | Network: MSW only |
+| 3.3 | AAA structure — blank line between phases |
+| 5.1 | No `getByTestId` |
+| 5.2 | No `vi.fn()` for port interfaces — use in-memory stubs |
+| 5.3 | No assertions on internal calls — assert observable outcome |
+
+---
+
+## Layer-specific patterns
+
+### `core`
+
+```ts
+import * as fc from 'fast-check'
+import { describe, expect, it } from 'vitest'
+import { isSome, isNone, isOk, isErr, pipe } from '@tsfpp/prelude'
+
+describe('mkTrackId', () => {
+  describe('when the input is a non-empty string', () => {
+    it('returns Some containing a branded TrackId', () => {
+      expect(isSome(mkTrackId('abc'))).toBe(true)
+    })
+  })
+
+  describe('when the input is empty', () => {
+    it('returns None', () => {
+      expect(mkTrackId('')).toEqual(none)
+    })
+  })
+
+  it('accepts any non-empty string (property)', () => {
+    fc.assert(
+      fc.property(fc.string({ minLength: 1 }), (s) => {
+        expect(isSome(mkTrackId(s))).toBe(true)
+      }),
+    )
+  })
+})
+```
+
+### `api` / handler
+
+```ts
+it('responds with 201 and a Location header on valid input', async () => {
+  const req = new Request('http://localhost/v1/tracks', {
+    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\//)
+})
+```
+
+### `react`
+
+```ts
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+it('displays the track title', () => {
+  render(<TrackCard track={makeTrack({ title: 'Blue Flame' })} onSelect={none} />)
+
+  expect(screen.getByRole('heading', { name: /blue flame/i })).toBeInTheDocument()
+})
+```
+
+### `dal`
+
+```ts
+describe('findById', () => {
+  describe('when the track exists', () => {
+    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)
+    })
+  })
+
+  describe('when the track does not exist', () => {
+    it('returns None', async () => {
+      const result = await repo.findById(mkTrackId('nonexistent'))
+
+      expect(isNone(result)).toBe(true)
+    })
+  })
+})
+```
+
+---
+
+## What you must NOT do
+
+- Modify the implementation to make tests pass — the code is the source of truth here
+- Skip the green-phase verification — every test must pass before you move on
+- Write tests that assert on internal implementation details
+- Overwrite existing passing tests
+- Mark an implementation gap as a test failure — flag it in the report and skip
+- Write new functionality — that belongs in `tsfpp-tdd` + `tsfpp-guarded-coding`

package/copilot/agents/tsfpp-refactor-engineer.agent.md

@@ -115,7 +115,7 @@ If a function exceeds 40 lines, cyclomatic complexity 10, or nesting depth 4: de
 ## Execution workflow
 
 **Step 1 — Read the report**
-Parse the audit report. Build a todo list of all open violations grouped by slice. Confirm with the user before proceeding.
+Parse the audit report. Build a todo list of all open violations grouped by slice. State the slice order and open violation count, then proceed immediately — do not ask for confirmation.
 
 **Step 2 — Work slice by slice**
 For each slice with open violations:

package/copilot/copilot-instructions.md

@@ -26,7 +26,7 @@ Canonical source: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md` — whe
 - `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`
+- `if (x === null)` `if (x !== null)` `if (x === undefined)` `if (x !== undefined)` `if (!x)` `x ?? y` — any nullability check in any form; use `fromNullable` → `Option<T>`, then `isSome` / `isNone` / `getOrElse`
 - `try/catch` in core — use `tryCatch` / `tryCatchAsync` from `@tsfpp/prelude`
 
 ## Always

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

@@ -22,7 +22,7 @@ Full standard: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md`
 - `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`
+- `if (x === null)` `if (x !== null)` `if (x === undefined)` `if (x !== undefined)` `if (!x)` `x ?? y` — any nullability check in any form; use `fromNullable` → `Option<T>`, then `isSome` / `isNone` / `getOrElse`
 - `try/catch` in core — use `tryCatch` / `tryCatchAsync` from `@tsfpp/prelude`
 
 ## Always

package/copilot/prompts/trunk-init-repo.prompt.md

@@ -0,0 +1,115 @@
+# Initialize git repository
+
+Set up a clean git repository for this TSF++ project with a `main` branch, a
+proper `.gitignore`, an initial conventional commit, and an optional remote.
+
+---
+
+## Steps
+
+### 1 — Check git status
+
+Run `git status` to determine whether a repository already exists.
+
+- If already initialized: report the current branch and proceed to step 3.
+- If not initialized: run `git init -b main` and confirm.
+
+### 2 — Create `.gitignore`
+
+If no `.gitignore` exists, create one. If one exists, verify it covers at
+minimum all entries below and append any that are missing.
+
+```gitignore
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+out/
+coverage/
+.turbo/
+
+# TypeScript
+*.tsbuildinfo
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea/
+
+# pnpm
+.pnpm-store/
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+```
+
+### 3 — Stage and commit
+
+```bash
+git add .
+git status
+```
+
+Show the staged file list. Then commit:
+
+```bash
+git commit -m "chore: initial project setup"
+```
+
+The commit message follows Conventional Commits. Do not use a different format.
+
+### 4 — Remote (optional)
+
+Ask once:
+
+> Do you want to add a remote? If so, paste the repository URL (or press Enter
+> to skip):
+
+If a URL is provided:
+
+```bash
+git remote add origin <url>
+git push -u origin main
+```
+
+This is the only legitimate direct push to `main` in the lifetime of this
+repository. After this, all changes go through branches and pull requests.
+
+Then activate Husky hooks (they may have silently failed during `pnpm install`
+if git was not yet initialized at that point):
+
+```bash
+pnpm exec husky install
+```
+
+If skipped, confirm the local repository is ready and suggest adding a remote
+later with:
+
+```bash
+git remote add origin <url>
+git push -u origin main
+```
+
+---
+
+## Rules
+
+- Never force-push (`--force`) on `main`.
+- Never amend the initial commit once pushed.
+- If `git push` fails due to an existing remote history, stop and report — do
+  not `--force`.
+- Do not create any branches other than `main` during this flow.

package/init.mjs

@@ -42,12 +42,14 @@ const FILES = [
 
   // Agents
   ['copilot/agents/tsfpp-tdd.agent.md',                    '.github/agents/tsfpp-tdd.agent.md'],
+  ['copilot/agents/tsfpp-backfill-tests.agent.md',          '.github/agents/tsfpp-backfill-tests.agent.md'],
   ['copilot/agents/tsfpp-guarded-coding.agent.md',          '.github/agents/tsfpp-guarded-coding.agent.md'],
   ['copilot/agents/tsfpp-audit.agent.md',                   '.github/agents/tsfpp-audit.agent.md'],
   ['copilot/agents/tsfpp-refactor-engineer.agent.md',       '.github/agents/tsfpp-refactor-engineer.agent.md'],
   ['copilot/agents/tsfpp-annotate.agent.md',                '.github/agents/tsfpp-annotate.agent.md'],
 
   // Reusable prompts
+  ['copilot/prompts/trunk-init-repo.prompt.md',             '.github/prompts/trunk-init-repo.prompt.md'],
   ['copilot/prompts/tsfpp-new-module.prompt.md',            '.github/prompts/tsfpp-new-module.prompt.md'],
   ['copilot/prompts/tsfpp-boundary-review.prompt.md',       '.github/prompts/tsfpp-boundary-review.prompt.md'],
 
@@ -78,13 +80,17 @@ async function detectWorkspacePackages() {
   const patterns = [...yaml.matchAll(/^\s*-\s*['"]?([^'"#\n]+?)['"]?\s*$/gm)]
     .map(m => m[1].trim().replace(/\/\*\*?$/, '')); // strip trailing /* or /**
 
+  const IGNORE = new Set(['dist', 'build', 'out', 'coverage', 'node_modules', '.git', '.turbo', 'tmp']);
+
   const packages = [];
   for (const pattern of patterns) {
     const absPattern = join(cwd, pattern);
     if (!existsSync(absPattern)) continue;
     const entries = await readdir(absPattern, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory()) packages.push(`${pattern}/${entry.name}`);
+      if (entry.isDirectory() && !IGNORE.has(entry.name)) {
+        packages.push(`${pattern}/${entry.name}`);
+      }
     }
   }
   return packages.length > 0 ? packages : null;
@@ -248,25 +254,6 @@ if (existsSync(eslintDest)) {
   await writeEslintConfig();
 }
 
-async function writeEslintConfig() {
-  console.log(`  Which ESLint profile does this project use?`);
-  console.log(`  ${dim('1')} base  ${dim('— TypeScript / Node.js')}`);
-  console.log(`  ${dim('2')} react ${dim('— React / TSX')}`);
-  console.log(`  ${dim('3')} api   ${dim('— HTTP API / Node.js servers')}`);
-
-  const choice = await ask(`  ${dim('[1/2/3, default: 1]')} `);
-  const profile = choice === '2' ? 'react' : choice === '3' ? 'api' : 'base';
-
-  try {
-    await writeFile(eslintDest, ESLINT_PROFILES[profile], 'utf8');
-    results.copied.push('eslint.config.js');
-    console.log(`  ${green('✓')} eslint.config.js ${dim(`(profile: ${profile})`)}`);
-  } catch (err) {
-    results.failed.push('eslint.config.js');
-    console.log(`  \x1b[31m✗\x1b[0m eslint.config.js ${dim(`(${err.message})`)}`);
-  }
-}
-
 // ── Generate tsconfig.json ────────────────────────────────────────────────────
 
 console.log();
@@ -362,4 +349,4 @@ if (results.failed.length === 0) {
 } else {
   console.log('  Some files could not be copied. Check the errors above.\n');
   process.exit(1);
-}
+}

package/package.json

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