Description

NPM installation of @beads/bd fails on Windows 10 with a file locking error during the postinstall script. The downloaded ZIP archive cannot be extracted because it's still locked by the Node.js process that downloaded it.

Environment

• OS: Windows 10 x64 (Build 19045)
• Node.js: v24.13.0
• npm: v11.6.2
• Package: @beads/bd@0.49.6
• PowerShell: Windows PowerShell 5.1
• Execution Policy: RemoteSigned (CurrentUser)

Steps to Reproduce

npm install -g @beads/bd

Expected Behavior

The package should install successfully with the bd.exe binary available in the global npm bin directory.

Actual Behavior

Installation fails during the postinstall script with the following error:

New-Object : Exception calling ".ctor" with "3" argument(s): "The process cannot access the file 
'C:\Users\virtu\AppData\Roaming\npm\node_modules\@beads\bd\bin\beads_0.49.6_windows_amd64.zip' because it is being 
used by another process."
At 
C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\Microsoft.PowerShell.Archive\Microsoft.PowerShell.Archive.psm1:931 
char:30

The installation process:

1. ✅ Successfully downloads the ZIP archive
2. ❌ Fails to extract it because the file is locked
3. ❌ Binary not found after extraction

Full Error Log

Root Cause

This is a race condition specific to Windows file locking behavior:

1. The postinstall script downloads the ZIP file and closes it
2. Windows keeps the file handle locked for a few milliseconds after closing
3. The PowerShell Expand-Archive command tries to open the file immediately
4. The file is still locked → extraction fails

Linux/macOS don't exhibit this issue because their file systems release locks immediately.

Proposed Solution

Add a small delay between downloading and extracting the archive in scripts/postinstall.js:

// After writing the file
await fs.promises.writeFile(zipPath, buffer);

// Add delay for Windows file lock release
if (process.platform === 'win32') {
  await new Promise(resolve => setTimeout(resolve, 2000)); // 2 seconds
}

// Then extract
await extractArchive(zipPath, binDir);

Alternatively, use Node.js built-in extraction instead of spawning PowerShell:

// Use node's extract-zip or adm-zip instead of PowerShell
const extract = require('extract-zip');
await extract(zipPath, { dir: binDir });

Workaround (for users)

Users can work around this issue by installing without postinstall and manually extracting:

# Install without running postinstall
npm install -g @beads/bd --ignore-scripts

# Manually download and extract with delay
$url = "https://github.com/steveyegge/beads/releases/download/v0.49.6/beads_0.49.6_windows_amd64.zip"
Invoke-WebRequest -Uri $url -OutFile "$env:TEMP\beads.zip"
Start-Sleep -Seconds 3  # Wait for file lock release
Expand-Archive "$env:TEMP\beads.zip" -DestinationPath "$env:APPDATA\npm\node_modules\@beads\bd\bin" -Force

Additional Context

• This is not a PowerShell configuration issue - ExecutionPolicy is correctly set to RemoteSigned
• This is not an antivirus issue - same error occurs with Windows Defender disabled
• This is not a permissions issue - same error occurs when running as Administrator
• The Microsoft.PowerShell.Archive module loads and works correctly when tested independently

This appears to be a timing issue that only manifests when the download and extraction happen in rapid succession within the same Node.js process.

Related Issues

Similar file locking issues in other npm packages:

• stream: removed outdated TODO nodejs/node#31701
• https://stackoverflow.com/questions/54150085/cannot-access-file-because-it-is-being-used-by-another-process

Impact

This affects all Windows users trying to install via npm, which is the recommended installation method according to the documentation. Manual installation workarounds defeat the purpose of package manager integration.

Suggested Priority

High - Blocks standard installation path for a major OS platform (Windows 10/11 users).