Check required local tools for Ballast rules using PATH detection plus Homebrew install guidance

[markcallen]

Summary

Add a way for Ballast to check whether the local tools required by installed Ballast rules are available, using a combination of:

• checking whether each tool is already available on the user’s current PATH
• providing Homebrew-based install requirements and remediation guidance when tools are missing

Problem

Ballast installs rules and guidance that may depend on local tools being present, but there is not yet a clear, centralized check for whether those tools are actually installed on the user’s machine.

That leads to a poor setup experience:

• rules may reference tools that are not installed yet
• users only discover missing prerequisites when a command fails later
• install guidance may be scattered across docs instead of surfaced in one place
• the project does not have a clear contract for which tools are expected for a selected Ballast setup

Goal

Define and implement prerequisite checking for tools needed by Ballast-installed rules so users can quickly see:

• which tools are required
• which tools are already available on PATH
• which tools are missing
• how to install missing tools with Homebrew where appropriate

Proposed approach

Use a hybrid detection model:

• detect installed tools by checking whether the executable is present on the user’s current PATH
• maintain a mapping of Ballast-required tools to Homebrew package names or casks when Homebrew is the preferred install path
• report missing tools with actionable install instructions

This can likely extend existing ballast doctor behavior, but the exact CLI surface can be determined during implementation.

Scope

The work should determine:

• which tools are required for the Ballast rules to function well
• which of those tools are mandatory vs optional
• how tool requirements vary by selected language, target, or agent set
• how to encode Homebrew install information for each tool
• how to handle tools that do not have a Homebrew package or where Homebrew should not be the default recommendation

Requirements

The solution should:

• check tool availability using command -v, equivalent PATH lookup logic, or the platform-appropriate equivalent already used in the codebase
• map known required tools to Homebrew install commands when possible
• distinguish between already-installed tools and missing tools
• provide clear remediation steps for missing tools
• avoid failing hard when optional tools are absent
• keep secrets and environment-specific values out of the configuration

Candidate examples

Depending on selected features, relevant tools may include items such as:

• pnpm
• uv
• go
• node
• python
• ruff
• other rule-specific CLIs that Ballast guidance expects users to have installed

The implementation should determine the real list from Ballast-managed targets, agents, languages, and related docs or metadata rather than hardcoding an ad hoc list without rationale.

Acceptance criteria

• Ballast can identify tools required for the active project or selected rule set.
• Tool presence is checked against the user’s current PATH.
• Missing tools are reported clearly.
• Homebrew installation guidance is provided for tools that Ballast expects users to install via Homebrew.
• The system distinguishes between required and optional tools where appropriate.
• The resulting output is practical for onboarding and troubleshooting.
• Documentation explains how tool requirements are determined and how users should remediate missing tools.

Notes

A good implementation may end up as:

• an enhancement to ballast doctor
• a dedicated prerequisite-check command
• or shared prerequisite logic used by install and doctor flows

The important part is that Ballast can verify the local toolchain expected by its rules and give users concrete next steps when something is missing.