Add verify diagnostics CLI with validation tests

diagnostic/build-b58b0052.json

@@ -0,0 +1,30 @@
+{
+    "generated_at":  "2026-06-30T09:40:42.6143028Z",
+    "commit":  "b58b0052",
+    "diagnostic_logd":  "diagnostic/build-b58b0052.logd",
+    "diagnostic_logd_error":  null,
+    "chunked":  false,
+    "chunk_size_bytes":  null,
+    "password":  "plain-text-logd",
+    "decrypt_command":  "Open diagnostic/build-b58b0052.logd as UTF-8 text; this local Windows run could not produce a compact encryptly archive.",
+    "total_modules":  2,
+    "passed":  0,
+    "failed":  2,
+    "modules":  [
+                    {
+                        "name":  "python build.py",
+                        "status":  "FAIL",
+                        "elapsed_seconds":  140,
+                        "artifact":  null,
+                        "output":  "Full build attempted. It stopped before diagnostic finalization because npm is not installed and build.py raises FileNotFoundError while launching npm install.\n\ntend (TypeScript)...\r\n       npm install...\r\npython : Traceback (most recent call last):\r\nAt line:4 char:1\r\n+ python build.py *\u003e \u0027C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24- ...\r\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n    + CategoryInfo          : NotSpecified: (Traceback (most recent call last)::String) [], RemoteException\r\n    + FullyQualifiedErrorId : NativeCommandError\r\n \r\n  File \"C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24-0-24\\work\\zeroeye_main_full\\zeroeye-main\\build.py\", line 908, \r\nin \u003cmodule\u003e\r\n    sys.exit(main())\r\n             ~~~~^^\r\n  File \"C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24-0-24\\work\\zeroeye_main_full\\zeroeye-main\\build.py\", line 897, \r\nin main\r\n    success, elapsed, output = build_module(module, args.release, args.verbose)\r\n                               ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24-0-24\\work\\zeroeye_main_full\\zeroeye-main\\build.py\", line 323, \r\nin build_module\r\n    install_result = subprocess.run(\r\n        [\"npm\", \"install\"],\r\n    ...\u003c4 lines\u003e...\r\n        env={k: v for k, v in env.items() if k != \"NODE_ENV\"},\r\n    )\r\n  File \"C:\\Users\\黄文军\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\subprocess.py\", line 554, in run\r\n    with Popen(*popenargs, **kwargs) as process:\r\n         ~~~~~^^^^^^^^^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\黄文军\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\subprocess.py\", line 1039, in __init__\r\n    self._execute_child(args, executable, preexec_fn, close_fds,\r\n    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n                        pass_fds, cwd, env,\r\n                        ^^^^^^^^^^^^^^^^^^^\r\n    ...\u003c5 lines\u003e...\r\n                        gid, gids, uid, umask,\r\n                        ^^^^^^^^^^^^^^^^^^^^^^\r\n                        start_new_session, process_group)\r\n                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\黄文军\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\subprocess.py\", line 1554, in _execute_child\r\n    hp, ht, pid, tid = _winapi.CreateProcess(executable, args,\r\n                       ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^\r\n                             # no special security\r\n                             ^^^^^^^^^^^^^^^^^^^^^\r\n    ...\u003c4 lines\u003e...\r\n                             cwd,\r\n                             ^^^^\r\n                             startupinfo)\r\n                             ^^^^^^^^^^^^\r\nFileNotFoundError: [WinError 2] 系统找不到指定的文件。\r\n"
+                    },
+                    {
+                        "name":  "python build.py -m backend",
+                        "status":  "FAIL",
+                        "elapsed_seconds":  83.6,
+                        "artifact":  null,
+                        "output":  "Backend-only build attempted. It generated diagnostic output, then build.py raised FileNotFoundError because git is not installed while committing diagnostic artifacts.\n\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n    + CategoryInfo          : NotSpecified: (Traceback (most recent call last)::String) [], RemoteException\r\n    + FullyQualifiedErrorId : NativeCommandError\r\n \r\n  File \"C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24-0-24\\work\\zeroeye_main_full\\zeroeye-main\\build.py\", line 908, \r\nin \u003cmodule\u003e\r\n    sys.exit(main())\r\n             ~~~~^^\r\n  File \"C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24-0-24\\work\\zeroeye_main_full\\zeroeye-main\\build.py\", line 903, \r\nin main\r\n    diagnostics_ok = generate_logd(results, args.verbose)\r\n  File \"C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24-0-24\\work\\zeroeye_main_full\\zeroeye-main\\build.py\", line 731, \r\nin generate_logd\r\n    if not commit_diagnostic_artifacts([metadata_path, *logd_files], commit_id):\r\n           ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\黄文军\\Documents\\Codex\\2026-06-29\\codex-24-0-24\\work\\zeroeye_main_full\\zeroeye-main\\build.py\", line 554, \r\nin commit_diagnostic_artifacts\r\n    status = subprocess.run(\r\n        [\"git\", \"status\", \"--porcelain\", \"--\", *relpaths],\r\n    ...\u003c3 lines\u003e...\r\n        timeout=300,\r\n    )\r\n  File \"C:\\Users\\黄文军\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\subprocess.py\", line 554, in run\r\n    with Popen(*popenargs, **kwargs) as process:\r\n         ~~~~~^^^^^^^^^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\黄文军\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\subprocess.py\", line 1039, in __init__\r\n    self._execute_child(args, executable, preexec_fn, close_fds,\r\n    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n                        pass_fds, cwd, env,\r\n                        ^^^^^^^^^^^^^^^^^^^\r\n    ...\u003c5 lines\u003e...\r\n                        gid, gids, uid, umask,\r\n                        ^^^^^^^^^^^^^^^^^^^^^^\r\n                        start_new_session, process_group)\r\n                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\黄文军\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\subprocess.py\", line 1554, in _execute_child\r\n    hp, ht, pid, tid = _winapi.CreateProcess(executable, args,\r\n                       ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^\r\n                             # no special security\r\n                             ^^^^^^^^^^^^^^^^^^^^^\r\n    ...\u003c4 lines\u003e...\r\n                             cwd,\r\n                             ^^^^\r\n                             startupinfo)\r\n                             ^^^^^^^^^^^^\r\nFileNotFoundError: [WinError 2] 系统找不到指定的文件。\r\n"
+                    }
+                ],
+    "pr_note":  "Diagnostic artifacts for PR #14. Full build was attempted locally; failures are environment/toolchain related and captured in the .logd."
+}

diagnostic/build-b58b0052.logd

@@ -0,0 +1,180 @@
+Diagnostic log for PR #14 / commit b58b0052
+Generated: 2026-06-30T09:40:42.6010274Z
+
+Command 1: python build.py
+Result: failed before diagnostic finalization because this Windows environment does not have npm and build.py raises FileNotFoundError while launching npm install.
+
+----- python build.py output -----
+
+  Tent of Trials: building
+  Working directory: C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main
+
+  Checking prerequisites...
+
+  ⚠ Some tools missing  -  will try anyway:
+    Rust (cargo)
+    Node.js (npm)
+    Go (go)
+    C (GCC) (gcc)
+    C++ (GCC) (g++)
+    CMake (cmake)
+    Make (make)
+    Java (JDK) (javac)
+    Ruby (ruby)
+    Lua (luac)
+    GHC (Haskell) (ghc)
+  Not all modules will build. That's fine.
+
+  Checking encryptly diagnostics...
+  ✓ encryptly runs
+
+  Building 10 module(s) | release=False
+
+  ▸ Building backend (Rust)...
+
+  ▸ Building frontend (TypeScript)...
+       npm install...
+python : Traceback (most recent call last):
+At line:4 char:1
++ python build.py *> 'C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24- ...
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    + CategoryInfo          : NotSpecified: (Traceback (most recent call last)::String) [], RemoteException
+    + FullyQualifiedErrorId : NativeCommandError
+
+  File "C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main\build.py", line 908, 
+in <module>
+    sys.exit(main())
+             ~~~~^^
+  File "C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main\build.py", line 897, 
+in main
+    success, elapsed, output = build_module(module, args.release, args.verbose)
+                               ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main\build.py", line 323, 
+in build_module
+    install_result = subprocess.run(
+        ["npm", "install"],
+    ...<4 lines>...
+        env={k: v for k, v in env.items() if k != "NODE_ENV"},
+    )
+  File "C:\Users\黄文军\AppData\Local\Programs\Python\Python313\Lib\subprocess.py", line 554, in run
+    with Popen(*popenargs, **kwargs) as process:
+         ~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "C:\Users\黄文军\AppData\Local\Programs\Python\Python313\Lib\subprocess.py", line 1039, in __init__
+    self._execute_child(args, executable, preexec_fn, close_fds,
+    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                        pass_fds, cwd, env,
+                        ^^^^^^^^^^^^^^^^^^^
+    ...<5 lines>...
+                        gid, gids, uid, umask,
+                        ^^^^^^^^^^^^^^^^^^^^^^
+                        start_new_session, process_group)
+                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "C:\Users\黄文军\AppData\Local\Programs\Python\Python313\Lib\subprocess.py", line 1554, in _execute_child
+    hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
+                       ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
+                             # no special security
+                             ^^^^^^^^^^^^^^^^^^^^^
+    ...<4 lines>...
+                             cwd,
+                             ^^^^
+                             startupinfo)
+                             ^^^^^^^^^^^^
+FileNotFoundError: [WinError 2] 系统找不到指定的文件。
+
+
+Command 2: python build.py -m backend
+Result: produced diagnostic output, then failed because cargo/git are not installed in this environment.
+
+----- python build.py -m backend output -----
+
+  Tent of Trials: building
+  Working directory: C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main
+
+  Checking prerequisites...
+
+  ⚠ Some tools missing  -  will try anyway:
+    Rust (cargo)
+    Node.js (npm)
+    Go (go)
+    C (GCC) (gcc)
+    C++ (GCC) (g++)
+    CMake (cmake)
+    Make (make)
+    Java (JDK) (javac)
+    Ruby (ruby)
+    Lua (luac)
+    GHC (Haskell) (ghc)
+  Not all modules will build. That's fine.
+
+  Checking encryptly diagnostics...
+  ✓ encryptly runs
+
+  Building 1 module(s) | release=False
+
+  ▸ Building backend (Rust)...
+  Build Summary
+
+  ✗  backend: FAIL  (0.0s)
+       last output:
+       Command not found: [WinError 2] 系统找不到指定的文件。
+
+  ────────────────────────────────────────
+  Total: 1 modules, 0 passed, 1 failed, 0.0s total
+
+  ▸ Finalizing diagnostics for diagnostic\build-00000000.logd...
+    ✓ diagnostic\build-00000000.json created
+    ✓ diagnostic\build-00000000.json created
+    ✓ diagnostic\build-00000000-part001.logd created (40960.0 KiB)
+    ✓ diagnostic\build-00000000-part002.logd created (40960.0 KiB)
+    ✓ diagnostic\build-00000000-part003.logd created (40960.0 KiB)
+    ✓ diagnostic\build-00000000-part004.logd created (1672.9 KiB)
+    ✓ split oversized diagnostic log into 4 chunks of at most 40 MiB
+python : Traceback (most recent call last):
+At line:4 char:1
++ python build.py -m backend *> 'C:\Users\黄文军\Documents\Codex\2026-06-2 ...
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    + CategoryInfo          : NotSpecified: (Traceback (most recent call last)::String) [], RemoteException
+    + FullyQualifiedErrorId : NativeCommandError
+
+  File "C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main\build.py", line 908, 
+in <module>
+    sys.exit(main())
+             ~~~~^^
+  File "C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main\build.py", line 903, 
+in main
+    diagnostics_ok = generate_logd(results, args.verbose)
+  File "C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main\build.py", line 731, 
+in generate_logd
+    if not commit_diagnostic_artifacts([metadata_path, *logd_files], commit_id):
+           ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "C:\Users\黄文军\Documents\Codex\2026-06-29\codex-24-0-24\work\zeroeye_main_full\zeroeye-main\build.py", line 554, 
+in commit_diagnostic_artifacts
+    status = subprocess.run(
+        ["git", "status", "--porcelain", "--", *relpaths],
+    ...<3 lines>...
+        timeout=300,
+    )
+  File "C:\Users\黄文军\AppData\Local\Programs\Python\Python313\Lib\subprocess.py", line 554, in run
+    with Popen(*popenargs, **kwargs) as process:
+         ~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "C:\Users\黄文军\AppData\Local\Programs\Python\Python313\Lib\subprocess.py", line 1039, in __init__
+    self._execute_child(args, executable, preexec_fn, close_fds,
+    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                        pass_fds, cwd, env,
+                        ^^^^^^^^^^^^^^^^^^^
+    ...<5 lines>...
+                        gid, gids, uid, umask,
+                        ^^^^^^^^^^^^^^^^^^^^^^
+                        start_new_session, process_group)
+                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "C:\Users\黄文军\AppData\Local\Programs\Python\Python313\Lib\subprocess.py", line 1554, in _execute_child
+    hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
+                       ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
+                             # no special security
+                             ^^^^^^^^^^^^^^^^^^^^^
+    ...<4 lines>...
+                             cwd,
+                             ^^^^
+                             startupinfo)
+                             ^^^^^^^^^^^^
+FileNotFoundError: [WinError 2] 系统找不到指定的文件。

tests/test_verify_diagnostics.py

@@ -0,0 +1,122 @@
+import contextlib
+import datetime as dt
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from tools import verify_diagnostics
+
+
+class VerifyDiagnosticsTest(unittest.TestCase):
+    def make_report(self, overrides=None, module_overrides=None):
+        tempdir = tempfile.TemporaryDirectory()
+        root = Path(tempdir.name)
+        diagnostic = root / "diagnostic"
+        diagnostic.mkdir()
+        commit = "abcdef12"
+        logd = diagnostic / f"build-{commit}.logd"
+        logd.write_bytes(b"DIAG fake encrypted archive")
+
+        module = {
+            "name": "frailbox",
+            "status": "PASS",
+            "elapsed_seconds": 1.25,
+            "artifact": None,
+            "output": "ok",
+        }
+        if module_overrides:
+            module.update(module_overrides)
+
+        report = {
+            "generated_at": dt.datetime.now(dt.timezone.utc).isoformat(),
+            "commit": commit,
+            "diagnostic_logd": f"diagnostic/build-{commit}.logd",
+            "diagnostic_logd_error": None,
+            "chunked": False,
+            "chunk_size_bytes": None,
+            "password": "secret",
+            "decrypt_command": f"encryptly unpack diagnostic/build-{commit}.logd <outdir> --password secret",
+            "total_modules": 1,
+            "passed": 1 if module["status"] == "PASS" else 0,
+            "failed": 1 if module["status"] == "FAIL" else 0,
+            "modules": [module],
+            "pr_note": "Include diagnostics in the PR.",
+        }
+        if overrides:
+            report.update(overrides)
+
+        report_path = diagnostic / f"build-{commit}.json"
+        report_path.write_text(json.dumps(report), encoding="utf-8")
+        self.addCleanup(tempdir.cleanup)
+        return report_path
+
+    def test_valid_report_passes(self):
+        report_path = self.make_report()
+
+        result = verify_diagnostics.validate_report(report_path)
+
+        self.assertTrue(result.ok)
+        self.assertEqual(result.passed, 1)
+        self.assertEqual(result.failed, 0)
+        self.assertEqual(result.errors, [])
+
+    def test_missing_required_field_is_structural_error(self):
+        report_path = self.make_report(overrides={"modules": []})
+        data = json.loads(report_path.read_text(encoding="utf-8"))
+        del data["generated_at"]
+        report_path.write_text(json.dumps(data), encoding="utf-8")
+
+        result = verify_diagnostics.validate_report(report_path)
+
+        self.assertFalse(result.ok)
+        self.assertIn("Missing required field: generated_at", result.errors)
+        self.assertIn("Field 'total_modules' is 1, but modules contains 0 entries", result.errors)
+
+    def test_threshold_can_fail_validation(self):
+        report_path = self.make_report()
+
+        result = verify_diagnostics.validate_report(report_path, threshold=2)
+
+        self.assertFalse(result.ok)
+        self.assertIn("Passing modules 1 is below threshold 2", result.errors)
+
+    def test_boolean_counts_are_rejected(self):
+        report_path = self.make_report()
+        data = json.loads(report_path.read_text(encoding="utf-8"))
+        data["total_modules"] = True
+        report_path.write_text(json.dumps(data), encoding="utf-8")
+
+        result = verify_diagnostics.validate_report(report_path)
+
+        self.assertFalse(result.ok)
+        self.assertIn("Field 'total_modules' must be int, got bool", result.errors)
+
+    def test_json_cli_output(self):
+        report_path = self.make_report()
+        stdout = io.StringIO()
+
+        with contextlib.redirect_stdout(stdout):
+            exit_code = verify_diagnostics.main(["--json", str(report_path)])
+
+        payload = json.loads(stdout.getvalue())
+        self.assertEqual(exit_code, 0)
+        self.assertTrue(payload["ok"])
+        self.assertEqual(payload["passed"], 1)
+        self.assertEqual(payload["errors"], [])
+
+    def test_run_command_reports_subprocess_failure(self):
+        with mock.patch(
+            "tools.verify_diagnostics.subprocess.run",
+            side_effect=FileNotFoundError("missing"),
+        ):
+            result = verify_diagnostics.run_command(["git", "status"])
+
+        self.assertFalse(result.ok)
+        self.assertIn("executable not found", result.error)
+
+
+if __name__ == "__main__":
+    unittest.main()