kaloko 0.5.0 → 0.5.2

package/src/lib/changelog.mjs

@@ -0,0 +1,333 @@
+// `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: { 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)) },
+    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 }
+}
+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 } = {}) {
+  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 (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). */
+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/) — learn by doing, start to finish\n- [How-to guides](how-to/) — one task each\n- [Reference](reference/) — the facts to look up\n- [Explanation](explanation/) — why it works this way\n',
+  'docs/tutorials/README.md': '# Tutorials\n',
+  'docs/how-to/README.md': '# How-to guides\n',
+  'docs/reference/README.md': '# Reference\n',
+  'docs/explanation/README.md': '# Explanation\n'
+}
+
+/**
+ * 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/doctor.mjs

@@ -12,6 +12,7 @@ import { DEFAULTS as JEV } from './jev.mjs'
 import { visionSettings, VISION_WEIGHT } from './vision-core.mjs'
 import { serviceUrl } from './service.mjs'
 import { videoTools, recordingChecks } from './video.mjs'
+import { productChecks } from './changelog.mjs'
 
 const portFree = (port) => new Promise((done) => {
   const s = createServer().once('error', () => done(false)).once('listening', () => s.close(() => done(true)))
@@ -36,8 +37,9 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {string[]} [o.engines] browser engines the scenarios and config.walk ask for (webkit, firefox)
  * @param {Function} [o.launchEngine] async (engine) => { version } — throws when the engine is not installed
  * @param {object} [o.tools] app tools found (default: looked up on PATH)
+ * @param {object[]} [o.scenarios] { file, product, module } of the scenario files (products checks)
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null }) {
+export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [] }) {
   const checks = []
   const add = (name, ok, detail = '', hint = '') => checks.push({ name, ok, detail, hint })
 
@@ -165,6 +167,9 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   // recordings (batch D): ffmpeg and the device recorders, with install hints per OS
   checks.push(...recordingChecks({ config, tools: await (videoToolsImpl || videoTools)() }))
 
+  // the visual changelog: each product's version resolves and scenarios say which product they show
+  checks.push(...await productChecks({ config, root, scenarios }))
+
   return { ok: checks.every((c) => c.ok), checks }
 }
 

package/src/lib/run.mjs

@@ -28,7 +28,7 @@ export function newRunId (scenario, date = new Date()) {
   return { id: `${today(date)}-${slugify(scenario.id)}-${short}`, short }
 }
 
-export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, appVersion = null }) {
+export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, appVersion = null, product = null }) {
   const { id, short } = newRunId(scenario)
   const dir = resolve(root, output, id)
   await mkdir(dir, { recursive: true })
@@ -36,7 +36,7 @@ export async function createRun ({ output, scenario, scenarioFile, env, scope, g
     id,
     short,
     scenario_file: relative(root, scenarioFile),
-    scenario: { id: scenario.id, title: scenario.title, kind: scenario.kind || 'task', version: scenario.version ?? null, source: scenario.source ?? null, ...(scenario.archived ? { archived: true } : {}), ...(scenario.readonly ? { readonly: true } : {}), ...(scenario.platform && scenario.platform !== 'web' ? { platform: scenario.platform } : {}) },
+    scenario: { id: scenario.id, title: scenario.title, kind: scenario.kind || 'task', version: scenario.version ?? null, source: scenario.source ?? null, ...(scenario.archived ? { archived: true } : {}), ...(scenario.readonly ? { readonly: true } : {}), ...(scenario.platform && scenario.platform !== 'web' ? { platform: scenario.platform } : {}), ...(product || scenario.product ? { product: product || scenario.product } : {}), ...(scenario.module ? { module: scenario.module } : {}) },
     environment: { name: env.name, base_url: env.base_url, readonly: env.readonly, ...(env.kind === 'design' ? { kind: 'design' } : {}) },
     scope,
     git,

package/src/lib/signoff-core.mjs

@@ -0,0 +1,138 @@
+// Signed sign-off records (idea 10): canonical JSON, Ed25519 signatures and their verification. Shared by the service
+// (worker/src/signoff.js) and the CLI (kaloko signoff): WebCrypto only, no node: imports, so it runs in both.
+//
+// What is signed: the record without its `signature` field, serialised as canonical JSON ("kaloko-c14n-v1": object
+// keys sorted by UTF-16 code units at every level, no whitespace, undefined values left out, numbers and strings as
+// JSON.stringify writes them). The signature is Ed25519 over the UTF-8 bytes of that text, base64url without padding.
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+
+export const CANONICAL = 'kaloko-c14n-v1'
+export const SIGNOFF_SCHEMA = 'kaloko.signoff.v1'
+export const PDF_ATTACHMENT = 'kaloko-signoff.json'
+/** Marks the embedded file object in a sign-off PDF so the record can be found again without a PDF parser. */
+export const PDF_MARK = '/KalokoSignoff true'
+
+/** Canonical JSON text of a value (see the header). */
+export function canonicalJson (value) {
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'number' && !Number.isFinite(value)) return 'null'
+    return JSON.stringify(value) ?? 'null'
+  }
+  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined || typeof v === 'function' ? 'null' : canonicalJson(v))).join(',')}]`
+  if (typeof value.toJSON === 'function') return canonicalJson(value.toJSON())
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined && typeof value[k] !== 'function').sort()
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`
+}
+
+const bytesOf = (x) => typeof x === 'string' ? enc.encode(x) : x instanceof Uint8Array ? x : new Uint8Array(x)
+
+/** SHA-256 as lowercase hex of a string (UTF-8) or bytes. */
+export async function sha256Hex (data) {
+  const h = new Uint8Array(await crypto.subtle.digest('SHA-256', bytesOf(data)))
+  return [...h].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+/** base64url without padding. */
+export function b64url (bytes) {
+  const b = bytesOf(bytes); let s = ''
+  for (let i = 0; i < b.length; i += 0x8000) s += String.fromCharCode(...b.subarray(i, i + 0x8000))
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+/** Bytes of base64 or base64url (padding optional). */
+export function fromB64url (text) {
+  const s = String(text).trim().replace(/-/g, '+').replace(/_/g, '/').replace(/\s+/g, '')
+  const bin = atob(s + '='.repeat((4 - (s.length % 4)) % 4))
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+const PKCS8_SEED_PREFIX = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20])
+const ED = { name: 'Ed25519' }
+
+/** Key id: the first 16 hex characters of the SHA-256 of the raw public key. */
+export const keyId = async (raw) => (await sha256Hex(raw)).slice(0, 16)
+
+/**
+ * The service's signing key from the secret: a base64/base64url 32-byte Ed25519 seed, a base64 PKCS#8 DER, or a JWK
+ * (JSON with d and x). Returns { privateKey, publicJwk, publicRaw (base64url), kid }.
+ */
+export async function importSigningKey (secret) {
+  const text = String(secret || '').trim()
+  if (!text) throw new Error('No signing key.')
+  let privateKey
+  if (text.startsWith('{')) {
+    const jwk = JSON.parse(text)
+    privateKey = await crypto.subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', d: jwk.d, x: jwk.x, ext: true }, ED, true, ['sign'])
+  } else {
+    const raw = fromB64url(text)
+    let der
+    if (raw.length === 32) { der = new Uint8Array(48); der.set(PKCS8_SEED_PREFIX); der.set(raw, 16) } else der = raw
+    privateKey = await crypto.subtle.importKey('pkcs8', der, ED, true, ['sign'])
+  }
+  const jwk = await crypto.subtle.exportKey('jwk', privateKey)
+  const publicRawBytes = fromB64url(jwk.x)
+  return { privateKey, publicJwk: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, publicRaw: jwk.x, kid: await keyId(publicRawBytes) }
+}
+
+const unsigned = (record) => { const { signature, ...rest } = record || {}; return rest }
+
+/** Signs a record: { ...record, signature: { alg, kid, value, canonical } }. */
+export async function signRecord (record, key) {
+  const body = unsigned(record)
+  const value = new Uint8Array(await crypto.subtle.sign(ED, key.privateKey, enc.encode(canonicalJson(body))))
+  return { ...body, signature: { alg: 'Ed25519', kid: key.kid, value: b64url(value), canonical: CANONICAL } }
+}
+
+/** SHA-256 (hex) of the signed part of a record: what the PDF and the CLI print as the record hash. */
+export const recordSha256 = (record) => sha256Hex(canonicalJson(unsigned(record)))
+
+/** The public keys of a well-known document ({ keys: [...] }), a list, or one key object, as [{ kid, public_key }]. */
+export function keyList (keys) {
+  const list = Array.isArray(keys) ? keys : Array.isArray(keys?.keys) ? keys.keys : keys ? [keys] : []
+  return list.map((k) => ({ kid: k.kid, public_key: k.public_key || k.x || k.jwk?.x })).filter((k) => k.public_key)
+}
+
+/** Verifies a signed record against public keys. Returns { ok, kid, reason }. */
+export async function verifyRecord (signed, keys) {
+  const sig = signed?.signature
+  if (!sig || typeof sig !== 'object') return { ok: false, kid: null, reason: 'The record has no signature.' }
+  if (sig.alg !== 'Ed25519') return { ok: false, kid: sig.kid || null, reason: `Unknown signature algorithm ${sig.alg}.` }
+  if (sig.canonical && sig.canonical !== CANONICAL) return { ok: false, kid: sig.kid || null, reason: `Unknown canonical form ${sig.canonical}.` }
+  const list = keyList(keys)
+  const candidates = sig.kid ? list.filter((k) => !k.kid || k.kid === sig.kid) : list
+  if (!candidates.length) return { ok: false, kid: sig.kid || null, reason: `No public key with id ${sig.kid} (the service may have rotated its key).` }
+  let value
+  try { value = fromB64url(sig.value) } catch { return { ok: false, kid: sig.kid || null, reason: 'The signature is not base64url.' } }
+  const data = enc.encode(canonicalJson(unsigned(signed)))
+  for (const k of candidates) {
+    try {
+      const pub = await crypto.subtle.importKey('raw', fromB64url(k.public_key), ED, false, ['verify'])
+      if (await crypto.subtle.verify(ED, pub, value, data)) return { ok: true, kid: k.kid || sig.kid || null, reason: null }
+    } catch {}
+  }
+  return { ok: false, kid: sig.kid || null, reason: 'The signature does not match: the record was changed after it was signed, or it was signed with another key.' }
+}
+
+/** Reads bytes as latin1 text (one character per byte), for searching a PDF. */
+const latin1 = (b) => { let s = ''; for (let i = 0; i < b.length; i += 0x8000) s += String.fromCharCode(...b.subarray(i, i + 0x8000)); return s }
+
+/** The signed record embedded in a sign-off PDF (the attached kaloko-signoff.json), or null. */
+export function extractRecordFromPdf (bytes) {
+  const b = bytesOf(bytes)
+  const text = latin1(b)
+  const at = text.lastIndexOf(PDF_MARK)
+  if (at < 0) return null
+  const dictStart = text.lastIndexOf('<<', at)
+  const dictEnd = text.indexOf('>>', at)
+  if (dictStart < 0 || dictEnd < 0) return null
+  const len = Number(text.slice(dictStart, dictEnd).match(/\/Length (\d+)/)?.[1])
+  const s = text.indexOf('stream', dictEnd)
+  if (!Number.isFinite(len) || s < 0) return null
+  let start = s + 'stream'.length
+  if (text[start] === '\r') start++
+  if (text[start] === '\n') start++
+  try { return JSON.parse(dec.decode(b.subarray(start, start + len))) } catch { return null }
+}

package/src/lib/signoff.mjs

@@ -0,0 +1,83 @@
+// `kaloko signoff <run> [--out dir] [--lang cs|en] [--json]` downloads the signed acceptance record of an accepted run
+// (JSON and PDF) and checks its signature; `kaloko signoff --verify <file.json|file.pdf> [--key file|url]` checks a
+// record someone handed over, without a token. The keys come from <service>/.well-known/kaloko-signoff.json.
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { UserError } from './util.mjs'
+import { serviceUrl } from './service.mjs'
+import { verifyRecord, recordSha256, extractRecordFromPdf, canonicalJson } from './signoff-core.mjs'
+
+/** Public keys from a file, a URL or the service's well-known document. */
+export async function loadKeys ({ config, key }) {
+  const src = typeof key === 'string' && key ? key : `${serviceUrl(config || {})}/.well-known/kaloko-signoff.json`
+  try {
+    if (/^https?:\/\//.test(src)) {
+      const res = await fetch(src, { headers: { Accept: 'application/json' } })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      return await res.json()
+    }
+    return JSON.parse(await readFile(resolve(src), 'utf8'))
+  } catch (e) { throw new UserError(`Could not read the public keys from ${src}: ${e.message}`) }
+}
+
+/** The signed record in a .json or .pdf file. */
+export async function readRecord (file) {
+  let bytes
+  try { bytes = await readFile(resolve(file)) } catch (e) { throw new UserError(`Cannot read ${file}: ${e.message}`) }
+  if (bytes.subarray(0, 5).toString('latin1') === '%PDF-') {
+    const record = extractRecordFromPdf(new Uint8Array(bytes))
+    if (!record) throw new UserError(`${file} has no Kaloko sign-off record attached.`)
+    return { record, kind: 'pdf' }
+  }
+  try { return { record: JSON.parse(bytes.toString('utf8')), kind: 'json' } } catch { throw new UserError(`${file} is neither a sign-off JSON nor a sign-off PDF.`) }
+}
+
+/** Verification of one record: { ok, kid, reason, sha256, run, verdict }. */
+export async function verifySignoff (record, keys) {
+  const v = await verifyRecord(record, keys)
+  return { ok: v.ok, kid: v.kid, reason: v.reason, sha256: await recordSha256(record), run: record?.run?.id || null, verdict: record?.verdict || null, issuer: record?.issuer?.service || null }
+}
+
+const summary = (r, check) => {
+  const v = r.verdict || {}; const a = r.approvals || {}; const s = r.summary || {}
+  const lines = [
+    `${r.run?.id} · ${r.run?.scenario?.title || r.run?.scenario?.id || ''} · ${r.run?.environment?.name || ''}${r.run?.git?.commit ? ` · ${String(r.run.git.commit).slice(0, 12)}` : ''}`,
+    `  verdict: ${v.verdict} by ${v.by}${v.via && v.via !== 'session' ? ` (${v.via}, not a person's decision)` : ''} on ${String(v.at || '').slice(0, 16).replace('T', ' ')}`,
+    `  approved in the app: ${(a.people || []).map((x) => x.email).join(', ') || 'nobody beyond the verdict'}${(a.tokens_and_agents || []).length ? `; by tokens or agents (not counted as people): ${a.tokens_and_agents.map((x) => x.email).join(', ')}` : ''}`,
+    `  steps: ${s.steps ?? (r.steps || []).length} (${s.pass || 0} pass, ${s.partial || 0} partial, ${s.fail || 0} fail, ${s.skip || 0} not checked)${s.carried ? `, ${s.carried} approval(s) carried over unchanged steps` : ''}`,
+    `  record SHA-256: ${check.sha256}`,
+    `  run.json SHA-256: ${r.manifest?.sha256 || '—'}`,
+    check.ok ? `  ✓ signature valid (Ed25519, key ${check.kid}, ${check.issuer || 'unknown issuer'})` : `  ✕ signature NOT valid: ${check.reason}`
+  ]
+  return lines.join('\n')
+}
+
+/**
+ * The command. `client` is service(config) (only for downloading); `runId` the run to download (a shared run id).
+ */
+export async function signoffCmd ({ config, args, say, client = null, runId = null }) {
+  if (typeof args.verify === 'string') {
+    const { record, kind } = await readRecord(args.verify)
+    const check = await verifySignoff(record, await loadKeys({ config, key: args.key }))
+    if (args.json) say(JSON.stringify({ file: args.verify, kind, ...check }, null, 2))
+    else say(summary(record, check))
+    if (!check.ok) throw new UserError(`The sign-off record in ${args.verify} does not verify: ${check.reason}`)
+    return check
+  }
+  if (!runId) throw new UserError('Usage: kaloko signoff <run-id> [--out dir] [--lang cs|en] | kaloko signoff --verify <file.json|file.pdf> [--key file|url]')
+  if (!client) throw new UserError('Downloading a sign-off record needs the service token (KALOKO_TOKEN).')
+  const base = `/orgs/${config.org}/runs/${encodeURIComponent(runId)}`
+  const lang = args.lang === 'cs' ? 'cs' : 'en'
+  const record = await client.request('GET', `${base}/signoff`)
+  const pdf = Buffer.from(await (await client.fetch(`${base}/signoff.pdf?lang=${lang}`)).arrayBuffer())
+  const dir = resolve(typeof args.out === 'string' ? args.out : '.')
+  await mkdir(dir, { recursive: true })
+  const jsonFile = join(dir, `kaloko-signoff-${runId}.json`); const pdfFile = join(dir, `kaloko-signoff-${runId}.pdf`)
+  await writeFile(jsonFile, canonicalJson(record))
+  await writeFile(pdfFile, pdf)
+  const check = await verifySignoff(record, await loadKeys({ config, key: args.key }))
+  if (args.json) say(JSON.stringify({ json: jsonFile, pdf: pdfFile, ...check }, null, 2))
+  else say(`${summary(record, check)}\nSaved ${jsonFile}\n      ${pdfFile}\nAnyone can check it later: kaloko signoff --verify ${pdfFile}`)
+  if (!check.ok) throw new UserError(`The downloaded record does not verify: ${check.reason}`)
+  return check
+}