fix(packaging): avoid mandatory Bun in prebuilt installs

[benvinegar]

Summary

• stop copying the mandatory bun dependency into staged prebuilt hunkdiff packages
• retain standalone platform binaries as the primary zero-prerequisite runtime and leave the legacy npm Bun fallback unchanged
• add an opt-in Firecracker compatibility suite for npm, pnpm, upgrades, fallback behavior, offline execution, curl failures, and the historical pnpm/Bun corruption
• add fast pack/install guards, a manual-only KVM workflow, and release guidance requiring a passed VM result

Problem

hunkdiff@0.20.1 installs Bun as a mandatory dependency even though its platform packages already contain standalone executables. Bun's postinstall can move its platform executable out of pnpm 11's shared global virtual-store projection. A later global update then encounters the missing @oven/bun-* executable, as reported in #866.

The mandatory dependency came from the prebuilt staging script copying the root development dependency set into the published meta-package.

Approach

Prebuilt staging now filters only bun from runtime dependencies. The source checkout keeps Bun for development and compilation, while published installations continue to select hunkdiff-<platform> without requiring users to install Bun separately. Pack and smoke checks fail if mandatory Bun or @oven/bun-* packages return.

The new test/cli/install-vm/ harness is entirely opt-in. It lazily prepares checksum-pinned Firecracker assets, publishes synthetic Hunk versions through a local Verdaccio registry, and runs fourteen scenarios in fresh sparse/reflinked Linux x64 guests. It emits JSON, JUnit, command logs, assertions, and observations while excluding writable disks, keys, sockets, credentials, and cache identities from uploaded results.

The workflow is manual-only because it runs privilege-bearing KVM infrastructure. Normal checkout, dependency installation, tests, typechecking, builds, and packing do not download VM assets or require Docker/KVM.

Closes #866.

Validation

• bun install --frozen-lockfile
• bun test ./test/cli/install-vm ./scripts/prebuilt-package-helpers.test.ts — 35 passed
• bun run test — all 2 shards passed, 7 skipped, 0 failed
• bun run typecheck
• bun run lint
• changed-path oxfmt --check
• bash -n and shellcheck -x across all install-VM shell scripts
• bun run deps:check
• bun run check:pack
• bun run check:docs
• bun run build:prebuilt:npm
• bun run check:prebuilt-pack
• bun run smoke:prebuilt-install
• bun run test:install-vm — 14 passed, 0 failed, 0 skipped on Linux x64 with KVM; explicit result validated against the full manifest and checkout identity

Coverage boundaries

Firecracker validates Linux x64 behavior only. It reproduces the shared pnpm projection mutation and Linux recovery, but not the reporter's final native macOS ARM64 command failure. Native macOS and Windows release jobs remain separate. Verdaccio may proxy uncached transitive dependencies, and the historical oracle intentionally uses pinned packages from the live npm registry.

This PR description was generated by Pi using gpt-5.6-sol

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored	Preview	Aug 30, 2026 12:16am

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	verdaccio@​6.10.1

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm json-schema is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: test/cli/install-vm/controller-deps/package-lock.json → npm/verdaccio@6.10.1 → npm/json-schema@0.4.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/json-schema@0.4.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm unix-crypt-td-js is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: test/cli/install-vm/controller-deps/package-lock.json → npm/verdaccio@6.10.1 → npm/unix-crypt-td-js@1.1.4 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/unix-crypt-td-js@1.1.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm validator is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: test/cli/install-vm/controller-deps/package-lock.json → npm/verdaccio@6.10.1 → npm/validator@13.15.26 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/validator@13.15.26. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[greptile-apps]

Greptile Summary

This PR removes Bun from staged prebuilt runtime dependencies and adds packaging guards plus an opt-in Firecracker compatibility harness.

• Filters Bun from the published meta-package while preserving the source checkout dependency.
• Adds pack and installed-command checks for Bun-free prebuilt installations.
• Introduces isolated VM scenarios, fixture preparation, structured results, a manual KVM workflow, and release guidance.
• The release-result check currently does not prove that a complete current run passed.

Confidence Score: 4/5

The release validation should be fixed before merging because it can accept a stale or partial Firecracker result as evidence that the full current suite passed.

The packaging change itself is guarded, but the newly documented release gate selects results by mtime and checks only a nonempty passing subset, so it does not enforce the stated full-suite, reviewed-tip requirement.

Files Needing Attention: skills/hunk-release/SKILL.md, test/cli/install-vm/runner.ts, test/cli/install-vm/results.ts

Important Files Changed

Filename	Overview
scripts/prebuilt-package-helpers.ts	Adds a focused non-mutating helper and assertion to remove mandatory Bun from staged prebuilt dependencies.
scripts/stage-prebuilt-npm.ts	Applies the Bun dependency filter while retaining other runtime and optional platform dependencies.
test/cli/install-vm/runner.ts	Coordinates locking, fixture preparation, Docker execution, and result aggregation, but failed runs may leave no current result for release selection.
test/cli/install-vm/results.ts	Strictly aggregates scenario artifacts and failures, though emitted run metadata does not identify the source checkout or full expected scenario set.
skills/hunk-release/SKILL.md	Adds required VM validation, but its result-selection command can accept stale or single-scenario passing output.
.github/workflows/install-vm.yml	Adds a manual-only, read-only-permission workflow with explicit skipped-result handling and filtered artifact upload.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Source[Source checkout] --> Build[Build prebuilt packages]
  Build --> Stage[Stage meta and platform packages]
  Stage --> Fixtures[Prepare synthetic registry fixtures]
  Fixtures --> Controller[Controller container]
  Controller --> VM[Fresh Firecracker guest]
  VM --> Scenarios[Install compatibility scenarios]
  Scenarios --> Results[result.json and JUnit]
  Results --> ReleaseGate[Manual release validation]

Loading

Prompt To Fix All With AI

### Issue 1
skills/hunk-release/SKILL.md:85-87
**Release gate accepts stale results**

When a selected scenario passes, or the current full-suite run fails before writing `result.json`, this command accepts a nonempty subset or selects an older passing result by mtime, allowing release validation to succeed without a complete passing run from the reviewed release tip.

### Issue 2
test/cli/install-vm/runner.ts:198-204
**Harness bypasses environment conventions**

The new harness reads `process.env` directly here and in fixture preparation, while several new fixture and lock helpers lack the required short TSDoc descriptions, bypassing the repository's environment-access and function-documentation conventions.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix(packaging): avoid mandatory Bun in p..." | Re-trigger Greptile}