@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/testing/VITEST_UNIT_TEST_PATTERNS.md

@@ -0,0 +1,75 @@
+---
+name: vitest-unit-test-patterns
+category: testing
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [testing, vitest, unit-tests, mocking, coverage]
+difficulty: easy
+---
+
+# Vitest Unit Test Patterns
+
+## Problem
+
+Unit tests are written inconsistently — some test implementation details instead of behavior, mocks leak between tests, and coverage reports show quantity but not quality.
+
+## Solution Pattern
+
+Structure unit tests with the AAA pattern (Arrange-Act-Assert), mock at boundaries, and test behavior not implementation.
+
+## Code Example
+
+```typescript
+// Before (testing implementation)
+test('calls setUser', () => {
+  const spy = vi.spyOn(store, 'setUser');
+  login('admin', 'pass');
+  expect(spy).toHaveBeenCalledWith({ name: 'admin' });
+});
+
+// After (testing behavior)
+test('successful login stores user and redirects', async () => {
+  // Arrange
+  const mockApi = vi.fn().mockResolvedValue({ user: { name: 'admin' } });
+
+  // Act
+  const result = await login('admin', 'pass', { api: mockApi });
+
+  // Assert
+  expect(result.user.name).toBe('admin');
+  expect(result.redirectTo).toBe('/dashboard');
+});
+```
+
+## Key Patterns
+
+### 1. Mock at Boundaries
+Mock: APIs, databases, file system, external services.
+Don't mock: internal functions, utilities, pure logic.
+
+### 2. Test Naming Convention
+```
+test('{action} should {expected result} when {condition}')
+```
+
+### 3. Isolation
+```typescript
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.clearAllTimers(); });
+```
+
+### 4. Coverage That Matters
+- Branch coverage > line coverage
+- Test error paths, not just happy paths
+- Edge cases: empty arrays, null, undefined, max values
+
+## When to Use
+- All new functions and modules
+- After fixing a bug (write the test that would have caught it)
+- During refactoring (tests prove behavior is preserved)
+
+## When NOT to Use
+- Simple getters/setters with no logic
+- Configuration files
+- Generated code

package/skills-library/testing/playwright-api-security-tests.md

@@ -0,0 +1,202 @@
+---
+name: playwright-api-security-tests
+category: testing
+version: 1.0.0
+contributed: 2026-02-19
+contributor: my-other-project
+last_updated: 2026-02-19
+tags: [playwright, security, e2e-testing, api-testing, regression]
+difficulty: easy
+usage_count: 0
+success_rate: 100
+---
+
+# Playwright API Security Test Suite
+
+## Problem
+
+After implementing security fixes (SQL injection prevention, path traversal, auth hardening, XSS sanitization, etc.), there's no automated way to verify the fixes work and prevent regressions. Manual curl testing is error-prone and not repeatable.
+
+## Solution Pattern
+
+Use Playwright's `request` API fixture (not browser-based) for fast, headless security regression tests. Tests run against a live API server and verify HTTP status codes and response shapes without needing a browser.
+
+### Key Design Decisions
+
+1. **API-only tests** — Use `request` fixture, not `page`. Security tests don't need a browser.
+2. **Defense-in-depth assertions** — Accept multiple valid status codes (e.g., `[400, 401]`) when auth blocks before validation.
+3. **No test credentials** — Test unauthenticated attack vectors. Auth-protected endpoints returning 401 IS the security proof.
+4. **Fast execution** — 26 tests in 2.5 seconds.
+
+## Code Example
+
+### Setup: Minimal Config (no webServer)
+
+```typescript
+// playwright-security.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  workers: 1,
+  reporter: 'list',
+  use: { baseURL: 'http://localhost:5000' },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});
+```
+
+### Test Categories Template
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+// 1. PATH TRAVERSAL
+test.describe('Path Traversal Prevention', () => {
+  test('Rejects ../ in URL params', async ({ request }) => {
+    const res = await request.delete('/api/media/..%2F..%2Fserver.js');
+    expect([400, 401]).toContain(res.status());
+  });
+
+  test('Rejects encoded backslash', async ({ request }) => {
+    const res = await request.delete('/api/media/..%5C..%5Cserver.js');
+    expect([400, 401]).toContain(res.status());
+  });
+});
+
+// 2. FILE UPLOAD ALLOWLIST
+test.describe('File Upload Security', () => {
+  test('Rejects dangerous file types', async ({ request }) => {
+    const res = await request.post('/api/upload', {
+      multipart: {
+        file: {
+          name: 'shell.php',
+          mimeType: 'application/x-php',
+          buffer: Buffer.from('<?php echo "test"; ?>'),
+        },
+      },
+    });
+    expect([400, 401]).toContain(res.status());
+  });
+});
+
+// 3. AUTH ENFORCEMENT
+test.describe('Auth Protection', () => {
+  test('Protected endpoint rejects unauthenticated', async ({ request }) => {
+    const res = await request.post('/api/payments/refund', {
+      data: { order_id: 'test', amount: 50 },
+    });
+    expect(res.status()).toBe(401);
+  });
+
+  test('Rejects invalid JWT', async ({ request }) => {
+    const res = await request.post('/api/payments/refund', {
+      headers: { Authorization: 'Bearer invalid-token' },
+      data: { order_id: 'test', amount: 50 },
+    });
+    expect(res.status()).toBe(401);
+  });
+});
+
+// 4. PII EXPOSURE
+test.describe('PII Protection', () => {
+  test('Public endpoint hides sensitive fields', async ({ request }) => {
+    const res = await request.get('/api/public-resource/some-token');
+    if (res.status() === 200) {
+      const body = await res.json();
+      expect(body.data).not.toHaveProperty('email');
+      expect(body.data).not.toHaveProperty('student_email');
+    }
+  });
+});
+
+// 5. INPUT VALIDATION
+test.describe('Input Validation', () => {
+  test('Rejects extreme values', async ({ request }) => {
+    const res = await request.patch('/api/payments/update-intent', {
+      data: { payment_intent_id: 'pi_fake', amount: 999999 },
+    });
+    expect([400, 500]).toContain(res.status());
+  });
+
+  test('Rejects negative values', async ({ request }) => {
+    const res = await request.patch('/api/payments/update-intent', {
+      data: { payment_intent_id: 'pi_fake', amount: -50 },
+    });
+    expect([400, 500]).toContain(res.status());
+  });
+});
+
+// 6. RATE LIMITING
+test.describe('Rate Limiting', () => {
+  test('Triggers on rapid requests', async ({ request }) => {
+    const statuses: number[] = [];
+    for (let i = 0; i < 25; i++) {
+      const res = await request.get(`/api/limited-endpoint/token-${i}`);
+      statuses.push(res.status());
+    }
+    const allValid = statuses.every(s => [200, 404, 429].includes(s));
+    expect(allValid).toBe(true);
+  });
+});
+
+// 7. SQL INJECTION
+test.describe('SQL Injection Prevention', () => {
+  test('Sort param injection returns safe defaults', async ({ request }) => {
+    const res = await request.get('/api/items?sort=name;DROP TABLE users;--');
+    expect([200, 401]).toContain(res.status());
+    if (res.status() === 200) {
+      const body = await res.json();
+      expect(body.success).toBe(true); // Returns normal data, not error
+    }
+  });
+});
+
+// 8. BASELINE
+test.describe('Health Baseline', () => {
+  test('Server is responsive', async ({ request }) => {
+    const res = await request.get('/api/health');
+    expect(res.status()).toBe(200);
+  });
+});
+```
+
+## Implementation Steps
+
+1. Install Playwright: `npm init playwright@latest` in client directory
+2. Create `e2e/security-hardening.spec.ts` with test categories above
+3. Adapt endpoint URLs and expected responses to your API
+4. Run with server already started: `npx playwright test e2e/security-hardening.spec.ts --project=chromium`
+5. Add to CI pipeline (start server, run tests, check exit code)
+
+## When to Use
+
+- After any security audit or hardening sprint
+- As a regression suite run before deployments
+- When onboarding security fixes to verify they work
+- In CI/CD pipelines alongside unit tests
+
+## When NOT to Use
+
+- For testing UI-level XSS (use browser-based Playwright tests with `page`)
+- For penetration testing (use dedicated tools like Burp Suite, OWASP ZAP)
+- For load/stress testing (use k6, Artillery, or similar)
+- If the API isn't running (these are integration tests, not unit tests)
+
+## Common Mistakes
+
+- Using the default `playwright.config.ts` with `webServer` — if your dev command starts both Vite AND Node, it may timeout. Use a separate config without `webServer`.
+- Expecting exact status codes when auth runs before validation — use `[400, 401]` to accept either.
+- Forgetting that `request` fixture shares no cookies — each test is unauthenticated by default.
+- Running in parallel (`fullyParallel: true`) — rate limiting tests may interfere with each other.
+
+## Related Skills
+
+- [sql-injection-prevention-postgresjs](../security/sql-injection-prevention-postgresjs.md) - The fixes these tests verify
+
+## References
+
+- Playwright API Testing: https://playwright.dev/docs/api-testing
+- OWASP Testing Guide: https://owasp.org/www-project-web-security-testing-guide/
+- Contributed from: my-other-project (Feb 2026 security audit, 26/26 tests passing)

package/skills-library/toolbox/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: toolbox
+description: Complete reference of available tools, plugins, marketplaces, and workflow commands
+user-invocable: false
+---
+
+# Available Tools & Resources Reference
+
+**Full reference file:** `C:\Users\FirstName\.claude\plugins\warrior-workflow\skills-library\AVAILABLE_TOOLS_REFERENCE.md`
+
+## Plugin Marketplaces (16 Total)
+
+| Category | Marketplaces |
+|----------|-------------|
+| **Official** | claude-plugins-official, superpowers-marketplace, anthropic-agent-skills |
+| **Workflows** | claude-code-workflows (107 skills), claude-code-plugins-plus, compounding-engineering |
+| **Specialized** | n8n-mcp (1,084 nodes), n8n-skills, ralph-wiggum (autonomous loops), hcp-terraform-skills |
+| **Community** | awesome-claude-code-plugins, awesome-claude-skills, cc-marketplace, mag-claude-plugins, thedotmack |
+
+## Dominion Flow System
+
+**Location:** `~/.claude/plugins/dominion-flow/` | **Version:** 3.2.0
+
+| Command | Purpose |
+|---------|---------|
+| `/fire-dashboard` | Project status & progress |
+| `/fire-1a-new` | Initialize new project |
+| `/fire-2-plan N` | Create phase plan |
+| `/fire-3-execute N` | Breath-based parallel execution |
+| `/fire-4-verify` | Goal-backward verification |
+| `/fire-5-handoff` | Create session handoff |
+| `/fire-6-resume` | Resume from handoff |
+| `/fire-debug` | Systematic debugging |
+| `/fire-loop` | Self-iterating autonomous loop |
+
+**Key Concepts:** CONSCIENCE.md (living memory), Breath-based execution, Must-haves verification, Checkpoints
+
+## Ralph Wiggum Loops
+
+Self-iterating autonomous loops until success criteria met:
+```bash
+/ralph-loop "Build X with tests. Output DONE when all tests pass." --completion-promise "DONE" --max-iterations 50
+```
+
+## Installed Official Plugins
+
+| Category | Plugins |
+|----------|---------|
+| **Productivity** | playwright, github, gitlab, greptile |
+| **Integrations** | figma, sentry, vercel, firebase, stripe, supabase, context7 |
+| **Project Mgmt** | atlassian, asana, linear, slack |
+| **Development** | hookify, plugin-dev, agent-sdk-dev, frontend-design, code-review, feature-dev, pr-review-toolkit, commit-commands |
+
+## Key Superpowers Skills
+
+Use the `Skill` tool to invoke:
+- `superpowers:brainstorming` - Before ANY creative work
+- `superpowers:test-driven-development` - When implementing features
+- `superpowers:systematic-debugging` - For bug investigation
+- `superpowers:verification-before-completion` - Before claiming done
+- `superpowers:requesting-code-review` - After completing tasks
+
+## WARRIOR Workflow
+
+| Command | Purpose |
+|---------|---------|
+| `/warrior-handoff` | Create comprehensive handoff |
+| `/warrior-review` | Conduct code review |
+| `/warrior-validation` | Verify work complete |
+
+**Skills Library:** `~/.claude/plugins/warrior-workflow/skills-library/`
+- methodology/, complexity-metrics/, ecommerce/, integrations/
+- video-media/, deployment-security/, database-solutions/, form-solutions/
+- advanced-features/, automation/, document-processing/, patterns-standards/
+
+## Swarm Mode (Agent Teams) - ENABLED
+
+Multi-agent swarm mode is enabled globally (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`).
+
+**How to trigger:** User asks for a team, e.g., "Use a team of specialists for this."
+
+**Controls:** `Shift+Up/Down` (select teammate), `Enter` (view session), `Ctrl+T` (task list), `Shift+Tab` (delegate-only mode)
+
+**Skill Reference:** `~/.claude/plugins/warrior-workflow/skills-library/automation/CLAUDE_CODE_SWARM_MODE.md`

package/skills-library/toolbox/code-graph-and-web-scraping-mcps.md

@@ -0,0 +1,237 @@
+---
+name: code-graph-and-web-scraping-mcps
+category: toolbox
+version: 1.0.0
+contributed: 2026-02-23
+contributor: Power-Flow
+last_updated: 2026-02-23
+tags: [mcp, refactoring, code-analysis, web-scraping, neo4j, graph-database, firecrawl, codegraphcontext]
+difficulty: easy
+usage_count: 0
+success_rate: 100
+---
+
+# Code Graph & Web Scraping MCP Servers for Refactoring
+
+## Overview
+
+Two MCP servers installed for deep code analysis and web research during refactoring:
+
+1. **CodeGraphContext (CGC)** — Indexes codebases into a Neo4j graph database. Provides function call relationships, class hierarchies, dead code detection, dependency tracking, and call chain analysis via MCP tools.
+
+2. **Firecrawl** — Web scraping with JavaScript rendering, anti-bot handling, and proxy rotation. Scrape docs, search the web, map site URLs, and run cloud browser sessions.
+
+## Installation Status
+
+### CodeGraphContext
+- **Installed:** `codegraphcontext==0.2.5` via Python 3.12
+- **Binary:** `C:\Users\FirstName\AppData\Local\Programs\Python\Python312\Scripts\cgc.exe`
+- **Database:** Neo4j 5 Community (Docker: `neo4j-cgc`, ports 7474/7687)
+- **Credentials:** `neo4j` / `codegraph123`
+- **Config:** `C:\Users\FirstName\.codegraphcontext\.env`
+- **MCP:** Added to user scope in `~/.claude.json`
+- **Languages:** Python, JavaScript, TypeScript, Java, C/C++, C#, Go, Rust, Ruby, PHP, Swift, Kotlin
+
+### Firecrawl
+- **CLI Installed:** `firecrawl-cli@1.6.2` (global npm)
+- **MCP:** Added to user scope in `~/.claude.json` (via `npx -y firecrawl-mcp`)
+- **Auth:** Requires API key — run `firecrawl login --browser` to authenticate
+- **Free tier:** Available at https://firecrawl.dev/app/api-keys
+
+## When to Use for Refactoring
+
+### CodeGraphContext — Use When:
+
+- **Understanding call chains:** "What functions call `processPayment()`?" → `cgc find callers processPayment`
+- **Dead code detection:** "What functions are never called?" → `cgc analyze dead-code`
+- **Dependency mapping:** "What imports does this module use?" → `cgc analyze dependencies`
+- **Class hierarchy:** "What extends BaseController?" → `cgc find subclasses BaseController`
+- **Impact analysis:** "If I change this function, what breaks?" → `cgc analyze impact functionName`
+- **Cyclomatic complexity:** "What are the most complex functions?" → `cgc analyze complexity`
+- **Before large refactors:** Index first, query the graph, then plan changes with full dependency knowledge
+
+### Firecrawl — Use When:
+
+- **Reading library docs:** Scrape latest API docs for libraries being refactored into
+- **Competitive analysis:** Scrape competitor implementations for design patterns
+- **Migration guides:** Extract migration guides from framework websites
+- **Stack Overflow research:** Search and scrape specific solutions
+- **Changelog analysis:** Scrape release notes to understand breaking changes
+
+## Quick Reference Commands
+
+### CGC CLI (Direct Usage)
+
+```bash
+# Set alias for convenience
+CGC="C:/Users/FirstName/AppData/Local/Programs/Python/Python312/Scripts/cgc.exe"
+
+# Index a codebase
+$CGC index "c:/path/to/my-other-project"
+
+# List indexed repos
+$CGC list
+
+# Find function callers
+$CGC find callers <function_name>
+
+# Find function callees (what does this call?)
+$CGC find callees <function_name>
+
+# Find elements
+$CGC find name <exact_name>             # Exact match
+$CGC find pattern <substring>           # Substring match (e.g., "Enrollment")
+$CGC find type Function                 # All functions
+$CGC find variable <var_name>           # Variable lookup
+$CGC find content "search text"         # Full-text search in source/docstrings
+$CGC find decorator <decorator_name>    # Functions with specific decorator
+$CGC find argument <param_name>         # Functions taking specific argument
+
+# Analyze
+$CGC analyze callers <function_name>    # What calls this function?
+$CGC analyze calls <function_name>      # What does this function call?
+$CGC analyze chain <func1> <func2>      # Call chain between two functions
+$CGC analyze deps <module_name>         # Module dependencies/imports
+$CGC analyze tree <class_name>          # Inheritance hierarchy
+$CGC analyze dead-code                  # Unused functions/classes
+$CGC analyze complexity                 # Cyclomatic complexity
+$CGC analyze overrides <function_name>  # Implementations across classes
+$CGC analyze variable <var_name>        # Where defined and used
+
+# Custom Cypher query
+$CGC query "MATCH (f:Function)-[:CALLS]->(g:Function) RETURN f.name, g.name LIMIT 20"
+
+# Watch for changes (auto-update graph)
+$CGC watch "c:/path/to/my-other-project"
+
+# Doctor/diagnostics
+$CGC doctor
+
+# Delete indexed repo
+$CGC delete <repo_name>
+
+# Stats
+$CGC stats
+```
+
+### Firecrawl CLI (Direct Usage)
+
+```bash
+# Authenticate (one-time)
+firecrawl login --browser
+
+# Search the web
+firecrawl search "react query migration guide v5"
+
+# Scrape a page to markdown
+firecrawl scrape https://docs.example.com/migration
+
+# Map all URLs on a site
+firecrawl map https://docs.example.com
+
+# Check status/credits
+firecrawl --status
+```
+
+### MCP Tools (Available in Claude Code after restart)
+
+**CodeGraphContext MCP provides:**
+- Query function definitions and locations
+- Caller/callee relationship queries
+- Class hierarchy traversal
+- Call chain analysis
+- Dead code detection
+- Cyclomatic complexity analysis
+- Custom Cypher queries against the code graph
+
+**Firecrawl MCP provides:**
+- `firecrawl_scrape` — Extract markdown from any URL
+- `firecrawl_search` — Web search with optional scraping
+- `firecrawl_map` — Discover all URLs on a website
+- `firecrawl_crawl` — Extract content from entire websites
+- `firecrawl_extract` — Structured data extraction
+
+## Refactoring Workflow Pattern
+
+```
+1. INDEX the target codebase with CGC
+   cgc index /path/to/project
+
+2. ANALYZE the area you're refactoring
+   cgc find callers <function>      # Who uses this?
+   cgc analyze impact <function>    # What breaks if I change it?
+   cgc analyze dead-code            # What can I safely delete?
+
+3. RESEARCH with Firecrawl (if migrating libraries)
+   firecrawl search "library-name migration guide"
+   firecrawl scrape <docs-url>
+
+4. PLAN the refactor using graph knowledge
+   - You know all callers → safe rename/signature change
+   - You know dead code → safe deletion
+   - You know call chains → understand blast radius
+
+5. EXECUTE the refactor
+   - Use the graph to verify no broken references
+   - Re-index after changes to validate
+
+6. VERIFY
+   cgc analyze dead-code            # No new dead code introduced?
+   cgc stats                        # Graph still consistent?
+```
+
+## Prerequisites
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| Python 3.12 | Installed | `C:\Users\FirstName\AppData\Local\Programs\Python\Python312` |
+| Node.js | Installed | Global npm packages available |
+| Docker | Running | For Neo4j container |
+| Neo4j container | Running | `docker start neo4j-cgc` if stopped |
+| Firecrawl API key | PENDING | Run `firecrawl login --browser` |
+
+## Verified Working (2026-02-23)
+
+- **Neo4j Docker:** Running, connected, healthy
+- **CGC indexing my-other-project:** 14,900+ variables, 5,306 functions, 1,032 files, 775 modules, 82 directories, 12 classes indexed
+- **CGC find pattern:** Returns results with file paths, line numbers, and types
+- **CGC analyze:** callers, calls, chain, dead-code, complexity all available
+- **MCP server:** Configured in `~/.claude.json` (user scope) — available after Claude Code restart
+- **Firecrawl CLI:** v1.6.2 installed globally, auth pending
+
+## Troubleshooting
+
+### Neo4j not connecting
+```bash
+# Check if container is running
+docker ps --filter name=neo4j-cgc
+# Start if stopped
+docker start neo4j-cgc
+# Check doctor
+cgc doctor
+```
+
+### Firecrawl auth issues
+```bash
+# Re-authenticate
+firecrawl login --browser
+# Or set env var
+export FIRECRAWL_API_KEY=fc-YOUR-KEY
+```
+
+### CGC not in PATH
+Use full path: `C:\Users\FirstName\AppData\Local\Programs\Python\Python312\Scripts\cgc.exe`
+Or add Python Scripts to PATH.
+
+## Related Skills
+
+- [AVAILABLE_TOOLS_REFERENCE.md](../AVAILABLE_TOOLS_REFERENCE.md) — Full tool inventory
+- [power-map-codebase](../../commands/fire-map-codebase.md) — Parallel codebase analysis
+- [parallel-explore](../../commands/parallel-explore.md) — Multi-agent code exploration
+
+## References
+
+- [CodeGraphContext GitHub](https://github.com/CodeGraphContext/CodeGraphContext) — 773 stars, 12 language support
+- [Firecrawl GitHub](https://github.com/firecrawl/firecrawl-mcp-server) — Official MCP server
+- [Firecrawl Claude Plugin](https://github.com/firecrawl/firecrawl-claude-plugin) — Native plugin
+- Contributed from: Dominion Flow tooling setup session (2026-02-23)