zx-bulk-release 2.21.1 → 3.0.1

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [3.0.1](https://github.com/semrel-extra/zx-bulk-release/compare/v3.0.0...v3.0.1) (2026-04-11)
+
+### Fixes & improvements
+* docs: add v2 > v3 migration guide ([18f68fa](https://github.com/semrel-extra/zx-bulk-release/commit/18f68fa62d700ae48f0f2da19b42bf91b23b5d14))
+
+## [3.0.0](https://github.com/semrel-extra/zx-bulk-release/compare/v2.21.1...v3.0.0) (2026-04-11)
+
+### Fixes & improvements
+* refactor: enhance courier inners ([0a75468](https://github.com/semrel-extra/zx-bulk-release/commit/0a75468a1736291d194e307c8fef39cbaae55948))
+* refactor: use `parcels` as default artifacts dir ([b1c589e](https://github.com/semrel-extra/zx-bulk-release/commit/b1c589edfcdfba2c548c09f35950b058e6cc2f8c))
+* refactor: simplify parcel contracts ([0a93948](https://github.com/semrel-extra/zx-bulk-release/commit/0a93948b2b4013ad3a620bcf93cf468651c0380b))
+* refactor: move git-tag phase to depot ([a736ead](https://github.com/semrel-extra/zx-bulk-release/commit/a736ead83a75014f4bf592b9b60d5a5073bb4381))
+* refactor: extract pack step from publish ([213a286](https://github.com/semrel-extra/zx-bulk-release/commit/213a28603ccfd3a9deed0d48652bca2864e17ef9))
+* refactor: lift api/ to post/ level as shared ([bc51e2c](https://github.com/semrel-extra/zx-bulk-release/commit/bc51e2c8e9517261de5107a7b67680018f8fe71d))
+* refactor: extract courier module with sealed directive ([20617d8](https://github.com/semrel-extra/zx-bulk-release/commit/20617d83f87b0409963b178b8a34fd11ad22df33))
+
+### BREAKING CHANGES
+* - --recover flag removed. Use --deliver <dir> to re-deliver pre-packed tars. ([c45ab47](https://github.com/semrel-extra/zx-bulk-release/commit/c45ab47a853a887f45abe6a0fa27eade0f71c4dc))
+
+### Features
+* feat: seal delivery flow — tar containers, template credentials ([2ba819a](https://github.com/semrel-extra/zx-bulk-release/commit/2ba819aef7e2d74f55db6bd6fc05f6589ddbc700))
+
 ## [2.21.1](https://github.com/semrel-extra/zx-bulk-release/compare/v2.21.0...v2.21.1) (2026-04-11)
 
 ### Fixes & improvements

package/README.md

@@ -14,10 +14,15 @@
 * Pkg changelogs go to `changelog` branch (configurable).
 * Docs are published to `gh-pages` branch (configurable).
 * No extra builds. The required deps are fetched from the pkg registry (`npmFetch` config opt).
+* **Two-phase pipeline**: build and delivery can run as separate jobs with isolated credentials.
+
+
+> [!NOTE]
+> **[Migration guide v2 → v3](./MIGRATION_V2_V3.md)**
 
 ## Roadmap
 * [x] Store release metrics to `meta`.
-* [ ] ~~Self-repair. Restore broken/missing metadata from external registries (npm, pypi, m2)~~. Tags should be the only source of truth
+* [x] Two-phase pipeline (pack / deliver).
 * [ ] Multistack. Add support for java/kt/py.
 * [ ] Semaphore. Let several release agents to serve the monorepo at the same time.
 
@@ -25,7 +30,6 @@
 * macOS / linux
 * Node.js >= 16.0.0
 * npm >=7 / yarn >= 3
-* ~~wget~~
 * tar
 * git
 
@@ -38,21 +42,56 @@ yarn add zx-bulk-release
 ```shell
 GH_TOKEN=ghtoken GH_USER=username NPM_TOKEN=npmtoken npx zx-bulk-release [opts]
 ```
-| Flag                         | Description                                                                                                               | Default          |
-|------------------------------|---------------------------------------------------------------------------------------------------------------------------|------------------|
-| `--ignore`                   | Packages to ignore: `a, b`                                                                                                |                  |
-| `--include-private`          | Include `private` packages                                                                                                | `false`          |
-| `--concurrency`              | `build/publish` threads limit                                                                                             | `os.cpus.length` |
-| `--no-build`                 | Skip `buildCmd` invoke                                                                                                    |                  |
-| `--no-test`                  | Disable `testCmd` run                                                                                                     |                  |
-| `--no-npm-fetch`             | Disable npm artifacts fetching                                                                                            |                  |                      
-| `--only-workspace-deps`      | Recognize only `workspace:` deps as graph edges                                                                           |                  |
-| `--dry-run` / `--no-publish` | Disable any publish logic                                                                                                 |                  |
-| `--report`                   | Persist release state to file                                                                                             |                  |
-| `--snapshot`                 | Disable any publishing steps except of `npm` and `publishCmd` (if defined), then  push packages to the `snapshot` channel |                  |  
-| `--recover`                  | Remove orphan git tags (tag exists but npm publish failed) and exit. Re-run without this flag to release.                  |                  |
-| `--debug`                    | Enable [zx](https://github.com/google/zx#verbose) verbose mode                                                            |                  |
-| `--version` / `-v`           | Print own version                                                                                                         |                  |
+| Flag                         | Description                                                                                       | Default          |
+|------------------------------|---------------------------------------------------------------------------------------------------|------------------|
+| `--pack [dir]`               | Pack only: build, test, and write delivery tars to `dir`. No credentials needed.                  | `parcels`        |
+| `--deliver [dir]`            | Deliver only: read tars from `dir` and run delivery channels. No source code needed.              | `parcels`        |
+| `--ignore`                   | Packages to ignore: `a, b`                                                                        |                  |
+| `--include-private`          | Include `private` packages                                                                        | `false`          |
+| `--concurrency`              | `build/publish` threads limit                                                                     | `os.cpus.length` |
+| `--no-build`                 | Skip `buildCmd` invoke                                                                            |                  |
+| `--no-test`                  | Disable `testCmd` run                                                                             |                  |
+| `--no-npm-fetch`             | Disable npm artifacts fetching                                                                    |                  |
+| `--only-workspace-deps`      | Recognize only `workspace:` deps as graph edges                                                   |                  |
+| `--dry-run` / `--no-publish` | Disable any publish logic                                                                         |                  |
+| `--report`                   | Persist release state to file                                                                     |                  |
+| `--snapshot`                 | Publish only to `npm` snapshot channel and run `publishCmd` (if defined), skip everything else    |                  |
+| `--debug`                    | Enable [zx](https://github.com/google/zx#verbose) verbose mode                                    |                  |
+| `--version` / `-v`           | Print own version                                                                                 |                  |
+
+### Two-phase pipeline
+By default, zbr runs the full pipeline in a single process. For better security isolation, split build and delivery into separate CI jobs:
+
+```yaml
+# Job 1: build (minimal privileges — source code access only)
+jobs:
+  pack:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: npx zx-bulk-release --pack
+      - uses: actions/upload-artifact@v4
+        with: { name: parcels, path: parcels, retention-days: 1 }
+
+# Job 2: deliver (only delivery credentials, no source code)
+  deliver:
+    needs: pack
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: parcels, path: parcels }
+      - run: npx zx-bulk-release --deliver
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - uses: actions/upload-artifact@v4
+        with: { name: parcels, path: parcels, overwrite: true, retention-days: 1 }
+```
+
+After delivery, each tar is replaced with a marker (`released` or `skip`). The final `upload-artifact` syncs these markers back to CI storage, so a re-run of the deliver job will skip already-delivered parcels. Artifacts expire naturally via retention policy.
+
+**Recovery** is simply re-running the deliver job. Only undelivered tars (not yet replaced with markers) will be processed. No rebuild required.
 
 ### JS API
 ```js
@@ -153,7 +192,7 @@ The `--snapshot` flag publishes packages to the `snapshot` npm dist-tag with a p
 **What snapshot does differently:**
 - Version gets a `-snap.<short-sha>` suffix instead of a clean bump
 - Git release tags are **not** pushed
-- Only `npm` and `publishCmd` publishers run (no gh-release, no changelog, no gh-pages, no meta)
+- Only `npm` and `publishCmd` channels run (no gh-release, no changelog, no gh-pages, no meta)
 - npm tag is `snapshot` instead of `latest`
 
 **Workflow example** (`.github/workflows/snapshot.yml`):
@@ -204,10 +243,22 @@ See [antongolub/misc](https://github.com/antongolub/misc) for a real-world examp
 * [antongolub/misc](https://github.com/antongolub/misc)
 
 ## Implementation notes
+### Architecture
+The release pipeline is split into three subsystems under `post/`:
+
+```
+post/
+  depot/     — preparation: analysis, versioning, building, testing, tar packing
+  courier/   — sealed delivery: receives self-describing tars and delivers through channels
+  api/       — shared infrastructure wrappers (git, npm, gh)
+```
+
+This separation ensures that courier never touches the project directory — it works only with pre-packed tars and credentials resolved at delivery time. The two subsystems can run in separate CI jobs with different privilege levels.
+
 ### Flow
 ```
-topo ─► contextify ─► analyze ──► build ──► test ──► publish ─► clean
-         (per pkg)    (per pkg)   (per pkg)  (per pkg) (per pkg)
+topo ─► contextify ─► analyze ──► build ──► test ──► pack ──► publish ─► clean
+         (per pkg)    (per pkg)   (per pkg)  (per pkg) (per pkg) (per pkg)
 ```
 [`@semrel-extra/topo`](https://github.com/semrel-extra/topo) resolves the release queue respecting dependency graphs. The graph allows parallel execution where the dependency tree permits; `memoizeBy` prevents duplicate work when a package is reached by multiple paths.
 
@@ -219,7 +270,8 @@ Each step has a uniform signature `(pkg, ctx)`:
 - **`analyze`** — determines semantic changes, release type, and next version.
 - **`build`** — runs `buildCmd` (with dep traversal and optional npm artifact fetch).
 - **`test`** — runs `testCmd`.
-- **`publish`** — orchestrates the publisher registry: prepare (serial) → run (parallel) → rollback on failure.
+- **`pack`** — stages delivery artifacts into self-describing tar containers (`npm pack`, docs copy, assets, release notes). Each tar is named `{tag}.{channel}.{hash8}.tar` and contains a `manifest.json` with channel name, delivery instructions, and template credentials (`${{ENV_VAR}}`). After this step, everything the courier needs is outside the project dir.
+- **`publish`** — pushes the release tag (commitment point), hands tars to courier's `deliver()`, runs `cmd` channel separately.
 - **`clean`** — restores `package.json` files and unsets git user config.
 
 Set `config.releaseRules` to override the default rules preset:
@@ -231,19 +283,39 @@ Set `config.releaseRules` to override the default rules preset:
 ]
 ```
 
-### Publishers
-Publish targets are a registry of `{name, when, prepare?, run, undo?, snapshot?}` objects:
+### Tar containers
+Each delivery artifact is a self-describing tar archive:
+```
+{tag}.{channel}.{hash8}.tar
+  manifest.json    — channel name, delivery params, template credentials
+  package.tgz     — (npm channel) npm tarball
+  assets/          — (gh-release channel) release assets
+  docs/            — (gh-pages channel) documentation files
+```
+
+The manifest contains `${{ENV_VAR}}` placeholders that are resolved by the courier at delivery time via `resolveManifest()`. This ensures credentials never touch the build phase.
+
+### Channels
+Delivery channels are a registry of `{name, when, prepare?, run, requires?, snapshot?, transport?}` objects:
 - **meta** — pushes release metadata to the `meta` branch (or as a GH release asset).
 - **npm** — publishes to the npm registry.
 - **gh-release** — creates a GitHub release with optional file assets.
 - **gh-pages** — pushes docs to a `gh-pages` branch.
 - **changelog** — pushes a changelog entry to a `changelog` branch.
-- **cmd** — runs a custom `publishCmd`.
+- **cmd** — runs a custom `publishCmd` (depot-side, not through courier; `transport: false`).
 
-Teardown walks the registry in reverse, calling `undo()` on each publisher for rollback/recovery.
+Each channel declares `requires` — a list of manifest fields that must be present after credential resolution. Courier validates all parcels before running any channel (fail-fast).
+
+### Credential flow
+```
+depot (build phase)                          courier (deliver phase)
+  manifest: { token: '${{NPM_TOKEN}}' }  →    resolveManifest(manifest, env)
+                                                 → { token: 'actual-secret' }
+```
+Template credentials (`${{ENV_VAR}}`) are written into manifests at pack time. Courier resolves them from `process.env` at delivery time. This means the build phase never sees real secrets.
 
 ### Tags
-[Lerna](https://github.com/lerna/lerna) tags (like `@pkg/name@v1.0.0-beta.0`) are suitable for monorepos, but they don’t follow [semver spec](https://semver.org/). Therefore, we propose another contract:
+[Lerna](https://github.com/lerna/lerna) tags (like `@pkg/name@v1.0.0-beta.0`) are suitable for monorepos, but they don't follow [semver spec](https://semver.org/). Therefore, we propose another contract:
 ```js
 '2022.6.13-optional-org.pkg-name.v1.0.0-beta.1+sha.1-f0'
 // date    name                  version             format

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zx-bulk-release",
   "alias": "bulk-release",
-  "version": "2.21.1",
+  "version": "3.0.1",
   "description": "zx-based alternative for multi-semantic-release",
   "type": "module",
   "exports": {

package/src/main/js/index.js

@@ -1 +1 @@
-export {run} from './processor/release.js'
+export {run} from './post/release.js'

package/src/main/js/{processor → post}/api/gh.js

@@ -40,15 +40,6 @@ export const ghCreateRelease = async ({ghApiUrl, ghToken, repoName, tag, body})
   return res
 }
 
-// https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#delete-a-release
-export const ghDeleteReleaseByTag = async ({ghApiUrl, ghToken, repoName, tag}) => {
-  const res = await attempt2(() => ghFetch(`${ghApiUrl}/repos/${repoName}/releases/tags/${tag}`, {ghToken}))
-  if (!res.ok) return false
-  const {id} = await res.json()
-  await attempt2(() => ghFetch(`${ghApiUrl}/repos/${repoName}/releases/${id}`, {ghToken, method: 'DELETE'}))
-  return true
-}
-
 // https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28#upload-a-release-asset
 export const ghPrepareAssets = async (assets, _cwd) => {
   const temp = tempy.temporaryDirectory()
@@ -83,24 +74,6 @@ export const ghPrepareAssets = async (assets, _cwd) => {
   return temp
 }
 
-export const ghUploadAssets = async ({ghToken, ghAssets, uploadUrl, cwd}) => {
-  const temp = await ghPrepareAssets(ghAssets, cwd)
-
-  return Promise.all(ghAssets.map(async ({name}) => {
-    const url = `${uploadUrl}?name=${name}`
-    const res = await ghFetch(url, {
-      ghToken,
-      method: 'POST',
-      headers: {'Content-Type': 'application/octet-stream'},
-      body: await fs.readFile(path.join(temp, name)),
-    })
-    if (!res.ok) {
-      throw new Error(`gh asset upload failed for '${name}': ${res.status}`)
-    }
-    return res
-  }))
-}
-
 export const ghGetAsset = async ({repoName, tag, name, ghUrl}) => {
   const url = `${ghUrl || 'https://github.com'}/${repoName}/releases/download/${tag.ref || tag}/${name}`
   const res = await attempt2(() => fetch(url))

package/src/main/js/{processor → post}/api/git.js

@@ -3,6 +3,7 @@ import {log} from '../log.js'
 import {attempt2, attempt3, memoizeBy} from '../../util.js'
 
 export const fetchRepo = memoizeBy(async ({cwd: _cwd, branch, origin: _origin, basicAuth}) => {
+  if (!_origin && !_cwd) throw new Error('fetchRepo requires either origin or cwd')
   const origin = _origin || (await getRepo(_cwd, {basicAuth})).repoAuthedUrl
   const cwd = tempy.temporaryDirectory()
   const _$ = $({cwd})
@@ -15,7 +16,7 @@ export const fetchRepo = memoizeBy(async ({cwd: _cwd, branch, origin: _origin, b
   }
 
   return cwd
-}, async ({cwd, branch}) => `${await getRoot(cwd)}:${branch}`)
+}, async ({cwd, branch, origin}) => origin ? `${origin}:${branch}` : `${await getRoot(cwd)}:${branch}`)
 
 export const pushCommit = async ({cwd, from, to, branch, origin, msg, ignoreFiles, files = [], basicAuth, gitCommitterEmail, gitCommitterName}) => {
   const _cwd = await fetchRepo({cwd, branch, origin, basicAuth})
@@ -106,15 +107,6 @@ export const pushTag = async ({cwd, tag, gitCommitterName, gitCommitterEmail}) =
     git push origin ${tag}`
 }
 
-export const fetchTags = async (cwd) =>
-  $({cwd})`git fetch --tags`
-
-export const deleteRemoteTag = async ({cwd, tag}) => {
-  log.info(`rolling back remote tag '${tag}'`)
-  await $({cwd, nothrow: true})`git push origin :refs/tags/${tag}`
-  await $({cwd, nothrow: true})`git tag -d ${tag}`
-}
-
 // Memoize prevents .git/config lock
 // https://github.com/qiwi/packasso/actions/runs/4539987310/jobs/8000403413#step:7:282
 export const setUserConfig = memoizeBy(async(cwd, gitCommitterName, gitCommitterEmail) => $({cwd})`

package/src/main/js/{processor → post}/api/npm.js

@@ -77,7 +77,7 @@ export const npmRestore = async (pkg) => {
 }
 
 export const npmPublish = async (pkg) => {
-  const {absPath: cwd, name, version, manifest, config: {npmPublish, npmRegistry, npmToken, npmConfig, npmProvenance, npmOidc}} = pkg
+  const {name, version, manifest, config: {npmPublish, npmRegistry, npmToken, npmConfig, npmProvenance, npmOidc}} = pkg
 
   if (manifest.private || npmPublish === false) return
 
@@ -105,7 +105,9 @@ export const npmPublish = async (pkg) => {
     if (npmProvenance) npmFlags.push('--provenance')
   }
 
-  await $({cwd})`npm publish ${npmFlags.filter(Boolean)}`
+  // Publish from pre-built tarball (courier mode) or project dir (legacy).
+  const target = pkg.npmTarball || pkg.absPath
+  await $`npm publish ${target} ${npmFlags.filter(Boolean)}`
 }
 
 export const getNpmrc = memoizeBy(async ({npmConfig, npmToken, npmRegistry}) => {

package/src/main/js/post/courier/channels/changelog.js

@@ -0,0 +1,29 @@
+import {$} from 'zx-extra'
+import {queuefy} from 'queuefy'
+import {fetchRepo, pushCommit} from '../../api/git.js'
+import {log} from '../../log.js'
+
+const run = queuefy(async (manifest, dir) => {
+  const {releaseNotes, branch, file, msg, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
+
+  log.info('push changelog')
+
+  const _cwd = await fetchRepo({branch, origin: repoAuthedUrl, basicAuth: ghBasicAuth})
+
+  await $({cwd: _cwd})`echo ${releaseNotes}"\n$(cat ./${file})" > ./${file}`
+  await pushCommit({
+    branch,
+    msg,
+    origin: repoAuthedUrl,
+    gitCommitterEmail,
+    gitCommitterName,
+    basicAuth: ghBasicAuth,
+  })
+})
+
+export default {
+  name: 'changelog',
+  requires: ['repoAuthedUrl'],
+  when: (pkg) => !!pkg.config.changelog,
+  run,
+}

package/src/main/js/{processor/publishers → post/courier/channels}/cmd.js

@@ -3,4 +3,5 @@ export default {
   when: (pkg) => !!(pkg.ctx?.flags?.publishCmd ?? pkg.config.publishCmd),
   run:  (pkg, exec) => exec(pkg, 'publishCmd'),
   snapshot: true,
+  transport: false,
 }

package/src/main/js/post/courier/channels/gh-pages.js

@@ -0,0 +1,30 @@
+import {path} from 'zx-extra'
+import {queuefy} from 'queuefy'
+import {log} from '../../log.js'
+import {pushCommit} from '../../api/git.js'
+
+const run = queuefy(async (manifest, dir) => {
+  const {branch, to, msg, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
+  const docsDir = path.join(dir, 'docs')
+
+  log.info(`publish docs to ${branch}`)
+
+  await pushCommit({
+    cwd: docsDir,
+    from: '.',
+    to,
+    branch,
+    origin: repoAuthedUrl,
+    msg,
+    gitCommitterEmail,
+    gitCommitterName,
+    basicAuth: ghBasicAuth,
+  })
+})
+
+export default {
+  name: 'gh-pages',
+  requires: ['repoAuthedUrl'],
+  when: (pkg) => !!pkg.config.ghPages,
+  run,
+}

package/src/main/js/post/courier/channels/gh-release.js

@@ -0,0 +1,35 @@
+import {fs, path} from 'zx-extra'
+import {log} from '../../log.js'
+import {ghCreateRelease, ghFetch} from '../../api/gh.js'
+
+const run = async (manifest, dir) => {
+  const {tag, token, apiUrl, repoName, releaseNotes, assets} = manifest
+  if (!token) return null
+
+  log.info('create gh release')
+  const now = Date.now()
+
+  const res = await ghCreateRelease({ghApiUrl: apiUrl, ghToken: token, repoName, tag, body: releaseNotes})
+
+  if (assets?.length) {
+    const uploadUrl = res.upload_url.slice(0, res.upload_url.indexOf('{'))
+    const assetsDir = path.join(dir, 'assets')
+    if (await fs.pathExists(assetsDir)) {
+      await Promise.all(assets.map(async ({name}) => {
+        const url = `${uploadUrl}?name=${name}`
+        const body = await fs.readFile(path.join(assetsDir, name))
+        const r = await ghFetch(url, {ghToken: token, method: 'POST', headers: {'Content-Type': 'application/octet-stream'}, body})
+        if (!r.ok) throw new Error(`gh asset upload failed for '${name}': ${r.status}`)
+      }))
+    }
+  }
+
+  log.info(`duration gh release: ${Date.now() - now}`)
+}
+
+export default {
+  name: 'gh-release',
+  requires: ['token', 'repoName'],
+  when: (pkg) => !!pkg.config.ghToken,
+  run,
+}

package/src/main/js/post/courier/channels/meta.js

@@ -0,0 +1,34 @@
+import {queuefy} from 'queuefy'
+import {log} from '../../log.js'
+import {pushCommit} from '../../api/git.js'
+import {getArtifactPath, isAssetMode} from '../../depot/generators/meta.js'
+import {prepareMeta} from '../../depot/generators/meta.js'
+
+const pushMetaBranch = queuefy(async (manifest, dir) => {
+  const {name, version, tag, type, data: meta, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
+  if (type === null || isAssetMode(type)) return
+
+  log.info('push artifact to branch \'meta\'')
+
+  const msg = `chore: release meta ${name} ${version}`
+  const files = [{relpath: `${getArtifactPath(tag)}.json`, contents: meta}]
+
+  await pushCommit({
+    to: '.',
+    branch: 'meta',
+    msg,
+    files,
+    origin: repoAuthedUrl,
+    gitCommitterEmail,
+    gitCommitterName,
+    basicAuth: ghBasicAuth,
+  })
+})
+
+export default {
+  name: 'meta',
+  requires: ['repoAuthedUrl'],
+  when:    (pkg) => pkg.config.meta.type !== null,
+  prepare: prepareMeta,
+  run:     pushMetaBranch,
+}

package/src/main/js/post/courier/channels/npm.js

@@ -0,0 +1,26 @@
+import {path} from 'zx-extra'
+import {npmPublish} from '../../api/npm.js'
+
+export const isNpmPublished = (pkg) =>
+  !pkg.manifest.private && pkg.config.npmPublish !== false
+
+export default {
+  name:     'npm',
+  requires: ['token'],
+  when:     isNpmPublished,
+  run:      (manifest, dir) => npmPublish({
+    name: manifest.name,
+    version: manifest.version,
+    npmTarball: path.join(dir, 'package.tgz'),
+    preversion: manifest.preversion,
+    manifest: {},
+    config: {
+      npmRegistry: manifest.registry,
+      npmToken: manifest.token,
+      npmConfig: manifest.config,
+      npmProvenance: manifest.provenance,
+      npmOidc: manifest.oidc,
+    },
+  }),
+  snapshot: true,
+}

package/src/main/js/post/courier/index.js

@@ -0,0 +1,113 @@
+import {$, tempy, within, path, semver, fs} from 'zx-extra'
+import {unpackTar} from '../tar.js'
+import {log} from '../log.js'
+import meta from './channels/meta.js'
+import npm from './channels/npm.js'
+import ghRelease from './channels/gh-release.js'
+import ghPages from './channels/gh-pages.js'
+import changelog from './channels/changelog.js'
+import cmd from './channels/cmd.js'
+
+export {buildParcels} from './parcel.js'
+
+export const channels = {meta, npm, 'gh-release': ghRelease, 'gh-pages': ghPages, changelog, cmd}
+export const defaultOrder = ['meta', 'npm', 'gh-release', 'gh-pages', 'changelog', 'cmd']
+
+export const prepare = async (names, pkg) => {
+  for (const n of names) await channels[n]?.prepare?.(pkg)
+}
+
+export const runChannel = async (name, ...args) => channels[name]?.run(...args)
+
+export const resolveManifest = (manifest, env = process.env) => {
+  const resolved = {}
+  for (const [k, v] of Object.entries(manifest))
+    resolved[k] = typeof v === 'string' ? v.replace(/\$\{\{(\w+)\}\}/g, (_, n) => env[n] || '') : v
+
+  const {repoHost, repoName, originUrl} = resolved
+  const token = env.GH_TOKEN || env.GITHUB_TOKEN || ''
+  const user = env.GH_USER || env.GH_USERNAME || env.GITHUB_USER || env.GITHUB_USERNAME || 'x-access-token'
+
+  if (repoHost && repoName && token) {
+    resolved.repoAuthedUrl = `https://${user}:${token}@${repoHost}/${repoName}.git`
+    resolved.ghBasicAuth = `${user}:${token}`
+  } else if (originUrl) {
+    resolved.repoAuthedUrl = originUrl
+  }
+
+  return resolved
+}
+
+const openParcel = async (tarPath, env) => {
+  const content = await fs.readFile(tarPath, 'utf8').catch(() => null)
+  if (content === 'released' || content === 'skip') return null
+
+  const destDir = tempy.temporaryDirectory()
+  const {manifest} = await unpackTar(tarPath, destDir)
+  const resolved = resolveManifest(manifest, env)
+  const ch = channels[resolved.channel]
+
+  if (!ch) return {warn: `unknown channel '${resolved.channel || '<none>'}'`}
+
+  const missing = (ch.requires || []).filter(f => !resolved[f])
+  if (missing.length) return {warn: `missing credentials — ${missing.join(', ')}`, tarPath}
+
+  return {ch, resolved, destDir, tarPath}
+}
+
+const pool = async (tasks, concurrency, fn) => {
+  const active = new Set()
+  let i = 0
+  await new Promise((resolve, reject) => {
+    const next = () => {
+      if (i >= tasks.length && active.size === 0) return resolve()
+      while (active.size < concurrency && i < tasks.length) {
+        const t = tasks[i++]
+        const p = fn(t).then(() => { active.delete(p); next() }, reject)
+        active.add(p)
+      }
+    }
+    next()
+  })
+}
+
+// Parcels grouped by package, sorted by semver asc (latest last).
+// Groups run in parallel (concurrency-limited), entries within a group — sequential.
+export const deliver = async (tars, env = process.env, {concurrency = 4} = {}) => {
+  const groups = new Map()
+
+  for (const tarPath of tars) {
+    const fname = path.basename(tarPath)
+    try {
+      const p = await openParcel(tarPath, env)
+      if (!p) continue
+      if (p.warn) {
+        log.warn(`skipping ${fname}: ${p.warn}`)
+        if (p.tarPath) await fs.writeFile(tarPath, 'skip')
+        continue
+      }
+      const key = p.resolved.name || p.resolved.channel
+      if (!groups.has(key)) groups.set(key, [])
+      groups.get(key).push(p)
+    } catch (e) {
+      log.warn(`skipping ${fname}: ${e.message}`)
+    }
+  }
+
+  for (const g of groups.values())
+    g.sort((a, b) => semver.compare(a.resolved.version || '0.0.0', b.resolved.version || '0.0.0'))
+
+  let delivered = 0
+  await pool([...groups.values()], concurrency, async (group) => {
+    for (const {ch, resolved, destDir, tarPath} of group) {
+      await within(async () => {
+        $.scope = resolved.name || resolved.channel
+        await ch.run(resolved, destDir)
+      })
+      await fs.writeFile(tarPath, 'released')
+      delivered++
+    }
+  })
+
+  return delivered
+}