bulk-release 2.21.0 → 3.0.0

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
+}

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

@@ -0,0 +1,77 @@
+import {asTuple, msgJoin} from '../../util.js'
+
+const gitFields = (a, pkg) => ({
+  repoHost: a.repoHost,
+  repoName: a.repoName,
+  originUrl: a.originUrl,
+  gitCommitterEmail: pkg.config.gitCommitterEmail,
+  gitCommitterName: pkg.config.gitCommitterName,
+})
+
+const entry = {
+  npm: (pkg, ctx, a) => ({
+    channel: 'npm',
+    manifest: {
+      channel: 'npm',
+      name: pkg.name, version: pkg.version, preversion: pkg.preversion,
+      registry: '${{NPM_REGISTRY}}', token: '${{NPM_TOKEN}}',
+      config: '${{NPM_CONFIG}}', provenance: '${{NPM_PROVENANCE}}', oidc: '${{NPM_OIDC}}',
+    },
+    files: a.npmTarball ? [{name: 'package.tgz', source: a.npmTarball}] : [],
+  }),
+
+  'gh-release': (pkg, ctx, a) => ({
+    channel: 'gh-release',
+    manifest: {
+      channel: 'gh-release',
+      tag: pkg.tag, repoName: a.repoName, releaseNotes: a.releaseNotes,
+      token: '${{GH_TOKEN}}', apiUrl: '${{GH_API_URL}}',
+      assets: pkg.config.ghAssets ? [...pkg.config.ghAssets] : undefined,
+    },
+    files: a.assetsDir ? [{name: 'assets', source: a.assetsDir}] : [],
+  }),
+
+  'gh-pages': (pkg, ctx, a) => {
+    const [branch = 'gh-pages', , to = '.', ..._msg] = asTuple(pkg.config.ghPages, ['branch', 'from', 'to', 'msg'])
+    return {
+      channel: 'gh-pages',
+      manifest: {channel: 'gh-pages', branch, to, msg: msgJoin(_msg, pkg, 'docs: update docs ${{name}} ${{version}}'), ...gitFields(a, pkg)},
+      files: a.docsDir ? [{name: 'docs', source: a.docsDir}] : [],
+    }
+  },
+
+  changelog: (pkg, ctx, a) => {
+    const [branch = 'changelog', file = `${pkg.name.replace(/[^a-z0-9-]/ig, '')}-changelog.md`, ..._msg] = asTuple(pkg.config.changelog, ['branch', 'file', 'msg'])
+    return {
+      channel: 'changelog',
+      manifest: {channel: 'changelog', releaseNotes: a.releaseNotes, branch, file, msg: msgJoin(_msg, pkg, 'chore: update changelog ${{name}}'), ...gitFields(a, pkg)},
+      files: [],
+    }
+  },
+
+  meta: (pkg, ctx, a) => ({
+    channel: 'meta',
+    manifest: {
+      channel: 'meta',
+      name: pkg.name, version: pkg.version, tag: pkg.tag,
+      type: pkg.config.meta?.type ?? null, data: pkg.meta,
+      ...gitFields(a, pkg),
+    },
+    files: [],
+  }),
+}
+
+const defaultEntry = (channel) => (pkg, ctx, a) => ({
+  channel,
+  manifest: {channel, name: pkg.name, version: pkg.version, tag: pkg.tag},
+  files: [],
+})
+
+export const buildParcels = (pkg, ctx, {
+  channels: channelNames = [],
+  npmTarball, releaseNotes, docsDir, assetsDir,
+  repoName, repoHost, originUrl,
+} = {}) => {
+  const a = {npmTarball, releaseNotes, docsDir, assetsDir, repoName, repoHost, originUrl}
+  return channelNames.map(n => (entry[n] || defaultEntry(n))(pkg, ctx, a))
+}

package/src/main/js/{processor → post/depot}/exec.js

@@ -1,5 +1,5 @@
-import {tpl} from '../util.js'
-import {log} from './log.js'
+import {tpl} from '../../util.js'
+import {log} from '../log.js'
 import {$} from 'zx-extra'
 
 export const exec = async (pkg, name) => {

package/src/main/js/{processor → post/depot}/generators/meta.js

@@ -1,9 +1,9 @@
 // Meta generator: builds pkg.meta payload and resolves latest-release meta from git tags / gh assets / meta branch.
 
 import {semver, $, fs, path} from 'zx-extra'
-import {fetchRepo, getTags as getGitTags, getRepo} from '../api/git.js'
-import {fetchManifest} from '../api/npm.js'
-import {ghGetAsset} from '../api/gh.js'
+import {fetchRepo, getTags as getGitTags, getRepo} from '../../api/git.js'
+import {fetchManifest} from '../../api/npm.js'
+import {ghGetAsset} from '../../api/gh.js'
 import {parseTag} from './tag.js'
 
 export const isAssetMode = (type) => type === 'asset' || type === 'assets'

package/src/main/js/{processor → post/depot}/generators/notes.js

@@ -1,6 +1,6 @@
 // Release notes formatting. Pure except for a single getRepo() call to resolve repoPublicUrl.
 
-import {getRepo} from '../api/git.js'
+import {getRepo} from '../../api/git.js'
 import {formatTag} from './tag.js'
 
 export const DIFF_TAG_URL = '${repoPublicUrl}/compare/${prevTag}...${newTag}'

package/src/main/js/{processor → post/depot}/steps/analyze.js

@@ -1,6 +1,6 @@
 import {semver} from 'zx-extra'
-import {log} from '../log.js'
-import {getCommits} from '../api/git.js'
+import {log} from '../../log.js'
+import {getCommits} from '../../api/git.js'
 import {updateDeps} from '../deps.js'
 import {formatTag} from '../generators/tag.js'
 

package/src/main/js/{processor → post/depot}/steps/build.js

@@ -1,5 +1,5 @@
-import {memoizeBy} from '../../util.js'
-import {fetchPkg} from '../api/npm.js'
+import {memoizeBy} from '../../../util.js'
+import {fetchPkg} from '../../api/npm.js'
 import {traverseDeps} from '../deps.js'
 import {exec} from '../exec.js'
 

package/src/main/js/{processor → post/depot}/steps/clean.js

@@ -1,5 +1,5 @@
-import {unsetUserConfig} from '../api/git.js'
-import {npmRestore} from '../api/npm.js'
+import {unsetUserConfig} from '../../api/git.js'
+import {npmRestore} from '../../api/npm.js'
 
 export const clean = async ({cwd, packages}) => {
   await unsetUserConfig(cwd)

package/src/main/js/{processor → post/depot}/steps/contextify.js

@@ -1,13 +1,13 @@
-import {getPkgConfig} from '../../config.js'
+import {getPkgConfig} from '../../../config.js'
 import {getLatest} from '../generators/meta.js'
-import {getRoot, getSha} from '../api/git.js'
+import {getRoot, getSha} from '../../api/git.js'
 
 /**
  * Global release context — one per `run()` invocation.
  * Built by `createContext()` in release.js and extended with runtime bits (run, publishers).
  *
  * @typedef {object} ReleaseContext
- * @property {object}                 flags       CLI flags (build, test, publish, snapshot, dryRun, recover, ...).
+ * @property {object}                 flags       CLI flags (build, test, publish, snapshot, dryRun, pack, deliver, ...).
  * @property {Record<string,string>}  env         Resolved process env (process.env merged with per-run overrides).
  * @property {string}                 cwd         Repo working directory.
  * @property {object}                 root        Root package descriptor (from topo()).

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

@@ -0,0 +1,59 @@
+import {$, tempy, fs, path} from 'zx-extra'
+import {memoizeBy, asTuple} from '../../../util.js'
+import {channels, prepare, buildParcels} from '../../courier/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})
+
+  await prepare(active, pkg)
+  await npmPersist(pkg)
+
+  const outputDir = flags.pack ? (typeof flags.pack === 'string' ? flags.pack : 'parcels') : null
+  const stageDir = outputDir || tempy.temporaryDirectory()
+  if (outputDir) await fs.ensureDir(outputDir)
+  const {repoName, repoHost, originUrl} = await getRepo(pkg.absPath, {basicAuth: pkg.config.ghBasicAuth})
+  const artifacts = {repoName, repoHost, originUrl}
+
+  if (active.includes('npm')) {
+    const out = await $({cwd: pkg.absPath})`npm pack --pack-destination ${stageDir}`
+    artifacts.npmTarball = path.join(stageDir, out.toString().trim())
+  }
+  if (active.includes('gh-release') || active.includes('changelog'))
+    artifacts.releaseNotes = await formatReleaseNotes(pkg)
+  if (active.includes('gh-pages')) {
+    const [, from = 'docs'] = asTuple(pkg.config.ghPages, ['branch', 'from'])
+    artifacts.docsDir = path.join(stageDir, 'docs')
+    await fs.copy(path.join(pkg.absPath, from), artifacts.docsDir)
+  }
+  if (active.includes('gh-release') && pkg.config.ghAssets?.length)
+    artifacts.assetsDir = await ghPrepareAssets(pkg.config.ghAssets, pkg.absPath)
+
+  const parcels = buildParcels(pkg, ctx, {channels: active, ...artifacts})
+
+  const tars = []
+  for (const {channel, manifest, files} of parcels) {
+    // Two-pass: pack to temp, hash, rename to final name.
+    const tmpPath = path.join(stageDir, `_tmp.${channel}.tar`)
+    await packTar(tmpPath, manifest, files)
+    const hash = await hashFile(tmpPath)
+    const finalPath = path.join(stageDir, `parcel.${pkg.tag}.${channel}.${hash}.tar`)
+    await fs.rename(tmpPath, finalPath)
+    tars.push(finalPath)
+  }
+
+  pkg.tars = tars
+  pkg.activeTransport = active
+})

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

@@ -0,0 +1,29 @@
+import {memoizeBy} from '../../../util.js'
+import {exec} from '../exec.js'
+import {log} from '../../log.js'
+import {deliver, channels, runChannel} from '../../courier/index.js'
+import {pushTag} from '../../api/git.js'
+
+export const publish = memoizeBy(async (pkg, ctx = pkg.ctx) => {
+  if (pkg.version !== pkg.manifest.version)
+    throw new Error('package.json version not synced')
+
+  const {run = exec, channels: channelNames = [], flags} = ctx
+  const snapshot = !!flags.snapshot
+  const {tars = []} = pkg
+
+  if (!snapshot) {
+    const {tag, config: {gitCommitterEmail, gitCommitterName}} = pkg
+    ctx.git.tag = tag
+    log.info(`push release tag ${tag}`)
+    await pushTag({cwd: ctx.git.root, tag, gitCommitterEmail, gitCommitterName})
+  }
+
+  await deliver(tars, ctx.env)
+
+  const cmd = channels.cmd
+  if (channelNames.includes('cmd') && cmd?.when(pkg) && (!snapshot || cmd.snapshot))
+    await runChannel('cmd', pkg, run)
+
+  pkg.published = true
+})

package/src/main/js/{processor → post/depot}/steps/test.js

@@ -1,4 +1,4 @@
-import {memoizeBy} from '../../util.js'
+import {memoizeBy} from '../../../util.js'
 import {exec} from '../exec.js'
 
 export const test = memoizeBy(async (pkg, ctx = pkg.ctx) => {

package/src/main/js/{processor → post}/release.js

@@ -1,29 +1,22 @@
 import os from 'node:os'
 import {createRequire} from 'node:module'
-import {$, within} from 'zx-extra'
+import {$, within, fs, glob, path} from 'zx-extra'
 import {queuefy} from 'queuefy'
-import {topo, traverseQueue} from './deps.js'
+import {topo, traverseQueue} from './depot/deps.js'
 import {createReport, log} from './log.js'
-import {exec} from './exec.js'
-
-import {contextify} from './steps/contextify.js'
-import {recover} from './steps/teardown.js'
-import {fetchTags} from './api/git.js'
-import {analyze} from './steps/analyze.js'
-import {build} from './steps/build.js'
-import {publish} from './steps/publish.js'
-import {clean} from './steps/clean.js'
-import {test} from './steps/test.js'
-
-import meta from './publishers/meta.js'
-import npm from './publishers/npm.js'
-import ghRelease from './publishers/gh-release.js'
-import ghPages from './publishers/gh-pages.js'
-import changelog from './publishers/changelog.js'
-import cmd from './publishers/cmd.js'
-
-// Publisher registry. Order = publish order; teardown walks it in reverse.
-const publishers = [meta, npm, ghRelease, ghPages, changelog, cmd]
+import {exec} from './depot/exec.js'
+
+import {contextify} from './depot/steps/contextify.js'
+import {analyze} from './depot/steps/analyze.js'
+import {build} from './depot/steps/build.js'
+import {pack} from './depot/steps/pack.js'
+import {publish} from './depot/steps/publish.js'
+import {clean} from './depot/steps/clean.js'
+import {test} from './depot/steps/test.js'
+
+import {deliver, defaultOrder as channels} from './courier/index.js'
+
+const PARCELS_DIR = 'parcels'
 
 export const run = async ({cwd = process.cwd(), env, flags = {}} = {}) => within(async () => {
   $.memo = new Map()
@@ -34,10 +27,22 @@ export const run = async ({cwd = process.cwd(), env, flags = {}} = {}) => within
     return
   }
 
+  // --deliver [dir]: standalone delivery from pre-packed tars.
+  if (flags.deliver) {
+    const dir = typeof flags.deliver === 'string' ? flags.deliver : PARCELS_DIR
+    const tars = await glob(path.join(dir, 'parcel.*.tar'))
+    if (!tars.length) throw new Error(`no tars found in ${dir}`)
+    const _env = {...process.env, ...env}
+    log.secret(_env.GH_TOKEN, _env.GITHUB_TOKEN, _env.NPM_TOKEN)
+    log.info(`deliver: ${tars.length} tar(s) from ${dir}`)
+    const delivered = await deliver(tars, _env)
+    log.info(`deliver: done, ${delivered} delivered`)
+    return
+  }
+
   const ctx = await createContext({flags, env, cwd})
   const {report, packages, queue, prev} = ctx
 
-  // Per-package scope: $.scope, packages[name] lookup, contextify on first touch.
   const forEachPkg = (cb) => traverseQueue({queue, prev, cb: (name) => within(async () => {
     $.scope = name
     const pkg = packages[name]
@@ -50,15 +55,6 @@ export const run = async ({cwd = process.cwd(), env, flags = {}} = {}) => within
     .log('queue:', queue)
     .log('graphs', ctx.graphs)
 
-  // --recover: standalone mode — clean orphan tags and exit.
-  if (flags.recover) {
-    await fetchTags(cwd)
-    let recovered = 0
-    await forEachPkg(async (pkg) => { if (await recover(pkg)) recovered++ })
-    report.log(`recover: cleaned ${recovered} orphan tag(s)`)
-    return
-  }
-
   try {
     await forEachPkg(async (pkg) => {
       report.setStatus('analyzing', pkg.name)
@@ -88,10 +84,22 @@ export const run = async ({cwd = process.cwd(), env, flags = {}} = {}) => within
         report.setStatus('testing', pkg.name)
         await test(pkg)
       }
-      if (!flags.dryRun && flags.publish !== false) {
-        report.setStatus('publishing', pkg.name)
-        await publish(pkg)
+      if (flags.dryRun || flags.publish === false) {
+        report.setStatus('success', pkg.name)
+        return
       }
+
+      report.setStatus('packing', pkg.name)
+      await pack(pkg)
+
+      // --pack <dir>: pack only, skip delivery.
+      if (flags.pack) {
+        report.setStatus('packed', pkg.name)
+        return
+      }
+
+      report.setStatus('publishing', pkg.name)
+      await publish(pkg)
       report.setStatus('success', pkg.name)
     })
   } catch (e) {
@@ -108,7 +116,6 @@ export const createContext = async ({flags, env: _env, cwd}) => {
   const report = createReport({packages, queue, flags})
   const env = {...process.env, ..._env}
 
-  // Register known secrets so the logger redacts them from all output.
   log.secret(env.GH_TOKEN, env.GITHUB_TOKEN, env.NPM_TOKEN)
 
   $.report  = report
@@ -118,7 +125,7 @@ export const createContext = async ({flags, env: _env, cwd}) => {
 
   return {
     cwd, env, flags, root, packages, queue, prev, graphs, report,
-    publishers,
+    channels,
     run: queuefy(exec, flags.concurrency || os.cpus().length),
   }
 }

package/src/main/js/post/tar.js

@@ -0,0 +1,73 @@
+import tar from 'tar-stream'
+import crypto from 'node:crypto'
+import {fs, path} from 'zx-extra'
+import {pipeline} from 'node:stream/promises'
+import {createWriteStream, createReadStream} from 'node:fs'
+
+export const packTar = async (tarPath, manifest, files = []) => {
+  const pack = tar.pack()
+  const json = JSON.stringify(manifest, null, 2)
+  pack.entry({name: 'manifest.json', size: Buffer.byteLength(json)}, json)
+
+  for (const {name, source} of files) {
+    const stat = await fs.stat(source)
+    if (stat.isDirectory()) await addDir(pack, name, source)
+    else {
+      const buf = await fs.readFile(source)
+      pack.entry({name, size: buf.length}, buf)
+    }
+  }
+
+  pack.finalize()
+  await pipeline(pack, createWriteStream(tarPath))
+  return tarPath
+}
+
+export const hashFile = async (filePath) => {
+  const hash = crypto.createHash('sha1')
+  await pipeline(createReadStream(filePath), hash)
+  return hash.digest('hex').slice(0, 8)
+}
+
+const addDir = async (pack, prefix, dirPath) => {
+  for (const e of await fs.readdir(dirPath, {withFileTypes: true})) {
+    const full = path.join(dirPath, e.name)
+    const rel = path.join(prefix, e.name)
+    if (e.isDirectory()) await addDir(pack, rel, full)
+    else {
+      const buf = await fs.readFile(full)
+      pack.entry({name: rel, size: buf.length}, buf)
+    }
+  }
+}
+
+export const unpackTar = async (tarPath, destDir) => {
+  await fs.ensureDir(destDir)
+  const extract = tar.extract()
+  let manifest = null
+
+  const done = new Promise((resolve, reject) => {
+    extract.on('entry', (header, stream, cb) => {
+      const chunks = []
+      stream.on('data', d => chunks.push(d))
+      stream.on('end', async () => {
+        const buf = Buffer.concat(chunks)
+        if (header.name === 'manifest.json') {
+          manifest = JSON.parse(buf.toString('utf8'))
+        } else {
+          const dest = path.join(destDir, header.name)
+          await fs.ensureDir(path.dirname(dest))
+          await fs.writeFile(dest, buf)
+        }
+        cb()
+      })
+      stream.resume()
+    })
+    extract.on('finish', resolve)
+    extract.on('error', reject)
+  })
+
+  await pipeline(createReadStream(tarPath), extract)
+  await done
+  return {manifest, dir: destDir}
+}

package/src/test/js/utils/gh-server.js

@@ -0,0 +1,33 @@
+import http from 'node:http'
+
+export const createGhServer = async () => {
+  const requests = []
+  let routes = {}
+
+  const server = http.createServer((req, res) => {
+    let body = ''
+    req.on('data', c => body += c)
+    req.on('end', () => {
+      requests.push({method: req.method, url: req.url, headers: req.headers, body})
+      const key = `${req.method} ${req.url}`
+      for (const [pattern, handler] of Object.entries(routes)) {
+        if (key.includes(pattern) || new RegExp(pattern).test(key)) {
+          return handler(req, res, body)
+        }
+      }
+      res.writeHead(404)
+      res.end('{}')
+    })
+  })
+
+  await new Promise(r => server.listen(0, '127.0.0.1', r))
+
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    requests,
+    routes,
+    reset() { requests.length = 0; routes = {}; return routes },
+    setRoutes(r) { Object.assign(routes, r) },
+    close() { server.close() },
+  }
+}