@vodailoc/kilo-kit-mcp 1.1.0

package/skills/engineering/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/skills/engineering/diagnose/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
+---
+
+# Diagnose
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+Do not proceed to Phase 2 until you have a loop you believe in.
+
+## Phase 2 — Reproduce
+
+Run the loop. Watch the bug appear.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+Do not proceed until you reproduce the bug.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/skills/engineering/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"