feat!: publish-target plugin system (npm / jsr / pypi / vscode-marketplace / open-vsx)

[theoephraim]

What

Packages can now publish to multiple targets at once. Each target is an instance of a plugin implementing one interface (src/core/targets/); built-ins: npm, jsr, pypi, vscode-marketplace, open-vsx, github-release-assets, docker, homebrew, and custom (shell-command escape hatch).

// .bumpy/_config.json
{
  "publish": { "provenance": true },                                    // defaults for every npm-type instance
  "targets": {
    "ghp": { "type": "npm", "registry": "https://npm.pkg.github.com" } // named reusable instance
  },
  "packages": {
    "my-lib": { "publishTargets": ["npm", "ghp", "jsr"] },
    "my-extension": { "publishTargets": ["vscode-marketplace", "open-vsx"] },
    "my-py-tool": { "publishTargets": ["pypi"] } // stub package.json + pyproject.toml
  }
}

Breaking (major bump): publishCommand / checkPublished / skipNpmPublish are removed — bumpy fails with the migration when it sees them. Root targets entries no longer inherit from each other. A package's own package.json may only reference targets by name.

State model

Three sources of "is this version out", with fixed precedence:

1. The registry (each target's checkPublished) — truth whenever it can answer. Asked before every publish, so a lost draft never causes a duplicate publish, and how a staged target is promoted once approved.
2. Release metadata — memory for what the registry can't tell us: which targets already succeeded (skip), are staged (re-check), or failed (retry). Stale keys from removed targets are pruned so they can't block finalization.
3. The git tag name@version — how packages with no queryable target are tracked.

The tag marks the commit artifacts shipped from: it follows HEAD across failed attempts and freezes the first time anything ships (success or staged). The draft is finalized once every target is live. The pipeline only publishes; tagging/finalizing is orchestrated from its outcomes in one place.

Design highlights

• Per-target resume: npm succeeded + Open VSX failed → the retry re-runs only Open VSX.
• Per-target ordering: a dependency failing on target T blocks dependents on T only (recorded as failed, retried next run) — app@jsr never goes out referencing a lib@jsr that didn't land.
• Staged publishing (npmStaged): publish() may report { status: 'staged', ref }. The target is recorded 🟡 staged with the npm stage id, the draft stays a draft (no dead link, no premature release: published), and the next publish run sees it live and finalizes. Snapshots never stage. Generic — any registry with an approval queue fits the same hook. (feat: mark staged publishes as staged in GH release + publish finalize #147's publish finalize command becomes a thin wrapper over this reconciliation.)
• Two phases around the GitHub release: release-phase targets constitute it (npm, marketplaces, github-release-assets) — the draft is held until they're done, then published. post-release-phase targets consume it and run only once it's public, because a draft's assets aren't downloadable (a Homebrew formula's urls, a Dockerfile's curl of the tarball). homebrew/docker default to post-release; any target can set "phase". A package whose release-phase targets didn't all succeed holds its post-release targets for the next run. This is the split varlock's release.yaml does by hand today with release-binaries → release-docker jobs.
• CLI distribution: github-release-assets (uploads to the draft, so release: published fires only once binaries are attached), docker (buildx --push, :version + :latest + dist-tag), homebrew (formula template with {{sha256 <asset>}}, committed + tagged + pushed to the tap; token via env, never argv).
• Shared artifacts: targets declaring the same artifact kind share one build — a single .vsix uploads to both marketplaces, byte-identical.
• Publish-time version sync (prepare()): jsr.json / pyproject.toml versions sync from package.json at publish time — commit them as 0.0.0 and forget them. JSR identity comes from jsr.json's name (JSR scopes are a separate namespace).
• Capabilities: marketplaces (no prereleases), JSR/PyPI (no snapshots) record skipped; a package none of whose targets can take a release kind is dropped from the plan before any draft is opened.
• Private packages with targets are managed: "private": true only means "not npm". A private package that declares publishTargets (an extension, a PyPI stub, a CLI shipped as release assets) is versioned and published regardless of privatePackages.version. (Surfaced by the testbed: none of its private packages were being planned.)
• Registry probes are bounded: every CLI-based checkPublished (npm info, docker manifest inspect, gh release view, gh api, vsce/ovsx) runs with a timeout and reports "unknown" on expiry, so a credential helper waiting for a prompt can't hang a release. (Surfaced by the testbed: docker manifest inspect blocked on the local credential helper.)
• Trust model: nothing from a package's package.json executes or steers a publish — only name references. buildCommand and inline target definitions there require allowCustomCommands. The root config is trusted.

End-to-end testbed

dmno-dev/bumpy-testbed (scaffolded alongside this PR) cuts a real patch release of one package per target shape on every run — npm+JSR, npm staged, TestPyPI, a CLI through release-assets → homebrew → docker, and a real vsce package — then verifies from the outside (registries, published release with assets, formula version + sha256, docker run, brew install on macOS). Nightly against @varlock/bumpy@next; a failure-injection mode asserts the held-draft/post-release behavior. Two bumpy bugs above came out of running its config through this branch's dry-run.

Validated against real setups

• varlock: the vscode extension's script chain collapses to two targets (incl. azureCredential: true) and gains per-registry retry.
• mirrordown: four hand-rolled publish scripts covered by built-ins; config collapses to ["npm", "jsr"].

Credits

JSR publishing behavior is modeled on Drake Costa's setup in mirrordown — thanks Drake! 🙏

Test plan

• 494 tests (phases: resolver defaults/overrides, release-vs-post-release passes, completion gating; resolver/trust-gate/migration errors, multi-target pipeline incl. per-target retry, per-target blocking, staged re-check + promotion, registry guards for marketplaces/JSR/PyPI, shared artifacts, preflight per distinct instance, release-assets/docker/homebrew incl. a real local tap push)
• Tests are now hermetic w.r.t. the developer's git config (test/setup.ts preload: no signing/hooks/identity from ~/.gitconfig). Fixing that surfaced a Bun quirk worth knowing: children spawned without an explicit env get the process's initial environment, so withReleaseToken()-style process.env mutations never reached gh/git under Bun — every spawn in utils/shell.ts now passes env: process.env explicitly.
• Not yet done: a live end-to-end publish — first real validation will be a varlock release after migrating its config.

[github-actions]

The changes in this PR will be included in the next version bump.

Minor releases

• @varlock/bumpy 1.18.1 → 1.19.0

Bump files in this PR

• publish-targets.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.