@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,438 @@
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
+ OpenXML Security & Protocol Defense Guard
8
+ -----------------------------------------
9
+ Shared hardening library for OpenXML MCP servers (Word .docx and Excel .xlsx).
10
+ Provides:
11
+ 1. Canonical workspace path traversal validation & sandbox enforcement.
12
+ 2. Zip-bomb defense (uncompressed size, compression ratio, entry count).
13
+ 3. OpenXML XML parsing resilience (handling malformed XML, missing parts, 0-byte files).
14
+ 4. Standard JSON-RPC 2.0 error and response helpers (-32700 to -32603).
15
+ """
16
+
17
+ import os
18
+ import sys
19
+ import zipfile
20
+ import tempfile
21
+ import xml.etree.ElementTree as ET
22
+ from pathlib import Path
23
+ from typing import Dict, Any, List, Optional, Tuple, Union
24
+
25
+ # Enforce UTF-8 stdout encoding for Windows console compatibility
26
+ if hasattr(sys.stdout, 'reconfigure'):
27
+ try:
28
+ sys.stdout.reconfigure(encoding='utf-8')
29
+ sys.stderr.reconfigure(encoding='utf-8')
30
+ except Exception:
31
+ pass
32
+
33
+ # Security Thresholds
34
+ MAX_FILE_SIZE = 50 * 1024 * 1024 # 50 MB
35
+ MAX_UNCOMPRESSED_SIZE = 200 * 1024 * 1024 # 200 MB
36
+ MAX_RATIO = 100.0 # 100:1 compression ratio limit
37
+ MAX_ZIP_ENTRIES = 10000 # 10,000 entries threshold
38
+
39
+ # JSON-RPC 2.0 Standard Error Codes
40
+ PARSE_ERROR = -32700 # Invalid JSON was received by the server.
41
+ INVALID_REQUEST = -32600 # The JSON sent is not a valid Request object.
42
+ METHOD_NOT_FOUND = -32601 # The method does not exist / is not available.
43
+ INVALID_PARAMS = -32602 # Invalid method parameter(s).
44
+ INTERNAL_ERROR = -32603 # Internal JSON-RPC error.
45
+
46
+
47
+ def get_workspace_root() -> Path:
48
+ """Returns canonical workspace root directory from environment or current working directory."""
49
+ env_root = os.environ.get("SYNAPSE_PROJECT_ROOT") or os.environ.get("SYNAPSE_WORKSPACE")
50
+ if env_root:
51
+ return Path(env_root).resolve()
52
+ repo_root = Path(__file__).resolve().parent.parent
53
+ cwd = Path.cwd().resolve()
54
+ # If daemon was launched from an application bundle (e.g. AppData/Local/Programs/antigravity), default to repo_root
55
+ cwd_lower = str(cwd).lower()
56
+ if "antigravity" in cwd_lower or "electron" in cwd_lower or "programs" in cwd_lower:
57
+ return repo_root
58
+ for prefix in get_sensitive_prefixes():
59
+ try:
60
+ res_prefix = prefix.resolve()
61
+ if cwd == res_prefix or res_prefix in cwd.parents:
62
+ return repo_root
63
+ except (ValueError, OSError):
64
+ continue
65
+ return cwd
66
+
67
+
68
+ def get_sensitive_prefixes() -> List[Path]:
69
+ """Returns list of sensitive system directories that must never be accessed."""
70
+ prefixes: List[Path] = [
71
+ Path("/etc"),
72
+ Path("/var/run"),
73
+ Path("/proc"),
74
+ Path("/sys"),
75
+ Path("/dev"),
76
+ Path("/root"),
77
+ ]
78
+
79
+ # User credential directories
80
+ try:
81
+ user_home = Path.home().resolve()
82
+ prefixes.extend([
83
+ user_home / ".ssh",
84
+ user_home / ".aws",
85
+ user_home / ".gnupg",
86
+ user_home / ".config",
87
+ ])
88
+ except (OSError, RuntimeError) as err:
89
+ sys.stderr.write(f"Warning: Failed to resolve user home: {err}\n")
90
+
91
+ # Windows system directories
92
+ if os.name == "nt":
93
+ win_dir = os.environ.get("SystemRoot", "C:\\Windows")
94
+ prefixes.extend([
95
+ Path(win_dir),
96
+ Path(win_dir) / "System32",
97
+ Path(win_dir) / "SysWOW64",
98
+ Path("C:\\Program Files"),
99
+ Path("C:\\Program Files (x86)"),
100
+ ])
101
+
102
+ return prefixes
103
+
104
+
105
+ def validate_openxml_path(
106
+ path: Union[str, Path],
107
+ workspace_root: Optional[Union[str, Path]] = None,
108
+ allowed_extensions: Tuple[str, ...] = ('.docx', '.xlsx'),
109
+ max_file_size: int = MAX_FILE_SIZE,
110
+ allow_empty: bool = False
111
+ ) -> Path:
112
+ """
113
+ Validates that a path is safe, does not escape workspace boundaries,
114
+ does not point to sensitive directories, exists, and is a valid OpenXML document.
115
+
116
+ Raises:
117
+ ValueError: If path is empty, non-string, wrong extension, empty file (0 bytes), or exceeds size.
118
+ PermissionError: If path contains null bytes, UNC prefixes, traversal escapes, or points to system directories.
119
+ FileNotFoundError: If the file does not exist on disk.
120
+ """
121
+ if not path or not isinstance(path, (str, Path)):
122
+ raise ValueError("File path must be a non-empty string")
123
+
124
+ raw_path = str(path).strip()
125
+ if not raw_path:
126
+ raise ValueError("File path cannot be blank")
127
+
128
+ # Reject null bytes
129
+ if "\0" in raw_path:
130
+ raise PermissionError(f"Access denied: path contains null bytes '{raw_path}'")
131
+
132
+ # Reject UNC paths (Windows network shares)
133
+ if raw_path.startswith("\\\\") or raw_path.startswith("//"):
134
+ raise PermissionError(f"Access denied: UNC paths are not permitted '{raw_path}'")
135
+
136
+ # Normalize backslashes to forward slashes for cross-platform path resolution
137
+ normalized_path = raw_path.replace("\\", "/")
138
+ target = Path(normalized_path).resolve()
139
+
140
+ # Determine boundary roots
141
+ root = Path(workspace_root).resolve() if workspace_root else get_workspace_root()
142
+ temp_dir = Path(tempfile.gettempdir()).resolve()
143
+
144
+ # Check sensitive system prefixes without swallowing PermissionError
145
+ sensitive_prefixes = get_sensitive_prefixes()
146
+ for prefix in sensitive_prefixes:
147
+ try:
148
+ resolved_prefix = prefix.resolve()
149
+ except (ValueError, OSError):
150
+ continue
151
+ if target == resolved_prefix or resolved_prefix in target.parents:
152
+ raise PermissionError(f"Access denied: path points to protected system directory '{raw_path}'")
153
+
154
+ # Enforce boundary: MUST be inside workspace root OR inside temp directory
155
+ is_in_root = False
156
+ try:
157
+ is_in_root = (target == root or root in target.parents or target.is_relative_to(root))
158
+ except (ValueError, AttributeError):
159
+ try:
160
+ target.relative_to(root)
161
+ is_in_root = True
162
+ except ValueError:
163
+ is_in_root = False
164
+
165
+ is_in_temp = False
166
+ try:
167
+ is_in_temp = (target == temp_dir or temp_dir in target.parents or target.is_relative_to(temp_dir))
168
+ except (ValueError, AttributeError):
169
+ try:
170
+ target.relative_to(temp_dir)
171
+ is_in_temp = True
172
+ except ValueError:
173
+ is_in_temp = False
174
+
175
+ repo_root = Path(__file__).resolve().parent.parent
176
+ is_in_repo = False
177
+ try:
178
+ is_in_repo = (target == repo_root or repo_root in target.parents or target.is_relative_to(repo_root))
179
+ except (ValueError, AttributeError):
180
+ try:
181
+ target.relative_to(repo_root)
182
+ is_in_repo = True
183
+ except ValueError:
184
+ is_in_repo = False
185
+
186
+ if not is_in_root and not is_in_temp and not is_in_repo:
187
+ raise PermissionError(f"Access denied: path '{raw_path}' resolves outside authorized workspace '{root}'")
188
+
189
+ if not target.exists():
190
+ raise FileNotFoundError(f"File not found: '{raw_path}'")
191
+
192
+ if not target.is_file():
193
+ raise ValueError(f"Path is not a regular file: '{raw_path}'")
194
+
195
+ # Validate file size: reject 0-byte empty files unless explicitly permitted
196
+ file_size = target.stat().st_size
197
+ if not allow_empty and file_size == 0:
198
+ raise ValueError(f"OpenXML file is empty (0 bytes): '{raw_path}'")
199
+
200
+ if max_file_size and file_size > max_file_size:
201
+ raise ValueError(f"File exceeds maximum allowed size ({file_size} > {max_file_size} bytes)")
202
+
203
+ # Validate allowed extensions
204
+ if allowed_extensions:
205
+ ext = target.suffix.lower()
206
+ valid_exts = tuple(e.lower() for e in allowed_extensions)
207
+ if ext not in valid_exts:
208
+ raise ValueError(f"Invalid file extension '{ext}'. Allowed: {', '.join(allowed_extensions)}")
209
+
210
+ return target
211
+
212
+
213
+ def validate_docx_path(path: str, workspace_root: Optional[Union[str, Path]] = None) -> str:
214
+ """Convenience wrapper validating .docx paths and returning string representation."""
215
+ p = validate_openxml_path(path, workspace_root=workspace_root, allowed_extensions=('.docx',))
216
+ return str(p)
217
+
218
+
219
+ def validate_excel_path(path: str, workspace_root: Optional[Union[str, Path]] = None) -> str:
220
+ """Convenience wrapper validating .xlsx paths and returning string representation."""
221
+ p = validate_openxml_path(path, workspace_root=workspace_root, allowed_extensions=('.xlsx',))
222
+ return str(p)
223
+
224
+
225
+ def validate_output_path(
226
+ path: Union[str, Path],
227
+ workspace_root: Optional[Union[str, Path]] = None,
228
+ allowed_extensions: Optional[Tuple[str, ...]] = None,
229
+ create_parent: bool = True,
230
+ is_dir: bool = False
231
+ ) -> Path:
232
+ """
233
+ Validates destination output paths (e.g. for image extraction or exported spreadsheets)
234
+ to ensure output files do not escape the workspace sandbox or overwrite system files.
235
+ """
236
+ if not path or not isinstance(path, (str, Path)):
237
+ raise ValueError("Output path must be a non-empty string")
238
+
239
+ raw_path = str(path).strip()
240
+ if not raw_path:
241
+ raise ValueError("Output path cannot be blank")
242
+
243
+ if "\0" in raw_path:
244
+ raise PermissionError(f"Access denied: output path contains null bytes '{raw_path}'")
245
+
246
+ if raw_path.startswith("\\\\") or raw_path.startswith("//"):
247
+ raise PermissionError(f"Access denied: UNC paths are not permitted '{raw_path}'")
248
+
249
+ target = Path(raw_path).resolve()
250
+ root = Path(workspace_root).resolve() if workspace_root else get_workspace_root()
251
+ temp_dir = Path(tempfile.gettempdir()).resolve()
252
+
253
+ # Reject system directories
254
+ for prefix in get_sensitive_prefixes():
255
+ try:
256
+ resolved_prefix = prefix.resolve()
257
+ except (ValueError, OSError):
258
+ continue
259
+ if target == resolved_prefix or resolved_prefix in target.parents:
260
+ raise PermissionError(f"Access denied: output destination in protected directory '{raw_path}'")
261
+
262
+ # Enforce boundary
263
+ is_in_root = False
264
+ try:
265
+ is_in_root = (target == root or root in target.parents or target.is_relative_to(root))
266
+ except (ValueError, AttributeError):
267
+ try:
268
+ target.relative_to(root)
269
+ is_in_root = True
270
+ except ValueError:
271
+ is_in_root = False
272
+
273
+ is_in_temp = False
274
+ try:
275
+ is_in_temp = (target == temp_dir or temp_dir in target.parents or target.is_relative_to(temp_dir))
276
+ except (ValueError, AttributeError):
277
+ try:
278
+ target.relative_to(temp_dir)
279
+ is_in_temp = True
280
+ except ValueError:
281
+ is_in_temp = False
282
+
283
+ repo_root = Path(__file__).resolve().parent.parent
284
+ is_in_repo = False
285
+ try:
286
+ is_in_repo = (target == repo_root or repo_root in target.parents or target.is_relative_to(repo_root))
287
+ except (ValueError, AttributeError):
288
+ try:
289
+ target.relative_to(repo_root)
290
+ is_in_repo = True
291
+ except ValueError:
292
+ is_in_repo = False
293
+
294
+ if not is_in_root and not is_in_temp and not is_in_repo:
295
+ raise PermissionError(f"Access denied: output path '{raw_path}' resolves outside workspace '{root}'")
296
+
297
+ if allowed_extensions:
298
+ ext = target.suffix.lower()
299
+ valid_exts = tuple(e.lower() for e in allowed_extensions)
300
+ if ext not in valid_exts:
301
+ raise ValueError(f"Invalid output extension '{ext}'. Allowed: {', '.join(allowed_extensions)}")
302
+
303
+ if create_parent:
304
+ if is_dir or not target.suffix:
305
+ target.mkdir(parents=True, exist_ok=True)
306
+ else:
307
+ target.parent.mkdir(parents=True, exist_ok=True)
308
+
309
+ return target
310
+
311
+
312
+ def safe_open_zip(
313
+ zip_path: Union[str, Path],
314
+ max_entries: int = MAX_ZIP_ENTRIES,
315
+ max_uncompressed_size: int = MAX_UNCOMPRESSED_SIZE,
316
+ max_ratio: float = MAX_RATIO
317
+ ) -> zipfile.ZipFile:
318
+ """
319
+ Opens a zip archive with multi-tier zip-bomb and integrity safeguards:
320
+ - Validates archive is a valid zip without crashing.
321
+ - Enforces total entry count ceiling (<= max_entries).
322
+ - Enforces uncompressed size limit (<= max_uncompressed_size).
323
+ - Enforces compression ratio limit (<= max_ratio).
324
+
325
+ Raises:
326
+ ValueError: If zip bomb or corrupt archive is detected.
327
+ """
328
+ try:
329
+ z = zipfile.ZipFile(str(zip_path), "r")
330
+ except zipfile.BadZipFile as err:
331
+ raise ValueError(f"Corrupt or invalid zip archive: {err}")
332
+ except (KeyError, OSError, UnicodeDecodeError) as err:
333
+ raise ValueError(f"Failed to open zip archive: {err}")
334
+
335
+ try:
336
+ infolist = z.infolist()
337
+ except Exception as err:
338
+ z.close()
339
+ raise ValueError(f"Corrupt zip table of contents: {err}")
340
+
341
+ # 1. Entry count ceiling check
342
+ if len(infolist) > max_entries:
343
+ z.close()
344
+ raise ValueError(
345
+ f"Zip bomb detected: entry count ({len(infolist)}) exceeds ceiling of {max_entries} entries."
346
+ )
347
+
348
+ # 2. Total uncompressed size check
349
+ total_uncompressed = sum(info.file_size for info in infolist)
350
+ if total_uncompressed > max_uncompressed_size:
351
+ z.close()
352
+ raise ValueError(
353
+ f"Zip bomb detected: uncompressed size ({total_uncompressed} bytes) exceeds {max_uncompressed_size} bytes limit."
354
+ )
355
+
356
+ # 3. Compression ratio check
357
+ try:
358
+ compressed_size = os.path.getsize(str(zip_path))
359
+ except (OSError, ValueError):
360
+ compressed_size = 0
361
+
362
+ if compressed_size > 0 and (total_uncompressed / compressed_size) > max_ratio:
363
+ ratio = total_uncompressed / compressed_size
364
+ z.close()
365
+ raise ValueError(
366
+ f"Zip bomb detected: compression ratio ({ratio:.1f}:1) exceeds {max_ratio:.1f}:1 ceiling."
367
+ )
368
+
369
+ return z
370
+
371
+
372
+ def safe_parse_xml(source: Any) -> ET.Element:
373
+ """
374
+ Parses XML data safely from stream, bytes, or string.
375
+ Catches ET.ParseError, KeyError, and UnicodeDecodeError, raising clean ValueError.
376
+ """
377
+ try:
378
+ if isinstance(source, (bytes, str)):
379
+ return ET.fromstring(source)
380
+ tree = ET.parse(source)
381
+ return tree.getroot()
382
+ except ET.ParseError as err:
383
+ raise ValueError(f"Malformed XML document: {err}")
384
+ except (KeyError, UnicodeDecodeError) as err:
385
+ raise ValueError(f"XML decoding error: {err}")
386
+
387
+
388
+ def safe_read_xml_from_zip(z: zipfile.ZipFile, entry_name: str) -> Optional[ET.Element]:
389
+ """
390
+ Safely reads and parses an XML entry from an open zip archive.
391
+ Returns None if entry is missing, or parsed root Element if successful.
392
+ Raises ValueError on parse or decode failure.
393
+ """
394
+ if entry_name not in z.namelist():
395
+ return None
396
+ try:
397
+ with z.open(entry_name) as f:
398
+ return safe_parse_xml(f)
399
+ except (KeyError, ET.ParseError, UnicodeDecodeError, ValueError) as err:
400
+ raise ValueError(f"Corrupt OpenXML entry '{entry_name}': {err}")
401
+
402
+
403
+ def jsonrpc_error_response(
404
+ code: int,
405
+ message: str,
406
+ req_id: Any = None,
407
+ data: Any = None
408
+ ) -> Dict[str, Any]:
409
+ """Constructs a compliant JSON-RPC 2.0 error response preserving request id."""
410
+ err: Dict[str, Any] = {"code": code, "message": message}
411
+ if data is not None:
412
+ err["data"] = data
413
+ return {
414
+ "jsonrpc": "2.0",
415
+ "id": req_id,
416
+ "error": err
417
+ }
418
+
419
+
420
+ def jsonrpc_success_response(result: Any, req_id: Any = None) -> Dict[str, Any]:
421
+ """Constructs a compliant JSON-RPC 2.0 success response."""
422
+ return {
423
+ "jsonrpc": "2.0",
424
+ "id": req_id,
425
+ "result": result
426
+ }
427
+
428
+
429
+ def mcp_tool_result(content_text: str, is_error: bool = False, req_id: Any = None) -> Dict[str, Any]:
430
+ """Constructs a compliant MCP CallToolResult object."""
431
+ return {
432
+ "jsonrpc": "2.0",
433
+ "id": req_id,
434
+ "result": {
435
+ "content": [{"type": "text", "text": content_text}],
436
+ "isError": is_error
437
+ }
438
+ }
@@ -0,0 +1,182 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ Enterprise Standardized Output Formatter & Exit Code Specification
4
+ ------------------------------------------------------------------
5
+ Provides centralized terminal styling, NO_COLOR standard compliance,
6
+ and deterministic exit codes across all Synapse Hub CLI tools.
7
+
8
+ Exit Code Standards:
9
+ 0: EXIT_SUCCESS (Operation passed, DoD compliant)
10
+ 1: EXIT_FAILURE (Test failure, linter defect, gate rejection)
11
+ 2: EXIT_USAGE_ERROR (Invalid CLI arguments, syntax error)
12
+ 3: EXIT_SECURITY_BLOCK (Destructive action blocked, secret leaked, MIT license altered)
13
+ 4: EXIT_ENVIRONMENT_ERROR (Missing required tool, incompatible runtime)
14
+ """
15
+
16
+ import os
17
+ import sys
18
+ import json
19
+ import logging
20
+ from typing import Any
21
+
22
+ # Standard Exit Codes
23
+ EXIT_SUCCESS = 0
24
+ EXIT_FAILURE = 1
25
+ EXIT_USAGE_ERROR = 2
26
+ EXIT_SECURITY_BLOCK = 3
27
+ EXIT_ENVIRONMENT_ERROR = 4
28
+
29
+
30
+ def is_color_enabled() -> bool:
31
+ """
32
+ Determines if ANSI color codes should be rendered.
33
+ Honors https://no-color.org specification (NO_COLOR env var).
34
+ """
35
+ if os.environ.get("NO_COLOR") is not None:
36
+ return False
37
+ if os.environ.get("TERM") == "dumb":
38
+ return False
39
+ if os.environ.get("FORCE_COLOR") in ("1", "true", "TRUE"):
40
+ return True
41
+ return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
42
+
43
+
44
+ class Colors:
45
+ """ANSI color codes with dynamic NO_COLOR enforcement."""
46
+ ESC = "\033"
47
+ CYAN = "\033[96m"
48
+ GREEN = "\033[92m"
49
+ YELLOW = "\033[93m"
50
+ RED = "\033[91m"
51
+ BOLD = "\033[1m"
52
+ DIM = "\033[2m"
53
+ RESET = "\033[0m"
54
+
55
+ @staticmethod
56
+ def _c(code: str) -> str:
57
+ return code if is_color_enabled() else ""
58
+
59
+ @classmethod
60
+ def cyan(cls, text: str) -> str:
61
+ """Wraps text with ANSI cyan color if color output is enabled."""
62
+ return f"{cls._c(cls.CYAN)}{text}{cls._c(cls.RESET)}"
63
+
64
+ @classmethod
65
+ def green(cls, text: str) -> str:
66
+ """Wraps text with ANSI green color if color output is enabled."""
67
+ return f"{cls._c(cls.GREEN)}{text}{cls._c(cls.RESET)}"
68
+
69
+ @classmethod
70
+ def yellow(cls, text: str) -> str:
71
+ """Wraps text with ANSI yellow color if color output is enabled."""
72
+ return f"{cls._c(cls.YELLOW)}{text}{cls._c(cls.RESET)}"
73
+
74
+ @classmethod
75
+ def red(cls, text: str) -> str:
76
+ """Wraps text with ANSI red color if color output is enabled."""
77
+ return f"{cls._c(cls.RED)}{text}{cls._c(cls.RESET)}"
78
+
79
+ @classmethod
80
+ def bold(cls, text: str) -> str:
81
+ """Wraps text with ANSI bold weight if color output is enabled."""
82
+ return f"{cls._c(cls.BOLD)}{text}{cls._c(cls.RESET)}"
83
+
84
+ @classmethod
85
+ def dim(cls, text: str) -> str:
86
+ """Wraps text with ANSI dim intensity if color output is enabled."""
87
+ return f"{cls._c(cls.DIM)}{text}{cls._c(cls.RESET)}"
88
+
89
+
90
+ class OutputFormatter:
91
+ """Standardized console & machine-readable output renderer."""
92
+
93
+ def __init__(self, quiet: bool = False, json_mode: bool = False, verbose: bool = False):
94
+ """Initializes the output formatter with verbosity and mode toggles."""
95
+ self.quiet = quiet
96
+ self.json_mode = json_mode
97
+ self.verbose = verbose
98
+
99
+ def debug(self, message: str):
100
+ """Prints a debug message when verbose mode is active."""
101
+ if self.verbose and not self.quiet and not self.json_mode:
102
+ print(f"{Colors.dim('🔍 [DEBUG]')} {message}")
103
+
104
+ def info(self, message: str):
105
+ """Alias for info_msg printing informational text."""
106
+ self.info_msg(message)
107
+
108
+ def warn(self, message: str):
109
+ """Alias for warn_msg printing warning text."""
110
+ self.warn_msg(message)
111
+
112
+ def error(self, message: str):
113
+ """Alias for fail_msg printing failure/error text."""
114
+ self.fail_msg(message)
115
+
116
+ def success(self, message: str):
117
+ """Alias for pass_msg printing passing/success text."""
118
+ self.pass_msg(message)
119
+
120
+ def header(self, title: str):
121
+ """Renders an eye-catching framed header box for CLI stages."""
122
+ if not self.quiet and not self.json_mode:
123
+ border = "=" * 70
124
+ print(f"\n{Colors.cyan(border)}")
125
+ print(f" {Colors.bold(title)}")
126
+ print(f"{Colors.cyan(border)}\n")
127
+
128
+ def step(self, current: int, total: int, title: str):
129
+ """Prints a numbered step indicator for multi-phase operations."""
130
+ if not self.quiet and not self.json_mode:
131
+ print(f"{Colors.bold(f'[{current}/{total}]')} {title}")
132
+
133
+ def pass_msg(self, message: str):
134
+ """Prints a green checkmark pass badge with the given message."""
135
+ if not self.json_mode:
136
+ print(f"{Colors.green('✅ [PASS]')} {message}")
137
+
138
+ def fail_msg(self, message: str):
139
+ """Prints a red cross fail badge with the given message."""
140
+ if not self.json_mode:
141
+ print(f"{Colors.red('❌ [FAIL]')} {message}")
142
+
143
+ def warn_msg(self, message: str):
144
+ """Prints a yellow warning badge with the given message."""
145
+ if not self.quiet and not self.json_mode:
146
+ print(f"{Colors.yellow('âš ī¸ [WARN]')} {message}")
147
+
148
+ def info_msg(self, message: str):
149
+ """Prints a cyan informational badge with the given message."""
150
+ if not self.quiet and not self.json_mode:
151
+ print(f"{Colors.cyan('â„šī¸ [INFO]')} {message}")
152
+
153
+ def print_data(self, data: Any, format_type: str = "text"):
154
+ """Formats and outputs data payload as either indented JSON or raw text."""
155
+ if format_type == "json" or self.json_mode:
156
+ if isinstance(data, (dict, list)):
157
+ print(json.dumps(data, indent=2, ensure_ascii=False))
158
+ else:
159
+ print(str(data))
160
+ else:
161
+ print(str(data))
162
+
163
+
164
+ def get_logger(name: str = "synapse", verbose: bool = False, quiet: bool = False) -> logging.Logger:
165
+ """Creates or returns a standard logging.Logger configured with Synapse formatting."""
166
+ logger = logging.getLogger(name)
167
+ if not logger.handlers:
168
+ handler = logging.StreamHandler(sys.stderr)
169
+ fmt = logging.Formatter("[%(levelname)s] %(message)s")
170
+ handler.setFormatter(fmt)
171
+ logger.addHandler(handler)
172
+ if quiet:
173
+ logger.setLevel(logging.ERROR)
174
+ elif verbose:
175
+ logger.setLevel(logging.DEBUG)
176
+ else:
177
+ logger.setLevel(logging.INFO)
178
+ return logger
179
+
180
+
181
+ # Global default instance
182
+ console = OutputFormatter()