fix(install): pin OpenShell to 0.0.21, upgrade on mismatch

[ericksoa]

Summary

• Adds openshellVersion: "0.0.21" to package.json as single source of truth for the required OpenShell CLI version
• install-openshell.sh now reads OPENSHELL_PIN_VERSION env var to download that exact tagged release (not latest) and treats it as the minimum required version
• onboard.js compares the installed OpenShell version against the pin and triggers an upgrade when below — previously it only checked binary presence

Test plan

• npm test passes (new tests for versionGte and install script pin awareness)
• Fresh install on machine without OpenShell installs v0.0.21 specifically
• Upgrade from OpenShell 0.0.20 triggers upgrade to 0.0.21
• Machine with OpenShell 0.0.21+ skips install
• Standalone install-openshell.sh (no env var) still downloads latest and uses 0.0.7 floor

Fixes NVBug 6044568

Summary by CodeRabbit

• New Features

  • Added OpenShell version pinning support, allowing the system to pin and enforce a specific version (0.0.21) during installation and upgrades.
  • Enhanced installation logic to detect installed OpenShell version and automatically upgrade if the current version falls below the required pinned version.

• Tests

  • Added unit tests for version comparison and pinned release download verification.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2a3a6667-4a28-4f5e-922d-e4297254433c

📥 Commits

Reviewing files that changed from the base of the PR and between b1bb01c and b403a0b.

📒 Files selected for processing (5)

• bin/lib/onboard.js
• package.json
• scripts/install-openshell.sh
• test/onboard.test.js
• test/runner.test.js

---

📝 Walkthrough

Walkthrough

This change implements OpenShell version pinning. A new versionGte() helper compares semantic versions, while package.json stores the pinned version (0.0.21). The onboarding script reads this version and passes it to the installer via environment variable. The install script now conditionally downloads specific pinned releases or falls back to latest based on the pinned version.

Changes

Cohort / File(s)	Summary
Core OpenShell Pinning bin/lib/onboard.js, package.json, scripts/install-openshell.sh	Added versionGte() semver comparison helper to onboard.js. Updated onboard.js to read openshellVersion from package.json and pass it to installer via OPENSHELL_PIN_VERSION env var. Modified install script to use pinned version for conditional GitHub release/curl downloads instead of fixed minimum version.
Test Coverage test/onboard.test.js, test/runner.test.js	Added unit test for versionGte() with multiple semver comparison assertions. Added regression test verifying install script contains pinned version variable handling and correct GitHub/curl download patterns.

Sequence Diagram

sequenceDiagram
    participant PkgJson as package.json
    participant Onboard as bin/lib/onboard.js
    participant InstallScript as scripts/install-openshell.sh
    participant GitHub as GitHub Releases
    
    Onboard->>PkgJson: Read openshellVersion
    PkgJson-->>Onboard: "0.0.21"
    Onboard->>Onboard: Call getInstalledOpenshellVersion()
    Onboard->>Onboard: versionGte(installed, pinned)?
    alt Version too low or missing
        Onboard->>InstallScript: spawnSync with OPENSHELL_PIN_VERSION=0.0.21
        InstallScript->>GitHub: gh release download --tag v0.0.21
        GitHub-->>InstallScript: Release artifact
        InstallScript-->>Onboard: Installation complete
    else Version sufficient
        Onboard-->>Onboard: Skip installation
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A version we pin, a path now more clear,
OpenShell's release, we hold it quite dear,
From package to script, the numbers align,
Comparing semver with logic so fine,
No more guessing games—our shell stays defined! 🎯

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: pinning OpenShell to version 0.0.21 and implementing upgrade-on-mismatch logic.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/pin-openshell-version

---

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

[ericksoa]

No longer relev