@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.
- package/.agents/agents/api-engineer.md +67 -0
- package/.agents/agents/failure-analyst.md +75 -0
- package/.agents/agents/live-explorer.md +70 -0
- package/.agents/agents/orchestrator.md +104 -0
- package/.agents/agents/perf-engineer.md +74 -0
- package/.agents/agents/pom-crafter.md +112 -0
- package/.agents/agents/quality-gatekeeper.md +87 -0
- package/.agents/agents/test-designer.md +73 -0
- package/.agents/agents/test-runner.md +67 -0
- package/.agents/rules/author-integrity-guard.md +33 -0
- package/.agents/rules/communication-style.md +18 -0
- package/.agents/rules/context-engineering.md +37 -0
- package/.agents/rules/git-push-protocol.md +33 -0
- package/.agents/rules/graphify.md +14 -0
- package/.agents/rules/lessons-learned.md +25 -0
- package/.agents/rules/mandatory-playwright-live.md +25 -0
- package/.agents/rules/mobile_appium_rules.md +43 -0
- package/.agents/rules/performance_testing_rules.md +35 -0
- package/.agents/rules/skill-precedence.md +29 -0
- package/.agents/rules/systematic-debugging.md +36 -0
- package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
- package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
- package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
- package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
- package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
- package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
- package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
- package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
- package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
- package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
- package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
- package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
- package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
- package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
- package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
- package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
- package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
- package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
- package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
- package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
- package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
- package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
- package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
- package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
- package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
- package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
- package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
- package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
- package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
- package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
- package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
- package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
- package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
- package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
- package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
- package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
- package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
- package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
- package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
- package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
- package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
- package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
- package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
- package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
- package/.agents/skills/github-actions-templates/SKILL.md +77 -0
- package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
- package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
- package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
- package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
- package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
- package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
- package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
- package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
- package/.agents/skills/lam-script-generator/SKILL.md +123 -0
- package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
- package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
- package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
- package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
- package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
- package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
- package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
- package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
- package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
- package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
- package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
- package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
- package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
- package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
- package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
- package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
- package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
- package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
- package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
- package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
- package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
- package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
- package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
- package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
- package/.agents/skills/qa-memory-os/SKILL.md +80 -0
- package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
- package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
- package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
- package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
- package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
- package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
- package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
- package/.agents/skills/review-spec/SKILL.md +60 -0
- package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
- package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
- package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
- package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
- package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
- package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
- package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
- package/.agents/skills/self-healing-locator/SKILL.md +86 -0
- package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
- package/.agents/skills/senior-code-review/SKILL.md +108 -0
- package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
- package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
- package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
- package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
- package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
- package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
- package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
- package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
- package/.agents/skills/systematic-debugging/SKILL.md +100 -0
- package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
- package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
- package/.agents/skills/test-driven-development/SKILL.md +114 -0
- package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
- package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
- package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
- package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
- package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
- package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
- package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
- package/.agents/skills/verification-before-completion/SKILL.md +100 -0
- package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
- package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
- package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
- package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
- package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
- package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
- package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
- package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
- package/.agents/templates/completion_report.md +57 -0
- package/.agents/workflows/analyze_requirement_document.md +18 -0
- package/.agents/workflows/export_testcases_excel.md +32 -0
- package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
- package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
- package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
- package/.agents/workflows/generate_requirements_from_website.md +25 -0
- package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
- package/.agents/workflows/graphify.md +10 -0
- package/.agents/workflows/test-impact.md +15 -0
- package/.agents/workflows/verify.md +34 -0
- package/.cursor/rules/agents.mdc +16 -0
- package/.cursor/rules/language.mdc +7 -0
- package/.cursor/rules/synapse-qa.mdc +24 -0
- package/.cursorrules +27 -0
- package/.dockerignore +53 -0
- package/.pre-commit-hooks.yaml +14 -0
- package/.windsurfrules +26 -0
- package/AGENTS.md +86 -0
- package/CLAUDE.md +54 -0
- package/Dockerfile +81 -0
- package/LICENSE +52 -0
- package/NOTICE +264 -0
- package/README.en.md +172 -0
- package/README.md +171 -2
- package/action.yml +51 -0
- package/agentskills.json +16 -0
- package/bin/agent-qa.js +138 -0
- package/docker-compose.yml +74 -0
- package/docs/ARCHITECTURE.en.md +197 -0
- package/docs/ARCHITECTURE.md +198 -0
- package/docs/CI_CD_INTEGRATION.en.md +170 -0
- package/docs/CI_CD_INTEGRATION.md +170 -0
- package/docs/CLI_REFERENCE.en.md +175 -0
- package/docs/CLI_REFERENCE.md +177 -0
- package/docs/CONTRIBUTING.en.md +49 -0
- package/docs/CONTRIBUTING.md +49 -0
- package/docs/PERFORMANCE_AUDIT_REPORT.md +784 -0
- package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
- package/docs/QUALITY_GATES.en.md +121 -0
- package/docs/QUALITY_GATES.md +121 -0
- package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
- package/docs/TOOL_CATALOG.md +129 -0
- package/docs/adopted-ecosystem-tools.md +96 -0
- package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
- package/docs/research/agent_skill_training_analysis.md +1359 -0
- package/docs/schemas/synapse.config.schema.json +87 -0
- package/package.json +94 -4
- package/plugin.json +31 -0
- package/scripts/generate_skill_examples.py +244 -0
- package/scripts/install.ps1 +112 -0
- package/scripts/install_global_plugin.ps1 +94 -0
- package/scripts/install_global_plugin.sh +49 -0
- package/scripts/lint_skills.ps1 +57 -0
- package/scripts/package_dist.py +337 -0
- package/scripts/setup.sh +59 -0
- package/scripts/update_hub.ps1 +19 -0
- package/scripts/update_hub.sh +15 -0
- package/skills_manifest.json +854 -0
- package/synapse.config.json +32 -0
- package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
- package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
- package/templates/ai_bridges/CLAUDE.md +54 -0
- package/templates/ai_bridges/copilot-instructions.md +20 -0
- package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
- package/templates/ai_bridges/windsurfrules +26 -0
- package/templates/ci/github-actions-synapse.yml +95 -0
- package/templates/ci/gitlab-ci-synapse.yml +16 -0
- package/templates/ui/index.html +1069 -0
- package/templates/welcome.html.tmpl +2079 -0
- package/tools/.infer_baseline.json +30 -0
- package/tools/TOOLS_RUNBOOK.md +1553 -0
- package/tools/TOOL_CATALOG.json +1769 -0
- package/tools/__init__.py +43 -0
- package/tools/_openapi_parser.py +158 -0
- package/tools/agent_canary.py +525 -0
- package/tools/agentless_patcher.py +417 -0
- package/tools/analyze_project.py +258 -0
- package/tools/api_drift_sentinel.py +208 -0
- package/tools/api_fuzzer.py +762 -0
- package/tools/author_integrity.py +184 -0
- package/tools/auto_heal.py +271 -0
- package/tools/auto_heal_reflexion.py +532 -0
- package/tools/autogen_qa_broker.py +844 -0
- package/tools/benchmark_swarm_context.py +394 -0
- package/tools/browser_helpers.js +746 -0
- package/tools/browsergym_eval.py +236 -0
- package/tools/bug_reporter.py +252 -0
- package/tools/bump_version.py +423 -0
- package/tools/cache_resolver.py +1214 -0
- package/tools/check_env.py +426 -0
- package/tools/check_version_sync.py +256 -0
- package/tools/ci_healing_hook.py +126 -0
- package/tools/cli.py +1598 -0
- package/tools/config_decoupler.py +253 -0
- package/tools/contract_validator.py +141 -0
- package/tools/core/__init__.py +70 -0
- package/tools/core/adapters.py +431 -0
- package/tools/core/circuit_breaker.py +263 -0
- package/tools/core/cli_runtime.py +66 -0
- package/tools/core/file_lock.py +159 -0
- package/tools/core/i18n.py +394 -0
- package/tools/core/memory_bus.py +905 -0
- package/tools/core/process_supervisor.py +332 -0
- package/tools/core/telemetry.py +329 -0
- package/tools/count_tokens.py +1267 -0
- package/tools/create_mock_docx.py +104 -0
- package/tools/dashboard_generator.py +2419 -0
- package/tools/db_sandbox.py +675 -0
- package/tools/debt_harvester.py +237 -0
- package/tools/distill_log.py +161 -0
- package/tools/dspy_qa_signatures.py +356 -0
- package/tools/e2e_flow_prober.py +132 -0
- package/tools/export_postman_collection.py +945 -0
- package/tools/flaky_detector.py +389 -0
- package/tools/fsm_enforcer.py +450 -0
- package/tools/fsm_middleware.py +401 -0
- package/tools/fuzz_payloads.py +197 -0
- package/tools/generate_allure_report.py +88 -0
- package/tools/generate_api_matrix.py +193 -0
- package/tools/generate_jmx_plan.py +1322 -0
- package/tools/generate_sbom.py +252 -0
- package/tools/generate_tc_from_story.py +203 -0
- package/tools/generate_test_reports.py +133 -0
- package/tools/generate_tool_catalog.py +482 -0
- package/tools/gherkin_suite.py +758 -0
- package/tools/git_pre_commit_guard.py +298 -0
- package/tools/goldfish_review.py +366 -0
- package/tools/heal/__init__.py +28 -0
- package/tools/heal_pr_automator.py +220 -0
- package/tools/heuristic_locator_matcher.py +351 -0
- package/tools/hub_publisher.py +623 -0
- package/tools/humanize_linter.py +438 -0
- package/tools/infer_linter.py +977 -0
- package/tools/init_config.py +307 -0
- package/tools/interview_story.py +116 -0
- package/tools/jira_sync.py +566 -0
- package/tools/jtl_analyzer.py +474 -0
- package/tools/lint/__init__.py +30 -0
- package/tools/lint_ai_docs.py +374 -0
- package/tools/lookup_tc.py +165 -0
- package/tools/lookup_xpath.py +167 -0
- package/tools/matrix_sharder.py +148 -0
- package/tools/mcp/__init__.py +18 -0
- package/tools/mcp_docx_server.ps1 +13 -0
- package/tools/mcp_docx_server.py +851 -0
- package/tools/mcp_excel_server.ps1 +13 -0
- package/tools/mcp_excel_server.py +441 -0
- package/tools/mcp_server.py +724 -0
- package/tools/md_to_xlsx.py +327 -0
- package/tools/micro_mutator.py +887 -0
- package/tools/mipro_assertion_tuner.py +210 -0
- package/tools/network_mock_shield.py +311 -0
- package/tools/newman_analyzer.py +384 -0
- package/tools/omni_emitter.py +579 -0
- package/tools/omni_parser.py +450 -0
- package/tools/omni_transpiler.py +168 -0
- package/tools/openxml_guard.py +438 -0
- package/tools/output_formatter.py +182 -0
- package/tools/package_release.py +325 -0
- package/tools/perf/__init__.py +24 -0
- package/tools/pinpoint_failure.py +190 -0
- package/tools/project_state.py +171 -0
- package/tools/qa_event_stream.py +358 -0
- package/tools/repo_map.py +346 -0
- package/tools/report/__init__.py +32 -0
- package/tools/reversible_sandbox.py +344 -0
- package/tools/safety_firewall.py +437 -0
- package/tools/security_coverage_ledger.py +538 -0
- package/tools/security_scanner.py +229 -0
- package/tools/senior_code_review.py +393 -0
- package/tools/setup_project.py +770 -0
- package/tools/skill_collision_guard.py +304 -0
- package/tools/skill_profiles.py +217 -0
- package/tools/skill_vault.py +481 -0
- package/tools/skillspector.py +1278 -0
- package/tools/smart_visual_masker.py +132 -0
- package/tools/spec_drift_sentinel.py +438 -0
- package/tools/swe_qa_aci.py +369 -0
- package/tools/synapse_observer.py +485 -0
- package/tools/synapse_qa_bench.py +190 -0
- package/tools/sync_agent_rules.py +274 -0
- package/tools/telemetry_correlator.py +397 -0
- package/tools/template_excel_exporter.py +514 -0
- package/tools/templates/jmeter-distributed/README.md +54 -0
- package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
- package/tools/test_impact.py +419 -0
- package/tools/test_memory_os.py +462 -0
- package/tools/textgrad_mutation_optimizer.py +237 -0
- package/tools/tms_sync_bridge.py +834 -0
- package/tools/tot_exploratory_tester.py +239 -0
- package/tools/trace_data_flow.py +240 -0
- package/tools/traffic_session_converter.py +256 -0
- package/tools/trend_analytics.py +314 -0
- package/tools/ui_server.py +401 -0
- package/tools/universal_ir.py +488 -0
- package/tools/update_sentinel.py +383 -0
- package/tools/validate_groovy_scripts.py +173 -0
- package/tools/verify_all.py +1259 -0
- package/tools/visual_diff_canvas.py +143 -0
- package/tools/visual_som_helper.py +550 -0
- package/tools/watch_mode.py +308 -0
- package/tools/wcag_audit.py +239 -0
- package/tools/welcome_page.py +290 -0
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
|
|
5
|
+
|
|
6
|
+
"""
|
|
7
|
+
Reusable Process Group Supervisor & Zombie Process Reaper (tools.core.process_supervisor)
|
|
8
|
+
------------------------------------------------------------------------------------------
|
|
9
|
+
Guarantees hermetic lifecycle supervision of external test runners and headless browsers.
|
|
10
|
+
Prevents orphaned zombie processes (chromedriver, chromium, node, java) from exhausting
|
|
11
|
+
system file descriptors and RAM on CI runners and local developer workstations.
|
|
12
|
+
|
|
13
|
+
Key Mechanisms:
|
|
14
|
+
1. Process Group Isolation:
|
|
15
|
+
- On POSIX: `start_new_session=True` assigns a distinct process group ID (`pgid = proc.pid`).
|
|
16
|
+
- On Windows: `CREATE_NEW_PROCESS_GROUP` isolates the process hierarchy.
|
|
17
|
+
2. Two-Stage Cascading Reap:
|
|
18
|
+
- Stage 1: Graceful termination via SIGTERM / SIGBREAK with bounded grace period.
|
|
19
|
+
- Stage 2: Forceful termination via SIGKILL / taskkill /F to eradicate descendants.
|
|
20
|
+
3. Optional psutil Integration:
|
|
21
|
+
- If psutil is present in environment, scans and kills recursive child trees directly.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
import os
|
|
27
|
+
import signal
|
|
28
|
+
import subprocess
|
|
29
|
+
import sys
|
|
30
|
+
import time
|
|
31
|
+
from dataclasses import dataclass
|
|
32
|
+
from typing import Any, Dict, List, Optional, Tuple
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass
|
|
36
|
+
class SupervisedResult:
|
|
37
|
+
"""Outcome of a supervised subprocess execution."""
|
|
38
|
+
cmd: List[str]
|
|
39
|
+
returncode: int
|
|
40
|
+
stdout: str
|
|
41
|
+
stderr: str
|
|
42
|
+
timed_out: bool = False
|
|
43
|
+
duration_sec: float = 0.0
|
|
44
|
+
|
|
45
|
+
@property
|
|
46
|
+
def ok(self) -> bool:
|
|
47
|
+
return self.returncode == 0 and not self.timed_out
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def kill_process_tree(pid: int, timeout: float = 2.0) -> bool:
|
|
51
|
+
"""
|
|
52
|
+
Terminates a process and all of its descendant child/grandchild processes.
|
|
53
|
+
Cross-platform: uses process groups on POSIX, taskkill on Windows, or psutil if available.
|
|
54
|
+
"""
|
|
55
|
+
if pid <= 0:
|
|
56
|
+
return False
|
|
57
|
+
|
|
58
|
+
# 1. Try psutil if installed
|
|
59
|
+
try:
|
|
60
|
+
import psutil # type: ignore
|
|
61
|
+
try:
|
|
62
|
+
parent = psutil.Process(pid)
|
|
63
|
+
children = parent.children(recursive=True)
|
|
64
|
+
for child in children:
|
|
65
|
+
try:
|
|
66
|
+
child.terminate()
|
|
67
|
+
except (psutil.NoSuchProcess, psutil.AccessDenied) as err:
|
|
68
|
+
_ = err
|
|
69
|
+
parent.terminate()
|
|
70
|
+
|
|
71
|
+
gone, alive = psutil.wait_procs(children + [parent], timeout=timeout)
|
|
72
|
+
for p in alive:
|
|
73
|
+
try:
|
|
74
|
+
p.kill()
|
|
75
|
+
except (psutil.NoSuchProcess, psutil.AccessDenied) as err:
|
|
76
|
+
_ = err
|
|
77
|
+
return True
|
|
78
|
+
except (psutil.NoSuchProcess, psutil.AccessDenied):
|
|
79
|
+
return True
|
|
80
|
+
except ImportError as err:
|
|
81
|
+
_ = err
|
|
82
|
+
|
|
83
|
+
# 2. Platform-native fallback
|
|
84
|
+
if sys.platform == "win32":
|
|
85
|
+
try:
|
|
86
|
+
subprocess.run(
|
|
87
|
+
["taskkill", "/F", "/T", "/PID", str(pid)],
|
|
88
|
+
stdout=subprocess.DEVNULL,
|
|
89
|
+
stderr=subprocess.DEVNULL,
|
|
90
|
+
check=False,
|
|
91
|
+
timeout=5.0
|
|
92
|
+
)
|
|
93
|
+
return True
|
|
94
|
+
except Exception:
|
|
95
|
+
return False
|
|
96
|
+
else:
|
|
97
|
+
# POSIX: use process group if PID is group leader, combined with recursive descendant tracking
|
|
98
|
+
descendant_pids: List[int] = []
|
|
99
|
+
to_check = [pid]
|
|
100
|
+
while to_check:
|
|
101
|
+
curr = to_check.pop(0)
|
|
102
|
+
try:
|
|
103
|
+
out = subprocess.run(
|
|
104
|
+
["pgrep", "-P", str(curr)],
|
|
105
|
+
capture_output=True,
|
|
106
|
+
text=True,
|
|
107
|
+
timeout=1.0,
|
|
108
|
+
check=False
|
|
109
|
+
)
|
|
110
|
+
if out.returncode == 0:
|
|
111
|
+
for line in out.stdout.splitlines():
|
|
112
|
+
c_str = line.strip()
|
|
113
|
+
if c_str.isdigit():
|
|
114
|
+
cp = int(c_str)
|
|
115
|
+
if cp not in descendant_pids and cp != pid:
|
|
116
|
+
descendant_pids.append(cp)
|
|
117
|
+
to_check.append(cp)
|
|
118
|
+
except Exception as err:
|
|
119
|
+
_ = err
|
|
120
|
+
|
|
121
|
+
try:
|
|
122
|
+
pgid = os.getpgid(pid)
|
|
123
|
+
except OSError as err:
|
|
124
|
+
_ = err
|
|
125
|
+
pgid = None
|
|
126
|
+
|
|
127
|
+
# Stage 1: Graceful SIGTERM to process group and individual descendants
|
|
128
|
+
if pgid is not None:
|
|
129
|
+
try:
|
|
130
|
+
os.killpg(pgid, signal.SIGTERM)
|
|
131
|
+
except OSError as err:
|
|
132
|
+
_ = err
|
|
133
|
+
for p in [pid] + descendant_pids:
|
|
134
|
+
try:
|
|
135
|
+
os.kill(p, signal.SIGTERM)
|
|
136
|
+
except OSError as err:
|
|
137
|
+
_ = err
|
|
138
|
+
|
|
139
|
+
# Bounded polling wait before force kill
|
|
140
|
+
start = time.time()
|
|
141
|
+
while time.time() - start < timeout:
|
|
142
|
+
alive = False
|
|
143
|
+
if pgid is not None:
|
|
144
|
+
try:
|
|
145
|
+
os.killpg(pgid, 0)
|
|
146
|
+
alive = True
|
|
147
|
+
except OSError as err:
|
|
148
|
+
_ = err
|
|
149
|
+
for p in [pid] + descendant_pids:
|
|
150
|
+
try:
|
|
151
|
+
os.kill(p, 0)
|
|
152
|
+
alive = True
|
|
153
|
+
except OSError as err:
|
|
154
|
+
_ = err
|
|
155
|
+
if not alive:
|
|
156
|
+
return True
|
|
157
|
+
time.sleep(0.05)
|
|
158
|
+
|
|
159
|
+
# Stage 2: Forceful SIGKILL to eradicate all remaining processes
|
|
160
|
+
for p in descendant_pids + [pid]:
|
|
161
|
+
try:
|
|
162
|
+
os.kill(p, signal.SIGKILL)
|
|
163
|
+
except OSError as err:
|
|
164
|
+
_ = err
|
|
165
|
+
if pgid is not None:
|
|
166
|
+
try:
|
|
167
|
+
os.killpg(pgid, signal.SIGKILL)
|
|
168
|
+
except OSError as err:
|
|
169
|
+
_ = err
|
|
170
|
+
try:
|
|
171
|
+
subprocess.run(["pkill", "-KILL", "-P", str(pid)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2.0)
|
|
172
|
+
except Exception as err:
|
|
173
|
+
_ = err
|
|
174
|
+
return True
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def reap_orphan_processes(target_names: Optional[Tuple[str, ...]] = None) -> int:
|
|
178
|
+
"""
|
|
179
|
+
Safeguard reaper for orphaned runner and browser processes.
|
|
180
|
+
Defaults to known test drivers: chromedriver, chromium, node, java.
|
|
181
|
+
Returns the count of reaped processes.
|
|
182
|
+
"""
|
|
183
|
+
targets = target_names or ("chromedriver", "geckodriver", "chromium", "playwright")
|
|
184
|
+
reaped = 0
|
|
185
|
+
|
|
186
|
+
try:
|
|
187
|
+
import psutil # type: ignore
|
|
188
|
+
current_pid = os.getpid()
|
|
189
|
+
for proc in psutil.process_iter(attrs=["pid", "name"]):
|
|
190
|
+
try:
|
|
191
|
+
pname = (proc.info.get("name") or "").lower()
|
|
192
|
+
pid = proc.info.get("pid")
|
|
193
|
+
if pid and pid != current_pid and any(t in pname for t in targets):
|
|
194
|
+
proc.kill()
|
|
195
|
+
reaped += 1
|
|
196
|
+
except (psutil.NoSuchProcess, psutil.AccessDenied):
|
|
197
|
+
continue
|
|
198
|
+
return reaped
|
|
199
|
+
except ImportError as err:
|
|
200
|
+
_ = err
|
|
201
|
+
|
|
202
|
+
# Native CLI fallbacks when psutil is not available
|
|
203
|
+
if sys.platform == "win32":
|
|
204
|
+
for target in targets:
|
|
205
|
+
im_name = target if target.endswith(".exe") else f"{target}.exe"
|
|
206
|
+
try:
|
|
207
|
+
res = subprocess.run(
|
|
208
|
+
["taskkill", "/F", "/IM", im_name],
|
|
209
|
+
stdout=subprocess.DEVNULL,
|
|
210
|
+
stderr=subprocess.DEVNULL,
|
|
211
|
+
timeout=5.0
|
|
212
|
+
)
|
|
213
|
+
if res.returncode == 0:
|
|
214
|
+
reaped += 1
|
|
215
|
+
except Exception as err:
|
|
216
|
+
_ = err
|
|
217
|
+
else:
|
|
218
|
+
for target in targets:
|
|
219
|
+
try:
|
|
220
|
+
res = subprocess.run(
|
|
221
|
+
["pkill", "-f", target],
|
|
222
|
+
stdout=subprocess.DEVNULL,
|
|
223
|
+
stderr=subprocess.DEVNULL,
|
|
224
|
+
timeout=5.0
|
|
225
|
+
)
|
|
226
|
+
if res.returncode == 0:
|
|
227
|
+
reaped += 1
|
|
228
|
+
except Exception as err:
|
|
229
|
+
_ = err
|
|
230
|
+
return reaped
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
class ProcessSupervisor:
|
|
234
|
+
"""
|
|
235
|
+
Supervises external process lifecycles with guaranteed group cleanup.
|
|
236
|
+
"""
|
|
237
|
+
|
|
238
|
+
def __init__(self, default_timeout: float = 60.0):
|
|
239
|
+
self.default_timeout = default_timeout
|
|
240
|
+
self._active_pids: List[int] = []
|
|
241
|
+
|
|
242
|
+
def run(
|
|
243
|
+
self,
|
|
244
|
+
cmd: List[str],
|
|
245
|
+
timeout: Optional[float] = None,
|
|
246
|
+
cwd: Optional[str] = None,
|
|
247
|
+
env: Optional[Dict[str, str]] = None,
|
|
248
|
+
capture_output: bool = True,
|
|
249
|
+
text: bool = True,
|
|
250
|
+
input_data: Optional[str] = None,
|
|
251
|
+
) -> SupervisedResult:
|
|
252
|
+
"""
|
|
253
|
+
Executes cmd in an isolated session/process-group, ensuring all descendants
|
|
254
|
+
are reaped upon timeout or unexpected failure.
|
|
255
|
+
"""
|
|
256
|
+
t_limit = timeout if timeout is not None else self.default_timeout
|
|
257
|
+
if t_limit is not None and t_limit <= 0:
|
|
258
|
+
t_limit = 0.001
|
|
259
|
+
start_time = time.perf_counter()
|
|
260
|
+
|
|
261
|
+
def _to_str(val: Any) -> str:
|
|
262
|
+
if isinstance(val, bytes):
|
|
263
|
+
return val.decode("utf-8", errors="replace")
|
|
264
|
+
return val or ""
|
|
265
|
+
|
|
266
|
+
# Process group configuration
|
|
267
|
+
popen_kwargs: Dict[str, Any] = {
|
|
268
|
+
"cwd": cwd,
|
|
269
|
+
"env": env,
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
if capture_output:
|
|
273
|
+
popen_kwargs["stdout"] = subprocess.PIPE
|
|
274
|
+
popen_kwargs["stderr"] = subprocess.PIPE
|
|
275
|
+
if input_data is not None:
|
|
276
|
+
popen_kwargs["stdin"] = subprocess.PIPE
|
|
277
|
+
|
|
278
|
+
if sys.platform == "win32":
|
|
279
|
+
popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
|
|
280
|
+
else:
|
|
281
|
+
popen_kwargs["start_new_session"] = True
|
|
282
|
+
|
|
283
|
+
proc = subprocess.Popen(cmd, text=text, **popen_kwargs)
|
|
284
|
+
self._active_pids.append(proc.pid)
|
|
285
|
+
|
|
286
|
+
stdout_data, stderr_data = "", ""
|
|
287
|
+
timed_out = False
|
|
288
|
+
|
|
289
|
+
try:
|
|
290
|
+
stdout_raw, stderr_raw = proc.communicate(input=input_data, timeout=t_limit)
|
|
291
|
+
stdout_data = _to_str(stdout_raw)
|
|
292
|
+
stderr_data = _to_str(stderr_raw)
|
|
293
|
+
returncode = proc.returncode
|
|
294
|
+
except subprocess.TimeoutExpired:
|
|
295
|
+
timed_out = True
|
|
296
|
+
kill_process_tree(proc.pid)
|
|
297
|
+
try:
|
|
298
|
+
stdout_raw, stderr_raw = proc.communicate(timeout=1.0)
|
|
299
|
+
stdout_data = _to_str(stdout_raw)
|
|
300
|
+
stderr_data = _to_str(stderr_raw)
|
|
301
|
+
except Exception as comm_err:
|
|
302
|
+
_ = comm_err
|
|
303
|
+
returncode = 124
|
|
304
|
+
except Exception as exc:
|
|
305
|
+
kill_process_tree(proc.pid)
|
|
306
|
+
returncode = 1
|
|
307
|
+
stderr_data = str(exc)
|
|
308
|
+
finally:
|
|
309
|
+
if proc.pid in self._active_pids:
|
|
310
|
+
self._active_pids.remove(proc.pid)
|
|
311
|
+
|
|
312
|
+
elapsed = time.perf_counter() - start_time
|
|
313
|
+
return SupervisedResult(
|
|
314
|
+
cmd=cmd,
|
|
315
|
+
returncode=returncode,
|
|
316
|
+
stdout=stdout_data,
|
|
317
|
+
stderr=stderr_data,
|
|
318
|
+
timed_out=timed_out,
|
|
319
|
+
duration_sec=elapsed
|
|
320
|
+
)
|
|
321
|
+
|
|
322
|
+
def cleanup_all(self):
|
|
323
|
+
"""Emergency cleanup of any active process groups tracked by this supervisor."""
|
|
324
|
+
for pid in list(self._active_pids):
|
|
325
|
+
kill_process_tree(pid)
|
|
326
|
+
self._active_pids.clear()
|
|
327
|
+
|
|
328
|
+
def __enter__(self) -> ProcessSupervisor:
|
|
329
|
+
return self
|
|
330
|
+
|
|
331
|
+
def __exit__(self, exc_type, exc_val, exc_tb):
|
|
332
|
+
self.cleanup_all()
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
|
|
5
|
+
|
|
6
|
+
"""
|
|
7
|
+
Synapse Hub — Structured Observability & OpenTelemetry W3C Trace Context
|
|
8
|
+
-----------------------------------------------------------------------
|
|
9
|
+
Provides high-performance structured JSON logging and W3C TraceContext
|
|
10
|
+
propagation across multi-agent processes, tools, and CI runners.
|
|
11
|
+
|
|
12
|
+
Key Features:
|
|
13
|
+
1. W3C TraceContext Specification (traceparent: 00-{trace_id}-{span_id}-{flags}):
|
|
14
|
+
- 128-bit Trace ID (32 hex characters) and 64-bit Span ID (16 hex characters).
|
|
15
|
+
- Deterministic injection/extraction across HTTP headers, dictionaries, and env vars.
|
|
16
|
+
2. Thread & Async Safe Context Propagation:
|
|
17
|
+
- Backed by contextvars with zero cross-coroutine leakage.
|
|
18
|
+
3. Structured JSON Logging:
|
|
19
|
+
- Formats standard log records into strict JSON conforming to:
|
|
20
|
+
{timestamp, level, trace_id, span_id, parent_span_id, module, event, duration_ms}
|
|
21
|
+
4. Span Tracing Context Manager:
|
|
22
|
+
- `trace_span(event, module=...)` for measuring latencies and emitting trace spans.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
import os
|
|
26
|
+
import sys
|
|
27
|
+
import json
|
|
28
|
+
import time
|
|
29
|
+
import secrets
|
|
30
|
+
import logging
|
|
31
|
+
import contextvars
|
|
32
|
+
from datetime import datetime, timezone
|
|
33
|
+
from dataclasses import dataclass
|
|
34
|
+
from typing import Dict, Any, Optional, Generator
|
|
35
|
+
from contextlib import contextmanager
|
|
36
|
+
|
|
37
|
+
# W3C Constants
|
|
38
|
+
W3C_VERSION = "00"
|
|
39
|
+
FLAG_SAMPLED = "01"
|
|
40
|
+
FLAG_NOT_SAMPLED = "00"
|
|
41
|
+
TRACEPARENT_HEADER = "traceparent"
|
|
42
|
+
TRACESTATE_HEADER = "tracestate"
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def generate_trace_id() -> str:
|
|
46
|
+
"""Generates a random 128-bit W3C Trace ID (32 lowercase hex characters)."""
|
|
47
|
+
return secrets.token_hex(16)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def generate_span_id() -> str:
|
|
51
|
+
"""Generates a random 64-bit W3C Span ID (16 lowercase hex characters)."""
|
|
52
|
+
return secrets.token_hex(8)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class TraceContext:
|
|
57
|
+
"""Represents a W3C TraceContext entity."""
|
|
58
|
+
trace_id: str
|
|
59
|
+
span_id: str
|
|
60
|
+
parent_span_id: Optional[str] = None
|
|
61
|
+
sampled: bool = True
|
|
62
|
+
trace_state: str = ""
|
|
63
|
+
|
|
64
|
+
@property
|
|
65
|
+
def traceparent(self) -> str:
|
|
66
|
+
flags = FLAG_SAMPLED if self.sampled else FLAG_NOT_SAMPLED
|
|
67
|
+
return f"{W3C_VERSION}-{self.trace_id}-{self.span_id}-{flags}"
|
|
68
|
+
|
|
69
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
70
|
+
return {
|
|
71
|
+
"trace_id": self.trace_id,
|
|
72
|
+
"span_id": self.span_id,
|
|
73
|
+
"parent_span_id": self.parent_span_id,
|
|
74
|
+
"sampled": self.sampled,
|
|
75
|
+
"traceparent": self.traceparent,
|
|
76
|
+
"trace_state": self.trace_state,
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
_CURRENT_CONTEXT: contextvars.ContextVar[Optional[TraceContext]] = contextvars.ContextVar(
|
|
81
|
+
"synapse_trace_context", default=None
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def get_current_trace_context() -> Optional[TraceContext]:
|
|
86
|
+
"""Retrieves the active TraceContext for the current execution context."""
|
|
87
|
+
ctx = _CURRENT_CONTEXT.get()
|
|
88
|
+
if ctx is None and os.environ.get("TRACEPARENT"):
|
|
89
|
+
ctx = parse_traceparent(os.environ["TRACEPARENT"])
|
|
90
|
+
if ctx:
|
|
91
|
+
_CURRENT_CONTEXT.set(ctx)
|
|
92
|
+
return ctx
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def set_current_trace_context(ctx: Optional[TraceContext]) -> None:
|
|
96
|
+
"""Sets the active TraceContext for the current execution context."""
|
|
97
|
+
_CURRENT_CONTEXT.set(ctx)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def parse_traceparent(header_val: str) -> Optional[TraceContext]:
|
|
101
|
+
"""
|
|
102
|
+
Parses a W3C traceparent header value.
|
|
103
|
+
Format: {version}-{trace_id}-{span_id}-{flags}
|
|
104
|
+
Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
|
|
105
|
+
"""
|
|
106
|
+
if not header_val or not isinstance(header_val, str):
|
|
107
|
+
return None
|
|
108
|
+
parts = header_val.strip().split("-")
|
|
109
|
+
if len(parts) != 4:
|
|
110
|
+
return None
|
|
111
|
+
|
|
112
|
+
version, trace_id, span_id, flags = parts
|
|
113
|
+
if len(version) != 2 or len(trace_id) != 32 or len(span_id) != 16 or len(flags) != 2:
|
|
114
|
+
return None
|
|
115
|
+
|
|
116
|
+
# Version 'ff' is forbidden by W3C specification
|
|
117
|
+
if version.lower() == "ff":
|
|
118
|
+
return None
|
|
119
|
+
|
|
120
|
+
# Validate hex characters and non-all-zero ids
|
|
121
|
+
try:
|
|
122
|
+
v_int = int(version, 16)
|
|
123
|
+
t_int = int(trace_id, 16)
|
|
124
|
+
s_int = int(span_id, 16)
|
|
125
|
+
f_int = int(flags, 16)
|
|
126
|
+
if t_int == 0 or s_int == 0:
|
|
127
|
+
return None
|
|
128
|
+
except ValueError:
|
|
129
|
+
return None
|
|
130
|
+
|
|
131
|
+
sampled = flags == FLAG_SAMPLED or bool(int(flags, 16) & 1)
|
|
132
|
+
return TraceContext(
|
|
133
|
+
trace_id=trace_id.lower(),
|
|
134
|
+
span_id=span_id.lower(),
|
|
135
|
+
parent_span_id=None,
|
|
136
|
+
sampled=sampled,
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def format_traceparent(trace_id: str, span_id: str, sampled: bool = True) -> str:
|
|
141
|
+
"""Formats trace components into a valid W3C traceparent string."""
|
|
142
|
+
flags = FLAG_SAMPLED if sampled else FLAG_NOT_SAMPLED
|
|
143
|
+
return f"{W3C_VERSION}-{trace_id.lower()}-{span_id.lower()}-{flags}"
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def inject_traceparent(headers: Optional[Dict[str, str]] = None, context: Optional[TraceContext] = None) -> Dict[str, str]:
|
|
147
|
+
"""
|
|
148
|
+
Injects W3C traceparent into an HTTP headers dictionary or carrier.
|
|
149
|
+
If context is omitted, uses the current ambient context or generates a new one.
|
|
150
|
+
"""
|
|
151
|
+
if headers is None:
|
|
152
|
+
headers = {}
|
|
153
|
+
ctx = context or get_current_trace_context()
|
|
154
|
+
if ctx is None:
|
|
155
|
+
ctx = create_trace_context()
|
|
156
|
+
set_current_trace_context(ctx)
|
|
157
|
+
|
|
158
|
+
headers[TRACEPARENT_HEADER] = ctx.traceparent
|
|
159
|
+
if ctx.trace_state:
|
|
160
|
+
headers[TRACESTATE_HEADER] = ctx.trace_state
|
|
161
|
+
return headers
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def extract_traceparent(headers: Dict[str, str]) -> Optional[TraceContext]:
|
|
165
|
+
"""Extracts W3C traceparent and tracestate from an HTTP headers dictionary (case-insensitive keys)."""
|
|
166
|
+
if not headers or not isinstance(headers, dict):
|
|
167
|
+
return None
|
|
168
|
+
ctx: Optional[TraceContext] = None
|
|
169
|
+
state = ""
|
|
170
|
+
for k, v in headers.items():
|
|
171
|
+
if not isinstance(v, str):
|
|
172
|
+
continue
|
|
173
|
+
k_lower = k.lower()
|
|
174
|
+
if k_lower == TRACEPARENT_HEADER:
|
|
175
|
+
ctx = parse_traceparent(v)
|
|
176
|
+
elif k_lower == TRACESTATE_HEADER:
|
|
177
|
+
state = v.strip()
|
|
178
|
+
if ctx and state:
|
|
179
|
+
ctx.trace_state = state
|
|
180
|
+
return ctx
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def create_trace_context(
|
|
184
|
+
parent: Optional[TraceContext] = None,
|
|
185
|
+
trace_id: Optional[str] = None,
|
|
186
|
+
sampled: bool = True
|
|
187
|
+
) -> TraceContext:
|
|
188
|
+
"""Creates a new TraceContext, linking to parent span if supplied."""
|
|
189
|
+
if parent is not None:
|
|
190
|
+
return TraceContext(
|
|
191
|
+
trace_id=parent.trace_id,
|
|
192
|
+
span_id=generate_span_id(),
|
|
193
|
+
parent_span_id=parent.span_id,
|
|
194
|
+
sampled=parent.sampled,
|
|
195
|
+
trace_state=parent.trace_state,
|
|
196
|
+
)
|
|
197
|
+
return TraceContext(
|
|
198
|
+
trace_id=trace_id or generate_trace_id(),
|
|
199
|
+
span_id=generate_span_id(),
|
|
200
|
+
parent_span_id=None,
|
|
201
|
+
sampled=sampled,
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
class StructuredJsonFormatter(logging.Formatter):
|
|
206
|
+
"""
|
|
207
|
+
Formats log records into structured JSON conforming to enterprise schema:
|
|
208
|
+
{timestamp, level, trace_id, span_id, parent_span_id, module, event, duration_ms, message}
|
|
209
|
+
"""
|
|
210
|
+
|
|
211
|
+
def format(self, record: logging.LogRecord) -> str:
|
|
212
|
+
ctx = get_current_trace_context()
|
|
213
|
+
record_dict: Dict[str, Any] = {
|
|
214
|
+
"timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
|
|
215
|
+
"level": record.levelname,
|
|
216
|
+
"trace_id": getattr(record, "trace_id", ctx.trace_id if ctx else None),
|
|
217
|
+
"span_id": getattr(record, "span_id", ctx.span_id if ctx else None),
|
|
218
|
+
"parent_span_id": getattr(record, "parent_span_id", ctx.parent_span_id if ctx else None),
|
|
219
|
+
"module": getattr(record, "module_name", record.module),
|
|
220
|
+
"event": getattr(record, "event", record.getMessage()),
|
|
221
|
+
"duration_ms": getattr(record, "duration_ms", None),
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
# Include custom extra fields
|
|
225
|
+
if hasattr(record, "extra_payload") and isinstance(record.extra_payload, dict):
|
|
226
|
+
record_dict.update(record.extra_payload)
|
|
227
|
+
|
|
228
|
+
# Include exception if present
|
|
229
|
+
if record.exc_info:
|
|
230
|
+
record_dict["exception"] = self.formatException(record.exc_info)
|
|
231
|
+
|
|
232
|
+
return json.dumps(record_dict, ensure_ascii=False)
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def get_logger(name: str = "synapse") -> logging.Logger:
|
|
236
|
+
"""Returns or configures a standard structured logger with JSON output."""
|
|
237
|
+
logger = logging.getLogger(name)
|
|
238
|
+
if not any(isinstance(h.formatter, StructuredJsonFormatter) for h in logger.handlers):
|
|
239
|
+
handler = logging.StreamHandler(sys.stdout)
|
|
240
|
+
handler.setFormatter(StructuredJsonFormatter())
|
|
241
|
+
logger.addHandler(handler)
|
|
242
|
+
logger.setLevel(logging.INFO)
|
|
243
|
+
return logger
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def log_event(
|
|
247
|
+
level: str,
|
|
248
|
+
event: str,
|
|
249
|
+
module: Optional[str] = None,
|
|
250
|
+
duration_ms: Optional[float] = None,
|
|
251
|
+
logger_name: str = "synapse",
|
|
252
|
+
**extra_payload
|
|
253
|
+
) -> Dict[str, Any]:
|
|
254
|
+
"""
|
|
255
|
+
Emits a structured JSON log event directly.
|
|
256
|
+
Returns the serialized structured dictionary for assertions or inspection.
|
|
257
|
+
"""
|
|
258
|
+
ctx = get_current_trace_context()
|
|
259
|
+
payload: Dict[str, Any] = {
|
|
260
|
+
"timestamp": datetime.now(timezone.utc).isoformat(),
|
|
261
|
+
"level": level.upper(),
|
|
262
|
+
"trace_id": ctx.trace_id if ctx else None,
|
|
263
|
+
"span_id": ctx.span_id if ctx else None,
|
|
264
|
+
"parent_span_id": ctx.parent_span_id if ctx else None,
|
|
265
|
+
"module": module or "synapse",
|
|
266
|
+
"event": event,
|
|
267
|
+
"duration_ms": duration_ms,
|
|
268
|
+
}
|
|
269
|
+
if extra_payload:
|
|
270
|
+
payload.update(extra_payload)
|
|
271
|
+
|
|
272
|
+
lvl_num = getattr(logging, level.upper(), logging.INFO)
|
|
273
|
+
logger = get_logger(logger_name)
|
|
274
|
+
logger.log(
|
|
275
|
+
lvl_num,
|
|
276
|
+
event,
|
|
277
|
+
extra={
|
|
278
|
+
"module_name": payload["module"],
|
|
279
|
+
"event": event,
|
|
280
|
+
"duration_ms": duration_ms,
|
|
281
|
+
"trace_id": payload["trace_id"],
|
|
282
|
+
"span_id": payload["span_id"],
|
|
283
|
+
"parent_span_id": payload["parent_span_id"],
|
|
284
|
+
"extra_payload": extra_payload,
|
|
285
|
+
}
|
|
286
|
+
)
|
|
287
|
+
return payload
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
@contextmanager
|
|
291
|
+
def trace_span(
|
|
292
|
+
event: str,
|
|
293
|
+
module: Optional[str] = None,
|
|
294
|
+
logger_name: str = "synapse",
|
|
295
|
+
**attributes
|
|
296
|
+
) -> Generator[TraceContext, None, None]:
|
|
297
|
+
"""
|
|
298
|
+
Context manager that starts a child span, measures latency,
|
|
299
|
+
logs the completed span with duration_ms, and restores the parent context.
|
|
300
|
+
"""
|
|
301
|
+
parent_ctx = get_current_trace_context()
|
|
302
|
+
span_ctx = create_trace_context(parent=parent_ctx)
|
|
303
|
+
set_current_trace_context(span_ctx)
|
|
304
|
+
start_time = time.perf_counter()
|
|
305
|
+
status = "SUCCESS"
|
|
306
|
+
err_msg = None
|
|
307
|
+
|
|
308
|
+
try:
|
|
309
|
+
yield span_ctx
|
|
310
|
+
except Exception as exc:
|
|
311
|
+
status = "ERROR"
|
|
312
|
+
err_msg = str(exc)
|
|
313
|
+
raise
|
|
314
|
+
finally:
|
|
315
|
+
elapsed_ms = round((time.perf_counter() - start_time) * 1000.0, 3)
|
|
316
|
+
extra = dict(attributes)
|
|
317
|
+
extra["status"] = status
|
|
318
|
+
if err_msg:
|
|
319
|
+
extra["error"] = err_msg
|
|
320
|
+
|
|
321
|
+
log_event(
|
|
322
|
+
level="INFO" if status == "SUCCESS" else "ERROR",
|
|
323
|
+
event=event,
|
|
324
|
+
module=module or "synapse",
|
|
325
|
+
duration_ms=elapsed_ms,
|
|
326
|
+
logger_name=logger_name,
|
|
327
|
+
**extra
|
|
328
|
+
)
|
|
329
|
+
set_current_trace_context(parent_ctx)
|