vlt: package the vlt package manager from npm (BSD-2-Clause-Patent) - #564

vlt 1.0.1 (vltpkg/vltpkg) shipped today. Seeded with pkgmgr import npm vlt, then refined by hand for the two things discovery mode can't know.

Why this one is unusually clean

The published tarball has zero dependencies. npm ci against the committed lockfile installs exactly one package, pinned by version + integrity — no transitive tree, no native addons, no compile step. npm audit in-build reports 0 vulnerabilities across the whole 2-package graph. For a distro whose premise is supply-chain tracking, that is about as good as an npm-distributed tool gets.

License is BSD-2-Clause-Patent (OSI-approved), confirmed against the repo's own LICENSE, not just the npm field.

What I changed on top of the generated files

Bins enumerated, not globbed. The importer emits bins = { glob = "usr/bin/*" }, which trips the enumerate bins checker for any package with a handful of bins — vlt has five (vlt, plus the documented shorthands vlr/vlx and their variants). The npm registry metadata lists them exactly, so nothing had to be inferred. Fixing that in the importer is pkgmgr-rs follow-up work, not a one-off.

Real standalone tests. The generated package had none — and standalone tests...Pass is what the checker reports for a package with zero tests, so the out-of-the-box green meant nothing. Added three that exercise the artifact rather than the build inputs:

Mutation-tested, because "the tests pass" was already established as meaningless here: flipping the expected version to 0.0.0-mutant turns the suite red with version_is_exact ... had exit code 1. They can fail for the reason they exist.

Why a registry artifact and not a source build

AGENTS.md requires a prebuilt fallback be called out explicitly. The reason here is not "nobody tried" — source is published (codeload.../vltpkg/tar.gz/refs/tags/v1.0.1, 200, 7.4 MB, 48 real TypeScript workspaces). It cannot be built with a toolchain we have. Measured against the extracted tarball:

npm  -> npm error code EUNSUPPORTEDPROTOCOL
        Unsupported URL Type "catalog:": catalog:
pnpm -> ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC
        No catalog entry '@eslint/js' was found for catalog 'default'

• The only lockfile in the repo is vlt-lock.json — vlt's own format. No pnpm-lock.yaml, no package-lock.json.
• Dependency specs use the catalog: protocol with the catalog declared in vlt.json. pnpm does support catalogs, but reads pnpm-workspace.yaml.
• package.json has no workspaces key at all, so neither tool can even see the 48-workspace layout.
• Upstream CI agrees: uses: vltpkg/setup-vlt@v1 then vlt install.
• The published package (infra/cli/package.json) declares bin: null, dependencies: {}, and one script — prepack: vlt-build-prepack. The npm tarball is generated wholesale by their internal bundler.

Building vlt from source requires vlt — a genuine bootstrap cycle, which is the "required toolchain genuinely isn't packaged yet" case AGENTS.md carves out. Breaking it would mean a two-stage vlt-bootstrap → vlt pair in the gawk-bootstrap shape. Worth doing if vlt becomes load-bearing; not before.

Verification

Built and checked on the min-native path against a clean-main worktree:

min session activate . --loadout pkgbuild --name vltfinal
min session attach vltfinal --command "min package build --rebuild --verbose vlt"
min session attach vltfinal --command "min check --packages vlt"

npm ci → added 1 package, and audited 2 packages in 300ms, found 0 vulnerabilities; then 15/15 Pass, check finished.

Not verified

• Reproducibility. AGENTS.md wants byte-identical rebuilds. npm ci from a pinned lockfile ought to be deterministic and there is no compiler involved, but I did not measure it — min materialize is not in the session --command allowlist, so getting the tree back to the host for a two-build hash comparison needs an interactive attach. Flagging rather than assuming.
• arm64. Built on this host's arch only. Pure JS with no native addons, so arch-independence is expected, not demonstrated.

Reviewer notes

No TODO:/FIXME remain. The importer's generated TODO ("add any peer packages the tool needs") is resolved, not dropped: vlt declares no dependencies, peerDependencies, optionalDependencies, or bundleDependencies.

Note on the sibling project

vltpkg/vsr (the registry) is not packageable on the same terms — it is FSL-1.1-MIT (source-available, competing-use restricted; converts to MIT on 2028-02-04), and it is a Cloudflare Workers app built via wrangler deploy. Details in the thread that prompted this.