ai-qakit 1.0.0

package/templates/.claude/skills/databases/scripts/tests/test_db_performance_check.py

@@ -0,0 +1,370 @@
+"""Tests for db_performance_check.py"""
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from unittest.mock import Mock, patch, MagicMock
+
+import pytest
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from db_performance_check import (
+    SlowQuery, IndexRecommendation, PerformanceReport, PerformanceAnalyzer
+)
+
+
+@pytest.fixture
+def mock_mongo_client():
+    """Mock MongoDB client."""
+    mock_client = MagicMock()
+    mock_db = MagicMock()
+    mock_client.get_default_database.return_value = mock_db
+    mock_client.server_info.return_value = {}
+    return mock_client, mock_db
+
+
+@pytest.fixture
+def mock_postgres_conn():
+    """Mock PostgreSQL connection."""
+    mock_conn = MagicMock()
+    mock_cursor = MagicMock()
+    mock_conn.cursor.return_value.__enter__.return_value = mock_cursor
+    return mock_conn, mock_cursor
+
+
+class TestSlowQuery:
+    """Test SlowQuery dataclass."""
+
+    def test_slow_query_creation(self):
+        """Test creating slow query object."""
+        query = SlowQuery(
+            query="SELECT * FROM users",
+            execution_time_ms=150.5,
+            count=10
+        )
+
+        assert query.query == "SELECT * FROM users"
+        assert query.execution_time_ms == 150.5
+        assert query.count == 10
+
+
+class TestIndexRecommendation:
+    """Test IndexRecommendation dataclass."""
+
+    def test_recommendation_creation(self):
+        """Test creating index recommendation."""
+        rec = IndexRecommendation(
+            collection_or_table="users",
+            fields=["email"],
+            reason="Frequently queried field",
+            estimated_benefit="High"
+        )
+
+        assert rec.collection_or_table == "users"
+        assert rec.fields == ["email"]
+        assert rec.reason == "Frequently queried field"
+        assert rec.estimated_benefit == "High"
+
+
+class TestPerformanceReport:
+    """Test PerformanceReport dataclass."""
+
+    def test_report_creation(self):
+        """Test creating performance report."""
+        report = PerformanceReport(
+            database_type="mongodb",
+            database_name="testdb",
+            timestamp=datetime.now(),
+            slow_queries=[],
+            index_recommendations=[],
+            database_metrics={}
+        )
+
+        assert report.database_type == "mongodb"
+        assert report.database_name == "testdb"
+        assert isinstance(report.slow_queries, list)
+        assert isinstance(report.index_recommendations, list)
+        assert isinstance(report.database_metrics, dict)
+
+
+class TestPerformanceAnalyzer:
+    """Test PerformanceAnalyzer class."""
+
+    def test_init(self):
+        """Test analyzer initialization."""
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost", 100)
+
+        assert analyzer.db_type == "mongodb"
+        assert analyzer.connection_string == "mongodb://localhost"
+        assert analyzer.threshold_ms == 100
+
+    @patch('db_performance_check.MongoClient')
+    def test_connect_mongodb(self, mock_client_class, mock_mongo_client):
+        """Test MongoDB connection."""
+        mock_client, mock_db = mock_mongo_client
+        mock_client_class.return_value = mock_client
+
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost")
+        result = analyzer.connect()
+
+        assert result is True
+        assert analyzer.client == mock_client
+        assert analyzer.db == mock_db
+
+    @patch('db_performance_check.psycopg2')
+    def test_connect_postgres(self, mock_psycopg2, mock_postgres_conn):
+        """Test PostgreSQL connection."""
+        mock_conn, mock_cursor = mock_postgres_conn
+        mock_psycopg2.connect.return_value = mock_conn
+
+        analyzer = PerformanceAnalyzer("postgres", "postgresql://localhost")
+        result = analyzer.connect()
+
+        assert result is True
+        assert analyzer.conn == mock_conn
+
+    def test_connect_unsupported_db(self):
+        """Test connection with unsupported database type."""
+        analyzer = PerformanceAnalyzer("unsupported", "connection_string")
+        result = analyzer.connect()
+
+        assert result is False
+
+    @patch('db_performance_check.MongoClient')
+    def test_analyze_mongodb(self, mock_client_class, mock_mongo_client):
+        """Test MongoDB performance analysis."""
+        mock_client, mock_db = mock_mongo_client
+        mock_client_class.return_value = mock_client
+
+        # Mock profiling
+        mock_db.command.side_effect = [
+            {"was": 0},  # profile -1 (get status)
+            {},          # profile 1 (enable)
+        ]
+
+        # Mock slow queries
+        mock_profile_cursor = MagicMock()
+        mock_profile_cursor.sort.return_value = [
+            {
+                "command": {"find": "users"},
+                "millis": 150,
+                "ns": "testdb.users",
+                "planSummary": "COLLSCAN"
+            }
+        ]
+        mock_db.system.profile.find.return_value = mock_profile_cursor
+
+        # Mock collections
+        mock_db.list_collection_names.return_value = ["users", "orders"]
+
+        # Mock collection stats
+        mock_coll = MagicMock()
+        mock_coll.aggregate.return_value = [{"storageStats": {}}]
+        mock_coll.list_indexes.return_value = [{"name": "_id_"}]
+        mock_coll.find.return_value.limit.return_value = [
+            {"_id": 1, "name": "Alice", "email": "alice@example.com"}
+        ]
+        mock_db.__getitem__.return_value = mock_coll
+
+        # Mock server status and db stats
+        mock_client.admin.command.return_value = {
+            "connections": {"current": 10},
+            "opcounters": {"query": 1000}
+        }
+        mock_db.command.return_value = {
+            "dataSize": 1024 * 1024 * 100,
+            "indexSize": 1024 * 1024 * 10,
+            "collections": 5
+        }
+
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost")
+        analyzer.connect()
+
+        report = analyzer.analyze()
+
+        assert report is not None
+        assert report.database_type == "mongodb"
+        assert isinstance(report.slow_queries, list)
+        assert isinstance(report.index_recommendations, list)
+        assert isinstance(report.database_metrics, dict)
+
+    @patch('db_performance_check.psycopg2')
+    def test_analyze_postgres(self, mock_psycopg2, mock_postgres_conn):
+        """Test PostgreSQL performance analysis."""
+        mock_conn, mock_cursor = mock_postgres_conn
+        mock_psycopg2.connect.return_value = mock_conn
+
+        # Mock cursor results
+        mock_cursor.fetchone.side_effect = [
+            {"has_extension": True},  # pg_stat_statements check
+            {"connections": 10, "commits": 1000, "rollbacks": 5},  # stats
+            {"db_size": 1024 * 1024 * 500},  # database size
+            {"cache_hit_ratio": 0.95}  # cache hit ratio
+        ]
+
+        mock_cursor.fetchall.side_effect = [
+            # Slow queries
+            [
+                {
+                    "query": "SELECT * FROM users",
+                    "mean_exec_time": 150.5,
+                    "calls": 100,
+                    "total_exec_time": 15050
+                }
+            ],
+            # Sequential scans
+            [
+                {
+                    "schemaname": "public",
+                    "tablename": "users",
+                    "seq_scan": 5000,
+                    "seq_tup_read": 500000,
+                    "idx_scan": 100
+                }
+            ],
+            # Unused indexes
+            []
+        ]
+
+        analyzer = PerformanceAnalyzer("postgres", "postgresql://localhost")
+        analyzer.connect()
+
+        report = analyzer.analyze()
+
+        assert report is not None
+        assert report.database_type == "postgres"
+        assert len(report.slow_queries) > 0
+        assert len(report.index_recommendations) > 0
+
+    def test_print_report(self, capsys):
+        """Test report printing."""
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost")
+
+        report = PerformanceReport(
+            database_type="mongodb",
+            database_name="testdb",
+            timestamp=datetime.now(),
+            slow_queries=[
+                SlowQuery(
+                    query="db.users.find({age: {$gte: 18}})",
+                    execution_time_ms=150.5,
+                    count=10,
+                    collection_or_table="users"
+                )
+            ],
+            index_recommendations=[
+                IndexRecommendation(
+                    collection_or_table="users",
+                    fields=["age"],
+                    reason="Frequently queried field",
+                    estimated_benefit="High"
+                )
+            ],
+            database_metrics={
+                "connections": 10,
+                "database_size_mb": 100.5
+            }
+        )
+
+        analyzer.print_report(report)
+
+        captured = capsys.readouterr()
+        assert "Database Performance Report" in captured.out
+        assert "testdb" in captured.out
+        assert "150.5ms" in captured.out
+        assert "users" in captured.out
+
+    def test_save_report(self, tmp_path):
+        """Test saving report to JSON."""
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost")
+
+        report = PerformanceReport(
+            database_type="mongodb",
+            database_name="testdb",
+            timestamp=datetime.now(),
+            slow_queries=[],
+            index_recommendations=[],
+            database_metrics={}
+        )
+
+        output_file = tmp_path / "report.json"
+        analyzer.save_report(report, str(output_file))
+
+        assert output_file.exists()
+
+        with open(output_file) as f:
+            data = json.load(f)
+            assert data["database_type"] == "mongodb"
+            assert data["database_name"] == "testdb"
+
+    def test_disconnect(self):
+        """Test disconnection."""
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost")
+
+        # Mock client and connection
+        analyzer.client = MagicMock()
+        analyzer.conn = MagicMock()
+
+        analyzer.disconnect()
+
+        analyzer.client.close.assert_called_once()
+        analyzer.conn.close.assert_called_once()
+
+    @patch('db_performance_check.MongoClient')
+    def test_analyze_error_handling(self, mock_client_class, mock_mongo_client):
+        """Test error handling during analysis."""
+        mock_client, mock_db = mock_mongo_client
+        mock_client_class.return_value = mock_client
+
+        # Simulate error
+        mock_db.command.side_effect = Exception("Database error")
+
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost")
+        analyzer.connect()
+
+        report = analyzer.analyze()
+
+        assert report is None
+
+
+class TestIntegration:
+    """Integration tests."""
+
+    @patch('db_performance_check.MongoClient')
+    def test_full_mongodb_workflow(self, mock_client_class, mock_mongo_client, tmp_path):
+        """Test complete MongoDB analysis workflow."""
+        mock_client, mock_db = mock_mongo_client
+        mock_client_class.return_value = mock_client
+
+        # Setup mocks
+        mock_db.command.return_value = {"was": 0}
+        mock_db.system.profile.find.return_value.sort.return_value = []
+        mock_db.list_collection_names.return_value = []
+        mock_client.admin.command.return_value = {
+            "connections": {"current": 10},
+            "opcounters": {"query": 1000}
+        }
+
+        analyzer = PerformanceAnalyzer("mongodb", "mongodb://localhost", 100)
+
+        # Connect
+        assert analyzer.connect() is True
+
+        # Analyze
+        report = analyzer.analyze()
+        assert report is not None
+
+        # Save report
+        output_file = tmp_path / "report.json"
+        analyzer.save_report(report, str(output_file))
+        assert output_file.exists()
+
+        # Disconnect
+        analyzer.disconnect()
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

package/templates/.claude/skills/debugging/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: Debugging
+description: Systematic debugging framework ensuring root cause investigation before fixes. Includes four-phase debugging process, backward call stack tracing, multi-layer validation, and verification protocols. Use when encountering bugs, test failures, unexpected behavior, performance issues, or before claiming work complete. Prevents random fixes, masks over symptoms, and false completion claims.
+version: 3.0.0
+languages: all
+---
+
+# Debugging
+
+Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.
+
+## Core Principle
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+
+Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.
+
+## When to Use
+
+**Always use for:** Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete
+
+**Especially when:** Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
+
+## The Four Techniques
+
+### 1. Systematic Debugging (`references/systematic-debugging.md`)
+
+Four-phase framework ensuring proper investigation:
+- Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
+- Phase 2: Pattern Analysis (find working examples, compare, identify differences)
+- Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
+- Phase 4: Implementation (create test, fix once, verify)
+
+**Key rule:** Complete each phase before proceeding. No fixes without Phase 1.
+
+**Load when:** Any bug/issue requiring investigation and fix
+
+### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
+
+Trace bugs backward through call stack to find original trigger.
+
+**Technique:** When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.
+
+**Includes:** `scripts/find-polluter.sh` for bisecting test pollution
+
+**Load when:** Error deep in call stack, unclear where invalid data originated
+
+### 3. Defense-in-Depth (`references/defense-in-depth.md`)
+
+Validate at every layer data passes through. Make bugs impossible.
+
+**Four layers:** Entry validation → Business logic → Environment guards → Debug instrumentation
+
+**Load when:** After finding root cause, need to add comprehensive validation
+
+### 4. Verification (`references/verification.md`)
+
+Run verification commands and confirm output before claiming success.
+
+**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+Run the command. Read the output. Then claim the result.
+
+**Load when:** About to claim work complete, fixed, or passing
+
+## Quick Reference
+
+```
+Bug → systematic-debugging.md (Phase 1-4)
+  Error deep in stack? → root-cause-tracing.md (trace backward)
+  Found root cause? → defense-in-depth.md (add layers)
+  About to claim success? → verification.md (verify first)
+```
+
+## Red Flags
+
+Stop and follow process if thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "Should work now" / "Seems fixed"
+- "Tests pass, we're done"
+
+**All mean:** Return to systematic process.

package/templates/.claude/skills/debugging/references/defense-in-depth.md

@@ -0,0 +1,124 @@
+# Defense-in-Depth Validation
+
+Validate at every layer data passes through to make bugs impossible.
+
+## Core Principle
+
+**Validate at EVERY layer data passes through. Make bug structurally impossible.**
+
+When fix bug caused by invalid data, adding validation at one place feels sufficient. But single check can be bypassed by different code paths, refactoring, or mocks.
+
+## Why Multiple Layers
+
+Single validation: "We fixed bug"
+Multiple layers: "We made bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // proceed
+}
+```
+
+## Applying the Pattern
+
+When find bug:
+
+1. **Trace data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Real Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.

package/templates/.claude/skills/debugging/references/root-cause-tracing.md

@@ -0,0 +1,122 @@
+# Root Cause Tracing
+
+Systematically trace bugs backward through call stack to find original trigger.
+
+## Core Principle
+
+**Trace backward through call chain until finding original trigger, then fix at source.**
+
+Bugs often manifest deep in call stack (git init in wrong directory, file created in wrong location). Instinct is to fix where error appears, but that's treating symptom.
+
+## When to Use
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+What code directly causes this?
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+What value was passed?
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+Where did empty string come from?
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When can't trace manually, add instrumentation:
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find line number triggering call
+- Identify pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but don't know which test:
+
+Use bisection script: `scripts/find-polluter.sh`
+
+```bash
+./scripts/find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter.
+
+## Key Principle
+
+**NEVER fix just where error appears.** Trace back to find original trigger.
+
+When found immediate cause:
+- Can trace one level up? → Trace backwards
+- Is this the source? → Fix at source
+- Then add validation at each layer (see defense-in-depth.md)
+
+## Real Example
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init