@teevee98/synapse-hub 4.2.3 → 4.2.4

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 (36) hide show
  1. package/.agents/rules/mandatory-playwright-live.md +1 -1
  2. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +2 -2
  3. package/.agents/skills/01-web-automation/playwright-live-interaction/references/recipes.md +14 -31
  4. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +5 -4
  5. package/AGENTS.md +1 -1
  6. package/README.en.md +2 -2
  7. package/README.md +2 -2
  8. package/agentskills.json +1 -1
  9. package/docs/ARCHITECTURE.en.md +1 -1
  10. package/docs/ARCHITECTURE.md +1 -1
  11. package/docs/PERFORMANCE_AUDIT_REPORT.md +2 -2
  12. package/docs/TOOL_CATALOG.md +25 -20
  13. package/package.json +1 -1
  14. package/plugin.json +1 -1
  15. package/scripts/setup.sh +6 -1
  16. package/skills_manifest.json +1 -1
  17. package/synapse.config.json +1 -1
  18. package/tools/TOOL_CATALOG.json +112 -31
  19. package/tools/__init__.py +1 -1
  20. package/tools/browser_helpers.js +2 -2
  21. package/tools/cli.py +3 -3
  22. package/tools/core/file_lock.py +7 -0
  23. package/tools/core/memory_bus.py +44 -40
  24. package/tools/core/process_supervisor.py +12 -4
  25. package/tools/core/telemetry.py +54 -16
  26. package/tools/dashboard_generator.py +6 -6
  27. package/tools/db_sandbox.py +8 -2
  28. package/tools/generate_tool_catalog.py +32 -2
  29. package/tools/mcp_docx_server.py +1 -1
  30. package/tools/mcp_excel_server.py +1 -1
  31. package/tools/mcp_server.py +1 -1
  32. package/tools/package_release.py +22 -27
  33. package/tools/reversible_sandbox.py +43 -10
  34. package/tools/ui_server.py +1 -1
  35. package/tools/update_sentinel.py +3 -3
  36. package/tools/welcome_page.py +1 -1
@@ -643,7 +643,7 @@ class DBSandbox:
643
643
  "tables_audited": 0,
644
644
  "total_purged_rows": 0,
645
645
  "purge_details": [],
646
- "zero_pollution_achieved": True,
646
+ "zero_pollution_achieved": False,
647
647
  "message": "No database found"
648
648
  }
649
649
 
@@ -688,12 +688,18 @@ class DBSandbox:
688
688
  finally:
689
689
  conn.close()
690
690
 
691
+ # Zero pollution is achieved if:
692
+ # 1. Not a dry run, meaning any identified pollution was actively deleted and committed.
693
+ # 2. Or, dry run audited the tables and found 0 polluted rows (total_purged == 0).
694
+ # If dry run found polluted rows but didn't delete them, zero pollution has NOT been achieved.
695
+ achieved = (not dry_run) or (total_purged == 0)
696
+
691
697
  return {
692
698
  "status": "CLEAN" if not dry_run else "DRY_RUN",
693
699
  "tables_audited": len(tables),
694
700
  "total_purged_rows": total_purged,
695
701
  "purge_details": purge_log,
696
- "zero_pollution_achieved": True,
702
+ "zero_pollution_achieved": achieved,
697
703
  "dry_run": dry_run
698
704
  }
699
705
 
@@ -64,11 +64,31 @@ TOOL_REGISTRY_METADATA = {
64
64
  "category": "CI/CD & Packaging",
65
65
  "owner_role": "orchestrator",
66
66
  "status": "stable",
67
- "risk_level": "read_only",
67
+ "risk_level": "modifying",
68
68
  "inputs": ["--output-dir", "--format zip|tar.gz|both", "--verify-archive"],
69
69
  "outputs": ["dist/synapse-hub-vX.Y.Z.zip", "dist/*-checksums.sha256"],
70
70
  "description": "Enterprise release packager preserving .github/workflows and generating SHA-256 provenance."
71
71
  },
72
+ "db_sandbox.py": {
73
+ "command": "python tools/db_sandbox.py",
74
+ "category": "Sandboxing & Isolation",
75
+ "owner_role": "failure-analyst",
76
+ "status": "stable",
77
+ "risk_level": "modifying",
78
+ "inputs": ["--mode audit|purge|restore", "--db-path", "--consent"],
79
+ "outputs": ["Database snapshots", "Purge audit logs"],
80
+ "description": "Database state isolation sentinel with granular consent-governed snapshot and purge capabilities."
81
+ },
82
+ "reversible_sandbox.py": {
83
+ "command": "python tools/reversible_sandbox.py",
84
+ "category": "Sandboxing & Isolation",
85
+ "owner_role": "failure-analyst",
86
+ "status": "stable",
87
+ "risk_level": "modifying",
88
+ "inputs": ["--execute-stateful", "--rollback", "--recover-wal"],
89
+ "outputs": [".agent_memory/undo_wal.jsonl", "Reversible execution rollbacks"],
90
+ "description": "Two-phase commit write-ahead logging (WAL) execution sandbox providing crash-resilient rollback guarantees."
91
+ },
72
92
  "fsm_enforcer.py": {
73
93
  "command": "python tools/fsm_enforcer.py",
74
94
  "category": "Orchestration",
@@ -395,13 +415,23 @@ def build_catalog() -> Dict[str, Any]:
395
415
  else:
396
416
  # Auto-inferred metadata for auxiliary tools
397
417
  is_test_tool = "test" in fname or "fuzz" in fname or "mock" in fname
418
+ lower_name = fname.lower()
419
+ if any(k in lower_name for k in ("purge", "delete", "destroy", "kill")):
420
+ inferred_risk = "destructive"
421
+ elif any(k in lower_name for k in ("network", "http", "curl", "fetch", "download")):
422
+ inferred_risk = "network"
423
+ elif any(k in lower_name for k in ("mutate", "heal", "patch", "sandbox", "supervisor", "exec", "publish", "deploy", "release", "push", "upload", "write", "sync", "bump", "rollback", "revert", "clean")):
424
+ inferred_risk = "modifying"
425
+ else:
426
+ inferred_risk = "read_only"
427
+
398
428
  entry = {
399
429
  "file": f"tools/{fname}",
400
430
  "command": f"python tools/{fname}",
401
431
  "category": "Testing & Utilities" if is_test_tool else "Auxiliary Utilities",
402
432
  "owner_role": "orchestrator",
403
433
  "status": "stable" if os.path.getsize(full_path) > 1000 else "experimental",
404
- "risk_level": "read_only",
434
+ "risk_level": inferred_risk,
405
435
  "inputs": ["CLI options"],
406
436
  "outputs": ["Artifacts / Telemetry"],
407
437
  "description": doc_summary or f"Synapse Hub utility module: {fname}"
@@ -60,7 +60,7 @@ if hasattr(sys.stdout, 'reconfigure'):
60
60
  except Exception:
61
61
  pass
62
62
 
63
- SERVER_VERSION = "4.2.3"
63
+ SERVER_VERSION = "4.2.4"
64
64
  MAX_DOCX_SIZE = 50 * 1024 * 1024 # 50 MB
65
65
  MAX_UNCOMPRESSED_SIZE = 200 * 1024 * 1024 # 200 MB
66
66
  MAX_RATIO = 100 # 100:1 compression ratio limit
@@ -55,7 +55,7 @@ if hasattr(sys.stdout, 'reconfigure'):
55
55
  except Exception:
56
56
  pass
57
57
 
58
- SERVER_VERSION = "4.2.3"
58
+ SERVER_VERSION = "4.2.4"
59
59
  MAX_XLSX_SIZE = 50 * 1024 * 1024 # 50 MB
60
60
  MAX_UNCOMPRESSED_SIZE = 200 * 1024 * 1024 # 200 MB
61
61
  MAX_RATIO = 100 # 100:1 compression ratio limit
@@ -50,7 +50,7 @@ import gherkin_suite
50
50
  import api_fuzzer
51
51
 
52
52
  SERVER_NAME = "enterprise-agent-qa"
53
- SERVER_VERSION = "4.2.3"
53
+ SERVER_VERSION = "4.2.4"
54
54
 
55
55
  MCP_TOOLS = [
56
56
  {
@@ -221,6 +221,25 @@ def verify_archive_integrity(archive_path: str) -> Tuple[bool, List[str]]:
221
221
  return (len(missing) == 0), missing
222
222
 
223
223
 
224
+ def clean_stale_release_archives(out_dir: str) -> int:
225
+ """
226
+ Safely cleans up older release archives strictly within the designated output directory.
227
+ Guarded against repo root wildcard deletion or cleaning outside the target output scope.
228
+ """
229
+ if not os.path.exists(out_dir):
230
+ return 0
231
+ release_pattern = re.compile(r"^synapse-hub-v\d+\.\d+\.\d+.*?\.(zip|tar\.gz|sha256)$", re.IGNORECASE)
232
+ cleaned = 0
233
+ for f in os.listdir(out_dir):
234
+ if release_pattern.match(f):
235
+ try:
236
+ os.remove(os.path.join(out_dir, f))
237
+ cleaned += 1
238
+ except OSError:
239
+ continue
240
+ return cleaned
241
+
242
+
224
243
  def package_synapse_hub(
225
244
  repo_root: str = REPO_ROOT,
226
245
  output_dir: str = "dist",
@@ -231,35 +250,11 @@ def package_synapse_hub(
231
250
  Main packaging entrypoint: cleans stale archives, builds single target archive, and verifies integrity.
232
251
  """
233
252
  version = get_version(repo_root)
234
- out_dir = os.path.join(repo_root, output_dir)
253
+ out_dir = os.path.abspath(output_dir) if os.path.isabs(output_dir) else os.path.abspath(os.path.join(repo_root, output_dir))
235
254
  os.makedirs(out_dir, exist_ok=True)
236
255
 
237
- # 1. Clean up old release archives safely (guarded against repo root wildcard deletion)
238
- is_same_as_root = False
239
- try:
240
- is_same_as_root = os.path.samefile(out_dir, repo_root)
241
- except (FileNotFoundError, OSError, ValueError):
242
- is_same_as_root = os.path.realpath(out_dir).lower() == os.path.realpath(repo_root).lower()
243
-
244
- for f in os.listdir(out_dir):
245
- if re.match(r"^synapse-hub-v\d+\.\d+\.\d+.*", f, re.IGNORECASE) and f.endswith((".zip", ".tar.gz", ".sha256")):
246
- try:
247
- os.remove(os.path.join(out_dir, f))
248
- except OSError:
249
- continue
250
- elif not is_same_as_root and f.endswith((".zip", ".tar.gz", ".sha256")) and f.lower().startswith("synapse-hub"):
251
- try:
252
- os.remove(os.path.join(out_dir, f))
253
- except OSError:
254
- continue
255
-
256
- if not is_same_as_root:
257
- for f in os.listdir(repo_root):
258
- if re.match(r"^synapse-hub-v\d+\.\d+\.\d+.*", f, re.IGNORECASE) and f.endswith((".zip", ".tar.gz", ".sha256")):
259
- try:
260
- os.remove(os.path.join(repo_root, f))
261
- except OSError:
262
- continue
256
+ # 1. Clean up old release archives strictly inside the designated out_dir
257
+ clean_stale_release_archives(out_dir)
263
258
 
264
259
  files = collect_package_files(repo_root)
265
260
  base_name = f"synapse-hub-v{version}"
@@ -134,8 +134,8 @@ class ExecutionSandbox:
134
134
  raise last_err or PathContainmentError(f"Path '{target_path}' escapes sandbox root containment.")
135
135
  return contained
136
136
 
137
- def _append_wal(self, action: ReversibleAction):
138
- """Persists a pending undo action to disk before side-effects complete."""
137
+ def _append_wal(self, action: ReversibleAction, status: str = "PENDING"):
138
+ """Persists an undo action to disk before side-effects complete with durable fsync. Propagates errors."""
139
139
  if not self.wal_path:
140
140
  return
141
141
  entry = {
@@ -143,7 +143,7 @@ class ExecutionSandbox:
143
143
  "target_resource": action.target_resource,
144
144
  "undo_command": action.undo_command,
145
145
  "metadata": action.metadata,
146
- "status": "PENDING",
146
+ "status": status,
147
147
  "timestamp": time.time()
148
148
  }
149
149
  line = json.dumps(entry, ensure_ascii=False) + "\n"
@@ -154,12 +154,15 @@ class ExecutionSandbox:
154
154
  with open(self.wal_path, "a", encoding="utf-8") as f:
155
155
  f.write(line)
156
156
  f.flush()
157
+ os.fsync(f.fileno())
157
158
  except ImportError:
158
159
  with open(self.wal_path, "a", encoding="utf-8") as f:
159
160
  f.write(line)
160
161
  f.flush()
162
+ os.fsync(f.fileno())
161
163
  except Exception as e:
162
- sys.stderr.write(f"Warning: Failed to write undo WAL journal: {e}\n")
164
+ sys.stderr.write(f"Error: Failed to write undo WAL journal: {e}\n")
165
+ raise RuntimeError(f"Failed to write undo WAL journal: {e}") from e
163
166
 
164
167
  def _clear_wal(self):
165
168
  """Clears or resets WAL journal when stack has been completely unwound without errors."""
@@ -170,10 +173,12 @@ class ExecutionSandbox:
170
173
  from tools.core.file_lock import file_lock
171
174
  with file_lock(self.wal_path + ".lock", timeout=5.0):
172
175
  with open(self.wal_path, "w", encoding="utf-8") as f:
173
- pass
176
+ f.flush()
177
+ os.fsync(f.fileno())
174
178
  except ImportError:
175
179
  with open(self.wal_path, "w", encoding="utf-8") as f:
176
- pass
180
+ f.flush()
181
+ os.fsync(f.fileno())
177
182
  except Exception as clear_err:
178
183
  sys.stderr.write(f"Notice: Failed to clear WAL: {clear_err}\n")
179
184
 
@@ -215,12 +220,15 @@ class ExecutionSandbox:
215
220
  with open(self.wal_path, "w", encoding="utf-8") as f:
216
221
  f.write(content)
217
222
  f.flush()
223
+ os.fsync(f.fileno())
218
224
  except ImportError:
219
225
  with open(self.wal_path, "w", encoding="utf-8") as f:
220
226
  f.write(content)
221
227
  f.flush()
228
+ os.fsync(f.fileno())
222
229
  except Exception as e:
223
230
  sys.stderr.write(f"Warning: Failed to update WAL journal: {e}\n")
231
+ raise RuntimeError(f"Failed to update WAL journal: {e}") from e
224
232
 
225
233
  def record_mutation(
226
234
  self,
@@ -236,8 +244,8 @@ class ExecutionSandbox:
236
244
  undo_command=undo_command,
237
245
  metadata=metadata or {}
238
246
  )
247
+ self._append_wal(action, status="PENDING")
239
248
  self.undo_stack.append(action)
240
- self._append_wal(action)
241
249
 
242
250
  def execute_stateful_action(
243
251
  self,
@@ -246,15 +254,37 @@ class ExecutionSandbox:
246
254
  forward_cmd: str,
247
255
  undo_cmd: str
248
256
  ) -> bool:
249
- """Executes a forward shell command and immediately records its reversible undo counterpart."""
257
+ """
258
+ Executes a forward shell command with strict Write-Ahead Logging (WAL) protocol:
259
+ 1. Persists PREPARED undo record with durable fsync BEFORE executing the side-effect.
260
+ 2. Executes forward command.
261
+ 3. If forward command succeeds, registers action into undo_stack and transitions WAL to PENDING.
262
+ 4. If forward command fails, reverts the PREPARED entry and aborts safely.
263
+ """
264
+ action = ReversibleAction(
265
+ action_type=action_type,
266
+ target_resource=target_resource,
267
+ undo_command=undo_cmd,
268
+ metadata={"forward_cmd": forward_cmd}
269
+ )
270
+ try:
271
+ self._append_wal(action, status="PREPARED")
272
+ except Exception as wal_err:
273
+ sys.stderr.write(f"Abort stateful action: cannot write WAL prepared record: {wal_err}\n")
274
+ return False
275
+
250
276
  try:
251
277
  args = _split_cmd(forward_cmd) if isinstance(forward_cmd, str) else forward_cmd
252
278
  res = subprocess.run(args, text=True, capture_output=True, timeout=60.0)
253
279
  if res.returncode == 0:
254
- self.record_mutation(action_type, target_resource, undo_cmd, {"forward_cmd": forward_cmd})
280
+ self.undo_stack.append(action)
281
+ self._update_wal_journal(self.undo_stack, failed_entries=None)
255
282
  return True
256
- return False
283
+ else:
284
+ self._update_wal_journal(self.undo_stack, failed_entries=None)
285
+ return False
257
286
  except Exception:
287
+ self._update_wal_journal(self.undo_stack, failed_entries=None)
258
288
  return False
259
289
 
260
290
  def rollback_all(self, silent: bool = False) -> List[Dict[str, Any]]:
@@ -366,6 +396,9 @@ class ExecutionSandbox:
366
396
  for line in lines:
367
397
  try:
368
398
  data = json.loads(line)
399
+ status = data.get("status", "PENDING")
400
+ if status in ("ABORTED", "RESOLVED"):
401
+ continue
369
402
  actions.append(ReversibleAction(
370
403
  action_type=data.get("action_type", "WAL_RECOVERED"),
371
404
  target_resource=data.get("target_resource", ""),
@@ -238,7 +238,7 @@ class SynapseUiHandler(BaseHTTPRequestHandler):
238
238
  if path == "/api/status":
239
239
  active_target = JOB_MANAGER.target_dir or REPO_ROOT
240
240
  self.send_json(200, {
241
- "version": "4.2.3",
241
+ "version": "4.2.4",
242
242
  "status": "ONLINE",
243
243
  "os": sys.platform,
244
244
  "workspace": active_target,
@@ -68,7 +68,7 @@ def get_local_version():
68
68
  try:
69
69
  with open(pkg_file, "r", encoding="utf-8") as f:
70
70
  data = json.load(f)
71
- return data.get("version", "4.2.3")
71
+ return data.get("version", "4.2.4")
72
72
  except (OSError, json.JSONDecodeError):
73
73
  data = {}
74
74
 
@@ -77,11 +77,11 @@ def get_local_version():
77
77
  try:
78
78
  with open(manifest_file, "r", encoding="utf-8") as f:
79
79
  data = json.load(f)
80
- return data.get("version", "4.2.3")
80
+ return data.get("version", "4.2.4")
81
81
  except (OSError, json.JSONDecodeError):
82
82
  data = {}
83
83
 
84
- return "4.2.3"
84
+ return "4.2.4"
85
85
 
86
86
 
87
87
  def fetch_remote_version():
@@ -47,7 +47,7 @@ def get_hub_metadata() -> Dict[str, Any]:
47
47
  """Retrieves version and catalog count from skills_manifest.json."""
48
48
  manifest_path = os.path.join(HUB_ROOT, "skills_manifest.json")
49
49
  meta = {
50
- "version": "4.2.3",
50
+ "version": "4.2.4",
51
51
  "totalSkills": 53,
52
52
  "author": "Thế Vị (@TeeVee98)",
53
53
  "repo": "https://github.com/TeeVee98/Synapse-Hub"