zx-bulk-release 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [3.1.1](https://github.com/semrel-extra/zx-bulk-release/compare/v3.1.0...v3.1.1) (2026-04-12)
+
+### Fixes & improvements
+* perf: add `--help` ([99fcfde](https://github.com/semrel-extra/zx-bulk-release/commit/99fcfde332c7730e335e46b4c2a8c844d53f8986))
+* refactor: separate parcel subdomain ([b168044](https://github.com/semrel-extra/zx-bulk-release/commit/b16804497693b42998cea2638ff6d11bd29eb84f))
+
 ## [3.1.0](https://github.com/semrel-extra/zx-bulk-release/compare/v3.0.5...v3.1.0) (2026-04-12)
 
 ### Features

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "zx-bulk-release",
   "alias": "bulk-release",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "zx-based alternative for multi-semantic-release",
   "type": "module",
   "exports": {
     ".": "./src/main/js/index.js",
     "./test-utils": "./src/test/js/utils/repo.js",
-    "./meta": "./src/main/js/processor/generators/meta.js"
+    "./meta": "./src/main/js/post/depot/generators/meta.js"
   },
   "bin": "./src/main/js/cli.js",
   "files": [

package/src/main/js/post/api/npm.js

@@ -146,18 +146,18 @@ const unzip = (stream, {pick, omit, cwd = process.cwd(), strip = 0} = {}) => new
   extract.on('entry', ({name, type}, stream, cb) => {
     const _name = safePath(strip ? name.split('/').slice(strip).join('/') : name)
     const fp = _path.join(cwd, _name)
+    const skip = type !== 'file' || omit?.includes(_name) || (pick && !pick.includes(_name))
 
-    let data = ''
+    const chunks = []
     stream.on('data', (chunk) => {
-      if (type !== 'file' || omit?.includes(_name) || (pick && !pick.includes(_name))) return
-      data += chunk
+      if (!skip) chunks.push(chunk)
     })
 
     stream.on('end', () => {
-      if (data) {
+      if (chunks.length) {
         results.push(
           _fs.mkdir(_path.dirname(fp), {recursive: true})
-            .then(() => _fs.writeFile(fp, data, 'utf8'))
+            .then(() => _fs.writeFile(fp, Buffer.concat(chunks)))
         )
       }
       cb()

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

@@ -1,4 +1,4 @@
-import {$} from 'zx-extra'
+import {fs, path} from 'zx-extra'
 import {queuefy} from 'queuefy'
 import {fetchRepo, pushCommit} from '../../api/git.js'
 import {log} from '../../log.js'
@@ -15,8 +15,10 @@ const run = queuefy(async (manifest, dir) => {
   log.info('push changelog')
 
   const _cwd = await fetchRepo({branch, origin: repoAuthedUrl, basicAuth: ghBasicAuth})
+  const filePath = path.resolve(_cwd, file)
+  const prev = await fs.readFile(filePath, 'utf8').catch(() => '')
+  await fs.outputFile(filePath, releaseNotes + '\n' + prev)
 
-  await $({cwd: _cwd})`echo ${releaseNotes}"\n$(cat ./${file})" > ./${file}`
   await pushCommit({
     branch,
     msg,

package/src/main/js/post/courier/channels/git-tag.js

@@ -1,5 +1,4 @@
-import {pushTag} from '../../api/git.js'
-import {DEFAULT_GIT_COMMITTER_NAME, DEFAULT_GIT_COMMITTER_EMAIL} from '../../api/git.js'
+import {pushTag, DEFAULT_GIT_COMMITTER_NAME, DEFAULT_GIT_COMMITTER_EMAIL} from '../../api/git.js'
 
 export const isTagConflict = (e) =>
   /already exists|updates were rejected|failed to push/i.test(e?.message || e?.stderr || '')

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

@@ -1,8 +1,7 @@
 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'
+import {getArtifactPath, isAssetMode, prepareMeta} from '../../depot/generators/meta.js'
 import {hasHigherVersion} from '../seniority.js'
 
 const pushMetaBranch = queuefy(async (manifest, dir) => {

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

@@ -1,7 +1,8 @@
 import {$, tempy, within, path, semver, fs} from 'zx-extra'
 import {unpackTar} from '../tar.js'
 import {log} from '../log.js'
-import {scanDirectives, invalidateOrphans} from './directive.js'
+import {pool} from '../../util.js'
+import {scanDirectives, invalidateOrphans} from '../parcel/directive.js'
 import {tryLock, unlock, signalRebuild} from './semaphore.js'
 import gitTag from './channels/git-tag.js'
 import meta from './channels/meta.js'
@@ -11,11 +12,16 @@ 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 = {'git-tag': gitTag, meta, npm, 'gh-release': ghRelease, 'gh-pages': ghPages, changelog, cmd}
 export const defaultOrder = ['git-tag', 'meta', 'npm', 'gh-release', 'gh-pages', 'changelog', 'cmd']
 
+export const getActiveChannels = (pkg, channelNames, snapshot) =>
+  channelNames.filter(n => {
+    const ch = channels[n]
+    return ch && ch.transport !== false && (!snapshot || ch.snapshot) && ch.when(pkg)
+  })
+
 export const prepare = async (names, pkg) => {
   for (const n of names) await channels[n]?.prepare?.(pkg)
 }
@@ -61,22 +67,6 @@ const openParcel = async (tarPath, env) => {
   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()
-  })
-}
-
 export const inspect = async (tars, env = process.env) => {
   const parcels = []
   const skipped = []

package/src/main/js/post/depot/context.js

@@ -1,7 +1,6 @@
 import {fs, path} from 'zx-extra'
-import {channels as channelRegistry} from '../courier/index.js'
 
-const CONTEXT_FILE = '.zbr-context.json'
+export const CONTEXT_FILE = '.zbr-context.json'
 
 export const writeContext = async (cwd, context) => {
   const filePath = path.resolve(cwd, CONTEXT_FILE)
@@ -9,22 +8,24 @@ export const writeContext = async (cwd, context) => {
   return filePath
 }
 
-export const readContext = async (cwd) => {
-  const filePath = path.resolve(cwd, CONTEXT_FILE)
-  try {
-    return await fs.readJson(filePath)
-  } catch {
-    return null
+export const readContext = async (filePath) => {
+  let data
+  try { data = await fs.readJson(filePath) } catch {
+    throw new Error(`context not found: ${filePath}`)
   }
-}
 
-const getActiveChannels = (pkg, channelNames, snapshot) =>
-  channelNames.filter(n => {
-    const ch = channelRegistry[n]
-    return ch && ch.transport !== false && (!snapshot || ch.snapshot) && ch.when(pkg)
-  })
+  if (!data || typeof data !== 'object') throw new Error(`context is not an object: ${filePath}`)
+  if (!data.status)                      throw new Error(`context missing status: ${filePath}`)
+  if (data.status === 'proceed') {
+    if (!data.sha || !data.sha7)         throw new Error(`context missing sha: ${filePath}`)
+    if (!data.packages || typeof data.packages !== 'object')
+      throw new Error(`context missing packages: ${filePath}`)
+  }
+
+  return data
+}
 
-export const buildContext = (packages, queue, sha, {channelNames = [], snapshot = false} = {}) => {
+export const buildContext = (packages, queue, sha, {getChannels} = {}) => {
   const pkgs = {}
   for (const name of queue) {
     const pkg = packages[name]
@@ -32,7 +33,7 @@ export const buildContext = (packages, queue, sha, {channelNames = [], snapshot
     pkgs[name] = {
       version:  pkg.version,
       tag:      pkg.tag,
-      channels: getActiveChannels(pkg, channelNames, snapshot),
+      channels: getChannels ? getChannels(pkg) : [],
     }
   }
 

package/src/main/js/post/depot/reconcile.js

@@ -4,9 +4,6 @@ import {getRemoteTagSha, clearTagsCache} from '../api/git.js'
 import {formatTag} from './generators/tag.js'
 import {resolvePkgVersion} from './steps/analyze.js'
 
-export const isTagConflict = (e) =>
-  /already exists|updates were rejected|failed to push/i.test(e?.message || e?.stderr || '')
-
 export const preflight = async (pkg, ctx) => {
   if (!pkg.tag) return 'ok'
 

package/src/main/js/post/depot/steps/pack.js

@@ -1,28 +1,22 @@
 import {$, tempy, fs, path} from 'zx-extra'
 import {memoizeBy, asTuple} from '../../../util.js'
-import {channels, prepare, buildParcels} from '../../courier/index.js'
+import {prepare, getActiveChannels} from '../../courier/index.js'
+import {buildParcels, PARCELS_DIR} from '../../parcel/index.js'
 import {npmPersist} from '../../api/npm.js'
 import {getRepo} from '../../api/git.js'
 import {formatReleaseNotes} from '../generators/notes.js'
 import {ghPrepareAssets} from '../../api/gh.js'
 import {packTar, hashFile} from '../../tar.js'
 
-
-const filterActive = (names, pkg, {snapshot = false} = {}) =>
-  names.filter(n => {
-    const ch = channels[n]
-    return ch && ch.transport !== false && (!snapshot || ch.snapshot) && ch.when(pkg)
-  })
-
 export const pack = memoizeBy(async (pkg, ctx = pkg.ctx) => {
   const {channels: channelNames = [], flags} = ctx
   const snapshot = !!flags.snapshot
-  const active = filterActive(channelNames, pkg, {snapshot})
+  const active = getActiveChannels(pkg, channelNames, snapshot)
 
   await prepare(active, pkg)
   await npmPersist(pkg)
 
-  const outputDir = flags.pack ? path.resolve(ctx.git.root, typeof flags.pack === 'string' ? flags.pack : 'parcels') : null
+  const outputDir = flags.pack ? path.resolve(ctx.git.root, typeof flags.pack === 'string' ? flags.pack : PARCELS_DIR) : null
   const stageDir = outputDir || tempy.temporaryDirectory()
   if (outputDir) await fs.ensureDir(outputDir)
   const {repoName, repoHost, originUrl} = await getRepo(pkg.absPath, {basicAuth: pkg.config.ghBasicAuth})

package/src/main/js/post/modes/deliver.js

@@ -1,8 +1,7 @@
 import {$, glob, path} from 'zx-extra'
 import {createReport, log} from '../log.js'
 import {deliver} from '../courier/index.js'
-
-const PARCELS_DIR = 'parcels'
+import {PARCELS_DIR} from '../parcel/index.js'
 
 export const runDeliver = async ({env, flags}) => {
   const dir = typeof flags.deliver === 'string' ? flags.deliver : PARCELS_DIR

package/src/main/js/post/modes/pack.js

@@ -10,9 +10,7 @@ import {publish} from '../depot/steps/publish.js'
 import {clean} from '../depot/steps/clean.js'
 import {test} from '../depot/steps/test.js'
 import {preflight} from '../depot/reconcile.js'
-import {buildDirective} from '../courier/directive.js'
-
-const PARCELS_DIR = 'parcels'
+import {buildDirective, PARCELS_DIR} from '../parcel/index.js'
 
 export const runPack = async ({cwd, env, flags}, ctx) => {
   const {report, packages, queue, prev} = ctx

package/src/main/js/post/modes/receive.js

@@ -7,6 +7,7 @@ import {analyze} from '../depot/steps/analyze.js'
 import {clean} from '../depot/steps/clean.js'
 import {preflight} from '../depot/reconcile.js'
 import {consumeRebuildSignal} from '../courier/semaphore.js'
+import {getActiveChannels} from '../courier/index.js'
 import {writeContext, buildContext} from '../depot/context.js'
 import {getSha} from '../api/git.js'
 import {setOutput, isRebuildTrigger} from '../api/gh.js'
@@ -17,7 +18,7 @@ export const runReceive = async ({cwd, env, flags}, ctx) => {
   const sha = await getSha(cwd)
   const sha7 = sha.slice(0, 7)
 
-  if (isRebuildTrigger(env)) {
+  if (isRebuildTrigger(env) && !flags.dryRun) {
     const result = await consumeRebuildSignal(cwd, sha)
     if (result?.exitCode !== 0 && result?.stderr?.includes('remote ref does not exist')) {
       log.info(`rebuild signal already consumed by another process`)
@@ -45,9 +46,9 @@ export const runReceive = async ({cwd, env, flags}, ctx) => {
       if (await preflight(pkg, pkg.ctx) === 'skip') { pkg.skipped = true; return }
     })
 
+    const snapshot = !!flags.snapshot
     const context = buildContext(packages, queue, sha, {
-      channelNames: ctx.channels,
-      snapshot: !!flags.snapshot,
+      getChannels: (pkg) => getActiveChannels(pkg, ctx.channels, snapshot),
     })
     await writeContext(cwd, context)
 

package/src/main/js/post/modes/verify.js

@@ -1,20 +1,19 @@
 import {glob, path, fs} from 'zx-extra'
 import {log} from '../log.js'
-import {parcelChannel} from '../courier/directive.js'
-
-const PARCELS_DIR = 'parcels'
+import {PARCELS_DIR, verifyParcels} from '../parcel/index.js'
+import {CONTEXT_FILE, readContext} from '../depot/context.js'
 
 export const runVerify = async ({cwd, flags}) => {
   const inputDir = typeof flags.verify === 'string' ? flags.verify : PARCELS_DIR
-  const contextPath = typeof flags.context === 'string' ? flags.context : path.resolve(cwd, '.zbr-context.json')
+  const contextPath = typeof flags.context === 'string' ? flags.context : path.resolve(cwd, CONTEXT_FILE)
   const outputDir = path.resolve(cwd, PARCELS_DIR)
 
   log.info(`verifying parcels in ${inputDir} against ${contextPath}`)
 
-  let context
-  try { context = await fs.readJson(contextPath) } catch { context = null }
-  if (!context || context.status !== 'proceed') {
-    throw new Error(`no valid context at ${contextPath}`)
+  const context = await readContext(contextPath)
+  if (context.status !== 'proceed') {
+    log.info(`context status is '${context.status}', nothing to verify`)
+    return
   }
 
   const tars = await glob(path.join(inputDir, 'parcel.*.tar'))
@@ -23,54 +22,13 @@ export const runVerify = async ({cwd, flags}) => {
     return
   }
 
-  const {sha7, packages: expected} = context
-  const errors = []
-  const verified = []
-
-  for (const tarPath of tars) {
-    const name = path.basename(tarPath)
-
-    // sha7 prefix must match
-    if (!name.startsWith(`parcel.${sha7}.`)) {
-      errors.push(`sha mismatch: ${name}`)
-      continue
-    }
-
-    const channel = parcelChannel(name)
-    if (!channel) {
-      errors.push(`malformed name: ${name}`)
-      continue
-    }
-
-    if (channel === 'directive') {
-      verified.push(tarPath)
-      continue
-    }
-
-    // match to an expected package by tag
-    const belongsTo = Object.entries(expected).find(([, pkg]) =>
-      pkg.tag && name.includes(`.${pkg.tag}.`)
-    )
-    if (!belongsTo) {
-      errors.push(`unexpected parcel (no matching package): ${name}`)
-      continue
-    }
-
-    const [pkgName, pkg] = belongsTo
-    if (!pkg.channels.includes(channel)) {
-      errors.push(`unexpected channel '${channel}' for ${pkgName}: ${name}`)
-      continue
-    }
-
-    verified.push(tarPath)
-  }
+  const {verified, errors} = verifyParcels(tars, context)
 
   if (errors.length) {
     for (const e of errors) log.error(`verify: ${e}`)
     throw new Error(`parcel verification failed: ${errors.length} error(s)`)
   }
 
-  // copy verified parcels to output
   if (path.resolve(inputDir) !== outputDir) {
     await fs.ensureDir(outputDir)
     for (const tarPath of verified) {

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

@@ -0,0 +1,4 @@
+export {buildParcels} from './build.js'
+export {buildDirective, parseDirective, scanDirectives, invalidateOrphans, parcelChannel} from './directive.js'
+export {verifyParcels} from './verify.js'
+export const PARCELS_DIR = 'parcels'

package/src/main/js/post/parcel/verify.js

@@ -0,0 +1,46 @@
+import {path} from 'zx-extra'
+import {parcelChannel} from './directive.js'
+
+export const verifyParcels = (tars, context) => {
+  const {sha7, packages: expected} = context
+  const errors = []
+  const verified = []
+
+  for (const tarPath of tars) {
+    const name = path.basename(tarPath)
+
+    if (!name.startsWith(`parcel.${sha7}.`)) {
+      errors.push(`sha mismatch: ${name}`)
+      continue
+    }
+
+    const channel = parcelChannel(name)
+    if (!channel) {
+      errors.push(`malformed name: ${name}`)
+      continue
+    }
+
+    if (channel === 'directive') {
+      verified.push(tarPath)
+      continue
+    }
+
+    const belongsTo = Object.entries(expected).find(([, pkg]) =>
+      pkg.tag && name.includes(`.${pkg.tag}.`)
+    )
+    if (!belongsTo) {
+      errors.push(`unexpected parcel (no matching package): ${name}`)
+      continue
+    }
+
+    const [pkgName, pkg] = belongsTo
+    if (!pkg.channels.includes(channel)) {
+      errors.push(`unexpected channel '${channel}' for ${pkgName}: ${name}`)
+      continue
+    }
+
+    verified.push(tarPath)
+  }
+
+  return {verified, errors}
+}

package/src/main/js/post/release.js

@@ -14,7 +14,39 @@ import {runPack} from './modes/pack.js'
 
 const ZBR_VERSION = createRequire(import.meta.url)('../../../../package.json').version
 
+const HELP = `
+zx-bulk-release v${ZBR_VERSION}
+
+Usage: npx zx-bulk-release [options]
+
+Modes:
+  (no flags)              All-in-one: analyze, build, test, pack, deliver
+  --receive               Analyze & preflight. Writes .zbr-context.json. Run BEFORE deps install.
+  --pack [dir]            Build, test, pack tars to dir.                          [default: parcels]
+  --verify [dir]          Validate parcels against context, copy to parcels/.     [default: parcels]
+  --deliver [dir]         Deliver parcels through channels.                       [default: parcels]
+
+Options:
+  --context <path>        Path to .zbr-context.json (with --verify).     [default: .zbr-context.json]
+  --dry-run, --no-publish Disable any publish / remote-mutating logic.
+  --no-build              Skip buildCmd.
+  --no-test               Skip testCmd.
+  --snapshot              Publish snapshot versions to npm only.
+  --ignore <a,b>          Packages to ignore.
+  --include-private       Include private packages.
+  --concurrency <n>       Build/publish thread limit.                        [default: os.cpus().length]
+  --only-workspace-deps   Recognize only workspace: deps as graph edges.
+  --no-npm-fetch          Disable npm artifact fetching.
+  --report <path>         Persist release state to file.
+  --debug                 Enable verbose mode.
+  -v, --version           Print version.
+  -h, --help              Show this help.
+`.trim()
+
 export const run = async ({cwd = process.cwd(), env: _env, flags = {}} = {}) => within(async () => {
+  if (flags.h || flags.help)
+    return console.log(HELP)
+
   if (flags.v || flags.version)
     return console.log(ZBR_VERSION)
 

package/src/main/js/util.js

@@ -72,3 +72,19 @@ export const memoizeBy = (fn, getKey = v => v) => {
 export const camelize = s => s.replace(/-./g, x => x[1].toUpperCase())
 
 export const asArray = v => Array.isArray(v) ? v : [v]
+
+export 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()
+  })
+}