synapse-hub 2.7.0 → 3.0.1

package/tools/output_formatter.py

@@ -58,26 +58,32 @@ class Colors:
 
     @classmethod
     def cyan(cls, text: str) -> str:
+        """Wraps text with ANSI cyan color if color output is enabled."""
         return f"{cls._c(cls.CYAN)}{text}{cls._c(cls.RESET)}"
 
     @classmethod
     def green(cls, text: str) -> str:
+        """Wraps text with ANSI green color if color output is enabled."""
         return f"{cls._c(cls.GREEN)}{text}{cls._c(cls.RESET)}"
 
     @classmethod
     def yellow(cls, text: str) -> str:
+        """Wraps text with ANSI yellow color if color output is enabled."""
         return f"{cls._c(cls.YELLOW)}{text}{cls._c(cls.RESET)}"
 
     @classmethod
     def red(cls, text: str) -> str:
+        """Wraps text with ANSI red color if color output is enabled."""
         return f"{cls._c(cls.RED)}{text}{cls._c(cls.RESET)}"
 
     @classmethod
     def bold(cls, text: str) -> str:
+        """Wraps text with ANSI bold weight if color output is enabled."""
         return f"{cls._c(cls.BOLD)}{text}{cls._c(cls.RESET)}"
 
     @classmethod
     def dim(cls, text: str) -> str:
+        """Wraps text with ANSI dim intensity if color output is enabled."""
         return f"{cls._c(cls.DIM)}{text}{cls._c(cls.RESET)}"
 
 
@@ -85,27 +91,34 @@ class OutputFormatter:
     """Standardized console & machine-readable output renderer."""
 
     def __init__(self, quiet: bool = False, json_mode: bool = False, verbose: bool = False):
+        """Initializes the output formatter with verbosity and mode toggles."""
         self.quiet = quiet
         self.json_mode = json_mode
         self.verbose = verbose
 
     def debug(self, message: str):
+        """Prints a debug message when verbose mode is active."""
         if self.verbose and not self.quiet and not self.json_mode:
             print(f"{Colors.dim('🔍 [DEBUG]')} {message}")
 
     def info(self, message: str):
+        """Alias for info_msg printing informational text."""
         self.info_msg(message)
 
     def warn(self, message: str):
+        """Alias for warn_msg printing warning text."""
         self.warn_msg(message)
 
     def error(self, message: str):
+        """Alias for fail_msg printing failure/error text."""
         self.fail_msg(message)
 
     def success(self, message: str):
+        """Alias for pass_msg printing passing/success text."""
         self.pass_msg(message)
 
     def header(self, title: str):
+        """Renders an eye-catching framed header box for CLI stages."""
         if not self.quiet and not self.json_mode:
             border = "=" * 70
             print(f"\n{Colors.cyan(border)}")
@@ -113,26 +126,32 @@ class OutputFormatter:
             print(f"{Colors.cyan(border)}\n")
 
     def step(self, current: int, total: int, title: str):
+        """Prints a numbered step indicator for multi-phase operations."""
         if not self.quiet and not self.json_mode:
             print(f"{Colors.bold(f'[{current}/{total}]')} {title}")
 
     def pass_msg(self, message: str):
+        """Prints a green checkmark pass badge with the given message."""
         if not self.json_mode:
             print(f"{Colors.green('✅ [PASS]')} {message}")
 
     def fail_msg(self, message: str):
+        """Prints a red cross fail badge with the given message."""
         if not self.json_mode:
             print(f"{Colors.red('❌ [FAIL]')} {message}")
 
     def warn_msg(self, message: str):
+        """Prints a yellow warning badge with the given message."""
         if not self.quiet and not self.json_mode:
             print(f"{Colors.yellow('⚠️  [WARN]')} {message}")
 
     def info_msg(self, message: str):
+        """Prints a cyan informational badge with the given message."""
         if not self.quiet and not self.json_mode:
             print(f"{Colors.cyan('ℹ️  [INFO]')} {message}")
 
     def print_data(self, data: Any, format_type: str = "text"):
+        """Formats and outputs data payload as either indented JSON or raw text."""
         if format_type == "json" or self.json_mode:
             if isinstance(data, (dict, list)):
                 print(json.dumps(data, indent=2, ensure_ascii=False))

package/tools/perf/__init__.py

@@ -0,0 +1,24 @@
+"""
+Synapse Hub — Performance, Stress & Flakiness Profilers (tools.perf)
+---------------------------------------------------------------------
+Domain package grouping all JMeter test plan generators, flakiness
+sentinels, BFCL agent gym benchmarks, and test matrix sharders.
+"""
+
+from tools import (
+    browsergym_eval,
+    db_sandbox,
+    flaky_detector,
+    generate_jmx_plan,
+    matrix_sharder,
+    synapse_qa_bench,
+)
+
+__all__ = [
+    "browsergym_eval",
+    "db_sandbox",
+    "flaky_detector",
+    "generate_jmx_plan",
+    "matrix_sharder",
+    "synapse_qa_bench",
+]

package/tools/pinpoint_failure.py

@@ -58,7 +58,7 @@ def parse_failures(xml_path):
                 if reason_match:
                     reason = reason_match.group(1).strip()
                 else:
-                    lines = [l.strip() for l in combined.split("\n") if l.strip()]
+                    lines = [line.strip() for line in combined.split("\n") if line.strip()]
                     reason = lines[0] if lines else "Unknown Error"
 
                 # Extract Failed Line in Groovy Page / Script

package/tools/project_state.py

@@ -8,9 +8,7 @@ Enforces a strict Rolling Window (< 50 lines, ~200 tokens) to guarantee zero tok
 
 import os
 import sys
-import json
 from datetime import datetime
-from pathlib import Path
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):

package/tools/qa_event_stream.py

@@ -25,7 +25,7 @@ import json
 import hashlib
 import argparse
 from datetime import datetime, timezone
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, Optional
 
 # Enforce UTF-8 stdout encoding
 if hasattr(sys.stdout, 'reconfigure'):

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'):
@@ -61,7 +60,7 @@ class ExecutionSandbox:
         """Executes a forward shell command and immediately records its reversible undo counterpart."""
         try:
             args = shlex.split(forward_cmd) if isinstance(forward_cmd, str) else forward_cmd
-            res = subprocess.run(args, text=True, capture_output=True)
+            res = subprocess.run(args, text=True, capture_output=True, timeout=60.0)
             if res.returncode == 0:
                 self.record_mutation(action_type, target_resource, undo_cmd, {"forward_cmd": forward_cmd})
                 return True
@@ -98,7 +97,7 @@ class ExecutionSandbox:
             elif cmd:
                 try:
                     args = shlex.split(cmd) if isinstance(cmd, str) else cmd
-                    res = subprocess.run(args, text=True, capture_output=True)
+                    res = subprocess.run(args, text=True, capture_output=True, timeout=60.0)
                     success = (res.returncode == 0)
                     if not success:
                         err_msg = res.stderr.strip()

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:
@@ -80,10 +80,11 @@ def get_git_diff(repo_dir: str, target: str = "uncommitted") -> str:
             text=True,
             encoding="utf-8",
             errors="ignore",
-            check=True
+            check=True,
+            timeout=30.0
         )
         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
@@ -50,11 +50,25 @@ QA_SYNONYMS: Dict[str, Set[str]] = {
     "dropdown": {"select", "combobox", "option", "menu", "picker", "choice"},
     "invoice": {"billing", "order", "receipt", "payment", "charge", "reconcile"},
     "cart": {"checkout", "basket", "purchase", "item", "order"},
-    "upload": {"attachment", "file", "import", "choose-file", "document"},
+    "upload": {"attachment", "file", "import", "choose-file", "document", "dropzone"},
+    "export": {"export", "download", "csv", "excel", "pdf", "report"},
+    "toast": {"toast", "notification", "snackbar", "alert", "message", "banner", "popup"},
+    "spinner": {"spinner", "loader", "loading", "shimmer", "skeleton", "progress", "wait"},
+    "drawer": {"drawer", "sidebar", "panel", "modal", "aside", "sheet"},
+    "tab": {"tab", "tabs", "tabpanel", "nav", "segment"},
     "wait": {"detach", "detached", "sleep", "loading", "spinner", "ready", "networkidle", "smartwait"},
 }
 
 
+def split_identifier(identifier: str) -> List[str]:
+    """Splits camelCase, PascalCase, and snake_case tokens into lowercase sub-tokens."""
+    tokens = re.sub(r'([A-Z]+)', r' \1', identifier).split()
+    sub_tokens = []
+    for t in tokens:
+        sub_tokens.extend(re.split(r'[_\\-]+', t))
+    return [t.lower() for t in sub_tokens if len(t) >= 2]
+
+
 def _expand_tokens_with_synonyms(tokens: List[str]) -> Set[str]:
     """Expands query tokens using the QA domain synonym clusters."""
     expanded = set(tokens)
@@ -101,6 +115,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 +136,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
 
@@ -176,7 +199,13 @@ class SkillVault:
         Queries verified primitives using intelligent fuzzy semantic matching:
         combines exact tokens, synonym expansion, n-gram substring match, and SequenceMatcher similarity.
         """
-        raw_tokens = [t.lower() for t in re.findall(r'[a-zA-Z0-9_-]+', query) if len(t) >= 2]
+        words = re.findall(r'[a-zA-Z0-9_-]+', query)
+        raw_tokens = []
+        for w in words:
+            sub = split_identifier(w)
+            raw_tokens.extend(sub if sub else [w.lower()])
+        raw_tokens = list(dict.fromkeys(raw_tokens))
+
         if not raw_tokens and not tag:
             return self.list_primitives(limit=top_k)
 
@@ -194,7 +223,12 @@ class SkillVault:
         scored = []
         for r in rows:
             corpus_text = f"{r['page_class']} {r['method_signature']} {r['semantic_docstring'] or ''} {r['tags'] or ''}".lower()
-            corpus_tokens = [t.lower() for t in re.findall(r'[a-zA-Z0-9_-]+', corpus_text) if len(t) >= 2]
+            corpus_words = re.findall(r'[a-zA-Z0-9_-]+', corpus_text)
+            corpus_tokens = []
+            for cw in corpus_words:
+                sub = split_identifier(cw)
+                corpus_tokens.extend(sub if sub else [cw.lower()])
+            corpus_tokens = list(dict.fromkeys(corpus_tokens))
 
             # Calculate individual query token matches
             token_scores = [_calculate_token_match_score(qt, corpus_tokens) for qt in raw_tokens]
@@ -220,6 +254,54 @@ class SkillVault:
         scored.sort(key=lambda x: (x["relevance_score"], x["mutation_score"]), reverse=True)
         return scored[:top_k]
 
+    def harvest_page_classes(self, dir_path: str) -> int:
+        """
+        Scans a directory for Page Classes across TS, JS, Python, and Groovy,
+        extracts method signatures, and registers them into SkillVault.
+        """
+        if not os.path.isdir(dir_path):
+            return 0
+        count = 0
+        for root, _, files in os.walk(dir_path):
+            for f in files:
+                ext = os.path.splitext(f)[1].lower()
+                if ext not in (".py", ".ts", ".js", ".groovy", ".java"):
+                    continue
+                file_path = os.path.join(root, f)
+                try:
+                    with open(file_path, "r", encoding="utf-8", errors="ignore") as fp:
+                        content = fp.read()
+                except OSError:
+                    continue
+
+                page_class = os.path.splitext(f)[0]
+                method_matches = re.finditer(r'(?:def\s+([a-zA-Z_]\w*)\s*\(([^)]*)\)|(?:async\s+)?([a-zA-Z_]\w*)\s*\(([^)]*)\)\s*(?::\s*[^\{]+)?\s*\{)', content)
+                for mm in method_matches:
+                    m_name = mm.group(1) or mm.group(3)
+                    m_args = mm.group(2) if mm.group(1) else mm.group(4)
+                    if not m_name or m_name.startswith("_") or m_name in ("constructor", "constructor__"):
+                        continue
+                    skill_id = f"SKILL_{page_class.upper()}_{m_name.upper()}"
+                    sig = f"{m_name}({m_args.strip() if m_args else ''})"
+                    doc_m = re.search(rf'{re.escape(m_name)}[^\n]*\n\s*[\'\""""/]+([^\'\""""\n*]+)', content)
+                    doc = doc_m.group(1).strip() if doc_m else f"Page method for {m_name} on {page_class}"
+                    tags = ",".join(split_identifier(page_class) + split_identifier(m_name))
+
+                    prim = PageClassPrimitive(
+                        skill_id=skill_id,
+                        page_class=page_class,
+                        method_signature=sig,
+                        method_code=f"// Harvested from {f}\n{sig}",
+                        locator_tier=1,
+                        semantic_docstring=doc,
+                        verified_on_url=f"local://{f}",
+                        mutation_score=85.0,
+                        tags=tags
+                    )
+                    if self.register_primitive(prim):
+                        count += 1
+        return count
+
     def list_primitives(self, limit: int = 50) -> List[Dict[str, Any]]:
         with self._get_connection() as conn:
             rows = conn.execute("SELECT * FROM page_primitives ORDER BY created_at DESC LIMIT ?", (limit,)).fetchall()
@@ -230,12 +312,18 @@ def main():
     parser = argparse.ArgumentParser(description="SkillVault Lifelong POM Library")
     parser.add_argument("--query", default=None, help="Query verified primitives by keyword (fuzzy semantic search)")
     parser.add_argument("--tag", default=None, help="Filter primitives by domain tag (e.g. auth, table, invoice)")
+    parser.add_argument("--harvest", default=None, help="Directory path to harvest Page Classes from")
     parser.add_argument("--list", action="store_true", help="List all stored primitives")
     parser.add_argument("--seed-samples", action="store_true", help="Seed initial verified POM primitives")
     args = parser.parse_args()
 
     vault = SkillVault()
 
+    if args.harvest:
+        num = vault.harvest_page_classes(args.harvest)
+        print(f"✅ Harvested {num} Page Class primitives from '{args.harvest}'.")
+        return 0
+
     if args.seed_samples:
         samples = [
             PageClassPrimitive(

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] = []
@@ -958,7 +956,11 @@ def scan_target(target_path: str) -> ScanReport:
     all_findings: List[Finding] = []
     scanned_count = 0
 
-    SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", ".pytest_cache", "dist", "build"}
+    SKIP_DIRS = {
+        ".git", ".venv", "venv", "node_modules", "__pycache__", ".pytest_cache",
+        "dist", "build", "claude-ecosystem-repos", "graphify-out", ".synapse",
+        ".mypy_cache", ".ruff_cache", ".sandbox_snapshots", "reports"
+    }
     SKIP_FILES = {"skillspector.py"}
     SCANNABLE_EXTS = {".md", ".py", ".json", ".yaml", ".yml", ".sh", ".ps1", ".txt", ".ts", ".js"}
 
@@ -1013,7 +1015,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}")