@teevee98/synapse-hub 4.1.3 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +6 -1
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +6 -1
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +8 -3
  5. package/.agents/skills/01-web-automation/clean-pom-crafter/examples/standard_test_case.groovy +3 -0
  6. package/.agents/skills/01-web-automation/clean-pom-crafter/references/pom_patterns.groovy +3 -0
  7. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/e2e-testing-patterns/examples/playwright_sharded_config.ts +3 -0
  9. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  10. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  11. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  12. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  13. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  14. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  15. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +7 -2
  16. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  17. package/.agents/skills/01-web-automation/playwright-webapp-testing/examples/server_lifecycle_playwright.py +3 -0
  18. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  19. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  20. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  21. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  22. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  23. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  24. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  25. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  26. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  27. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  28. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  29. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  30. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +3 -0
  31. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  32. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/references/dast_recipes.ts +3 -0
  33. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  34. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  38. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  39. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  40. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  41. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  42. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  43. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  44. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  45. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  46. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  48. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +3 -0
  49. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +3 -0
  50. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  51. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  52. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  53. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  54. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  55. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  56. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  57. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  58. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  59. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  60. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  61. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  62. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  63. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  64. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  65. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/examples/surgical_code_window_walkthrough.md +1 -1
  66. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  67. package/AGENTS.md +7 -1
  68. package/LICENSE +5 -5
  69. package/NOTICE +1 -1
  70. package/README.en.md +4 -4
  71. package/README.md +4 -4
  72. package/agentskills.json +1 -1
  73. package/docs/ARCHITECTURE.en.md +2 -2
  74. package/docs/ARCHITECTURE.md +11 -2
  75. package/docs/CLI_REFERENCE.en.md +6 -4
  76. package/docs/CLI_REFERENCE.md +1 -1
  77. package/docs/CONTRIBUTING.en.md +1 -1
  78. package/docs/CONTRIBUTING.md +2 -2
  79. package/docs/PERFORMANCE_AUDIT_REPORT.md +2 -2
  80. package/docs/TOOL_CATALOG.md +6 -2
  81. package/docs/research/agent_skill_training_analysis.md +1 -1
  82. package/package.json +1 -1
  83. package/plugin.json +1 -1
  84. package/scripts/generate_skill_examples.py +3 -0
  85. package/scripts/package_dist.py +3 -0
  86. package/skills_manifest.json +320 -55
  87. package/synapse.config.json +1 -1
  88. package/templates/ui/index.html +2 -2
  89. package/tools/.infer_baseline.json +3 -796
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +4 -1
  92. package/tools/agent_canary.py +3 -0
  93. package/tools/analyze_project.py +3 -0
  94. package/tools/api_drift_sentinel.py +3 -0
  95. package/tools/api_fuzzer.py +182 -118
  96. package/tools/ast_cache.py +4 -2
  97. package/tools/author_integrity.py +174 -12
  98. package/tools/auto_heal.py +7 -2
  99. package/tools/autogen_qa_broker.py +14 -15
  100. package/tools/benchmark_swarm_context.py +119 -18
  101. package/tools/break_ui_generator.py +233 -0
  102. package/tools/browser_helpers.js +2 -2
  103. package/tools/bug_reporter.py +3 -0
  104. package/tools/build_consolidated_report.py +3 -0
  105. package/tools/bump_version.py +4 -1
  106. package/tools/cache_resolver.py +7 -3
  107. package/tools/check_env.py +3 -0
  108. package/tools/check_version_sync.py +21 -50
  109. package/tools/ci_healing_hook.py +3 -0
  110. package/tools/cli.py +116 -22
  111. package/tools/config_decoupler.py +3 -0
  112. package/tools/core/__init__.py +3 -0
  113. package/tools/core/bm25_retriever.py +218 -0
  114. package/tools/core/file_lock.py +23 -14
  115. package/tools/core/i18n.py +13 -11
  116. package/tools/core/memory_bus.py +6 -3
  117. package/tools/core/process_supervisor.py +28 -18
  118. package/tools/core/provider_usage_adapter.py +317 -0
  119. package/tools/core/token_estimator.py +83 -18
  120. package/tools/count_tokens.py +16 -7
  121. package/tools/coverage_reporter.py +245 -0
  122. package/tools/create_mock_docx.py +3 -0
  123. package/tools/dashboard_generator.py +17 -15
  124. package/tools/db_sandbox.py +150 -5
  125. package/tools/debt_harvester.py +2 -2
  126. package/tools/diagram_architect.py +3 -0
  127. package/tools/distill_log.py +22 -2
  128. package/tools/distill_skill.py +191 -0
  129. package/tools/e2e_flow_prober.py +3 -0
  130. package/tools/export_postman_collection.py +3 -0
  131. package/tools/flaky_detector.py +3 -0
  132. package/tools/fsm_enforcer.py +2 -2
  133. package/tools/fuzz_payloads.py +3 -0
  134. package/tools/generate_allure_report.py +3 -0
  135. package/tools/generate_api_matrix.py +3 -0
  136. package/tools/generate_jmx_plan.py +3 -0
  137. package/tools/generate_tc_from_story.py +3 -0
  138. package/tools/generate_test_reports.py +3 -0
  139. package/tools/git_pre_commit_guard.py +25 -3
  140. package/tools/git_worktree_manager.py +3 -0
  141. package/tools/heal/__init__.py +3 -0
  142. package/tools/heal_pr_automator.py +3 -0
  143. package/tools/heuristic_locator_matcher.py +3 -0
  144. package/tools/hub_publisher.py +3 -3
  145. package/tools/humanize_linter.py +3 -0
  146. package/tools/infer_linter.py +19 -9
  147. package/tools/init_config.py +6 -9
  148. package/tools/jtl_analyzer.py +3 -0
  149. package/tools/lint/__init__.py +3 -0
  150. package/tools/lint_ai_docs.py +3 -0
  151. package/tools/lookup_tc.py +3 -0
  152. package/tools/lookup_xpath.py +3 -0
  153. package/tools/matrix_sharder.py +3 -0
  154. package/tools/mcp/__init__.py +3 -0
  155. package/tools/mcp_docx_server.py +1 -1
  156. package/tools/mcp_excel_server.py +4 -1
  157. package/tools/mcp_server.py +78 -15
  158. package/tools/md_to_xlsx.py +3 -0
  159. package/tools/mechanical_ui_gate.py +3 -0
  160. package/tools/micro_mutator.py +93 -19
  161. package/tools/network_mock_shield.py +3 -0
  162. package/tools/newman_analyzer.py +3 -0
  163. package/tools/omni_emitter.py +3 -0
  164. package/tools/omni_parser.py +3 -0
  165. package/tools/omni_transpiler.py +3 -0
  166. package/tools/output_formatter.py +3 -0
  167. package/tools/package_release.py +6 -6
  168. package/tools/pairwise_generator.py +3 -0
  169. package/tools/pentest_scope_guard.py +401 -58
  170. package/tools/perf/__init__.py +3 -0
  171. package/tools/perf/benchmark_perf_runner.py +42 -0
  172. package/tools/pinpoint_failure.py +3 -0
  173. package/tools/project_state.py +3 -0
  174. package/tools/repo_map.py +3 -0
  175. package/tools/report/__init__.py +3 -0
  176. package/tools/rules_router.py +426 -34
  177. package/tools/runaway_stopper.py +3 -0
  178. package/tools/safety_firewall.py +3 -0
  179. package/tools/security_scanner.py +80 -0
  180. package/tools/senior_code_review.py +14 -0
  181. package/tools/setup_project.py +9 -4
  182. package/tools/skill_canonical_digest.py +244 -0
  183. package/tools/skill_collision_guard.py +2 -2
  184. package/tools/skill_profiles.py +77 -7
  185. package/tools/skillspector.py +2 -1
  186. package/tools/slide_deck_exporter.py +477 -0
  187. package/tools/smart_visual_masker.py +3 -0
  188. package/tools/sync_skills_manifest.py +166 -0
  189. package/tools/task_memory_manager.py +260 -0
  190. package/tools/telemetry_correlator.py +3 -0
  191. package/tools/template_excel_exporter.py +2 -2
  192. package/tools/test_impact.py +3 -0
  193. package/tools/trace_data_flow.py +3 -0
  194. package/tools/traffic_session_converter.py +3 -0
  195. package/tools/ui_server.py +2 -2
  196. package/tools/universal_ir.py +3 -0
  197. package/tools/update_sentinel.py +15 -9
  198. package/tools/validate_groovy_scripts.py +3 -0
  199. package/tools/validate_host_interop.py +485 -0
  200. package/tools/validate_skills_schema.py +282 -0
  201. package/tools/verify_all.py +600 -63
  202. package/tools/visual_diff_canvas.py +3 -0
  203. package/tools/visual_som_helper.py +3 -0
  204. package/tools/watch_mode.py +4 -4
  205. package/tools/wcag_audit.py +3 -0
  206. package/tools/welcome_page.py +2 -2
@@ -0,0 +1,218 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ # -*- coding: utf-8 -*-
6
+ """
7
+ tools/core/bm25_retriever.py — Zero-Dependency Pure Python BM25 Knowledge Retriever
8
+ Inspired by nextlevelbuilder/ui-ux-pro-max-skill core.py algorithm.
9
+ Enables instant sub-millisecond retrieval of guidelines, rules, and QA patterns
10
+ with zero external dependencies and guaranteed < 300 character truncation (95% token savings).
11
+ 100% UTF-8 No BOM.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import json
18
+ import math
19
+ import os
20
+ import re
21
+ import sys
22
+ from collections import Counter
23
+ from typing import Any, Dict, List, Tuple
24
+
25
+ # Enforce UTF-8 stdout encoding
26
+ if hasattr(sys.stdout, "reconfigure"):
27
+ try:
28
+ sys.stdout.reconfigure(encoding="utf-8")
29
+ sys.stderr.reconfigure(encoding="utf-8")
30
+ except Exception:
31
+ pass
32
+
33
+ TRUNCATE_AT: int = 300
34
+
35
+ # Common English / QA stopwords
36
+ STOPWORDS: set[str] = {
37
+ "a", "an", "the", "and", "or", "in", "on", "at", "to", "for", "with",
38
+ "by", "of", "from", "is", "are", "was", "were", "be", "been", "being",
39
+ "have", "has", "had", "do", "does", "did", "this", "that", "these",
40
+ "those", "it", "its", "as", "if", "each", "which", "into", "than", "then"
41
+ }
42
+
43
+ # Domain acronyms & synonym expansion mapping
44
+ SYNONYMS: Dict[str, List[str]] = {
45
+ "pom": ["page", "object", "model", "locator"],
46
+ "a11y": ["accessibility", "wcag", "aria", "contrast"],
47
+ "perf": ["performance", "latency", "p95", "throughput", "jmeter", "k6"],
48
+ "sec": ["security", "credential", "sarif", "cwe", "vuln"],
49
+ "fsm": ["finite", "state", "machine", "stage", "lifecycle"],
50
+ "dod": ["definition", "done", "gate", "verify", "quality"],
51
+ "ast": ["abstract", "syntax", "tree", "mutation", "linter"],
52
+ }
53
+
54
+
55
+ def tokenize(text: str) -> List[str]:
56
+ """Tokenizes text into lowercase alphanumeric tokens, filtering stopwords."""
57
+ if not text:
58
+ return []
59
+ words = re.findall(r"[a-zA-Z0-9_]+", text.lower())
60
+ tokens: List[str] = []
61
+ for w in words:
62
+ if len(w) > 1 and w not in STOPWORDS:
63
+ tokens.append(w)
64
+ if w in SYNONYMS:
65
+ tokens.extend(SYNONYMS[w])
66
+ return tokens
67
+
68
+
69
+ class BM25Document:
70
+ """Represents an indexed document with precomputed tokens."""
71
+
72
+ def __init__(self, doc_id: str, title: str, content: str, source: str = ""):
73
+ self.doc_id = doc_id
74
+ self.title = title
75
+ self.content = content
76
+ self.source = source
77
+ self.tokens = tokenize(f"{title} {content}")
78
+ self.length = len(self.tokens)
79
+ self.term_freqs = Counter(self.tokens)
80
+
81
+ def snippet(self, max_len: int = TRUNCATE_AT) -> str:
82
+ """Returns a trimmed snippet bounded by max_len."""
83
+ cleaned = re.sub(r"\s+", " ", self.content).strip()
84
+ if len(cleaned) <= max_len:
85
+ return cleaned
86
+ return cleaned[:max_len].rstrip() + "..."
87
+
88
+
89
+ class BM25Index:
90
+ """
91
+ Rank BM25 search index using the Okapi BM25 formula:
92
+ IDF(q) = ln((N - n(q) + 0.5) / (n(q) + 0.5) + 1)
93
+ Score = sum(IDF(q) * (f(q, D) * (k1 + 1)) / (f(q, D) + k1 * (1 - b + b * (|D| / avgdl))))
94
+ """
95
+
96
+ def __init__(self, k1: float = 1.5, b: float = 0.75):
97
+ self.k1 = k1
98
+ self.b = b
99
+ self.documents: List[BM25Document] = []
100
+ self.doc_count: int = 0
101
+ self.avg_doc_len: float = 0.0
102
+ self.doc_freqs: Counter[str] = Counter()
103
+ self.idf_cache: Dict[str, float] = {}
104
+
105
+ def add_document(self, doc_id: str, title: str, content: str, source: str = "") -> None:
106
+ """Adds a single document to the index."""
107
+ doc = BM25Document(doc_id, title, content, source)
108
+ self.documents.append(doc)
109
+ self.doc_count = len(self.documents)
110
+
111
+ def build(self) -> None:
112
+ """Finalizes the index, computes average document length and IDF scores."""
113
+ self.doc_freqs.clear()
114
+ total_len = 0
115
+ for doc in self.documents:
116
+ total_len += doc.length
117
+ for token in set(doc.tokens):
118
+ self.doc_freqs[token] += 1
119
+
120
+ self.avg_doc_len = (total_len / self.doc_count) if self.doc_count > 0 else 0.0
121
+
122
+ # Precompute IDF
123
+ self.idf_cache.clear()
124
+ for token, df in self.doc_freqs.items():
125
+ # Robertson-Spärck Jones IDF formula with +1 smoothing
126
+ idf = math.log(((self.doc_count - df + 0.5) / (df + 0.5)) + 1.0)
127
+ self.idf_cache[token] = max(idf, 0.0)
128
+
129
+ def search(
130
+ self, query: str, top_k: int = 3, truncate_at: int = TRUNCATE_AT
131
+ ) -> List[Dict[str, Any]]:
132
+ """Searches documents matching the query and returns top_k ranked results."""
133
+ if not self.documents:
134
+ return []
135
+
136
+ query_tokens = tokenize(query)
137
+ if not query_tokens:
138
+ return []
139
+
140
+ scores: List[Tuple[float, BM25Document]] = []
141
+ for doc in self.documents:
142
+ if doc.length == 0:
143
+ continue
144
+ score = 0.0
145
+ doc_len_ratio = doc.length / self.avg_doc_len if self.avg_doc_len > 0 else 1.0
146
+ len_norm = 1.0 - self.b + self.b * doc_len_ratio
147
+
148
+ for q in query_tokens:
149
+ if q in doc.term_freqs:
150
+ freq = doc.term_freqs[q]
151
+ idf = self.idf_cache.get(q, 0.0)
152
+ numerator = freq * (self.k1 + 1.0)
153
+ denominator = freq + self.k1 * len_norm
154
+ score += idf * (numerator / denominator)
155
+
156
+ if score > 0.0:
157
+ scores.append((score, doc))
158
+
159
+ scores.sort(key=lambda x: x[0], reverse=True)
160
+
161
+ results: List[Dict[str, Any]] = []
162
+ for rank, (score, doc) in enumerate(scores[:top_k], start=1):
163
+ results.append({
164
+ "rank": rank,
165
+ "score": round(score, 4),
166
+ "doc_id": doc.doc_id,
167
+ "title": doc.title,
168
+ "snippet": doc.snippet(truncate_at),
169
+ "source": doc.source,
170
+ })
171
+ return results
172
+
173
+
174
+ def index_directory(dir_path: str, extensions: Tuple[str, ...] = (".md", ".txt")) -> BM25Index:
175
+ """Indexes all files with matching extensions under dir_path."""
176
+ index = BM25Index()
177
+ if not os.path.exists(dir_path):
178
+ return index
179
+
180
+ for root, _, files in os.walk(dir_path):
181
+ for f in files:
182
+ if any(f.endswith(ext) for ext in extensions):
183
+ full_path = os.path.join(root, f)
184
+ try:
185
+ with open(full_path, "r", encoding="utf-8", errors="replace") as fp:
186
+ content = fp.read()
187
+ rel_path = os.path.relpath(full_path, dir_path)
188
+ title = f.replace(".md", "").replace("_", " ").title()
189
+ index.add_document(doc_id=rel_path, title=title, content=content, source=full_path)
190
+ except OSError:
191
+ continue
192
+
193
+ index.build()
194
+ return index
195
+
196
+
197
+ def main() -> None:
198
+ parser = argparse.ArgumentParser(description="BM25 Knowledge Retriever for Synapse Hub")
199
+ parser.add_argument("--query", "-q", type=str, required=True, help="Search query string")
200
+ parser.add_argument("--dir", "-d", type=str, default=".agents/rules", help="Directory to search (default: .agents/rules)")
201
+ parser.add_argument("--top-k", "-k", type=int, default=3, help="Number of results to return (default: 3)")
202
+ parser.add_argument("--json", action="store_true", help="Output results in JSON format")
203
+ args = parser.parse_args()
204
+
205
+ index = index_directory(args.dir)
206
+ results = index.search(args.query, top_k=args.top_k)
207
+
208
+ if args.json:
209
+ print(json.dumps(results, indent=2, ensure_ascii=False))
210
+ else:
211
+ print(f"🔍 BM25 Search Results for: '{args.query}' in '{args.dir}' (Found: {len(results)})")
212
+ for res in results:
213
+ print(f"\n[#{res['rank']}] {res['title']} (Score: {res['score']}) -> {res['doc_id']}")
214
+ print(f" {res['snippet']}")
215
+
216
+
217
+ if __name__ == "__main__":
218
+ main()
@@ -87,7 +87,8 @@ def _win32_lock(fd: int, shared: bool = False) -> bool:
87
87
  return True
88
88
  except (AttributeError, TypeError, ValueError) as exc:
89
89
  # Fall through to msvcrt fallback if ctypes kernel32 LockFileEx is missing or incompatible
90
- _ = exc
90
+ import logging
91
+ logging.getLogger("file_lock").debug("LockFileEx fallback to msvcrt: %s", exc)
91
92
 
92
93
  # Graceful fallback to msvcrt.locking (exclusive lock only)
93
94
  if msvcrt_mod is not None:
@@ -117,7 +118,8 @@ def _win32_unlock(fd: int) -> bool:
117
118
  )
118
119
  return bool(res)
119
120
  except (AttributeError, TypeError, ValueError) as exc:
120
- _ = exc
121
+ import logging
122
+ logging.getLogger("file_lock").debug("UnlockFileEx fallback to msvcrt: %s", exc)
121
123
 
122
124
  # Graceful fallback to msvcrt.locking
123
125
  if msvcrt_mod is not None:
@@ -153,8 +155,9 @@ def _is_process_alive(pid: int) -> bool:
153
155
  return True
154
156
  return False
155
157
  except Exception as err:
156
- _ = err
157
- return True
158
+ import logging
159
+ logging.getLogger("file_lock").debug("Stale lock check error: %s", err)
160
+ return True
158
161
 
159
162
 
160
163
  class FileLockTimeoutError(TimeoutError):
@@ -194,8 +197,9 @@ class FileLock:
194
197
  elif content.isdigit():
195
198
  return int(content)
196
199
  except Exception as err:
197
- _ = err
198
- return None
200
+ import logging
201
+ logging.getLogger("file_lock").debug("Failed to read lock holder PID: %s", err)
202
+ return None
199
203
 
200
204
  def acquire(self) -> FileLock:
201
205
  """Acquires the advisory lock, polling until timeout with stale-lock reclamation."""
@@ -216,7 +220,8 @@ class FileLock:
216
220
  if os.fstat(self._fd).st_size == 0:
217
221
  os.write(self._fd, b"\x00")
218
222
  except (OSError, PermissionError) as err:
219
- _ = err
223
+ import logging
224
+ logging.getLogger("file_lock").debug("Win zero-byte write error: %s", err)
220
225
  os.lseek(self._fd, 0, os.SEEK_SET)
221
226
  _win32_lock(self._fd, shared=self.shared)
222
227
 
@@ -226,14 +231,16 @@ class FileLock:
226
231
  os.lseek(self._fd, 0, os.SEEK_SET)
227
232
  os.write(self._fd, f"{os.getpid()}:{int(time.time())}\n".encode("utf-8"))
228
233
  except OSError as err:
229
- _ = err
234
+ import logging
235
+ logging.getLogger("file_lock").debug("PID write error: %s", err)
230
236
  return self
231
237
  except (BlockingIOError, OSError, PermissionError):
232
238
  if self._fd is not None:
233
239
  try:
234
240
  os.close(self._fd)
235
241
  except OSError as err:
236
- _ = err
242
+ import logging
243
+ logging.getLogger("file_lock").debug("PID write error: %s", err)
237
244
  self._fd = None
238
245
 
239
246
  elapsed = time.time() - start
@@ -246,10 +253,10 @@ class FileLock:
246
253
  if os.path.exists(self.lock_path):
247
254
  os.remove(self.lock_path)
248
255
  stale_reclaimed = True
249
- time.sleep(0.02)
256
+ time.sleep(0.02) # synapse-ignore: HARD_DELAY_ANTI_PATTERN
257
+ continue
258
+ except OSError:
250
259
  continue
251
- except OSError as err:
252
- _ = err
253
260
 
254
261
  raise FileLockTimeoutError(
255
262
  f"Timed out after {self.timeout}s waiting for lock on {self.lock_path}"
@@ -266,7 +273,8 @@ class FileLock:
266
273
  _win32_unlock(self._fd)
267
274
  os.close(self._fd)
268
275
  except OSError as err:
269
- _ = err
276
+ import logging
277
+ logging.getLogger("file_lock").debug("FD close on unlock error: %s", err)
270
278
  finally:
271
279
  self._fd = None
272
280
 
@@ -312,7 +320,8 @@ def locked_write(file_path: str, content: str, timeout: float = 10.0, atomic: bo
312
320
  try:
313
321
  os.remove(temp_path)
314
322
  except OSError as err:
315
- _ = err
323
+ import logging
324
+ logging.getLogger("file_lock").debug("PID write error: %s", err)
316
325
  else:
317
326
  with open(file_path, "w", encoding="utf-8") as f:
318
327
  f.write(content)
@@ -26,13 +26,13 @@ MESSAGES: Dict[str, Dict[str, str]] = {
26
26
  "core_commands_title": "🌟 CORE & DAILY WORKFLOWS:",
27
27
  "advanced_highlights_title": "🎯 ADVANCED AI/QA CAPABILITIES:",
28
28
  "general_options_title": "GENERAL OPTIONS:",
29
- "opt_all": "Display all 58+ advanced and infrastructure commands",
29
+ "opt_all": "Display all registered advanced and infrastructure commands",
30
30
  "opt_version": "Show current version and author provenance",
31
31
  "opt_offline": "Force 100% offline air-gapped mode (zero network / LLM calls)",
32
32
  "opt_quiet": "Suppress banner, show only verdict and critical output",
33
33
  "opt_lang": "Set CLI interface language (en: English, vi: Vietnamese)",
34
34
  "tips_header": "💡 Quick Navigation Tips:",
35
- "tip_all": "👉 Run 'agent-qa --help --all' to inspect all 58+ commands.",
35
+ "tip_all": "👉 Run 'agent-qa --help --all' to inspect all registered commands.",
36
36
  "tip_cmd": "👉 Run 'agent-qa <command> --help' for detailed command options.",
37
37
  "tip_welcome": "👉 Run 'agent-qa welcome' to launch the interactive visual landing page.",
38
38
  "tip_lang_switch": "💡 Switch language: agent-qa --lang vi (Vietnamese) | agent-qa --lang en (English)",
@@ -122,13 +122,13 @@ MESSAGES: Dict[str, Dict[str, str]] = {
122
122
  "core_commands_title": "🌟 LỆNH CỐT LÕI & THƯỜNG DÙNG:",
123
123
  "advanced_highlights_title": "🎯 CÁC KHÁI NIỆM AI/QA NÂNG CAO TIÊU BIỂU:",
124
124
  "general_options_title": "TÙY CHỌN CHUNG:",
125
- "opt_all": "Hiển thị toàn bộ 58+ lệnh nâng cao & hạ tầng",
125
+ "opt_all": "Hiển thị toàn bộ các lệnh nâng cao & hạ tầng đã đăng ký",
126
126
  "opt_version": "Hiển thị phiên bản hiện tại và thông tin tác quyền MIT",
127
127
  "opt_offline": "Ép chế độ 100% offline air-gapped (zero network / LLM calls)",
128
128
  "opt_quiet": "Ẩn banner thông tin, chỉ xuất kết quả phán quyết quan trọng",
129
129
  "opt_lang": "Chọn ngôn ngữ hiển thị giao diện CLI (en: Tiếng Anh, vi: Tiếng Việt)",
130
130
  "tips_header": "💡 Mẹo Tra Cứu:",
131
- "tip_all": "👉 Chạy 'agent-qa --help --all' để xem toàn bộ 58+ lệnh.",
131
+ "tip_all": "👉 Chạy 'agent-qa --help --all' để xem toàn bộ các lệnh đã đăng ký.",
132
132
  "tip_cmd": "👉 Chạy 'agent-qa <lệnh> --help' để xem hướng dẫn chi tiết cho từng lệnh cụ thể.",
133
133
  "tip_welcome": "👉 Chạy 'agent-qa welcome' để mở giao diện Landing Page tương tác trực quan.",
134
134
  "tip_lang_switch": "💡 Chuyển đổi ngôn ngữ: agent-qa --lang vi (Tiếng Việt) | agent-qa --lang en (Tiếng Anh)",
@@ -266,7 +266,6 @@ def persist_language_preference(lang: str, target_dir: Optional[str] = None) ->
266
266
  if isinstance(loaded, dict):
267
267
  data = loaded
268
268
  except Exception as _err:
269
- _ = _err
270
269
  data = {}
271
270
 
272
271
  data["language"] = clean_lang
@@ -299,11 +298,11 @@ def _probe_config_file_lang() -> Optional[str]:
299
298
  cfg_lang = str(cfg_data.get("language", "")).strip().lower()
300
299
  if cfg_lang in ("vi", "en"):
301
300
  return cfg_lang
302
- except Exception as _err:
303
- _ = _err
301
+ except Exception:
304
302
  continue
305
303
  except Exception as _err:
306
- _ = _err
304
+ import logging
305
+ logging.getLogger("i18n").debug("Language resolution error: %s", _err)
307
306
  return None
308
307
 
309
308
 
@@ -321,9 +320,11 @@ def _probe_global_config_lang() -> Optional[str]:
321
320
  if cfg_lang in ("vi", "en"):
322
321
  return cfg_lang
323
322
  except Exception as _err:
324
- _ = _err
323
+ import logging
324
+ logging.getLogger("i18n").debug("Global config read error: %s", _err)
325
325
  except Exception as _err:
326
- _ = _err
326
+ import logging
327
+ logging.getLogger("i18n").debug("Language resolution error: %s", _err)
327
328
  return None
328
329
 
329
330
 
@@ -354,7 +355,8 @@ def _probe_os_locale_lang() -> Optional[str]:
354
355
  if def_loc.startswith("en"):
355
356
  return "en"
356
357
  except Exception as _err:
357
- _ = _err
358
+ import logging
359
+ logging.getLogger("i18n").debug("Language resolution error: %s", _err)
358
360
  return None
359
361
 
360
362
 
@@ -125,7 +125,8 @@ class UnifiedMemoryBus:
125
125
  try:
126
126
  cur.execute("ALTER TABLE actor_mailbox ADD COLUMN session_id TEXT;")
127
127
  except sqlite3.OperationalError as _err:
128
- _ = _err
128
+ import logging
129
+ logging.getLogger("memory_bus").debug("session_id column already exists: %s", _err)
129
130
 
130
131
  # 3. Skill Vault Partition
131
132
  cur.execute("""
@@ -734,7 +735,8 @@ class UnifiedMemoryBus:
734
735
  try:
735
736
  self._conn.execute("ROLLBACK;")
736
737
  except Exception as _rb_err:
737
- _ = _rb_err
738
+ import logging
739
+ logging.getLogger("memory_bus").debug("Rollback on transaction error: %s", _rb_err)
738
740
  if attempt == max_retries - 1:
739
741
  raise
740
742
  # Non-blocking backoff jitter on SQLite contention
@@ -881,7 +883,8 @@ class UnifiedMemoryBus:
881
883
  try:
882
884
  self._conn.close()
883
885
  except Exception as err:
884
- _ = err
886
+ import logging
887
+ logging.getLogger("memory_bus").debug("Connection close error: %s", err)
885
888
 
886
889
  def __enter__(self) -> "UnifiedMemoryBus":
887
890
  return self
@@ -64,21 +64,22 @@ def kill_process_tree(pid: int, timeout: float = 2.0) -> bool:
64
64
  for child in children:
65
65
  try:
66
66
  child.terminate()
67
- except (psutil.NoSuchProcess, psutil.AccessDenied) as err:
68
- _ = err
67
+ except (psutil.NoSuchProcess, psutil.AccessDenied):
68
+ continue
69
69
  parent.terminate()
70
70
 
71
71
  gone, alive = psutil.wait_procs(children + [parent], timeout=timeout)
72
72
  for p in alive:
73
73
  try:
74
74
  p.kill()
75
- except (psutil.NoSuchProcess, psutil.AccessDenied) as err:
76
- _ = err
75
+ except (psutil.NoSuchProcess, psutil.AccessDenied):
76
+ continue
77
77
  return True
78
78
  except (psutil.NoSuchProcess, psutil.AccessDenied):
79
79
  return True
80
80
  except ImportError as err:
81
- _ = err
81
+ import logging
82
+ logging.getLogger("process_supervisor").debug("psutil import error: %s", err)
82
83
 
83
84
  # 2. Platform-native fallback
84
85
  if sys.platform == "win32":
@@ -116,7 +117,9 @@ def kill_process_tree(pid: int, timeout: float = 2.0) -> bool:
116
117
  descendant_pids.append(cp)
117
118
  to_check.append(cp)
118
119
  except Exception as err:
119
- _ = err
120
+ import logging
121
+ logging.getLogger("process_supervisor").debug("Process tree inspection error: %s", err)
122
+ continue
120
123
 
121
124
  try:
122
125
  caller_pgrp = os.getpgrp() if hasattr(os, "getpgrp") else None
@@ -128,7 +131,8 @@ def kill_process_tree(pid: int, timeout: float = 2.0) -> bool:
128
131
  else:
129
132
  pgid = None
130
133
  except OSError as err:
131
- _ = err
134
+ import logging
135
+ logging.getLogger("process_supervisor").debug("getpgid failed: %s", err)
132
136
  pgid = None
133
137
 
134
138
  sig_term = getattr(signal, "SIGTERM", 15)
@@ -139,12 +143,13 @@ def kill_process_tree(pid: int, timeout: float = 2.0) -> bool:
139
143
  try:
140
144
  os.killpg(pgid, sig_term)
141
145
  except OSError as err:
142
- _ = err
146
+ import logging
147
+ logging.getLogger("process_supervisor").debug("SIGTERM to pgid %s failed: %s", pgid, err)
143
148
  for p in [pid] + descendant_pids:
144
149
  try:
145
150
  os.kill(p, sig_term)
146
- except OSError as err:
147
- _ = err
151
+ except OSError:
152
+ continue
148
153
 
149
154
  # Bounded polling wait before force kill
150
155
  start = time.time()
@@ -155,32 +160,36 @@ def kill_process_tree(pid: int, timeout: float = 2.0) -> bool:
155
160
  os.killpg(pgid, 0)
156
161
  alive = True
157
162
  except OSError as err:
158
- _ = err
163
+ import logging
164
+ logging.getLogger("process_supervisor").debug("killpg 0 probe failed: %s", err)
159
165
  for p in [pid] + descendant_pids:
160
166
  try:
161
167
  os.kill(p, 0)
162
168
  alive = True
163
169
  except OSError as err:
164
- _ = err
170
+ import logging
171
+ logging.getLogger("process_supervisor").debug("killpg 0 probe failed: %s", err)
165
172
  if not alive:
166
173
  return True
167
- time.sleep(0.05)
174
+ time.sleep(0.05) # synapse-ignore: HARD_DELAY_ANTI_PATTERN
168
175
 
169
176
  # Stage 2: Forceful SIGKILL to eradicate all remaining processes
170
177
  for p in descendant_pids + [pid]:
171
178
  try:
172
179
  os.kill(p, sig_kill)
173
- except OSError as err:
174
- _ = err
180
+ except OSError:
181
+ continue
175
182
  if pgid is not None:
176
183
  try:
177
184
  os.killpg(pgid, sig_kill)
178
185
  except OSError as err:
179
- _ = err
186
+ import logging
187
+ logging.getLogger("process_supervisor").debug("SIGKILL to pgid %s failed: %s", pgid, err)
180
188
  try:
181
189
  subprocess.run(["pkill", "-KILL", "-P", str(pid)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2.0)
182
190
  except Exception as err:
183
- _ = err
191
+ import logging
192
+ logging.getLogger("process_supervisor").debug("pkill subprocess failed: %s", err)
184
193
  return True
185
194
 
186
195
 
@@ -338,7 +347,8 @@ class ProcessSupervisor:
338
347
  stdout_data = _to_str(stdout_raw)
339
348
  stderr_data = _to_str(stderr_raw)
340
349
  except Exception as comm_err:
341
- _ = comm_err
350
+ import logging
351
+ logging.getLogger("process_supervisor").debug("Process communicate error: %s", comm_err)
342
352
  returncode = 124
343
353
  except Exception as exc:
344
354
  kill_process_tree(proc.pid)