docs: document macOS test command-line dependencies

[VishnuR23]

Summary

npx vitest run --project cli fails on a macOS host that does not provide the GNU timeout utility. src/lib/shields/state-dir-lock.test.ts spawns timeout, the spawn fails, the result carries no stdout, and parseGuardOutput reports TypeError: Cannot read properties of undefined (reading 'split'). Before this change, CONTRIBUTING.md listed no command-line tool prerequisite, and the error named neither the missing utility nor macOS. After this change, the testing section names the required tools, gives the brew and PATH commands, and points to the workflow that owns the list.

Related Issue

None.

Changes

• Add a macOS Test Dependencies subsection to the testing section of CONTRIBUTING.md.
• Name the failing test, the spawned utility, and the reported error.
• Give the brew install and PATH commands that the macos-vitest job already runs.
• Record that the macos-vitest job runs on a push to main and on manual dispatch, so a pull request does not report a macOS-only failure.

This PR adds no abstraction, configuration, fallback, migration, or compatibility path. It changes no source file and no workflow.

Reproduction and Verification

On macOS 26 arm64 with no GNU timeout on PATH:

npx vitest run --project cli src/lib/shields/state-dir-lock.test.ts
 FAIL  src/lib/shields/state-dir-lock.test.ts > hands the manifest plan to an injected startup helper (#8006)
TypeError: Cannot read properties of undefined (reading 'split')
 ❯ parseGuardOutput src/lib/shields/state-dir-lock.ts:160:36

I confirmed the cause by putting a timeout stand-in first on PATH and running the same command again:

 Test Files  1 passed (1)
      Tests  15 passed (15)

.github/workflows/platform-vitest-main.yaml installs bash coreutils fd gawk ripgrep, adds the Bash bin directory and the coreutils and gawk gnubin directories to PATH, and prints timeout --version in its environment step. The macOS lane therefore passes while a contributor host without those utilities fails.

This PR documents the command-line tools rather than changing the test, because the macos-vitest job already resolves the same gap by installing them. Tell me if you would prefer the test to skip or to report the missing utility instead, and I will implement that.

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)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification: The change adds prose and one shell sample to CONTRIBUTING.md. It changes no source file, script, workflow, command, or default.
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: CONTRIBUTING.md; the Homebrew Bash, coreutils, and gawk path order matches the macOS workflow. Markdown lint passed, the focused state-directory lock file passed 15 tests, and the documentation build completed with 0 errors and 2 existing Fern warnings.
• Agent: Codex Desktop

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Tests are marked not applicable above. markdownlint-cli2, gitleaks, and commitlint passed in pre-commit and commit-msg. The pre-push TypeScript checks passed. The focused state-directory lock file passed all 15 tests after one confirmed transient host-timing failure was safely rerun.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• 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)

Notes on the unchecked verification items:

• Broad gate: CONTRIBUTING.md states that a doc-only change does not need the full test suite, so I did not run npm test or npm run check.
• npm run docs: I ran it. It reports Found 0 errors and 2 warnings. I left the item unchecked because the command does not build without warnings. This PR changes no file under docs/, so both warnings exist on main independently of this change.
• Doc-page items: this PR changes CONTRIBUTING.md at the repository root. It adds no page under docs/, so the Fern page style and new-page frontmatter items do not apply.

---

Signed-off-by: Vishnu Rajeev 19866703+VishnuR23@users.noreply.github.com

Summary by CodeRabbit

• Documentation
  • Added macOS-specific guidance for installing required command-line tools.
  • Documented how to configure the system PATH for local testing.
  • Identified the macOS test workflow as the authoritative dependency reference.

[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]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The contribution guide adds macOS test setup instructions. It covers GNU utility installation, PATH configuration, and the macos-vitest workflow as the dependency reference.

Changes

macOS test setup

Layer / File(s)	Summary
Document macOS test dependencies CONTRIBUTING.md	Adds instructions for the missing timeout utility, Homebrew installation of GNU utilities, PATH configuration, and the macos-vitest workflow.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation change for macOS GNU utilities used by the test suite.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@CONTRIBUTING.md`:
- Around line 274-275: Update the Homebrew PATH setup in the installation
instructions to prepend $(brew --prefix bash)/bin, matching the macos-vitest
workflow while preserving the existing coreutils and gawk paths.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d8bda046-a33a-4ed4-b70d-c19a54bf2d60

📥 Commits

Reviewing files that changed from the base of the PR and between 04e28aa and c2cb06b.

📒 Files selected for processing (1)

• CONTRIBUTING.md

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections match; severity counts match.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — macOS test dependencies at CONTRIBUTING.md:265: Keep `macOS test dependencies` for the workflow dependency group.
• established — command-line tools at CONTRIBUTING.md:267: Keep `command-line tools` for executable test prerequisites.
• justified — authoritative list at CONTRIBUTING.md:282: Keep `authoritative list`; the workflow link names the owner of the package list.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[VishnuR23]

Applied the CodeRabbit finding in d01a844. The macos-vitest job prepends $(brew --prefix bash)/bin alongside the two gnubin directories, and the sample now matches. The finding was correct: the sample installed Homebrew bash and then left the macOS system bash first on PATH.

[apurvvkumaria]

Maintainer readiness update

This branch revision is technically prepared: the requested Homebrew Bash path is present, the documentation writer review is recorded, the docs build reports 0 errors with only the 2 warnings already present on main, contributor compliance passes, and the only review thread is resolved.

The deterministic repository gate remains fail-closed because the secondary PR Review Advisor lane failed again during analysis after one safe rerun. The trusted publisher reports no blocking findings from the primary advisor, but the failed lane and provenance check prevent approval and merge. No bypass or merge was attempted. This PR remains open pending normal advisor automation recovery.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[apurvvkumaria]

Security review for the latest PR commit: PASS

The effective change adds 21 lines to CONTRIBUTING.md. It does not change source code, workflows, dependency manifests, or runtime configuration.

• Trust boundaries and input validation: no runtime input or parser changes.
• Authentication, authorization, and tenant isolation: no changes.
• Secrets, privacy, and logging: no data path changes; the command sample contains no credentials.
• Command and shell injection: the sample uses fixed Homebrew package names, trusted brew --prefix output, and the contributor's existing PATH.
• Filesystem safety and path traversal: no runtime file operations.
• Network access and SSRF: no changes.
• Cryptography and verification: no changes.
• Dependencies and supply chain: the text documents the package list already owned by the trusted macOS workflow; it does not alter that workflow or any dependency lockfile.
• Availability, concurrency, and resource limits: no changes.

Validation passed: Markdown lint, the five macOS workflow contract tests, the documentation build with 0 errors and 2 existing warnings, and all applicable pre-commit checks. GitHub reports every PR commit as Verified, and the DCO declarations are preserved.

The earlier Nemotron review-advisor failure was advisor infrastructure, not a documentation failure. Its artifact showed that the model emitted text before the required terminology-tool result. The artifact had already verified the documentation claims and reported no security findings. The updated branch is running a new advisor review.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@CONTRIBUTING.md`:
- Around line 274-278: Update the installation instruction in the CONTRIBUTING
guide to use precise terminology: either rename “GNU utilities” to “GNU
utilities and other command-line tools” or separate the Homebrew packages into
their respective categories, while preserving the installation and PATH-ordering
guidance.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 43e7b1e3-23ab-41a1-b027-be4cc46ebc68

📥 Commits

Reviewing files that changed from the base of the PR and between 08cc324 and 0f2b66f.

📒 Files selected for processing (1)

• CONTRIBUTING.md

[apurvvkumaria]

Final review update for the latest PR commit

• The automated terminology finding is addressed. The guide now calls the complete package list “command-line tools” and names only the bash, coreutils, and gawk package directories that the PATH command prepends.
• Markdown lint passed with 0 errors. All five macOS workflow contract tests passed. The documentation build completed with 0 errors and the 2 existing warnings. The complete repository hook set passed.
• The nine-category security result remains PASS because the final changes affect only contributor documentation. No source code, workflow, dependency, credential, network, filesystem, or runtime behavior changed.
• GitHub reports every PR commit as Verified, and the contributor attribution and DCO declarations remain intact.

The earlier Nemotron advisor failure was review infrastructure. The model emitted text before the required terminology-tool result completed. The preserved analysis reported all nine security categories as passing and recorded no findings. A new advisor run is evaluating the corrected branch.

[prekshivyas]

Reviewed latest PR commit 64b234b09; no substantive documentation finding.

The Homebrew package list and PATH order match the macOS workflow, including Homebrew Bash before coreutils/gawk gnubin, and the text accurately limits the workflow to pushes to main and manual dispatch. No runtime or security surface changes.

No approval because base 9257fe0f6 is behind current main, required checks are absent, and the Nemotron advisor check remains red.

[prekshivyas]

Reviewed the current head and found no documentation correctness or style issue. I am withholding approval because this branch does not contain current main; refresh the branch and rerun the required checks so approval can bind to the integrated exact head.