dsh-keys-manager 0.2.2 → 0.2.3

package/locale/en.json

@@ -3,6 +3,14 @@
     "title": "Keys Manager",
     "description": "Multiple API keys per provider with sticky sessions, round-robin selection, retry failover, cooldown recovery, and searchable extra providers."
   },
+  "filterAll": "All",
+  "filterBuiltin": "Built-in",
+  "filterPlugin": "Plugin",
+  "filterOauth": "OAuth-capable",
+  "filterTransport": "Transport",
+  "unattributed": "{n} unattributed",
+  "unattributedHint": "Stream attempts this route served with no account owner because its ownership read had not landed (or had failed). A failover retry is a new attempt, so one request can be counted more than once. The count clears when a read attributes the route.",
+  "managedFilteredEmpty": "No managed providers match the current filter.",
   "addAccount": "Add account",
   "adoptAccountTitle": "Sign in with an OAuth account to use this provider.",
   "accountIdentity": "Account",
@@ -28,7 +36,7 @@
   "deleteAccountTitle": "Delete account “{alias}”?",
   "deleteAccountBody": "This removes the account’s stored OAuth grant from the credential store. If it is the active account, the provider route stops serving it and falls back to its API-key pool; the provider stays managed.",
   "deleteAccountBodyNoKeys": "This removes the account’s stored OAuth grant from the credential store. This route has no API-key pool, so it stops serving requests until an account is signed in again.",
-  "transportAccounts": "Transport accounts",
+  "transportProviderHint": "Served by a transport plugin: its credential is managed inside this card.",
   "transportTag": "Transport",
   "transportSignIn": "Sign in",
   "transportExpires": "Expires {time}",
@@ -37,5 +45,7 @@
   "transportStatusNeedsReauth": "Sign in again",
   "transportStatusSignedOut": "Not signed in",
   "transportRemoveTitle": "Remove the {name} transport account?",
-  "transportRemoveBody": "This removes the grant stored for this transport route from the credential store and cancels a sign-in still in progress; the route does not recreate it. Sign in again to restore service."
+  "transportRemoveBody": "This removes the grant stored for this transport route from the credential store and cancels a sign-in still in progress; the route does not recreate it. Sign in again to restore service.",
+  "filterGroup": "Filters",
+  "transportEmpty": "No transport accounts yet."
 }

package/locale/zh.json

@@ -3,6 +3,14 @@
     "title": "密钥管理",
     "description": "为同一个 Provider 配置多个 API Key，支持单会话固定、Round Robin、重试切换、冷却恢复，并提供可搜索的扩展 Provider。"
   },
+  "filterAll": "全部",
+  "filterBuiltin": "内置",
+  "filterPlugin": "插件",
+  "filterOauth": "支持 OAuth",
+  "filterTransport": "传输",
+  "unattributed": "{n} 无归属",
+  "unattributedHint": "该路由在归属读取尚未落地（或已失败）期间应答的流尝试数；失败转移重试会各计一次，故单个请求可能被计多次。读取完成归属后清零。",
+  "managedFilteredEmpty": "当前筛选下没有已接管的 Provider。",
   "addAccount": "添加账户",
   "adoptAccountTitle": "使用 OAuth 账户登录后即可使用该 Provider。",
   "accountIdentity": "账户",
@@ -28,7 +36,7 @@
   "deleteAccountTitle": "删除账户“{alias}”？",
   "deleteAccountBody": "这会从凭证库中删除该账户保存的 OAuth 授权。如果它是当前账户，该 Provider 路由将停用它并回落到 API-key 池；Provider 仍保持接管状态。",
   "deleteAccountBodyNoKeys": "这会从凭证库中删除该账户保存的 OAuth 授权。该路由没有 API-key 池，删除后将停止服务，直到重新登录账户。",
-  "transportAccounts": "传输账户",
+  "transportProviderHint": "该路由由传输插件提供，凭证就在本卡片中管理。",
   "transportTag": "传输",
   "transportSignIn": "登录",
   "transportExpires": "有效期至 {time}",
@@ -37,5 +45,7 @@
   "transportStatusNeedsReauth": "需重新登录",
   "transportStatusSignedOut": "未登录",
   "transportRemoveTitle": "移除 {name} 传输账户？",
-  "transportRemoveBody": "这会从凭证库中删除该传输路由保存的授权，并取消仍在进行的登录；路由自身不会重建它。要恢复服务需要重新登录。"
+  "transportRemoveBody": "这会从凭证库中删除该传输路由保存的授权，并取消仍在进行的登录；路由自身不会重建它。要恢复服务需要重新登录。",
+  "filterGroup": "筛选",
+  "transportEmpty": "还没有传输账户。"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-keys-manager",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "description": "Multi-key management for DSH providers: sticky per-session round-robin, retry failover, cooldown recovery, and searchable extra providers.",
   "repository": {
@@ -72,7 +72,7 @@
     "react": "^18.2.0"
   },
   "dependencies": {
-    "dsh-llm-omp-transports": "^0.2.2"
+    "dsh-llm-omp-transports": "^0.2.3"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",

package/scripts/prepare-release.mjs

@@ -1,15 +1,25 @@
 #!/usr/bin/env node
 /**
- * Release-prep version helper (plans dsh-keys-manager-ci-release, task 2 + 4;
- * omp-transport-cursor-tools, task 5):
+ * Release-prep version and changelog helper (plans dsh-keys-manager-ci-release,
+ * task 2 + 4; omp-transport-cursor-tools, task 5; release-changelog-fragments,
+ * task 1):
  * resolves the target version — explicit `X.Y.Z` / `X.Y.Z-prerelease`
  * argument (e.g. 0.1.1-alpha.1) or an auto patch bump from package.json —
- * refuses already-released versions (existing `v<version>` git tag), aborts
- * when there are no commits since the previous release tag (nothing to
- * release), bumps package.json, inserts the `## [<version>]` section into
- * CHANGELOG.md (root only — the transports package has no generated
- * changelog), and prints the root and transports versions and tags for the
- * workflow to capture. Node built-ins only, no new dependencies.
+ * refuses already-released versions (existing `v<version>` git tag), bumps
+ * package.json, assembles the release notes from the authored
+ * `.changes/unreleased/*.md` fragments, inserts the `## [<version>]` section
+ * into CHANGELOG.md (root only — the transports package has no generated
+ * changelog), archives the consumed fragments to `.changes/archive/<version>/`,
+ * and prints the root and transports versions and tags for the workflow to
+ * capture. Node built-ins only, no new dependencies.
+ *
+ * The fragments ARE the release notes: a release whose rendered body is empty
+ * (zero fragments, prose-only fragments, or fragments without `- ` bullet
+ * lines) is refused on both a dry run and a real run, so an empty
+ * `## [<version>]` section can never be published. Archiving never overwrites
+ * an existing `.changes/archive/<version>/` file, and a failed archive reports
+ * what moved and what did not. A run prints `ARCHIVED=1` only when it really
+ * consumed the fragments.
  *
  * The workspace package `packages/llm-omp` (`dsh-llm-omp-transports`) ships as
  * part of the same release and always carries the same version: the resolved
@@ -25,13 +35,22 @@
  *   node scripts/prepare-release.mjs --dry-run # validate + print, write nothing
  *
  * Exit codes: 0 = bumped (or dry-run resolved) and printed versions; 1 =
- * rejected (unparseable version, existing tag, no commits since the previous
- * release tag, unparseable current package.json version, invalid prerelease
- * dist-tag, or CHANGELOG.md write error).
+ * rejected (unparseable version, existing tag, no changelog bullets in
+ * `.changes/unreleased/`, an archive destination that already exists, an
+ * archive move that failed, unparseable current package.json version, invalid
+ * prerelease dist-tag, or CHANGELOG.md write error).
  */
 
 import { execFileSync } from 'node:child_process'
-import { readFileSync, writeFileSync } from 'node:fs'
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -41,7 +60,10 @@ const TRANSPORTS_PKG_PATH = join(REPO_ROOT, 'packages/llm-omp/package.json')
 const TRANSPORT_PACKAGE = 'dsh-llm-omp-transports'
 const CHANGELOG_PATH = join(REPO_ROOT, 'CHANGELOG.md')
 const CHANGELOG_HEADER =
-  '# Changelog\n\nAll notable changes to dsh-keys-manager are documented here. Generated from git log by the release-prep workflow.\n'
+  '# Changelog\n\nAll notable changes to dsh-keys-manager are documented here. Assembled from `.changes/unreleased/` fragments by the release-prep workflow.\n'
+const UNRELEASED_DIR = join(REPO_ROOT, '.changes/unreleased')
+const ARCHIVE_DIR = join(REPO_ROOT, '.changes/archive')
+const DEFAULT_CATEGORY = 'Changed'
 
 /**
  * Parse X.Y.Z or X.Y.Z[-prerelease] (numeric parts; optional prerelease
@@ -81,24 +103,6 @@ function assertPublishablePrerelease(prerelease) {
   }
 }
 
-const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'))
-const transportsPkg = JSON.parse(readFileSync(TRANSPORTS_PKG_PATH, 'utf8'))
-
-const { versionArg, dryRun } = parseArgs(process.argv.slice(2))
-
-const target = resolveTarget(versionArg, pkg.version, 'package.json')
-const version = formatVersion(target)
-
-// Validate the npm dist-tag derived by the release workflow. A prerelease
-// identifier like "latest" would move the stable tag, and a numeric one like
-// "1" is not a legal npm tag. Reject both before the release PR is opened.
-assertPublishablePrerelease(target.prerelease)
-
-// The transports package ships from the same version as the root: one input
-// drives both package.json files, so the two can never drift.
-const transportVersion = version
-const transportTag = `${TRANSPORT_PACKAGE}@${transportVersion}`
-
 /**
  * Parse CLI flags. The first non-flag argument is the target version.
  */
@@ -193,122 +197,150 @@ function tagExists(tag) {
   }
 }
 
-// Reject already-released versions: the tag exists iff the version was
-// released. Works unchanged for prerelease tags (v0.1.1-alpha.1 is a plain
-// tag name). Run from REPO_ROOT so the check is cwd-independent.
-if (tagExists(`v${version}`)) {
-  console.error(`Error: tag v${version} already exists — this version is already released.`)
-  process.exit(1)
+/**
+ * Split an optional leading `---` frontmatter block off a fragment. Only
+ * `key: value` lines are read; the rest of the file is the body.
+ */
+function parseFrontmatter(text) {
+  const frontmatter = {}
+  if (!text.startsWith('---')) return { frontmatter, body: text }
+  const end = text.indexOf('\n---', 3)
+  if (end === -1) return { frontmatter, body: text }
+  for (const line of text.slice(3, end).split('\n')) {
+    const match = /^([A-Za-z0-9 _-]+):\s*(.*)$/.exec(line)
+    if (match) frontmatter[match[1].trim()] = match[2].trim()
+  }
+  return { frontmatter, body: text.slice(end + 4).replace(/^\n/, '') }
 }
-if (tagExists(transportTag)) {
-  console.error(`Error: tag ${transportTag} already exists — this transport version is already released.`)
-  process.exit(1)
+
+/**
+ * One fragment file -> its grouping category (undefined = default), its bullet
+ * lines, and how many other non-blank body lines were ignored. Only lines that
+ * start with `- ` after trimming (and carry text after the dash) are release
+ * notes; prose cannot pass for a bullet, so a fragment of prose renders an
+ * empty body and the caller refuses the release instead of publishing a
+ * paragraph as a changelog entry.
+ */
+export function parseFragment(file, text) {
+  const { frontmatter, body } = parseFrontmatter(text)
+  const bullets = []
+  let dropped = 0
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0) continue
+    if (trimmed.startsWith('- ') && trimmed.slice(2).trim().length > 0) bullets.push(trimmed)
+    else dropped += 1
+  }
+  return {
+    file,
+    category: frontmatter.category?.trim() || undefined,
+    bullets,
+    dropped,
+  }
 }
 
-// Fail fast on a no-change release: an empty notes range means no commits
-// since the previous release tag — prepare-release must not bump the version
-// or touch CHANGELOG.md for an empty release (no empty release PR). First-
-// ever releases (no ancestor tag yet) span the full first-parent history,
-// which is non-empty by construction, so they still pass.
-const { prevTag, notes } = resolveReleaseNotes()
-if (notes === '') {
-  console.error(
-    `Error: no commits since previous release tag ${prevTag === '' ? '<first commit>' : prevTag} — nothing to release. Aborting.`,
-  )
-  process.exit(1)
+/**
+ * Fragments in filename order. `README.md` (the format doc) and every
+ * non-`.md` entry (`.gitkeep`) are skipped; a missing directory is zero
+ * fragments, which the caller refuses for a real release.
+ */
+export function readFragments(dir = UNRELEASED_DIR) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((file) => file.endsWith('.md') && file !== 'README.md')
+    .sort()
+    .map((file) => parseFragment(file, readFileSync(join(dir, file), 'utf8')))
 }
 
-// Write only outside a dry run: a dry run validates and prints the resolved
-// versions exactly like a real run, then leaves the working tree untouched.
-if (!dryRun) {
-  pkg.version = version
-  // Preserve repo formatting: 2-space indent + trailing newline. Bumping only
-  // the version keeps `git diff package.json` to that one line.
-  writeFileSync(PKG_PATH, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+/**
+ * Render the section body: `### <category>` + its bullets, categories in
+ * first-seen order (a fragment without `category:` lands under `Changed`).
+ * A fragment with no bullets contributes nothing — not even a bullet-less
+ * heading — so "every fragment is empty" really renders an empty body and the
+ * caller can refuse it.
+ */
+export function buildSectionBody(fragments) {
+  const groups = []
+  for (const fragment of fragments) {
+    if (fragment.bullets.length === 0) continue
+    const category = fragment.category ?? DEFAULT_CATEGORY
+    let group = groups.find((candidate) => candidate.category === category)
+    if (group === undefined) {
+      group = { category, bullets: [] }
+      groups.push(group)
+    }
+    group.bullets.push(...fragment.bullets)
+  }
+  return groups
+    .map((group) => [`### ${group.category}`, '', ...group.bullets].join('\n'))
+    .join('\n\n')
+}
 
-  transportsPkg.version = transportVersion
-  writeFileSync(TRANSPORTS_PKG_PATH, `${JSON.stringify(transportsPkg, null, 2)}\n`, 'utf8')
+/**
+ * Why this fragment set cannot be released, or null when it can. The rendered
+ * body IS the release notes, so an empty body — no fragments at all, fragments
+ * that are prose only, or fragments whose `- ` lines carry no text — would
+ * publish an empty section: refuse it. The message names the files that
+ * contributed nothing. Exported so a caller (CI, a test) can ask the same
+ * question without running the release flow.
+ */
+export function notesRefusal(fragments) {
+  if (buildSectionBody(fragments).trim() !== '') return null
+  const empties = fragments
+    .filter((fragment) => fragment.bullets.length === 0)
+    .map((fragment) => fragment.file)
+  return (
+    'no changelog bullets in .changes/unreleased/ — nothing to release. ' +
+    'Add one `- ` bullet per user-visible change (format: .changes/unreleased/README.md).' +
+    (empties.length === 0 ? '' : ` Fragment files without bullets: ${empties.join(', ')}.`)
+  )
 }
 
 /**
- * Resolve the previous release tag (nearest ancestor tag of HEAD; empty
- * when none exists yet) and the first-parent commit subjects since that
- * tag (full first-parent history when no tag exists). Same git-log snippet
- * the workflows use for the PR body — the CHANGELOG section and the PR body
- * stay consistent. Do NOT use "v$VERSION^": the version string is not a
- * git ref — the bump commit is not tagged yet.
+ * Insert a `## [<version>] - <date>` section above the first existing
+ * `## [` section (or after the header block when there is none yet).
+ * Everything at and below the insertion point keeps its bytes, including the
+ * file's trailing-newline state (a split/splice/join round-trip would
+ * re-normalize line breaks).
  */
-function resolveReleaseNotes() {
-  let prevTag = ''
-  try {
-    prevTag = execFileSync('git', ['describe', '--tags', '--abbrev=0', 'HEAD'], {
-      cwd: REPO_ROOT,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim()
-  } catch {
-    // No ancestor tag yet → full history.
+export function insertSection(changelog, version, date, body) {
+  const header = `## [${version}] - ${date}`
+  const section = body.trim() === '' ? `${header}\n` : `${header}\n\n${body.trim()}\n`
+  const firstSectionMatch = /^## \[/m.exec(changelog)
+  if (firstSectionMatch === null) {
+    // No sections yet — append the new section after the header block.
+    return changelog.endsWith('\n')
+      ? `${changelog}\n${section}`
+      : `${changelog}\n\n${section}`
   }
-  const range = prevTag === '' ? 'HEAD' : `${prevTag}..HEAD`
-  const notes = execFileSync('git', ['log', '--oneline', '--first-parent', range], {
-    cwd: REPO_ROOT,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'ignore'],
-  }).trim()
-  return { prevTag, notes }
+  return `${changelog.slice(0, firstSectionMatch.index)}${section}\n${changelog.slice(firstSectionMatch.index)}`
 }
 
 /**
- * Insert a `## [<version>] - <YYYY-MM-DD>` section under the `# Changelog`
- * header, above the existing sections, from the pre-collected git-log notes
- * (guaranteed non-empty by the no-change guard, so no fallback text is ever
- * written). Preserves all existing sections; no-op when the section for this
- * version already exists (idempotent re-runs must not duplicate it); write
- * failures exit 1.
+ * Write the new section into CHANGELOG.md and report whether it was written.
+ * Preserves all existing sections; no-op (returns false) when the section for
+ * this version already exists, so a re-run must not duplicate it and must not
+ * consume fragments it never rendered. A 0-byte or whitespace-only file (e.g.
+ * manual truncation) is treated as missing, so it still boots with the
+ * standard header instead of a section above no header at all. Write failures
+ * exit 1.
  */
-function updateChangelog(version, notes) {
+function updateChangelog(version, body) {
   let content
   try {
     content = readFileSync(CHANGELOG_PATH, 'utf8')
   } catch {
     content = CHANGELOG_HEADER
   }
-  // A 0-byte or whitespace-only CHANGELOG.md (e.g. manual truncation) is
-  // treated as missing: such a file must still bootstrap with the standard
-  // header, otherwise the new section would land at the top with leading
-  // blank lines and no `# Changelog` header.
   if (content.trim() === '') {
     content = CHANGELOG_HEADER
   }
 
   if (content.includes(`## [${version}]`)) {
-    return
+    return false
   }
 
-  const sectionHeader = `## [${version}] - ${new Date().toISOString().slice(0, 10)}`
-  const sectionBody = notes
-    .split('\n')
-    .map((line) => `- ${line}`)
-    .join('\n')
-  // The section's own trailing `\n` plus the inserted `\n` below form the
-  // blank-line separator between the new section and the existing sections.
-  const section = `${sectionHeader}\n\n${sectionBody}\n`
-
-  // Insert on the first `## [` section header via string slice: everything
-  // at and below the insertion point — including the file's exact trailing
-  // newline — is preserved byte-for-byte. (A split('\n')/splice/join('\n')
-  // round-trip would re-normalize line breaks and could alter the tail, e.g.
-  // appending a trailing newline that was not in the source file.)
-  const firstSectionMatch = /^## \[/m.exec(content)
-  const firstSectionIdx = firstSectionMatch === null ? -1 : firstSectionMatch.index
-  let next
-  if (firstSectionIdx === -1) {
-    // No sections yet — append the new section after the header block,
-    // keeping the file's own trailing-newline state.
-    next = content.endsWith('\n') ? `${content}\n${section}` : `${content}\n\n${section}`
-  } else {
-    next = `${content.slice(0, firstSectionIdx)}${section}\n${content.slice(firstSectionIdx)}`
-  }
+  const next = insertSection(content, version, new Date().toISOString().slice(0, 10), body)
 
   try {
     writeFileSync(CHANGELOG_PATH, next, 'utf8')
@@ -316,15 +348,173 @@ function updateChangelog(version, notes) {
     console.error(`Error: cannot write ${CHANGELOG_PATH}: ${error.message}`)
     process.exit(1)
   }
+  return true
 }
 
-// Root changelog only: the transports package has no generated changelog.
-if (!dryRun) updateChangelog(version, notes)
+/**
+ * Move the consumed fragments to `.changes/archive/<version>/`.
+ *
+ * Authored release notes are never overwritten: a destination file that
+ * already exists refuses the whole move before anything is renamed, so a
+ * collision cannot leave the fragments half-archived. A move that fails
+ * mid-way reports exactly which files were archived and which remain, then
+ * exits 1 — a partially archived set must not be silently reported as done.
+ * `FS_*` is not needed for that; the paths are printed verbatim.
+ */
+function archiveFragments(version, fragments) {
+  if (fragments.length === 0) return true
+  const destination = join(ARCHIVE_DIR, version)
+  const moves = fragments.map((fragment) => ({
+    file: fragment.file,
+    from: join(UNRELEASED_DIR, fragment.file),
+    to: join(destination, fragment.file),
+  }))
 
-// The workflow captures VERSION; the remaining lines are informational and
-// let a dry run show both derived tags without touching the tree.
-if (dryRun) console.log('DRY_RUN=1')
-console.log(`VERSION=${version}`)
-console.log(`TAG=v${version}`)
-console.log(`TRANSPORT_VERSION=${transportVersion}`)
-console.log(`TRANSPORT_TAG=${transportTag}`)
+  const collisions = moves.filter((move) => existsSync(move.to)).map((move) => move.to)
+  if (collisions.length > 0) {
+    console.error(
+      `Error: refusing to overwrite archived release notes: ${collisions.join(', ')}. ` +
+        'Move the existing files away (or pick another version) and re-run.',
+    )
+    process.exit(1)
+  }
+
+  const fail = (error, archived) => {
+    const remaining = moves.slice(archived.length).map((candidate) => candidate.from)
+    console.error(`Error: cannot archive fragments: ${error.message}`)
+    console.error(
+      `Archived (${archived.length}): ${archived.length === 0 ? 'none' : archived.join(', ')}.`,
+    )
+    console.error(`Remaining (${remaining.length}): ${remaining.join(', ')}.`)
+    process.exit(1)
+  }
+
+  const archived = []
+  try {
+    mkdirSync(destination, { recursive: true })
+  } catch (error) {
+    fail(error, archived)
+  }
+  for (const move of moves) {
+    try {
+      renameSync(move.from, move.to)
+    } catch (error) {
+      fail(error, archived)
+    }
+    archived.push(move.file)
+  }
+  return true
+}
+
+function main() {
+  const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'))
+  const transportsPkg = JSON.parse(readFileSync(TRANSPORTS_PKG_PATH, 'utf8'))
+
+  const { versionArg, dryRun } = parseArgs(process.argv.slice(2))
+
+  const target = resolveTarget(versionArg, pkg.version, 'package.json')
+  const version = formatVersion(target)
+
+  // Validate the npm dist-tag derived by the release workflow. A prerelease
+  // identifier like "latest" would move the stable tag, and a numeric one like
+  // "1" is not a legal npm tag. Reject both before the release PR is opened.
+  assertPublishablePrerelease(target.prerelease)
+
+  // The transports package ships from the same version as the root: one input
+  // drives both package.json files, so the two can never drift.
+  const transportVersion = version
+  const transportTag = `${TRANSPORT_PACKAGE}@${transportVersion}`
+
+  // Reject already-released versions: the tag exists iff the version was
+  // released. Works unchanged for prerelease tags (v0.1.1-alpha.1 is a plain
+  // tag name). Run from REPO_ROOT so the check is cwd-independent.
+  if (tagExists(`v${version}`)) {
+    console.error(`Error: tag v${version} already exists — this version is already released.`)
+    process.exit(1)
+  }
+  if (tagExists(transportTag)) {
+    console.error(`Error: tag ${transportTag} already exists — this transport version is already released.`)
+    process.exit(1)
+  }
+
+  // The fragments are the only release-notes source, so a release whose
+  // rendered body is empty — no fragments at all, or only fragments with no
+  // bullet lines — would publish an empty `## [<version>]` section: refuse
+  // instead, on a dry run too (a dry run is release validation, not an
+  // exemption). Prose that looks like notes is not a bullet; it is reported
+  // below and never rendered.
+  const fragments = readFragments()
+  for (const fragment of fragments) {
+    if (fragment.dropped > 0) {
+      console.error(
+        `Notice: ${fragment.file}: ignored ${fragment.dropped} non-bullet line(s) — notes publish only "- " bullets.`,
+      )
+    }
+  }
+  const refusal = notesRefusal(fragments)
+  if (refusal !== null) {
+    console.error(`Error: ${refusal}`)
+    process.exit(1)
+  }
+  const body = buildSectionBody(fragments)
+
+  // Whether this run actually moved the fragments into the archive, so a
+  // caller can tell "release prepared" from "nothing consumed" (dry run, or an
+  // existing section for this version) without guessing from the tree.
+  let archived = false
+
+  // Write only outside a dry run: a dry run validates and prints the resolved
+  // versions exactly like a real run, then leaves the working tree untouched.
+  if (!dryRun) {
+    pkg.version = version
+    // Preserve repo formatting: 2-space indent + trailing newline. Bumping only
+    // the version keeps `git diff package.json` to that one line.
+    writeFileSync(PKG_PATH, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+
+    transportsPkg.version = transportVersion
+    writeFileSync(TRANSPORTS_PKG_PATH, `${JSON.stringify(transportsPkg, null, 2)}\n`, 'utf8')
+
+    // Root changelog only: the transports package has no generated changelog.
+    // Fragments are archived only when this run rendered them: an existing
+    // section (idempotent re-run) must not consume them unrendered.
+    if (updateChangelog(version, body)) {
+      archived = archiveFragments(version, fragments)
+    } else {
+      console.error(
+        `Notice: CHANGELOG.md already has a "## [${version}]" section — fragments left in .changes/unreleased/: ${fragments.map((fragment) => fragment.file).join(', ')}.`,
+      )
+    }
+  }
+
+  // The workflow captures VERSION; the remaining lines are informational and
+  // let a dry run show both derived tags without touching the tree.
+  if (dryRun) console.log('DRY_RUN=1')
+  console.log(`FRAGMENTS=${fragments.length}`)
+  console.log(`VERSION=${version}`)
+  console.log(`TAG=v${version}`)
+  console.log(`TRANSPORT_VERSION=${transportVersion}`)
+  console.log(`TRANSPORT_TAG=${transportTag}`)
+  console.log(`ARCHIVED=${archived ? 1 : 0}`)
+}
+
+/**
+ * Whether this module is the entry point of the running process. Compared by
+ * real path, not by string: a symlinked checkout (macOS `/tmp` ->
+ * `/private/tmp`, a linked worktree, an npm bin shim) runs `argv[1]` through a
+ * different path than `import.meta.url`, and a string comparison would silently
+ * no-op the whole release flow. Importing the module (tests) stays a no-op.
+ */
+function isDirectExecution() {
+  if (process.argv[1] === undefined) return false
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return false
+  }
+}
+
+// Run only when executed directly (node scripts/prepare-release.mjs):
+// importing the module (tests) must not start the release flow.
+if (isDirectExecution()) {
+  main()
+}