kaloko 0.5.0 → 0.5.2

package/src/cli.mjs

@@ -18,7 +18,8 @@ import { configureGate } from './lib/linkcheck.mjs'
 import { rememberEnvironment } from './lib/secrets.mjs'
 import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
 import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
-import { stabilityCmd } from './lib/stability.mjs'
+import { stabilityCmd, pullDrawn } from './lib/stability.mjs'
+import { signoffCmd } from './lib/signoff.mjs'
 import { localized, readJson, UserError, globToRegExp, failureStreak, expiryNote } from './lib/util.mjs'
 import { packageRoot } from './lib/schema.mjs'
 import { compareRuns, formatComparison } from './lib/compare.mjs'
@@ -68,10 +69,11 @@ Project
   draft <url> [url…] [--id SITE-X] [--title t] [--out qa/flows/site.yml] [--force]
                                     First plan + read-only production scenario for public pages, drafted from the
                                     pages (title, description, H1) with the seo, a11y, perf and console packs
-  init [--agent claude|codex|all] [--org <slug>] [--no-detect] [--no-scenario]
+  init [--agent claude|codex|all] [--org <slug>] [--no-detect] [--no-scenario] [--docs=off|changelog|full]
                                     Create ${CONFIG_FILE} and install the kaloko skill for your agent; detects the
                                     framework, dev server URL, locales and main routes, and drafts a first scenario
-                                    (qa/flows/main-pages.yml) when the project has none
+                                    (qa/flows/main-pages.yml) when the project has none; asks "Keep a visual changelog?"
+                                    (--docs: changelog adds CHANGELOG.md and the config block, full also docs/ folders)
   ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected]
        [--out file] [--print] [--force]
                                     Write a workflow that walks what each pull request affects on its preview
@@ -217,10 +219,31 @@ Results
                                     Regions that change on every run or move while the page is idle (clocks, ads,
                                     carousels): ignore suggestions per step in <run>/stability.yml; --apply adds
                                     them to the scenario (ignore:), and pixel diffs then skip them
+  signoff <run-id> [--out dir] [--lang cs|en] [--json]
+                                    The signed acceptance record of an accepted run (Business): JSON and PDF with who
+                                    approved what and when, criteria results and capture hashes, checked against the
+                                    service's public key
+  signoff --verify <file.json|file.pdf> [--key file|url] [--json]
+                                    Check a record someone handed over (no token needed); exit 1 when it does not verify
+  stability --pull [--scenario id] [--json]
+                                    Regions people drew on screenshots on kaloko.app (step detail → Page → Draw a
+                                    region) go into the scenario's ignore: of their steps; walk them again after
   compare [--run id] [--baseline id | --design] [--json]
                                     Text diff of two runs: step statuses, criterion verdicts, scores and evidence
                                     (default: current run against the scenario baseline, else the previous run)
 
+Changelog (Keep a Changelog in CHANGELOG.md; pictures are step references kaloko:<scenario>/<step>)
+  changelog draft [--product p] [--since <tag|version>] [--apply] [--json] [--offline]
+                                    The Unreleased entry since the last release: merged pull requests and commits
+                                    (Conventional Commits when used, gh for titles) grouped Added / Changed / Fixed /
+                                    Removed, plus before/after pictures of the screens accepted runs show differently;
+                                    printed, or --apply writes it into CHANGELOG.md (not when a release tool owns it)
+  release [<version>] [--product p] [--date YYYY-MM-DD] [--runs id,id] [--no-write] [--dry-run] [--json]
+                                    Record a release on Kaloko: the version (default: from git tags, package.json,
+                                    release-please or changesets), its CHANGELOG.md entry (Unreleased becomes the
+                                    version unless --no-write) and the accepted runs that are its pictures; prints the
+                                    illustrated changelog page
+
 Design (environments with kind: design; live HTML steps in a folder)
   start --scenario <file> --env <design env>   A run of the design folder (same scenario as development and QA)
   walk [--steps a,b] [--no-cache]   Render the steps; unchanged revisions reuse their captures
@@ -257,6 +280,15 @@ Design (environments with kind: design; live HTML steps in a folder)
 Common options: --run <id|dir> (or KALOKO_RUN)  --config <file>   KALOKO_AGENT=<name> labels writes by an agent
 `
 
+/** A comment's drawing for the terminal: "· box 120,340 300×80 px on desktop" (CSS px when the size is known). */
+export function regionText (g) {
+  if (!g) return ''
+  const pct = (v) => `${Math.round(v * 100)}%`
+  const where = g.px ? `${g.px[0]},${g.px[1]} ${g.px[2]}×${g.px[3]} px` : `${pct(g.box[0])},${pct(g.box[1])} ${pct(g.box[2])}×${pct(g.box[3])}`
+  const kind = g.kind === 'arrow' ? 'arrow over' : g.kind === 'pen' ? 'drawing over' : 'box'
+  return ` · ${kind} ${where}${g.viewport ? ` on ${g.viewport}` : ''}`
+}
+
 /** validate: scenarios the service still lists as active whose scenario file no longer exists here (#58). */
 async function warnRetired (args) {
   if (args.offline) return
@@ -754,6 +786,38 @@ const commands = {
       await writeFile(file, tpl)
       say(`Created ${CONFIG_FILE}${detected ? ` (local: ${detected.url})` : ''}. Edit org and the staging and production environments.`)
     } else if (!existsSync(join(cwd, LEGACY_CONFIG_FILE))) say(`${CONFIG_FILE} already exists; kept.`)
+    // the visual changelog (docs/DOCS-CHANGELOG.md): asked once; --docs=off|changelog|full for scripts and agents
+    let docsMode = typeof args.docs === 'string' ? args.docs : null
+    if (docsMode && !['off', 'changelog', 'full'].includes(docsMode)) throw new UserError('--docs must be off, changelog or full.')
+    if (!docsMode && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI && !process.env.NODE_TEST_CONTEXT) {
+      const rl = (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout })
+      const a = (await rl.question('Keep a visual changelog? (recommended) [Y/n] ')).trim().toLowerCase(); rl.close()
+      docsMode = a === 'n' || a === 'no' ? 'off' : 'changelog'
+    }
+    if (docsMode && docsMode !== 'off') {
+      const { docsConfigBlock, detectProducts, DOCS_SKELETON } = await import('./lib/changelog.mjs')
+      const { CHANGELOG_SKELETON } = await import('./lib/changelog-core.mjs')
+      const { mkdir: mkdirp } = await import('node:fs/promises')
+      const cfgFile = existsSync(file) ? file : join(cwd, LEGACY_CONFIG_FILE)
+      const cfg = await readFile(cfgFile, 'utf8')
+      const products = /^products:/m.test(cfg) ? [] : await detectProducts(cwd)
+      if (!/^docs:/m.test(cfg) && !/^products:/m.test(cfg)) { await writeFile(cfgFile, `${cfg.replace(/\n*$/, '\n')}${docsConfigBlock({ products })}`); say(`Added the changelog settings to ${relative(cwd, cfgFile)}${products.length ? ` with ${products.length} products (${products.map((p) => p.slug).join(', ')})` : ''}`) }
+      for (const f of products.length ? products.map((p) => join(cwd, p.dir, 'CHANGELOG.md')) : [join(cwd, 'CHANGELOG.md')]) {
+        if (existsSync(f)) continue
+        await mkdirp(dirname(f), { recursive: true })
+        await writeFile(f, CHANGELOG_SKELETON)
+        say(`Created ${relative(cwd, f)} (Keep a Changelog; kaloko changelog draft fills Unreleased, kaloko release records a version)`)
+      }
+      if (docsMode === 'full') {
+        for (const [rel, text] of Object.entries(DOCS_SKELETON)) {
+          const f = join(cwd, rel)
+          if (existsSync(f)) continue
+          await mkdirp(dirname(f), { recursive: true })
+          await writeFile(f, text)
+        }
+        say('Docs folders in docs/ (tutorials, how-to, reference, explanation) with an index')
+      }
+    } else if (!docsMode) say('Visual changelog: kaloko init --docs=changelog adds CHANGELOG.md and the config block (recommended).')
     const agent = typeof args.agent === 'string' ? args.agent : 'none'
     if (!['claude', 'codex', 'all', 'none'].includes(agent)) throw new UserError('--agent must be claude, codex, all or none.')
     const { cp, mkdir, appendFile, rm } = await import('node:fs/promises')
@@ -858,7 +922,9 @@ const commands = {
     const executor = { kind: args.executor ? 'agent' : 'cli', name: args.executor || 'kaloko-cli' }
     const { project, issue } = await projectAndIssue({ cwd: root, config, scenario, branch: git?.branch })
     const appVer = typeof args['app-version'] === 'string' ? args['app-version'].slice(0, 80) : await appVersion(root)
-    const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer })
+    // the product the flow documents (visual changelog): its tag, or the only product of the config
+    const product = scenario.product || (Object.keys(config.products || {}).length === 1 ? Object.keys(config.products)[0] : null)
+    const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer, product })
     say(`Run ${meta.id}\n  dir: ${relative(process.cwd(), dir)}\n  env: ${env.name}${env.readonly ? ' (readonly)' : ''}\n  locales: ${locales.join(', ')}  viewports: ${vpNames.length > 12 ? `${vpNames.slice(0, 12).join(', ')} … (${vpNames.length})` : vpNames.join(', ')}${dimensionLine(scope)}\n  project: ${project.slug}${issue ? `  issue: ${issue.repo ? issue.repo + '#' : '#'}${issue.number}` : ''}`)
     const addr = recipient(env.mail, meta.short)
     if (addr) say(`  test e-mail: ${addr}`)
@@ -1485,6 +1551,8 @@ const commands = {
 
   async stability (args) {
     const { config, root, run, scenario } = await runContext(args)
+    // regions drawn by hand on the canvas (kaloko.app) into the scenario's ignore:
+    if (args.pull) { await pullDrawn({ root, config, run, args, say, client: service(config) }); return }
     await stabilityCmd({ root, config, run, scenario, args, say })
   },
 
@@ -1685,7 +1753,8 @@ const commands = {
     say(`Feedback for ${data.run.id} (${data.scenario}) — run verdict: ${data.verdict?.verdict || 'pending'}${data.verdict?.by ? ` by ${data.verdict.by}` : ''}${data.verdict?.note ? `: ${data.verdict.note}` : ''}${data.verdict?.awaiting?.length ? `\n  awaiting approval from: ${data.verdict.awaiting.join(', ')}` : ''}${data.approved.length ? `\n  approved: ${data.approved.join(', ')}` : ''}`)
     for (const c of data.criterion_verdicts || []) say(`  ✕ ${c.node_id} ${c.criterion_id}${c.locale ? ` [${c.locale}]` : ''} — ${c.email}: ${c.note}`)
     const thread = (r, where) => {
-      say(`  ${r.status === 'rejected' ? '✕' : '•'} [${r.id}] ${where}${r.locale ? ` [${r.locale}]` : ''}${r.pin ? ` · pinned at ${Math.round(r.pin.x * 100)}%,${Math.round(r.pin.y * 100)}%${r.pin.viewport ? ` (${r.pin.viewport})` : ''}` : ''}${r.anchor?.selector ? ` · on ${r.anchor.selector}` : ''} — ${r.email}${r.agent ? ` via ${r.agent}` : ''}: ${r.note}`)
+      say(`  ${r.status === 'rejected' ? '✕' : '•'} [${r.id}] ${where}${r.locale ? ` [${r.locale}]` : ''}${r.pin ? ` · pinned at ${Math.round(r.pin.x * 100)}%,${Math.round(r.pin.y * 100)}%${r.pin.viewport ? ` (${r.pin.viewport})` : ''}` : ''}${r.anchor?.selector ? ` · on ${r.anchor.selector}` : ''}${regionText(r.region)} — ${r.email}${r.agent ? ` via ${r.agent}` : ''}: ${r.note}`)
+      for (const f of r.attachments || []) say(`      attached ${f.name} (${f.type}): ${f.url || f.id}`)
       for (const x of r.replies || []) say(`      ↳ ${x.email}${x.agent ? ` via ${x.agent}` : ''}: ${x.deleted ? '(deleted)' : x.note}`)
     }
     const flow = data.flow_comments || []
@@ -1708,6 +1777,22 @@ const commands = {
    * accepted run, returned, commented), the approvals carried over unchanged steps, and the review-mode link. For
    * agents: report it to the person; never approve on their behalf.
    */
+  /**
+   * The signed acceptance record of an accepted run: JSON and PDF downloaded and checked against the service's public
+   * key; --verify checks a record someone handed over (no token, no project needed).
+   */
+  async signoff (args) {
+    if (typeof args.verify === 'string') {
+      const config = await context(args).then((c) => c.config).catch(() => ({}))
+      return signoffCmd({ config, args, say })
+    }
+    const { config, root } = await context(args)
+    let runId = args._[0] || (typeof args.run === 'string' ? args.run : null)
+    if (!runId) { try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id } catch {} }
+    if (!runId) throw new UserError('Usage: kaloko signoff <run-id> [--out dir] | kaloko signoff --verify <file.json|file.pdf>')
+    return signoffCmd({ config, args, say, client: service(config), runId })
+  },
+
   async review (args) {
     const { config, root } = await context(args)
     const client = service(config)
@@ -1981,12 +2066,56 @@ const commands = {
     const { config, root, file } = await context(args)
     // engines the scenarios ask for (browsers: [webkit, firefox]), so doctor checks they are installed
     const engines = []
-    for (const f of await scenarioFiles(config, root).catch(() => [])) { try { engines.push(...((yaml.load(await readFile(f, 'utf8')) || {}).browsers || [])) } catch {} }
-    const r = await doctor({ config, root, file, fix: !!args.fix, engines })
+    const scenarios = []
+    for (const f of await scenarioFiles(config, root).catch(() => [])) { try { const s = yaml.load(await readFile(f, 'utf8')) || {}; engines.push(...(s.browsers || [])); scenarios.push({ file: relative(root, f), product: s.product || null, module: s.module || null }) } catch {} }
+    const r = await doctor({ config, root, file, fix: !!args.fix, engines, scenarios })
     say(args.json ? JSON.stringify(r, null, 2) : formatDoctor(r))
     if (!r.ok) process.exitCode = 1
   },
 
+  /** `kaloko changelog draft`: the Unreleased entry from merged work and the screens accepted runs show differently. */
+  async changelog (args) {
+    const sub = args._[0]
+    if (sub !== 'draft') throw new UserError('Usage: kaloko changelog draft [--product p] [--since <tag|version>] [--apply] [--json] [--offline]')
+    const { config, root } = await context(args)
+    const { pickProduct, draftChangelog, draftText, applyToChangelog } = await import('./lib/changelog.mjs')
+    const product = pickProduct(config, root, args.product)
+    let client = null
+    if (!args.offline) { try { client = service(config) } catch {} }
+    const d = await draftChangelog({ root, config, product, since: typeof args.since === 'string' ? args.since : null, client })
+    if (args.json) { say(JSON.stringify(d, null, 2)); return }
+    const pictures = d.changes.reduce((n, s) => n + (s.steps?.length || 0), 0)
+    const head = `${product.slug}: ${d.commits} change(s) since ${d.since.ref || 'the first commit'}${d.service === 'ok' ? `, ${pictures} changed screen(s) in accepted runs since ${d.previous ? `release ${d.previous.version}` : 'the first accepted runs'}` : d.service === 'offline' ? ' (no service: pictures of changed screens need a token)' : ` (service: ${d.service})`}; ${d.internal.length} internal left out.`
+    if (args.apply) {
+      const r = await applyToChangelog(d)
+      say(`${head}\n${r.created ? 'Created' : 'Updated'} ${relative(process.cwd(), d.file) || d.file}: ${r.added} new item(s) in Unreleased. Edit them for people, then kaloko release <version>.`)
+      return
+    }
+    console.error(head)
+    say(draftText(d))
+  },
+
+  /** `kaloko release <version>`: the version's changelog entry and its reference runs on the service. */
+  async release (args) {
+    const { config, root } = await context(args)
+    if (!config.org) throw new UserError('Set org: in the config first.')
+    const { pickProduct, releaseProduct } = await import('./lib/changelog.mjs')
+    const product = pickProduct(config, root, args.product)
+    const client = args['dry-run'] ? null : service(config)
+    const r = await releaseProduct({ root, config, product, version: args._[0] || null, date: typeof args.date === 'string' ? args.date : null, client, write: !args['no-write'], runs: list(args.runs), dryRun: !!args['dry-run'] })
+    if (args.json) { say(JSON.stringify(r, null, 2)); return }
+    const file = relative(process.cwd(), r.file) || r.file
+    const lines = [`${product.slug} ${r.version} (${r.date}) · version source: ${r.source.tool || r.source.source}${r.source.path ? ` (${r.source.path})` : ''}`]
+    lines.push(r.section ? `  ${file}: ${r.finalized ? 'Unreleased became' : 'entry'} ${r.version}, ${r.items} item(s), ${r.refs} picture reference(s)` : `  ${file}: no entry for ${r.version}`)
+    if (r.release) {
+      lines.push(`  ${r.release.created ? 'Recorded' : 'Updated'} on the service with ${r.release.runs.length} reference run(s)${r.release.versioned_runs ? `; ${r.release.versioned_runs} accepted run(s) now carry ${r.version}` : ''}`)
+      lines.push(`  ${r.release.url}`)
+    } else lines.push('  Dry run: nothing sent.')
+    for (const n of r.notes) lines.push(`  ! ${n}`)
+    if (r.finalized) lines.push(`  Commit ${file} with the release.`)
+    say(lines.join('\n'))
+  },
+
   async help () { say(HELP) }
 }
 

package/src/lib/changelog-core.mjs

@@ -0,0 +1,323 @@
+// The visual changelog (docs/DOCS-CHANGELOG.md, phase 1), the parts the CLI and the service share: step references
+// in Markdown, Keep a Changelog parsing and editing, commit classification and the draft skeleton. No I/O here: the
+// worker imports this file too (worker/src/changelog.js), so it stays plain JavaScript without Node built-ins.
+
+// ---------- step references ----------
+
+/** Scenario and step ids as the service accepts them (design.js SCENARIO_ID). */
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/
+const PARAMS = {
+  locale: /^[A-Za-z0-9_-]{1,20}$/,
+  viewport: /^[A-Za-z0-9._-]{1,80}$/,
+  version: /^[A-Za-z0-9._+-]{1,80}$/,
+  state: /^[A-Za-z0-9._-]{1,60}$/
+}
+export const REF_SCHEME = 'kaloko:'
+
+/**
+ * A step reference `kaloko:<scenario>/<step>[?locale=&viewport=&version=&state=]`, or the short `kaloko:<step>` that
+ * means a step of the product's default scenario. `version` is a released version, `latest` (default) or `prev` (the
+ * release before the one the text belongs to); `state` picks a variant of the capture (dark, webkit, reduce: the
+ * dimension values in the capture key). Returns null for anything else.
+ */
+export function parseStepRef (ref) {
+  const s = String(ref || '').trim()
+  if (!s.startsWith(REF_SCHEME)) return null
+  const rest = s.slice(REF_SCHEME.length)
+  const qi = rest.indexOf('?')
+  const path = qi < 0 ? rest : rest.slice(0, qi)
+  let parts
+  try { parts = path.split('/').map((p) => decodeURIComponent(p)) } catch { return null }
+  if (!parts.length || parts.length > 2 || parts.some((p) => !ID.test(p))) return null
+  const out = { scenario: parts.length === 2 ? parts[0] : null, step: parts[parts.length - 1], locale: null, viewport: null, version: null, state: null }
+  const q = new URLSearchParams(qi < 0 ? '' : rest.slice(qi + 1))
+  for (const [k, v] of q) {
+    if (!(k in PARAMS)) return null
+    if (!PARAMS[k].test(v)) return null
+    out[k] = v
+  }
+  if (out.version === 'latest') out.version = null
+  return out
+}
+
+/** The reference text of a parsed (or hand-built) reference; parameters in a fixed order. */
+export function formatStepRef ({ scenario = null, step, locale = null, viewport = null, version = null, state = null }) {
+  const path = `${scenario ? `${encodeURIComponent(scenario)}/` : ''}${encodeURIComponent(step)}`
+  const q = Object.entries({ locale, viewport, version, state }).filter(([, v]) => v != null && v !== '')
+  return `${REF_SCHEME}${path}${q.length ? `?${q.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}` : ''}`
+}
+
+/** Every image with a step reference in a Markdown text: { alt, ref, parsed, index }; broken ones have parsed null. */
+export function findStepRefs (markdown) {
+  const out = []
+  const re = /!\[([^\]]*)\]\((kaloko:[^)\s]+)\)/g
+  let m
+  while ((m = re.exec(String(markdown || '')))) out.push({ alt: m[1], ref: m[2], parsed: parseStepRef(m[2]), index: m.index })
+  return out
+}
+
+// ---------- versions ----------
+
+/** "v2.4.0" → "2.4.0"; anything else stays as it is (trimmed). */
+export const cleanVersion = (v) => String(v ?? '').trim().replace(/^v(?=\d)/, '')
+
+/** Semantic Versioning order (prereleases before their release); versions that are not semver sort by text. */
+export function compareVersions (a, b) {
+  const p = (v) => { const m = cleanVersion(v).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/); return m ? { n: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || null } : null }
+  const x = p(a); const y = p(b)
+  if (!x || !y) return String(a).localeCompare(String(b))
+  for (let i = 0; i < 3; i++) if (x.n[i] !== y.n[i]) return x.n[i] - y.n[i]
+  if (x.pre === y.pre) return 0
+  if (!x.pre) return 1
+  if (!y.pre) return -1
+  return x.pre.localeCompare(y.pre, 'en', { numeric: true })
+}
+
+/** The git tag of a version for a tag pattern ("v*" → "v2.4.0", "shop-v*" → "shop-v2.4.0"). */
+export const tagFor = (pattern, version) => String(pattern || 'v*').replace('*', cleanVersion(version))
+/** The version a tag names under a pattern, or null when the tag does not match it. */
+export function versionOfTag (pattern, tag) {
+  const [pre, post = ''] = String(pattern || 'v*').split('*')
+  const t = String(tag || '')
+  if (!t.startsWith(pre) || !t.endsWith(post) || t.length <= pre.length + post.length) return null
+  return cleanVersion(t.slice(pre.length, t.length - post.length))
+}
+
+// ---------- Keep a Changelog ----------
+
+export const GROUPS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
+const GROUP_ALIASES = { added: 'Added', new: 'Added', features: 'Added', 'minor changes': 'Added', changed: 'Changed', 'patch changes': 'Fixed', 'major changes': 'Changed', improvements: 'Changed', deprecated: 'Deprecated', removed: 'Removed', fixed: 'Fixed', 'bug fixes': 'Fixed', fixes: 'Fixed', security: 'Security', 'performance improvements': 'Changed' }
+/** A group heading as written by people or release tools ("Bug Fixes", "Minor Changes") in Keep a Changelog terms. */
+export const groupName = (h) => GROUP_ALIASES[String(h || '').trim().toLowerCase()] || String(h || '').trim()
+
+export const CHANGELOG_HEAD = `# Changelog
+
+All notable changes for the people who use this product. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow
+[Semantic Versioning](https://semver.org/). Pictures are step references
+(\`![](kaloko:<scenario>/<step>)\`) that Kaloko shows from the accepted runs.
+`
+export const CHANGELOG_SKELETON = `${CHANGELOG_HEAD}
+## [Unreleased]
+`
+
+const RELEASE_HEADING = /^##\s+(.+?)\s*$/
+const DATE = /(\d{4}-\d{2}-\d{2})/
+
+/** "## [2.4.0] - 2026-10-12", "## [1.2.0](https://…compare…) (2026-10-12)", "## 1.2.0", "## [Unreleased]". */
+export function parseHeading (line) {
+  const m = String(line).match(RELEASE_HEADING)
+  if (!m || /^#/.test(m[1])) return null
+  const text = m[1]
+  const bracket = text.match(/^\[([^\]]+)\]/)
+  const label = (bracket ? bracket[1] : text.split(/\s+/)[0]).trim()
+  if (/^unreleased$/i.test(label)) return { unreleased: true, version: null, date: null }
+  const version = cleanVersion(label)
+  if (!/^\d/.test(version)) return null
+  const rest = text.slice(bracket ? bracket[0].length : label.length)
+  return { unreleased: false, version, date: (rest.match(DATE) || [])[1] || null }
+}
+
+/** List items of a group body: each item keeps its continuation lines (pictures under it), without the "- ". */
+export function listItems (body) {
+  const items = []
+  let cur = null
+  for (const line of String(body || '').split('\n')) {
+    const m = line.match(/^[-*+]\s+(.*)$/)
+    if (m) { if (cur) items.push(cur.trimEnd()); cur = m[1]; continue }
+    if (cur != null && (/^\s+\S/.test(line) || line.trim() === '')) { cur += `\n${line.replace(/^ {1,4}/, '')}`; continue }
+    if (cur != null) { items.push(cur.trimEnd()); cur = null }
+  }
+  if (cur) items.push(cur.trimEnd())
+  return items.map((x) => x.replace(/\n+$/, '')).filter(Boolean)
+}
+
+/** Groups of a release body: [{ name, heading, items }] plus text before the first group (notes). */
+export function parseEntry (body) {
+  const groups = []; const notes = []
+  let cur = null
+  for (const line of String(body || '').replace(/\r/g, '').split('\n')) {
+    const h = line.match(/^###\s+(.+?)\s*$/)
+    if (h) { cur = { name: groupName(h[1]), heading: h[1].trim(), lines: [] }; groups.push(cur); continue }
+    if (cur) cur.lines.push(line); else notes.push(line)
+  }
+  return { notes: notes.join('\n').trim(), groups: groups.map((g) => ({ name: g.name, heading: g.heading, items: listItems(g.lines.join('\n')) })).filter((g) => g.items.length || g.name) }
+}
+
+/**
+ * A changelog file: { head (text before the first release heading), sections: [{ unreleased, version, date, heading,
+ * body, start, end }] (line numbers, end exclusive), links (the reference definitions at the bottom, by lower-case
+ * label), linksStart }.
+ */
+export function parseChangelog (text) {
+  const lines = String(text || '').replace(/\r/g, '').split('\n')
+  let linksStart = lines.length
+  while (linksStart > 0 && (/^\[[^\]]+\]:\s*\S+/.test(lines[linksStart - 1]) || lines[linksStart - 1].trim() === '')) linksStart--
+  if (!lines.slice(linksStart).some((l) => /^\[[^\]]+\]:/.test(l))) linksStart = lines.length
+  const links = {}
+  for (const l of lines.slice(linksStart)) { const m = l.match(/^\[([^\]]+)\]:\s*(\S+)/); if (m) links[m[1].toLowerCase()] = m[2] }
+  const sections = []
+  for (let i = 0; i < linksStart; i++) {
+    const h = /^##\s/.test(lines[i]) ? parseHeading(lines[i]) : null
+    if (!h) continue
+    if (sections.length) sections[sections.length - 1].end = i
+    sections.push({ ...h, heading: lines[i], start: i, end: linksStart })
+  }
+  for (const s of sections) s.body = lines.slice(s.start + 1, s.end).join('\n').trim()
+  const head = lines.slice(0, sections.length ? sections[0].start : linksStart).join('\n').trimEnd()
+  return { head, sections, links, linksStart, lines }
+}
+
+/** The section of a version (or the Unreleased one for null), or null. */
+export function sectionOf (text, version) {
+  const { sections } = parseChangelog(text)
+  const v = version == null ? null : cleanVersion(version)
+  return sections.find((s) => v == null ? s.unreleased : !s.unreleased && s.version === v) || null
+}
+
+/** The newest released version written in the file (null when none). */
+export function latestVersionIn (text) {
+  const v = parseChangelog(text).sections.filter((s) => !s.unreleased).map((s) => s.version)
+  return v.sort(compareVersions).pop() || null
+}
+
+const norm = (item) => String(item).split('\n')[0].replace(/<!--[\s\S]*?-->/g, '').replace(/\s+/g, ' ').trim().toLowerCase()
+
+/** Markdown of groups ({ Added: [items] } in Keep a Changelog order; other names after them). */
+export function groupsMarkdown (groups) {
+  const names = [...GROUPS.filter((g) => groups[g]?.length), ...Object.keys(groups).filter((g) => !GROUPS.includes(g) && groups[g]?.length)]
+  return names.map((g) => `### ${g}\n\n${groups[g].map((it) => `- ${String(it).split('\n').map((l, i) => i && l ? `  ${l}` : l).join('\n')}`).join('\n')}`).join('\n\n')
+}
+
+/**
+ * Puts draft items into the Unreleased section of a changelog: items whose first line is already there are left
+ * out, groups that exist get the new items at their end, missing groups are added in Keep a Changelog order. A file
+ * without an Unreleased section gets one above the newest release; an empty file gets the skeleton.
+ * Returns { text, added } (the number of new items).
+ */
+export function applyDraft (text, groups) {
+  let src = String(text || '')
+  if (!src.trim()) src = CHANGELOG_SKELETON
+  let parsed = parseChangelog(src)
+  let un = parsed.sections.find((s) => s.unreleased)
+  if (!un) {
+    const lines = parsed.lines
+    const at = parsed.sections.length ? parsed.sections[0].start : parsed.linksStart
+    const before = lines.slice(0, at); while (before.length && before[before.length - 1].trim() === '') before.pop()
+    src = [...before, '', '## [Unreleased]', '', ...lines.slice(at)].join('\n')
+    parsed = parseChangelog(src)
+    un = parsed.sections.find((s) => s.unreleased)
+  }
+  const existing = parseEntry(un.body)
+  const seen = new Set(parsed.sections.flatMap((s) => parseEntry(s.body).groups.flatMap((g) => g.items.map(norm))))
+  const merged = new Map(existing.groups.map((g) => [g.name, { heading: g.heading, items: [...g.items] }]))
+  let added = 0
+  for (const [name, items] of Object.entries(groups)) {
+    for (const it of items || []) {
+      if (seen.has(norm(it))) continue
+      seen.add(norm(it))
+      if (!merged.has(name)) merged.set(name, { heading: name, items: [] })
+      merged.get(name).items.push(it); added++
+    }
+  }
+  const order = [...GROUPS.filter((g) => merged.has(g)), ...[...merged.keys()].filter((g) => !GROUPS.includes(g))]
+  const body = [existing.notes, ...order.map((g) => { const x = merged.get(g); return groupsMarkdown({ [g]: x.items }).replace(/^### [^\n]+/, `### ${x.heading}`) })].filter(Boolean).join('\n\n')
+  const lines = parsed.lines
+  const out = [...lines.slice(0, un.start + 1), '', ...(body ? [body, ''] : []), ...lines.slice(un.end)]
+  return { text: out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '\n'), added }
+}
+
+/**
+ * Turns the Unreleased section into the release `version` of `date` and opens a new, empty Unreleased section above
+ * it. Compare links at the bottom ([unreleased]: …/compare/v1...HEAD) move along. Returns { text, changed, empty }.
+ */
+export function finalizeRelease (text, version, date, { tagPattern = 'v*' } = {}) {
+  const v = cleanVersion(version)
+  const parsed = parseChangelog(text)
+  if (parsed.sections.some((s) => !s.unreleased && s.version === v)) return { text, changed: false, empty: false }
+  const un = parsed.sections.find((s) => s.unreleased)
+  if (!un) return { text, changed: false, empty: true }
+  const lines = [...parsed.lines]
+  lines.splice(un.start, 1, '## [Unreleased]', '', `## [${v}] - ${date}`)
+  let out = lines.join('\n')
+  const link = parsed.links.unreleased
+  const m = link && link.match(/^(.*\/compare\/)(.+)\.\.\.HEAD$/)
+  if (m) {
+    const tag = tagFor(tagPattern, v)
+    out = out.replace(/^\[unreleased\]:\s*\S+$/im, `[unreleased]: ${m[1]}${tag}...HEAD\n[${v}]: ${m[1]}${m[2]}...${tag}`)
+  }
+  return { text: out, changed: true, empty: !un.body.trim() }
+}
+
+// ---------- commits and the draft ----------
+
+const CONVENTIONAL = /^(\w+)(?:\(([^)]*)\))?(!)?:\s*(.+)$/
+const INTERNAL = new Set(['docs', 'test', 'tests', 'chore', 'ci', 'build', 'style', 'refactor', 'release', 'wip', 'deps'])
+const TYPE_GROUP = { feat: 'Added', feature: 'Added', add: 'Added', fix: 'Fixed', bugfix: 'Fixed', hotfix: 'Fixed', perf: 'Changed', revert: 'Changed', remove: 'Removed', deprecate: 'Deprecated', security: 'Security', sec: 'Security' }
+
+/**
+ * Where a commit or pull request title goes: { group, text, internal, breaking, pr }. Conventional Commits when the
+ * title uses them; otherwise the first verb decides (add → Added, fix → Fixed, remove → Removed, else Changed).
+ * Documentation, tests, chores, CI, refactors, merges and releases are internal.
+ */
+export function classifyCommit (subject, body = '') {
+  let s = String(subject || '').trim()
+  let pr = null
+  const sq = s.match(/\s*\(#(\d+)\)\s*$/)
+  if (sq) { pr = Number(sq[1]); s = s.slice(0, sq.index).trim() }
+  const breaking = /BREAKING[ -]CHANGE/.test(body)
+  if (/^Merge\b|^Revert "|^v?\d+\.\d+\.\d+$|\[skip changelog\]|\[no changelog\]/i.test(s)) return { group: null, text: s, internal: true, breaking, pr }
+  const m = s.match(CONVENTIONAL)
+  if (m) {
+    const type = m[1].toLowerCase()
+    const text = sentence(m[4])
+    if (INTERNAL.has(type) && !m[3] && !breaking) return { group: null, text, internal: true, breaking: false, pr, type, scope: m[2] || null }
+    const group = TYPE_GROUP[type] || (/^(remove|drop|delete)\b/i.test(m[4]) ? 'Removed' : 'Changed')
+    return { group: m[3] || breaking ? (group === 'Added' ? 'Added' : 'Changed') : group, text, internal: false, breaking: !!m[3] || breaking, pr, type, scope: m[2] || null }
+  }
+  const verb = s.toLowerCase()
+  const group = /^(add|adds|added|new|introduce|support|allow|enable)\b/.test(verb) ? 'Added'
+    : /^(fix|fixes|fixed|correct|repair|resolve|prevent)\b/.test(verb) ? 'Fixed'
+      : /^(remove|removes|removed|drop|delete)\b/.test(verb) ? 'Removed'
+        : /^(deprecate)\b/.test(verb) ? 'Deprecated' : 'Changed'
+  return { group, text: sentence(s), internal: false, breaking, pr }
+}
+const sentence = (t) => { const x = String(t || '').trim().replace(/\.$/, ''); return x ? x[0].toUpperCase() + x.slice(1) : x }
+
+/**
+ * The draft entry: items grouped Added / Changed / Fixed / Removed (Deprecated, Security when present).
+ *
+ * commits  [{ subject, body, pr: { number, url } | null }] — merged pull requests or commits since the last release
+ * changes  [{ scenario, title, steps: [{ step, title, reason: new|changed|removed, pr: number|null }] }] — what the
+ *          accepted runs since the last release show differently (from the service)
+ * Pictures are step references: a changed step gets before and after (`?version=prev` is the previous release), a
+ * new step one picture. A step whose run came from a pull request goes under that pull request's item.
+ * Returns { groups, internal (titles left out), markdown }.
+ */
+export function draftEntry ({ commits = [], changes = [], scenarioLabel = (s) => s.title || s.scenario } = {}) {
+  const groups = {}
+  const internal = []
+  const byPr = new Map()
+  const add = (g, item) => { (groups[g] ||= []).push(item); return groups[g].length - 1 }
+  for (const c of commits) {
+    const k = classifyCommit(c.subject, c.body)
+    if (k.internal) { internal.push(c.subject); continue }
+    const number = c.pr?.number || k.pr
+    const url = c.pr?.url || null
+    const text = `${k.text}${k.breaking ? ' (breaking: say what people have to do)' : ''}${number ? ` (${url ? `[#${number}](${url})` : `#${number}`})` : ''}`
+    const i = add(k.group, text)
+    if (number && !byPr.has(number)) byPr.set(number, { group: k.group, i })
+  }
+  for (const sc of changes) {
+    for (const st of sc.steps || []) {
+      const ref = (version) => formatStepRef({ scenario: sc.scenario, step: st.step, version })
+      const title = st.title || st.step
+      const pics = st.reason === 'new' ? `![${title}](${ref(null)})` : st.reason === 'removed' ? `![${title} before](${ref('prev')})` : `![${title} before](${ref('prev')}) ![${title} after](${ref(null)})`
+      const home = st.pr && byPr.get(st.pr)
+      if (home) { groups[home.group][home.i] += `\n${pics}`; continue }
+      const g = st.reason === 'new' ? 'Added' : st.reason === 'removed' ? 'Removed' : 'Changed'
+      add(g, `**${title}** in ${scenarioLabel(sc)} <!-- say what a person notices here -->\n${pics}`)
+    }
+  }
+  return { groups, internal, markdown: groupsMarkdown(groups) }
+}