fix: Windows install + config docs (closes #32, #34)#35
Merged
Conversation
Windows lacks the unzip command, so the postinstall extraction silently failed and stacklit.exe never landed in npm/bin/. Switch to Expand-Archive (ships with Windows 10+) for .zip on win32, surface extraction output via stdio inherit, and fail loudly when the binary is missing after extraction. Closes #32
The README and USAGE guide showed a TOML schema, but the loader in internal/config reads .stacklitrc.json. Update both docs to JSON so the example matches the file the tool actually loads. Closes #34
This was referenced May 6, 2026
thegdsks
added
bug
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the npm install experience on Windows by replacing the non-existent unzip dependency with a PowerShell-based extraction path, and aligns the public documentation with the actual configuration loader (which reads .stacklitrc.json).
Changes:
- Update
npm/install.jsto extract Windows.zipreleases via PowerShellExpand-Archive, surface install output, and error if the expected binary is missing after extraction. - Update
README.mdandUSAGE.mdto document.stacklitrc.json(JSON) configuration instead ofstacklit.toml(TOML).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| USAGE.md | Updates configuration documentation to .stacklitrc.json JSON schema and summarizes supported keys. |
| README.md | Updates the README configuration snippet and heading to .stacklitrc.json. |
| npm/install.js | Adjusts archive extraction to work on Windows without unzip, inherits stdio, and validates the extracted binary exists. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Address PR review feedback from Copilot: - Use execFileSync instead of execSync for all extraction commands so paths are passed as args, never interpolated into a shell string. The original PowerShell command wrapped paths in single quotes inside a double-quoted string, so a single quote in __dirname (e.g. C:\\Users\\O'Connor\\...) would have broken parsing or altered the command. - On Windows, hand the archive and bin paths to PowerShell via env vars ($env:STACKLIT_ARCHIVE / $env:STACKLIT_BINDIR) and use -LiteralPath so the script body has no string interpolation at all. - Move archive.tmp cleanup into a finally so a failed extraction doesn't leave the temp file behind. - Set process.exitCode = 1 in the top-level catch so npm postinstall reports a non-zero status when extraction fails or the binary is missing afterward. Download failures still return silently, matching the existing 'let the bin script show a helpful error' behavior.
The post-commit hook regenerated stacklit.json (new merkle hash and timestamp) when committing the npm fix. That regeneration is unrelated to this PR's scope, so revert it to keep the diff focused on npm/install.js.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this fixes
#32, Windows install is broken.
npm/install.jsshells out tounzipto extract the release zip, but Windows doesn't shipunzip. The download works, extraction fails silently, andstacklit.exenever makes it intonpm/bin/. The user then hits "stacklit binary not found" on first run because that's all the wrapper script knows how to say.This swaps in PowerShell's
Expand-Archiveon Windows (it's been there since Windows 10), routes install output throughstdio: 'inherit'so problems are visible duringnpm install, and throws if the binary is still missing after extraction. Failures are loud now instead of silent.#34, config docs were lying. The README and USAGE guide showed a TOML schema, but the loader in
internal/configreads.stacklitrc.json. Anyone following the docs was writing TOML the tool just ignored. Both docs now show the JSON example. No code change, since existing users were already on JSON.Test plan
go build ./...cleango test ./internal/config/passesnode --check npm/install.jspassesnpm install -g stacklitthenstacklit --versionCloses #32
Closes #34