@qball-inc/the-bulwark 1.0.0

package/skills/component-patterns/references/pattern-database.md

@@ -0,0 +1,166 @@
+# Pattern 5: Database Verification
+
+## Strategy
+
+Setup test database, execute operations, verify state changes, teardown.
+
+---
+
+## Template (Node/Jest)
+
+```javascript
+const { setupTestDb, teardownTestDb } = require('./test-utils');
+const { saveRecord, findRecord, deleteRecord } = require('{component_path}');
+
+describe('{component_name} Database Operations', () => {
+  let db;
+
+  beforeAll(async () => {
+    db = await setupTestDb();
+  });
+
+  afterAll(async () => {
+    await teardownTestDb(db);
+  });
+
+  beforeEach(async () => {
+    await db.clear();  // Clean state between tests
+  });
+
+  test('save creates record in database', async () => {
+    const data = { id: 1, value: 'test' };
+    await saveRecord(db, data);
+
+    const found = await db.findOne({ id: 1 });
+    expect(found).toBeDefined();
+    expect(found.value).toBe('test');
+  });
+
+  test('find retrieves existing record', async () => {
+    await db.insert({ id: 2, value: 'existing' });
+
+    const result = await findRecord(db, 2);
+    expect(result.value).toBe('existing');
+  });
+
+  test('delete removes record from database', async () => {
+    await db.insert({ id: 3, value: 'to-delete' });
+
+    await deleteRecord(db, 3);
+
+    const found = await db.findOne({ id: 3 });
+    expect(found).toBeNull();
+  });
+});
+```
+
+---
+
+## Template (Python/pytest)
+
+```python
+import pytest
+from {module} import save_record, find_record, delete_record
+
+@pytest.fixture
+def test_db():
+    db = setup_test_database()
+    yield db
+    teardown_test_database(db)
+
+@pytest.fixture(autouse=True)
+def clean_db(test_db):
+    yield
+    test_db.clear()
+
+def test_save_creates_record(test_db):
+    save_record(test_db, {'id': 1, 'value': 'test'})
+
+    found = test_db.find_one({'id': 1})
+    assert found is not None
+    assert found['value'] == 'test'
+
+def test_find_retrieves_record(test_db):
+    test_db.insert({'id': 2, 'value': 'existing'})
+
+    result = find_record(test_db, 2)
+    assert result['value'] == 'existing'
+
+def test_delete_removes_record(test_db):
+    test_db.insert({'id': 3, 'value': 'to-delete'})
+
+    delete_record(test_db, 3)
+
+    found = test_db.find_one({'id': 3})
+    assert found is None
+```
+
+---
+
+## Template (Bash - SQLite)
+
+```bash
+#!/bin/bash
+# Database Verification: {component_name}
+set -e
+
+echo "=== Database Verification: {component_name} ==="
+
+TEST_DB=$(mktemp --suffix=.db)
+
+cleanup() {
+  rm -f "$TEST_DB"
+}
+trap cleanup EXIT
+
+# Initialize test database
+sqlite3 "$TEST_DB" "CREATE TABLE {table} (id INTEGER PRIMARY KEY, value TEXT);"
+
+# Test 1: Insert
+echo -n "Test 1: Insert record... "
+{insert_command} "$TEST_DB"
+COUNT=$(sqlite3 "$TEST_DB" "SELECT COUNT(*) FROM {table};")
+if [ "$COUNT" -gt 0 ]; then
+  echo "PASS ($COUNT records)"
+else
+  echo "FAIL (no records inserted)"
+  exit 1
+fi
+
+# Test 2: Query
+echo -n "Test 2: Query record... "
+VALUE=$(sqlite3 "$TEST_DB" "SELECT value FROM {table} WHERE id=1;")
+if [ "$VALUE" = "{expected_value}" ]; then
+  echo "PASS"
+else
+  echo "FAIL (expected: {expected_value}, got: $VALUE)"
+  exit 1
+fi
+
+# Test 3: Delete
+echo -n "Test 3: Delete record... "
+{delete_command} "$TEST_DB"
+COUNT=$(sqlite3 "$TEST_DB" "SELECT COUNT(*) FROM {table};")
+if [ "$COUNT" -eq 0 ]; then
+  echo "PASS (deleted)"
+else
+  echo "FAIL ($COUNT records remain)"
+  exit 1
+fi
+
+echo "=== All tests passed ==="
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{component_name}` | Name of the database component |
+| `{component_path}` | Import path to the database module |
+| `{module}` | Python module name |
+| `{table}` | Database table name |
+| `{insert_command}` | Command to insert records |
+| `{delete_command}` | Command to delete records |
+| `{expected_value}` | Expected value after operations |

package/skills/component-patterns/references/pattern-external-api.md

@@ -0,0 +1,139 @@
+# Pattern 6: External API Verification
+
+## Strategy
+
+Use MSW (Mock Service Worker) to intercept at network level - not module level.
+This allows real HTTP calls while controlling external responses.
+
+---
+
+## Template (Node/Jest with MSW)
+
+```javascript
+import { setupServer } from 'msw/node';
+import { rest } from 'msw';
+import { fetchUserData, postOrder } from '{component_path}';
+
+// Setup MSW server with handlers
+const server = setupServer(
+  rest.get('https://api.example.com/users/:id', (req, res, ctx) => {
+    return res(ctx.json({
+      id: req.params.id,
+      name: 'Test User',
+      email: 'test@example.com'
+    }));
+  }),
+  rest.post('https://api.example.com/orders', async (req, res, ctx) => {
+    const body = await req.json();
+    return res(ctx.json({
+      orderId: 'ORD-123',
+      items: body.items,
+      status: 'created'
+    }));
+  })
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe('{component_name} External API', () => {
+  test('fetches user data from API', async () => {
+    // Real fetch call - intercepted by MSW at network level
+    const user = await fetchUserData(1);
+
+    expect(user.name).toBe('Test User');
+    expect(user.email).toBe('test@example.com');
+  });
+
+  test('posts order to API', async () => {
+    const order = await postOrder({ items: [{ sku: 'ABC', qty: 2 }] });
+
+    expect(order.orderId).toBe('ORD-123');
+    expect(order.status).toBe('created');
+  });
+
+  test('handles API errors gracefully', async () => {
+    // Override handler for this test
+    server.use(
+      rest.get('https://api.example.com/users/:id', (req, res, ctx) => {
+        return res(ctx.status(500), ctx.json({ error: 'Server error' }));
+      })
+    );
+
+    await expect(fetchUserData(1)).rejects.toThrow('API error');
+  });
+});
+```
+
+---
+
+## Template (Python/pytest with responses)
+
+```python
+import pytest
+import responses
+from {module} import fetch_user_data, post_order
+
+@responses.activate
+def test_fetches_user_data():
+    responses.add(
+        responses.GET,
+        'https://api.example.com/users/1',
+        json={'id': 1, 'name': 'Test User', 'email': 'test@example.com'},
+        status=200
+    )
+
+    user = fetch_user_data(1)
+
+    assert user['name'] == 'Test User'
+    assert user['email'] == 'test@example.com'
+
+@responses.activate
+def test_posts_order():
+    responses.add(
+        responses.POST,
+        'https://api.example.com/orders',
+        json={'orderId': 'ORD-123', 'status': 'created'},
+        status=201
+    )
+
+    order = post_order({'items': [{'sku': 'ABC', 'qty': 2}]})
+
+    assert order['orderId'] == 'ORD-123'
+    assert order['status'] == 'created'
+
+@responses.activate
+def test_handles_api_errors():
+    responses.add(
+        responses.GET,
+        'https://api.example.com/users/1',
+        json={'error': 'Server error'},
+        status=500
+    )
+
+    with pytest.raises(Exception) as exc:
+        fetch_user_data(1)
+    assert 'API error' in str(exc.value)
+```
+
+---
+
+## Key Difference from jest.mock
+
+| Approach | What Happens | Real HTTP? |
+|----------|--------------|------------|
+| `jest.mock('node-fetch')` | Replaces module entirely | No |
+| MSW / responses | Intercepts at network layer | Yes (intercepted before leaving machine) |
+
+MSW allows real `fetch()` calls to execute, testing the actual HTTP code path while still controlling external responses.
+
+---
+
+## Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{component_name}` | Name of the API client component |
+| `{component_path}` | Import path to the API module |
+| `{module}` | Python module name |

package/skills/component-patterns/references/pattern-file-parser.md

@@ -0,0 +1,168 @@
+# Pattern 3: File Parser Verification
+
+## Strategy
+
+Create test input file, run parser, verify parsed output structure and values.
+
+---
+
+## Template (Bash)
+
+```bash
+#!/bin/bash
+# File Parser Verification: {component_name}
+set -e
+
+echo "=== File Parser Verification: {component_name} ==="
+
+# Create test input
+TEST_FILE=$(mktemp --suffix=.{ext})
+cat > "$TEST_FILE" << 'EOF'
+{test_input_content}
+EOF
+
+# Cleanup trap
+cleanup() {
+  rm -f "$TEST_FILE"
+}
+trap cleanup EXIT
+
+# Test 1: Parse succeeds
+echo -n "Test 1: Parse succeeds... "
+OUTPUT=$({parser_command} "$TEST_FILE" 2>&1)
+if [ $? -eq 0 ]; then
+  echo "PASS"
+else
+  echo "FAIL"
+  exit 1
+fi
+
+# Test 2: Output structure valid
+echo -n "Test 2: Output structure... "
+if echo "$OUTPUT" | jq -e '{json_structure_check}' > /dev/null 2>&1; then
+  echo "PASS"
+else
+  echo "FAIL"
+  echo "Output was: $OUTPUT"
+  exit 1
+fi
+
+# Test 3: Values correct
+echo -n "Test 3: Values correct... "
+VALUE=$(echo "$OUTPUT" | jq -r '{value_path}')
+if [ "$VALUE" = "{expected_value}" ]; then
+  echo "PASS"
+else
+  echo "FAIL (expected: {expected_value}, got: $VALUE)"
+  exit 1
+fi
+
+# Test 4: Invalid input handling
+echo -n "Test 4: Invalid input handling... "
+if ! {parser_command} "/nonexistent/file.{ext}" 2>&1; then
+  echo "PASS (error returned)"
+else
+  echo "FAIL (should have errored)"
+  exit 1
+fi
+
+echo "=== All tests passed ==="
+```
+
+---
+
+## Template (Node/Jest)
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { parse } = require('{component_path}');
+
+describe('{component_name} Parser', () => {
+  let testFile;
+
+  beforeAll(() => {
+    testFile = path.join(os.tmpdir(), 'test-input.{ext}');
+    fs.writeFileSync(testFile, `{test_input_content}`);
+  });
+
+  afterAll(() => {
+    fs.unlinkSync(testFile);
+  });
+
+  test('parses valid input', () => {
+    const result = parse(testFile);
+    expect(result).toBeDefined();
+  });
+
+  test('output has expected structure', () => {
+    const result = parse(testFile);
+    expect(result).toHaveProperty('{expected_field}');
+  });
+
+  test('values are correct', () => {
+    const result = parse(testFile);
+    expect(result.{field}).toBe('{expected_value}');
+  });
+
+  test('handles invalid input', () => {
+    expect(() => parse('/nonexistent/file.{ext}')).toThrow();
+  });
+});
+```
+
+---
+
+## Template (Python/pytest)
+
+```python
+import pytest
+import tempfile
+import os
+from {module} import {parser_function}
+
+@pytest.fixture
+def test_file():
+    fd, path = tempfile.mkstemp(suffix='.{ext}')
+    with os.fdopen(fd, 'w') as f:
+        f.write('''{test_input_content}''')
+    yield path
+    os.unlink(path)
+
+def test_parse_succeeds(test_file):
+    result = {parser_function}(test_file)
+    assert result is not None
+
+def test_output_structure(test_file):
+    result = {parser_function}(test_file)
+    assert '{expected_field}' in result
+
+def test_values_correct(test_file):
+    result = {parser_function}(test_file)
+    assert result['{field}'] == '{expected_value}'
+
+def test_handles_invalid_input():
+    with pytest.raises({ExpectedException}):
+        {parser_function}('/nonexistent/file.{ext}')
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{component_name}` | Name of the parser component |
+| `{component_path}` | Import path to the parser module |
+| `{module}` | Python module name |
+| `{parser_function}` | Name of the parse function |
+| `{parser_command}` | CLI command to run parser |
+| `{ext}` | File extension (e.g., json, yaml, csv) |
+| `{test_input_content}` | Sample input content |
+| `{expected_field}` | Field expected in parsed result |
+| `{field}` | Specific field to check value |
+| `{expected_value}` | Expected value of field |
+| `{json_structure_check}` | jq expression for structure check |
+| `{value_path}` | jq path to specific value |
+| `{ExpectedException}` | Python exception class for errors |

package/skills/component-patterns/references/pattern-http-server.md

@@ -0,0 +1,162 @@
+# Pattern 2: HTTP Server Verification
+
+## Strategy
+
+Start server, wait for ready, make HTTP requests, verify responses, cleanup.
+
+---
+
+## Template (Bash)
+
+```bash
+#!/bin/bash
+# HTTP Server Verification: {component_name}
+set -e
+
+echo "=== HTTP Server Verification: {component_name} ==="
+
+# Start server in background
+{start_command} &
+SERVER_PID=$!
+echo "Started server (PID: $SERVER_PID)"
+
+# Cleanup trap
+cleanup() {
+  echo "Cleaning up..."
+  kill $SERVER_PID 2>/dev/null || true
+  wait $SERVER_PID 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# Wait for server to be ready
+echo -n "Waiting for server... "
+for i in {1..30}; do
+  if curl -s http://localhost:{port}/health > /dev/null 2>&1; then
+    echo "ready"
+    break
+  fi
+  sleep 0.5
+done
+
+# Test 1: Health endpoint
+echo -n "Test 1: Health endpoint... "
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}/health)
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "PASS (HTTP 200)"
+else
+  echo "FAIL (HTTP $HTTP_CODE)"
+  exit 1
+fi
+
+# Test 2: API endpoint response
+echo -n "Test 2: API response... "
+RESPONSE=$(curl -s http://localhost:{port}{endpoint})
+if echo "$RESPONSE" | jq -e '{json_validation}' > /dev/null 2>&1; then
+  echo "PASS (valid response)"
+else
+  echo "FAIL (invalid response)"
+  echo "Response was: $RESPONSE"
+  exit 1
+fi
+
+# Test 3: 404 handling
+echo -n "Test 3: 404 handling... "
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}/nonexistent)
+if [ "$HTTP_CODE" = "404" ]; then
+  echo "PASS (HTTP 404)"
+else
+  echo "FAIL (HTTP $HTTP_CODE, expected 404)"
+  exit 1
+fi
+
+echo "=== All tests passed ==="
+```
+
+---
+
+## Template (Node/Jest with Supertest)
+
+```javascript
+const request = require('supertest');
+const { createServer } = require('{component_path}');
+
+describe('{component_name} HTTP Server', () => {
+  let server;
+
+  beforeAll(async () => {
+    server = await createServer();
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  test('health endpoint returns 200', async () => {
+    const response = await request(server).get('/health');
+    expect(response.status).toBe(200);
+  });
+
+  test('API endpoint returns valid data', async () => {
+    const response = await request(server).get('{endpoint}');
+    expect(response.status).toBe(200);
+    expect(response.body).toHaveProperty('{expected_field}');
+  });
+
+  test('handles 404 gracefully', async () => {
+    const response = await request(server).get('/nonexistent');
+    expect(response.status).toBe(404);
+  });
+});
+```
+
+---
+
+## Template (Python/pytest)
+
+```python
+import pytest
+import requests
+import subprocess
+import time
+
+@pytest.fixture(scope='module')
+def server():
+    proc = subprocess.Popen(['{start_command}'])
+    # Wait for server to start
+    for _ in range(30):
+        try:
+            requests.get('http://localhost:{port}/health')
+            break
+        except requests.ConnectionError:
+            time.sleep(0.5)
+    yield 'http://localhost:{port}'
+    proc.terminate()
+    proc.wait()
+
+def test_health_endpoint(server):
+    response = requests.get(f'{server}/health')
+    assert response.status_code == 200
+
+def test_api_endpoint(server):
+    response = requests.get(f'{server}{endpoint}')
+    assert response.status_code == 200
+    assert '{expected_field}' in response.json()
+
+def test_404_handling(server):
+    response = requests.get(f'{server}/nonexistent')
+    assert response.status_code == 404
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{component_name}` | Name of the HTTP server component |
+| `{component_path}` | Import path to the server module |
+| `{start_command}` | Command to start the server |
+| `{port}` | Port the server listens on |
+| `{endpoint}` | API endpoint to test |
+| `{expected_field}` | Field expected in JSON response |
+| `{json_validation}` | jq expression for JSON validation |