synapse-hub 2.6.0 → 3.0.0

package/tools/qa_event_stream.py

@@ -0,0 +1,336 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+Immutable QA Event Stream Engine (OpenHands EventStream Pattern)
+----------------------------------------------------------------
+Provides a deterministic, append-only event stream for test automation sessions:
+  1. Immutable Event Logging: Sequential JSON Lines recording of all actor actions and observations.
+  2. Cryptographic Hash Chain: SHA-256 hash chaining ensures audit integrity and tamper resistance.
+  3. Reversible Checkpoints: Enables safe rollback to prior verified states on failures.
+  4. Stream Verification: Verifies stream schema, timestamp monotonicity, and hash chain integrity.
+
+Usage:
+  python tools/qa_event_stream.py init-stream --session-id "E2E_001" --out-file .agent_memory/timeline.jsonl
+  python tools/qa_event_stream.py record-event --stream .agent_memory/timeline.jsonl --event-type ACTION_CLICK --actor live-explorer --payload '{"target": "#btn"}'
+  python tools/qa_event_stream.py verify-stream --stream .agent_memory/timeline.jsonl
+  python tools/qa_event_stream.py rollback --stream .agent_memory/timeline.jsonl --to-checkpoint CHECKPOINT_PRE_CHECKOUT
+"""
+
+import os
+import sys
+import json
+import hashlib
+import argparse
+from datetime import datetime, timezone
+from typing import Dict, Any, Optional
+
+# Enforce UTF-8 stdout encoding
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+GENESIS_HASH = "0" * 64
+VALID_EVENT_TYPES = {
+    "STREAM_INIT",
+    "ACTION_NAVIGATE",
+    "ACTION_CLICK",
+    "ACTION_TYPE",
+    "OBSERVATION_DOM",
+    "ASSERTION_EVALUATED",
+    "CHECKPOINT",
+    "ERROR_OCCURRED",
+    "ROLLBACK_EXECUTED",
+    "TEST_COMPLETED"
+}
+
+
+class QaEventStream:
+    """Immutable Event Stream with SHA-256 Hash Chaining."""
+
+    def __init__(self, repo_root: Optional[str] = None):
+        self.repo_root = repo_root or os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+    def _compute_hash(self, prev_hash: str, session_id: str, event_type: str,
+                      actor: str, payload_str: str, timestamp: str) -> str:
+        raw = f"{prev_hash}|{session_id}|{event_type}|{actor}|{payload_str}|{timestamp}"
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+    def init_stream(self, session_id: str, out_file: str) -> Dict[str, Any]:
+        """Initializes an append-only timeline stream file."""
+        resolved = os.path.join(self.repo_root, out_file) if not os.path.isabs(out_file) else out_file
+        os.makedirs(os.path.dirname(os.path.abspath(resolved)), exist_ok=True)
+
+        now = datetime.now(timezone.utc).isoformat()
+        init_payload = {"session_id": session_id, "initialized_at": now}
+        init_payload_str = json.dumps(init_payload, sort_keys=True)
+        event_hash = self._compute_hash(GENESIS_HASH, session_id, "STREAM_INIT", "system", init_payload_str, now)
+
+        entry = {
+            "index": 0,
+            "session_id": session_id,
+            "event_type": "STREAM_INIT",
+            "actor": "system",
+            "payload": init_payload,
+            "timestamp": now,
+            "prev_hash": GENESIS_HASH,
+            "event_hash": event_hash
+        }
+
+        with open(resolved, "w", encoding="utf-8", newline="\n") as f:
+            f.write(json.dumps(entry) + "\n")
+
+        return {
+            "status": "PASS",
+            "session_id": session_id,
+            "out_file": resolved,
+            "genesis_hash": event_hash
+        }
+
+    def record_event(self, stream_file: str, event_type: str, actor: str,
+                     payload: Any, checkpoint_id: Optional[str] = None) -> Dict[str, Any]:
+        """Appends an event to the stream with continuous cryptographic hash chain."""
+        resolved = os.path.join(self.repo_root, stream_file) if not os.path.isabs(stream_file) else stream_file
+        if not os.path.exists(resolved):
+            return {"status": "FAIL", "error": f"Stream file not found: {stream_file}"}
+
+        # Read last line to get index and prev_hash
+        last_entry = None
+        total_count = 0
+        with open(resolved, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                stripped = line.strip()
+                if stripped:
+                    try:
+                        last_entry = json.loads(stripped)
+                        total_count += 1
+                    except Exception as err:
+                        sys.stderr.write(f"Notice: Skip malformed stream line: {err}\n")
+
+        if not last_entry:
+            return {"status": "FAIL", "error": "Stream file is empty or corrupted"}
+
+        prev_hash = last_entry.get("event_hash", GENESIS_HASH)
+        session_id = last_entry.get("session_id", "default_session")
+        now = datetime.now(timezone.utc).isoformat()
+
+        if checkpoint_id:
+            if isinstance(payload, dict):
+                payload["checkpoint_id"] = checkpoint_id
+            else:
+                payload = {"data": payload, "checkpoint_id": checkpoint_id}
+
+        payload_str = json.dumps(payload, sort_keys=True) if not isinstance(payload, str) else payload
+        event_hash = self._compute_hash(prev_hash, session_id, event_type, actor, payload_str, now)
+
+        new_entry = {
+            "index": total_count,
+            "session_id": session_id,
+            "event_type": event_type,
+            "actor": actor,
+            "payload": payload if not isinstance(payload, str) else json.loads(payload_str),
+            "timestamp": now,
+            "prev_hash": prev_hash,
+            "event_hash": event_hash
+        }
+
+        with open(resolved, "a", encoding="utf-8", newline="\n") as f:
+            f.write(json.dumps(new_entry) + "\n")
+
+        return {
+            "status": "PASS",
+            "index": total_count,
+            "event_type": event_type,
+            "event_hash": event_hash,
+            "prev_hash": prev_hash
+        }
+
+    def verify_stream(self, stream_file: str) -> Dict[str, Any]:
+        """Verifies hash chain integrity and JSON schema compliance (Gate 12)."""
+        resolved = os.path.join(self.repo_root, stream_file) if not os.path.isabs(stream_file) else stream_file
+        if not os.path.exists(resolved):
+            return {"status": "FAIL", "verified": False, "error": f"Stream file not found: {stream_file}"}
+
+        events = []
+        with open(resolved, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                stripped = line.strip()
+                if stripped:
+                    try:
+                        events.append(json.loads(stripped))
+                    except Exception as err:
+                        return {"status": "FAIL", "verified": False, "error": f"JSON decode error: {err}"}
+
+        if not events:
+            return {"status": "FAIL", "verified": False, "error": "Stream is empty"}
+
+        expected_prev = GENESIS_HASH
+        for idx, ev in enumerate(events):
+            if ev.get("index") != idx:
+                return {
+                    "status": "FAIL",
+                    "verified": False,
+                    "error": f"Index mismatch at position {idx}: expected {idx}, got {ev.get('index')}"
+                }
+
+            if ev.get("prev_hash") != expected_prev:
+                return {
+                    "status": "FAIL",
+                    "verified": False,
+                    "error": f"Broken hash chain at index {idx}: expected prev_hash {expected_prev}, got {ev.get('prev_hash')}"
+                }
+
+            payload_str = json.dumps(ev.get("payload"), sort_keys=True)
+            recalc = self._compute_hash(
+                expected_prev,
+                ev.get("session_id", ""),
+                ev.get("event_type", ""),
+                ev.get("actor", ""),
+                payload_str,
+                ev.get("timestamp", "")
+            )
+
+            if recalc != ev.get("event_hash"):
+                return {
+                    "status": "FAIL",
+                    "verified": False,
+                    "error": f"Hash tamper detected at index {idx}: declared {ev.get('event_hash')}, computed {recalc}"
+                }
+
+            expected_prev = ev["event_hash"]
+
+        return {
+            "status": "PASS",
+            "verified": True,
+            "events_verified": len(events),
+            "final_event_hash": expected_prev,
+            "integrity": "CRYPTOGRAPHICALLY_VERIFIED"
+        }
+
+    def rollback(self, stream_file: str, to_checkpoint: str) -> Dict[str, Any]:
+        """Rolls back execution state to a designated checkpoint in the stream."""
+        resolved = os.path.join(self.repo_root, stream_file) if not os.path.isabs(stream_file) else stream_file
+        if not os.path.exists(resolved):
+            return {"status": "FAIL", "error": f"Stream file not found: {stream_file}"}
+
+        target_checkpoint = None
+        checkpoint_index = -1
+        events = []
+
+        with open(resolved, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                stripped = line.strip()
+                if stripped:
+                    try:
+                        ev = json.loads(stripped)
+                        events.append(ev)
+                        p = ev.get("payload", {})
+                        if isinstance(p, dict) and p.get("checkpoint_id") == to_checkpoint:
+                            target_checkpoint = ev
+                            checkpoint_index = ev.get("index", -1)
+                    except Exception as err:
+                        sys.stderr.write(f"Notice: Skip malformed stream line during rollback: {err}\n")
+
+        if not target_checkpoint:
+            return {
+                "status": "FAIL",
+                "error": f"Checkpoint '{to_checkpoint}' not found in event stream."
+            }
+
+        rolled_back_count = len(events) - (checkpoint_index + 1)
+
+        # Record ROLLBACK_EXECUTED event in the immutable stream
+        rollback_payload = {
+            "target_checkpoint": to_checkpoint,
+            "target_index": checkpoint_index,
+            "events_rewound": rolled_back_count,
+            "restored_state": target_checkpoint.get("payload")
+        }
+        rec_res = self.record_event(
+            stream_file=stream_file,
+            event_type="ROLLBACK_EXECUTED",
+            actor="system",
+            payload=rollback_payload
+        )
+
+        return {
+            "status": "PASS",
+            "to_checkpoint": to_checkpoint,
+            "target_index": checkpoint_index,
+            "events_rewound": rolled_back_count,
+            "new_event_hash": rec_res.get("event_hash"),
+            "restored_state": target_checkpoint.get("payload")
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="QA Event Stream Engine (OpenHands Pattern)")
+    subparsers = parser.add_subparsers(dest="subcommand", help="Subcommand to execute")
+
+    # init-stream
+    init_p = subparsers.add_parser("init-stream", help="Initialize a new event stream")
+    init_p.add_argument("--session-id", required=True, help="Unique test session ID")
+    init_p.add_argument("--out-file", required=True, help="Path to write JSONL stream")
+
+    # record-event
+    rec_p = subparsers.add_parser("record-event", help="Append an event to the stream")
+    rec_p.add_argument("--stream", required=True, help="Path to stream file")
+    rec_p.add_argument("--event-type", required=True, help="Event type (ACTION_CLICK, CHECKPOINT, etc.)")
+    rec_p.add_argument("--actor", required=True, help="Actor name (live-explorer, test-runner, etc.)")
+    rec_p.add_argument("--payload", required=True, help="JSON payload string")
+    rec_p.add_argument("--checkpoint-id", help="Optional checkpoint ID")
+
+    # verify-stream
+    ver_p = subparsers.add_parser("verify-stream", help="Verify cryptographic hash chain integrity")
+    ver_p.add_argument("--stream", required=True, help="Path to stream file")
+
+    # rollback
+    rb_p = subparsers.add_parser("rollback", help="Roll back state to a checkpoint")
+    rb_p.add_argument("--stream", required=True, help="Path to stream file")
+    rb_p.add_argument("--to-checkpoint", required=True, help="Target checkpoint ID")
+
+    args = parser.parse_args()
+    engine = QaEventStream()
+
+    if args.subcommand == "init-stream":
+        res = engine.init_stream(session_id=args.session_id, out_file=args.out_file)
+        print(json.dumps(res, indent=2))
+        sys.exit(0 if res["status"] == "PASS" else 1)
+
+    elif args.subcommand == "record-event":
+        try:
+            parsed_payload = json.loads(args.payload)
+        except Exception:
+            parsed_payload = args.payload
+        res = engine.record_event(
+            stream_file=args.stream,
+            event_type=args.event_type,
+            actor=args.actor,
+            payload=parsed_payload,
+            checkpoint_id=args.checkpoint_id
+        )
+        print(json.dumps(res, indent=2))
+        sys.exit(0 if res["status"] == "PASS" else 1)
+
+    elif args.subcommand == "verify-stream":
+        res = engine.verify_stream(stream_file=args.stream)
+        print(json.dumps(res, indent=2))
+        sys.exit(0 if res["status"] == "PASS" else 1)
+
+    elif args.subcommand == "rollback":
+        res = engine.rollback(stream_file=args.stream, to_checkpoint=args.to_checkpoint)
+        print(json.dumps(res, indent=2))
+        sys.exit(0 if res["status"] == "PASS" else 1)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/tools/repo_map.py

@@ -199,13 +199,13 @@ def build_repo_map(target_repo=None, output_txt=None, output_json=None):
     # Render text map
     timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     out_lines = [
-        f"# ==============================================================================",
-        f"# ENTERPRISE AUTOMATION REPOSITORY MAP (Aider-Style AST Compression)",
+        "# ==============================================================================",
+        "# ENTERPRISE AUTOMATION REPOSITORY MAP (Aider-Style AST Compression)",
         f"# Generated : {timestamp}",
         f"# Target    : {repo}",
         f"# Scope     : {len(classes)} Classes ({total_raw_lines} source lines, {total_raw_bytes / 1024:.1f} KB)",
-        f"# Purpose   : Token-budgeted index (< 600 tokens) for instant method lookup",
-        f"# ==============================================================================\n"
+        "# Purpose   : Token-budgeted index (< 600 tokens) for instant method lookup",
+        "# ==============================================================================\n"
     ]
 
     total_methods = 0
@@ -294,9 +294,9 @@ def main():
         return 1
 
     stats = build_repo_map(target_repo=target_repo)
-    print(f"\n======================================================================")
-    print(f"       Enterprise Repository Map Compressor (Aider-Style AST Map)           ")
-    print(f"======================================================================")
+    print("\n======================================================================")
+    print("       Enterprise Repository Map Compressor (Aider-Style AST Map)           ")
+    print("======================================================================")
     print(f"  Target Repository       : {stats['target_repo']}")
     print(f"  Indexed Classes         : {stats['classes_count']} Page Classes & Helpers")
     print(f"  Extracted Methods       : {stats['methods_count']} API signatures")
@@ -304,7 +304,7 @@ def main():
     print(f"  Compressed Map Size     : {stats['compressed_bytes'] / 1024:.1f} KB (~{stats['estimated_tokens']} tokens)")
     print(f"  Compression Ratio       : {stats['compression_ratio_pct']:.1f}% reduction")
     print(f"  Artifact Generated      : {stats['output_file']}")
-    print(f"======================================================================\n")
+    print("======================================================================\n")
 
     if args.print:
         with open(stats['output_file'], "r", encoding="utf-8") as f:

package/tools/report/__init__.py

@@ -0,0 +1,32 @@
+"""
+Synapse Hub — Reporting & Telemetry Engines (tools.report)
+----------------------------------------------------------
+Domain package grouping all HTML dashboard, spreadsheet, JTL/Newman
+metric parser, and visual reporting tools.
+"""
+
+from tools import (
+    bug_reporter,
+    dashboard_generator,
+    generate_allure_report,
+    generate_test_reports,
+    jtl_analyzer,
+    md_to_xlsx,
+    newman_analyzer,
+    output_formatter,
+    telemetry_correlator,
+    welcome_page,
+)
+
+__all__ = [
+    "bug_reporter",
+    "dashboard_generator",
+    "generate_allure_report",
+    "generate_test_reports",
+    "jtl_analyzer",
+    "md_to_xlsx",
+    "newman_analyzer",
+    "output_formatter",
+    "telemetry_correlator",
+    "welcome_page",
+]

package/tools/reversible_sandbox.py

@@ -17,11 +17,10 @@ Reference:
 
 import os
 import sys
-import json
 import shlex
 import subprocess
 from dataclasses import dataclass, field
-from typing import List, Optional, Callable, Dict, Any
+from typing import List, Optional, Dict, Any
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -120,6 +119,10 @@ class ExecutionSandbox:
 
         return results
 
+    def stack_size(self) -> int:
+        """Returns the number of pending undo actions in the stack."""
+        return len(self.undo_stack)
+
     def __enter__(self):
         return self
 

package/tools/safety_firewall.py

@@ -245,7 +245,7 @@ def detect_action_loop(action_history: List[str], repeat_threshold: int = 4) ->
     """
     Detects infinite action loops and repeating cycle patterns among agent tool calls.
     Inspired by agentblazo/blazo deterministic detection rules.
-    
+
     Checks:
       1. Consecutive identical actions (>= repeat_threshold)
       2. 2-action repeating cycle: [A, B, A, B]
@@ -411,7 +411,7 @@ def main():
             if all_authorized:
                 print(f"\n✅ All actions cleared by Safety Firewall{' (Dry-Run)' if args.dry_run else ''}.\n")
             else:
-                print(f"\n❌ Pre-execution Blocked: Destructive actions intercepted without --force or ALLOW_DESTRUCTIVE=1.\n")
+                print("\n❌ Pre-execution Blocked: Destructive actions intercepted without --force or ALLOW_DESTRUCTIVE=1.\n")
 
         return 0 if all_authorized else 1
 

package/tools/senior_code_review.py

@@ -28,7 +28,7 @@ import re
 import json
 import subprocess
 import argparse
-from typing import Dict, List, Any, Optional, Tuple
+from typing import Dict, List, Any, Tuple
 
 if hasattr(sys.stdout, 'reconfigure'):
     try:
@@ -83,7 +83,7 @@ def get_git_diff(repo_dir: str, target: str = "uncommitted") -> str:
             check=True
         )
         return res.stdout
-    except Exception as e:
+    except Exception:
         return ""
 
 

package/tools/setup_project.py

@@ -24,7 +24,6 @@ import json
 import shutil
 import argparse
 from pathlib import Path
-from datetime import datetime
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -39,9 +38,8 @@ HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
 TEMPLATES_DIR = os.path.join(HUB_ROOT, "templates")
 sys.path.insert(0, SCRIPT_DIR)
 
-import analyze_project
-import verify_all
-import project_state
+import analyze_project  # noqa: E402
+import project_state  # noqa: E402
 
 GREEN = "\033[92m"
 RED = "\033[91m"
@@ -412,7 +410,7 @@ def inject_antigravity_global_plugin():
                 try:
                     os.unlink(dst)
                 except OSError:
-                    unlinked = False
+                    _ = False
             if sys.platform == "win32":
                 try:
                     import _winapi
@@ -420,7 +418,7 @@ def inject_antigravity_global_plugin():
                         _winapi.CreateJunction(src, dst)
                         return
                 except (OSError, ImportError, AttributeError):
-                    junction_created = False
+                    _ = False
             shutil.copytree(src, dst, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.tmp"))
 
         sync_dir(os.path.join(HUB_ROOT, ".agents", "skills"), os.path.join(target_plugin_dir, "skills"))
@@ -612,26 +610,26 @@ def run_setup(target_repo, dry_run=False, profile="auto", no_global=True, no_git
     if dry_run:
         print(f"Operational Mode   : {YELLOW}DRY-RUN (Simulating without modifying files on disk){RESET}\n")
     else:
-        print(f"Operational Mode   : APPLY CHANGES\n")
+        print("Operational Mode   : APPLY CHANGES\n")
 
     if dry_run:
         print(f"{YELLOW}[DRY-RUN PREVIEW]{RESET}")
         print(f"  • Profile: {profile.upper()}")
         print(f"  • Would generate: {os.path.join(target_repo, 'PROJECT_AI_GUIDE.md')}")
-        print(f"  • Would deploy AI bridges: .cursor/rules/synapse-qa.mdc, .github/copilot-instructions.md, .windsurfrules")
+        print("  • Would deploy AI bridges: .cursor/rules/synapse-qa.mdc, .github/copilot-instructions.md, .windsurfrules")
         print(f"  • Would install pre-push hook: {os.path.join(target_repo, '.git', 'hooks', 'pre-push')}")
-        print(f"  • Would initialize: Central Agent Memory (~/.agent_memory/global_cache.db)")
+        print("  • Would initialize: Central Agent Memory (~/.agent_memory/global_cache.db)")
         print(f"\n{GREEN}✅ Dry-run completed successfully. Zero changes written to disk.{RESET}\n")
         return 0
 
     # 2. Ensure PROJECT_AI_GUIDE.md & PROJECT_STATE.md
     print(f"{BOLD}[1/5] Checking Project AI Guide & State Anchor...{RESET}")
-    guide_created = ensure_project_ai_guide(target_repo, stack_info, profile=profile)
+    ensure_project_ai_guide(target_repo, stack_info, profile=profile)
     project_state.init_state(target_repo)
 
     # 3. Deploy Universal AI Bridges (Cursor, Claude Code, GitHub Copilot, Windsurf)
     print(f"\n{BOLD}[2/5] Deploying Universal AI Bridges (Cursor, Claude, Copilot, Windsurf)...{RESET}")
-    bridges_deployed = install_universal_ai_bridges(target_repo)
+    install_universal_ai_bridges(target_repo)
 
     # 4. Inject Antigravity Global Plugin
     plugin_injected = False
@@ -687,7 +685,7 @@ def run_setup(target_repo, dry_run=False, profile="auto", no_global=True, no_git
     print(f"  Target Framework    : {stack_info['framework']}")
     print(f"  Active Profile      : {profile.upper()}")
     print(f"  AI Project Guide    : {os.path.join(target_repo, 'PROJECT_AI_GUIDE.md')}")
-    print(f"  Universal Bridges   : Cursor (.cursor/rules), Claude Code, Copilot, Windsurf")
+    print("  Universal Bridges   : Cursor (.cursor/rules), Claude Code, Copilot, Windsurf")
     print(f"  Antigravity Plugin  : {'ACTIVE (~/.gemini/config/plugins/synapse-hub)' if plugin_injected else 'STANDALONE'}")
     print(f"  AST Method Map      : {os.path.join(target_repo, 'repo_map.txt')}")
     print(f"  Health Report       : {os.path.join(target_repo, 'PROJECT_HEALTH_REPORT.md')}")

package/tools/skill_collision_guard.py

@@ -23,8 +23,8 @@ import sys
 import re
 import math
 import json
+from typing import Dict, List, Tuple, Any
 import argparse
-from typing import Dict, List, Tuple
 from collections import Counter
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -136,7 +136,7 @@ class SkillCollisionGuard:
         fallback_name = os.path.basename(os.path.dirname(path))
         return fallback_name, ""
 
-    def audit(self) -> Tuple[bool, List[Dict[str, any]]]:
+    def audit(self) -> Tuple[bool, List[Dict[str, Any]]]:
         """
         Computes pairwise similarity.
         Returns (is_clean, report_items).
@@ -211,7 +211,7 @@ def run_guard(skills_dir: str = ".agents/skills", threshold: float = 0.75, warn_
         print("=" * 70 + "\n")
         return 1
 
-    print(f"\n✅ [PASS] 0 routing collisions detected. All skill descriptions uniquely segmented.\n")
+    print("\n✅ [PASS] 0 routing collisions detected. All skill descriptions uniquely segmented.\n")
     print("=" * 70 + "\n")
     return 0
 

package/tools/skill_vault.py

@@ -22,7 +22,7 @@ import json
 import re
 import difflib
 import argparse
-from dataclasses import dataclass, asdict
+from dataclasses import dataclass
 from typing import List, Optional, Dict, Any, Set
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -101,6 +101,15 @@ class PageClassPrimitive:
     tags: str = ""            # Comma-separated domain tags, e.g. "auth,sso,login"
 
 
+class ManagedConnection(sqlite3.Connection):
+    """SQLite connection that automatically commits/rollbacks and closes on context exit."""
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            super().__exit__(exc_type, exc_val, exc_tb)
+        finally:
+            self.close()
+
+
 class SkillVault:
     """Persistent library of verified, self-contained Page Class methods."""
 
@@ -113,8 +122,8 @@ class SkillVault:
         self.db_path = db_path
         self._init_schema()
 
-    def _get_connection(self) -> sqlite3.Connection:
-        conn = sqlite3.connect(self.db_path)
+    def _get_connection(self) -> ManagedConnection:
+        conn = sqlite3.connect(self.db_path, factory=ManagedConnection)
         conn.row_factory = sqlite3.Row
         return conn
 

package/tools/skillspector.py

@@ -42,17 +42,15 @@ Usage:
 from __future__ import annotations
 
 import ast
-import fnmatch
 import hashlib
 import json
 import os
 import re
 import sys
-import unicodedata
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Set, Tuple
+from typing import Any, Dict, List, Tuple
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, "reconfigure"):
@@ -529,9 +527,9 @@ def scan_text_patterns(file_path: str, content: str) -> List[Finding]:
     # Line number offset indexing
     line_offsets = []
     curr = 0
-    for l in lines:
+    for line_str in lines:
         line_offsets.append(curr)
-        curr += len(l)
+        curr += len(line_str)
 
     def get_line_num(char_idx: int) -> int:
         for idx, offset in enumerate(line_offsets):
@@ -925,7 +923,7 @@ def scan_file(file_path: str) -> List[Finding]:
     try:
         with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
             content = f.read()
-    except Exception as e:
+    except Exception:
         return []
 
     findings: List[Finding] = []
@@ -1013,7 +1011,7 @@ def format_terminal(report: ScanReport) -> str:
     out.append(f"{BOLD}{CYAN}======================================================================{RESET}")
     out.append(f"📁 Target Scope   : {report.target_path}")
     out.append(f"📄 Scanned Files  : {report.scanned_files}")
-    out.append(f"🛡️  Engine Source  : NVIDIA/SkillSpector Spec (71 Patterns, 17 Categories)")
+    out.append("🛡️  Engine Source  : NVIDIA/SkillSpector Spec (71 Patterns, 17 Categories)")
 
     rec_color = GREEN if report.recommendation == Recommendation.SAFE else (YELLOW if report.recommendation == Recommendation.CAUTION else RED)
     out.append(f"\n{BOLD}🎯 AUDIT VERDICT :{RESET} {rec_color}{BOLD}{report.recommendation.value}{RESET}")