@aperant/framework 0.6.5 → 0.6.7

package/src/cli/release-notes/compile.mjs

@@ -0,0 +1,261 @@
+/**
+ * release-notes/compile.mjs — tag-time narrative compiler.
+ *
+ * Reads every `<output_dir>/_unreleased/PR-*.md` fragment, classifies each
+ * against the project's persona roster + filter mode, and writes
+ * `<output_dir>/<tag>.md`. Atomic-rename pattern: the fragments dir is
+ * cleared only AFTER the compiled file lands on disk, so a crash mid-write
+ * cannot orphan fragments without their compiled output.
+ *
+ * Non-negotiable invariant (ID-6): unmapped fragments (no persona tag, or
+ * a tag the roster doesn't recognize) MUST appear in a `## Needs Triage`
+ * section. Never silent-drop. The triage section is the human curator's
+ * safety net — its presence is asserted by TD-3.
+ */
+
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { loadProjectConfig } from '../config/load.mjs'
+import { readPersonas } from '../personas/sidecar.mjs'
+import { atomicWriteText } from '../util/atomic-write.mjs'
+import { resolveOutputDir, validateTag } from './output-dir.mjs'
+import { buildPersonaTierMap, classifyFragment, isNoneSentinel } from './persona-filter.mjs'
+
+const VALID_MODES = new Set(['primary', 'primary+secondary', 'all'])
+
+/** Pre-compiled at module level to avoid recompilation in the sort comparator (PRF-001). */
+const PR_FILENAME_RE = /^PR-(\d+)\.md$/
+
+/**
+ * Parse a single fragment file. Tolerant: missing keys default to empty
+ * strings; the body after `## Release note` is read verbatim.
+ *
+ * @param {string} text
+ * @returns {{ pr: string, date: string, persona: string, note: string, raw: string }}
+ */
+function parseFragment(text) {
+	const lines = text.split('\n')
+	let pr = ''
+	let date = ''
+	let persona = ''
+	let note = ''
+	let noteStart = -1
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		if (line.startsWith('pr: ')) pr = line.slice(4).trim()
+		else if (line.startsWith('date: ')) date = line.slice(6).trim()
+		else if (line.startsWith('persona: ')) persona = line.slice(9).trim()
+		else if (line.startsWith('## Release note')) {
+			noteStart = i
+			break
+		}
+	}
+	if (noteStart >= 0) {
+		note = lines
+			.slice(noteStart + 1)
+			.join('\n')
+			.trim()
+	}
+	return { pr, date, persona, note, raw: text }
+}
+
+/**
+ * Resolve the output dir and persona filter mode from config + flag override.
+ *
+ * @param {string} projectDir
+ * @param {string | null} flagOverride
+ * @returns {{ outputDir: string, personaFilter: 'primary' | 'primary+secondary' | 'all' }}
+ */
+function resolveContext(projectDir, flagOverride) {
+	const config = loadProjectConfig(projectDir)
+	const outputDir = resolveOutputDir(projectDir, flagOverride)
+	const filterRaw = config?.changelog?.release_notes?.persona_filter
+	const personaFilter =
+		typeof filterRaw === 'string' && VALID_MODES.has(filterRaw)
+			? /** @type {'primary' | 'primary+secondary' | 'all'} */ (filterRaw)
+			: 'primary+secondary'
+	return { outputDir, personaFilter }
+}
+
+/**
+ * @typedef {Object} CompileInput
+ * @property {string} projectDir
+ * @property {string} tag
+ * @property {string | null} outputDir
+ */
+
+/**
+ * @typedef {Object} CompileResult
+ * @property {boolean} written
+ * @property {string} path
+ * @property {number} fragmentsTotal
+ * @property {number} fragmentsInBody
+ * @property {number} fragmentsInTriage
+ * @property {number} fragmentsFiltered
+ * @property {boolean} clearedUnreleased
+ */
+
+/**
+ * Compile every `_unreleased/PR-*.md` fragment into `<output_dir>/<tag>.md`.
+ *
+ * @param {CompileInput} input
+ * @returns {CompileResult}
+ */
+export function compileTag(input) {
+	validateTag(input.tag)
+	const { outputDir, personaFilter } = resolveContext(input.projectDir, input.outputDir)
+	const fragmentsDir = join(outputDir, '_unreleased')
+	const targetPath = join(outputDir, `${input.tag}.md`)
+
+	const rawFiles = existsSync(fragmentsDir)
+		? readdirSync(fragmentsDir).filter((f) => PR_FILENAME_RE.test(f))
+		: []
+	// Pre-compute PR numbers once to avoid re-running the regex in the comparator (PRF-001).
+	const withNumbers = rawFiles.map((f) => ({
+		f,
+		n: Number.parseInt(PR_FILENAME_RE.exec(f)?.[1] ?? '0', 10),
+	}))
+	withNumbers.sort((a, b) => a.n - b.n)
+	const fragments = withNumbers.map(({ f }) => ({
+		filename: f,
+		...parseFragment(readFileSync(join(fragmentsDir, f), 'utf-8')),
+	}))
+
+	const personasEnvelope = readPersonas(input.projectDir)
+	const tierMap = buildPersonaTierMap(personasEnvelope)
+
+	/** @type {Array<{ pr: string, date: string, persona: string, note: string, tier: 'primary' | 'secondary' | 'tertiary' }>} */
+	const bodyEntries = []
+	/** @type {Array<{ pr: string, date: string, persona: string, note: string, reason: string }>} */
+	const triageEntries = []
+	let filteredCount = 0
+
+	for (const frag of fragments) {
+		const { bucket, resolvedTier } = classifyFragment(frag.persona, tierMap, personaFilter)
+		if (bucket === 'body' && resolvedTier !== null && resolvedTier !== 'unknown') {
+			bodyEntries.push({
+				pr: frag.pr,
+				date: frag.date,
+				persona: frag.persona,
+				note: frag.note,
+				tier: resolvedTier,
+			})
+		} else if (bucket === 'triage' || resolvedTier === 'unknown') {
+			// Use the shared sentinel predicate so this label stays in lockstep
+			// with persona-filter.mjs's NONE_SENTINELS set. Without it, the
+			// classifier and labeller drift (e.g. literal "null" persona tags
+			// land in triage as 'unknown-persona' instead of 'no-persona-tag').
+			// 'unknown' tier (malformed tier value in personas.json) is also
+			// routed here — never silent-drop (ID-6 / LOG-001).
+			const reason = isNoneSentinel(frag.persona)
+				? 'no-persona-tag'
+				: resolvedTier === 'unknown'
+					? 'unknown-tier'
+					: 'unknown-persona'
+			triageEntries.push({
+				pr: frag.pr,
+				date: frag.date,
+				persona: frag.persona,
+				note: frag.note,
+				reason,
+			})
+		} else {
+			filteredCount++
+		}
+	}
+
+	const compiled = renderCompiled({
+		tag: input.tag,
+		body: bodyEntries,
+		triage: triageEntries,
+		filter: personaFilter,
+	})
+
+	atomicWriteText(targetPath, compiled)
+
+	// Clear _unreleased only AFTER the compiled file is durably written.
+	let clearedUnreleased = false
+	if (existsSync(fragmentsDir) && fragments.length > 0) {
+		for (const frag of fragments) {
+			rmSync(join(fragmentsDir, frag.filename), { force: true })
+		}
+		clearedUnreleased = true
+	}
+
+	return {
+		written: true,
+		path: targetPath,
+		fragmentsTotal: fragments.length,
+		fragmentsInBody: bodyEntries.length,
+		fragmentsInTriage: triageEntries.length,
+		fragmentsFiltered: filteredCount,
+		clearedUnreleased,
+	}
+}
+
+/**
+ * Render the per-tag compiled body.
+ *
+ * Layout:
+ *   # Release <tag>
+ *
+ *   (per-tier sections — primary first, then secondary, then tertiary
+ *    when filter==='all'. Each section's entries sorted by PR number.)
+ *
+ *   ## Needs Triage   (only when triage[] non-empty)
+ *
+ * @param {{
+ *   tag: string,
+ *   body: Array<{ pr: string, date: string, persona: string, note: string, tier: 'primary' | 'secondary' | 'tertiary' }>,
+ *   triage: Array<{ pr: string, date: string, persona: string, note: string, reason: string }>,
+ *   filter: 'primary' | 'primary+secondary' | 'all',
+ * }} input
+ * @returns {string}
+ */
+function renderCompiled(input) {
+	const lines = []
+	lines.push(`# Release ${input.tag}`)
+	lines.push('')
+	lines.push(`<!-- persona_filter: ${input.filter} -->`)
+	lines.push('')
+
+	const tiersInOrder = /** @type {const} */ (['primary', 'secondary', 'tertiary'])
+	for (const tier of tiersInOrder) {
+		const rows = input.body.filter((e) => e.tier === tier)
+		if (rows.length === 0) continue
+		lines.push(`## ${capitalize(tier)} personas`)
+		lines.push('')
+		for (const row of rows) {
+			lines.push(`- **PR #${row.pr}** (${row.persona}): ${row.note}`)
+		}
+		lines.push('')
+	}
+
+	if (input.triage.length > 0) {
+		lines.push('## Needs Triage')
+		lines.push('')
+		lines.push('_These fragments lack a recognized persona tag. Curate before publishing._')
+		lines.push('')
+		for (const row of input.triage) {
+			const personaLabel = row.persona && row.persona !== '(none)' ? row.persona : '(no tag)'
+			lines.push(`- **PR #${row.pr}** (${personaLabel}, ${row.reason}): ${row.note}`)
+		}
+		lines.push('')
+	}
+
+	if (input.body.length === 0 && input.triage.length === 0) {
+		lines.push('_No fragments to compile._')
+		lines.push('')
+	}
+
+	return lines.join('\n')
+}
+
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+function capitalize(s) {
+	return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1)
+}

package/src/cli/release-notes/draft.mjs

@@ -0,0 +1,133 @@
+/**
+ * release-notes/draft.mjs — towncrier-style per-PR fragment writer.
+ *
+ * Writes `<output_dir>/_unreleased/PR-<n>.md` for a single PR. Idempotent:
+ * if the target file already exists with byte-identical content, the call
+ * is a no-op and the envelope reports `written: false`. The same input
+ * always produces the same bytes on disk — that is the load-bearing
+ * invariant the news-fragment pattern depends on (zero merge conflicts
+ * on the unreleased file, AC2).
+ *
+ * Deterministic I/O only. No LLM calls. No prompt templates. The host
+ * LLM authors the note text and hands it in via --note.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { atomicWriteText } from '../util/atomic-write.mjs'
+import { resolveOutputDir } from './output-dir.mjs'
+
+/**
+ * Build the canonical fragment body. The shape is intentionally simple +
+ * stable so the compile step can parse it back without YAML / front-matter
+ * gymnastics. Date is the calling day in UTC, not a wall-clock timestamp —
+ * idempotency demands the same inputs produce the same bytes regardless of
+ * when the day they're called within.
+ *
+ * @param {{
+ *   pr: number,
+ *   note: string,
+ *   persona: string | null,
+ *   date: string,
+ *   commits: string[],
+ * }} input
+ * @returns {string}
+ */
+export function renderFragment(input) {
+	const personaLine = input.persona ? `persona: ${input.persona}` : 'persona: (none)'
+	const commitsLine =
+		input.commits.length === 0 ? 'commits: (none)' : `commits: ${input.commits.join(', ')}`
+	return [
+		`# PR-${input.pr}`,
+		'',
+		`date: ${input.date}`,
+		`pr: ${input.pr}`,
+		personaLine,
+		commitsLine,
+		'',
+		'## Release note',
+		'',
+		input.note.trim(),
+		'',
+	].join('\n')
+}
+
+/**
+ * Resolve the commits referencing a PR by number. Best-effort — if git is
+ * unavailable or no matching commits are found, returns an empty array.
+ * Caller can pass commits explicitly via --commits to bypass git inspection.
+ *
+ * @param {string} projectDir
+ * @param {number} pr
+ * @returns {string[]}
+ */
+function discoverCommitsForPr(projectDir, pr) {
+	try {
+		const out = execFileSync(
+			'git',
+			['-C', projectDir, 'log', '--no-merges', `--grep=#${pr}\\b`, '--format=%H'],
+			{ encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
+		)
+		return out
+			.split('\n')
+			.map((s) => s.trim())
+			.filter((s) => s.length > 0)
+			.map((sha) => sha.slice(0, 12))
+	} catch {
+		return []
+	}
+}
+
+/**
+ * @typedef {Object} DraftInput
+ * @property {string} projectDir
+ * @property {number} pr
+ * @property {string} note
+ * @property {string | null} persona
+ * @property {string | null} outputDir   // CLI flag override (relative to projectDir or absolute).
+ * @property {string[] | null} commits   // explicit commit list; null → autodetect via git log.
+ * @property {string | null} date        // ISO yyyy-mm-dd; null → today (UTC).
+ */
+
+/**
+ * @typedef {Object} DraftResult
+ * @property {boolean} written
+ * @property {string} path
+ * @property {string} reason     // 'created' | 'no-change' | 'updated'
+ */
+
+/**
+ * Write the PR fragment idempotently. Returns the result envelope.
+ *
+ * @param {DraftInput} input
+ * @returns {DraftResult}
+ */
+export function writeDraft(input) {
+	const outputDir = resolveOutputDir(input.projectDir, input.outputDir)
+	const unreleasedDir = join(outputDir, '_unreleased')
+	const target = join(unreleasedDir, `PR-${input.pr}.md`)
+
+	const date = input.date ?? new Date().toISOString().slice(0, 10)
+	const commits = input.commits ?? discoverCommitsForPr(input.projectDir, input.pr)
+
+	const body = renderFragment({
+		pr: input.pr,
+		note: input.note,
+		persona: input.persona,
+		date,
+		commits,
+	})
+
+	if (existsSync(target)) {
+		const existing = readFileSync(target, 'utf-8')
+		if (existing === body) {
+			return { written: false, path: target, reason: 'no-change' }
+		}
+		atomicWriteText(target, body)
+		return { written: true, path: target, reason: 'updated' }
+	}
+	atomicWriteText(target, body)
+	return { written: true, path: target, reason: 'created' }
+}

package/src/cli/release-notes/output-dir.mjs

@@ -0,0 +1,52 @@
+/**
+ * release-notes/output-dir.mjs — shared output directory resolver.
+ *
+ * Extracted from draft.mjs, compile.mjs, and publish.mjs to eliminate
+ * copy-paste duplication (QUA-003).
+ */
+
+import { resolve } from 'node:path'
+
+import { loadProjectConfig } from '../config/load.mjs'
+
+const DEFAULT_OUTPUT_DIR = 'docs/releases'
+
+/** Allowlist for release tag values — semver-compatible subset. */
+const TAG_PATTERN = /^[a-zA-Z0-9._-]+$/
+
+/**
+ * Validate a release tag. Throws if the tag contains path-traversal
+ * sequences (`..`, `/`) or characters outside the semver-compatible
+ * allowlist. Defends path.join calls in compile.mjs and publish.mjs
+ * against directory escape (SEC-001).
+ *
+ * @param {string} tag
+ * @returns {void}
+ */
+export function validateTag(tag) {
+	if (tag.includes('..') || tag.includes('/')) {
+		throw new Error(`Invalid --tag: "${tag}" contains path-traversal sequences (.. or /)`)
+	}
+	if (!TAG_PATTERN.test(tag)) {
+		throw new Error(
+			`Invalid --tag: "${tag}" must match /^[a-zA-Z0-9._-]+$/ (no spaces or special characters)`,
+		)
+	}
+}
+
+/**
+ * Resolve the canonical output directory from flag override → config → default.
+ * Flag override wins when present. Returns an absolute path.
+ *
+ * @param {string} projectDir
+ * @param {string | null} flagOverride
+ * @returns {string}
+ */
+export function resolveOutputDir(projectDir, flagOverride) {
+	const config = loadProjectConfig(projectDir)
+	const configured = config?.changelog?.release_notes?.output_dir
+	return resolve(
+		projectDir,
+		flagOverride ?? (typeof configured === 'string' ? configured : DEFAULT_OUTPUT_DIR),
+	)
+}

package/src/cli/release-notes/persona-filter.mjs

@@ -0,0 +1,126 @@
+/**
+ * release-notes/persona-filter.mjs — shared persona-filter logic.
+ *
+ * The compile + autodraft surfaces both need the same predicate: given a
+ * persona id (or name) extracted from a fragment, the project's
+ * `.aperant/personas.json` roster, and a filter mode, decide whether the
+ * fragment belongs in the user-facing body, in the "Needs Triage" bucket,
+ * or filtered out entirely.
+ *
+ * Three filter modes (config.changelog.release_notes.persona_filter):
+ *
+ *   - 'primary'             — only personas whose `tier === 'primary'`.
+ *   - 'primary+secondary'   — primary OR secondary. DEFAULT.
+ *   - 'all'                 — every tier passes (no filter).
+ *
+ * Triage rules (ID-6 in spec.md, never-silent-drop invariant):
+ *
+ *   - Fragment with no persona tag         → bucket = 'triage'.
+ *   - Fragment with a tag that doesn't
+ *     resolve to a known persona in the
+ *     roster                              → bucket = 'triage'.
+ *   - Fragment whose persona DOES resolve
+ *     but is filtered out by the mode     → bucket = 'filtered'.
+ *   - Fragment whose persona resolves AND
+ *     passes the mode                     → bucket = 'body', with the
+ *                                            resolved tier exposed for
+ *                                            grouping in compile output.
+ *
+ * The matcher is case-insensitive on persona names. Empty string and the
+ * literal sentinel `(none)` are both treated as "no tag" — the draft
+ * renderer writes `persona: (none)` when no --persona flag is passed.
+ */
+
+/** @typedef {'primary' | 'secondary' | 'tertiary' | 'unknown'} PersonaTier */
+/** @typedef {'body' | 'triage' | 'filtered'} FilterBucket */
+
+const NONE_SENTINELS = new Set(['', '(none)', 'none', 'null', 'undefined'])
+
+/**
+ * True when the raw persona-tag string from a fragment should be treated as
+ * "no tag" (and therefore routed to triage with reason `no-persona-tag`).
+ * Mirrors `NONE_SENTINELS` so callers — notably `compile.mjs`'s triage-reason
+ * labeller — stay in lockstep with the classifier. Case-insensitive.
+ *
+ * @param {string | null | undefined} raw
+ * @returns {boolean}
+ */
+export function isNoneSentinel(raw) {
+	const normalized = (raw ?? '').trim().toLowerCase()
+	return NONE_SENTINELS.has(normalized)
+}
+
+/**
+ * Read tier + name out of a persona envelope row (the shape personas.mjs
+ * persists). Tier lives inside `ui_json` (a JSON string). Returns null
+ * when the row is unusable.
+ *
+ * @param {{ ui_json?: unknown }} row
+ * @returns {{ name: string, tier: PersonaTier } | null}
+ */
+export function extractPersonaIdentity(row) {
+	if (!row || typeof row !== 'object') return null
+	if (typeof row.ui_json !== 'string') return null
+	let parsed
+	try {
+		parsed = JSON.parse(row.ui_json)
+	} catch {
+		return null
+	}
+	if (!parsed || typeof parsed !== 'object') return null
+	const name = typeof parsed.name === 'string' ? parsed.name.trim() : ''
+	const tierRaw = typeof parsed.tier === 'string' ? parsed.tier.trim().toLowerCase() : ''
+	if (name.length === 0) return null
+	/** @type {PersonaTier} */
+	const tier =
+		tierRaw === 'primary' || tierRaw === 'secondary' || tierRaw === 'tertiary' ? tierRaw : 'unknown'
+	return { name, tier }
+}
+
+/**
+ * Build a name → tier map from a personas envelope.
+ *
+ * @param {{ personas?: Array<{ ui_json?: unknown }> } | null | undefined} envelope
+ * @returns {Map<string, PersonaTier>}
+ */
+export function buildPersonaTierMap(envelope) {
+	/** @type {Map<string, PersonaTier>} */
+	const map = new Map()
+	if (!envelope || !Array.isArray(envelope.personas)) return map
+	for (const row of envelope.personas) {
+		const identity = extractPersonaIdentity(row)
+		if (!identity) continue
+		map.set(identity.name.toLowerCase(), identity.tier)
+	}
+	return map
+}
+
+/**
+ * Classify a fragment's persona tag against the roster + filter mode.
+ *
+ * @param {string | null | undefined} personaTag   The raw tag from the fragment.
+ * @param {Map<string, PersonaTier>} tierMap        From `buildPersonaTierMap`.
+ * @param {'primary' | 'primary+secondary' | 'all'} mode
+ * @returns {{ bucket: FilterBucket, resolvedName: string | null, resolvedTier: PersonaTier | null }}
+ */
+export function classifyFragment(personaTag, tierMap, mode) {
+	const normalized = (personaTag ?? '').trim().toLowerCase()
+	if (normalized.length === 0 || NONE_SENTINELS.has(normalized)) {
+		return { bucket: 'triage', resolvedName: null, resolvedTier: null }
+	}
+	const tier = tierMap.get(normalized)
+	if (tier === undefined) {
+		// Tag was set but the roster doesn't recognize it — never silent-drop.
+		return { bucket: 'triage', resolvedName: personaTag ?? null, resolvedTier: null }
+	}
+	if (mode === 'all') {
+		return { bucket: 'body', resolvedName: personaTag ?? null, resolvedTier: tier }
+	}
+	if (mode === 'primary' && tier !== 'primary') {
+		return { bucket: 'filtered', resolvedName: personaTag ?? null, resolvedTier: tier }
+	}
+	if (mode === 'primary+secondary' && tier !== 'primary' && tier !== 'secondary') {
+		return { bucket: 'filtered', resolvedName: personaTag ?? null, resolvedTier: tier }
+	}
+	return { bucket: 'body', resolvedName: personaTag ?? null, resolvedTier: tier }
+}

package/src/cli/release-notes/publish.mjs

@@ -0,0 +1,128 @@
+/**
+ * release-notes/publish.mjs — `gh release create/edit` shell.
+ *
+ * Reads `<output_dir>/<tag>.md` and shells `gh release create <tag>
+ * --notes-file <path>` (or `gh release edit` if a release already exists
+ * for that tag). When `gh` is unavailable on the host, returns a graceful
+ * `{status: 'skipped', reason: 'gh-not-found'}` envelope rather than
+ * crashing — AC4.
+ *
+ * Tests inject a custom shell via the GH_BIN env var (mocked to a no-op
+ * shell script) so the publish branch of TD-5 can run without making a
+ * real network call.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { resolveOutputDir, validateTag } from './output-dir.mjs'
+
+/**
+ * @typedef {Object} PublishInput
+ * @property {string} projectDir
+ * @property {string} tag
+ * @property {string | null} outputDir
+ * @property {boolean} dryRun
+ */
+
+/**
+ * @typedef {{
+ *   status: 'ok',
+ *   mode: 'created' | 'edited' | 'dry-run',
+ *   notesPath: string,
+ * } | {
+ *   status: 'skipped',
+ *   reason: 'gh-not-found' | 'notes-not-found' | 'gh-failed',
+ *   notesPath?: string,
+ *   exit_code?: number | null,
+ *   stderr?: string | null,
+ * }} PublishResult
+ */
+
+/**
+ * Resolve which `gh` binary to use. Defaults to `gh` on PATH; tests
+ * override via the GH_BIN env var (only honored in NODE_ENV=test).
+ *
+ * @returns {string}
+ */
+function ghBin() {
+	if (process.env.NODE_ENV === 'test') {
+		const override = process.env.GH_BIN
+		if (override && override.length > 0) return override
+	}
+	return 'gh'
+}
+
+/**
+ * Detect whether `gh` is available on the host. Uses `which` semantics:
+ * `gh --version` exit-0 → available. Any error path → unavailable.
+ *
+ * @returns {boolean}
+ */
+function ghAvailable() {
+	try {
+		const result = spawnSync(ghBin(), ['--version'], { stdio: ['ignore', 'ignore', 'ignore'] })
+		return result.status === 0
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Check whether a release already exists for the given tag.
+ *
+ * @param {string} projectDir
+ * @param {string} tag
+ * @returns {boolean}
+ */
+function releaseExists(projectDir, tag) {
+	try {
+		const result = spawnSync(ghBin(), ['release', 'view', tag, '--json', 'tagName'], {
+			cwd: projectDir,
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		return result.status === 0
+	} catch {
+		return false
+	}
+}
+
+/**
+ * @param {PublishInput} input
+ * @returns {PublishResult}
+ */
+export function publishTag(input) {
+	validateTag(input.tag)
+	const outputDir = resolveOutputDir(input.projectDir, input.outputDir)
+	const notesPath = join(outputDir, `${input.tag}.md`)
+	if (!existsSync(notesPath)) {
+		return { status: 'skipped', reason: 'notes-not-found', notesPath }
+	}
+	if (input.dryRun) {
+		return { status: 'ok', mode: 'dry-run', notesPath }
+	}
+	if (!ghAvailable()) {
+		return { status: 'skipped', reason: 'gh-not-found', notesPath }
+	}
+	const exists = releaseExists(input.projectDir, input.tag)
+	const verb = exists ? 'edit' : 'create'
+	const args = ['release', verb, input.tag, '--notes-file', notesPath]
+	// `gh release edit` only takes --notes-file; `gh release create` takes
+	// --notes-file too and a positional tag — same argv order works.
+	try {
+		execFileSync(ghBin(), args, {
+			cwd: input.projectDir,
+			stdio: ['ignore', 'pipe', 'pipe'],
+		})
+	} catch (err) {
+		return {
+			status: 'skipped',
+			reason: 'gh-failed',
+			notesPath,
+			exit_code: err.status ?? null,
+			stderr: err.stderr?.toString() ?? null,
+		}
+	}
+	return { status: 'ok', mode: exists ? 'edited' : 'created', notesPath }
+}