@teevee98/synapse-hub 0.0.0-stage → 3.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (369) hide show
  1. package/.agents/agents/api-engineer.md +67 -0
  2. package/.agents/agents/failure-analyst.md +75 -0
  3. package/.agents/agents/live-explorer.md +70 -0
  4. package/.agents/agents/orchestrator.md +104 -0
  5. package/.agents/agents/perf-engineer.md +74 -0
  6. package/.agents/agents/pom-crafter.md +112 -0
  7. package/.agents/agents/quality-gatekeeper.md +87 -0
  8. package/.agents/agents/test-designer.md +73 -0
  9. package/.agents/agents/test-runner.md +67 -0
  10. package/.agents/rules/author-integrity-guard.md +33 -0
  11. package/.agents/rules/communication-style.md +18 -0
  12. package/.agents/rules/context-engineering.md +37 -0
  13. package/.agents/rules/git-push-protocol.md +33 -0
  14. package/.agents/rules/graphify.md +14 -0
  15. package/.agents/rules/lessons-learned.md +25 -0
  16. package/.agents/rules/mandatory-playwright-live.md +25 -0
  17. package/.agents/rules/mobile_appium_rules.md +43 -0
  18. package/.agents/rules/performance_testing_rules.md +35 -0
  19. package/.agents/rules/skill-precedence.md +29 -0
  20. package/.agents/rules/systematic-debugging.md +36 -0
  21. package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
  22. package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
  23. package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
  24. package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
  25. package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
  26. package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
  27. package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
  28. package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
  29. package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
  30. package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
  31. package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
  32. package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
  33. package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
  34. package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
  35. package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
  36. package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
  37. package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
  38. package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
  39. package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
  40. package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
  41. package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
  42. package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
  43. package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
  44. package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
  45. package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
  46. package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
  47. package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
  48. package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
  49. package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
  50. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
  51. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
  52. package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
  53. package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
  54. package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
  55. package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
  56. package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
  57. package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
  58. package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
  59. package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
  60. package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
  61. package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
  62. package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
  63. package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
  64. package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
  65. package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
  66. package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
  67. package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
  68. package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
  69. package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
  70. package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
  71. package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
  72. package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
  73. package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
  74. package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
  75. package/.agents/skills/github-actions-templates/SKILL.md +77 -0
  76. package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
  77. package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
  78. package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
  79. package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
  80. package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
  81. package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
  82. package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
  83. package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
  84. package/.agents/skills/lam-script-generator/SKILL.md +123 -0
  85. package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
  86. package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
  87. package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
  88. package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
  89. package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
  90. package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
  91. package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
  92. package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
  93. package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
  94. package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
  95. package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
  96. package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
  97. package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
  98. package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
  99. package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
  100. package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
  101. package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
  102. package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
  103. package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
  104. package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
  105. package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
  106. package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
  107. package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
  108. package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
  109. package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
  110. package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
  111. package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
  112. package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
  113. package/.agents/skills/qa-memory-os/SKILL.md +80 -0
  114. package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
  115. package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
  116. package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
  117. package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
  118. package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
  119. package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
  120. package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
  121. package/.agents/skills/review-spec/SKILL.md +60 -0
  122. package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
  123. package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
  124. package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
  125. package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
  126. package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
  127. package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
  128. package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
  129. package/.agents/skills/self-healing-locator/SKILL.md +86 -0
  130. package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
  131. package/.agents/skills/senior-code-review/SKILL.md +108 -0
  132. package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
  133. package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
  134. package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
  135. package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
  136. package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
  137. package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
  138. package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
  139. package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
  140. package/.agents/skills/systematic-debugging/SKILL.md +100 -0
  141. package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
  142. package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
  143. package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
  144. package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
  145. package/.agents/skills/test-driven-development/SKILL.md +114 -0
  146. package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
  147. package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
  148. package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
  149. package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
  150. package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
  151. package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
  152. package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
  153. package/.agents/skills/verification-before-completion/SKILL.md +100 -0
  154. package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
  155. package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
  156. package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
  157. package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
  158. package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
  159. package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
  160. package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
  161. package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
  162. package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
  163. package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
  164. package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
  165. package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
  166. package/.agents/templates/completion_report.md +57 -0
  167. package/.agents/workflows/analyze_requirement_document.md +18 -0
  168. package/.agents/workflows/export_testcases_excel.md +32 -0
  169. package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
  170. package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
  171. package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
  172. package/.agents/workflows/generate_requirements_from_website.md +25 -0
  173. package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
  174. package/.agents/workflows/graphify.md +10 -0
  175. package/.agents/workflows/test-impact.md +15 -0
  176. package/.agents/workflows/verify.md +34 -0
  177. package/.cursor/rules/agents.mdc +16 -0
  178. package/.cursor/rules/language.mdc +7 -0
  179. package/.cursor/rules/synapse-qa.mdc +24 -0
  180. package/.cursorrules +27 -0
  181. package/.dockerignore +53 -0
  182. package/.pre-commit-hooks.yaml +14 -0
  183. package/.windsurfrules +26 -0
  184. package/AGENTS.md +86 -0
  185. package/CLAUDE.md +54 -0
  186. package/Dockerfile +81 -0
  187. package/LICENSE +52 -0
  188. package/NOTICE +264 -0
  189. package/README.en.md +171 -0
  190. package/README.md +170 -2
  191. package/action.yml +51 -0
  192. package/agentskills.json +16 -0
  193. package/bin/agent-qa.js +138 -0
  194. package/docker-compose.yml +74 -0
  195. package/docs/ARCHITECTURE.en.md +198 -0
  196. package/docs/ARCHITECTURE.md +199 -0
  197. package/docs/CI_CD_INTEGRATION.en.md +170 -0
  198. package/docs/CI_CD_INTEGRATION.md +170 -0
  199. package/docs/CLI_REFERENCE.en.md +174 -0
  200. package/docs/CLI_REFERENCE.md +176 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +118 -0
  206. package/docs/QUALITY_GATES.md +118 -0
  207. package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
  208. package/docs/TOOL_CATALOG.md +129 -0
  209. package/docs/adopted-ecosystem-tools.md +96 -0
  210. package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
  211. package/docs/research/agent_skill_training_analysis.md +1358 -0
  212. package/docs/schemas/synapse.config.schema.json +86 -0
  213. package/package.json +94 -4
  214. package/plugin.json +31 -0
  215. package/scripts/generate_skill_examples.py +244 -0
  216. package/scripts/install.ps1 +112 -0
  217. package/scripts/install_global_plugin.ps1 +94 -0
  218. package/scripts/install_global_plugin.sh +49 -0
  219. package/scripts/lint_skills.ps1 +57 -0
  220. package/scripts/package_dist.py +337 -0
  221. package/scripts/setup.sh +59 -0
  222. package/scripts/update_hub.ps1 +19 -0
  223. package/scripts/update_hub.sh +15 -0
  224. package/skills_manifest.json +854 -0
  225. package/synapse.config.json +31 -0
  226. package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
  227. package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
  228. package/templates/ai_bridges/CLAUDE.md +54 -0
  229. package/templates/ai_bridges/copilot-instructions.md +20 -0
  230. package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
  231. package/templates/ai_bridges/windsurfrules +26 -0
  232. package/templates/ci/github-actions-synapse.yml +95 -0
  233. package/templates/ci/gitlab-ci-synapse.yml +16 -0
  234. package/templates/ui/index.html +1069 -0
  235. package/templates/welcome.html.tmpl +2074 -0
  236. package/tools/.infer_baseline.json +30 -0
  237. package/tools/TOOLS_RUNBOOK.md +1553 -0
  238. package/tools/TOOL_CATALOG.json +1769 -0
  239. package/tools/__init__.py +43 -0
  240. package/tools/_openapi_parser.py +158 -0
  241. package/tools/agent_canary.py +525 -0
  242. package/tools/agentless_patcher.py +417 -0
  243. package/tools/analyze_project.py +262 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +190 -0
  247. package/tools/auto_heal.py +271 -0
  248. package/tools/auto_heal_reflexion.py +532 -0
  249. package/tools/autogen_qa_broker.py +844 -0
  250. package/tools/benchmark_swarm_context.py +394 -0
  251. package/tools/browser_helpers.js +746 -0
  252. package/tools/browsergym_eval.py +236 -0
  253. package/tools/bug_reporter.py +252 -0
  254. package/tools/bump_version.py +423 -0
  255. package/tools/cache_resolver.py +1214 -0
  256. package/tools/check_env.py +426 -0
  257. package/tools/check_version_sync.py +256 -0
  258. package/tools/ci_healing_hook.py +126 -0
  259. package/tools/cli.py +1598 -0
  260. package/tools/config_decoupler.py +253 -0
  261. package/tools/contract_validator.py +141 -0
  262. package/tools/core/__init__.py +70 -0
  263. package/tools/core/adapters.py +431 -0
  264. package/tools/core/circuit_breaker.py +263 -0
  265. package/tools/core/cli_runtime.py +66 -0
  266. package/tools/core/file_lock.py +159 -0
  267. package/tools/core/i18n.py +394 -0
  268. package/tools/core/memory_bus.py +905 -0
  269. package/tools/core/process_supervisor.py +332 -0
  270. package/tools/core/telemetry.py +329 -0
  271. package/tools/count_tokens.py +1267 -0
  272. package/tools/create_mock_docx.py +104 -0
  273. package/tools/dashboard_generator.py +2403 -0
  274. package/tools/db_sandbox.py +675 -0
  275. package/tools/debt_harvester.py +237 -0
  276. package/tools/distill_log.py +161 -0
  277. package/tools/dspy_qa_signatures.py +356 -0
  278. package/tools/e2e_flow_prober.py +132 -0
  279. package/tools/export_postman_collection.py +945 -0
  280. package/tools/flaky_detector.py +389 -0
  281. package/tools/fsm_enforcer.py +450 -0
  282. package/tools/fsm_middleware.py +401 -0
  283. package/tools/fuzz_payloads.py +197 -0
  284. package/tools/generate_allure_report.py +88 -0
  285. package/tools/generate_api_matrix.py +193 -0
  286. package/tools/generate_jmx_plan.py +1322 -0
  287. package/tools/generate_sbom.py +252 -0
  288. package/tools/generate_tc_from_story.py +203 -0
  289. package/tools/generate_test_reports.py +133 -0
  290. package/tools/generate_tool_catalog.py +482 -0
  291. package/tools/gherkin_suite.py +758 -0
  292. package/tools/git_pre_commit_guard.py +298 -0
  293. package/tools/goldfish_review.py +366 -0
  294. package/tools/heal/__init__.py +28 -0
  295. package/tools/heal_pr_automator.py +220 -0
  296. package/tools/heuristic_locator_matcher.py +351 -0
  297. package/tools/hub_publisher.py +623 -0
  298. package/tools/humanize_linter.py +438 -0
  299. package/tools/infer_linter.py +977 -0
  300. package/tools/init_config.py +306 -0
  301. package/tools/interview_story.py +116 -0
  302. package/tools/jira_sync.py +566 -0
  303. package/tools/jtl_analyzer.py +474 -0
  304. package/tools/lint/__init__.py +30 -0
  305. package/tools/lint_ai_docs.py +374 -0
  306. package/tools/lookup_tc.py +165 -0
  307. package/tools/lookup_xpath.py +167 -0
  308. package/tools/matrix_sharder.py +148 -0
  309. package/tools/mcp/__init__.py +18 -0
  310. package/tools/mcp_docx_server.ps1 +13 -0
  311. package/tools/mcp_docx_server.py +851 -0
  312. package/tools/mcp_excel_server.ps1 +13 -0
  313. package/tools/mcp_excel_server.py +441 -0
  314. package/tools/mcp_server.py +725 -0
  315. package/tools/md_to_xlsx.py +327 -0
  316. package/tools/micro_mutator.py +887 -0
  317. package/tools/mipro_assertion_tuner.py +210 -0
  318. package/tools/network_mock_shield.py +311 -0
  319. package/tools/newman_analyzer.py +384 -0
  320. package/tools/omni_emitter.py +579 -0
  321. package/tools/omni_parser.py +450 -0
  322. package/tools/omni_transpiler.py +168 -0
  323. package/tools/openxml_guard.py +438 -0
  324. package/tools/output_formatter.py +182 -0
  325. package/tools/package_release.py +325 -0
  326. package/tools/perf/__init__.py +24 -0
  327. package/tools/pinpoint_failure.py +190 -0
  328. package/tools/project_state.py +171 -0
  329. package/tools/qa_event_stream.py +358 -0
  330. package/tools/repo_map.py +346 -0
  331. package/tools/report/__init__.py +32 -0
  332. package/tools/reversible_sandbox.py +344 -0
  333. package/tools/safety_firewall.py +437 -0
  334. package/tools/security_coverage_ledger.py +538 -0
  335. package/tools/security_scanner.py +229 -0
  336. package/tools/senior_code_review.py +393 -0
  337. package/tools/setup_project.py +770 -0
  338. package/tools/skill_collision_guard.py +304 -0
  339. package/tools/skill_profiles.py +217 -0
  340. package/tools/skill_vault.py +481 -0
  341. package/tools/skillspector.py +1278 -0
  342. package/tools/smart_visual_masker.py +132 -0
  343. package/tools/spec_drift_sentinel.py +438 -0
  344. package/tools/swe_qa_aci.py +369 -0
  345. package/tools/synapse_observer.py +485 -0
  346. package/tools/synapse_qa_bench.py +190 -0
  347. package/tools/sync_agent_rules.py +274 -0
  348. package/tools/telemetry_correlator.py +397 -0
  349. package/tools/template_excel_exporter.py +514 -0
  350. package/tools/templates/jmeter-distributed/README.md +54 -0
  351. package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
  352. package/tools/test_impact.py +419 -0
  353. package/tools/test_memory_os.py +462 -0
  354. package/tools/textgrad_mutation_optimizer.py +237 -0
  355. package/tools/tms_sync_bridge.py +834 -0
  356. package/tools/tot_exploratory_tester.py +239 -0
  357. package/tools/trace_data_flow.py +240 -0
  358. package/tools/traffic_session_converter.py +256 -0
  359. package/tools/trend_analytics.py +314 -0
  360. package/tools/ui_server.py +401 -0
  361. package/tools/universal_ir.py +488 -0
  362. package/tools/update_sentinel.py +383 -0
  363. package/tools/validate_groovy_scripts.py +173 -0
  364. package/tools/verify_all.py +1271 -0
  365. package/tools/visual_diff_canvas.py +143 -0
  366. package/tools/visual_som_helper.py +550 -0
  367. package/tools/watch_mode.py +308 -0
  368. package/tools/wcag_audit.py +239 -0
  369. package/tools/welcome_page.py +290 -0
@@ -0,0 +1,675 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ Enterprise Zero-Pollution Database Sandbox & Ephemeral Teardown Engine
4
+ ---------------------------------------------------------------------
5
+ Eliminates database test pollution and cascading flaky failures during parallel E2E runs.
6
+
7
+ Features:
8
+ 1. Transaction Savepoint Rollback Context:
9
+ - Runs tests inside isolated transactional savepoints (ROLLBACK TO SAVEPOINT),
10
+ guaranteeing zero leftover records regardless of test pass or fail.
11
+ 2. Ephemeral Snapshot & Rapid Restore (< 0.5s):
12
+ - Takes snapshot of database state before test suite execution.
13
+ - Restores pristine clean state immediately after test completion.
14
+ - SQLite implemented natively; other engines via file-copy hooks. Boot
15
+ containers with external `docker`/Testcontainers, then gate readiness
16
+ with the `wait-ready` command (see Wait Strategies below).
17
+ 3. Taint Pollution Auditor:
18
+ - Automatically detects orphan rows created during test sessions and performs
19
+ dependency-aware cascading cleanup.
20
+ 4. Container Readiness Wait Strategies (`wait-ready`):
21
+ - port / http / sqlite probes with deadline + backoff, so CI never races
22
+ a not-yet-ready database (concept borrowed from the Testcontainers
23
+ WaitStrategy taxonomy, Apache-2.0, re-implemented stdlib-only).
24
+ """
25
+
26
+ import os
27
+ import re
28
+ import sys
29
+ import time
30
+ import json
31
+ import shutil
32
+ import socket
33
+ import sqlite3
34
+ import argparse
35
+ import subprocess
36
+ import urllib.request
37
+ import urllib.error
38
+ from typing import Dict, Any, List, Tuple, Optional
39
+
40
+ # Enforce UTF-8 stdout encoding for Windows console compatibility
41
+ if hasattr(sys.stdout, 'reconfigure'):
42
+ try:
43
+ sys.stdout.reconfigure(encoding='utf-8')
44
+ sys.stderr.reconfigure(encoding='utf-8')
45
+ except Exception:
46
+ pass
47
+
48
+ SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
49
+ QA_HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
50
+
51
+
52
+ def _resolve_snapshot_dir():
53
+ cwd = os.path.abspath(os.getcwd())
54
+ try:
55
+ is_hub = os.path.samefile(cwd, QA_HUB_ROOT)
56
+ except (FileNotFoundError, OSError, ValueError):
57
+ is_hub = os.path.realpath(cwd).lower() == os.path.realpath(QA_HUB_ROOT).lower()
58
+ if not is_hub:
59
+ target = os.path.join(cwd, ".synapse", "snapshots")
60
+ else:
61
+ target = os.path.join(QA_HUB_ROOT, ".sandbox_snapshots")
62
+ return target
63
+
64
+
65
+ SNAPSHOT_DIR = _resolve_snapshot_dir()
66
+
67
+
68
+ class DBSandbox:
69
+ """Zero-pollution ephemeral database management."""
70
+
71
+ def __init__(self, db_type: str = "sqlite", db_path: str = "", snapshot_dir: Optional[str] = None):
72
+ clean_path = (db_path or "").strip()
73
+ lowered_path = clean_path.lower()
74
+ if lowered_path.startswith(("postgresql://", "postgres://")):
75
+ self.db_type = "postgres"
76
+ elif lowered_path.startswith(("mysql://", "mariadb://")):
77
+ self.db_type = "mysql"
78
+ elif lowered_path.startswith("oracle://"):
79
+ self.db_type = "oracle"
80
+ else:
81
+ self.db_type = db_type.lower().strip() or "sqlite"
82
+ self.db_path = clean_path
83
+ self.snapshot_dir = snapshot_dir if snapshot_dir is not None else _resolve_snapshot_dir()
84
+ try:
85
+ os.makedirs(self.snapshot_dir, exist_ok=True)
86
+ except OSError as err:
87
+ import tempfile
88
+ sys.stderr.write(f"Notice: Snapshot dir creation fallback: {err}\n")
89
+ self.snapshot_dir = os.path.join(tempfile.gettempdir(), ".synapse", "snapshots")
90
+ try:
91
+ os.makedirs(self.snapshot_dir, exist_ok=True)
92
+ except OSError as ferr:
93
+ sys.stderr.write(f"Notice: Snapshot dir fallback failed: {ferr}\n")
94
+
95
+ # -------------------------------------------------------------------------
96
+ # 1. SNAPSHOT & RAPID RESTORE
97
+ # -------------------------------------------------------------------------
98
+ def _resolve_safe_snapshot_paths(self, snapshot_id: str) -> Tuple[str, str, str]:
99
+ """Sanitizes snapshot_id and ensures target paths remain inside self.snapshot_dir."""
100
+ clean_id = re.sub(r'[^a-zA-Z0-9_\-]', '', snapshot_id.strip())
101
+ if not clean_id:
102
+ clean_id = "pristine_baseline"
103
+ base_dir = os.path.abspath(self.snapshot_dir)
104
+ snap_path = os.path.abspath(os.path.join(base_dir, f"{clean_id}.db"))
105
+ meta_path = os.path.abspath(os.path.join(base_dir, f"{clean_id}_meta.json"))
106
+ if not snap_path.startswith(base_dir + os.sep) or not meta_path.startswith(base_dir + os.sep):
107
+ raise ValueError(f"Path traversal detected in snapshot_id: '{snapshot_id}'")
108
+ return clean_id, snap_path, meta_path
109
+
110
+ def create_snapshot(self, snapshot_id: str = "pristine_baseline") -> Dict[str, Any]:
111
+ """
112
+ Creates an instantaneous pristine snapshot of the database state.
113
+ """
114
+ start_time = time.perf_counter()
115
+ clean_id, snapshot_file, meta_file = self._resolve_safe_snapshot_paths(snapshot_id)
116
+
117
+ is_net = any(
118
+ (self.db_path or "").lower().startswith(p)
119
+ for p in ("postgresql://", "postgres://", "mysql://", "mariadb://", "oracle://")
120
+ ) or self.db_type in ("postgres", "postgresql", "mysql", "mariadb", "oracle")
121
+
122
+ error_msg = None
123
+ if is_net:
124
+ # Networked RDBMS snapshot execution hook (pg_dump / mysqldump)
125
+ is_pg = "postgres" in self.db_type or "postgresql" in (self.db_path or "").lower() or "postgres" in (self.db_path or "").lower()
126
+ is_my = "mysql" in self.db_type or "mariadb" in self.db_type or "mysql://" in (self.db_path or "").lower()
127
+ dump_tool = "pg_dump" if is_pg else ("mysqldump" if is_my else None)
128
+
129
+ if not dump_tool or not shutil.which(dump_tool):
130
+ error_msg = (
131
+ f"Network database snapshot requires '{dump_tool or 'CLI dump'}' in PATH "
132
+ f"for connection '{self.db_path}'. Fake snapshot approval blocked."
133
+ )
134
+ else:
135
+ try:
136
+ if is_pg:
137
+ cmd = [dump_tool, "--dbname", self.db_path, "-F", "c", "-f", snapshot_file]
138
+ else:
139
+ cmd = [dump_tool, self.db_path, f"--result-file={snapshot_file}"]
140
+ proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60.0)
141
+ if proc.returncode != 0:
142
+ error_msg = f"{dump_tool} failed with exit code {proc.returncode}: {proc.stderr.strip()}"
143
+ except Exception as e:
144
+ error_msg = f"{dump_tool} execution error: {str(e)}"
145
+ elif self.db_type == "sqlite":
146
+ if not self.db_path:
147
+ self.db_path = os.path.join(self.snapshot_dir, "active_test.db")
148
+
149
+ if not os.path.exists(self.db_path):
150
+ conn = sqlite3.connect(self.db_path)
151
+ try:
152
+ cursor = conn.cursor()
153
+ cursor.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, code TEXT, status TEXT)")
154
+ cursor.execute("CREATE TABLE IF NOT EXISTS orders (id INTEGER PRIMARY KEY, user_id INTEGER, amount REAL)")
155
+ conn.commit()
156
+ finally:
157
+ conn.close()
158
+
159
+ # Perform atomic SQLite backup
160
+ src_conn = sqlite3.connect(self.db_path)
161
+ try:
162
+ dst_conn = sqlite3.connect(snapshot_file)
163
+ try:
164
+ src_conn.backup(dst_conn)
165
+ finally:
166
+ dst_conn.close()
167
+ finally:
168
+ src_conn.close()
169
+ else:
170
+ # Local file-based non-sqlite database (e.g. DuckDB file)
171
+ if os.path.isfile(self.db_path):
172
+ shutil.copy2(self.db_path, snapshot_file)
173
+ else:
174
+ error_msg = f"Database file '{self.db_path}' not found."
175
+
176
+ elapsed = round(time.perf_counter() - start_time, 4)
177
+
178
+ metadata = {
179
+ "snapshot_id": clean_id,
180
+ "db_type": self.db_type,
181
+ "source_db": self.db_path,
182
+ "snapshot_path": snapshot_file,
183
+ "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
184
+ "snapshot_duration_sec": elapsed,
185
+ "status": "ERROR" if error_msg else "READY"
186
+ }
187
+ if error_msg:
188
+ metadata["error"] = error_msg
189
+ with open(meta_file, "w", encoding="utf-8") as f:
190
+ json.dump(metadata, f, indent=2)
191
+
192
+ return metadata
193
+
194
+ def restore_snapshot(self, snapshot_id: str = "pristine_baseline") -> Dict[str, Any]:
195
+ """
196
+ Restores database to pristine baseline, wiping 100% of test data junk.
197
+ """
198
+ start_time = time.perf_counter()
199
+ try:
200
+ clean_id, snapshot_file, meta_file = self._resolve_safe_snapshot_paths(snapshot_id)
201
+ except ValueError as e:
202
+ return {"status": "ERROR", "message": str(e)}
203
+
204
+ if os.path.exists(meta_file):
205
+ try:
206
+ with open(meta_file, "r", encoding="utf-8") as f:
207
+ meta = json.load(f)
208
+ if meta.get("status") == "ERROR":
209
+ return {
210
+ "status": "ERROR",
211
+ "message": f"Cannot restore corrupted/failed snapshot '{clean_id}': {meta.get('error', 'snapshot creation error')}",
212
+ "snapshot_id": clean_id,
213
+ "target_db": self.db_path,
214
+ "zero_pollution_guaranteed": False
215
+ }
216
+ if not self.db_path:
217
+ self.db_path = meta.get("source_db", "")
218
+ except (OSError, json.JSONDecodeError) as read_meta_err:
219
+ sys.stderr.write(f"Notice: Failed to read meta file {meta_file}: {read_meta_err}\n")
220
+
221
+ if not os.path.exists(snapshot_file):
222
+ return {
223
+ "status": "ERROR",
224
+ "message": f"Snapshot '{clean_id}' does not exist at {snapshot_file}",
225
+ "snapshot_id": clean_id,
226
+ "target_db": self.db_path,
227
+ "zero_pollution_guaranteed": False
228
+ }
229
+
230
+ if not self.db_path:
231
+ self.db_path = os.path.join(self.snapshot_dir, "active_test.db")
232
+
233
+ is_net = any(
234
+ (self.db_path or "").lower().startswith(p)
235
+ for p in ("postgresql://", "postgres://", "mysql://", "mariadb://", "oracle://")
236
+ ) or self.db_type in ("postgres", "postgresql", "mysql", "mariadb", "oracle")
237
+
238
+ restore_err = None
239
+ if is_net:
240
+ is_pg = "postgres" in self.db_type or "postgresql" in (self.db_path or "").lower() or "postgres" in (self.db_path or "").lower()
241
+ is_my = "mysql" in self.db_type or "mariadb" in self.db_type or "mysql://" in (self.db_path or "").lower()
242
+ restore_tool = "pg_restore" if is_pg else ("mysql" if is_my else None)
243
+
244
+ if not restore_tool or not shutil.which(restore_tool):
245
+ restore_err = (
246
+ f"Network database restore requires '{restore_tool or 'CLI restore'}' in PATH "
247
+ f"for connection '{self.db_path}'. Cannot restore state."
248
+ )
249
+ else:
250
+ try:
251
+ if is_pg:
252
+ cmd = [restore_tool, "--clean", "--if-exists", "--dbname", self.db_path, snapshot_file]
253
+ else:
254
+ cmd = [restore_tool, self.db_path, "-e", f"source {snapshot_file}"]
255
+ proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60.0)
256
+ if proc.returncode != 0:
257
+ restore_err = f"{restore_tool} failed with exit code {proc.returncode}: {proc.stderr.strip()}"
258
+ except Exception as e:
259
+ restore_err = f"{restore_tool} execution error: {str(e)}"
260
+ elif self.db_type == "sqlite":
261
+ src_conn = sqlite3.connect(snapshot_file)
262
+ try:
263
+ dst_conn = sqlite3.connect(self.db_path)
264
+ try:
265
+ src_conn.backup(dst_conn)
266
+ finally:
267
+ dst_conn.close()
268
+ finally:
269
+ src_conn.close()
270
+ else:
271
+ if os.path.isfile(snapshot_file):
272
+ shutil.copy2(snapshot_file, self.db_path)
273
+ else:
274
+ restore_err = f"Snapshot file '{snapshot_file}' not found."
275
+
276
+ elapsed = round(time.perf_counter() - start_time, 4)
277
+ if restore_err:
278
+ return {
279
+ "status": "ERROR",
280
+ "message": restore_err,
281
+ "snapshot_id": clean_id,
282
+ "target_db": self.db_path,
283
+ "zero_pollution_guaranteed": False
284
+ }
285
+ return {
286
+ "status": "RESTORED",
287
+ "snapshot_id": clean_id,
288
+ "target_db": self.db_path,
289
+ "restore_duration_sec": elapsed,
290
+ "zero_pollution_guaranteed": True
291
+ }
292
+
293
+ # -------------------------------------------------------------------------
294
+ # 2. TRANSACTION SAVEPOINT ROLLBACK WRAPPER
295
+ # -------------------------------------------------------------------------
296
+ def execute_with_savepoint(self, sql_commands: List[str], savepoint_name: str = "sp_test_run") -> Dict[str, Any]:
297
+ """
298
+ Executes SQL statements inside an isolated transaction savepoint,
299
+ then automatically rolls back to verify zero database side-effects.
300
+ """
301
+ if not self.db_path or not os.path.exists(self.db_path):
302
+ self.create_snapshot()
303
+
304
+ conn = sqlite3.connect(self.db_path)
305
+ cursor = conn.cursor()
306
+ executed_count = 0
307
+
308
+ safe_sp = re.sub(r'[^a-zA-Z0-9_]', '', savepoint_name) or "sp_test_run"
309
+ try:
310
+ cursor.execute(f"SAVEPOINT {safe_sp};")
311
+ for sql in sql_commands:
312
+ cursor.execute(sql)
313
+ executed_count += 1
314
+
315
+ # Determine sample table for verification read (prefer 'users', fallback to first user table)
316
+ cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%';")
317
+ tables = [row[0] for row in cursor.fetchall()]
318
+ target_table = "users" if "users" in tables else (tables[0] if tables else None)
319
+
320
+ count_inside_tx = 0
321
+ if target_table:
322
+ safe_tbl = target_table.replace('"', '""')
323
+ cursor.execute(f'SELECT COUNT(*) FROM "{safe_tbl}"')
324
+ count_inside_tx = cursor.fetchone()[0]
325
+ else:
326
+ count_inside_tx = executed_count
327
+
328
+ # Enforce automatic zero-pollution rollback
329
+ cursor.execute(f"ROLLBACK TO SAVEPOINT {safe_sp};")
330
+ cursor.execute(f"RELEASE SAVEPOINT {safe_sp};")
331
+
332
+ # Verify that outside the savepoint, table is pristine
333
+ count_after_rollback = 0
334
+ if target_table:
335
+ safe_tbl = target_table.replace('"', '""')
336
+ cursor.execute(f'SELECT COUNT(*) FROM "{safe_tbl}"')
337
+ count_after_rollback = cursor.fetchone()[0]
338
+
339
+ return {
340
+ "status": "SUCCESS",
341
+ "statements_executed": executed_count,
342
+ "count_inside_transaction": count_inside_tx,
343
+ "count_after_rollback": count_after_rollback,
344
+ "side_effect_count": count_after_rollback,
345
+ "zero_pollution_verified": count_after_rollback == 0
346
+ }
347
+ except Exception as e:
348
+ try:
349
+ cursor.execute(f"ROLLBACK TO SAVEPOINT {safe_sp};")
350
+ except sqlite3.Error as rollback_err:
351
+ sys.stderr.write(f"Notice: Savepoint rollback notice: {rollback_err}\n")
352
+ return {
353
+ "status": "ERROR",
354
+ "error": str(e),
355
+ "zero_pollution_verified": True
356
+ }
357
+ finally:
358
+ conn.close()
359
+
360
+ # -------------------------------------------------------------------------
361
+ # 3. TAINT POLLUTION AUDIT & PURGE
362
+ # -------------------------------------------------------------------------
363
+ @staticmethod
364
+ def _escape_sql_like(prefix: str) -> str:
365
+ """Escapes SQL LIKE wildcard characters (_, %) so prefix is matched literally."""
366
+ return prefix.replace('\\', '\\\\').replace('%', '\\%').replace('_', '\\_')
367
+
368
+ def audit_and_purge_pollution(
369
+ self,
370
+ known_test_prefixes: Tuple[str, ...] = ("AUTO_", "TEST_", "TEMP_"),
371
+ dry_run: bool = False
372
+ ) -> Dict[str, Any]:
373
+ """
374
+ Scans all tables for orphan records carrying test prefixes and purges them.
375
+ Properly escapes SQL LIKE wildcards ('_' and '%') with an explicit ESCAPE clause
376
+ to avoid deleting real business data (e.g. 'Automotive', 'Tester', 'Tempest').
377
+ """
378
+ if not self.db_path:
379
+ candidate = os.path.join(self.snapshot_dir, "active_test.db")
380
+ if os.path.exists(candidate):
381
+ self.db_path = candidate
382
+
383
+ if not self.db_path or not os.path.exists(self.db_path):
384
+ return {
385
+ "status": "SKIPPED",
386
+ "tables_audited": 0,
387
+ "total_purged_rows": 0,
388
+ "purge_details": [],
389
+ "zero_pollution_achieved": True,
390
+ "message": "No database found"
391
+ }
392
+
393
+ conn = sqlite3.connect(self.db_path)
394
+ try:
395
+ cursor = conn.cursor()
396
+ cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%';")
397
+ tables = [r[0] for r in cursor.fetchall()]
398
+
399
+ total_purged = 0
400
+ purge_log = []
401
+
402
+ for table in tables:
403
+ # Validate table identifier to protect against injection
404
+ if not re.match(r'^[a-zA-Z0-9_]+$', table):
405
+ continue
406
+ cursor.execute(f"PRAGMA table_info([{table}]);")
407
+ columns = [c[1] for c in cursor.fetchall()]
408
+
409
+ # Look for code or name columns
410
+ target_cols = [c for c in columns if c.lower() in ("code", "username", "name", "email", "status") and re.match(r'^[a-zA-Z0-9_]+$', c)]
411
+ for col in target_cols:
412
+ for prefix in known_test_prefixes:
413
+ escaped_pattern = self._escape_sql_like(prefix) + "%"
414
+ cursor.execute(
415
+ f"SELECT COUNT(*) FROM [{table}] WHERE [{col}] LIKE ? ESCAPE '\\'",
416
+ (escaped_pattern,)
417
+ )
418
+ c_count = cursor.fetchone()[0]
419
+ if c_count > 0:
420
+ if not dry_run:
421
+ cursor.execute(
422
+ f"DELETE FROM [{table}] WHERE [{col}] LIKE ? ESCAPE '\\'",
423
+ (escaped_pattern,)
424
+ )
425
+ total_purged += c_count
426
+ action_str = "previewed" if dry_run else "deleted"
427
+ purge_log.append(f"Table '{table}' ({col}): {action_str} {c_count} rows matching literal prefix '{prefix}'")
428
+
429
+ if not dry_run:
430
+ conn.commit()
431
+ finally:
432
+ conn.close()
433
+
434
+ return {
435
+ "status": "CLEAN" if not dry_run else "DRY_RUN",
436
+ "tables_audited": len(tables),
437
+ "total_purged_rows": total_purged,
438
+ "purge_details": purge_log,
439
+ "zero_pollution_achieved": True,
440
+ "dry_run": dry_run
441
+ }
442
+
443
+
444
+ # -------------------------------------------------------------------------
445
+ # 4. CONTAINER READINESS WAIT STRATEGIES
446
+ # (Concept borrowed from the Testcontainers WaitStrategy taxonomy,
447
+ # Apache-2.0 - re-implemented stdlib-only. Boot the container with
448
+ # external `docker`/Testcontainers, then gate on readiness here.)
449
+ # -------------------------------------------------------------------------
450
+
451
+ def _probe_sqlite(target: str) -> Tuple[bool, str]:
452
+ """Ready when the SQLite file opens read-only and answers a pragma."""
453
+ try:
454
+ conn = sqlite3.connect(f"file:{target}?mode=ro", uri=True, timeout=2.0)
455
+ try:
456
+ conn.execute("PRAGMA schema_version").fetchone()
457
+ finally:
458
+ conn.close()
459
+ return True, "sqlite pragma answered"
460
+ except sqlite3.Error as exc:
461
+ return False, f"sqlite probe failed: {exc}"
462
+
463
+
464
+ def _probe_port(target: str) -> Tuple[bool, str]:
465
+ """Ready when a TCP connection to host:port succeeds."""
466
+ m = re.match(r"^(?:[\w.\-]+://)?([\w.\-]+):(\d+)$", target)
467
+ if not m:
468
+ return False, f"invalid host:port target '{target}'"
469
+ host, port = m.group(1), int(m.group(2))
470
+ try:
471
+ with socket.create_connection((host, port), timeout=2.0):
472
+ return True, f"tcp {host}:{port} accepted"
473
+ except OSError as exc:
474
+ return False, f"tcp {host}:{port} refused: {exc}"
475
+
476
+
477
+ def _probe_http(target: str) -> Tuple[bool, str]:
478
+ """Ready when the endpoint answers with any non-5xx status (an auth wall
479
+ such as 401/403 still proves the service is up)."""
480
+ try:
481
+ req = urllib.request.Request(target, method="GET")
482
+ with urllib.request.urlopen(req, timeout=2.0) as resp: # nosec B310
483
+ return True, f"http {resp.getcode()}"
484
+ except urllib.error.HTTPError as exc:
485
+ if exc.code < 500:
486
+ return True, f"http {exc.code} (service reachable)"
487
+ return False, f"http {exc.code} server error"
488
+ except (urllib.error.URLError, OSError) as exc:
489
+ return False, f"http probe failed: {exc}"
490
+
491
+
492
+ def infer_wait_strategy(target: str) -> str:
493
+ """Auto-detects the wait strategy from the target shape."""
494
+ lowered = target.lower()
495
+ if lowered.startswith("http://") or lowered.startswith("https://"):
496
+ return "http"
497
+ if lowered.endswith((".db", ".sqlite", ".sqlite3")) or os.path.exists(target):
498
+ return "sqlite"
499
+ if re.match(r"^[\w.\-]+:\d+$", target):
500
+ return "port"
501
+ return "port"
502
+
503
+
504
+ def wait_for_ready(target: str, strategy: str = "auto", timeout_sec: float = 30.0) -> Dict[str, Any]:
505
+ """Polls a readiness probe until it succeeds or the deadline expires.
506
+
507
+ Returns a structured result; exit codes are enforced by the CLI
508
+ (0 = ready, 1 = timeout) so CI pipelines can gate on database health
509
+ before dispatching suites.
510
+ """
511
+ if strategy == "auto":
512
+ strategy = infer_wait_strategy(target)
513
+ probes = {"sqlite": _probe_sqlite, "port": _probe_port, "http": _probe_http}
514
+ probe = probes.get(strategy)
515
+ if probe is None:
516
+ return {"target": target, "strategy": strategy, "ready": False,
517
+ "elapsed_ms": 0, "attempts": 0, "error": f"unknown strategy '{strategy}'"}
518
+
519
+ start = time.perf_counter()
520
+ attempts = 0
521
+ backoff = 0.25
522
+ last_error = ""
523
+ while time.perf_counter() - start < timeout_sec:
524
+ attempts += 1
525
+ ok, detail = probe(target)
526
+ if ok:
527
+ return {
528
+ "target": target,
529
+ "strategy": strategy,
530
+ "ready": True,
531
+ "elapsed_ms": round((time.perf_counter() - start) * 1000, 1),
532
+ "attempts": attempts,
533
+ "error": None,
534
+ }
535
+ last_error = detail
536
+ time.sleep(backoff)
537
+ backoff = min(backoff * 2, 2.0)
538
+
539
+ return {
540
+ "target": target,
541
+ "strategy": strategy,
542
+ "ready": False,
543
+ "elapsed_ms": round((time.perf_counter() - start) * 1000, 1),
544
+ "attempts": attempts,
545
+ "error": last_error or "timeout expired before readiness",
546
+ }
547
+
548
+
549
+ def main():
550
+ parser = argparse.ArgumentParser(description="Zero-Pollution Database Sandbox & Ephemeral Teardown")
551
+ subparsers = parser.add_subparsers(dest="command", help="Sandbox command")
552
+
553
+ # Command: snapshot
554
+ snap_p = subparsers.add_parser("snapshot", help="Create pristine database snapshot")
555
+ snap_p.add_argument("--db-path", default="", help="Path to database file or network URI")
556
+ snap_p.add_argument("--db-type", default="", help="Database engine type (sqlite, postgres, mysql, oracle)")
557
+ snap_p.add_argument("--id", default="pristine_baseline", help="Snapshot identifier")
558
+ snap_p.add_argument("--json", action="store_true", help="Output JSON format")
559
+
560
+ # Command: restore
561
+ rest_p = subparsers.add_parser("restore", help="Restore pristine snapshot")
562
+ rest_p.add_argument("--db-path", default="", help="Path to database file or network URI")
563
+ rest_p.add_argument("--db-type", default="", help="Database engine type (sqlite, postgres, mysql, oracle)")
564
+ rest_p.add_argument("--id", default="pristine_baseline", help="Snapshot identifier")
565
+ rest_p.add_argument("--json", action="store_true", help="Output JSON format")
566
+
567
+ # Command: rollback-test
568
+ roll_p = subparsers.add_parser("rollback-test", help="Execute SQL in savepoint and rollback")
569
+ roll_p.add_argument("--db-path", default="", help="Path to database file")
570
+ roll_p.add_argument("--db-type", default="", help="Database engine type (sqlite, postgres, mysql)")
571
+ roll_p.add_argument("--sql", action="append", default=[], help="SQL statements to run")
572
+ roll_p.add_argument("--json", action="store_true", help="Output JSON format")
573
+
574
+ # Command: audit
575
+ aud_p = subparsers.add_parser("audit", help="Audit orphan test junk and purge")
576
+ aud_p.add_argument("--db-path", default="", help="Path to database file")
577
+ aud_p.add_argument("--db-type", default="", help="Database engine type (sqlite, postgres, mysql)")
578
+ aud_p.add_argument("--dry-run", action="store_true", help="Preview test records to purge without deleting")
579
+ aud_p.add_argument("--json", action="store_true", help="Output JSON format")
580
+
581
+ # Command: wait-ready (Testcontainers-style readiness gate)
582
+ wait_p = subparsers.add_parser("wait-ready", help="Wait until a database/container is ready (port|http|sqlite probe)")
583
+ wait_p.add_argument("target", help="URL (http(s)://), host:port, or SQLite file path")
584
+ wait_p.add_argument("--strategy", choices=["auto", "port", "http", "sqlite"], default="auto",
585
+ help="Readiness probe strategy (default: auto-detect)")
586
+ wait_p.add_argument("--timeout", type=float, default=30.0, help="Deadline in seconds (default: 30)")
587
+ wait_p.add_argument("--json", action="store_true", help="Output JSON format")
588
+
589
+ args = parser.parse_args()
590
+
591
+ if not args.command:
592
+ parser.print_help()
593
+ return 1
594
+
595
+ if args.command == "wait-ready":
596
+ res = wait_for_ready(args.target, strategy=args.strategy, timeout_sec=args.timeout)
597
+ if args.json:
598
+ print(json.dumps(res, indent=2))
599
+ else:
600
+ if res["ready"]:
601
+ print(f"✅ [READY] {res['target']} via {res['strategy']} probe "
602
+ f"({res['elapsed_ms']}ms, {res['attempts']} attempt(s))")
603
+ else:
604
+ print(f"❌ [NOT READY] {res['target']} via {res['strategy']} probe "
605
+ f"after {res['elapsed_ms']}ms / {res['attempts']} attempt(s)")
606
+ print(f" Last error: {res['error']}")
607
+ return 0 if res["ready"] else 1
608
+
609
+ resolved_db_type = getattr(args, "db_type", "") or "sqlite"
610
+ sandbox = DBSandbox(db_type=resolved_db_type, db_path=args.db_path)
611
+
612
+ if args.command == "snapshot":
613
+ res = sandbox.create_snapshot(args.id)
614
+ if args.json:
615
+ print(json.dumps(res, indent=2))
616
+ else:
617
+ if res.get("status") == "ERROR":
618
+ print(f"❌ [DB SNAPSHOT FAILED] ID: {res.get('snapshot_id')}")
619
+ print(f" Error: {res.get('error')}")
620
+ else:
621
+ print(f"📦 [DB SNAPSHOT CREATED] ID: {res['snapshot_id']}")
622
+ print(f" Source : {res['source_db']}")
623
+ print(f" Target : {res['snapshot_path']}")
624
+ print(f" Time : {res['snapshot_duration_sec']}s")
625
+ return 0 if res.get("status") != "ERROR" else 1
626
+
627
+ elif args.command == "restore":
628
+ res = sandbox.restore_snapshot(args.id)
629
+ if args.json:
630
+ print(json.dumps(res, indent=2))
631
+ else:
632
+ if res.get("status") == "ERROR":
633
+ print(f"❌ [DB RESTORE FAILED] ID: {res.get('snapshot_id')}")
634
+ print(f" Error: {res.get('message')}")
635
+ else:
636
+ print(f"♻️ [DB RESTORED] Snapshot: {res.get('snapshot_id')}")
637
+ print(f" Target : {res.get('target_db')}")
638
+ print(f" Time : {res.get('restore_duration_sec', 0)}s (Zero-Pollution Guaranteed)")
639
+ return 0 if res.get("status") != "ERROR" else 1
640
+
641
+ elif args.command == "rollback-test":
642
+ sqls = args.sql or [
643
+ "INSERT INTO users (code, status) VALUES ('AUTO_USER_001', 'ACTIVE');",
644
+ "INSERT INTO orders (user_id, amount) VALUES (1, 1500.0);"
645
+ ]
646
+ res = sandbox.execute_with_savepoint(sqls)
647
+ if args.json:
648
+ print(json.dumps(res, indent=2))
649
+ else:
650
+ print(f"🛡️ [TRANSACTION SAVEPOINT ROLLBACK] Status: {res['status']}")
651
+ print(f" Executed : {res['statements_executed']} statements")
652
+ print(f" Inside Transaction : {res['count_inside_transaction']} records")
653
+ print(f" After Rollback : {res['count_after_rollback']} records (Pristine clean)")
654
+ return 0
655
+
656
+ elif args.command == "audit":
657
+ res = sandbox.audit_and_purge_pollution(dry_run=args.dry_run)
658
+ if args.json:
659
+ print(json.dumps(res, indent=2))
660
+ else:
661
+ action_label = "Previewed" if args.dry_run else "Purged"
662
+ print(f"🧹 [TAINT POLLUTION AUDIT] {action_label} {res['total_purged_rows']} orphan test records.")
663
+ for detail in res.get("purge_details", []):
664
+ print(f" - {detail}")
665
+ if not args.dry_run:
666
+ print(" ✅ Zero Pollution Achieved.")
667
+ return 0
668
+
669
+ else:
670
+ parser.print_help()
671
+ return 0
672
+
673
+
674
+ if __name__ == "__main__":
675
+ sys.exit(main())