Skip to content

Add native Windows installer and documentation - #678

Open
nsxdavid wants to merge 5 commits into
justrach:release/0.2.5829from
nsxdavid:docs/windows-native-install
Open

Add native Windows installer and documentation#678
nsxdavid wants to merge 5 commits into
justrach:release/0.2.5829from
nsxdavid:docs/windows-native-install

Conversation

@nsxdavid

Copy link
Copy Markdown
Contributor

Closes #677

Summary

  • add a native Windows PowerShell installer for the published x86_64 release binary
  • require SHA256 verification before installing the downloaded executable
  • support safe installation, reinstallation, and rollback when a new binary cannot execute
  • correct the Bash installer's Windows routing so it stops before entering the Linux/macOS download path
  • align the README, MCP documentation, npm documentation, and website with shipped native Windows support

Why

codedb already publishes codedb-windows-x86_64.exe, but its primary installation surfaces do not provide a consistent native Windows installation path.

If npm is the maintainer's preferred long-term distribution and update mechanism for Windows, this PowerShell installer is intended as an interim bootstrap path—not a replacement for proper npm publishing. It makes the already-published Windows binary easy to install safely now, without committing the project to PowerShell as its permanent Windows packaging strategy.

No MCP runtime behavior is changed.

Before

Under simulated MINGW Windows detection, the existing Bash installer:

  1. says codedb is Linux/macOS-only
  2. directs the user to WSL
  3. continues into the Linux/macOS download path
  4. fails when that download is blocked

Result:

Windows detected — codedb is a native Linux/macOS binary.
Run this inside WSL2 instead:
  wsl curl -fsSL https://codedb.codegraff.com/install.sh | bash
error: could not fetch latest version
exit=1

The reproduction replaced uname with MINGW/x86_64 results and replaced curl with a network-blocking stub.

After

The same reproduction against this branch:

  1. recognizes the published native Windows x86_64 binary
  2. prints the native PowerShell installation command
  3. stops before entering the Linux/macOS download path
  4. exits successfully
Windows detected — codedb has a native Windows x86_64 binary.
This Bash installer is for macOS/Linux. Run this in PowerShell:
  irm https://raw.githubusercontent.com/justrach/codedb/main/install/install.ps1 | iex
Use WSL2 only if you want the Linux binary inside WSL.
exit=0

Validation

Native Windows validation:

  • Windows PowerShell 5.1.26100.8737: installer parse passed
  • PowerShell 7.5.8: installer parse passed
  • Windows PowerShell 5.1 downloaded release 0.2.5830
  • codedb-windows-x86_64.exe matched its published SHA256 checksum
  • installed executable returned codedb 0.2.5830
  • clean installation with PATH modification disabled passed
  • update while codedb.exe remained running passed
  • simulated post-install smoke failure restored the previous executable byte-for-byte
  • exact irm ... | iex pipeline shape was validated against the checked-out installer
  • native Windows MCP E2E passed 20/20 scenarios
  • locally packed codedeebee 0.2.5830 installed and launched the Windows binary

Neighboring checks:

  • canonical Bash syntax passed for:
    • install/install.sh
    • website/app/install_script.sh
    • website/dist/install.sh
  • simulated Windows dispatch passed for all three copies
  • the network-blocking stub confirmed that corrected Windows dispatch does not attempt a Linux/macOS download
  • git diff --check passed

Scope and repository state

  • target: release/0.2.5829
  • base commit: b6b4f7f
  • changed files: 12
  • changed lines: 399
  • MCP runtime changes: none
  • lockfile changes: none
  • benchmark changes: none
  • local build artifacts: none

Tracked website deployment outputs changed:

  • website/dist/install.sh
  • website/dist/privacy.html
  • website/dist/quickstart.html

These are updated alongside their corresponding website sources. No .zig-cache, zig-out, benchmark logs, or native build outputs are included.

CI note

The fork's bench-regression workflow currently fails before building repository code because its pinned Zig archive URL returns HTTP 404:

zig-x86_64-linux-0.17.0-dev.813+2153f8143.tar.xz
curl: (22) The requested URL returned error: 404

The PR base guard accepts release/0.2.5829, and the branch is mergeable.

Contributing checklist

  • Linked to an issue
  • Tightly scoped to native Windows installation and install-facing documentation
  • Exact failing behavior recorded
  • Corrected rerun recorded
  • Neighboring non-regression checks recorded
  • Generated deployment outputs disclosed
  • No unrelated lockfile, benchmark, or build-artifact churn
  • Submission follows CONTRIBUTING.md; the release target follows the repository's active PR base guard

justrach added a commit that referenced this pull request Jul 30, 2026
…tinel fix

Merges nsxdavid's install/install.ps1 (verbatim) plus its Windows docs, on
top of 6387fe3 which already fixed #677 a different way.

Conflict resolution in the three tracked copies of the bash installer
(install/, website/app/, website/dist/ — kept byte-identical):

- detect_platform keeps our "windows" sentinel. The PR's `{ ...; } >&2;
  return 10` variant works, but the sentinel is the narrower fix: the
  function still only ever reports a platform, and main() owns all user
  output and control flow.
- main()'s windows branch keeps the sentinel check and adopts the PR's
  better guidance — the native PowerShell one-liner first, WSL2 demoted to
  the alternative. The one-liner points at raw.githubusercontent.com as the
  PR wrote it; codedb.codegraff.com has no /install.ps1 route.
- All of #658 survives: the no-hooks marker, the hooks-registered receipt,
  pretooluse_entry_present(), the gated block-legacy script write, and the
  README hook opt-out paragraph.

Docs take the PR's Windows coverage with the stale claims corrected:

- npm: the launcher already resolves codedb-windows-x86_64.exe, but the
  published codedeebee predates that release asset, so `npx -y codedeebee
  mcp` is documented as arriving with the next published release rather
  than as working today. Dropped the named 0.2.5830 target.
- Removed the pointer to issue #501 (closed).

Verified: bash -n clean on all three copies; stubbed MINGW uname + a curl
that prints NETWORK-TOUCHED and exits 7 — all three exit 0, print the ps1
guidance, and never reach curl; darwin-arm64 still detects normally;
zig build test green. pwsh unavailable locally, so install.ps1 rides on the
PR's recorded 5.1 + 7.5 parse checks.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TD448QW4vLZ2UqPic6gR5a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant