@teevee98/synapse-hub 4.1.3 → 4.2.0

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 (206) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +6 -1
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +6 -1
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +8 -3
  5. package/.agents/skills/01-web-automation/clean-pom-crafter/examples/standard_test_case.groovy +3 -0
  6. package/.agents/skills/01-web-automation/clean-pom-crafter/references/pom_patterns.groovy +3 -0
  7. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/e2e-testing-patterns/examples/playwright_sharded_config.ts +3 -0
  9. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  10. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  11. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  12. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  13. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  14. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  15. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +7 -2
  16. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  17. package/.agents/skills/01-web-automation/playwright-webapp-testing/examples/server_lifecycle_playwright.py +3 -0
  18. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  19. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  20. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  21. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  22. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  23. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  24. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  25. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  26. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  27. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  28. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  29. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  30. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +3 -0
  31. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  32. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/references/dast_recipes.ts +3 -0
  33. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  34. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  38. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  39. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  40. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  41. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  42. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  43. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  44. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  45. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  46. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  48. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +3 -0
  49. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +3 -0
  50. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  51. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  52. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  53. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  54. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  55. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  56. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  57. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  58. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  59. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  60. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  61. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  62. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  63. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  64. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  65. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/examples/surgical_code_window_walkthrough.md +1 -1
  66. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  67. package/AGENTS.md +7 -1
  68. package/LICENSE +5 -5
  69. package/NOTICE +1 -1
  70. package/README.en.md +4 -4
  71. package/README.md +4 -4
  72. package/agentskills.json +1 -1
  73. package/docs/ARCHITECTURE.en.md +2 -2
  74. package/docs/ARCHITECTURE.md +11 -2
  75. package/docs/CLI_REFERENCE.en.md +6 -4
  76. package/docs/CLI_REFERENCE.md +1 -1
  77. package/docs/CONTRIBUTING.en.md +1 -1
  78. package/docs/CONTRIBUTING.md +2 -2
  79. package/docs/PERFORMANCE_AUDIT_REPORT.md +2 -2
  80. package/docs/TOOL_CATALOG.md +6 -2
  81. package/docs/research/agent_skill_training_analysis.md +1 -1
  82. package/package.json +1 -1
  83. package/plugin.json +1 -1
  84. package/scripts/generate_skill_examples.py +3 -0
  85. package/scripts/package_dist.py +3 -0
  86. package/skills_manifest.json +320 -55
  87. package/synapse.config.json +1 -1
  88. package/templates/ui/index.html +2 -2
  89. package/tools/.infer_baseline.json +3 -796
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +4 -1
  92. package/tools/agent_canary.py +3 -0
  93. package/tools/analyze_project.py +3 -0
  94. package/tools/api_drift_sentinel.py +3 -0
  95. package/tools/api_fuzzer.py +182 -118
  96. package/tools/ast_cache.py +4 -2
  97. package/tools/author_integrity.py +174 -12
  98. package/tools/auto_heal.py +7 -2
  99. package/tools/autogen_qa_broker.py +14 -15
  100. package/tools/benchmark_swarm_context.py +119 -18
  101. package/tools/break_ui_generator.py +233 -0
  102. package/tools/browser_helpers.js +2 -2
  103. package/tools/bug_reporter.py +3 -0
  104. package/tools/build_consolidated_report.py +3 -0
  105. package/tools/bump_version.py +4 -1
  106. package/tools/cache_resolver.py +7 -3
  107. package/tools/check_env.py +3 -0
  108. package/tools/check_version_sync.py +21 -50
  109. package/tools/ci_healing_hook.py +3 -0
  110. package/tools/cli.py +116 -22
  111. package/tools/config_decoupler.py +3 -0
  112. package/tools/core/__init__.py +3 -0
  113. package/tools/core/bm25_retriever.py +218 -0
  114. package/tools/core/file_lock.py +23 -14
  115. package/tools/core/i18n.py +13 -11
  116. package/tools/core/memory_bus.py +6 -3
  117. package/tools/core/process_supervisor.py +28 -18
  118. package/tools/core/provider_usage_adapter.py +317 -0
  119. package/tools/core/token_estimator.py +83 -18
  120. package/tools/count_tokens.py +16 -7
  121. package/tools/coverage_reporter.py +245 -0
  122. package/tools/create_mock_docx.py +3 -0
  123. package/tools/dashboard_generator.py +17 -15
  124. package/tools/db_sandbox.py +150 -5
  125. package/tools/debt_harvester.py +2 -2
  126. package/tools/diagram_architect.py +3 -0
  127. package/tools/distill_log.py +22 -2
  128. package/tools/distill_skill.py +191 -0
  129. package/tools/e2e_flow_prober.py +3 -0
  130. package/tools/export_postman_collection.py +3 -0
  131. package/tools/flaky_detector.py +3 -0
  132. package/tools/fsm_enforcer.py +2 -2
  133. package/tools/fuzz_payloads.py +3 -0
  134. package/tools/generate_allure_report.py +3 -0
  135. package/tools/generate_api_matrix.py +3 -0
  136. package/tools/generate_jmx_plan.py +3 -0
  137. package/tools/generate_tc_from_story.py +3 -0
  138. package/tools/generate_test_reports.py +3 -0
  139. package/tools/git_pre_commit_guard.py +25 -3
  140. package/tools/git_worktree_manager.py +3 -0
  141. package/tools/heal/__init__.py +3 -0
  142. package/tools/heal_pr_automator.py +3 -0
  143. package/tools/heuristic_locator_matcher.py +3 -0
  144. package/tools/hub_publisher.py +3 -3
  145. package/tools/humanize_linter.py +3 -0
  146. package/tools/infer_linter.py +19 -9
  147. package/tools/init_config.py +6 -9
  148. package/tools/jtl_analyzer.py +3 -0
  149. package/tools/lint/__init__.py +3 -0
  150. package/tools/lint_ai_docs.py +3 -0
  151. package/tools/lookup_tc.py +3 -0
  152. package/tools/lookup_xpath.py +3 -0
  153. package/tools/matrix_sharder.py +3 -0
  154. package/tools/mcp/__init__.py +3 -0
  155. package/tools/mcp_docx_server.py +1 -1
  156. package/tools/mcp_excel_server.py +4 -1
  157. package/tools/mcp_server.py +78 -15
  158. package/tools/md_to_xlsx.py +3 -0
  159. package/tools/mechanical_ui_gate.py +3 -0
  160. package/tools/micro_mutator.py +93 -19
  161. package/tools/network_mock_shield.py +3 -0
  162. package/tools/newman_analyzer.py +3 -0
  163. package/tools/omni_emitter.py +3 -0
  164. package/tools/omni_parser.py +3 -0
  165. package/tools/omni_transpiler.py +3 -0
  166. package/tools/output_formatter.py +3 -0
  167. package/tools/package_release.py +6 -6
  168. package/tools/pairwise_generator.py +3 -0
  169. package/tools/pentest_scope_guard.py +401 -58
  170. package/tools/perf/__init__.py +3 -0
  171. package/tools/perf/benchmark_perf_runner.py +42 -0
  172. package/tools/pinpoint_failure.py +3 -0
  173. package/tools/project_state.py +3 -0
  174. package/tools/repo_map.py +3 -0
  175. package/tools/report/__init__.py +3 -0
  176. package/tools/rules_router.py +426 -34
  177. package/tools/runaway_stopper.py +3 -0
  178. package/tools/safety_firewall.py +3 -0
  179. package/tools/security_scanner.py +80 -0
  180. package/tools/senior_code_review.py +14 -0
  181. package/tools/setup_project.py +9 -4
  182. package/tools/skill_canonical_digest.py +244 -0
  183. package/tools/skill_collision_guard.py +2 -2
  184. package/tools/skill_profiles.py +77 -7
  185. package/tools/skillspector.py +2 -1
  186. package/tools/slide_deck_exporter.py +477 -0
  187. package/tools/smart_visual_masker.py +3 -0
  188. package/tools/sync_skills_manifest.py +166 -0
  189. package/tools/task_memory_manager.py +260 -0
  190. package/tools/telemetry_correlator.py +3 -0
  191. package/tools/template_excel_exporter.py +2 -2
  192. package/tools/test_impact.py +3 -0
  193. package/tools/trace_data_flow.py +3 -0
  194. package/tools/traffic_session_converter.py +3 -0
  195. package/tools/ui_server.py +2 -2
  196. package/tools/universal_ir.py +3 -0
  197. package/tools/update_sentinel.py +15 -9
  198. package/tools/validate_groovy_scripts.py +3 -0
  199. package/tools/validate_host_interop.py +485 -0
  200. package/tools/validate_skills_schema.py +282 -0
  201. package/tools/verify_all.py +600 -63
  202. package/tools/visual_diff_canvas.py +3 -0
  203. package/tools/visual_som_helper.py +3 -0
  204. package/tools/watch_mode.py +4 -4
  205. package/tools/wcag_audit.py +3 -0
  206. package/tools/welcome_page.py +2 -2
@@ -163,6 +163,78 @@ def audit_threat_model_firewall() -> Tuple[bool, List[str]]:
163
163
  return (len(findings) == 0), findings
164
164
 
165
165
 
166
+ def format_sarif(report: Dict[str, Any]) -> Dict[str, Any]:
167
+ """Formats security scan report into OASIS SARIF v2.1.0 JSON format."""
168
+ rules = [
169
+ {
170
+ "id": "SEC001-CWE-798",
171
+ "name": "HardcodedCredentialCheck",
172
+ "shortDescription": {"text": "Hard-coded credentials or secret token exposure (CWE-798)"},
173
+ "defaultConfiguration": {"level": "error"}
174
+ },
175
+ {
176
+ "id": "SEC002-CWE-1104",
177
+ "name": "DependencyVulnerabilityCheck",
178
+ "shortDescription": {"text": "Vulnerable third-party dependency (CWE-1104)"},
179
+ "defaultConfiguration": {"level": "warning"}
180
+ },
181
+ {
182
+ "id": "SEC003-CWE-284",
183
+ "name": "ThreatModelFirewallBypass",
184
+ "shortDescription": {"text": "Improper access control or destructive action bypass (CWE-284)"},
185
+ "defaultConfiguration": {"level": "error"}
186
+ }
187
+ ]
188
+
189
+ results = []
190
+ checks = report.get("checks", {})
191
+
192
+ # Check python dependencies findings
193
+ for finding in checks.get("python_dependencies", {}).get("findings", []):
194
+ results.append({
195
+ "ruleId": "SEC002-CWE-1104",
196
+ "level": "warning",
197
+ "message": {"text": str(finding)},
198
+ "locations": [{"physicalLocation": {"artifactLocation": {"uri": "requirements.txt"}}}]
199
+ })
200
+
201
+ # Check npm dependencies findings
202
+ for finding in checks.get("npm_dependencies", {}).get("findings", []):
203
+ results.append({
204
+ "ruleId": "SEC002-CWE-1104",
205
+ "level": "warning",
206
+ "message": {"text": str(finding)},
207
+ "locations": [{"physicalLocation": {"artifactLocation": {"uri": "package.json"}}}]
208
+ })
209
+
210
+ # Check threat model firewall findings
211
+ for finding in checks.get("threat_model_firewall", {}).get("findings", []):
212
+ results.append({
213
+ "ruleId": "SEC003-CWE-284",
214
+ "level": "error",
215
+ "message": {"text": str(finding)},
216
+ "locations": [{"physicalLocation": {"artifactLocation": {"uri": "tools/safety_firewall.py"}}}]
217
+ })
218
+
219
+ return {
220
+ "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
221
+ "version": "2.1.0",
222
+ "runs": [
223
+ {
224
+ "tool": {
225
+ "driver": {
226
+ "name": "Synapse-Hub Security Sentinel",
227
+ "version": "1.0.0",
228
+ "informationUri": "https://github.com/TeeVee98/Synapse-Hub",
229
+ "rules": rules
230
+ }
231
+ },
232
+ "results": results
233
+ }
234
+ ]
235
+ }
236
+
237
+
166
238
  def run_security_scan(repo_root: str = REPO_ROOT) -> Dict[str, Any]:
167
239
  """Runs complete security scan suite."""
168
240
  py_ok, py_findings = audit_python_dependencies(repo_root)
@@ -185,11 +257,19 @@ def run_security_scan(repo_root: str = REPO_ROOT) -> Dict[str, Any]:
185
257
  def main() -> int:
186
258
  parser = argparse.ArgumentParser(description="Comprehensive Enterprise Security Sentinel for Synapse Hub")
187
259
  parser.add_argument("--json", action="store_true", help="Output results in JSON format")
260
+ parser.add_argument("--sarif", type=str, default="", help="Path to write OASIS SARIF v2.1.0 output file")
188
261
  parser.add_argument("--strict", action="store_true", help="Enforce zero warnings")
189
262
  args = parser.parse_args()
190
263
 
191
264
  report = run_security_scan()
192
265
 
266
+ if args.sarif:
267
+ sarif_doc = format_sarif(report)
268
+ os.makedirs(os.path.dirname(os.path.abspath(args.sarif)), exist_ok=True)
269
+ with open(args.sarif, "w", encoding="utf-8") as sf:
270
+ json.dump(sarif_doc, sf, indent=2)
271
+ print(f"📄 SARIF v2.1.0 security report written to: {args.sarif}")
272
+
193
273
  if args.json:
194
274
  print(json.dumps(report, indent=2))
195
275
  return 0 if report["status"] == "PASS" else 1
@@ -257,6 +257,20 @@ def analyze_diff(files: List[Dict[str, Any]], repo_dir: str) -> Tuple[List[Findi
257
257
  if_skipped="Technical debt and confusion will accumulate across commits."
258
258
  ))
259
259
 
260
+ # 6. Flakiness: Raw setTimeout in test code (Next.js & Codex Invariant)
261
+ if is_code_file and ("test" in path_lower or "spec" in path_lower):
262
+ if re.search(r'\bsetTimeout\s*\(', stripped) and not (stripped.startswith("//") or stripped.startswith("#")):
263
+ findings.append(Finding(
264
+ severity="Should fix",
265
+ title="Raw setTimeout detected in test (Next.js / Codex Invariant)",
266
+ file_path=path,
267
+ line_no=line_no,
268
+ what_is="A raw setTimeout delay used in test code.",
269
+ problem="Fixed time delays cause non-deterministic test race conditions and CI flakiness.",
270
+ fix="Replace with explicit retry() / waitForCondition() polling on observable state.",
271
+ if_skipped="Test suite will become flaky under variable runner and network loads."
272
+ ))
273
+
260
274
  # 6. Completeness: Non-trivial logic without any test
261
275
  if has_new_business_code and not has_new_test:
262
276
  findings.append(Finding(
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
2
5
  """
3
6
  Enterprise QA Autonomous Project Setup & Bootstrap Engine
4
7
  ----------------------------------------------------------
@@ -427,16 +430,18 @@ def inject_antigravity_global_plugin():
427
430
  if os.path.islink(dst):
428
431
  try:
429
432
  os.unlink(dst)
430
- except OSError:
431
- _ = False
433
+ except OSError as err:
434
+ import logging
435
+ logging.getLogger("setup_project").debug("Unlink failed: %s", err)
432
436
  if sys.platform == "win32":
433
437
  try:
434
438
  import _winapi
435
439
  if not os.path.exists(dst):
436
440
  _winapi.CreateJunction(src, dst)
437
441
  return
438
- except (OSError, ImportError, AttributeError):
439
- _ = False
442
+ except (OSError, ImportError, AttributeError) as err:
443
+ import logging
444
+ logging.getLogger("setup_project").debug("Windows junction failed, falling back to copytree: %s", err)
440
445
  shutil.copytree(src, dst, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.tmp"))
441
446
 
442
447
  sync_dir(os.path.join(HUB_ROOT, ".agents", "skills"), os.path.join(target_plugin_dir, "skills"))
@@ -0,0 +1,244 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ tools/skill_canonical_digest.py — Single Source of Truth for Skill Canonical Digest & Lockfile Integrity
8
+ ----------------------------------------------------------------------------------------------------------
9
+ Defines and enforces the strict deterministic canonicalization contract for skill folders:
10
+
11
+ 1. Canonicalization Semantics:
12
+ - Root: The skill folder directory (resolves parent directory if pointing to SKILL.md).
13
+ - Traversal: Recursive directory walk across all nested files and subdirectories.
14
+ - Exclusion Set:
15
+ * OS artifacts: .DS_Store, Thumbs.db, desktop.ini, ehthumbs.db
16
+ * Bytecode & runtime cache: __pycache__ directories, *.pyc, *.pyo, *.pyd
17
+ * Editor swap/temp files: *~, *.swp, *.swo, *.tmp, .#*
18
+ * Version control internals: .git, .svn, .hg, .gitignore
19
+ - Symlink Policy: Prohibited (Fail-Closed). Any symlink inside a skill package raises ValueError.
20
+ - Sorting / Ordering: Canonical lexicographical sort on relative POSIX paths (using forward slashes '/').
21
+ - Entry Delimitation:
22
+ * Relative POSIX path encoded as UTF-8, terminated by null byte (b"\\0").
23
+ * Raw binary content read in 64KB chunks.
24
+ * Trailing null byte (b"\\0") after file content to prevent path/content boundary collision.
25
+ - Digest Algorithm: SHA-256 (64 lowercase hexadecimal characters).
26
+
27
+ 2. Validation Invariant (Check Mode):
28
+ - Purely read-only: STRICTLY ZERO filesystem modifications in check mode.
29
+ - Lockfile Parity: skills-lock.json and .skill-lock.json must be byte-for-byte identical.
30
+ - Dynamic Recomputation: Every validation computes digests live from disk; never trusts format alone.
31
+ - Fail-Closed: Any missing file, forged hash, parity mismatch, or corrupted entry fails immediately.
32
+
33
+ 3. Generation Invariant (Update Mode):
34
+ - Explicit generator only (--update-hashes).
35
+ - Deterministic key ordering and LF line endings produce 100% byte-identical output across runs.
36
+ """
37
+
38
+ from __future__ import annotations
39
+
40
+ import os
41
+ import json
42
+ import hashlib
43
+ from typing import Tuple, List, Dict, Any
44
+
45
+ # Files and directories excluded from canonical hash calculation
46
+ EXCLUDED_FILENAMES = frozenset({
47
+ ".DS_Store",
48
+ "Thumbs.db",
49
+ "desktop.ini",
50
+ "ehthumbs.db",
51
+ ".gitignore",
52
+ })
53
+
54
+ EXCLUDED_EXTENSIONS = (
55
+ ".pyc",
56
+ ".pyo",
57
+ ".pyd",
58
+ ".swp",
59
+ ".swo",
60
+ ".tmp",
61
+ "~",
62
+ )
63
+
64
+ EXCLUDED_DIRNAMES = frozenset({
65
+ "__pycache__",
66
+ ".git",
67
+ ".svn",
68
+ ".hg",
69
+ })
70
+
71
+ TOTAL_REGISTERED_SKILLS = 53
72
+
73
+
74
+ def get_skill_canonical_entries(skill_folder_or_file: str) -> List[Tuple[str, str]]:
75
+ """
76
+ Collects and validates all canonical file entries for a skill folder.
77
+ Returns a sorted list of (relative_posix_path, absolute_file_path).
78
+ Raises ValueError if symlinks or invalid files are detected.
79
+ """
80
+ clean_path = os.path.abspath(skill_folder_or_file)
81
+ if not os.path.exists(clean_path):
82
+ raise FileNotFoundError(f"Skill path does not exist: {clean_path}")
83
+
84
+ folder = os.path.dirname(clean_path) if os.path.isfile(clean_path) else clean_path
85
+ entries: List[Tuple[str, str]] = []
86
+
87
+ for root, dirs, files in os.walk(folder, topdown=True):
88
+ # Prune excluded directories in-place (sorted for determinism)
89
+ dirs[:] = [d for d in sorted(dirs) if d not in EXCLUDED_DIRNAMES]
90
+
91
+ for f in sorted(files):
92
+ # Exclude OS, editor, and cache files
93
+ if f in EXCLUDED_FILENAMES:
94
+ continue
95
+ if any(f.endswith(ext) for ext in EXCLUDED_EXTENSIONS):
96
+ continue
97
+ if f.startswith(".#"):
98
+ continue
99
+
100
+ full_p = os.path.join(root, f)
101
+ rel_p = os.path.relpath(full_p, folder).replace("\\", "/")
102
+
103
+ # Enforce symlink policy: reject symlinks to prevent traversal / spoofing
104
+ if os.path.islink(full_p):
105
+ raise ValueError(f"Symlinks are strictly prohibited inside canonical skill packages: {rel_p}")
106
+
107
+ entries.append((rel_p, full_p))
108
+
109
+ entries.sort(key=lambda x: x[0])
110
+ return entries
111
+
112
+
113
+ def compute_skill_folder_hash(skill_folder_or_file: str) -> str:
114
+ """
115
+ Computes a deterministic canonical SHA-256 digest of a skill folder.
116
+ Incorporates relative POSIX paths and file byte contents delimited by null bytes.
117
+ """
118
+ entries = get_skill_canonical_entries(skill_folder_or_file)
119
+ hasher = hashlib.sha256()
120
+
121
+ for rel_p, full_p in entries:
122
+ hasher.update(rel_p.encode("utf-8"))
123
+ hasher.update(b"\0")
124
+ with open(full_p, "rb") as fh:
125
+ while chunk := fh.read(65536):
126
+ hasher.update(chunk)
127
+ hasher.update(b"\0")
128
+
129
+ return hasher.hexdigest().lower()
130
+
131
+
132
+ def validate_lockfile_integrity(repo_root: str, enforce_content_hash: bool = True) -> Tuple[bool, str]:
133
+ """
134
+ Validates canonical lockfile (skills-lock.json) and secondary (.skill-lock.json) integrity.
135
+ Recomputes SHA-256 digests live from disk contents.
136
+
137
+ IMPORTANT: This function runs strictly in check mode and NEVER modifies the working tree.
138
+ """
139
+ canonical_lock = os.path.join(repo_root, "skills-lock.json")
140
+ secondary_lock = os.path.join(repo_root, ".skill-lock.json")
141
+
142
+ # 1. Existence check
143
+ if not os.path.exists(canonical_lock):
144
+ return False, "Canonical lockfile skills-lock.json is missing!"
145
+ if not os.path.exists(secondary_lock):
146
+ return False, "Secondary lockfile .skill-lock.json is missing! Run generator to restore parity."
147
+
148
+ # 2. Strict Lockfile Parity (Must be byte-for-byte identical; no auto-sync during check)
149
+ try:
150
+ with open(canonical_lock, "rb") as cf, open(secondary_lock, "rb") as sf:
151
+ if cf.read() != sf.read():
152
+ return False, (
153
+ "Lockfile parity mismatch: skills-lock.json and .skill-lock.json differ in content. "
154
+ "Run 'python3 tools/check_version_sync.py --update-hashes' to synchronize."
155
+ )
156
+ except OSError as err:
157
+ return False, f"Failed to read lockfiles for parity check: {err}"
158
+
159
+ # 3. JSON Parsing & Structure Validation
160
+ try:
161
+ with open(canonical_lock, "r", encoding="utf-8") as f:
162
+ lock_data = json.load(f)
163
+ except Exception as e:
164
+ return False, f"skills-lock.json malformed JSON: {e}"
165
+
166
+ if lock_data.get("version") != 3:
167
+ return False, f"Unsupported lockfile format version: expected 3, found {lock_data.get('version')}"
168
+
169
+ skills = lock_data.get("skills", {})
170
+ if len(skills) != TOTAL_REGISTERED_SKILLS:
171
+ return False, f"Expected {TOTAL_REGISTERED_SKILLS} skills in skills-lock.json, found {len(skills)}"
172
+
173
+ # 4. Per-Skill Disk Recomputation & Verification
174
+ for s_name, s_meta in skills.items():
175
+ s_path = s_meta.get("skillPath")
176
+ if not s_path:
177
+ return False, f"Skill '{s_name}' missing skillPath"
178
+
179
+ full_path = os.path.join(repo_root, s_path)
180
+ if not os.path.exists(full_path):
181
+ return False, f"Skill '{s_name}' path not found: {s_path}"
182
+
183
+ s_hash = s_meta.get("skillFolderHash")
184
+ if not s_hash or len(s_hash) != 64 or not all(c in "0123456789abcdefABCDEF" for c in s_hash):
185
+ return False, f"Skill '{s_name}' has invalid SHA-256 hash format: {s_hash}"
186
+
187
+ if enforce_content_hash:
188
+ try:
189
+ computed_hash = compute_skill_folder_hash(full_path)
190
+ except Exception as err:
191
+ return False, f"Failed to compute canonical hash for skill '{s_name}': {err}"
192
+
193
+ if s_hash.lower() != computed_hash.lower():
194
+ return False, f"Skill '{s_name}' content hash mismatch: expected {computed_hash}, found in lockfile {s_hash}"
195
+
196
+ return True, f"{len(skills)}/{TOTAL_REGISTERED_SKILLS} skills verified with valid paths & content SHA-256 hashes"
197
+
198
+
199
+ def update_skills_lockfile(repo_root: str) -> Tuple[bool, str]:
200
+ """
201
+ Recalculates canonical SHA-256 hashes for all 53 skills and writes to skills-lock.json & .skill-lock.json.
202
+ Ensures deterministic output: generating twice on the same tree produces byte-identical files.
203
+ """
204
+ canonical_lock = os.path.join(repo_root, "skills-lock.json")
205
+ secondary_lock = os.path.join(repo_root, ".skill-lock.json")
206
+
207
+ if not os.path.exists(canonical_lock):
208
+ return False, "Canonical lockfile skills-lock.json is missing!"
209
+
210
+ try:
211
+ with open(canonical_lock, "r", encoding="utf-8") as f:
212
+ lock_data = json.load(f)
213
+ except Exception as e:
214
+ return False, f"skills-lock.json read error: {e}"
215
+
216
+ skills = lock_data.get("skills", {})
217
+ updated_skills: Dict[str, Any] = {}
218
+
219
+ # Sort skills by name for deterministic serialization
220
+ for s_name in sorted(skills.keys()):
221
+ s_meta = skills[s_name]
222
+ s_path = s_meta.get("skillPath")
223
+ if not s_path:
224
+ return False, f"Skill '{s_name}' missing skillPath"
225
+ full_path = os.path.join(repo_root, s_path)
226
+ if not os.path.exists(full_path):
227
+ return False, f"Skill '{s_name}' path not found: {s_path}"
228
+
229
+ computed_hash = compute_skill_folder_hash(full_path)
230
+ s_meta["skillFolderHash"] = computed_hash
231
+ updated_skills[s_name] = s_meta
232
+
233
+ lock_data["skills"] = updated_skills
234
+ content_str = json.dumps(lock_data, indent=2, ensure_ascii=False) + "\n"
235
+
236
+ try:
237
+ with open(canonical_lock, "w", encoding="utf-8", newline="\n") as f:
238
+ f.write(content_str)
239
+ with open(secondary_lock, "w", encoding="utf-8", newline="\n") as f:
240
+ f.write(content_str)
241
+ except OSError as err:
242
+ return False, f"Failed to write lockfiles: {err}"
243
+
244
+ return True, f"Successfully recalculated and synchronized canonical hashes for {len(updated_skills)} skills."
@@ -129,8 +129,8 @@ class SkillCollisionGuard:
129
129
  with open(full_path, "r", encoding="utf-8", errors="ignore") as fp:
130
130
  content = fp.read()
131
131
  rules[f] = content
132
- except OSError as err:
133
- _ = err
132
+ except OSError:
133
+ continue
134
134
  return rules
135
135
 
136
136
  def audit_rules(self, rules_dir: str = ".agents/rules") -> Tuple[bool, List[Dict[str, Any]]]:
@@ -38,13 +38,80 @@ REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
38
38
  DEFAULT_MANIFEST = os.path.join(REPO_ROOT, "skills_manifest.json")
39
39
 
40
40
 
41
+ def resolve_manifest_path(repo_root: Optional[str] = None) -> Optional[str]:
42
+ """
43
+ Fallback manifest resolution:
44
+ 1. REPO_ROOT/skills_manifest.json
45
+ 2. tools/skills_manifest.json
46
+ 3. importlib.resources.files("tools").joinpath("skills_manifest.json")
47
+ """
48
+ root = repo_root or REPO_ROOT
49
+ # 1. Check REPO_ROOT/skills_manifest.json
50
+ candidate1 = os.path.join(root, "skills_manifest.json")
51
+ if os.path.isfile(candidate1):
52
+ return candidate1
53
+
54
+ # 2. Check tools/skills_manifest.json
55
+ script_dir = os.path.dirname(os.path.abspath(__file__))
56
+ candidate2 = os.path.join(script_dir, "skills_manifest.json")
57
+ if os.path.isfile(candidate2):
58
+ return candidate2
59
+ candidate2_alt = os.path.join(root, "tools", "skills_manifest.json")
60
+ if os.path.isfile(candidate2_alt):
61
+ return candidate2_alt
62
+
63
+ # 3. Check importlib.resources.files("tools").joinpath("skills_manifest.json")
64
+ try:
65
+ import importlib.resources as pkg_resources
66
+ resource = pkg_resources.files("tools").joinpath("skills_manifest.json")
67
+ if resource.is_file():
68
+ try:
69
+ r_str = str(resource)
70
+ if os.path.isfile(r_str):
71
+ return r_str
72
+ except (TypeError, ValueError) as str_err:
73
+ res_str_err = str(str_err)
74
+ with pkg_resources.as_file(resource) as p:
75
+ return str(p)
76
+ except (ImportError, AttributeError, TypeError) as res_err:
77
+ res_load_err = str(res_err)
78
+
79
+ return None
80
+
81
+
82
+ def get_skills_dir(repo_root: Optional[str] = None) -> Optional[str]:
83
+ """Resolves local skills directory or returns None with actionable guidance."""
84
+ root = repo_root or REPO_ROOT
85
+ candidates = [
86
+ os.path.join(root, ".agents", "skills"),
87
+ os.path.join(root, "skills"),
88
+ os.path.join(os.path.dirname(os.path.abspath(__file__)), "skills"),
89
+ ]
90
+ for c in candidates:
91
+ if os.path.isdir(c):
92
+ return c
93
+ return None
94
+
95
+
41
96
  def load_manifest(manifest_path: Optional[str] = None) -> Dict[str, Any]:
42
- """Loads and validates skills_manifest.json."""
43
- path = manifest_path or DEFAULT_MANIFEST
44
- if not os.path.isfile(path):
45
- raise FileNotFoundError(f"Skills manifest not found: {path}")
46
- with open(path, "r", encoding="utf-8") as f:
47
- return json.load(f)
97
+ """Loads and validates skills_manifest.json with fallback resolution."""
98
+ path = manifest_path or resolve_manifest_path()
99
+ if not path or not os.path.isfile(path):
100
+ searched = [
101
+ os.path.join(REPO_ROOT, "skills_manifest.json"),
102
+ os.path.join(os.path.dirname(os.path.abspath(__file__)), "skills_manifest.json"),
103
+ "importlib.resources.files('tools').joinpath('skills_manifest.json')",
104
+ ]
105
+ searched_desc = "\n".join(f" • {s}" for s in searched)
106
+ raise FileNotFoundError(
107
+ f"Skills manifest could not be located. Searched locations:\n{searched_desc}\n"
108
+ "Ensure Synapse Hub was installed with package data, or specify --manifest <path>."
109
+ )
110
+ try:
111
+ with open(path, "r", encoding="utf-8") as f:
112
+ return json.load(f)
113
+ except Exception as e:
114
+ raise RuntimeError(f"Failed to read skills manifest at '{path}': {e}") from e
48
115
 
49
116
 
50
117
  def list_profiles(manifest: Optional[Dict[str, Any]] = None) -> Dict[str, Dict[str, Any]]:
@@ -176,12 +243,15 @@ def main() -> int:
176
243
  parser.add_argument("--category", "-c", help="Filter skills by category")
177
244
  parser.add_argument("--query", "-q", help="Search skills by keyword")
178
245
  parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format (default: text)")
179
- parser.add_argument("--manifest", help="Optional path to skills_manifest.json", default=DEFAULT_MANIFEST)
246
+ parser.add_argument("--manifest", help="Optional path to skills_manifest.json", default=None)
180
247
 
181
248
  args = parser.parse_args()
182
249
 
183
250
  try:
184
251
  manifest = load_manifest(args.manifest)
252
+ except FileNotFoundError as e:
253
+ print(f"Error: {e}", file=sys.stderr)
254
+ return 1
185
255
  except Exception as e:
186
256
  print(f"Error loading manifest: {e}", file=sys.stderr)
187
257
  return 1
@@ -995,7 +995,8 @@ def is_path_ignored(file_or_dir_path: str, repo_anchor: Path, patterns: List[str
995
995
  if spec.match_file(rel_posix):
996
996
  return True
997
997
  except (ImportError, Exception) as err:
998
- _ = err # Fallback to fnmatch below
998
+ import logging
999
+ logging.getLogger("skillspector").debug("Pathspec match failed, falling back to fnmatch: %s", err)
999
1000
 
1000
1001
  # fnmatch fallback
1001
1002
  for pat in patterns: