@teevee98/synapse-hub 0.0.0-stage → 3.8.3

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 (369) hide show
  1. package/.agents/agents/api-engineer.md +67 -0
  2. package/.agents/agents/failure-analyst.md +75 -0
  3. package/.agents/agents/live-explorer.md +70 -0
  4. package/.agents/agents/orchestrator.md +104 -0
  5. package/.agents/agents/perf-engineer.md +74 -0
  6. package/.agents/agents/pom-crafter.md +112 -0
  7. package/.agents/agents/quality-gatekeeper.md +87 -0
  8. package/.agents/agents/test-designer.md +73 -0
  9. package/.agents/agents/test-runner.md +67 -0
  10. package/.agents/rules/author-integrity-guard.md +33 -0
  11. package/.agents/rules/communication-style.md +18 -0
  12. package/.agents/rules/context-engineering.md +37 -0
  13. package/.agents/rules/git-push-protocol.md +33 -0
  14. package/.agents/rules/graphify.md +14 -0
  15. package/.agents/rules/lessons-learned.md +25 -0
  16. package/.agents/rules/mandatory-playwright-live.md +25 -0
  17. package/.agents/rules/mobile_appium_rules.md +43 -0
  18. package/.agents/rules/performance_testing_rules.md +35 -0
  19. package/.agents/rules/skill-precedence.md +29 -0
  20. package/.agents/rules/systematic-debugging.md +36 -0
  21. package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
  22. package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
  23. package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
  24. package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
  25. package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
  26. package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
  27. package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
  28. package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
  29. package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
  30. package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
  31. package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
  32. package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
  33. package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
  34. package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
  35. package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
  36. package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
  37. package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
  38. package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
  39. package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
  40. package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
  41. package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
  42. package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
  43. package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
  44. package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
  45. package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
  46. package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
  47. package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
  48. package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
  49. package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
  50. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
  51. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
  52. package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
  53. package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
  54. package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
  55. package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
  56. package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
  57. package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
  58. package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
  59. package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
  60. package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
  61. package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
  62. package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
  63. package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
  64. package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
  65. package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
  66. package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
  67. package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
  68. package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
  69. package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
  70. package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
  71. package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
  72. package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
  73. package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
  74. package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
  75. package/.agents/skills/github-actions-templates/SKILL.md +77 -0
  76. package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
  77. package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
  78. package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
  79. package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
  80. package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
  81. package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
  82. package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
  83. package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
  84. package/.agents/skills/lam-script-generator/SKILL.md +123 -0
  85. package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
  86. package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
  87. package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
  88. package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
  89. package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
  90. package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
  91. package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
  92. package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
  93. package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
  94. package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
  95. package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
  96. package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
  97. package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
  98. package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
  99. package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
  100. package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
  101. package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
  102. package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
  103. package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
  104. package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
  105. package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
  106. package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
  107. package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
  108. package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
  109. package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
  110. package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
  111. package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
  112. package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
  113. package/.agents/skills/qa-memory-os/SKILL.md +80 -0
  114. package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
  115. package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
  116. package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
  117. package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
  118. package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
  119. package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
  120. package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
  121. package/.agents/skills/review-spec/SKILL.md +60 -0
  122. package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
  123. package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
  124. package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
  125. package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
  126. package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
  127. package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
  128. package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
  129. package/.agents/skills/self-healing-locator/SKILL.md +86 -0
  130. package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
  131. package/.agents/skills/senior-code-review/SKILL.md +108 -0
  132. package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
  133. package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
  134. package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
  135. package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
  136. package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
  137. package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
  138. package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
  139. package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
  140. package/.agents/skills/systematic-debugging/SKILL.md +100 -0
  141. package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
  142. package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
  143. package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
  144. package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
  145. package/.agents/skills/test-driven-development/SKILL.md +114 -0
  146. package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
  147. package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
  148. package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
  149. package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
  150. package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
  151. package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
  152. package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
  153. package/.agents/skills/verification-before-completion/SKILL.md +100 -0
  154. package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
  155. package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
  156. package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
  157. package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
  158. package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
  159. package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
  160. package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
  161. package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
  162. package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
  163. package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
  164. package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
  165. package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
  166. package/.agents/templates/completion_report.md +57 -0
  167. package/.agents/workflows/analyze_requirement_document.md +18 -0
  168. package/.agents/workflows/export_testcases_excel.md +32 -0
  169. package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
  170. package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
  171. package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
  172. package/.agents/workflows/generate_requirements_from_website.md +25 -0
  173. package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
  174. package/.agents/workflows/graphify.md +10 -0
  175. package/.agents/workflows/test-impact.md +15 -0
  176. package/.agents/workflows/verify.md +34 -0
  177. package/.cursor/rules/agents.mdc +16 -0
  178. package/.cursor/rules/language.mdc +7 -0
  179. package/.cursor/rules/synapse-qa.mdc +24 -0
  180. package/.cursorrules +27 -0
  181. package/.dockerignore +53 -0
  182. package/.pre-commit-hooks.yaml +14 -0
  183. package/.windsurfrules +26 -0
  184. package/AGENTS.md +86 -0
  185. package/CLAUDE.md +54 -0
  186. package/Dockerfile +81 -0
  187. package/LICENSE +52 -0
  188. package/NOTICE +264 -0
  189. package/README.en.md +171 -0
  190. package/README.md +170 -2
  191. package/action.yml +51 -0
  192. package/agentskills.json +16 -0
  193. package/bin/agent-qa.js +138 -0
  194. package/docker-compose.yml +74 -0
  195. package/docs/ARCHITECTURE.en.md +198 -0
  196. package/docs/ARCHITECTURE.md +199 -0
  197. package/docs/CI_CD_INTEGRATION.en.md +170 -0
  198. package/docs/CI_CD_INTEGRATION.md +170 -0
  199. package/docs/CLI_REFERENCE.en.md +174 -0
  200. package/docs/CLI_REFERENCE.md +176 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +118 -0
  206. package/docs/QUALITY_GATES.md +118 -0
  207. package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
  208. package/docs/TOOL_CATALOG.md +129 -0
  209. package/docs/adopted-ecosystem-tools.md +96 -0
  210. package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
  211. package/docs/research/agent_skill_training_analysis.md +1358 -0
  212. package/docs/schemas/synapse.config.schema.json +86 -0
  213. package/package.json +94 -4
  214. package/plugin.json +31 -0
  215. package/scripts/generate_skill_examples.py +244 -0
  216. package/scripts/install.ps1 +112 -0
  217. package/scripts/install_global_plugin.ps1 +94 -0
  218. package/scripts/install_global_plugin.sh +49 -0
  219. package/scripts/lint_skills.ps1 +57 -0
  220. package/scripts/package_dist.py +337 -0
  221. package/scripts/setup.sh +59 -0
  222. package/scripts/update_hub.ps1 +19 -0
  223. package/scripts/update_hub.sh +15 -0
  224. package/skills_manifest.json +854 -0
  225. package/synapse.config.json +31 -0
  226. package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
  227. package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
  228. package/templates/ai_bridges/CLAUDE.md +54 -0
  229. package/templates/ai_bridges/copilot-instructions.md +20 -0
  230. package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
  231. package/templates/ai_bridges/windsurfrules +26 -0
  232. package/templates/ci/github-actions-synapse.yml +95 -0
  233. package/templates/ci/gitlab-ci-synapse.yml +16 -0
  234. package/templates/ui/index.html +1069 -0
  235. package/templates/welcome.html.tmpl +2074 -0
  236. package/tools/.infer_baseline.json +30 -0
  237. package/tools/TOOLS_RUNBOOK.md +1553 -0
  238. package/tools/TOOL_CATALOG.json +1769 -0
  239. package/tools/__init__.py +43 -0
  240. package/tools/_openapi_parser.py +158 -0
  241. package/tools/agent_canary.py +525 -0
  242. package/tools/agentless_patcher.py +417 -0
  243. package/tools/analyze_project.py +262 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +190 -0
  247. package/tools/auto_heal.py +271 -0
  248. package/tools/auto_heal_reflexion.py +532 -0
  249. package/tools/autogen_qa_broker.py +844 -0
  250. package/tools/benchmark_swarm_context.py +394 -0
  251. package/tools/browser_helpers.js +746 -0
  252. package/tools/browsergym_eval.py +236 -0
  253. package/tools/bug_reporter.py +252 -0
  254. package/tools/bump_version.py +423 -0
  255. package/tools/cache_resolver.py +1214 -0
  256. package/tools/check_env.py +426 -0
  257. package/tools/check_version_sync.py +256 -0
  258. package/tools/ci_healing_hook.py +126 -0
  259. package/tools/cli.py +1598 -0
  260. package/tools/config_decoupler.py +253 -0
  261. package/tools/contract_validator.py +141 -0
  262. package/tools/core/__init__.py +70 -0
  263. package/tools/core/adapters.py +431 -0
  264. package/tools/core/circuit_breaker.py +263 -0
  265. package/tools/core/cli_runtime.py +66 -0
  266. package/tools/core/file_lock.py +159 -0
  267. package/tools/core/i18n.py +394 -0
  268. package/tools/core/memory_bus.py +905 -0
  269. package/tools/core/process_supervisor.py +332 -0
  270. package/tools/core/telemetry.py +329 -0
  271. package/tools/count_tokens.py +1267 -0
  272. package/tools/create_mock_docx.py +104 -0
  273. package/tools/dashboard_generator.py +2403 -0
  274. package/tools/db_sandbox.py +675 -0
  275. package/tools/debt_harvester.py +237 -0
  276. package/tools/distill_log.py +161 -0
  277. package/tools/dspy_qa_signatures.py +356 -0
  278. package/tools/e2e_flow_prober.py +132 -0
  279. package/tools/export_postman_collection.py +945 -0
  280. package/tools/flaky_detector.py +389 -0
  281. package/tools/fsm_enforcer.py +450 -0
  282. package/tools/fsm_middleware.py +401 -0
  283. package/tools/fuzz_payloads.py +197 -0
  284. package/tools/generate_allure_report.py +88 -0
  285. package/tools/generate_api_matrix.py +193 -0
  286. package/tools/generate_jmx_plan.py +1322 -0
  287. package/tools/generate_sbom.py +252 -0
  288. package/tools/generate_tc_from_story.py +203 -0
  289. package/tools/generate_test_reports.py +133 -0
  290. package/tools/generate_tool_catalog.py +482 -0
  291. package/tools/gherkin_suite.py +758 -0
  292. package/tools/git_pre_commit_guard.py +298 -0
  293. package/tools/goldfish_review.py +366 -0
  294. package/tools/heal/__init__.py +28 -0
  295. package/tools/heal_pr_automator.py +220 -0
  296. package/tools/heuristic_locator_matcher.py +351 -0
  297. package/tools/hub_publisher.py +623 -0
  298. package/tools/humanize_linter.py +438 -0
  299. package/tools/infer_linter.py +977 -0
  300. package/tools/init_config.py +306 -0
  301. package/tools/interview_story.py +116 -0
  302. package/tools/jira_sync.py +566 -0
  303. package/tools/jtl_analyzer.py +474 -0
  304. package/tools/lint/__init__.py +30 -0
  305. package/tools/lint_ai_docs.py +374 -0
  306. package/tools/lookup_tc.py +165 -0
  307. package/tools/lookup_xpath.py +167 -0
  308. package/tools/matrix_sharder.py +148 -0
  309. package/tools/mcp/__init__.py +18 -0
  310. package/tools/mcp_docx_server.ps1 +13 -0
  311. package/tools/mcp_docx_server.py +851 -0
  312. package/tools/mcp_excel_server.ps1 +13 -0
  313. package/tools/mcp_excel_server.py +441 -0
  314. package/tools/mcp_server.py +725 -0
  315. package/tools/md_to_xlsx.py +327 -0
  316. package/tools/micro_mutator.py +887 -0
  317. package/tools/mipro_assertion_tuner.py +210 -0
  318. package/tools/network_mock_shield.py +311 -0
  319. package/tools/newman_analyzer.py +384 -0
  320. package/tools/omni_emitter.py +579 -0
  321. package/tools/omni_parser.py +450 -0
  322. package/tools/omni_transpiler.py +168 -0
  323. package/tools/openxml_guard.py +438 -0
  324. package/tools/output_formatter.py +182 -0
  325. package/tools/package_release.py +325 -0
  326. package/tools/perf/__init__.py +24 -0
  327. package/tools/pinpoint_failure.py +190 -0
  328. package/tools/project_state.py +171 -0
  329. package/tools/qa_event_stream.py +358 -0
  330. package/tools/repo_map.py +346 -0
  331. package/tools/report/__init__.py +32 -0
  332. package/tools/reversible_sandbox.py +344 -0
  333. package/tools/safety_firewall.py +437 -0
  334. package/tools/security_coverage_ledger.py +538 -0
  335. package/tools/security_scanner.py +229 -0
  336. package/tools/senior_code_review.py +393 -0
  337. package/tools/setup_project.py +770 -0
  338. package/tools/skill_collision_guard.py +304 -0
  339. package/tools/skill_profiles.py +217 -0
  340. package/tools/skill_vault.py +481 -0
  341. package/tools/skillspector.py +1278 -0
  342. package/tools/smart_visual_masker.py +132 -0
  343. package/tools/spec_drift_sentinel.py +438 -0
  344. package/tools/swe_qa_aci.py +369 -0
  345. package/tools/synapse_observer.py +485 -0
  346. package/tools/synapse_qa_bench.py +190 -0
  347. package/tools/sync_agent_rules.py +274 -0
  348. package/tools/telemetry_correlator.py +397 -0
  349. package/tools/template_excel_exporter.py +514 -0
  350. package/tools/templates/jmeter-distributed/README.md +54 -0
  351. package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
  352. package/tools/test_impact.py +419 -0
  353. package/tools/test_memory_os.py +462 -0
  354. package/tools/textgrad_mutation_optimizer.py +237 -0
  355. package/tools/tms_sync_bridge.py +834 -0
  356. package/tools/tot_exploratory_tester.py +239 -0
  357. package/tools/trace_data_flow.py +240 -0
  358. package/tools/traffic_session_converter.py +256 -0
  359. package/tools/trend_analytics.py +314 -0
  360. package/tools/ui_server.py +401 -0
  361. package/tools/universal_ir.py +488 -0
  362. package/tools/update_sentinel.py +383 -0
  363. package/tools/validate_groovy_scripts.py +173 -0
  364. package/tools/verify_all.py +1271 -0
  365. package/tools/visual_diff_canvas.py +143 -0
  366. package/tools/visual_som_helper.py +550 -0
  367. package/tools/watch_mode.py +308 -0
  368. package/tools/wcag_audit.py +239 -0
  369. package/tools/welcome_page.py +290 -0
@@ -0,0 +1,66 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ Shared CLI Runtime Utilities for Synapse-Hub Tools
8
+ --------------------------------------------------
9
+ Eliminates duplicated boilerplate across CLI tools:
10
+ - Robust UTF-8 console output setup (Windows cp1252 / cmd.exe compatibility)
11
+ - Canonical repository root resolution
12
+ - Standardized JSON formatting and error exits
13
+ """
14
+
15
+ import os
16
+ import sys
17
+ import json
18
+ from typing import Any, Optional
19
+
20
+
21
+ def setup_utf8_output():
22
+ """Configures sys.stdout and sys.stderr with UTF-8 encoding safely."""
23
+ for stream in (sys.stdout, sys.stderr):
24
+ if hasattr(stream, "reconfigure"):
25
+ try:
26
+ stream.reconfigure(encoding="utf-8", errors="replace")
27
+ except Exception:
28
+ pass
29
+
30
+
31
+ # Automatically configure UTF-8 output when this module is imported
32
+ setup_utf8_output()
33
+
34
+
35
+ def get_repo_root(start_file: Optional[str] = None) -> str:
36
+ """Returns the canonical absolute repository root path.
37
+ Prioritizes SYNAPSE_PROJECT_ROOT env var, then walks up from start_file or CWD."""
38
+ env_root = os.environ.get("SYNAPSE_PROJECT_ROOT")
39
+ if env_root and os.path.isdir(env_root):
40
+ return os.path.abspath(env_root)
41
+
42
+ origin = os.path.abspath(start_file or __file__)
43
+ current = os.path.dirname(origin) if os.path.isfile(origin) else origin
44
+
45
+ # Walk up to locate marker files (package.json, pyproject.toml, .agents)
46
+ for _ in range(8):
47
+ if any(os.path.exists(os.path.join(current, marker)) for marker in ("package.json", "pyproject.toml", "AGENTS.md")):
48
+ return current
49
+ parent = os.path.dirname(current)
50
+ if parent == current:
51
+ break
52
+ current = parent
53
+
54
+ return os.path.abspath(os.getcwd())
55
+
56
+
57
+ def print_json(data: Any, indent: int = 2, file=None):
58
+ """Prints serializable data as UTF-8 formatted JSON."""
59
+ out = json.dumps(data, indent=indent, ensure_ascii=False, default=str)
60
+ print(out, file=file or sys.stdout)
61
+
62
+
63
+ def exit_with_error(message: str, code: int = 1):
64
+ """Prints a formatted error message to stderr and exits."""
65
+ sys.stderr.write(f"[ERROR] {message}\n")
66
+ sys.exit(code)
@@ -0,0 +1,159 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ Cross-Platform Advisory File Locking (tools.core.file_lock)
8
+ -----------------------------------------------------------
9
+ Eliminates race condition truncations and concurrent read/write corruptions
10
+ under multi-agent swarms (actor-qa-swarm, parallel subagents).
11
+
12
+ Key Mechanisms:
13
+ 1. POSIX: Uses stdlib `fcntl.flock` with shared (LOCK_SH) and exclusive (LOCK_EX) modes.
14
+ 2. Windows: Uses stdlib `msvcrt.locking` with non-blocking polling fallback.
15
+ 3. Non-blocking polling timeout: Prevents indefinite deadlocks if another process stalls.
16
+ 4. Atomic safe write: Staged writes to .tmp with fsync and atomic rename (os.replace).
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import json
22
+ import os
23
+ import sys
24
+ import time
25
+ from typing import Any, Optional
26
+
27
+ # POSIX vs Windows native locking imports
28
+ if sys.platform != "win32":
29
+ import fcntl
30
+ else:
31
+ import msvcrt # type: ignore
32
+
33
+
34
+ class FileLockTimeoutError(TimeoutError):
35
+ """Raised when acquiring a file lock exceeds the allocated timeout."""
36
+ pass
37
+
38
+
39
+ class FileLock:
40
+ """
41
+ Cross-platform advisory file lock context manager.
42
+ """
43
+
44
+ def __init__(
45
+ self,
46
+ target_path: str,
47
+ timeout: float = 10.0,
48
+ shared: bool = False,
49
+ poll_interval: float = 0.05,
50
+ ):
51
+ self.target_path = os.path.abspath(target_path)
52
+ self.lock_path = self.target_path + ".lock"
53
+ self.timeout = timeout
54
+ self.shared = shared
55
+ self.poll_interval = poll_interval
56
+ self._fd: Optional[int] = None
57
+
58
+ def acquire(self) -> FileLock:
59
+ """Acquires the advisory lock, polling until timeout."""
60
+ os.makedirs(os.path.dirname(self.lock_path), exist_ok=True)
61
+ start = time.time()
62
+ while True:
63
+ try:
64
+ if self._fd is None:
65
+ # Open without O_TRUNC to prevent metadata race conditions
66
+ self._fd = os.open(self.lock_path, os.O_RDWR | os.O_CREAT, 0o666)
67
+ if sys.platform != "win32":
68
+ mode = fcntl.LOCK_SH if self.shared else fcntl.LOCK_EX
69
+ fcntl.flock(self._fd, mode | fcntl.LOCK_NB)
70
+ else:
71
+ # Ensure at least 1 byte exists to lock on Windows
72
+ if os.path.getsize(self.lock_path) == 0:
73
+ os.write(self._fd, b"\x00")
74
+ os.lseek(self._fd, 0, os.SEEK_SET)
75
+ msvcrt.locking(self._fd, msvcrt.LK_NBLCK, 1)
76
+ return self
77
+ except (BlockingIOError, OSError, PermissionError):
78
+ if self._fd is not None:
79
+ try:
80
+ os.close(self._fd)
81
+ except OSError as err:
82
+ _ = err
83
+ self._fd = None
84
+ if time.time() - start >= self.timeout:
85
+ raise FileLockTimeoutError(
86
+ f"Timed out after {self.timeout}s waiting for lock on {self.lock_path}"
87
+ )
88
+ time.sleep(self.poll_interval)
89
+
90
+ def release(self):
91
+ """Releases the advisory lock and closes the descriptor."""
92
+ if self._fd is not None:
93
+ try:
94
+ if sys.platform != "win32":
95
+ fcntl.flock(self._fd, fcntl.LOCK_UN)
96
+ else:
97
+ try:
98
+ os.lseek(self._fd, 0, os.SEEK_SET)
99
+ msvcrt.locking(self._fd, msvcrt.LK_UNLCK, 1)
100
+ except OSError as err:
101
+ _ = err
102
+ os.close(self._fd)
103
+ except OSError as err:
104
+ _ = err
105
+ finally:
106
+ self._fd = None
107
+
108
+ def __enter__(self) -> FileLock:
109
+ return self.acquire()
110
+
111
+ def __exit__(self, exc_type, exc_val, exc_tb):
112
+ self.release()
113
+
114
+
115
+ def locked_read(file_path: str, timeout: float = 10.0) -> str:
116
+ """Safely reads a file while holding a shared advisory lock."""
117
+ with FileLock(file_path, timeout=timeout, shared=True):
118
+ with open(file_path, "r", encoding="utf-8") as f:
119
+ return f.read()
120
+
121
+
122
+ def locked_write(file_path: str, content: str, timeout: float = 10.0, atomic: bool = True) -> None:
123
+ """
124
+ Safely writes content to a file while holding an exclusive lock.
125
+ When atomic=True, writes to a temporary file first, then atomically replaces.
126
+ """
127
+ os.makedirs(os.path.dirname(os.path.abspath(file_path)), exist_ok=True)
128
+ with FileLock(file_path, timeout=timeout, shared=False):
129
+ if atomic:
130
+ temp_path = f"{file_path}.tmp.{os.getpid()}.{time.time_ns()}"
131
+ try:
132
+ with open(temp_path, "w", encoding="utf-8") as f:
133
+ f.write(content)
134
+ f.flush()
135
+ os.fsync(f.fileno())
136
+ os.replace(temp_path, file_path)
137
+ finally:
138
+ if os.path.exists(temp_path):
139
+ try:
140
+ os.remove(temp_path)
141
+ except OSError as err:
142
+ _ = err
143
+ else:
144
+ with open(file_path, "w", encoding="utf-8") as f:
145
+ f.write(content)
146
+
147
+
148
+ def locked_json_read(file_path: str, timeout: float = 10.0) -> Any:
149
+ """Reads JSON content while holding a shared lock."""
150
+ text = locked_read(file_path, timeout=timeout)
151
+ return json.loads(text)
152
+
153
+
154
+ def locked_json_write(
155
+ file_path: str, data: Any, indent: int = 2, timeout: float = 10.0, atomic: bool = True
156
+ ) -> None:
157
+ """Writes formatted JSON content while holding an exclusive lock."""
158
+ content = json.dumps(data, indent=indent, ensure_ascii=False)
159
+ locked_write(file_path, content, timeout=timeout, atomic=atomic)
@@ -0,0 +1,394 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ Synapse Hub — Bilingual Internationalization Engine (tools.core.i18n)
8
+ ---------------------------------------------------------------------
9
+ Provides centralized English/Vietnamese message resolution across
10
+ the CLI hub, Web UI bridges, and automated developer experience tools.
11
+ Precedence: CLI flag > ENV (SYNAPSE_LANG) > .synapse.json / ~/.synapse.json > 'en'
12
+ """
13
+
14
+ import os
15
+ import json
16
+ import locale
17
+ from typing import Dict, Any, Optional
18
+
19
+ MESSAGES: Dict[str, Dict[str, str]] = {
20
+ "en": {
21
+ "banner_title": "SYNAPSE HUB CLI — Enterprise AI Agent Quality Engineering Hub",
22
+ "hub_cli_description": "Enterprise AI Agent Quality Engineering & Test Automation Hub CLI",
23
+ "version_info": "Version: v{version} | Author: Thế Vị (@TeeVee98) | License: MIT",
24
+ "usage_title": "USAGE:",
25
+ "usage_syntax": " agent-qa <command> [options...]",
26
+ "core_commands_title": "🌟 CORE & DAILY WORKFLOWS:",
27
+ "advanced_highlights_title": "🎯 ADVANCED AI/QA CAPABILITIES:",
28
+ "general_options_title": "GENERAL OPTIONS:",
29
+ "opt_all": "Display all 58+ advanced and infrastructure commands",
30
+ "opt_version": "Show current version and author provenance",
31
+ "opt_offline": "Force 100% offline air-gapped mode (zero network / LLM calls)",
32
+ "opt_quiet": "Suppress banner, show only verdict and critical output",
33
+ "opt_lang": "Set CLI interface language (en: English, vi: Vietnamese)",
34
+ "tips_header": "💡 Quick Navigation Tips:",
35
+ "tip_all": "👉 Run 'agent-qa --help --all' to inspect all 58+ commands.",
36
+ "tip_cmd": "👉 Run 'agent-qa <command> --help' for detailed command options.",
37
+ "tip_welcome": "👉 Run 'agent-qa welcome' to launch the interactive visual landing page.",
38
+ "tip_lang_switch": "💡 Switch language: agent-qa --lang vi (Vietnamese) | agent-qa --lang en (English)",
39
+ "cmd_set_lang": "Set and persist CLI interface language (en: English, vi: Vietnamese)",
40
+ "lang_saved": "✅ Interface language preference saved: {lang_name} ({lang_code}) -> {config_path}",
41
+ "cmd_doctor": "Run 1-click diagnostic check of environment (Node.js, Python, Git, Browsers)",
42
+ "cmd_setup": "Autonomous 1-click bootstrap of target project (AI guide, Git hook, AST map)",
43
+ "cmd_init_config": "Initialize standardized .synapse.json configuration for Spoke project",
44
+ "cmd_lint": "AST scan catching fake-passes (0 assert, try-catch swallow, hard sleeps)",
45
+ "cmd_verify": "Execute 10 Quality Gates Definition of Done (DoD) verification",
46
+ "cmd_export_excel": "Export Markdown test cases to enterprise 12-column Excel (.xlsx)",
47
+ "cmd_welcome": "Launch interactive visual landing page introducing Synapse Hub",
48
+ "cmd_ui": "Launch real-time Interactive Mission Control Web UI dashboard",
49
+ "cmd_dashboard": "Generate standalone executive HTML project health dashboard",
50
+ "cmd_analyze": "Execute comprehensive project health & AST knowledge graph analysis",
51
+ "cmd_mutate": "Syntactic micro-mutation testing measuring assertion sensitivity (Kill Score >= 80%)",
52
+ "cmd_auto_heal": "Autonomous test self-healing (Reflexion K=3) using AOM contextual diff",
53
+ "cmd_som": "Visual Set-of-Marks grounding on Canvas/GIS elements without DOM",
54
+ "cmd_fuzz_api": "Autonomous API fuzzing & chaos fault injection breaker",
55
+ "cmd_transpile": "Zero-token polyglot test transpilation across Playwright, Cypress, Selenium",
56
+ "cmd_help": "Display CLI help and command search reference",
57
+ "cmd_version": "Show Hub version and catalog metadata",
58
+ "cmd_uninstall": "Revert and remove files installed by setup in target project",
59
+ "cmd_clean": "Clean build artifacts, __pycache__, and bytecode",
60
+ "cmd_update": "1-Click update Synapse-Hub to latest version from GitHub/NPM",
61
+ "cmd_check_version": "Verify universal version synchronization across all files",
62
+ "cmd_sync_rules": "Synchronize AGENTS.md single source of truth across all AI IDE bridges",
63
+ "cmd_heal_pr": "Calculate self-healing confidence and generate Git PR draft",
64
+ "cmd_heal": "Query, learn, or record-failed into semantic memory cache",
65
+ "cmd_shard": "Balance parallel CI/CD test execution using duration-balanced bin-packing",
66
+ "cmd_sync_jira": "Bidirectional sync with Jira / Xray / Zephyr (pull stories, push tests, create bugs)",
67
+ "cmd_trend": "Historical Quality Trend & Flakiness Analytics Engine",
68
+ "cmd_flaky": "Detect flaky tests and manage quarantine lifecycle",
69
+ "cmd_canary": "Run autonomous canary resilience benchmark",
70
+ "cmd_watch": "Real-Time incremental watch mode & test engineering HUD (< 100ms feedback)",
71
+ "cmd_pinpoint_failure": "Parse JUnit XML and locate exact failing line in 0.1s",
72
+ "cmd_ci_hook": "CI/CD Silent Self-Healing Pipeline Hook & Automated PR Generator",
73
+ "cmd_debt": "Harvest shortcut: comments into a tracked technical debt ledger",
74
+ "cmd_review": "Senior developer quality & lean diff review (bugs, security, scale, tests, bloat)",
75
+ "cmd_safety_check": "Action Safety Firewall & Blast Radius Containment",
76
+ "cmd_contract_drift": "Detect breaking API changes across OpenAPI / Swagger specs",
77
+ "cmd_skillspector": "AI Agent Skill & MCP Security Sentinel (71 vectors, NVIDIA SkillSpector spec)",
78
+ "cmd_skills": "List, filter, and inspect AI agent skills and 4 core capability profiles",
79
+ "cmd_verify_author": "Verify author attribution, provenance, and anti-tamper integrity",
80
+ "cmd_wcag_audit": "Audit WCAG 2.2 accessibility conformance and contrast ratios",
81
+ "cmd_impact": "Analyze code change impact using AST Knowledge Graph",
82
+ "cmd_review_spec": "Zero-context stress-test for specifications and user stories (Elephant-Goldfish Model)",
83
+ "cmd_drift_check": "Spec-to-Code Drift Sentinel checking Deficit & Scope Drift",
84
+ "cmd_trace_data_flow": "Trace test data lifecycles to detect DB leaks and missing teardowns",
85
+ "cmd_distill": "Distill and filter verbose CLI logs by 95 percent",
86
+ "cmd_gherkin": "Compile Gherkin .feature files into test matrix, Universal IR and coverage-gap report (0-token)",
87
+ "cmd_omni_scan": "Scan repository and build polyglot test inventory (0-token)",
88
+ "cmd_report_bug": "Auto-generate enterprise Jira/Markdown Bug Ticket with RCA",
89
+ "cmd_mock_shield": "Generate API Route Interception & Chaos Fault Injection Shield",
90
+ "cmd_visual_mask": "Smart Visual Masking & Anti-Flake Animation Blocker",
91
+ "cmd_migrate": "Autonomous suite migration from legacy (Katalon/Cypress) to modern Playwright",
92
+ "cmd_decouple_config": "Decouple hardcoded URLs, credentials, and secrets into env profiles",
93
+ "cmd_export_postman": "Export OpenAPI / Swagger / HAR to Postman Collection v2.1.0 with auto-asserts",
94
+ "cmd_generate_jmx": "Generate Apache JMeter 5.x Test Plan XML (.jmx) with JMeter 360 Enterprise Capabilities",
95
+ "cmd_analyze_jtl": "Analyze JMeter .jtl results, evaluate P90/P95/P99 SLA, and enforce CI/CD Quality Gate",
96
+ "cmd_correlate_telemetry": "Correlate Client-Side JMeter latency with Server-Side APM CPU/RAM/DB telemetry",
97
+ "cmd_analyze_newman": "Analyze Postman / Newman test results, triage failed assertions, and enforce CI/CD Quality Gate",
98
+ "cmd_tokens": "Audit token usage and estimated API cost across Antigravity, Cursor, and Claude Code",
99
+ "cmd_lookup_tc": "Search test cases by ID, tag, priority, or flow",
100
+ "cmd_lookup_xpath": "Query cached resilient XPath & AOM locators",
101
+ "cmd_generate_tc": "Compile natural language user stories into Clean POM test cases",
102
+ "cmd_api_matrix": "Generate Positive, Boundary, and Negative test matrix from OpenAPI/Swagger",
103
+ "cmd_canvas_diff": "HTML5 Canvas visual regression diffing & blank check",
104
+ "cmd_validate_groovy": "Pre-check Groovy scripts & keywords syntax balance",
105
+ "cmd_mcp_serve": "Start the JSON-RPC 2.0 stdio Model Context Protocol (MCP) server",
106
+ "cmd_mcp_excel": "Start the JSON-RPC 2.0 stdio MCP Excel server",
107
+ "cmd_mcp_docx": "Start the JSON-RPC 2.0 stdio MCP Word (.docx) server",
108
+ "cmd_release": "1-Click atomic release: bump version across all targets, verify DoD gates, git tag & push for NPM",
109
+ "cmd_publish": "1-Click end-to-end publish pipeline: push main, git tag, create release, GitHub package & NPM publish",
110
+ "subcommands_help": "Available subcommands",
111
+ "typo_error": "❌ Error: Command '{choice}' does not exist in Synapse-Hub.",
112
+ "typo_suggest": "💡 Did you mean: {suggestions} ?",
113
+ "typo_help_hint": "👉 Try running: agent-qa {first_match} --help",
114
+ "typo_list_hint": "👉 Type 'agent-qa --help' to see all available commands.",
115
+ },
116
+ "vi": {
117
+ "banner_title": "SYNAPSE HUB CLI — Enterprise AI Agent Quality Engineering Hub",
118
+ "hub_cli_description": "Nền tảng kỹ thuật kiểm thử và đảm bảo chất lượng AI Agent tự động",
119
+ "version_info": "Phiên bản: v{version} | Tác giả: Thế Vị (@TeeVee98) | Giấy phép: MIT",
120
+ "usage_title": "CÚ PHÁP SỬ DỤNG:",
121
+ "usage_syntax": " agent-qa <lệnh> [tùy_chọn...]",
122
+ "core_commands_title": "🌟 LỆNH CỐT LÕI & THƯỜNG DÙNG:",
123
+ "advanced_highlights_title": "🎯 CÁC KHÁI NIỆM AI/QA NÂNG CAO TIÊU BIỂU:",
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",
126
+ "opt_version": "Hiển thị phiên bản hiện tại và thông tin tác quyền MIT",
127
+ "opt_offline": "Ép chế độ 100% offline air-gapped (zero network / LLM calls)",
128
+ "opt_quiet": "Ẩn banner thông tin, chỉ xuất kết quả phán quyết quan trọng",
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
+ "tips_header": "💡 Mẹo Tra Cứu:",
131
+ "tip_all": "👉 Chạy 'agent-qa --help --all' để xem toàn bộ 58+ lệnh.",
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
+ "tip_welcome": "👉 Chạy 'agent-qa welcome' để mở giao diện Landing Page tương tác trực quan.",
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)",
135
+ "cmd_set_lang": "Thiết lập và ghi nhớ ngôn ngữ giao diện CLI (en: Tiếng Anh, vi: Tiếng Việt)",
136
+ "lang_saved": "✅ Đã lưu cấu hình ngôn ngữ giao diện: {lang_name} ({lang_code}) -> {config_path}",
137
+ "cmd_doctor": "Kiểm tra chẩn đoán môi trường (Node.js, Python, Git, trình duyệt)",
138
+ "cmd_setup": "Thiết lập bảo vệ 1-click cho dự án mục tiêu (AI rules, Git hook, AST map)",
139
+ "cmd_init_config": "Khởi tạo file cấu hình .synapse.json chuẩn hóa cho dự án Spoke",
140
+ "cmd_lint": "Quét AST phát hiện test pass ảo (0 assert, try-catch rỗng, sleep cứng)",
141
+ "cmd_verify": "Kiểm tra toàn diện 10 Cổng Chất Lượng DoD (Definition of Done)",
142
+ "cmd_export_excel": "Xuất test cases Markdown sang file Excel (.xlsx) chuẩn doanh nghiệp",
143
+ "cmd_welcome": "Khởi chạy Landing Page trực quan giới thiệu các trụ cột của Synapse Hub",
144
+ "cmd_ui": "Khởi chạy Web UI Mission Control tương tác thời gian thực (Live Dashboard)",
145
+ "cmd_dashboard": "Tạo dashboard HTML báo cáo sức khỏe và tiến độ kiểm thử dự án",
146
+ "cmd_analyze": "Phân tích tổng thể sức khỏe dự án và xây dựng bản đồ tri thức AST",
147
+ "cmd_mutate": "Kiểm thử đột biến (AST Mutation) — đo độ nhạy câu lệnh assert (Min Score >= 80%)",
148
+ "cmd_auto_heal": "Tự sửa test hỏng (Reflexion K=3) — AI tự soi chiếu vết lỗi và đề xuất bản vá",
149
+ "cmd_som": "Gắn nhãn thị giác (Set-of-Marks) — đánh số trực quan trên Canvas/GIS để click chính xác",
150
+ "cmd_fuzz_api": "API Chaos Fuzzing — bắn payload đột biến bắt lỗi 500 và rò rỉ dữ liệu",
151
+ "cmd_transpile": "Chuyển đổi ngôn ngữ test giữa Playwright, Cypress, Selenium, Katalon",
152
+ "cmd_help": "Hiển thị hướng dẫn tra cứu lệnh CLI của Synapse Hub",
153
+ "cmd_version": "Hiển thị phiên bản Hub và danh mục kỹ năng (metadata)",
154
+ "cmd_uninstall": "Gỡ bỏ các file cấu hình và hook do lệnh setup cài đặt",
155
+ "cmd_clean": "Dọn dẹp tệp build thừa, __pycache__ và bytecode rác",
156
+ "cmd_update": "Cập nhật 1-click Synapse-Hub lên phiên bản mới nhất từ GitHub/NPM",
157
+ "cmd_check_version": "Kiểm tra tính đồng nhất của phiên bản trên toàn bộ tệp dự án",
158
+ "cmd_sync_rules": "Đồng bộ tệp quy tắc AGENTS.md sang tất cả cấu hình cầu nối AI IDE",
159
+ "cmd_heal_pr": "Tính điểm tin cậy tự phục hồi và tạo bản nháp Git PR tự động",
160
+ "cmd_heal": "Tra cứu, học hoặc ghi nhận lỗi kiểm thử vào bộ nhớ ngữ nghĩa",
161
+ "cmd_shard": "Phân bổ tải kiểm thử CI/CD song song cân bằng theo thời lượng",
162
+ "cmd_sync_jira": "Đồng bộ 2 chiều với Jira / Xray / Zephyr (pull story, push tests, tạo bug tự động)",
163
+ "cmd_trend": "Phân tích xu hướng chất lượng và độ ổn định kiểm thử theo thời gian",
164
+ "cmd_flaky": "Phát hiện kiểm thử chập chờn (flaky) và quản lý vòng đời cách ly",
165
+ "cmd_canary": "Chạy đánh giá chuẩn độ bền vững canary tự động",
166
+ "cmd_watch": "Chế độ giám sát thay đổi thời gian thực & giao diện HUD (< 100ms)",
167
+ "cmd_pinpoint_failure": "Phân tích JUnit XML và định vị chính xác dòng lỗi trong 0.1s",
168
+ "cmd_ci_hook": "Hook tự động phục hồi trong CI/CD & tự động tạo PR sửa lỗi",
169
+ "cmd_debt": "Thu hoạch các chú thích shortcut: vào sổ cái nợ kỹ thuật cần xử lý",
170
+ "cmd_review": "Đánh giá chất lượng code chuẩn Senior Dev (lỗi, bảo mật, tải, test, code thừa)",
171
+ "cmd_safety_check": "Tường lửa an toàn thao tác & khoanh vùng bán kính ảnh hưởng",
172
+ "cmd_contract_drift": "Phát hiện sai lệch và vi phạm tương thích ngược trong OpenAPI/Swagger",
173
+ "cmd_skillspector": "Quét bảo mật kỹ năng AI Agent & MCP (71 véc-tơ theo chuẩn NVIDIA SkillSpector)",
174
+ "cmd_skills": "Liệt kê, lọc và kiểm tra các kỹ năng AI Agent và 4 gói năng lực cốt lõi",
175
+ "cmd_verify_author": "Xác minh tác quyền tác giả, nguồn gốc và tính toàn vẹn chống chỉnh sửa",
176
+ "cmd_wcag_audit": "Kiểm toán độ tương phản và tuân thủ tiêu chuẩn tiếp cận WCAG 2.2",
177
+ "cmd_impact": "Phân tích phạm vi ảnh hưởng thay đổi mã nguồn qua đồ thị tri thức AST",
178
+ "cmd_review_spec": "Đánh giá chất lượng tài liệu đặc tả & user story theo mô hình Elephant-Goldfish",
179
+ "cmd_drift_check": "Giám sát độ lệch giữa đặc tả và mã kiểm thử thực tế (Deficit & Scope Drift)",
180
+ "cmd_trace_data_flow": "Theo dõi vòng đời dữ liệu test để phát hiện rò rỉ DB và thiếu sót teardown",
181
+ "cmd_distill": "Cô đọng và tinh lọc log dài dòng giảm 95% độ nhiễu",
182
+ "cmd_gherkin": "Biên dịch file Gherkin .feature thành ma trận kiểm thử, Universal IR và báo cáo thiếu phủ (0-token)",
183
+ "cmd_omni_scan": "Quét toàn bộ dự án và thống kê danh mục kiểm thử đa ngôn ngữ (0-token)",
184
+ "cmd_report_bug": "Tự động tạo phiếu báo lỗi Jira/Markdown chuyên nghiệp kèm phân tích nguyên nhân gốc",
185
+ "cmd_mock_shield": "Tạo lá chắn chặn bắt API Route & tiêm lỗi hỗn loạn (Chaos Injection)",
186
+ "cmd_visual_mask": "Mặt nạ thị giác thông minh & chặn hoạt ảnh chống chập chờn giao diện",
187
+ "cmd_migrate": "Tự động chuyển đổi toàn diện bộ test cũ (Katalon/Cypress) sang Playwright hiện đại",
188
+ "cmd_decouple_config": "Tách biệt URL, tài khoản và bí mật cứng vào các cấu hình môi trường chuẩn",
189
+ "cmd_export_postman": "Xuất OpenAPI / Swagger / HAR sang Postman Collection v2.1.0 kèm assert tự động",
190
+ "cmd_generate_jmx": "Tạo kịch bản Apache JMeter 5.x (.jmx) chuyên sâu với đầy đủ tính năng tải doanh nghiệp",
191
+ "cmd_analyze_jtl": "Phân tích kết quả JMeter .jtl, đánh giá SLA P90/P95/P99 và chốt cổng CI/CD",
192
+ "cmd_correlate_telemetry": "Đối chiếu độ trễ client JMeter với chỉ số CPU/RAM/DB máy chủ (APM Telemetry)",
193
+ "cmd_analyze_newman": "Phân tích kết quả Newman/Postman, sàng lọc assert lỗi và chốt cổng kiểm soát CI/CD",
194
+ "cmd_tokens": "Kiểm toán lượng token tiêu thụ và chi phí ước tính trên Antigravity, Cursor, Claude Code",
195
+ "cmd_lookup_tc": "Tra cứu ca kiểm thử theo mã ID, nhãn tag, độ ưu tiên hoặc luồng nghiệp vụ",
196
+ "cmd_lookup_xpath": "Tra cứu bộ định vị phần tử XPath và AOM bền vững đã ghi nhớ",
197
+ "cmd_generate_tc": "Biên dịch tài liệu yêu cầu / user story tự nhiên thành kịch bản Clean POM chuẩn hóa",
198
+ "cmd_api_matrix": "Tạo ma trận kiểm thử Positive, Boundary và Negative từ tài liệu OpenAPI/Swagger",
199
+ "cmd_canvas_diff": "So sánh khác biệt giao diện đồ họa Canvas HTML5 & kiểm tra lỗi canvas trống",
200
+ "cmd_validate_groovy": "Kiểm tra trước cú pháp đóng mở ngoặc và tính hợp lệ kịch bản Groovy",
201
+ "cmd_mcp_serve": "Khởi chạy máy chủ giao thức Model Context Protocol (MCP) chuẩn JSON-RPC 2.0",
202
+ "cmd_mcp_excel": "Khởi chạy máy chủ MCP Excel chuyên dụng qua luồng stdio",
203
+ "cmd_mcp_docx": "Khởi chạy máy chủ MCP Word (.docx) chuyên dụng qua luồng stdio",
204
+ "cmd_release": "Phát hành 1-click: nâng số phiên bản, kiểm tra 10 Cổng DoD, gắn tag git và xuất bản NPM",
205
+ "cmd_publish": "Quy trình phát hành trọn gói 1-click: đẩy nhánh main, tạo tag git, phát hành GitHub Release & NPM",
206
+ "subcommands_help": "Danh sách các lệnh khả dụng",
207
+ "typo_error": "❌ Lỗi: Lệnh '{choice}' không tồn tại trong Synapse-Hub.",
208
+ "typo_suggest": "💡 Có phải ý bạn là: {suggestions} ?",
209
+ "typo_help_hint": "👉 Thử chạy: agent-qa {first_match} --help",
210
+ "typo_list_hint": "👉 Gõ 'agent-qa --help' để xem danh sách tất cả các lệnh khả dụng.",
211
+ }
212
+ }
213
+
214
+
215
+ def _probe_cli_flag(cli_flag: Optional[str]) -> Optional[str]:
216
+ """Probes the CLI flag for valid language codes ('vi', 'en')."""
217
+ if not cli_flag:
218
+ return None
219
+ val = str(cli_flag).strip().lower()
220
+ if val.startswith(("--lang=", "-l=")):
221
+ val = val.split("=", 1)[1].strip().lower()
222
+ if val in ("vi", "en"):
223
+ return val
224
+ return None
225
+
226
+
227
+ def _probe_env_lang() -> Optional[str]:
228
+ """Probes the SYNAPSE_LANG environment variable."""
229
+ env_lang = os.environ.get("SYNAPSE_LANG", "").strip().lower()
230
+ if env_lang in ("vi", "en"):
231
+ return env_lang
232
+ return None
233
+
234
+
235
+ def persist_language_preference(lang: str, target_dir: Optional[str] = None) -> str:
236
+ """
237
+ Persists the chosen language code ('en' or 'vi') to configuration.
238
+ 1. If SYNAPSE_CONFIG_PATH is set in environment, persists to that file.
239
+ 2. Else if target_dir is provided, persists to target_dir/.synapse.json.
240
+ 3. Else if .synapse.json exists in CWD, updates it.
241
+ 4. Else if TARGET_PROJECT_DIR env var is set and has .synapse.json, updates it.
242
+ 5. Otherwise, persists globally to ~/.synapse.json.
243
+ Returns the path of the file that was updated or created.
244
+ """
245
+ clean_lang = str(lang).strip().lower()
246
+ if clean_lang not in ("vi", "en"):
247
+ raise ValueError(f"Invalid language code: '{lang}'. Must be 'en' or 'vi'.")
248
+
249
+ env_cfg = os.environ.get("SYNAPSE_CONFIG_PATH")
250
+ if env_cfg:
251
+ cfg_path = os.path.abspath(env_cfg)
252
+ elif target_dir:
253
+ cfg_path = os.path.abspath(os.path.join(target_dir, ".synapse.json"))
254
+ elif os.path.isfile(os.path.join(os.getcwd(), ".synapse.json")):
255
+ cfg_path = os.path.abspath(os.path.join(os.getcwd(), ".synapse.json"))
256
+ elif os.environ.get("TARGET_PROJECT_DIR") and os.path.isfile(os.path.join(os.environ["TARGET_PROJECT_DIR"], ".synapse.json")):
257
+ cfg_path = os.path.abspath(os.path.join(os.environ["TARGET_PROJECT_DIR"], ".synapse.json"))
258
+ else:
259
+ cfg_path = os.path.expanduser("~/.synapse.json")
260
+
261
+ data: Dict[str, Any] = {}
262
+ if os.path.isfile(cfg_path):
263
+ try:
264
+ with open(cfg_path, "r", encoding="utf-8") as f:
265
+ loaded = json.load(f)
266
+ if isinstance(loaded, dict):
267
+ data = loaded
268
+ except Exception as _err:
269
+ _ = _err
270
+ data = {}
271
+
272
+ data["language"] = clean_lang
273
+
274
+ parent = os.path.dirname(cfg_path)
275
+ if parent:
276
+ os.makedirs(parent, exist_ok=True)
277
+
278
+ with open(cfg_path, "w", encoding="utf-8") as f:
279
+ json.dump(data, f, indent=2, ensure_ascii=False)
280
+ f.write("\n")
281
+
282
+ return cfg_path
283
+
284
+
285
+ def _probe_config_file_lang() -> Optional[str]:
286
+ """Probes target project config (.synapse.json) in CWD or TARGET_PROJECT_DIR."""
287
+ try:
288
+ candidate_dirs = [os.getcwd()]
289
+ target_env = os.environ.get("TARGET_PROJECT_DIR")
290
+ if target_env:
291
+ candidate_dirs.append(target_env)
292
+ for d in candidate_dirs:
293
+ cfg_path = os.path.join(d, ".synapse.json")
294
+ if os.path.isfile(cfg_path):
295
+ try:
296
+ with open(cfg_path, "r", encoding="utf-8") as f:
297
+ cfg_data = json.load(f)
298
+ if isinstance(cfg_data, dict):
299
+ cfg_lang = str(cfg_data.get("language", "")).strip().lower()
300
+ if cfg_lang in ("vi", "en"):
301
+ return cfg_lang
302
+ except Exception as _err:
303
+ _ = _err
304
+ continue
305
+ except Exception as _err:
306
+ _ = _err
307
+ return None
308
+
309
+
310
+ def _probe_global_config_lang() -> Optional[str]:
311
+ """Probes user global config ~/.synapse.json or SYNAPSE_CONFIG_PATH."""
312
+ try:
313
+ env_cfg = os.environ.get("SYNAPSE_CONFIG_PATH")
314
+ cfg_path = os.path.abspath(env_cfg) if env_cfg else os.path.expanduser("~/.synapse.json")
315
+ if os.path.isfile(cfg_path):
316
+ try:
317
+ with open(cfg_path, "r", encoding="utf-8") as f:
318
+ cfg_data = json.load(f)
319
+ if isinstance(cfg_data, dict):
320
+ cfg_lang = str(cfg_data.get("language", "")).strip().lower()
321
+ if cfg_lang in ("vi", "en"):
322
+ return cfg_lang
323
+ except Exception as _err:
324
+ _ = _err
325
+ except Exception as _err:
326
+ _ = _err
327
+ return None
328
+
329
+
330
+ def _probe_os_locale_lang() -> Optional[str]:
331
+ """Probes the OS system locale environment variables and locale module."""
332
+ try:
333
+ for loc_key in ("LC_ALL", "LC_MESSAGES", "LANG"):
334
+ val = (os.environ.get(loc_key) or "").lower()
335
+ if val:
336
+ if val.startswith("vi"):
337
+ return "vi"
338
+ if val.startswith("en"):
339
+ return "en"
340
+ return None
341
+ loc_tuple = locale.getlocale() if hasattr(locale, "getlocale") else None
342
+ if loc_tuple and loc_tuple[0]:
343
+ code = loc_tuple[0].lower()
344
+ if code.startswith("vi"):
345
+ return "vi"
346
+ if code.startswith("en"):
347
+ return "en"
348
+ if hasattr(locale, "getdefaultlocale"):
349
+ raw_def = locale.getdefaultlocale()[0]
350
+ if raw_def:
351
+ def_loc = raw_def.lower()
352
+ if def_loc.startswith("vi"):
353
+ return "vi"
354
+ if def_loc.startswith("en"):
355
+ return "en"
356
+ except Exception as _err:
357
+ _ = _err
358
+ return None
359
+
360
+
361
+ def resolve_language(cli_flag: Optional[str] = None) -> str:
362
+ """
363
+ Resolves the active interface language with precedence:
364
+ 1. CLI flag: --lang {en,vi}
365
+ 2. Environment Variable: SYNAPSE_LANG=en|vi
366
+ 3. Target Project Config: .synapse.json ("language": "en"|"vi")
367
+ 4. User Global Config: ~/.synapse.json ("language": "en"|"vi")
368
+ 5. Fallback: "en" (Strictly English default per specification)
369
+ """
370
+ return (
371
+ _probe_cli_flag(cli_flag)
372
+ or _probe_env_lang()
373
+ or _probe_config_file_lang()
374
+ or _probe_global_config_lang()
375
+ or "en"
376
+ )
377
+
378
+
379
+
380
+ def t(key: str, lang: str = "en", **kwargs: Any) -> str:
381
+ """
382
+ Translates a message key into target language with optional formatting.
383
+ Falls back to English if the key is missing from the target language,
384
+ and falls back to the key itself if not found in English.
385
+ """
386
+ lang_code = (lang or "en").lower()
387
+ lang_dict = MESSAGES.get(lang_code, MESSAGES["en"])
388
+ template = lang_dict.get(key, MESSAGES.get("en", {}).get(key, key))
389
+ if kwargs:
390
+ try:
391
+ return template.format(**kwargs)
392
+ except Exception:
393
+ return template
394
+ return template