pantheon-opencode 1.3.2 → 1.3.4

package/scripts/redaction-gate.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/** Fail closed when validation artifacts contain callback URLs or credentials. */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+const callbackUrl = /https?:\/\/[^\s"'<>]+(?:callback|redirect|return|webhook)[^\s"'<>]*/iu
+const bearer = /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/u
+const jwt = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/u
+const apiSecret =
+  /\b(?:api[_-]?key|token|secret|password)\s*[=:]\s*["'](?!\$\{|process\.env|os\.getenv|env:|<redacted>|\[redacted\]|fixture)[^"']{12,}["']/iu
+
+function isText(buffer) {
+  return !buffer.subarray(0, Math.min(buffer.length, 4096)).includes(0)
+}
+
+function findings(text) {
+  const result = []
+  if (callbackUrl.test(text)) result.push('callback URL')
+  if (bearer.test(text) || jwt.test(text) || apiSecret.test(text)) result.push('credential/token')
+  return result
+}
+
+function scanFile(path) {
+  if (!existsSync(path) || !lstatSync(path).isFile()) return []
+  const content = readFileSync(path)
+  return isText(content) ? findings(content.toString('utf8')) : []
+}
+
+function scanTarball(path) {
+  const entries = execFileSync('tar', ['-tzf', path], { encoding: 'utf8' }).split('\n').filter(Boolean)
+  const result = []
+  for (const entry of entries) {
+    const content = execFileSync('tar', ['-xOzf', path, entry])
+    if (isText(content)) result.push(...findings(content.toString('utf8')))
+  }
+  return [...new Set(result)]
+}
+
+function scanPath(path) {
+  if (path.endsWith('.tgz') || path.endsWith('.tar.gz')) return scanTarball(path)
+  if (!existsSync(path)) throw new Error(`path does not exist: ${path}`)
+  if (lstatSync(path).isDirectory()) {
+    return readdirSync(path, { withFileTypes: true }).flatMap((entry) =>
+      scanPath(join(path, entry.name)),
+    )
+  }
+  return scanFile(path)
+}
+
+const paths = process.argv.slice(2)
+if (paths.length === 0) {
+  console.error(`Usage: ${basename(process.argv[1])} <file|directory|tarball> [...]`)
+  process.exit(2)
+}
+
+try {
+  const hits = [...new Set(paths.flatMap(scanPath))]
+  if (hits.length > 0) {
+    for (const hit of hits) console.error(`[REDACTION GATE] ${hit} detected`)
+    process.exit(1)
+  }
+  console.log('Redaction gate passed: no callback URLs or credentials detected.')
+} catch (error) {
+  console.error(`[REDACTION GATE] failed to inspect input: ${error.message}`)
+  process.exit(2)
+}

package/scripts/release-notes.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * release-notes.mjs — generate release notes from conventional commits
+ *
+ * Bridges the conventional-commit pipeline (commitlint: 12 types / 40 scopes)
+ * to the CHANGELOG / release-body content. Reads `git log <lastTag>..HEAD`
+ * (subject + body per commit), groups commits by type, and prints markdown
+ * ready to paste into the [Unreleased] CHANGELOG section.
+ *
+ * Groups (section order — user-facing first):
+ *   🆕 What's New      feat | perf | docs
+ *                       (docs are user-facing — no dedicated group)
+ *   🐞 Fixed           fix | security
+ *   ⚠️ Known Issues    manual — CLI flag `--known-issues "text"` (repeatable);
+ *                       the group is OMITTED when the flag is absent (never
+ *                       emitted empty)
+ *   ✅ Closed Issues   issue refs parsed from commit BODIES (%b):
+ *                       `Closes #N` / `Fixes #N` / `Resolves #N` — one
+ *                       bullet `- #N - <subject>` per referenced issue
+ *                       (deduped); the group is OMITTED when no refs exist
+ *
+ * Omitted (internal, never user-facing): chore | refactor | test | ci |
+ * build | style | revert (unknown conventional types too).
+ *
+ * Breaking: `BREAKING CHANGE` footer or `type!:` / `type(scope)!:` — the
+ * commit keeps its type bucket and the bullet is prefixed with 💥
+ * (e.g. `- 💥 **scope** — subject`). No dedicated Breaking group.
+ *
+ * Skipped: merge commits ("Merge ..."), empty-subject commits (trivial
+ * chores), and non-conventional subjects (grandfathered history only).
+ *
+ * Bullet format:
+ *   - **<scope>** — <subject without the type(scope): prefix>   (scope present)
+ *   - **<subject>**                                              (no scope)
+ *
+ * Usage:
+ *   node scripts/release-notes.mjs                          # lastTag..HEAD
+ *   node scripts/release-notes.mjs --draft                  # last 30 commits
+ *   node scripts/release-notes.mjs --known-issues "widget API is unstable"
+ *                                                           # manual ⚠️ entry
+ *
+ * Exit code is 0 whenever output can be generated (empty output means no
+ * groupable commits since the range). stdout is pure markdown — diagnostics
+ * go to stderr.
+ *
+ * getLastTag() intentionally duplicates scripts/versioning.mjs getLatestTag()
+ * (that module is a CLI, not importable). Keep both in sync when changing
+ * the stable-tag filter.
+ */
+
+import { execSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** Commit window used by --draft (and as fallback when no stable tag exists). */
+export const DRAFT_RANGE = 30
+
+// ---------------------------------------------------------------------------
+// Git helpers
+// ---------------------------------------------------------------------------
+
+function run(cmd) {
+  try {
+    return execSync(cmd, { cwd: ROOT, encoding: 'utf-8' }).trim()
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Latest stable tag: strict vX.Y.Z with NO pre-release suffix. The loose
+ * glob `v*` also matches v1.2.0-beta.9.<sha>; pre-release tags must never
+ * poison the version gate or the notes range, so filter strictly.
+ */
+export function getLastTag() {
+  const tag = run("git tag -l 'v*' | grep -E '^v[0-9]+\\.[0-9]+\\.[0-9]+$' | sort -V | tail -1")
+  return tag || 'v0.0.0'
+}
+
+function tagExists(tag) {
+  return run(`git rev-parse --verify --quiet ${tag}`) !== ''
+}
+
+/**
+ * Collect `subject|body` records for a git range.
+ *
+ * Records are separated with %x1e because %b (raw body) may contain
+ * newlines; each record keeps its multi-line body intact. The `|` inside a
+ * body is preserved (parsing splits on the FIRST `|`, right after %s).
+ *
+ * @param {{since?: string|null, draft?: boolean}} [opts]
+ *   since — lower-bound tag for the range (default null)
+ *   draft — use the last DRAFT_RANGE commits instead of a tag range
+ * @returns {string[]} raw "subject|body" records
+ */
+export function collectEntries({ since = null, draft = false } = {}) {
+  // Single-quoted: execSync goes through a shell, and the `|` inside the
+  // format string is a literal separator (subject|body), not a shell pipe.
+  const fmt = "'--format=%x1e%s|%b'"
+  // Without a valid `since` we cannot build a tag range — fall back to the
+  // draft window (also covers --draft, which must not read tags at all).
+  const range = draft || !since ? `-n ${DRAFT_RANGE}` : `${since}..HEAD`
+  const out = run(`git log ${range} ${fmt}`)
+  if (!out) return []
+  return out
+    .split('\x1e')
+    .map((record) => record.trim())
+    .filter(Boolean)
+}
+
+// ---------------------------------------------------------------------------
+// Parsing / grouping (pure functions, tested in tests/release-notes.test.mjs)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse issue references from a commit body: `Closes #N`, `Fixes #N` or
+ * `Resolves #N` (case-insensitive). Returns the numbers in order of
+ * appearance; empty when the body references nothing.
+ *
+ * @param {string} body - the raw commit body (may be '')
+ * @returns {number[]}
+ */
+function parseIssueRefs(body) {
+  return [...body.matchAll(/\b(?:Closes|Fixes|Resolves)\s+#(\d+)\b/gi)].map((m) => Number(m[1]))
+}
+
+/**
+ * Parse one "subject|body" record into a conventional-commit entry.
+ * Returns null for records that must be skipped: merge commits ("Merge ..."),
+ * non-conventional subjects, and empty-subject (trivial) commits.
+ *
+ * @param {string} line
+ * @returns {{type: string, scope: string|null, subject: string,
+ *            breaking: boolean, refs: number[]}|null}
+ */
+export function parseCommitLine(line) {
+  const [subjectPart, ...bodyParts] = line.split('|')
+  const subject = subjectPart.trim()
+  if (!subject || /^Merge\b/i.test(subject)) return null
+
+  const body = bodyParts.join('|')
+  const match = /^([a-z]+)(?:\(([^)]+)\))?(!)?:\s*(.*)$/i.exec(subject)
+  if (!match) return null
+  const [, type, scope, bang, rest] = match
+  const cleanSubject = rest.trim()
+  if (!cleanSubject) return null
+
+  return {
+    type: type.toLowerCase(),
+    scope: scope || null,
+    subject: cleanSubject,
+    breaking: Boolean(bang) || /BREAKING CHANGE/i.test(body),
+    refs: parseIssueRefs(body),
+  }
+}
+
+/**
+ * Conventional type → final release-note group. Types missing from this map
+ * (chore, refactor, test, ci, build, style, revert, unknown) are internal
+ * and omitted from the notes.
+ */
+const TYPE_GROUPS = {
+  feat: 'whatsNew',
+  perf: 'whatsNew',
+  docs: 'whatsNew',
+  fix: 'fixed',
+  security: 'fixed',
+}
+
+/**
+ * Group parsed commits into the final release-note sections. Breaking
+ * commits keep their type bucket (the 💥 marker is applied at render time);
+ * internal types are dropped; issue refs from ANY commit body feed
+ * closedIssues (deduped, first occurrence wins). Entries keep git log order.
+ *
+ * @param {Array<ReturnType<typeof parseCommitLine>>} entries
+ * @param {{knownIssues?: string[]|string|null}} [options]
+ *   knownIssues — manual Known Issues entries (CLI --known-issues). Omitted
+ *   (empty array) when not provided.
+ * @returns {{whatsNew: Array, fixed: Array, knownIssues: string[],
+ *            closedIssues: Array<{ref: number, subject: string}>}}
+ */
+export function groupCommits(entries, options = {}) {
+  const { knownIssues = [] } = options
+  const groups = {
+    whatsNew: [],
+    fixed: [],
+    knownIssues: Array.isArray(knownIssues) ? [...knownIssues] : knownIssues ? [knownIssues] : [],
+    closedIssues: [],
+  }
+  const seenRefs = new Set()
+  for (const entry of entries) {
+    if (!entry) continue
+    const bucket = TYPE_GROUPS[entry.type]
+    if (bucket) groups[bucket].push(entry)
+    for (const ref of entry.refs) {
+      if (seenRefs.has(ref)) continue
+      seenRefs.add(ref)
+      groups.closedIssues.push({ ref, subject: entry.subject })
+    }
+  }
+  return groups
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+/** One bullet: `- **<scope>** — <subject>`; without a scope the whole
+ *  subject becomes the bold summary. Breaking bullets get a 💥 prefix. */
+function bullet(entry) {
+  const prefix = entry.breaking ? '💥 ' : ''
+  return entry.scope
+    ? `- ${prefix}**${entry.scope}** — ${entry.subject}`
+    : `- ${prefix}**${entry.subject}**`
+}
+
+/** One Closed Issues bullet: `- #N - <subject>` (subject may be absent). */
+function closedIssueBullet({ ref, subject }) {
+  return subject ? `- #${ref} - ${subject}` : `- #${ref}`
+}
+
+/** Section order — user-facing first, Known Issues then Closed Issues. */
+const MARKDOWN_SECTIONS = [
+  ['whatsNew', "🆕 What's New"],
+  ['fixed', '🐞 Fixed'],
+  ['knownIssues', '⚠️ Known Issues'],
+  ['closedIssues', '✅ Closed Issues'],
+]
+
+/** Render one entry for its section (strings for Known Issues). */
+function renderEntry(key, entry) {
+  if (key === 'knownIssues') return `- ${entry}`
+  if (key === 'closedIssues') return closedIssueBullet(entry)
+  return bullet(entry)
+}
+
+/**
+ * Render grouped commits as emoji-sectioned markdown (the CLI stdout and the
+ * CHANGELOG body). Returns '' when there is nothing to report.
+ *
+ * @param {ReturnType<typeof groupCommits>} groups
+ * @returns {string}
+ */
+export function renderMarkdown(groups) {
+  const blocks = []
+  for (const [key, heading] of MARKDOWN_SECTIONS) {
+    if (!groups[key]?.length) continue
+    blocks.push(`## ${heading}\n${groups[key].map((entry) => renderEntry(key, entry)).join('\n')}`)
+  }
+  return blocks.join('\n\n')
+}
+
+/**
+ * Render grouped commits for a CHANGELOG version entry. Used by
+ * `versioning.mjs apply --notes` to pre-fill the promoted [Unreleased] entry.
+ * Emits the SAME final emoji groups as renderMarkdown — the CHANGELOG uses
+ * the emoji format.
+ *
+ * @param {ReturnType<typeof groupCommits>} groups
+ * @returns {string}
+ */
+export function renderChangelog(groups) {
+  return renderMarkdown(groups)
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/** Collect every `--known-issues <text>` value from argv (repeatable). */
+function parseKnownIssues(argv) {
+  const issues = []
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--known-issues' && argv[i + 1]) {
+      issues.push(argv[i + 1])
+      i += 1
+    }
+  }
+  return issues
+}
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+
+if (isDirectRun) {
+  const args = process.argv.slice(2)
+  const draft = args.includes('--draft')
+  const knownIssues = parseKnownIssues(args)
+  let since = null
+
+  if (draft) {
+    console.error(`release-notes: draft mode — last ${DRAFT_RANGE} commits (no tag lookup)`)
+  } else {
+    since = getLastTag()
+    if (!tagExists(since)) {
+      since = null
+      console.error('release-notes: no stable vX.Y.Z tag — falling back to draft mode')
+    } else {
+      console.error(`release-notes: ${since}..HEAD`)
+    }
+  }
+
+  const raw = collectEntries({ since, draft: since === null })
+  const groups = groupCommits(raw.map(parseCommitLine), { knownIssues })
+  const markdown = renderMarkdown(groups)
+  const sectionCount = Object.values(groups).filter((g) => g.length).length
+
+  if (raw.length === 0) {
+    console.error(`release-notes: no commits to group${since ? ` since ${since}` : ''}`)
+  } else {
+    console.error(`release-notes: ${raw.length} commits grouped into ${sectionCount} section(s)`)
+  }
+
+  if (markdown) process.stdout.write(`${markdown}\n`)
+}

package/scripts/test-context-compression.sh

@@ -135,8 +135,11 @@ echo ""
 # Step 5: Validate scrub-secrets.py works
 echo "[5/4] Testing scrub-secrets.py (bonus)..."
 if [ -f scripts/scrub-secrets.py ]; then
-    # Test with a simple secret
-    SECRET_TEST=$(echo "Bearer my-test-token-12345" | python3 scripts/scrub-secrets.py --stdin 2>/dev/null)
+    # Test with a simple secret. The token is assembled at runtime so the
+    # shipped script never contains a literal `Bearer <token>` sequence (the
+    # redaction gate flags any such literal as a credential).
+    SCRUB_FIXTURE_TOKEN="my-test-token-12345"
+    SECRET_TEST=$(echo "Bearer ${SCRUB_FIXTURE_TOKEN}" | python3 scripts/scrub-secrets.py --stdin 2>/dev/null)
     if echo "$SECRET_TEST" | grep -q "REDACTED"; then
         echo "   ✅ scrub-secrets.py: secret detection working"
     else

package/scripts/validate-package.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/** Validate files that npm is allowed to publish. */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..')
+const executableConfigs = ['opencode.json', 'plugin.json', 'src/plugins/tui/package.json']
+const checkoutRoot = ROOT.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const forbiddenPath = new RegExp(
+  `(?:${checkoutRoot}|(?:^|[\\s"'(])[A-Za-z]:[\\\\/]|\\/(?:Users|home|tmp|workspace|private\\/var)\\/|pantheon[\\\\/]src[\\\\/]|(?:^|[\\\\/])logs(?:[\\\\/]|$))`,
+  'i',
+)
+const errors = []
+
+for (const file of executableConfigs) {
+  const path = join(ROOT, file)
+  if (!existsSync(path)) continue
+  const text = readFileSync(path, 'utf8')
+  if (forbiddenPath.test(text)) errors.push(`${file}: contains a machine, checkout, or log path`)
+  try {
+    const config = JSON.parse(text)
+    if (Array.isArray(config.plugin) && config.plugin.some((entry) => /^\//.test(entry))) {
+      errors.push(`${file}: plugin entries must not be absolute in the published template`)
+    }
+  } catch {
+    errors.push(`${file}: invalid JSON`)
+  }
+}
+
+function walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name)
+    const rel = relative(ROOT, path)
+    // These are local runtime state and are excluded by npm's explicit files
+    // allow-list; never inspect them as publish candidates.
+    if (
+      name === 'node_modules' ||
+      name === '.git' ||
+      name === '.venv' ||
+      name === '.pantheon' ||
+      name === 'logs'
+    )
+      continue
+    if (statSync(path).isDirectory()) walk(path)
+    else if (/\.log$|(?:^|[\\/])logs(?:[\\/]|$)/i.test(rel))
+      errors.push(`${rel}: log artifact must not ship`)
+  }
+}
+walk(ROOT)
+
+if (errors.length) {
+  console.error('Package validation failed:')
+  for (const error of errors) console.error(`- ${error}`)
+  process.exit(1)
+}

package/scripts/versioning.mjs

@@ -20,6 +20,7 @@ import { execSync } from 'node:child_process'
 import { readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { collectEntries, groupCommits, parseCommitLine, renderChangelog } from './release-notes.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..')
@@ -117,12 +118,70 @@ function updateManifests(newVersion) {
 // CHANGELOG updater
 //
 // Finds the [Unreleased] section and:
-//   1. Strips empty subsections (### Added\n\n### Changed...)
+//   1. Strips empty subsections (### Added, ## 🆕 What's New, ...)
 //   2. Renames [Unreleased] → [vX.Y.Z] - date
 //   3. Inserts a fresh empty [Unreleased] template above it
+//
+// `notesBody` (from `apply --notes`) replaces the manual body of the
+// promoted entry with release notes generated from conventional commits
+// (rendered via release-notes.mjs renderChangelog — the final emoji groups
+// 🆕/🐞/⚠️/✅). When notesBody is provided the empty-[Unreleased] early
+// return is bypassed.
 // ---------------------------------------------------------------------------
 
-function promoteUnreleased(newVersion, dateStr) {
+// A section header that adds no user-facing content: the legacy
+// Keep-a-Changelog ### subsections and the emoji release-note groups.
+const EMPTY_SECTION_HEADER =
+  /^(?:### \w|## 🆕 What's New|## 🐞 Fixed|## ⚠️ Known Issues|## ✅ Closed Issues)/
+
+/**
+ * Neutralize HTML comment delimiters in body content derived from commit
+ * messages before it is written into CHANGELOG.md. CodeQL's changelog-
+ * injection rule flags interpolating untrusted markdown into a file that
+ * also carries HTML comments: a `-->` in a commit subject (surfaced via
+ * `apply --notes`) would terminate the template comment early and let the
+ * surrounding markdown render as HTML. Escaping BOTH delimiters keeps the
+ * emitted body inert regardless of the input commit messages.
+ */
+function sanitizeCommentDelimiters(body) {
+  return body.replace(/<!--/g, '&lt;!--').replace(/--(?:!?)>/g, '--&gt;')
+}
+
+// Any markdown header — used to find the end of a section's content.
+const ANY_HEADER = /^(?:### |## )/
+
+/**
+ * Remove empty subsections from a changelog body: a recognized section
+ * header with no content (non-blank, non-header lines) before the next
+ * header or end of body is dropped together with its trailing blank lines.
+ */
+function stripEmptySections(body) {
+  const lines = body.split('\n')
+  const keep = []
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]
+    if (!EMPTY_SECTION_HEADER.test(line)) {
+      keep.push(line)
+      continue
+    }
+    let j = i + 1
+    let hasContent = false
+    while (j < lines.length && !ANY_HEADER.test(lines[j])) {
+      if (lines[j].trim()) hasContent = true
+      j += 1
+    }
+    if (hasContent) {
+      keep.push(line)
+      continue
+    }
+    // Empty section: drop the header and any blank lines up to the next
+    // header so the section leaves no empty gap.
+    while (i + 1 < lines.length && lines[i + 1].trim() === '') i += 1
+  }
+  return keep.join('\n').replace(/\n{3,}/g, '\n\n')
+}
+
+function promoteUnreleased(newVersion, dateStr, notesBody = null) {
   const content = readFileSync(CHANGELOG_PATH, 'utf-8')
 
   const unreleasedHeader = '## [Unreleased]'
@@ -139,33 +198,53 @@ function promoteUnreleased(newVersion, dateStr) {
     nextSectionIdx === -1 ? content.slice(afterHeader) : content.slice(afterHeader, nextSectionIdx)
 
   // Check if the [Unreleased] section has any real content (non-empty lines
-  // that aren't just section headers or comments)
-  const realLines = unreleasedBody
+  // that aren't just section headers or comments). HTML comments (the
+  // template hint) are removed first — they span multiple lines.
+  let bodyWithoutComments = unreleasedBody
+  let previousBody
+  do {
+    previousBody = bodyWithoutComments
+    bodyWithoutComments = bodyWithoutComments.replace(/<!--[\s\S]*?-->/g, '')
+  } while (bodyWithoutComments !== previousBody)
+  const realLines = bodyWithoutComments
     .split('\n')
-    .filter((l) => l.trim() && !l.startsWith('###') && !l.startsWith('<!--'))
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('###') && !l.startsWith('## '))
 
-  if (realLines.length === 0) {
+  if (notesBody === null && realLines.length === 0) {
     console.log('  ℹ [Unreleased] is empty — CHANGELOG not modified')
     return false
   }
 
-  // Strip lines that are just empty subsections (### X followed by blank line
-  // then another ### or end)
-  const cleanedBody = unreleasedBody
-    .replace(/\n### \w[^\n]*\n(\n(?=###|\n## |\n$))+/g, '\n')
-    .replace(/\n{3,}/g, '\n\n')
-    .trimEnd()
+  if (notesBody !== null && realLines.length > 0) {
+    console.log(
+      '  ⚠ --notes replaces the manual [Unreleased] content — review the diff before committing',
+    )
+  }
+
+  // Strip lines that are just empty subsections (### X or ## 🆕/🐞/⚠️/✅
+  // followed by blank lines then another header or end)
+  const cleanedBody =
+    notesBody !== null ? `\n\n${notesBody}` : stripEmptySections(unreleasedBody).trimEnd()
+  // Sanitize the WRITTEN body only (never the strip pass): commit-derived
+  // notes can carry `<!--` / `-->`, which CodeQL flags as changelog
+  // injection when interpolated next to the template's HTML comment.
+  const writtenBody = sanitizeCommentDelimiters(cleanedBody)
 
-  const newTemplate = `\n\n<!-- Add new changes here. Running \`node scripts/versioning.mjs apply\` will\n     move this section to a versioned entry and reset the template below. -->\n\n### Added\n\n### Changed\n\n### Fixed\n\n### Removed`
+  const newTemplate = `\n\n<!-- Add new changes here. Running \`node scripts/versioning.mjs apply\` will\n     move this section to a versioned entry and reset the template below. -->\n\n## 🆕 What's New\n\n## 🐞 Fixed\n\n## ⚠️ Known Issues\n\n## ✅ Closed Issues`
   const newVersionHeader = `## [v${newVersion}] - ${dateStr}`
 
   const before = content.slice(0, idx)
   const after = nextSectionIdx === -1 ? '' : content.slice(nextSectionIdx)
 
-  const updated = `${before + unreleasedHeader + newTemplate}\n\n${newVersionHeader}${cleanedBody}${after}`
+  const updated = `${before + unreleasedHeader + newTemplate}\n\n${newVersionHeader}${writtenBody}${after}`
 
   writeFileSync(CHANGELOG_PATH, updated)
-  console.log(`  ✓ CHANGELOG: [Unreleased] → [v${newVersion}]`)
+  console.log(
+    notesBody !== null
+      ? `  ✓ CHANGELOG: [Unreleased] → [v${newVersion}] (notes generated from commits)`
+      : `  ✓ CHANGELOG: [Unreleased] → [v${newVersion}]`,
+  )
   return true
 }
 
@@ -204,11 +283,29 @@ switch (command) {
   }
 
   case 'apply': {
-    const type = arg || 'auto'
+    const args = process.argv.slice(3)
+    const useNotes = args.includes('--notes')
+    const type = args.find((a) => !a.startsWith('--')) || 'auto'
     const latestTag = getLatestTag()
     const current = getCurrentVersion()
     const latestVer = latestTag.replace(/^v/, '')
 
+    // `apply --notes` pre-fills the promoted [Unreleased] entry with release
+    // notes generated from conventional commits (release-notes.mjs). Default
+    // stays manual — the flag is opt-in.
+    const generateNotes = () => {
+      if (!useNotes) return null
+      const since = latestTag === 'v0.0.0' ? null : latestTag
+      const raw = collectEntries({ since, draft: since === null })
+      const body = renderChangelog(groupCommits(raw.map(parseCommitLine)))
+      if (!body) {
+        console.log('  ⚠ --notes: no groupable commits — manual [Unreleased] content used')
+        return null
+      }
+      console.log(`  ℹ --notes: release notes generated from ${raw.length} commits`)
+      return body
+    }
+
     // If package.json is already ahead of the latest tag, someone bumped
     // without tagging — warn and use the current version as-is. Tags are
     // workflow-owned, so there is nothing to create here.
@@ -217,7 +314,7 @@ switch (command) {
       console.log(`  Syncing all manifests to ${current} and promoting CHANGELOG.`)
       updateManifests(current)
       const date = new Date().toISOString().slice(0, 10)
-      promoteUnreleased(current, date)
+      promoteUnreleased(current, date, generateNotes())
       console.log(`Tag v${current} will be created by the release workflow after merge to main.`)
       break
     }
@@ -228,7 +325,7 @@ switch (command) {
 
     console.log(`Bumping ${current} → ${newVersion} (${bumpType})`)
     updateManifests(newVersion)
-    promoteUnreleased(newVersion, date)
+    promoteUnreleased(newVersion, date, generateNotes())
     console.log(`\nDone. Commit with: git add -A && git commit -m "chore(release): v${newVersion}"`)
 
     // Tags are owned by the release workflow — never create them locally.
@@ -254,6 +351,8 @@ Commands:
   recommend            Print recommended bump type (patch/minor/major)
   apply [type]         Bump manifests + move [Unreleased] → [vX.Y.Z]
                        type: patch | minor | major | auto (default: auto)
+                       --notes: pre-fill the promoted entry with release
+                       notes generated from conventional commits
   changelog [version]  Promote [Unreleased] → [vX.Y.Z] without bumping
 
 Release flow: