kaloko 0.5.1 → 0.6.0

package/src/lib/changelog.mjs

@@ -0,0 +1,399 @@
+// `kaloko changelog draft` and `kaloko release` (docs/DOCS-CHANGELOG.md, phase 1): products from kaloko.config.yml,
+// the version source the repository already uses (never fighting a release tool), merged pull requests and commits
+// since the last release, the steps the accepted runs show differently (from the service), the draft entry and the
+// release record. Parsing and the draft itself are in changelog-core.mjs, shared with the service.
+import { readFile, writeFile, access, readdir } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join, resolve, relative, dirname, basename } from 'node:path'
+import { UserError, sha256 } from './util.mjs'
+import { repoSlug } from './git.mjs'
+import { cleanVersion, compareVersions, tagFor, versionOfTag, latestVersionIn, sectionOf, applyDraft, finalizeRelease, draftEntry, groupsMarkdown, parseEntry, findStepRefs, CHANGELOG_SKELETON } from './changelog-core.mjs'
+
+const run = promisify(execFile)
+async function out (cmd, args, cwd, timeout = 20000) {
+  try { return (await run(cmd, args, { cwd, timeout, maxBuffer: 50 * 1024 * 1024 })).stdout } catch { return null }
+}
+const exists = async (f) => { try { await access(f); return true } catch { return false } }
+const readJson = async (f) => { try { return JSON.parse(await readFile(f, 'utf8')) } catch { return null } }
+const readText = async (f) => { try { return await readFile(f, 'utf8') } catch { return null } }
+export const today = () => new Date().toISOString().slice(0, 10)
+
+// ---------- products ----------
+
+const slugOf = (s) => String(s || '').toLowerCase().replace(/^@[^/]+\//, '').replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80)
+
+/**
+ * Products of the configuration, normalized. Without `products:` the project is the product (implicit): its slug is
+ * the config's project, else the directory name.
+ */
+export function productsOf (config, root = process.cwd()) {
+  const docs = config.docs || {}
+  const list = Object.entries(config.products || {}).map(([slug, p]) => ({
+    slug, implicit: false, name: p.name || slug,
+    projects: [...new Set([p.project, ...(p.projects || [])].filter(Boolean))],
+    modules: p.modules || [], reference_env: p.reference_env || null, default_scenario: p.default_scenario || null,
+    version: p.version || null, docs: { ...docs, ...(p.docs || {}) }, publish: p.publish || docs.publish || null
+  }))
+  if (list.length) return list
+  const slug = slugOf(config.project || basename(root)) || 'app'
+  return [{ slug, implicit: true, name: config.project || slug, projects: [slug], modules: [], reference_env: null, default_scenario: null, version: null, docs, publish: docs.publish || null }]
+}
+
+/** The product a command works on: --product, else the only one. */
+export function pickProduct (config, root, name) {
+  const all = productsOf(config, root)
+  if (typeof name === 'string' && name) {
+    const p = all.find((x) => x.slug === name)
+    if (!p) throw new UserError(`No product ${name} in the config (${all.map((x) => x.slug).join(', ')}).`)
+    return p
+  }
+  if (all.length > 1) throw new UserError(`The config has several products; pass --product (${all.map((x) => x.slug).join(', ')}).`)
+  return all[0]
+}
+
+export const changelogFile = (root, product) => resolve(root, product.docs?.changelog || 'CHANGELOG.md')
+
+// ---------- the version source ----------
+
+const SEMREL = ['.releaserc', '.releaserc.json', '.releaserc.yml', '.releaserc.yaml', '.releaserc.js', '.releaserc.cjs', 'release.config.js', 'release.config.cjs', 'release.config.mjs']
+
+/**
+ * Where the product's version comes from, as the repository already decides it: { source, path, pattern, version,
+ * owns_changelog, tool }. The config wins (products.<p>.version or docs.version_source); otherwise release-please,
+ * changesets, semantic-release, package.json, pyproject.toml, Cargo.toml, a gemspec, else git tags (v*).
+ */
+export async function detectVersionSource (root, product = {}) {
+  const v = product.version || {}
+  const wanted = v.source && v.source !== 'auto' ? v.source : product.docs?.version_source && product.docs.version_source !== 'auto' ? product.docs.version_source : null
+  const pattern = v.pattern || 'v*'
+  const pkgPath = v.path && /package\.json$/.test(v.path) ? v.path : 'package.json'
+  const dir = v.path ? dirname(v.path) : '.'
+  const found = async (source) => {
+    if (source === 'release-please') {
+      const manifest = await readJson(join(root, '.release-please-manifest.json'))
+      const key = dir === '.' ? '.' : dir
+      return { source, path: '.release-please-manifest.json', pattern, version: manifest ? cleanVersion(manifest[key] ?? manifest['.'] ?? '') || null : null, owns_changelog: true, tool: 'release-please' }
+    }
+    if (source === 'changesets') return { source, path: pkgPath, pattern, version: cleanVersion((await readJson(join(root, pkgPath)))?.version || '') || null, owns_changelog: true, tool: 'changesets' }
+    if (source === 'semantic-release') {
+      let conf = ''
+      for (const f of SEMREL) conf += (await readText(join(root, f))) || ''
+      conf += JSON.stringify((await readJson(join(root, 'package.json')))?.release || '')
+      return { source, path: null, pattern, version: await latestTag(root, pattern), owns_changelog: conf.includes('@semantic-release/changelog'), tool: 'semantic-release' }
+    }
+    if (source === 'package.json') return { source, path: pkgPath, pattern, version: cleanVersion((await readJson(join(root, pkgPath)))?.version || '') || null, owns_changelog: false }
+    if (source === 'pyproject') { const t = await readText(join(root, v.path || 'pyproject.toml')); return { source, path: v.path || 'pyproject.toml', pattern, version: (t?.match(/^version\s*=\s*["']([^"']+)["']/m) || [])[1] || null, owns_changelog: false } }
+    if (source === 'cargo') { const t = await readText(join(root, v.path || 'Cargo.toml')); return { source, path: v.path || 'Cargo.toml', pattern, version: (t?.match(/^\[package\][\s\S]*?^version\s*=\s*"([^"]+)"/m) || [])[1] || null, owns_changelog: false } }
+    if (source === 'gemspec') {
+      const f = v.path || (await readdir(root).catch(() => [])).find((x) => x.endsWith('.gemspec'))
+      const t = f ? await readText(join(root, f)) : null
+      return { source, path: f || null, pattern, version: (t?.match(/\.version\s*=\s*["']([^"']+)["']/) || [])[1] || null, owns_changelog: false }
+    }
+    if (source === 'manual') return { source, path: null, pattern, version: null, owns_changelog: false }
+    return { source: 'git-tag', path: null, pattern, version: await latestTag(root, pattern), owns_changelog: false }
+  }
+  if (wanted) return found(wanted)
+  if (await exists(join(root, '.release-please-manifest.json')) || await exists(join(root, 'release-please-config.json'))) return found('release-please')
+  if (await exists(join(root, '.changeset', 'config.json'))) return found('changesets')
+  for (const f of SEMREL) if (await exists(join(root, f))) return found('semantic-release')
+  const pkg = await readJson(join(root, pkgPath))
+  if (pkg?.release) return found('semantic-release')
+  if (pkg?.version && !pkg.private) return found('package.json')
+  if (pkg?.version && pkg.version !== '0.0.0') return found('package.json')
+  if (await exists(join(root, 'pyproject.toml')) && /^version\s*=/m.test(await readText(join(root, 'pyproject.toml')) || '')) return found('pyproject')
+  if (await exists(join(root, 'Cargo.toml'))) return found('cargo')
+  if ((await readdir(root).catch(() => [])).some((x) => x.endsWith('.gemspec'))) return found('gemspec')
+  return found('git-tag')
+}
+
+/** The newest tag of the pattern (version order), or null. */
+async function latestTag (root, pattern) {
+  const tags = ((await out('git', ['tag', '--list', pattern], root)) || '').split('\n').map((t) => t.trim()).filter(Boolean)
+  const versions = tags.map((t) => versionOfTag(pattern, t)).filter(Boolean)
+  return versions.sort(compareVersions).pop() || null
+}
+const tagExists = async (root, tag) => !!(await out('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], root))
+
+/**
+ * Where the draft starts: --since (a tag, or a version that has a tag), else the newest tag of the pattern reachable
+ * from HEAD, else the newest release written in the changelog when it has a tag; null = the whole history.
+ */
+export async function sinceRef (root, product, src, since, changelogText = '') {
+  const pattern = src.pattern || 'v*'
+  if (typeof since === 'string' && since) {
+    if (await tagExists(root, since)) return { ref: since, version: versionOfTag(pattern, since) || cleanVersion(since) }
+    const tag = tagFor(pattern, since)
+    if (await tagExists(root, tag)) return { ref: tag, version: cleanVersion(since) }
+    if (await out('git', ['rev-parse', '--verify', '--quiet', `${since}^{commit}`], root)) return { ref: since, version: null }
+    throw new UserError(`--since ${since}: no tag ${since} or ${tag} and no such commit.`)
+  }
+  const described = ((await out('git', ['describe', '--tags', '--abbrev=0', '--match', pattern, 'HEAD'], root)) || '').trim()
+  if (described) return { ref: described, version: versionOfTag(pattern, described) }
+  const written = latestVersionIn(changelogText)
+  if (written && await tagExists(root, tagFor(pattern, written))) return { ref: tagFor(pattern, written), version: written }
+  return { ref: null, version: written || null }
+}
+
+// ---------- pull requests and commits ----------
+
+/**
+ * Merged work since `ref` along the first-parent history: a merge of a pull request is one item (its title), other
+ * merges are opened up into their commits, plain commits are items. PR numbers come from merge subjects and squash
+ * suffixes ("(#12)"); titles and links from gh when it is there (KALOKO_NO_GH=1 skips it). `dir` limits the history
+ * to a product's folder in a monorepo.
+ */
+export async function collectCommits (root, ref, { dir = null, limit = 400 } = {}) {
+  const range = ref ? `${ref}..HEAD` : 'HEAD'
+  const SEP = '\u001f'; const END = '\u001e'
+  const fmt = `--format=%H${SEP}%P${SEP}%s${SEP}%b${END}`
+  const log = async (args) => ((await out('git', ['log', fmt, ...args], root)) || '').split(END).map((x) => x.trim()).filter(Boolean).map((x) => { const [sha, parents, subject, body = ''] = x.split(SEP); return { sha, parents: parents.split(' ').filter(Boolean), subject, body: body.trim() } })
+  const scope = dir && dir !== '.' ? ['--', dir] : []
+  const first = await log(['--first-parent', `-n${limit}`, range, ...scope])
+  const items = []
+  for (const c of first) {
+    if (c.parents.length > 1) {
+      const pr = c.subject.match(/^Merge pull request #(\d+)/) || c.subject.match(/^Merge branch .* into .*\(#(\d+)\)/) || c.subject.match(/\(#(\d+)\)\s*$/)
+      if (pr) { items.push({ sha: c.sha, subject: c.body.split('\n')[0] || c.subject, body: c.body.split('\n').slice(1).join('\n'), pr: { number: Number(pr[1]), url: null } }); continue }
+      for (const inner of await log(['--no-merges', `-n${limit}`, `${c.parents[0]}..${c.sha}`, ...scope])) items.push({ sha: inner.sha, subject: inner.subject, body: inner.body, pr: null })
+      continue
+    }
+    const sq = c.subject.match(/\(#(\d+)\)\s*$/)
+    items.push({ sha: c.sha, subject: c.subject, body: c.body, pr: sq ? { number: Number(sq[1]), url: null } : null })
+  }
+  // links and titles of pull requests (GitHub)
+  const repo = await repoSlug(root)
+  const numbers = [...new Set(items.map((i) => i.pr?.number).filter(Boolean))]
+  if (repo?.host === 'github') {
+    let titles = new Map()
+    if (numbers.length && process.env.KALOKO_NO_GH !== '1') {
+      const json = await out('gh', ['pr', 'list', '--state', 'merged', '--limit', '200', '--json', 'number,title,url'], root, 15000)
+      try { titles = new Map(JSON.parse(json || '[]').map((p) => [p.number, p])) } catch {}
+    }
+    for (const i of items) {
+      if (!i.pr) continue
+      const p = titles.get(i.pr.number)
+      i.pr.url = p?.url || `https://github.com/${repo.slug}/pull/${i.pr.number}`
+      // a squash commit or merge keeps its own title unless it is GitHub's default "Merge pull request" line
+      if (p?.title && /^Merge pull request/.test(i.subject)) i.subject = p.title
+    }
+  }
+  return items
+}
+
+// ---------- the draft ----------
+
+/**
+ * The draft entry of a product: commits and pull requests since the last release plus the steps that accepted runs
+ * show differently (when a service client is given). Returns { product, since, source, commits, changes, groups,
+ * markdown, internal, service, file }.
+ */
+export async function draftChangelog ({ root, config, product, since = null, client = null }) {
+  const file = changelogFile(root, product)
+  const text = (await readText(file)) || ''
+  const src = await detectVersionSource(root, product)
+  const from = await sinceRef(root, product, src, since, text)
+  const dir = product.version?.path ? dirname(product.version.path) : null
+  const commits = await collectCommits(root, from.ref, { dir })
+  let changes = []; let service = 'offline'; let previous = null
+  if (client && config.org) {
+    try {
+      const q = new URLSearchParams({ product: product.slug, ...(from.version && since ? { since: from.version } : {}) })
+      const r = await client.request('GET', `/orgs/${config.org}/changelog/changes?${q}`)
+      changes = (r.scenarios || []).map((s) => ({ scenario: s.scenario, title: s.title, steps: (s.steps || []).map((st) => ({ ...st, pr: st.pr ?? s.run?.pr?.number ?? null })) }))
+      previous = r.previous || null
+      service = 'ok'
+    } catch (e) { service = `error: ${String(e.message || e).split('\n')[0].slice(0, 200)}` }
+  }
+  const d = draftEntry({ commits, changes })
+  return { product: product.slug, since: from, previous, source: src, commits: commits.length, changes, groups: d.groups, markdown: d.markdown, internal: d.internal, service, file }
+}
+
+/** The draft as an Unreleased section, with a note for whoever edits it. */
+export function draftText (d) {
+  if (!d.markdown) return '## [Unreleased]\n\n<!-- Nothing user-facing since the last release: no merged changes and no changed screens. -->\n'
+  return `## [Unreleased]\n\n<!-- Draft by kaloko changelog draft: write each line for the people who use the product (what they can do now,\n     what looks different), one change per line; delete what is internal; keep the step references for the pictures. -->\n\n${d.markdown}\n`
+}
+
+/** Writes the draft into the changelog's Unreleased section (creating the file with the skeleton when missing). */
+export async function applyToChangelog (d) {
+  if (d.source.owns_changelog) throw new UserError(`${d.source.tool} writes ${relative(process.cwd(), d.file) || 'CHANGELOG.md'}; kaloko leaves it to it. Use the printed draft in your pull request or release notes, and kaloko release reads the entry ${d.source.tool} writes.`)
+  const before = (await readText(d.file)) || ''
+  const { text, added } = applyDraft(before || CHANGELOG_SKELETON, d.groups)
+  if (text !== before) await writeFile(d.file, text)
+  return { added, created: !before }
+}
+
+// ---------- the release ----------
+
+/**
+ * Records a release on the service: the product (from the config), the version (given, else the version source's),
+ * the entry of that version in the changelog (an Unreleased section becomes the release unless a release tool owns
+ * the file; --no-write leaves the file alone) and the runs, which the service picks (newest accepted run per flow)
+ * unless `runs` names them. Returns what happened, for the CLI to say.
+ */
+export async function releaseProduct ({ root, config, product, version = null, date = null, client, write = true, runs = null, dryRun = false }) {
+  const src = await detectVersionSource(root, product)
+  const v = cleanVersion(version || src.version || '')
+  if (!v) throw new UserError(`Which version? Pass it (kaloko release 2.4.0); ${src.source === 'git-tag' ? `no tag matches ${src.pattern}` : `${src.path || src.source} names none`}.`)
+  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,79}$/.test(v)) throw new UserError(`Not a version: ${v}`)
+  const notes = []
+  if (src.version && src.version !== v && src.source !== 'git-tag' && src.source !== 'semantic-release') notes.push(`${src.tool || src.source} (${src.path}) says ${src.version}; recording ${v} as you asked.`)
+  const file = changelogFile(root, product)
+  let text = (await readText(file)) || ''
+  let section = sectionOf(text, v)
+  let finalized = false
+  const day = /^\d{4}-\d{2}-\d{2}$/.test(date || '') ? date : section?.date || today()
+  if (!section && write && !src.owns_changelog && sectionOf(text, null)?.body?.trim()) {
+    const f = finalizeRelease(text, v, day, { tagPattern: src.pattern })
+    if (f.changed) {
+      if (!dryRun) await writeFile(file, f.text)
+      text = f.text; section = sectionOf(text, v); finalized = true
+    }
+  }
+  if (!section) notes.push(`${relative(root, file) || 'CHANGELOG.md'} has no entry for ${v}${src.owns_changelog ? ` (${src.tool} writes it)` : ''}; the release is recorded without text.`)
+  const md = section?.body || ''
+  const refs = findStepRefs(md)
+  const broken = refs.filter((r) => !r.parsed).map((r) => r.ref)
+  if (broken.length) notes.push(`Broken step references: ${broken.join(', ')}`)
+  const tag = tagFor(src.pattern, v)
+  const commit = (await tagExists(root, tag)) ? ((await out('git', ['rev-list', '-n', '1', tag], root)) || '').trim() : ((await out('git', ['rev-parse', 'HEAD'], root)) || '').trim()
+  const payload = {
+    product: await productPayload(root, product, src),
+    release: { product: product.slug, version: v, date: section?.date || day, changelog: md, source_hash: sha256(md), tag: (await tagExists(root, tag)) ? tag : null, commit: /^[0-9a-f]{40}$/.test(commit) ? commit : null, ...(runs ? { runs } : {}) }
+  }
+  if (dryRun) return { version: v, date: payload.release.date, file, section: !!section, finalized, source: src, notes, payload, items: parseEntry(md).groups.reduce((n, g) => n + g.items.length, 0), refs: refs.length }
+  const saved = await client.request('POST', `/orgs/${config.org}/products`, payload.product)
+  notes.push(...(saved.notes || []))
+  const rec = await client.request('POST', `/orgs/${config.org}/releases`, payload.release)
+  return { version: v, date: payload.release.date, file, section: !!section, finalized, source: src, notes, release: rec, product: saved.product, items: parseEntry(md).groups.reduce((n, g) => n + g.items.length, 0), refs: refs.length }
+}
+/** The product as the service records it (POST /products): from the config, with the version source found. */
+export async function productPayload (root, product, src) {
+  return { slug: product.slug, name: product.name, projects: product.projects, modules: product.modules, reference_env: product.reference_env, default_scenario: product.default_scenario, implicit: product.implicit, version_source: { source: src.source, ...(src.path ? { path: src.path } : {}), pattern: src.pattern, ...(src.tool ? { tool: src.tool } : {}) }, ...(product.publish ? { publish: product.publish } : {}), ...(await repoUrl(root)) }
+}
+
+async function repoUrl (root) {
+  const r = await repoSlug(root)
+  return r?.host === 'github' ? { repo: `https://github.com/${r.slug}` } : r?.host === 'gitlab' ? { repo: `https://gitlab.com/${r.slug}` } : {}
+}
+
+// ---------- init and doctor ----------
+
+/** The config block `kaloko init --docs=changelog|full` adds (comments say what each line does). */
+export function docsConfigBlock ({ products = null, full = false } = {}) {
+  const lines = ['', '# Visual changelog: kaloko changelog draft writes the Unreleased entry with step references,', '# kaloko release <version> records the release and its pictures (docs/DOCS-CHANGELOG.md on kaloko.app)', 'docs:', '  changelog: CHANGELOG.md', '  version_source: auto       # git-tag | package.json | release-please | changesets | semantic-release']
+  if (full) lines.push('  dir: docs                  # guides with step references; kaloko docs publish sends them, kaloko docs check checks them', '  # languages: [en, cs]      # the first is the originals\' language; translations sit next to them (guide.cs.md)')
+  if (products?.length) {
+    lines.push('# one product per app in this repository; scenarios say which one they show (product: <slug>)', 'products:')
+    for (const p of products) lines.push(`  ${p.slug}:`, `    name: ${JSON.stringify(p.name)}`, `    version: { source: package.json, path: ${p.path} }`, `    docs: { changelog: ${p.dir}/CHANGELOG.md }`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/** Apps of a monorepo that look like products (apps/* with a package.json), for kaloko init. */
+export async function detectProducts (root) {
+  const out = []
+  for (const base of ['apps']) {
+    const names = await readdir(join(root, base)).catch(() => [])
+    for (const n of names.sort()) {
+      const pkg = await readJson(join(root, base, n, 'package.json'))
+      if (pkg) out.push({ slug: slugOf(n), name: pkg.name ? String(pkg.name).replace(/^@[^/]+\//, '') : n, dir: `${base}/${n}`, path: `${base}/${n}/package.json` })
+    }
+  }
+  return out.length > 1 ? out : []
+}
+
+/**
+ * Diátaxis folders and an index for `kaloko init --docs=full` (only what is missing). Each folder's README says what
+ * belongs there and carries a template in a comment (comments never show on Kaloko or in exports).
+ */
+export const DOCS_SKELETON = {
+  'docs/index.md': '# Documentation\n\nGuides for the people who use the product. Pictures are step references\n(`![](kaloko:<scenario>/<step>)`) that always show the newest accepted screen.\n\n- [Tutorials](tutorials/README.md): learn by doing, start to finish\n- [How-to guides](how-to/README.md): one task each\n- [Reference](reference/README.md): the facts to look up\n- [Explanation](explanation/README.md): why it works this way\n',
+  'docs/tutorials/README.md': `# Tutorials
+
+A tutorial takes a newcomer through a first success, start to finish, on a path that always works.
+
+<!-- Template (copy into a new file, e.g. first-order.md):
+---
+title: Your first order
+order: 1
+---
+# Your first order
+
+In ten minutes you will have placed an order and seen it in your account.
+
+1. Open the shop and put a tea in the cart.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Checkout** and pay with a test card.
+   ![Payment](kaloko:checkout/payment)
+
+You have placed your first order. Next: [track it](../how-to/track-an-order.md).
+-->
+`,
+  'docs/how-to/README.md': `# How-to guides
+
+One task per page, for someone who already knows what they want to do.
+
+<!-- Template (copy into a new file, e.g. pay-with-apple-pay.md):
+# Pay with Apple Pay
+
+1. Open the cart and choose **Checkout**.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Apple Pay** above the card form and confirm on your phone or Mac.
+   ![Payment](kaloko:checkout/payment)
+
+If the button is missing, your browser has no Apple Pay set up.
+-->
+`,
+  'docs/reference/README.md': `# Reference
+
+Facts to look up: fields, limits, settings, keyboard shortcuts. Tables and lists, no story.
+
+<!-- Template (copy into a new file, e.g. order-states.md):
+# Order states
+
+| State | What it means |
+|---|---|
+| Paid | The payment went through; the order waits for packing. |
+| Shipped | The parcel left the warehouse. |
+
+![Order detail](kaloko:account/order-detail)
+-->
+`,
+  'docs/explanation/README.md': `# Explanation
+
+Why things work the way they do: background, choices, trade-offs.
+
+<!-- Template (copy into a new file, e.g. why-we-hold-payments.md):
+# Why a payment waits a day
+
+Card payments are confirmed the next morning, so a cancelled order costs the customer nothing.
+-->
+`
+}
+
+/**
+ * Doctor checks for products: each product's version resolves from its source, scenarios name a known product
+ * (and module), and with several products every scenario says which one it shows. [{ name, ok, detail, hint }]
+ */
+export async function productChecks ({ config, root, scenarios = [] }) {
+  const checks = []
+  const products = Object.keys(config.products || {})
+  if (!products.length) return checks
+  for (const p of productsOf(config, root)) {
+    const src = await detectVersionSource(root, p)
+    const ok = !!src.version || src.source === 'manual'
+    checks.push({ name: `product ${p.slug}`, ok, detail: ok ? `version ${src.version || '(set by kaloko release)'} from ${src.source}${src.path ? ` (${src.path})` : src.source === 'git-tag' ? ` (${src.pattern})` : ''}` : `no version from ${src.source}${src.path ? ` (${src.path})` : ` (${src.pattern})`}`, hint: ok ? '' : src.source === 'git-tag' ? `Tag a release (git tag ${tagFor(src.pattern, '1.0.0')}) or set products.${p.slug}.version.` : `Set the version in ${src.path || src.source}, or products.${p.slug}.version in the config.` })
+  }
+  const untagged = []; const unknown = []
+  for (const s of scenarios) {
+    if (!s.product) { untagged.push(s.file); continue }
+    if (!products.includes(s.product)) unknown.push(`${s.file}: product ${s.product}`)
+    else if (s.module && !(config.products[s.product].modules || []).includes(s.module)) unknown.push(`${s.file}: module ${s.module} of ${s.product}`)
+  }
+  if (unknown.length) checks.push({ name: 'scenario products', ok: false, detail: unknown.slice(0, 5).join('; '), hint: 'Use a key of products: (and one of its modules:) in the scenario.' })
+  if (untagged.length && products.length > 1) checks.push({ name: 'scenario products', ok: false, detail: `${untagged.length} scenario(s) without product: ${untagged.slice(0, 4).join(', ')}${untagged.length > 4 ? ' …' : ''}`, hint: `Add product: <${products.join('|')}> to each, so their pictures go to the right changelog.` })
+  else if (!unknown.length) checks.push({ name: 'scenario products', ok: true, detail: products.length === 1 ? `untagged scenarios belong to ${products[0]}` : 'every scenario names its product' })
+  return checks
+}

package/src/lib/ci.mjs

@@ -209,3 +209,74 @@ export function addPreviewEnvironment (text, name = 'preview') {
   const at = m.index + m[0].length
   return text.slice(0, at) + '\n' + block + text.slice(at)
 }
+
+// ---------- releases (docs/DOCS-CHANGELOG.md → release-tool integrations) ----------
+
+const TOOL_SNIPPETS = {
+  'release-please': { after: 'googleapis/release-please-action (id: release)', when: '${{ steps.release.outputs.release_created }}', version: '${{ steps.release.outputs.version }}' },
+  changesets: { after: 'changesets/action (id: changesets)', when: "${{ steps.changesets.outputs.published == 'true' }}", version: '' },
+  'semantic-release': { after: 'npx semantic-release', when: null, version: '' }
+}
+
+/**
+ * .github/workflows/kaloko-release.yml: when a GitHub release is published (release-please, semantic-release with
+ * @semantic-release/github and changesets all publish one) or by hand, `kaloko release <version> --no-write` records
+ * it on Kaloko: the entry the release tool wrote, the accepted runs that are its pictures, and the docs of that
+ * version. `products`: [{ slug, pattern }] (tag patterns such as v* or shop-v*); several products get one step each.
+ */
+export function releaseWorkflow ({ products = [{ slug: null, pattern: 'v*' }], pm = 'npm', dependency = true, version = 'latest', node = 22, tool = null }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const several = products.length > 1
+  const steps = products.map((p) => {
+    const prefix = String(p.pattern || 'v*').split('*')[0]
+    const flag = several || p.slug ? ` --product ${q(p.slug)}` : ''
+    return `      - name: Record ${p.slug || 'the release'} on Kaloko
+${several ? `        if: startsWith(env.TAG, '${prefix}')\n` : ''}        run: ${k} release "\${TAG#${prefix}}"${flag} --no-write`
+  }).join('\n')
+  return `# Kaloko: record every release on Kaloko once your release tool has published it: its changelog entry with
+# before/after pictures, the accepted runs that are its reference, and the docs of that version.
+# Written by kaloko ci github --release${tool ? ` (${tool} found)` : ''}. Secret: KALOKO_TOKEN (tester role, upload scope).
+# kaloko release --no-write only reads CHANGELOG.md; the release tool keeps writing it.
+name: Kaloko release
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag of the release to record (e.g. v2.4.0)
+        required: true
+permissions:
+  contents: read
+jobs:
+  record:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      GH_TOKEN: \${{ github.token }}
+      KALOKO_AGENT: github-actions
+      TAG: \${{ github.event.release.tag_name || inputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.release.tag_name || inputs.tag }}
+          fetch-depth: 0   # the tags and the history since the previous release
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${node}
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}${steps}
+`
+}
+
+/** The step to paste into an existing release workflow, right after the release tool's own step. */
+export function releaseSnippet ({ tool = null, pm = 'npm', dependency = true, version = 'latest', product = null }) {
+  const { kaloko: k } = runner({ pm, dependency, version })
+  const s = TOOL_SNIPPETS[tool] || { after: 'the step that publishes the release', when: null, version: '' }
+  return `# after ${s.after}:
+      - name: Record the release on Kaloko
+${s.when ? `        if: ${s.when}\n` : ''}        run: ${k} release${s.version ? ` ${s.version}` : ''}${product ? ` --product ${q(product)}` : ''} --no-write
+        env:
+          KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+`
+}

package/src/lib/design-cli.mjs

@@ -297,11 +297,31 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
   return { pushed: toPush.length, pulled: toPull.length, conflicts: conflicts.length ? conflicts : null, seq: after.seq }
 }
 
-/** Publishes the draft head as a version (a run of the design environment). */
+/** The notes an agent or person wrote for a version: --notes <file> or --notes - (stdin); null without the option. */
+export async function readNotesArg (value, stdin = process.stdin) {
+  if (value == null || value === false) return null
+  if (value === true) throw new UserError('--notes takes a file (Markdown, text or JSON) or - for standard input.')
+  if (value === '-') { const chunks = []; for await (const c of stdin) chunks.push(c); return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf8') }
+  try { return await readFile(value, 'utf8') } catch { throw new UserError(`--notes: cannot read ${value}.`) }
+}
+
+/** What publishing the draft now would write as "what changed" (kaloko share --notes-preview). */
+export async function previewNotes ({ config, scenario, client, args, say }) {
+  const branch = typeof args.branch === 'string' ? args.branch : 'main'
+  const r = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions/draft/notes?branch=${enc(branch)}`)
+  if (args.json) { say(JSON.stringify(r, null, 2)); return r }
+  const { notesText } = await import('./design-notes.mjs')
+  say(`What publishing now would say (${r.changed} changed, ${r.unchanged} unchanged${r.notes?.from ? ` since v${r.notes.from.version}` : ''}):\n\n${notesText(r.notes, { lang: args.lang === 'cs' ? 'cs' : 'en' })}\n\nWrite your own in a file (a summary, then "step-id: what changed" lines) and publish with kaloko share --notes <file>.`)
+  return r
+}
+
+/** Publishes the draft head as a version (a run of the design environment), with "what changed" notes. */
 export async function publishVersion ({ config, scenario, client, args, say }) {
   const branch = typeof args.branch === 'string' ? args.branch : 'main'
-  const r = await client.request('POST', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions`, { branch, ...(typeof args.name === 'string' ? { name: args.name } : {}) })
+  const notes = await readNotesArg(args.notes)
+  const r = await client.request('POST', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions`, { branch, ...(typeof args.name === 'string' ? { name: args.name } : {}), ...(notes ? { notes } : {}) })
   say(`Version v${r.version}${r.name ? ` "${r.name}"` : ''} · ${r.changed} changed, ${r.unchanged} unchanged${r.changed_steps.length ? ` (${r.changed_steps.join(', ')})` : ''}\n${r.url}`)
+  if (r.notes) { const { notesText } = await import('./design-notes.mjs'); say(`\nWhat changed${notes ? ' (your notes over the generated ones)' : ''}:\n${notesText(r.notes)}`) }
   return r
 }