fix(scripts): improve usability across all ADR-061 QEMU testing scripts

- Add --help/-h flags to all 4 shell scripts with usage, env vars, examples
- Add prerequisite checks with install hints (apt/brew/pip) for missing tools
- Standardize exit codes (0=PASS, 1=WARN, 2=FAIL, 3=FATAL) across all scripts
- Standardize MESH_TIMEOUT to QEMU_TIMEOUT with backward compatibility
- Add SKIP_BUILD precheck for missing flash image in qemu-esp32s3-test.sh
- Add argparse to validate_qemu_output.py (was using raw sys.argv)
- Improve error messages in generate_nvs_matrix.py with NVS tool install hints
- Add socket connection warnings in inject_fault.py connect_monitor()
- Add example output epilog to check_health.py --help
- Add glossary (14 terms) and quick-start section to ADR-061
- Add GDB debugging walkthrough to ADR-061 Layer 4
- Fix stat portability in CI workflow (stat -c%s -> portable file_size())
- Add -type f to find commands in CI workflow

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
2026-03-14 11:19:39 -04:00
parent fb2d1afb0c
commit 1dbea4e9fb
11 changed files with 457 additions and 51 deletions
+19 -7
View File
@@ -196,12 +196,18 @@ def validate_mesh(
# Load aggregator results if available
results: Optional[dict] = None
if results_path and results_path.exists():
try:
results = json.loads(results_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError) as exc:
report.add("Results JSON", Severity.ERROR,
f"Failed to parse results: {exc}")
if results_path:
if not results_path.exists():
print(f"WARNING: Aggregator results file not found: {results_path}",
file=sys.stderr)
report.add("Results JSON", Severity.WARN,
f"Results file not found: {results_path}")
else:
try:
results = json.loads(results_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError) as exc:
report.add("Results JSON", Severity.ERROR,
f"Failed to parse results: {exc}")
# Load per-node logs
node_logs: Dict[int, str] = {}
@@ -449,8 +455,14 @@ def validate_mesh(
def main():
parser = argparse.ArgumentParser(
description="Validate multi-node mesh QEMU test output (ADR-061 Layer 3)",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=(
"Examples:\n"
" python3 validate_mesh_test.py --nodes 3 --results mesh_results.json\n"
" python3 validate_mesh_test.py --nodes 4 --log node0.log --log node1.log"
),
)
parser.add_argument("results", nargs="?", default=None,
parser.add_argument("--results", default=None,
help="Path to mesh_test_results.json from aggregator")
parser.add_argument("--nodes", "-n", type=int, required=True,
help="Expected number of mesh nodes")