npm - @pennyfarthing/core - Versions diffs - 7.4.1 → 7.5.0 - Mend

@pennyfarthing/core 7.4.1 → 7.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 (890) hide show

package/pennyfarthing-dist/skills/systematic-debugging/SKILL.md DELETED Viewed

@@ -1,390 +0,0 @@
----
-name: systematic-debugging
-description: Systematic debugging approach for isolating and fixing issues. Use when debugging failures, investigating errors, bisecting regressions, or validating fixes.
----
-# Systematic Debugging Skill
-**Purpose:** Guide methodical debugging to find root causes, not just symptoms.
-**Use when:** Bug reports, test failures, unexpected behavior, regressions.
----
-## When to Use This Skill
-- Debugging test failures or unexpected behavior
-- Investigating error messages or stack traces
-- Bisecting to find when a regression was introduced
-- Validating that a fix addresses root cause, not just symptoms
-- Intermittent failures that are hard to reproduce
----
-## The Debugging Cycle
-```
-1. REPRODUCE  → Make the failure happen reliably
-2. ISOLATE    → Narrow down to minimal reproducer
-3. HYPOTHESIZE → Form theory about root cause
-4. TEST       → Validate or invalidate hypothesis
-5. FIX        → Implement solution
-6. VERIFY     → Confirm fix addresses root cause
-```
-### Quick Reference
-| Phase | Question to Answer | Output |
-|-------|-------------------|--------|
-| REPRODUCE | Can I make it fail consistently? | Reliable reproduction steps |
-| ISOLATE | What's the minimal code/input that triggers it? | Minimal reproducer |
-| HYPOTHESIZE | What could cause this behavior? | Ranked list of theories |
-| TEST | Does evidence support my theory? | Confirmed or refuted hypothesis |
-| FIX | What's the minimal change to fix it? | Working code |
-| VERIFY | Does the fix address root cause? | Regression test |
----
-## Phase 1: REPRODUCE
-**Goal:** Make the failure happen reliably.
-### Steps
-1. **Document exact error** - Copy the full error message, stack trace, logs
-2. **Capture environment** - Versions, configuration, system state
-3. **Create reproduction steps** - Exact commands/actions to trigger
-4. **Test reproduction** - Run it 3+ times to confirm consistency
-### For Intermittent Failures
-| Pattern | Approach |
-|---------|----------|
-| Race condition | Add delays, run in tight loop, stress test |
-| State-dependent | Reset to clean state, document preconditions |
-| Environment-specific | Compare working vs failing environments |
-| Timing-dependent | Add timestamps, check for timeouts |
-### Example
-```bash
-# Document the failure
-$ npm test -- -t "user authentication"
-# Error: Expected 200 but got 401
-# Capture environment
-$ node --version  # v18.17.0
-$ npm --version   # 9.6.7
-# Reproduction steps
-1. Start fresh database: docker-compose down -v && docker-compose up -d
-2. Run: npm test -- -t "user authentication"
-3. Observe: 401 error on third test
-# Verify reproduction
-$ npm test -- -t "user authentication"  # Fails
-$ npm test -- -t "user authentication"  # Fails
-$ npm test -- -t "user authentication"  # Fails - consistent!
-```
----
-## Phase 2: ISOLATE
-**Goal:** Narrow down to the smallest code/input that triggers the bug.
-### Techniques
-#### Binary Search (Code)
-```
-1. Find a known-good commit
-2. Find the failing commit
-3. git bisect between them
-4. Each step: test, mark good/bad
-5. Arrive at first bad commit
-```
-```bash
-git bisect start
-git bisect bad HEAD
-git bisect good v1.2.0
-# Git checks out middle commit
-npm test -- -t "failing test"
-git bisect bad  # or good
-# Repeat until found
-git bisect reset
-```
-#### Minimal Reproducer
-1. Start with failing test/code
-2. Remove components one at a time
-3. Stop when removal fixes the bug
-4. The last removed component is involved
-#### Variable Elimination
-| Remove | Still fails? | Conclusion |
-|--------|--------------|------------|
-| External API calls | Yes | Not API-related |
-| Database queries | No | Database-related |
-| Specific table | Yes | Not that table |
-| Auth middleware | No | Auth is involved |
-### Example
-```typescript
-// Full failing code
-async function createUser(data) {
-  validateInput(data);
-  const hash = await hashPassword(data.password);
-  const user = await db.insert({ ...data, password: hash });
-  await sendWelcomeEmail(user.email);
-  return user;
-}
-// Minimal reproducer (isolated the issue)
-async function createUser(data) {
-  const user = await db.insert(data);  // Fails here!
-  return user;
-}
-// Conclusion: Issue is in db.insert, not validation/email
-```
----
-## Phase 3: HYPOTHESIZE
-**Goal:** Form testable theories about root cause.
-### Common Root Causes
-| Category | Examples |
-|----------|----------|
-| State | Uninitialized variable, stale cache, leftover data |
-| Timing | Race condition, timeout, async ordering |
-| Input | Edge case, null/undefined, empty collection, boundary |
-| Environment | Missing env var, wrong version, config mismatch |
-| Logic | Off-by-one, wrong operator, incorrect condition |
-### Hypothesis Formation
-1. **Read the error message carefully** - Often tells you exactly what's wrong
-2. **Check recent changes** - `git log --oneline -20`, `git diff HEAD~5`
-3. **Consider edge cases** - What if null? Empty? Max value?
-4. **Look for patterns** - When does it fail vs succeed?
-### Rank Hypotheses
-```
-Hypothesis 1 (HIGH): Database connection timing out
-- Evidence: Error mentions timeout, happens under load
-- Test: Check connection pool settings
-Hypothesis 2 (MEDIUM): Invalid input not validated
-- Evidence: Stack trace shows null pointer in parser
-- Test: Add input validation logging
-Hypothesis 3 (LOW): Bug in library
-- Evidence: Nothing obvious in our code
-- Test: Check library issues, try downgrade
-```
----
-## Phase 4: TEST
-**Goal:** Validate or invalidate each hypothesis.
-### Testing Approaches
-| Approach | When to Use |
-|----------|-------------|
-| Add logging | Need to see values at runtime |
-| Debugger breakpoint | Need to inspect state interactively |
-| Unit test | Can isolate the specific function |
-| Print statements | Quick check in specific location |
-| Assertion | Verify assumption holds |
-### Logging Strategy
-```typescript
-// Add strategic logging
-console.log('[DEBUG] Input:', JSON.stringify(data));
-console.log('[DEBUG] Before DB call, user:', user?.id);
-console.log('[DEBUG] After DB call, result:', result);
-console.log('[DEBUG] Query took:', endTime - startTime, 'ms');
-```
-### Hypothesis Testing
-```
-HYPOTHESIS: Connection pool exhausted under load
-TEST 1: Check pool stats
-> db.pool.stats()
-{ active: 50, idle: 0, waiting: 12 }  // Pool full!
-TEST 2: Increase pool size
-> config.pool.max = 100
-> Rerun test
-> PASS
-CONCLUSION: Hypothesis confirmed. Pool too small.
-```
-### When Hypothesis is Wrong
-If evidence doesn't support your theory:
-1. Don't force-fit the evidence
-2. Return to HYPOTHESIZE phase
-3. Form new theory based on new observations
-4. Repeat until you find the cause
----
-## Phase 5: FIX
-**Goal:** Implement the minimal change that fixes the issue.
-### Fix Principles
-1. **Fix the root cause, not the symptom**
-   - BAD: Add try/catch to hide the error
-   - GOOD: Fix why the error occurs
-2. **Minimal change**
-   - Change only what's necessary
-   - Don't refactor while fixing bugs
-3. **One fix per bug**
-   - Don't bundle unrelated changes
-   - Makes it clear what fixed what
-### Fix Template
-```typescript
-// BEFORE: Bug - pool exhaustion under load
-const pool = new Pool({ max: 10 });
-// AFTER: Fix - increase pool size based on expected load
-const pool = new Pool({
-  max: 50,  // Increased from 10 to handle peak load
-  idleTimeoutMillis: 30000,
-});
-```
----
-## Phase 6: VERIFY
-**Goal:** Confirm the fix addresses root cause and doesn't break anything else.
-### Verification Checklist
-- [ ] Original reproduction steps now pass
-- [ ] New test case covers the bug (regression test)
-- [ ] Existing tests still pass
-- [ ] Fix doesn't introduce new issues
-- [ ] Fix addresses root cause, not just symptom
-### Write a Regression Test
-```typescript
-// This test should have caught the bug
-test('handles concurrent requests without pool exhaustion', async () => {
-  const requests = Array(100).fill(null).map(() => api.createUser());
-  const results = await Promise.all(requests);
-  expect(results.every(r => r.status === 201)).toBe(true);
-});
-```
-### Symptom vs Root Cause Check
-Ask yourself:
-- "Would this bug happen again in a different form?"
-- "Did I fix WHY it happened, or just WHAT happened?"
-| Fix | Symptom or Root Cause? |
-|-----|------------------------|
-| Add null check | Symptom (why is it null?) |
-| Initialize variable properly | Root cause |
-| Increase timeout | Symptom (why is it slow?) |
-| Fix N+1 query | Root cause |
----
-## Debugging Anti-Patterns
-### What NOT to Do
-| Anti-Pattern | Why It's Bad | Instead |
-|--------------|--------------|---------|
-| Random changes | Introduces new bugs, wastes time | Follow the cycle |
-| Fix without reproducing | Can't verify fix works | Always reproduce first |
-| Blame external factors | Delays finding real cause | Assume it's your code |
-| Skip verification | Bug may not be fixed | Always verify |
-| Big refactor as "fix" | Hides what actually fixed it | Minimal changes |
-### Common Traps
-1. **Confirmation bias** - Looking for evidence that supports your theory
-2. **Premature optimization** - Fixing performance before correctness
-3. **Tunnel vision** - Fixating on one hypothesis
-4. **Solution jumping** - Skipping to fix before understanding
----
-## Quick Debugging Commands
-### Git Bisect (Find Regression)
-```bash
-git bisect start
-git bisect bad                 # Current commit is bad
-git bisect good v1.0.0         # Known good commit
-# Run test, then:
-git bisect good  # or bad
-# Repeat until found
-git bisect reset
-```
-### Find Recent Changes
-```bash
-# What changed recently?
-git log --oneline -20
-git diff HEAD~5
-# Who changed this file?
-git blame path/to/file.ts
-# When did this line change?
-git log -p -S "problematic code" -- path/to/file.ts
-```
-### Check Running Processes
-```bash
-# What's using resources?
-ps aux | grep node
-lsof -i :3000
-# Check memory/CPU
-top -l 1 | head -20
-```
----
-## Integration with Other Skills
-| Skill | How It Complements |
-|-------|-------------------|
-| `/testing` | Run tests to verify fixes |
-| `/dev-patterns` | Avoid common pitfalls |
-| `/agentic-patterns` | ReAct pattern for systematic investigation |
----
-**Remember:** Debugging is detective work. Follow the evidence, test your theories, and fix the root cause. Rushing leads to band-aid fixes that break later.

package/pennyfarthing-dist/skills/testing/SKILL.md DELETED Viewed

@@ -1,99 +0,0 @@
----
-name: testing
-description: Test commands and patterns for TDD workflow. This skill should be used when running tests, debugging test failures, setting up test infrastructure, or writing new tests. Provides framework-agnostic patterns that projects customize.
----
-# Testing Skill
-## When to Use This Skill
-- Running tests (backend, frontend, or all)
-- Debugging test failures
-- Setting up test containers/infrastructure
-- Writing new tests
-- Pre-commit verification
-- Understanding TDD workflow
-## TDD Workflow (RED → GREEN → REFACTOR)
-```
-1. TEA writes failing tests (RED)
-2. Dev implements code to pass tests (GREEN)
-3. Dev refactors while keeping tests GREEN
-4. Reviewer validates quality
-```
-## Quick Reference
-```bash
-# Setup test infrastructure (run once per session)
-# Project-specific: check your justfile or package.json
-# Run all tests
-just test              # If using just
-npm test               # If using npm
-go test ./...          # If using Go directly
-# Run specific test patterns
-just test-api -run "TestName"     # Go pattern
-npm test -- -t "test name"        # Jest/Vitest pattern
-```
-## Test Command Patterns
-### Go (Backend)
-```bash
-# Run all tests
-go test ./...
-# Run tests in specific package
-go test ./internal/handlers
-# Run tests matching pattern
-go test -run "TestCreate" ./...
-# Verbose output
-go test -v ./internal/handlers
-# With coverage
-go test -cover ./...
-```
-### Node/React (Frontend)
-```bash
-# Run all tests (Vitest)
-npm test
-# Run tests matching pattern
-npm test -- -t "button"
-# Watch mode
-npm test -- --watch
-# Coverage
-npm test -- --coverage
-```
-## Test File Naming Conventions
-| Type | Go Pattern | TypeScript Pattern |
-|------|------------|-------------------|
-| Unit test | `*_test.go` | `*.test.ts`, `*.test.tsx` |
-| Integration | `*_integration_test.go` | `*.integration.test.ts` |
-| E2E | N/A | `*.e2e.test.ts` |
-## Reference Documentation
-- **Troubleshooting:** See `references/troubleshooting.md`
-- **TDD Policy:** See `references/tdd-policy.md` (project-specific)
-- **Backend Patterns:** See `references/backend-patterns.md` (project-specific)
-- **Frontend Patterns:** See `references/frontend-patterns.md` (project-specific)
-## Project Customization
-Projects should create their own testing skill in `.claude/project/skills/testing/` with:
-- Project-specific test commands
-- Custom patterns and conventions
-- Infrastructure setup instructions

package/pennyfarthing-dist/skills/testing/references/troubleshooting.md DELETED Viewed

@@ -1,124 +0,0 @@
-# Test Troubleshooting Guide
-## Tests Timing Out
-```bash
-# Ensure test infrastructure is running
-just test-setup        # Or project-specific setup command
-# Check container status
-docker ps
-# Increase timeout if needed
-go test -timeout 60s ./...
-```
-## "No Tests to Run" Message
-### Go Tests
-The `-run` flag filters by **test function name**, not by file or domain:
-- `-run "User"` matches `TestUserCreate` but NOT `TestCreateAccount`
-- The pattern is a regex, case-sensitive
-```bash
-# Run ALL tests in a package (no name filter)
-go test ./internal/handlers/...
-# Run tests with "Create" in name in specific package
-go test -run "Create" ./internal/handlers
-```
-### JavaScript/TypeScript Tests
-The `-t` flag filters by test description:
-```bash
-# Run tests matching description
-npm test -- -t "should create user"
-# Run all tests in a file
-npm test -- path/to/file.test.ts
-```
-## Case Sensitivity
-### Go
-- `-run "User"` - Correct (matches TestUser...)
-- `-run "user"` - Won't match (Go regex is case-sensitive)
-### Jest/Vitest
-- `-t "user"` - Case-insensitive by default
-## Package/Path Format
-### Go
-```bash
-./internal/handlers      # Correct - relative with ./
-internal/handlers        # May not work without ./
-./internal/handlers/...  # Include subpackages
-```
-### Node
-```bash
-src/components           # Relative path
-./src/components         # Also works
-```
-## Tests Passing Locally but Failing in CI
-1. **Environment differences** - Check env vars
-2. **Race conditions** - Run tests multiple times locally
-3. **Database state** - Ensure clean state between tests
-```bash
-# Run full test suite to catch integration issues
-just test
-# Run tests with race detection (Go)
-go test -race ./...
-```
-## Container Issues
-```bash
-# Restart test containers
-docker-compose -f docker-compose.test.yml down
-docker-compose -f docker-compose.test.yml up -d
-# Check container logs
-docker logs <container-name>
-# Verify connectivity
-docker exec <container-name> pg_isready  # Postgres
-docker exec <container-name> redis-cli ping  # Redis
-```
-## Database Connection Errors
-```bash
-# Check environment variables
-echo $TEST_DATABASE_URL
-# Verify database is accepting connections
-psql $TEST_DATABASE_URL -c "SELECT 1"
-```
-## Common Patterns
-### Flaky Tests
-1. Check for timing dependencies
-2. Look for shared state between tests
-3. Ensure proper cleanup in teardown
-4. Consider using test isolation
-### Memory Issues
-```bash
-# Run with memory limit (Go)
-go test -memprofile mem.out ./...
-# Check for goroutine leaks
-go test -race ./...
-```