fix(install): fail fast on missing binutils at preflight (#4415)

[latenighthackathon]

Summary

Adds an early preflight check so the installer fails fast with an actionable message when binutils (the strings binary) is missing, instead of running for several minutes and then aborting at the final OpenShell verification step.

Problem

scripts/install-openshell.sh uses strings (from binutils) in openshell_has_required_messaging_features to confirm the OpenShell CLI binary carries the credential-rewrite endpoints. That check only runs during OpenShell install/verification, which happens late in the installer. On a clean host without binutils the installer therefore ran for around five minutes (Node.js install, repo clone, npm install, tsc build, OpenShell download and checksum) before aborting with 'strings' is required to verify OpenShell messaging credential rewrite support. All of that work was discarded, and the installer could only complete after binutils was installed and the run repeated. Reported on a clean Ubuntu 24.04 host in #4415.

Changes

• Add ensure_openshell_build_deps and call it in main() immediately after ensure_docker, before any clone, build, or download work.
• When strings is absent the check exits with a single actionable line pointing at sudo apt-get install -y binutils.
• Skip the check when NEMOCLAW_DEFER_OPENSHELL_INSTALL=1, because that flag postpones all OpenShell work to a later phase where install-openshell.sh runs the same strings check itself, so the pre-upgrade backup flow is unaffected.
• Mirror the existing ensure_docker and ensure_supported_runtime detect-and-fail-fast preflight pattern rather than auto-installing a system package.

Related Issue

Closes #4415

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Ran: full test/install-preflight.test.ts suite passes (101/101), including two new cases - the installer fails fast with the binutils guidance and never reaches the OpenShell install or clone when strings is missing, and the preflight stays silent under NEMOCLAW_DEFER_OPENSHELL_INSTALL=1; bash -n scripts/install.sh clean; shellcheck passes via the pre-push hook.

---

Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com

Summary by CodeRabbit

Release Notes

• New Features
  • The installer now validates required build tools upfront before beginning the setup process. When dependencies are unavailable, the installation process stops early with clear remediation guidance, preventing wasted time and failed builds. This validation check can be deferred via environment variable configuration if needed for specific workflows or custom environments.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds an early-stage preflight check that detects missing strings binary (from binutils) before any OpenShell download or build work, failing fast with apt-get remediation guidance instead of waiting ~5 minutes for the verification step to fail.

Changes

Build dependency preflight enforcement

Layer / File(s)	Summary
Preflight check implementation scripts/install.sh	New ensure_openshell_build_deps() function validates strings availability and integrates into main() immediately after third-party preflight, before other host setup steps. Check is skipped when NEMOCLAW_DEFER_OPENSHELL_INSTALL=1.
Preflight runtime tests test/install-preflight.test.ts	Helpers construct isolated system PATH (simulating missing binaries) and Docker/systemctl stubs to focus test scope. Test suite verifies early exit with remediation output when strings is missing, and confirms the preflight is skipped when OpenShell installation is deferred.

Sequence Diagram

sequenceDiagram
    participant Installer as Installer main()
    participant Preflight as ensure_openshell_build_deps()
    participant Shell as Shell (which strings)
    
    Installer->>Preflight: Call after third-party preflight
    Preflight->>Shell: Check strings availability
    alt strings found
        Shell-->>Preflight: success
        Preflight-->>Installer: continue to other setup
    else strings not found
        Shell-->>Preflight: not found
        Preflight-->>Installer: exit 1 with apt-get hint
    end

Loading

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested Labels

Getting Started, fix

Suggested Reviewers

• ericksoa

Poem

🐰 A rabbit hops through install logs with glee,
Catching missing strings before they steal the spree—
Five minutes saved by checking early today,
No more false builds to throw away! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding an early preflight check for missing binutils that causes the installer to fail fast.
Linked Issues check	✅ Passed	The PR fully addresses the linked issue #4415 by implementing early preflight detection of missing binutils/strings before any download/build work.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing the preflight check requirement from issue #4415; no unrelated modifications are present.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[wscurran]

✨ Thanks for submitting this detailed PR about adding an early preflight check for missing binutils. This proposes a code change to fail fast with an actionable message when binutils is missing, instead of running for several minutes and then aborting at the final OpenShell verification step.

---

Related open issues:

• #4415 [Ubuntu 24.04][Install] missing binutils not detected at preflight; OpenShell verification fails ~5 min into install