@teevee98/synapse-hub 0.0.0-stage → 3.8.2

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 +172 -0
  190. package/README.md +171 -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 +197 -0
  196. package/docs/ARCHITECTURE.md +198 -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 +175 -0
  200. package/docs/CLI_REFERENCE.md +177 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +784 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +121 -0
  206. package/docs/QUALITY_GATES.md +121 -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 +1359 -0
  212. package/docs/schemas/synapse.config.schema.json +87 -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 +32 -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 +2079 -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 +258 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +184 -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 +2419 -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 +307 -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 +724 -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 +1259 -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,332 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
5
+
6
+ """
7
+ Reusable Process Group Supervisor & Zombie Process Reaper (tools.core.process_supervisor)
8
+ ------------------------------------------------------------------------------------------
9
+ Guarantees hermetic lifecycle supervision of external test runners and headless browsers.
10
+ Prevents orphaned zombie processes (chromedriver, chromium, node, java) from exhausting
11
+ system file descriptors and RAM on CI runners and local developer workstations.
12
+
13
+ Key Mechanisms:
14
+ 1. Process Group Isolation:
15
+ - On POSIX: `start_new_session=True` assigns a distinct process group ID (`pgid = proc.pid`).
16
+ - On Windows: `CREATE_NEW_PROCESS_GROUP` isolates the process hierarchy.
17
+ 2. Two-Stage Cascading Reap:
18
+ - Stage 1: Graceful termination via SIGTERM / SIGBREAK with bounded grace period.
19
+ - Stage 2: Forceful termination via SIGKILL / taskkill /F to eradicate descendants.
20
+ 3. Optional psutil Integration:
21
+ - If psutil is present in environment, scans and kills recursive child trees directly.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import os
27
+ import signal
28
+ import subprocess
29
+ import sys
30
+ import time
31
+ from dataclasses import dataclass
32
+ from typing import Any, Dict, List, Optional, Tuple
33
+
34
+
35
+ @dataclass
36
+ class SupervisedResult:
37
+ """Outcome of a supervised subprocess execution."""
38
+ cmd: List[str]
39
+ returncode: int
40
+ stdout: str
41
+ stderr: str
42
+ timed_out: bool = False
43
+ duration_sec: float = 0.0
44
+
45
+ @property
46
+ def ok(self) -> bool:
47
+ return self.returncode == 0 and not self.timed_out
48
+
49
+
50
+ def kill_process_tree(pid: int, timeout: float = 2.0) -> bool:
51
+ """
52
+ Terminates a process and all of its descendant child/grandchild processes.
53
+ Cross-platform: uses process groups on POSIX, taskkill on Windows, or psutil if available.
54
+ """
55
+ if pid <= 0:
56
+ return False
57
+
58
+ # 1. Try psutil if installed
59
+ try:
60
+ import psutil # type: ignore
61
+ try:
62
+ parent = psutil.Process(pid)
63
+ children = parent.children(recursive=True)
64
+ for child in children:
65
+ try:
66
+ child.terminate()
67
+ except (psutil.NoSuchProcess, psutil.AccessDenied) as err:
68
+ _ = err
69
+ parent.terminate()
70
+
71
+ gone, alive = psutil.wait_procs(children + [parent], timeout=timeout)
72
+ for p in alive:
73
+ try:
74
+ p.kill()
75
+ except (psutil.NoSuchProcess, psutil.AccessDenied) as err:
76
+ _ = err
77
+ return True
78
+ except (psutil.NoSuchProcess, psutil.AccessDenied):
79
+ return True
80
+ except ImportError as err:
81
+ _ = err
82
+
83
+ # 2. Platform-native fallback
84
+ if sys.platform == "win32":
85
+ try:
86
+ subprocess.run(
87
+ ["taskkill", "/F", "/T", "/PID", str(pid)],
88
+ stdout=subprocess.DEVNULL,
89
+ stderr=subprocess.DEVNULL,
90
+ check=False,
91
+ timeout=5.0
92
+ )
93
+ return True
94
+ except Exception:
95
+ return False
96
+ else:
97
+ # POSIX: use process group if PID is group leader, combined with recursive descendant tracking
98
+ descendant_pids: List[int] = []
99
+ to_check = [pid]
100
+ while to_check:
101
+ curr = to_check.pop(0)
102
+ try:
103
+ out = subprocess.run(
104
+ ["pgrep", "-P", str(curr)],
105
+ capture_output=True,
106
+ text=True,
107
+ timeout=1.0,
108
+ check=False
109
+ )
110
+ if out.returncode == 0:
111
+ for line in out.stdout.splitlines():
112
+ c_str = line.strip()
113
+ if c_str.isdigit():
114
+ cp = int(c_str)
115
+ if cp not in descendant_pids and cp != pid:
116
+ descendant_pids.append(cp)
117
+ to_check.append(cp)
118
+ except Exception as err:
119
+ _ = err
120
+
121
+ try:
122
+ pgid = os.getpgid(pid)
123
+ except OSError as err:
124
+ _ = err
125
+ pgid = None
126
+
127
+ # Stage 1: Graceful SIGTERM to process group and individual descendants
128
+ if pgid is not None:
129
+ try:
130
+ os.killpg(pgid, signal.SIGTERM)
131
+ except OSError as err:
132
+ _ = err
133
+ for p in [pid] + descendant_pids:
134
+ try:
135
+ os.kill(p, signal.SIGTERM)
136
+ except OSError as err:
137
+ _ = err
138
+
139
+ # Bounded polling wait before force kill
140
+ start = time.time()
141
+ while time.time() - start < timeout:
142
+ alive = False
143
+ if pgid is not None:
144
+ try:
145
+ os.killpg(pgid, 0)
146
+ alive = True
147
+ except OSError as err:
148
+ _ = err
149
+ for p in [pid] + descendant_pids:
150
+ try:
151
+ os.kill(p, 0)
152
+ alive = True
153
+ except OSError as err:
154
+ _ = err
155
+ if not alive:
156
+ return True
157
+ time.sleep(0.05)
158
+
159
+ # Stage 2: Forceful SIGKILL to eradicate all remaining processes
160
+ for p in descendant_pids + [pid]:
161
+ try:
162
+ os.kill(p, signal.SIGKILL)
163
+ except OSError as err:
164
+ _ = err
165
+ if pgid is not None:
166
+ try:
167
+ os.killpg(pgid, signal.SIGKILL)
168
+ except OSError as err:
169
+ _ = err
170
+ try:
171
+ subprocess.run(["pkill", "-KILL", "-P", str(pid)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2.0)
172
+ except Exception as err:
173
+ _ = err
174
+ return True
175
+
176
+
177
+ def reap_orphan_processes(target_names: Optional[Tuple[str, ...]] = None) -> int:
178
+ """
179
+ Safeguard reaper for orphaned runner and browser processes.
180
+ Defaults to known test drivers: chromedriver, chromium, node, java.
181
+ Returns the count of reaped processes.
182
+ """
183
+ targets = target_names or ("chromedriver", "geckodriver", "chromium", "playwright")
184
+ reaped = 0
185
+
186
+ try:
187
+ import psutil # type: ignore
188
+ current_pid = os.getpid()
189
+ for proc in psutil.process_iter(attrs=["pid", "name"]):
190
+ try:
191
+ pname = (proc.info.get("name") or "").lower()
192
+ pid = proc.info.get("pid")
193
+ if pid and pid != current_pid and any(t in pname for t in targets):
194
+ proc.kill()
195
+ reaped += 1
196
+ except (psutil.NoSuchProcess, psutil.AccessDenied):
197
+ continue
198
+ return reaped
199
+ except ImportError as err:
200
+ _ = err
201
+
202
+ # Native CLI fallbacks when psutil is not available
203
+ if sys.platform == "win32":
204
+ for target in targets:
205
+ im_name = target if target.endswith(".exe") else f"{target}.exe"
206
+ try:
207
+ res = subprocess.run(
208
+ ["taskkill", "/F", "/IM", im_name],
209
+ stdout=subprocess.DEVNULL,
210
+ stderr=subprocess.DEVNULL,
211
+ timeout=5.0
212
+ )
213
+ if res.returncode == 0:
214
+ reaped += 1
215
+ except Exception as err:
216
+ _ = err
217
+ else:
218
+ for target in targets:
219
+ try:
220
+ res = subprocess.run(
221
+ ["pkill", "-f", target],
222
+ stdout=subprocess.DEVNULL,
223
+ stderr=subprocess.DEVNULL,
224
+ timeout=5.0
225
+ )
226
+ if res.returncode == 0:
227
+ reaped += 1
228
+ except Exception as err:
229
+ _ = err
230
+ return reaped
231
+
232
+
233
+ class ProcessSupervisor:
234
+ """
235
+ Supervises external process lifecycles with guaranteed group cleanup.
236
+ """
237
+
238
+ def __init__(self, default_timeout: float = 60.0):
239
+ self.default_timeout = default_timeout
240
+ self._active_pids: List[int] = []
241
+
242
+ def run(
243
+ self,
244
+ cmd: List[str],
245
+ timeout: Optional[float] = None,
246
+ cwd: Optional[str] = None,
247
+ env: Optional[Dict[str, str]] = None,
248
+ capture_output: bool = True,
249
+ text: bool = True,
250
+ input_data: Optional[str] = None,
251
+ ) -> SupervisedResult:
252
+ """
253
+ Executes cmd in an isolated session/process-group, ensuring all descendants
254
+ are reaped upon timeout or unexpected failure.
255
+ """
256
+ t_limit = timeout if timeout is not None else self.default_timeout
257
+ if t_limit is not None and t_limit <= 0:
258
+ t_limit = 0.001
259
+ start_time = time.perf_counter()
260
+
261
+ def _to_str(val: Any) -> str:
262
+ if isinstance(val, bytes):
263
+ return val.decode("utf-8", errors="replace")
264
+ return val or ""
265
+
266
+ # Process group configuration
267
+ popen_kwargs: Dict[str, Any] = {
268
+ "cwd": cwd,
269
+ "env": env,
270
+ }
271
+
272
+ if capture_output:
273
+ popen_kwargs["stdout"] = subprocess.PIPE
274
+ popen_kwargs["stderr"] = subprocess.PIPE
275
+ if input_data is not None:
276
+ popen_kwargs["stdin"] = subprocess.PIPE
277
+
278
+ if sys.platform == "win32":
279
+ popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
280
+ else:
281
+ popen_kwargs["start_new_session"] = True
282
+
283
+ proc = subprocess.Popen(cmd, text=text, **popen_kwargs)
284
+ self._active_pids.append(proc.pid)
285
+
286
+ stdout_data, stderr_data = "", ""
287
+ timed_out = False
288
+
289
+ try:
290
+ stdout_raw, stderr_raw = proc.communicate(input=input_data, timeout=t_limit)
291
+ stdout_data = _to_str(stdout_raw)
292
+ stderr_data = _to_str(stderr_raw)
293
+ returncode = proc.returncode
294
+ except subprocess.TimeoutExpired:
295
+ timed_out = True
296
+ kill_process_tree(proc.pid)
297
+ try:
298
+ stdout_raw, stderr_raw = proc.communicate(timeout=1.0)
299
+ stdout_data = _to_str(stdout_raw)
300
+ stderr_data = _to_str(stderr_raw)
301
+ except Exception as comm_err:
302
+ _ = comm_err
303
+ returncode = 124
304
+ except Exception as exc:
305
+ kill_process_tree(proc.pid)
306
+ returncode = 1
307
+ stderr_data = str(exc)
308
+ finally:
309
+ if proc.pid in self._active_pids:
310
+ self._active_pids.remove(proc.pid)
311
+
312
+ elapsed = time.perf_counter() - start_time
313
+ return SupervisedResult(
314
+ cmd=cmd,
315
+ returncode=returncode,
316
+ stdout=stdout_data,
317
+ stderr=stderr_data,
318
+ timed_out=timed_out,
319
+ duration_sec=elapsed
320
+ )
321
+
322
+ def cleanup_all(self):
323
+ """Emergency cleanup of any active process groups tracked by this supervisor."""
324
+ for pid in list(self._active_pids):
325
+ kill_process_tree(pid)
326
+ self._active_pids.clear()
327
+
328
+ def __enter__(self) -> ProcessSupervisor:
329
+ return self
330
+
331
+ def __exit__(self, exc_type, exc_val, exc_tb):
332
+ self.cleanup_all()
@@ -0,0 +1,329 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
5
+
6
+ """
7
+ Synapse Hub — Structured Observability & OpenTelemetry W3C Trace Context
8
+ -----------------------------------------------------------------------
9
+ Provides high-performance structured JSON logging and W3C TraceContext
10
+ propagation across multi-agent processes, tools, and CI runners.
11
+
12
+ Key Features:
13
+ 1. W3C TraceContext Specification (traceparent: 00-{trace_id}-{span_id}-{flags}):
14
+ - 128-bit Trace ID (32 hex characters) and 64-bit Span ID (16 hex characters).
15
+ - Deterministic injection/extraction across HTTP headers, dictionaries, and env vars.
16
+ 2. Thread & Async Safe Context Propagation:
17
+ - Backed by contextvars with zero cross-coroutine leakage.
18
+ 3. Structured JSON Logging:
19
+ - Formats standard log records into strict JSON conforming to:
20
+ {timestamp, level, trace_id, span_id, parent_span_id, module, event, duration_ms}
21
+ 4. Span Tracing Context Manager:
22
+ - `trace_span(event, module=...)` for measuring latencies and emitting trace spans.
23
+ """
24
+
25
+ import os
26
+ import sys
27
+ import json
28
+ import time
29
+ import secrets
30
+ import logging
31
+ import contextvars
32
+ from datetime import datetime, timezone
33
+ from dataclasses import dataclass
34
+ from typing import Dict, Any, Optional, Generator
35
+ from contextlib import contextmanager
36
+
37
+ # W3C Constants
38
+ W3C_VERSION = "00"
39
+ FLAG_SAMPLED = "01"
40
+ FLAG_NOT_SAMPLED = "00"
41
+ TRACEPARENT_HEADER = "traceparent"
42
+ TRACESTATE_HEADER = "tracestate"
43
+
44
+
45
+ def generate_trace_id() -> str:
46
+ """Generates a random 128-bit W3C Trace ID (32 lowercase hex characters)."""
47
+ return secrets.token_hex(16)
48
+
49
+
50
+ def generate_span_id() -> str:
51
+ """Generates a random 64-bit W3C Span ID (16 lowercase hex characters)."""
52
+ return secrets.token_hex(8)
53
+
54
+
55
+ @dataclass
56
+ class TraceContext:
57
+ """Represents a W3C TraceContext entity."""
58
+ trace_id: str
59
+ span_id: str
60
+ parent_span_id: Optional[str] = None
61
+ sampled: bool = True
62
+ trace_state: str = ""
63
+
64
+ @property
65
+ def traceparent(self) -> str:
66
+ flags = FLAG_SAMPLED if self.sampled else FLAG_NOT_SAMPLED
67
+ return f"{W3C_VERSION}-{self.trace_id}-{self.span_id}-{flags}"
68
+
69
+ def to_dict(self) -> Dict[str, Any]:
70
+ return {
71
+ "trace_id": self.trace_id,
72
+ "span_id": self.span_id,
73
+ "parent_span_id": self.parent_span_id,
74
+ "sampled": self.sampled,
75
+ "traceparent": self.traceparent,
76
+ "trace_state": self.trace_state,
77
+ }
78
+
79
+
80
+ _CURRENT_CONTEXT: contextvars.ContextVar[Optional[TraceContext]] = contextvars.ContextVar(
81
+ "synapse_trace_context", default=None
82
+ )
83
+
84
+
85
+ def get_current_trace_context() -> Optional[TraceContext]:
86
+ """Retrieves the active TraceContext for the current execution context."""
87
+ ctx = _CURRENT_CONTEXT.get()
88
+ if ctx is None and os.environ.get("TRACEPARENT"):
89
+ ctx = parse_traceparent(os.environ["TRACEPARENT"])
90
+ if ctx:
91
+ _CURRENT_CONTEXT.set(ctx)
92
+ return ctx
93
+
94
+
95
+ def set_current_trace_context(ctx: Optional[TraceContext]) -> None:
96
+ """Sets the active TraceContext for the current execution context."""
97
+ _CURRENT_CONTEXT.set(ctx)
98
+
99
+
100
+ def parse_traceparent(header_val: str) -> Optional[TraceContext]:
101
+ """
102
+ Parses a W3C traceparent header value.
103
+ Format: {version}-{trace_id}-{span_id}-{flags}
104
+ Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
105
+ """
106
+ if not header_val or not isinstance(header_val, str):
107
+ return None
108
+ parts = header_val.strip().split("-")
109
+ if len(parts) != 4:
110
+ return None
111
+
112
+ version, trace_id, span_id, flags = parts
113
+ if len(version) != 2 or len(trace_id) != 32 or len(span_id) != 16 or len(flags) != 2:
114
+ return None
115
+
116
+ # Version 'ff' is forbidden by W3C specification
117
+ if version.lower() == "ff":
118
+ return None
119
+
120
+ # Validate hex characters and non-all-zero ids
121
+ try:
122
+ v_int = int(version, 16)
123
+ t_int = int(trace_id, 16)
124
+ s_int = int(span_id, 16)
125
+ f_int = int(flags, 16)
126
+ if t_int == 0 or s_int == 0:
127
+ return None
128
+ except ValueError:
129
+ return None
130
+
131
+ sampled = flags == FLAG_SAMPLED or bool(int(flags, 16) & 1)
132
+ return TraceContext(
133
+ trace_id=trace_id.lower(),
134
+ span_id=span_id.lower(),
135
+ parent_span_id=None,
136
+ sampled=sampled,
137
+ )
138
+
139
+
140
+ def format_traceparent(trace_id: str, span_id: str, sampled: bool = True) -> str:
141
+ """Formats trace components into a valid W3C traceparent string."""
142
+ flags = FLAG_SAMPLED if sampled else FLAG_NOT_SAMPLED
143
+ return f"{W3C_VERSION}-{trace_id.lower()}-{span_id.lower()}-{flags}"
144
+
145
+
146
+ def inject_traceparent(headers: Optional[Dict[str, str]] = None, context: Optional[TraceContext] = None) -> Dict[str, str]:
147
+ """
148
+ Injects W3C traceparent into an HTTP headers dictionary or carrier.
149
+ If context is omitted, uses the current ambient context or generates a new one.
150
+ """
151
+ if headers is None:
152
+ headers = {}
153
+ ctx = context or get_current_trace_context()
154
+ if ctx is None:
155
+ ctx = create_trace_context()
156
+ set_current_trace_context(ctx)
157
+
158
+ headers[TRACEPARENT_HEADER] = ctx.traceparent
159
+ if ctx.trace_state:
160
+ headers[TRACESTATE_HEADER] = ctx.trace_state
161
+ return headers
162
+
163
+
164
+ def extract_traceparent(headers: Dict[str, str]) -> Optional[TraceContext]:
165
+ """Extracts W3C traceparent and tracestate from an HTTP headers dictionary (case-insensitive keys)."""
166
+ if not headers or not isinstance(headers, dict):
167
+ return None
168
+ ctx: Optional[TraceContext] = None
169
+ state = ""
170
+ for k, v in headers.items():
171
+ if not isinstance(v, str):
172
+ continue
173
+ k_lower = k.lower()
174
+ if k_lower == TRACEPARENT_HEADER:
175
+ ctx = parse_traceparent(v)
176
+ elif k_lower == TRACESTATE_HEADER:
177
+ state = v.strip()
178
+ if ctx and state:
179
+ ctx.trace_state = state
180
+ return ctx
181
+
182
+
183
+ def create_trace_context(
184
+ parent: Optional[TraceContext] = None,
185
+ trace_id: Optional[str] = None,
186
+ sampled: bool = True
187
+ ) -> TraceContext:
188
+ """Creates a new TraceContext, linking to parent span if supplied."""
189
+ if parent is not None:
190
+ return TraceContext(
191
+ trace_id=parent.trace_id,
192
+ span_id=generate_span_id(),
193
+ parent_span_id=parent.span_id,
194
+ sampled=parent.sampled,
195
+ trace_state=parent.trace_state,
196
+ )
197
+ return TraceContext(
198
+ trace_id=trace_id or generate_trace_id(),
199
+ span_id=generate_span_id(),
200
+ parent_span_id=None,
201
+ sampled=sampled,
202
+ )
203
+
204
+
205
+ class StructuredJsonFormatter(logging.Formatter):
206
+ """
207
+ Formats log records into structured JSON conforming to enterprise schema:
208
+ {timestamp, level, trace_id, span_id, parent_span_id, module, event, duration_ms, message}
209
+ """
210
+
211
+ def format(self, record: logging.LogRecord) -> str:
212
+ ctx = get_current_trace_context()
213
+ record_dict: Dict[str, Any] = {
214
+ "timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
215
+ "level": record.levelname,
216
+ "trace_id": getattr(record, "trace_id", ctx.trace_id if ctx else None),
217
+ "span_id": getattr(record, "span_id", ctx.span_id if ctx else None),
218
+ "parent_span_id": getattr(record, "parent_span_id", ctx.parent_span_id if ctx else None),
219
+ "module": getattr(record, "module_name", record.module),
220
+ "event": getattr(record, "event", record.getMessage()),
221
+ "duration_ms": getattr(record, "duration_ms", None),
222
+ }
223
+
224
+ # Include custom extra fields
225
+ if hasattr(record, "extra_payload") and isinstance(record.extra_payload, dict):
226
+ record_dict.update(record.extra_payload)
227
+
228
+ # Include exception if present
229
+ if record.exc_info:
230
+ record_dict["exception"] = self.formatException(record.exc_info)
231
+
232
+ return json.dumps(record_dict, ensure_ascii=False)
233
+
234
+
235
+ def get_logger(name: str = "synapse") -> logging.Logger:
236
+ """Returns or configures a standard structured logger with JSON output."""
237
+ logger = logging.getLogger(name)
238
+ if not any(isinstance(h.formatter, StructuredJsonFormatter) for h in logger.handlers):
239
+ handler = logging.StreamHandler(sys.stdout)
240
+ handler.setFormatter(StructuredJsonFormatter())
241
+ logger.addHandler(handler)
242
+ logger.setLevel(logging.INFO)
243
+ return logger
244
+
245
+
246
+ def log_event(
247
+ level: str,
248
+ event: str,
249
+ module: Optional[str] = None,
250
+ duration_ms: Optional[float] = None,
251
+ logger_name: str = "synapse",
252
+ **extra_payload
253
+ ) -> Dict[str, Any]:
254
+ """
255
+ Emits a structured JSON log event directly.
256
+ Returns the serialized structured dictionary for assertions or inspection.
257
+ """
258
+ ctx = get_current_trace_context()
259
+ payload: Dict[str, Any] = {
260
+ "timestamp": datetime.now(timezone.utc).isoformat(),
261
+ "level": level.upper(),
262
+ "trace_id": ctx.trace_id if ctx else None,
263
+ "span_id": ctx.span_id if ctx else None,
264
+ "parent_span_id": ctx.parent_span_id if ctx else None,
265
+ "module": module or "synapse",
266
+ "event": event,
267
+ "duration_ms": duration_ms,
268
+ }
269
+ if extra_payload:
270
+ payload.update(extra_payload)
271
+
272
+ lvl_num = getattr(logging, level.upper(), logging.INFO)
273
+ logger = get_logger(logger_name)
274
+ logger.log(
275
+ lvl_num,
276
+ event,
277
+ extra={
278
+ "module_name": payload["module"],
279
+ "event": event,
280
+ "duration_ms": duration_ms,
281
+ "trace_id": payload["trace_id"],
282
+ "span_id": payload["span_id"],
283
+ "parent_span_id": payload["parent_span_id"],
284
+ "extra_payload": extra_payload,
285
+ }
286
+ )
287
+ return payload
288
+
289
+
290
+ @contextmanager
291
+ def trace_span(
292
+ event: str,
293
+ module: Optional[str] = None,
294
+ logger_name: str = "synapse",
295
+ **attributes
296
+ ) -> Generator[TraceContext, None, None]:
297
+ """
298
+ Context manager that starts a child span, measures latency,
299
+ logs the completed span with duration_ms, and restores the parent context.
300
+ """
301
+ parent_ctx = get_current_trace_context()
302
+ span_ctx = create_trace_context(parent=parent_ctx)
303
+ set_current_trace_context(span_ctx)
304
+ start_time = time.perf_counter()
305
+ status = "SUCCESS"
306
+ err_msg = None
307
+
308
+ try:
309
+ yield span_ctx
310
+ except Exception as exc:
311
+ status = "ERROR"
312
+ err_msg = str(exc)
313
+ raise
314
+ finally:
315
+ elapsed_ms = round((time.perf_counter() - start_time) * 1000.0, 3)
316
+ extra = dict(attributes)
317
+ extra["status"] = status
318
+ if err_msg:
319
+ extra["error"] = err_msg
320
+
321
+ log_event(
322
+ level="INFO" if status == "SUCCESS" else "ERROR",
323
+ event=event,
324
+ module=module or "synapse",
325
+ duration_ms=elapsed_ms,
326
+ logger_name=logger_name,
327
+ **extra
328
+ )
329
+ set_current_trace_context(parent_ctx)