Installation Script & Upgrade MCP Tool (#7)

[dcodesdev]

Summary

This PR introduces compiled binary distribution for Neptune CLI and an automatic update system, making installation easier for users.

Key Changes

Installation

• One-line installers for all platforms (macOS/Linux/Windows)
• No Python or uv dependency required
• Binaries available for: Linux (amd64/arm64), macOS (Intel/Apple Silicon), Windows (amd64)

Auto-Update System

• Automatic update checks every 24 hours (silent, non-intrusive)
• neptune upgrade command for manual updates
• Self-replacing binary upgrade mechanism
• Update checks can be disabled via NEPTUNE_SKIP_UPDATE_CHECK=1

Build Infrastructure

• GitHub Actions workflow for multi-platform binary builds
• PyInstaller-based compilation with optimized dependencies
• Automated release process on version tags
• Release testing workflow to verify installers work correctly

Developer Tools

• scripts/build.sh for local binary builds
• scripts/bump_version.py for version management
• Simplified versioning workflow (auto-updates pyproject.toml and creates git tags)

Installation

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/shuttle-hq/neptune-cli-python/main/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/shuttle-hq/neptune-cli-python/main/install.ps1 | iex

Testing

All platform installers are automatically tested on each release via the test-releases.yml workflow.

Breaking Changes

None - existing Python-based installations continue to work unchanged.

[the-wondersmith]

So all told, there isn't anything overtly crazy here, but I really don't love that it looks like we're hand-rolling a lot of this (specifically the semver handling and in-place binary updating machinery).

Are we hand-rolling all of this stuff because there's legitimately no pre-existing option that's a better fit? Or are we doing this for the sake of expediency?

I'm ok with dropping an approval, but I'd like to at least get an answer to the above "on record" so to speak.

[the-wondersmith]

Just out of curiosity, why is Windows unsupported on arm64?

[dcodesdev]

Because GitHub doesn't provide a GitHub actions runner for it. We'll need a self hosted runner for that.

[the-wondersmith]

Does the windows tooling not include a cross-compiler? I'd swear one was included in the visual studio tooling the last several times I've had to futz with it.

[dcodesdev]

This is more like a PyInstaller issue, you'll need to be on the same target as your code compiles to. A self hosted GHA runner sounds like our best bet.

[dcodesdev]

@the-wondersmith Mostly for speed and iteration. The current version works (tested on all platforms) and gets us unblocked now.

Regarding your comment about in-place binary upgrades, I actually didn't look into alternatives, wrote what works and tested across platforms. Happy to revisit if someone finds a better solution.

For semver, using a library is definitely a good solution, but wanted to avoid the overhead right now. Every new dependency requires manually updating neptune.spec for PyInstaller, and misconfiguring imports leads to runtime errors, since we don't have automated testing at the moment, all MCP tools need to be manually tested. The simple implementation we have sidesteps that complexity for our basic versioning needs.

Current approach is the best fit given where we are. Can always refactor later with more breathing room.