@grimoire-cc/cli 0.13.3 → 0.14.0

package/packs/rust-pack/skills/grimoire.unit-testing-rust/reference/tdd-workflow-patterns.md

@@ -0,0 +1,259 @@
+# TDD Workflow Patterns
+
+Guidance on the test-driven development process, when to apply it, and advanced techniques.
+
+## Table of Contents
+
+- [Canon TDD — Start with a Test List](#canon-tdd--start-with-a-test-list)
+- [Red-Green-Refactor](#red-green-refactor)
+- [Transformation Priority Premise](#transformation-priority-premise)
+- [F.I.R.S.T. Principles](#first-principles)
+- [London School vs Detroit School](#london-school-vs-detroit-school)
+- [When to Use TDD](#when-to-use-tdd)
+- [When TDD Is Less Effective](#when-tdd-is-less-effective)
+- [BDD and ATDD Extensions](#bdd-and-atdd-extensions)
+- [Advanced Techniques](#advanced-techniques)
+
+## Canon TDD — Start with a Test List
+
+> Source: https://tidyfirst.substack.com/p/canon-tdd
+
+Kent Beck's recommended starting point is not a single test but a **test list** — a written enumeration of all behaviors you intend to verify. This separates the creative work (what to test) from the mechanical work (write, make pass, refactor).
+
+**Process:**
+1. Write down all behaviors the code needs — a flat list, not tests
+2. Pick the simplest item on the list
+3. Write one failing test for it
+4. Make it pass with the minimum code
+5. Refactor
+6. Cross off the item; repeat
+
+**Why test order matters:** Starting with simpler behaviors forces simpler transformations (see TPP below) and lets the design emerge naturally. Jumping to complex cases early leads to over-engineered solutions. The test list keeps you focused and prevents scope creep.
+
+## Red-Green-Refactor
+
+> Source: https://martinfowler.com/bliki/TestDrivenDevelopment.html
+
+The core TDD cycle, repeated in small increments:
+
+### 1. Red — Write a Failing Test
+
+Write the smallest test that describes the next piece of behavior. The test MUST fail before you write any production code. A test that passes immediately provides no confidence.
+
+**Rules:**
+- Write only ONE test at a time
+- The test should compile/parse but fail at the assertion
+- If the test passes immediately, it's either trivial or testing existing behavior
+
+### 2. Green — Make It Pass
+
+Write the MINIMUM code to make the failing test pass. Do not add extra logic, handle cases not yet tested, or optimize.
+
+**Rules:**
+- Write the simplest code that makes the test pass
+- It's OK to hardcode values initially — the next test will force generalization
+- Do not add code for future tests
+- All existing tests must still pass
+
+### 3. Refactor — Clean Up
+
+With all tests green, improve the code structure without changing behavior. Tests give you the safety net.
+
+**Rules:**
+- No new functionality during refactoring
+- All tests must remain green after each refactoring step
+- Remove duplication, improve naming, extract methods
+- Refactor both production code AND test code
+
+### Cycle Length
+
+Each Red-Green-Refactor cycle should take 1–10 minutes. If you're spending more than 10 minutes in the Red or Green phase, the step is too large — break it down.
+
+## Transformation Priority Premise
+
+> Source: http://blog.cleancoder.com/uncle-bob/2013/05/27/TheTransformationPriorityPremise.html
+
+When going from Red to Green, prefer simpler transformations over complex ones. Listed from simplest to most complex:
+
+1. **Constant** — return a hardcoded value
+2. **Scalar** — replace constant with a variable
+3. **Direct** — replace unconditional with conditional (if/else)
+4. **Collection** — operate on a collection instead of a scalar
+5. **Iteration** — add a loop
+6. **Recursion** — add recursive call
+7. **Assignment** — replace computed value with mutation
+
+**Example — building FizzBuzz with TDD:**
+
+```
+Test 1: input 1 → "1"          Transformation: Constant
+Test 2: input 2 → "2"          Transformation: Scalar (use the input)
+Test 3: input 3 → "Fizz"       Transformation: Direct (add if)
+Test 4: input 5 → "Buzz"       Transformation: Direct (add another if)
+Test 5: input 15 → "FizzBuzz"  Transformation: Direct (add combined if)
+Test 6: input 1-15 → full list Transformation: Iteration (generalize)
+```
+
+By following this priority, you avoid over-engineering early and let the design emerge naturally from the tests.
+
+## F.I.R.S.T. Principles
+
+Every unit test must satisfy these five properties:
+
+| Principle | Definition | Violation Signal |
+|-----------|------------|-----------------|
+| **Fast** | Runs in milliseconds | Real I/O, network calls, `sleep()` |
+| **Independent** | No dependency on other tests | Shared mutable state, ordered execution |
+| **Repeatable** | Same result every run | System clock, random data without seed, race conditions |
+| **Self-Validating** | Pass or fail without manual interpretation | Tests that print output for a human to read |
+| **Timely** | Written before or alongside production code | Tests added weeks after a feature shipped |
+
+F.I.R.S.T. is a diagnostic checklist: if a test violates any property, it will erode team trust and reduce the value of the suite.
+
+## London School vs Detroit School
+
+> Source: https://martinfowler.com/articles/mocksArentStubs.html
+
+Two schools of TDD with different philosophies on test doubles. Most teams use a hybrid.
+
+### Detroit School (Classicist, Inside-Out)
+
+- **Unit definition**: A module of any size — can span multiple classes
+- **Approach**: Bottom-up; start from domain logic, build outward
+- **Test doubles**: Avoid mocks; use real objects when feasible
+- **Verification**: State verification — examine the result after execution
+- **Testing style**: Black-box; test through public API
+- **Refactoring**: Safe — tests aren't coupled to implementation details
+- **Best for**: Building confidence in real interactions; reducing brittleness
+
+### London School (Mockist, Outside-In)
+
+- **Unit definition**: A single class in isolation
+- **Approach**: Top-down; start from the API, work inward
+- **Test doubles**: Mock all collaborators
+- **Verification**: Behavior verification — confirm correct method calls occurred
+- **Testing style**: White-box; tests know about internals
+- **Refactoring**: Can be brittle — tests break when implementation changes
+- **Best for**: Designing interactions upfront; driving architecture decisions
+
+### Recommended: Hybrid Approach
+
+Apply Detroit discipline as the default — use real objects, verify state. Apply London mocking only at architectural boundaries (external APIs, databases, clocks). Never mock value objects, pure functions, or in-process helpers.
+
+The most important rule: if you're mocking to make a test easy to write, that's often a design smell (see The Hard Test in anti-patterns). If you're mocking because the dependency is genuinely external or slow, that's the right use.
+
+## When to Use TDD
+
+TDD is most valuable when:
+
+- **Business logic** — Complex rules, calculations, state machines. TDD forces you to think through all cases before implementing.
+- **Algorithm development** — Sorting, parsing, validation, transformation logic. Tests serve as a specification.
+- **Bug fixes** — Write a test that reproduces the bug first (Red), then fix it (Green). This prevents regressions.
+- **API/interface design** — Writing tests first helps you design interfaces from the consumer's perspective.
+- **Refactoring** — Ensure tests exist before refactoring. If they don't, write characterization tests first, then refactor.
+
+## When TDD Is Less Effective
+
+TDD is not universally optimal. Use judgment:
+
+- **UI/visual components** — Layout, styling, animations are hard to express as unit tests. Use visual regression testing or snapshot tests instead.
+- **Exploratory/prototype code** — When you don't know what to build yet, writing tests first slows exploration. Spike first, then write tests.
+- **Thin integration layers** — Simple pass-through code (e.g., a controller that calls a service) may not benefit from test-first approach. Integration tests are more valuable here.
+- **Infrastructure/glue code** — Database migrations, config files, build scripts. Test these with integration or end-to-end tests.
+- **External API wrappers** — Thin clients wrapping external APIs are better tested with integration tests against the real (or sandboxed) API.
+
+For these cases, write tests AFTER the implementation (test-last), but still write them.
+
+## BDD and ATDD Extensions
+
+### Behavior-Driven Development (BDD)
+
+> Source: https://martinfowler.com/bliki/GivenWhenThen.html
+
+BDD extends TDD by using natural language to describe behavior. Useful when tests need to be readable by non-developers.
+
+**Given-When-Then** structure:
+
+```gherkin
+Given a cart with items totaling $100
+When a 10% discount is applied
+Then the total should be $90
+```
+
+Maps to test code:
+
+```python
+def test_cart_with_10_percent_discount_totals_90():
+    # Given
+    cart = Cart(items=[Item(price=100)])
+
+    # When
+    cart.apply_discount(PercentageDiscount(10))
+
+    # Then
+    assert cart.total == 90.0
+```
+
+### Acceptance TDD (ATDD)
+
+Write high-level acceptance tests before implementing a feature. These tests describe the feature from the user's perspective and drive the overall design. Unit tests (via TDD) then drive the implementation of each component.
+
+**Flow:**
+1. Write acceptance test (fails — Red)
+2. Use TDD to implement components needed to pass it
+3. Acceptance test passes (Green)
+4. Refactor
+
+ATDD is most valuable for features with clear acceptance criteria and when working with product owners or stakeholders.
+
+## Advanced Techniques
+
+### Property-Based Testing
+
+Instead of writing individual input/output pairs, define **properties** that should always hold true and let a framework generate hundreds of test cases automatically.
+
+**Best for:** Pure functions, algorithms, data transformations, serialization round-trips.
+
+**Tools:**
+- Python: [Hypothesis](https://hypothesis.readthedocs.io)
+- JavaScript/TypeScript: [fast-check](https://fast-check.dev)
+- Go: `testing/quick` (stdlib), [gopter](https://github.com/leanovate/gopter)
+- Rust: [proptest](https://github.com/proptest-rs/proptest)
+- Java: [jqwik](https://jqwik.net)
+- Elixir: [StreamData](https://hexdocs.pm/stream_data)
+
+**Example property** (Python/Hypothesis):
+```python
+from hypothesis import given, strategies as st
+
+@given(st.lists(st.integers()))
+def test_sort_is_idempotent(lst):
+    assert sorted(sorted(lst)) == sorted(lst)
+```
+
+### Mutation Testing
+
+Mutation testing introduces small code changes (mutations) and checks whether your tests catch them. A test suite that lets mutations survive has gaps in its coverage.
+
+**Metric:** Mutation score = % of mutations killed. Target 80%+.
+
+**Tools:**
+- JavaScript/TypeScript/C#: [Stryker](https://stryker-mutator.io)
+- Java: [PITest](https://pitest.org)
+- Python: [mutmut](https://mutmut.readthedocs.io)
+- Go: [go-mutesting](https://github.com/zimmski/go-mutesting)
+
+Run mutation testing periodically (not on every commit) to identify weak spots in the test suite.
+
+### Contract Testing
+
+In microservice or distributed architectures, contract tests verify that services communicate correctly without running full integration tests.
+
+**How it works:**
+1. Consumer defines a contract (expected interactions)
+2. Provider verifies it can fulfill the contract
+3. Both test independently — no need to spin up the full system
+
+**Tool:** [Pact](https://pact.io) — supports most major languages.
+
+Contract tests replace the expensive integration test layer for inter-service communication while still catching breaking API changes early.

package/packs/ts-pack/agents/grimoire.typescript-coder.md

@@ -2,12 +2,23 @@
 name: grimoire.typescript-coder
 description: "Use this agent when the user needs to write, refactor, debug, review, or understand TypeScript code in any environment — Node.js backends, React, Angular, Vue, Svelte, or any other TypeScript-compatible platform. This includes tasks like designing type-safe data models, implementing utility types, handling errors with discriminated unions, refactoring JavaScript to TypeScript, or reviewing TypeScript code for type safety and correctness.\\n\\nExamples:\\n<example>\\nContext: User wants to write a type-safe API client.\\nuser: \"Write a type-safe fetch wrapper that handles errors without throwing\"\\nassistant: \"I'll use the grimoire.typescript-coder agent to implement this with a Result type pattern.\"\\n<commentary>\\nThe user needs TypeScript code involving error handling and type safety — a perfect fit for the grimoire.typescript-coder agent.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User is refactoring an existing function.\\nuser: \"Refactor this function to be more type-safe and remove the use of `any`\"\\nassistant: \"Let me hand this off to the grimoire.typescript-coder agent to refactor it properly.\"\\n<commentary>\\nRemoving `any` and improving type safety is core to what this agent does.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User is building a Vue 3 composable.\\nuser: \"Create a reusable composable for paginated data fetching with TypeScript\"\\nassistant: \"I'll use the grimoire.typescript-coder agent to design this composable with proper types.\"\\n<commentary>\\nFramework-specific TypeScript (Vue Composition API here) is within scope for this agent.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User asks about discriminated unions.\\nuser: \"How do I model a payment result that can succeed or fail with different error types?\"\\nassistant: \"I'll use the grimoire.typescript-coder agent to model this with a discriminated union Result type.\"\\n<commentary>\\nType design questions are core responsibilities of this agent.\\n</commentary>\\n</example>"
 tools: Glob, Grep, Read, Edit, Write, Skill, TaskCreate, TaskGet, TaskUpdate, TaskList, mcp__plugin_context7_context7__resolve-library-id, mcp__plugin_context7_context7__query-docs
-model: sonnet
 memory: project
 ---
 
 You are an expert TypeScript developer with deep mastery of the TypeScript type system, modern language features, and best practices across all major frameworks and runtimes. Your role is to write, refactor, debug, and review high-quality, production-ready TypeScript code. You are platform-agnostic and framework-agnostic — equally fluent in Node.js backends, React, Angular, Vue, Svelte, and any other TypeScript-compatible environment.
 
+You own the implementation end-to-end. You receive a task, read the codebase, make design decisions, and deliver working TypeScript code that fits the project.
+
+## How You Work
+
+1. **Read the task** — understand what needs to be built or changed
+2. **Look up docs when needed** — use Context7 for API reference when working with unfamiliar libraries or APIs
+3. **Break down complex work** — use tasks to track progress on multi-file implementations
+4. **Implement** — write clean, working code that fits the existing codebase
+5. **Verify** — ensure code compiles logically, follows existing patterns, handles edge cases
+
+When the task specifies an approach, follow it. When it doesn't, choose the best one yourself. Make reasonable decisions — don't ask back for clarification on implementation details you can resolve by reading the code.
+
 ## Core Principles
 
 ### Type Safety
@@ -108,3 +119,27 @@ Before presenting code, verify:
 - [ ] Error cases are modeled explicitly
 - [ ] Code compiles cleanly under `strict: true` assumptions
 - [ ] Logic is idiomatic for the target framework (if applicable)
+
+# Persistent Agent Memory
+
+Your `memory: project` setting gives you a persistent memory directory (under `.claude/agent-memory/grimoire.typescript-coder/`). Contents persist across conversations.
+
+Consult your memory files to build on previous experience. When you encounter a recurring mistake or confirm a stable pattern, record it.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — keep it under 200 lines
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for details and link from MEMORY.md
+- Update or remove memories that turn out to be wrong or outdated
+- Organize by topic, not chronologically
+
+What to save:
+- Stable patterns and conventions confirmed across multiple interactions
+- Key architectural decisions, important file paths, and project structure
+- User preferences for workflow, tools, and communication style
+- Solutions to recurring problems and debugging insights
+
+What NOT to save:
+- Session-specific context (current task details, in-progress work)
+- Information that might be incomplete — verify before writing
+- Anything that duplicates existing CLAUDE.md instructions
+- Speculative conclusions from reading a single file

package/packs/ts-pack/grimoire.json

@@ -6,7 +6,7 @@
       "name": "grimoire.typescript-coder",
       "path": "agents/grimoire.typescript-coder.md",
       "description": "Use this agent when the user needs to write, refactor, debug, review, or understand TypeScript code in any environment — Node.js backends, React, Angular, Vue, Svelte, or any other TypeScript-compatible platform. This includes tasks like designing type-safe data models, implementing utility types, handling errors with discriminated unions, refactoring JavaScript to TypeScript, or reviewing TypeScript code for type safety and correctness.",
-      "version": "1.0.0",
+      "version": "2.0.0",
       "file_patterns": ["*.ts", "*.tsx", "*.mts", "*.cts", "*.js", "*.mjs", "*.cjs"]
     }
   ],
@@ -37,6 +37,32 @@
         ],
         "file_paths": ["**/tsconfig*", "**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"]
       }
+    },
+    {
+      "name": "grimoire.unit-testing-typescript",
+      "path": "skills/grimoire.unit-testing-typescript",
+      "description": "TypeScript/JavaScript unit testing specialist. Framework selection, patterns, and best practices for Vitest, Jest, Mocha, and Node test runner. Use when writing tests for .ts/.tsx/.js files, configuring test frameworks, or asking about TypeScript testing patterns, mocking, assertions, async testing.",
+      "version": "1.0.0",
+      "triggers": {
+        "keywords": ["vitest", "jest", "mocha"],
+        "file_extensions": [".ts", ".tsx", ".js", ".jsx"],
+        "patterns": [
+          "write.*test",
+          "add.*test",
+          "create.*test",
+          "test.*coverage",
+          "typescript.*test"
+        ],
+        "file_paths": [
+          "__tests__/**",
+          "**/*.test.ts",
+          "**/*.spec.ts",
+          "**/*.test.js",
+          "**/*.spec.js",
+          "**/vitest.config.*",
+          "**/jest.config.*"
+        ]
+      }
     }
   ]
 }

package/packs/ts-pack/skills/grimoire.unit-testing-typescript/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: grimoire.unit-testing-typescript
+description: "TypeScript/JavaScript unit testing specialist. Framework selection, patterns, and best practices for Vitest, Jest, Mocha, and Node test runner. Use when writing tests for .ts/.tsx/.js files, configuring test frameworks, or asking about TypeScript testing patterns, mocking, assertions, async testing."
+---
+
+# TypeScript Unit Testing
+
+Focused guidance for writing clean, type-safe unit tests in TypeScript and JavaScript projects.
+
+## Framework Selection
+
+### Detection
+
+1. Check existing test files first — always match what the project uses
+2. Check `package.json` devDependencies for `vitest`, `jest`, `mocha`, `@types/mocha`
+3. Check for config files: `vitest.config.ts`, `jest.config.ts`, `.mocharc.*`
+
+### Decision Table
+
+| Condition | Use | Reason |
+|-----------|-----|--------|
+| Project has existing tests | **Match existing** | Consistency is paramount |
+| Vite-based project | **Vitest** | Native integration, fastest |
+| New TypeScript project | **Vitest** | ESM-native, Jest-compatible API, fast |
+| React (CRA) or existing Jest | **Jest** | Mature ecosystem, wide adoption |
+| Legacy project, custom setup | **Mocha + Chai** | Flexible, pluggable |
+| Node.js 20+, minimal deps | **Node test runner** | Built-in, zero dependencies |
+| User explicitly requests | **Requested** | Respect user preference |
+
+## Naming Conventions
+
+Use descriptive strings in `test()` or `it()`:
+
+```typescript
+// Pattern: 'methodName scenario expected behavior'
+test('getUser with invalid id throws NotFound', () => { ... });
+test('calculateTotal with discount applies percentage', () => { ... });
+test('parseConfig with missing required fields throws ValidationError', () => { ... });
+
+// describe blocks for grouping
+describe('OrderService', () => {
+  describe('processOrder', () => {
+    test('with valid order saves and returns id', async () => { ... });
+    test('with invalid order throws ValidationError', async () => { ... });
+  });
+});
+```
+
+## Patterns
+
+### AAA with Vitest/Jest
+
+```typescript
+import { describe, test, expect, vi, beforeEach } from 'vitest';
+
+describe('OrderService', () => {
+  let mockRepo: MockedObject<OrderRepository>;
+  let service: OrderService;
+
+  beforeEach(() => {
+    mockRepo = { save: vi.fn(), findById: vi.fn() };
+    service = new OrderService(mockRepo);
+  });
+
+  test('processOrder with valid order saves and returns id', async () => {
+    // Arrange
+    const order = createValidOrder();
+    mockRepo.save.mockResolvedValue({ id: '123' });
+
+    // Act
+    const result = await service.processOrder(order);
+
+    // Assert
+    expect(result.id).toBe('123');
+    expect(mockRepo.save).toHaveBeenCalledWith(order);
+  });
+
+  test('processOrder with invalid order throws ValidationError', async () => {
+    // Arrange
+    const order = createInvalidOrder();
+
+    // Act & Assert
+    await expect(service.processOrder(order)).rejects.toThrow(ValidationError);
+  });
+});
+```
+
+### Parameterized Tests
+
+```typescript
+// Vitest/Jest
+test.each([
+  { discount: 0, expected: 100.0 },
+  { discount: 10, expected: 90.0 },
+  { discount: 50, expected: 50.0 },
+])('applyDiscount with $discount% returns $expected', ({ discount, expected }) => {
+  expect(applyDiscount(100, discount)).toBe(expected);
+});
+
+// With descriptive names via tagged template
+test.each`
+  input    | expected
+  ${''}    | ${false}
+  ${'abc'} | ${true}
+  ${'a'}   | ${true}
+`('isNonEmpty("$input") returns $expected', ({ input, expected }) => {
+  expect(isNonEmpty(input)).toBe(expected);
+});
+```
+
+### Async Testing
+
+```typescript
+// Async/await (preferred)
+test('fetchUser resolves with user data', async () => {
+  const user = await fetchUser('123');
+  expect(user.name).toBe('Alice');
+});
+
+// Promise rejection
+test('fetchUser with bad id rejects with NotFound', async () => {
+  await expect(fetchUser('bad')).rejects.toThrow(NotFoundError);
+});
+
+// Callback-based (rare, legacy)
+test('legacyFetch calls back with data', (done) => {
+  legacyFetch('123', (err, data) => {
+    expect(err).toBeNull();
+    expect(data.name).toBe('Alice');
+    done();
+  });
+});
+```
+
+### Error Testing
+
+```typescript
+// Sync errors
+test('divide by zero throws', () => {
+  expect(() => divide(1, 0)).toThrow('Cannot divide by zero');
+});
+
+// Async errors
+test('save invalid order rejects with ValidationError', async () => {
+  await expect(service.save(invalidOrder)).rejects.toThrow(ValidationError);
+});
+
+// Error properties
+test('validation error includes field name', async () => {
+  try {
+    await service.save(invalidOrder);
+    expect.fail('should have thrown');
+  } catch (err) {
+    expect(err).toBeInstanceOf(ValidationError);
+    expect((err as ValidationError).field).toBe('items');
+  }
+});
+```
+
+## Mocking
+
+### Vitest (`vi`)
+
+```typescript
+// Function mock
+const mockFn = vi.fn().mockReturnValue(42);
+
+// Module mock
+vi.mock('./emailService', () => ({
+  sendEmail: vi.fn().mockResolvedValue(true),
+}));
+
+// Spy on object method
+const spy = vi.spyOn(console, 'log');
+
+// Timer mocking
+vi.useFakeTimers();
+vi.advanceTimersByTime(1000);
+vi.useRealTimers();
+
+// Mock reset
+beforeEach(() => vi.clearAllMocks());
+```
+
+### Jest (`jest`)
+
+```typescript
+// Same API, replace `vi` with `jest`
+const mockFn = jest.fn().mockReturnValue(42);
+jest.mock('./emailService');
+jest.spyOn(console, 'log');
+jest.useFakeTimers();
+```
+
+### Type-safe mocking
+
+```typescript
+// Use MockedObject for full type safety
+import type { MockedObject } from 'vitest';
+
+let mockRepo: MockedObject<OrderRepository>;
+
+// Or create typed mock factories
+function createMockRepo(overrides?: Partial<OrderRepository>): MockedObject<OrderRepository> {
+  return {
+    save: vi.fn(),
+    findById: vi.fn(),
+    delete: vi.fn(),
+    ...overrides,
+  } as MockedObject<OrderRepository>;
+}
+```
+
+### What NOT to mock
+
+- Value objects, DTOs, plain data structures
+- Pure functions with no side effects
+- The class/module under test itself
+- Simple utility functions
+
+Mock only at system boundaries: APIs, databases, file system, timers, randomness.
+
+## File Conventions
+
+- `*.test.ts` / `*.spec.ts` (co-located or in `__tests__/`)
+- `vitest.config.ts` or `jest.config.ts` for configuration
+- `vitest` or `jest` in `package.json` scripts
+- Shared test utilities in `test/helpers/` or `__tests__/helpers/`
+
+## Package Setup
+
+```bash
+# Vitest
+npm install -D vitest @vitest/coverage-v8
+
+# Jest with TypeScript
+npm install -D jest ts-jest @types/jest
+npx ts-jest config:init
+
+# Optional: testing-library for DOM
+npm install -D @testing-library/react @testing-library/jest-dom
+```
+
+## Authoritative Sources
+
+- Vitest: https://vitest.dev
+- Jest: https://jestjs.io
+- Mocha: https://mochajs.org
+- Kent Beck — Canon TDD: https://tidyfirst.substack.com/p/canon-tdd
+- Martin Fowler — Mocks Aren't Stubs: https://martinfowler.com/articles/mocksArentStubs.html
+
+## Reference Materials
+
+- **[Anti-Patterns](reference/anti-patterns.md)** — Common testing mistakes and how to fix them
+- **[TDD Workflow Patterns](reference/tdd-workflow-patterns.md)** — Red-Green-Refactor, Transformation Priority Premise, when to use TDD