@specship/specship 0.11.0

package/scripts/offline-install.ps1

@@ -0,0 +1,148 @@
+<#
+.SYNOPSIS
+  Offline / air-gapped install of SpecShip from this source folder (Windows).
+
+.DESCRIPTION
+  Assumes the client workstation has:
+    - Node.js (>=18 <25) and npm on PATH
+    - npm configured against a registry it CAN reach (e.g. a private mirror)
+    - No git, no public GitHub access required
+
+  Does NOT call git, does NOT download anything from github.com. Dependencies
+  are pulled from whatever registry npm is already pointed at.
+
+.PARAMETER SkipClaude
+  Skip wiring Claude Code at the end.
+
+.PARAMETER Undo
+  Unlink the global `specship` symlink and exit.
+
+.EXAMPLE
+  .\scripts\offline-install.ps1
+  .\scripts\offline-install.ps1 -SkipClaude
+  .\scripts\offline-install.ps1 -Undo
+#>
+[CmdletBinding()]
+param(
+  [switch]$SkipClaude,
+  [switch]$Undo
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Resolve repo root from this script's location (no git).
+$Repo = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+Set-Location $Repo
+
+$Pkg     = node -p "require('./package.json').name"
+$Version = node -p "require('./package.json').version"
+
+if ($Undo) {
+  Write-Host "[offline-install] unlinking $Pkg"
+  & npm unlink -g $Pkg 2>$null
+  Write-Host "[offline-install] done"
+  exit 0
+}
+
+# --- Node version gate ---------------------------------------------------
+# Tighter than package.json engines (>=18 <25): the runtime needs node:sqlite
+# (Node 22.5+) AND that SQLite must have FTS5 compiled in. SpecShip's own
+# release bundle pins v24.16.0 for that reason; older Node builds either lack
+# node:sqlite entirely or ship SQLite without FTS5.
+$NodeMajor = [int](node -p "process.versions.node.split('.')[0]")
+$NodeMinor = [int](node -p "process.versions.node.split('.')[1]")
+if ($NodeMajor -lt 22 -or
+    ($NodeMajor -eq 22 -and $NodeMinor -lt 5) -or
+    $NodeMajor -ge 25) {
+  $nv = node --version
+  Write-Error "[offline-install] Node $nv is unsupported. Requires >=22.5 <25 (Node 24.x recommended)."
+  exit 1
+}
+
+# --- FTS5 capability probe ---------------------------------------------
+# Fail fast with a clear remediation message instead of letting `specship init`
+# die with a cryptic "no such module: fts5" deep inside indexing. node:sqlite
+# is present from 22.5+, but FTS5 is only enabled in newer Node builds —
+# Node 22.x typically ships SQLite without it.
+$probeScript = @'
+try {
+  const { DatabaseSync } = require('node:sqlite');
+  const db = new DatabaseSync(':memory:');
+  db.exec("CREATE VIRTUAL TABLE t USING fts5(x)");
+  console.log('OK');
+} catch (e) {
+  console.log('FAIL:' + e.message);
+}
+'@
+$probe = (node -e $probeScript 2>$null)
+if ($probe -eq 'OK') {
+  # FTS5 ok
+} elseif ($probe -like 'FAIL:*') {
+  $msg = $probe.Substring(5)
+  $nv  = node --version
+  Write-Error @"
+[offline-install] SQLite probe failed: $msg
+
+SpecShip requires Node.js whose bundled SQLite has FTS5 enabled. Your Node
+($nv) does not. Install Node 24.x and re-run this script. SpecShip's
+release bundle pins v24.16.0 as the known-good version.
+"@
+  exit 1
+} else {
+  Write-Error "[offline-install] unable to probe node:sqlite. Need Node >=22.5 (24.x recommended)."
+  exit 1
+}
+
+$Registry = npm config get registry
+Write-Host "[offline-install] repo:     $Repo"
+Write-Host "[offline-install] package:  $Pkg@$Version"
+Write-Host "[offline-install] node:     $(node --version)"
+Write-Host "[offline-install] registry: $Registry"
+
+# --- install deps --------------------------------------------------------
+if (Test-Path 'package-lock.json') {
+  Write-Host "[offline-install] npm ci"
+  & npm ci
+} else {
+  Write-Host "[offline-install] npm install"
+  & npm install
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# --- build ---------------------------------------------------------------
+Write-Host "[offline-install] npm run build"
+& npm run build
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# --- link as global specship -------------------------------------------
+Write-Host "[offline-install] npm link"
+& npm link
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# Avoid PS 7+ null-conditional (?.) — locked-down Windows clients often ship
+# only Windows PowerShell 5.1, where ?. fails to parse.
+$cmd    = Get-Command specship -ErrorAction SilentlyContinue
+$Linked = if ($cmd) { $cmd.Source } else { '(not on PATH)' }
+Write-Host "[offline-install] specship -> $Linked"
+
+# --- wire Claude Code (non-interactive) ---------------------------------
+# Invoke the just-built binary directly instead of relying on `specship` being
+# visible on PATH in this PowerShell session — `npm link`'s shim may not be
+# picked up until the user opens a new shell.
+if (-not $SkipClaude) {
+  Write-Host "[offline-install] wiring Claude Code"
+  & node (Join-Path $Repo 'dist/bin/specship.js') install --target claude -y
+  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
+Write-Host ""
+Write-Host "[OK] SpecShip $Version installed offline from source."
+Write-Host "  binary: $Linked"
+Write-Host "  source: $Repo"
+Write-Host ""
+Write-Host "Next:"
+Write-Host "  specship --version"
+Write-Host "  cd <your-project>; specship init; specship index"
+Write-Host ""
+Write-Host "To uninstall:"
+Write-Host "  .\scripts\offline-install.ps1 -Undo"

package/scripts/offline-install.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+#
+# Offline / air-gapped install of SpecShip from this source folder.
+#
+# Assumes the client workstation has:
+#   - Node.js (>=18 <25) and npm on PATH
+#   - npm configured against a registry it CAN reach (e.g. a private mirror)
+#   - No git, no public GitHub access required
+#
+# Does NOT call git, does NOT download anything from github.com. Dependencies
+# are pulled from whatever registry npm is already pointed at.
+#
+# Usage:
+#   ./scripts/offline-install.sh                    # build, link, wire Claude Code
+#   ./scripts/offline-install.sh --skip-claude      # build + link only
+#   ./scripts/offline-install.sh --undo             # unlink the global symlink
+#
+# After install:  `specship --version` should print the package.json version.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+REPO="$(pwd)"
+
+PKG=$(node -p "require('./package.json').name")
+VERSION=$(node -p "require('./package.json').version")
+
+# --- undo path ---------------------------------------------------------------
+if [ "${1:-}" = "--undo" ]; then
+  echo "[offline-install] unlinking ${PKG}"
+  npm unlink -g "${PKG}" >/dev/null 2>&1 || true
+  echo "[offline-install] done"
+  exit 0
+fi
+
+SKIP_CLAUDE=0
+[ "${1:-}" = "--skip-claude" ] && SKIP_CLAUDE=1
+
+# --- Node version gate -------------------------------------------------------
+# Tighter than package.json engines (>=18 <25): the runtime needs node:sqlite
+# (Node 22.5+) AND that SQLite must have FTS5 compiled in. SpecShip's own
+# release bundle pins v24.16.0 for that reason; older Node builds either lack
+# node:sqlite entirely or ship SQLite without FTS5.
+NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]")
+NODE_MINOR=$(node -p "process.versions.node.split('.')[1]")
+if [ "$NODE_MAJOR" -lt 22 ] \
+  || { [ "$NODE_MAJOR" -eq 22 ] && [ "$NODE_MINOR" -lt 5 ]; } \
+  || [ "$NODE_MAJOR" -ge 25 ]; then
+  echo "[offline-install] error: Node $(node --version) is unsupported. Requires >=22.5 <25 (Node 24.x recommended)." >&2
+  exit 1
+fi
+
+# --- FTS5 capability probe ---------------------------------------------------
+# Fail fast with a clear remediation message instead of letting `specship init`
+# die with a cryptic "no such module: fts5" deep inside indexing. node:sqlite
+# is present from 22.5+, but FTS5 is only enabled in newer Node builds —
+# Node 22.x typically ships SQLite without it.
+PROBE=$(node -e "
+  try {
+    const { DatabaseSync } = require('node:sqlite');
+    const db = new DatabaseSync(':memory:');
+    db.exec('CREATE VIRTUAL TABLE t USING fts5(x)');
+    console.log('OK');
+  } catch (e) {
+    console.log('FAIL:' + e.message);
+  }
+" 2>/dev/null)
+case "$PROBE" in
+  OK) ;;
+  FAIL:*)
+    cat >&2 <<EOF
+[offline-install] error: SQLite probe failed: ${PROBE#FAIL:}
+
+SpecShip requires Node.js whose bundled SQLite has FTS5 enabled. Your Node
+($(node --version)) does not. Install Node 24.x and re-run:
+
+  nvm install 24 && nvm use 24
+  ./scripts/offline-install.sh
+
+(SpecShip's release bundle pins v24.16.0 as the known-good version.)
+EOF
+    exit 1
+    ;;
+  *)
+    echo "[offline-install] error: unable to probe node:sqlite. Need Node >=22.5 (24.x recommended)." >&2
+    exit 1
+    ;;
+esac
+
+echo "[offline-install] repo:    ${REPO}"
+echo "[offline-install] package: ${PKG}@${VERSION}"
+echo "[offline-install] node:    $(node --version)"
+echo "[offline-install] registry: $(npm config get registry)"
+
+# --- install deps (offline-friendly: respects whatever registry npm is on) ---
+#
+# --ignore-scripts skips native-module postinstalls (notably better-sqlite3,
+# whose node-gyp rebuild needs a C toolchain that an air-gapped workstation
+# usually doesn't have). SpecShip treats better-sqlite3 as optional anyway —
+# without it the wasm SQLite path takes over, which is what the offline-
+# install flow expects.
+if [ -f package-lock.json ]; then
+  echo "[offline-install] npm ci --ignore-scripts"
+  npm ci --ignore-scripts
+else
+  echo "[offline-install] npm install --ignore-scripts"
+  npm install --ignore-scripts
+fi
+
+# --- build -------------------------------------------------------------------
+# Skip the build when this is a pre-compiled drop (no tsconfig.json + a
+# populated dist/ already on disk). The release tarball is shipped pre-built;
+# only a source checkout has tsconfig.json and needs `npm run build`.
+if [ -f tsconfig.json ]; then
+  echo "[offline-install] npm run build"
+  npm run build
+else
+  echo "[offline-install] skipping build (pre-compiled dist/ found)"
+fi
+
+# --- link as global specship ------------------------------------------------
+echo "[offline-install] npm link"
+npm link
+
+LINKED=$(command -v specship || echo "(not on PATH)")
+echo "[offline-install] specship -> ${LINKED}"
+
+# --- wire Claude Code (non-interactive) --------------------------------------
+# Invoke the just-built binary directly instead of relying on `specship` being
+# visible on PATH in this shell session — `npm link`'s shim may not be picked
+# up until the user opens a new shell.
+if [ "$SKIP_CLAUDE" -eq 0 ]; then
+  echo "[offline-install] wiring Claude Code"
+  node "$REPO/dist/bin/specship.js" install --target claude -y
+fi
+
+cat <<EOF
+
+✓ SpecShip ${VERSION} installed offline from source.
+  binary:    ${LINKED}
+  source:    ${REPO}
+
+Next:
+  specship --version
+  cd <your-project> && specship init && specship index
+
+To uninstall:
+  ./scripts/offline-install.sh --undo
+EOF

package/scripts/pack-npm.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+#
+# Assemble the npm thin-installer packages from built bundles (esbuild pattern).
+#
+# Produces, under release/npm/:
+#   specship-<target>/   one per built bundle — the vendored Node + app, tagged
+#                         with os/cpu so npm installs only the matching one.
+#   main/                 the @specship/specship shim package: a tiny bin
+#                         that execs the matching platform bundle, with every
+#                         platform package in optionalDependencies.
+#
+# The release pipeline then `npm publish`es each dir. This does NOT touch the
+# repo's package.json — the dev/from-source path keeps working; the *published*
+# main package's shape is generated here.
+#
+# Prereq: run build-bundle.sh for each target first (release/specship-*.tar.gz).
+# Usage:  scripts/pack-npm.sh [version]    (default: version from package.json)
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERSION="${1:-$(node -p "require('$ROOT/package.json').version")}"
+SCOPE="@specship"
+REL="$ROOT/release"
+NPM="$REL/npm"
+
+rm -rf "$NPM"
+mkdir -p "$NPM/main"
+
+shopt -s nullglob
+archives=("$REL"/specship-*.tar.gz "$REL"/specship-*.zip)
+[ ${#archives[@]} -gt 0 ] || { echo "[pack-npm] no bundles in $REL — run build-bundle.sh first" >&2; exit 1; }
+
+targets=()
+for archive in "${archives[@]}"; do
+  fname="$(basename "$archive")"
+  case "$fname" in
+    *.tar.gz) base="${fname%.tar.gz}" ;;   # specship-<target>
+    *.zip)    base="${fname%.zip}" ;;
+  esac
+  target="${base#specship-}"             # <target>, e.g. darwin-arm64 / win32-x64
+  os="${target%-*}"                       # darwin | linux | win32
+  arch="${target##*-}"                    # arm64 | x64
+  pkgdir="$NPM/$base"
+  mkdir -p "$pkgdir"
+  case "$fname" in
+    *.zip)
+      tmpx="$(mktemp -d)"
+      unzip -q "$archive" -d "$tmpx"
+      mv "$tmpx/specship-${target}"/* "$pkgdir"/
+      rm -rf "$tmpx"
+      nodefile="node.exe"
+      ;;
+    *)
+      tar -xzf "$archive" -C "$pkgdir" --strip-components=1
+      nodefile="node"
+      ;;
+  esac
+  VERSION="$VERSION" SCOPE="$SCOPE" TARGET="$target" OSV="$os" ARCHV="$arch" NODEFILE="$nodefile" \
+    node -e '
+      const fs=require("fs");
+      fs.writeFileSync(process.argv[1], JSON.stringify({
+        name: `${process.env.SCOPE}/specship-${process.env.TARGET}`,
+        version: process.env.VERSION,
+        description: `SpecShip self-contained bundle for ${process.env.TARGET}`,
+        os: [process.env.OSV], cpu: [process.env.ARCHV],
+        files: [process.env.NODEFILE, "lib", "bin"],
+        license: "MIT"
+      }, null, 2) + "\n");
+    ' "$pkgdir/package.json"
+  targets+=("$target")
+  echo "[pack-npm] ${SCOPE}/specship-${target}@${VERSION}"
+done
+
+# Main shim package.
+#   npm-shim.js  CLI/MCP launcher (execs the bundled Node) — the `bin`.
+#   npm-sdk.js   programmatic/embedded entry (#354): re-exports the installed
+#                platform bundle's compiled library — the `main`.
+#   dist/        the .d.ts tree only (types). The runtime .js stays in the
+#                per-platform bundle so its deps aren't duplicated here.
+cp "$ROOT/scripts/npm-shim.js" "$NPM/main/npm-shim.js"
+cp "$ROOT/scripts/npm-sdk.js" "$NPM/main/npm-sdk.js"
+[ -f "$ROOT/README.md" ] && cp "$ROOT/README.md" "$NPM/main/README.md"
+
+# Ship the type declarations so `types`/`exports.types` resolve. Built from this
+# same release, so they can't skew from the runtime npm-sdk.js re-exports.
+[ -f "$ROOT/dist/index.d.ts" ] || ( echo "[pack-npm] building dist for .d.ts" >&2 && cd "$ROOT" && npm run build >/dev/null )
+ROOT="$ROOT" DEST="$NPM/main" node -e '
+  const fs=require("fs"), path=require("path");
+  const src=path.join(process.env.ROOT,"dist"), dest=path.join(process.env.DEST,"dist");
+  fs.cpSync(src, dest, { recursive:true, filter(s){
+    try { return fs.statSync(s).isDirectory() || s.endsWith(".d.ts"); } catch (e) { return false; }
+  }});
+'
+
+VERSION="$VERSION" SCOPE="$SCOPE" TARGETS="${targets[*]}" \
+  node -e '
+    const fs=require("fs");
+    const opt={};
+    for (const t of process.env.TARGETS.split(/\s+/).filter(Boolean))
+      opt[`${process.env.SCOPE}/specship-${t}`]=process.env.VERSION;
+    fs.writeFileSync(process.argv[1], JSON.stringify({
+      name: `${process.env.SCOPE}/specship`,
+      version: process.env.VERSION,
+      description: "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
+      bin: { specship: "npm-shim.js" },
+      main: "npm-sdk.js",
+      types: "dist/index.d.ts",
+      exports: {
+        ".": { types: "./dist/index.d.ts", default: "./npm-sdk.js" },
+        "./package.json": "./package.json"
+      },
+      optionalDependencies: opt,
+      files: ["npm-shim.js","npm-sdk.js","dist","README.md"],
+      license: "MIT"
+    }, null, 2) + "\n");
+  ' "$NPM/main/package.json"
+
+echo "[pack-npm] ${SCOPE}/specship@${VERSION} (${#targets[@]} platform packages in optionalDependencies)"
+echo "[pack-npm] output: $NPM"

package/scripts/prepare-release.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * Promote `## [Unreleased]` content into `## [<version>]` in CHANGELOG.md
+ * so the release.yml workflow's `extract-release-notes.mjs <version>` call
+ * picks up everything that landed since the last release.
+ *
+ * **Why this exists:** the release workflow used to do a literal
+ * `extract-release-notes.mjs <version>` lookup with an `[Unreleased]`
+ * fallback. The fallback only triggers if the `[<version>]` block
+ * doesn't exist at all — and in practice maintainers sometimes had a
+ * sparse `[<version>]` block pre-populated (e.g. one early fix
+ * documented before the rest of the work landed). The workflow then
+ * extracted that sparse block, ignoring the much larger `[Unreleased]`
+ * section above it — so the published release notes were missing most
+ * of what shipped. See v0.9.5 for the canonical post-mortem.
+ *
+ * **What it does**, idempotently:
+ *
+ *   Case A — `[<version>]` does not exist yet:
+ *     Rename the `[Unreleased]` header to `[<version>] - <YYYY-MM-DD>`
+ *     and add a fresh empty `## [Unreleased]` block above it. This is
+ *     the common case.
+ *
+ *   Case B — `[<version>]` exists AND `[Unreleased]` has content:
+ *     Merge `[Unreleased]`'s sub-sections (### Added / ### Fixed /
+ *     ### Changed / ### Removed / ### Deprecated / ### Security) into
+ *     the corresponding sub-sections of `[<version>]`. Unmatched
+ *     sub-sections are appended to `[<version>]`. The `[Unreleased]`
+ *     block is then emptied.
+ *
+ *   Case C — `[Unreleased]` has no content:
+ *     No-op. Exit 0. Re-runs of the workflow are safe.
+ *
+ * **Where the date comes from:** for Case A, `<YYYY-MM-DD>` is the
+ * UTC date at run time. Matches the existing CHANGELOG convention.
+ *
+ * **Usage:**
+ *
+ *   node scripts/prepare-release.mjs                # reads version from package.json
+ *   node scripts/prepare-release.mjs 1.2.3          # explicit version
+ *
+ * **Output:**
+ *
+ *   Writes CHANGELOG.md in place. Prints a summary line to stdout
+ *   like `prepare-release: 0.9.5 — promoted 6 Unreleased entries`.
+ *   Exits non-zero on parse failures.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const CHANGELOG_PATH = resolve(process.cwd(), 'CHANGELOG.md');
+
+function readPackageVersion() {
+  const pkg = JSON.parse(readFileSync(resolve(process.cwd(), 'package.json'), 'utf8'));
+  if (!pkg.version) throw new Error('package.json has no "version" field');
+  return pkg.version;
+}
+
+function todayUtcIsoDate() {
+  // YYYY-MM-DD in UTC. Matches the CHANGELOG's existing convention
+  // (the existing dated entries don't disclose a timezone, but UTC is
+  // stable across runners and is what the workflow's runner produces
+  // by default anyway).
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Split the CHANGELOG into a header preface + an ordered list of
+ * version blocks `{ header, body[] }`, preserving line content
+ * verbatim so we can re-join without surprises.
+ */
+function parseChangelog(text) {
+  const lines = text.split('\n');
+  const versionHeaderRe = /^## \[([^\]]+)\](?:\s+-\s+(.+))?\s*$/;
+  const preface = [];
+  const blocks = []; // { header: string, name: string, body: string[] }
+  let cur = null;
+  for (const line of lines) {
+    const m = line.match(versionHeaderRe);
+    if (m) {
+      if (cur) blocks.push(cur);
+      cur = { header: line, name: m[1], date: m[2] ?? null, body: [] };
+    } else if (cur) {
+      cur.body.push(line);
+    } else {
+      preface.push(line);
+    }
+  }
+  if (cur) blocks.push(cur);
+  return { preface, blocks };
+}
+
+function joinChangelog({ preface, blocks }) {
+  const parts = [preface.join('\n')];
+  for (const b of blocks) {
+    // Reconstruct: header + body. The block body INCLUDES the blank
+    // line after the header (it was captured verbatim).
+    parts.push([b.header, ...b.body].join('\n'));
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Split a block body into ordered sub-sections keyed by their
+ * `### Heading`. Lines before the first `### Heading` go in
+ * `leading`. Preserves the original (line-array) body inside each
+ * sub-section so we can splice cleanly when merging.
+ */
+function splitSubsections(body) {
+  const subsectionRe = /^### (\w+)\s*$/;
+  const leading = [];
+  const subs = []; // { heading: 'Added' | 'Fixed' | …, headerLine: string, body: string[] }
+  let cur = null;
+  for (const line of body) {
+    const m = line.match(subsectionRe);
+    if (m) {
+      if (cur) subs.push(cur);
+      cur = { heading: m[1], headerLine: line, body: [] };
+    } else if (cur) {
+      cur.body.push(line);
+    } else {
+      leading.push(line);
+    }
+  }
+  if (cur) subs.push(cur);
+  return { leading, subs };
+}
+
+function rebuildBody({ leading, subs }) {
+  const parts = [];
+  if (leading.length) parts.push(leading.join('\n'));
+  for (const s of subs) {
+    parts.push([s.headerLine, ...s.body].join('\n'));
+  }
+  return parts.join('\n').split('\n');
+}
+
+/**
+ * Return true when the block has any meaningful entries (a bullet line
+ * starting with `-`, `*`, or a digit) — vs. being empty / just
+ * whitespace / just sub-section headers with nothing under them.
+ */
+function blockHasContent(body) {
+  for (const line of body) {
+    if (/^\s*([-*]|\d+\.)\s+/.test(line)) return true;
+  }
+  return false;
+}
+
+/**
+ * Trim trailing blank lines from an array of lines, then return.
+ * Keeps the output tidy when merging.
+ */
+function trimTrailingBlank(arr) {
+  let i = arr.length;
+  while (i > 0 && /^\s*$/.test(arr[i - 1])) i--;
+  return arr.slice(0, i);
+}
+
+function main() {
+  const versionArg = process.argv[2];
+  const version = versionArg || readPackageVersion();
+
+  const text = readFileSync(CHANGELOG_PATH, 'utf8');
+  const parsed = parseChangelog(text);
+
+  const unrelIdx = parsed.blocks.findIndex((b) => b.name === 'Unreleased');
+  const verIdx = parsed.blocks.findIndex((b) => b.name === version);
+
+  if (unrelIdx === -1) {
+    console.log(`prepare-release: no [Unreleased] block — nothing to do`);
+    return;
+  }
+
+  const unrel = parsed.blocks[unrelIdx];
+  if (!blockHasContent(unrel.body)) {
+    console.log(`prepare-release: [Unreleased] is empty — nothing to do`);
+    return;
+  }
+
+  if (verIdx === -1) {
+    // Case A — promote Unreleased → [version].
+    const today = todayUtcIsoDate();
+    const promoted = {
+      header: `## [${version}] - ${today}`,
+      name: version,
+      date: today,
+      body: trimTrailingBlank(unrel.body).concat(['']), // single trailing blank
+    };
+    const emptied = {
+      header: `## [Unreleased]`,
+      name: 'Unreleased',
+      date: null,
+      body: ['', ''], // two blank lines for the next round of entries
+    };
+    parsed.blocks.splice(unrelIdx, 1, emptied, promoted);
+    const next = joinChangelog(parsed);
+    writeFileSync(CHANGELOG_PATH, appendLinkRef(next, version));
+    console.log(`prepare-release: ${version} — renamed [Unreleased] to [${version}] - ${today}`);
+    return;
+  }
+
+  // Case B — merge Unreleased sub-sections into the existing
+  // [version] sub-sections. New sub-section headings encountered in
+  // Unreleased that don't exist in [version] get appended.
+  const ver = parsed.blocks[verIdx];
+  const unrelSubs = splitSubsections(unrel.body);
+  const verSubs = splitSubsections(ver.body);
+
+  let merged = 0;
+  for (const us of unrelSubs.subs) {
+    const target = verSubs.subs.find((s) => s.heading === us.heading);
+    const usBody = trimTrailingBlank(us.body);
+    if (usBody.length === 0) continue;
+    if (target) {
+      // Append Unreleased's entries to the end of the version's matching
+      // sub-section, keeping their original ordering. Insert a separating
+      // blank line if the existing sub-section doesn't already end in one.
+      const existing = trimTrailingBlank(target.body);
+      const sep = existing.length && !/^\s*$/.test(existing[existing.length - 1]) ? [''] : [];
+      target.body = existing.concat(sep, usBody, ['']);
+    } else {
+      // Append the whole sub-section to the end.
+      verSubs.subs.push({
+        heading: us.heading,
+        headerLine: us.headerLine,
+        body: usBody.concat(['']),
+      });
+    }
+    merged += usBody.filter((l) => /^\s*([-*]|\d+\.)\s+/.test(l)).length;
+  }
+
+  ver.body = rebuildBody(verSubs);
+  // Empty out Unreleased.
+  unrel.body = ['', ''];
+
+  const merged_text = joinChangelog(parsed);
+  writeFileSync(CHANGELOG_PATH, appendLinkRef(merged_text, version));
+  console.log(`prepare-release: ${version} — merged ${merged} Unreleased entries into existing [${version}] block`);
+}
+
+/**
+ * Append a `[X.Y.Z]: https://github.com/selvakumarEsra/specship/releases/tag/vX.Y.Z`
+ * link reference at the end of the file IF one doesn't already exist. The
+ * link ref is what makes `## [X.Y.Z]` heading text auto-link to its tag in
+ * GitHub's renderer; without it the heading still renders, just unlinked.
+ *
+ * Idempotent. The existing CHANGELOG mixes link refs scattered through the
+ * file and a sorted block at the bottom — we just append at the very end,
+ * which CommonMark accepts regardless.
+ */
+function appendLinkRef(text, version) {
+  const refLine = `[${version}]: https://github.com/selvakumarEsra/specship/releases/tag/v${version}`;
+  // Already there? Look for a line that EQUALS this (anywhere in the file)
+  // to keep idempotency robust against the scattered-vs-block layout.
+  const lines = text.split('\n');
+  if (lines.some((l) => l.trim() === refLine)) return text;
+  // Append, separated by a blank line from the prior content. Preserve a
+  // single trailing newline at EOF.
+  const trailingNewline = text.endsWith('\n') ? '' : '\n';
+  return text + trailingNewline + refLine + '\n';
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`prepare-release: ${err?.message ?? err}`);
+  process.exit(1);
+}