fix(npm): use native tar for Windows extraction, with PowerShell fallback

[greynewell]

Picks up #131 with additional fixes and tests.

Changes:

• Try Windows-native tar first to extract the downloaded zip — avoids Antivirus file-lock crashes on Expand-Archive
• Fall back to PowerShell Expand-Archive with a 10-attempt retry loop if tar fails
• try/finally guarantees tmpDir is cleaned up even if copyFileSync throws
• Move all side-effectful module-level code inside require.main guard so require('./install') no longer triggers a download
• Extract extractZip() as a testable function with injectable execFn
• Add 6 node:test tests covering: tar path, PowerShell fallback, retry loop structure, path interpolation, and cleanup

Closes #131

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Enhanced Windows installation reliability with a fallback retry mechanism to mitigate transient file-lock issues during extraction.

• Tests

  • Added test suite validating extraction behavior across different scenarios and execution paths.

• Chores

  • Updated build configuration with new test script.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

The installation script now executes only when invoked directly (preventing side effects on import), and introduces a new extractZip helper that attempts Windows archive extraction via native tar first, then falls back to PowerShell with retry logic to mitigate transient file-lock issues. Comprehensive tests validate both extraction paths.

Changes

Cohort / File(s)	Summary
Installation Workflow npm/install.js	Guarded execution to prevent side effects on import; added extractZip helper that tries native tar -xf, falls back to PowerShell Expand-Archive with retry loop for file-lock resilience; accepts optional execFn for testing.
Test Suite npm/install.test.js	New test file using Node's built-in test runner; validates extractZip behavior across tar success, tar failure + PowerShell fallback, and retry logic (including $RetryCount and Start-Sleep assertions).
Configuration npm/package.json	Added test script entry to run the test suite via node --test install.test.js.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🏃‍♂️ Tar to the rescue, swift and sleek,
PowerShell waiting, backup technique,
Retries dancing, no locks shall stand,
Windows Defender meets its match, so grand! ⚡

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: switching to native tar for Windows extraction with PowerShell as a fallback, which directly addresses the primary objective of fixing the Expand-Archive Windows Defender lock bug.
Description check	✅ Passed	The description covers all required template sections with clear changes, motivation (Closes #131), and mentions test coverage, though the test plan checklist items lack explicit check marks.
Linked Issues check	✅ Passed	All coding objectives from issue #131 are met: native tar replaces Expand-Archive [#131], PowerShell fallback with retry logic is implemented [#131], tmpDir cleanup is guaranteed [#131], module side effects are guarded [#131], and extractZip is testable [#131].
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the Windows extraction issue: extractZip implementation, extraction logic changes, test suite for the new function, and test script addition. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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/windows-tar-extraction

---

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