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
+12 -4
View File
@@ -16,6 +16,7 @@ Exit codes:
3 Fatal (crash or corruption detected)
"""
import argparse
import re
import sys
from dataclasses import dataclass, field
@@ -364,11 +365,18 @@ def validate_log(log_text: str) -> ValidationReport:
def main():
if len(sys.argv) < 2:
print(f"Usage: {sys.argv[0]} <log_file>", file=sys.stderr)
sys.exit(3)
parser = argparse.ArgumentParser(
description="Validate QEMU ESP32-S3 UART output (ADR-061)",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="Example: python3 validate_qemu_output.py build/qemu_output.log",
)
parser.add_argument(
"log_file",
help="Path to QEMU UART log file",
)
args = parser.parse_args()
log_path = Path(sys.argv[1])
log_path = Path(args.log_file)
if not log_path.exists():
print(f"ERROR: Log file not found: {log_path}", file=sys.stderr)
sys.exit(3)