kaloko 0.5.2 → 0.6.0

package/src/lib/docs-export.mjs

@@ -0,0 +1,271 @@
+// Exports of living docs and the visual changelog (docs/DOCS-CHANGELOG.md → Exports): Markdown with the pictures as
+// files, folders for Docusaurus, VitePress and MkDocs (sidebars and front matter), a self-contained HTML folder that
+// opens offline, a structured JSON changelog, and neutral blocks for the PDF writer. Pure: the service builds the zip
+// (worker/src/docs-export.js adds the picture files), the CLI unpacks it. No Node built-ins here.
+import { frontMatter, renderMarkdown, buildNav, navOrder, folderTitle, docLink, escapeHtml as esc, inlineHtml } from './docs-core.mjs'
+import { findStepRefs, parseEntry, GROUPS } from './changelog-core.mjs'
+
+export const FORMATS = ['md', 'docusaurus', 'vitepress', 'mkdocs', 'html', 'pdf', 'json']
+export const ZIP_FORMATS = ['md', 'docusaurus', 'vitepress', 'mkdocs', 'html']
+
+/**
+ * The file name of a resolved picture inside an export: assets/<scenario>--<step>--<locale>--<viewport>--<run>.<ext>.
+ * `pic` is a resolver answer ({ scenario, step, locale, viewport, run, file }).
+ */
+export function assetFile (pic) {
+  const ext = (String(pic.file || pic.path || '').match(/\.(png|jpe?g|webp|gif)$/i) || [, 'png'])[1].toLowerCase()
+  const safe = (s) => String(s || '').replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 60)
+  return `assets/${safe(pic.scenario)}--${safe(pic.step?.id || pic.step)}--${safe(pic.locale)}--${safe(pic.viewport)}--${safe(String(pic.run?.id || pic.run || '').split('-').pop())}.${ext}`
+}
+
+/** The key of a picture in a bundle: the reference, in the context of a release for changelog entries (prev). */
+export const pictureKey = (ref, context = null) => `${context || ''}|${ref}`
+
+/** The file of a page inside a docs folder: '' → index.md, 'how-to' (with pages under it) → how-to/index.md. */
+export function pageFile (path, { folders = new Set(), ext = '.md' } = {}) {
+  if (!path) return `index${ext}`
+  return folders.has(path) ? `${path}/index${ext}` : `${path}${ext}`
+}
+const foldersOf = (pages) => new Set(pages.flatMap((p) => p.path.split('/').slice(0, -1).map((_, i, a) => a.slice(0, i + 1).join('/'))))
+
+/** The relative way from one file to another inside the export ('docs/how-to/a.md' → 'docs/assets/x.png'). */
+export function relativePath (from, to) {
+  const a = from.split('/').slice(0, -1); const b = to.split('/')
+  let i = 0
+  while (i < a.length && i < b.length - 1 && a[i] === b[i]) i++
+  return [...a.slice(i).map(() => '..'), ...b.slice(i)].join('/') || to
+}
+
+/**
+ * Markdown with its step references replaced by files of the export: `![alt](kaloko:…)` → `![alt](../assets/…)`.
+ * A reference without a picture becomes its alt text in italics, so the text still reads. Links to other pages are
+ * rewritten by `link(href)` when given.
+ */
+export function localizeMarkdown (md, { file, pictures, context = null, root = 'docs', link = null }) {
+  let out = String(md || '').replace(/!\[([^\]]*)\]\((kaloko:[^)\s]+)\)/g, (_, alt, ref) => {
+    const p = pictures.get(pictureKey(ref, context))
+    if (!p?.ok) return `*${alt || 'picture'}*`
+    return `![${alt || p.alt || ''}](${relativePath(file, `${root}/${p.export_file}`)})`
+  })
+  if (link) out = out.replace(/(?<!!)\[([^\]]+)\]\(([^)\s]+)\)/g, (m, t, href) => { const x = link(href); return x == null ? m : `[${t}](${x})` })
+  return out
+}
+
+/** Every reference a bundle uses, with its context: [{ ref, context }] (docs: null; changelog: the release). */
+export function bundleRefs (bundle) {
+  const out = []; const seen = new Set()
+  const add = (ref, context) => { const k = pictureKey(ref, context); if (!seen.has(k)) { seen.add(k); out.push({ ref, context }) } }
+  for (const p of bundle.pages || []) for (const r of findStepRefs(p.md)) if (r.parsed) add(r.ref, null)
+  for (const r of bundle.releases || []) for (const x of findStepRefs(r.markdown)) if (x.parsed) add(x.ref, r.version)
+  return out
+}
+
+const productTitle = (b) => typeof b.product?.name === 'string' ? b.product.name : b.product?.slug || 'Docs'
+const changelogMarkdown = (b, file, root) => {
+  const head = `# ${b.lang === 'cs' ? 'Co je nového' : 'Changelog'}: ${productTitle(b)}\n`
+  return `${head}\n${(b.releases || []).map((r) => `## [${r.version}] - ${r.released_on}\n\n${localizeMarkdown(String(r.markdown || '').replace(/<!--[\s\S]*?-->/g, '').trim(), { file, pictures: b.pictureMap, context: r.version, root })}\n`).join('\n')}`
+}
+
+/**
+ * Text files of a Markdown export (the pictures are added by the caller from `bundle.pictureMap`):
+ *   md          docs/<page>.md, docs/assets/…, CHANGELOG.md
+ *   docusaurus  docs/<page>.md with title and sidebar_position, _category_.json per folder, docs/changelog.md,
+ *               sidebars.js
+ *   vitepress   docs/<page>.md, docs/changelog.md, docs/.vitepress/config.mjs with the sidebar
+ *   mkdocs      docs/<page>.md, docs/changelog.md, mkdocs.yml with the nav
+ * Returns [{ name, text }].
+ */
+export function markdownExport (bundle, flavor = 'md') {
+  const b = { ...bundle, pictureMap: bundle.pictureMap || new Map() }
+  const pages = b.pages || []
+  const folders = foldersOf(pages)
+  const nav = buildNav(pages.map((p) => ({ path: p.path, title: p.title, order: p.order ?? null })))
+  const fileOf = (path) => `docs/${pageFile(path, { folders })}`
+  const files = []
+  pages.forEach((p) => {
+    const file = fileOf(p.path)
+    const link = (href) => { const t = docLink(p.path, href, { isIndex: folders.has(p.path) || p.path === '' }); return t && pages.some((x) => x.path === t.path) ? `${relativePath(file, fileOf(t.path))}${t.hash ? `#${t.hash}` : ''}` : null }
+    const { data, body } = frontMatter(p.md)
+    let text = localizeMarkdown(body, { file, pictures: b.pictureMap, link })
+    const pos = navOrder(nav).indexOf(p.path) + 1
+    if (flavor === 'docusaurus') text = `---\ntitle: ${yamlString(p.title)}\nsidebar_position: ${data.sidebar_position ?? data.order ?? pos}\n${p.path === '' ? 'slug: /\n' : ''}---\n\n${text.trim()}\n`
+    else if (flavor === 'vitepress' || flavor === 'mkdocs') text = `---\ntitle: ${yamlString(p.title)}\n---\n\n${text.trim()}\n`
+    else text = `${Object.keys(data).length ? `---\n${Object.entries(data).map(([k, v]) => `${k}: ${Array.isArray(v) ? `[${v.join(', ')}]` : yamlString(v)}`).join('\n')}\n---\n\n` : ''}${text.trim()}\n`
+    files.push({ name: file, text })
+  })
+  const hasChangelog = (b.releases || []).length > 0
+  if (hasChangelog) {
+    const file = flavor === 'md' ? 'CHANGELOG.md' : 'docs/changelog.md'
+    let text = changelogMarkdown(b, file, 'docs')
+    if (flavor === 'docusaurus') text = `---\ntitle: ${yamlString(b.lang === 'cs' ? 'Co je nového' : 'Changelog')}\nsidebar_position: 1000\n---\n\n${text}`
+    files.push({ name: file, text })
+  }
+  const label = (n) => n.title || folderTitle(n.path)
+  if (flavor === 'docusaurus') {
+    nav.forEach((n, i) => { if (n.children.length) files.push({ name: `docs/${n.path}/_category_.json`, text: `${JSON.stringify({ label: label(n), position: i + 1 }, null, 2)}\n` }) })
+    const id = (path) => pageFile(path, { folders, ext: '' }).replace(/\/index$/, '/index')
+    const items = nav.map((n) => n.children.length ? { type: 'category', label: label(n), items: [...(n.page ? [id(n.path)] : []), ...n.children.map((c) => id(c.path))] } : id(n.path))
+    if (hasChangelog) items.push('changelog')
+    files.push({ name: 'sidebars.js', text: `// Written by kaloko export --format docusaurus\nmodule.exports = {\n  docs: ${JSON.stringify(items, null, 2).replace(/\n/g, '\n  ')}\n}\n` })
+  }
+  if (flavor === 'vitepress') {
+    const link = (path) => `/${pageFile(path, { folders, ext: '' }).replace(/(^|\/)index$/, '$1')}`
+    const sidebar = nav.map((n) => n.children.length ? { text: label(n), items: [...(n.page ? [{ text: label(n), link: link(n.path) }] : []), ...n.children.map((c) => ({ text: c.title, link: link(c.path) }))] } : { text: label(n), link: link(n.path) })
+    if (hasChangelog) sidebar.push({ text: b.lang === 'cs' ? 'Co je nového' : 'Changelog', link: '/changelog' })
+    files.push({ name: 'docs/.vitepress/config.mjs', text: `// Written by kaloko export --format vitepress\nexport default {\n  title: ${JSON.stringify(productTitle(b))},\n  lang: ${JSON.stringify(b.lang || 'en')},\n  themeConfig: {\n    sidebar: ${JSON.stringify(sidebar, null, 2).replace(/\n/g, '\n    ')}\n  }\n}\n` })
+  }
+  if (flavor === 'mkdocs') {
+    const entry = (path, title) => `${yamlString(title)}: ${pageFile(path, { folders })}`
+    const lines = ['# Written by kaloko export --format mkdocs', `site_name: ${yamlString(productTitle(b))}`, 'docs_dir: docs', 'nav:']
+    for (const n of nav) {
+      if (!n.children.length) { lines.push(`  - ${entry(n.path, label(n))}`); continue }
+      lines.push(`  - ${yamlString(label(n))}:`)
+      if (n.page) lines.push(`      - ${entry(n.path, label(n))}`)
+      for (const c of n.children) lines.push(`      - ${entry(c.path, c.title)}`)
+    }
+    if (hasChangelog) lines.push(`  - ${yamlString(b.lang === 'cs' ? 'Co je nového' : 'Changelog')}: changelog.md`)
+    files.push({ name: 'mkdocs.yml', text: `${lines.join('\n')}\n` })
+  }
+  return files
+}
+const yamlString = (v) => typeof v === 'number' || typeof v === 'boolean' ? String(v) : /^[A-Za-z0-9 ._/-]+$/.test(String(v)) && !/^[-\d]/.test(String(v)) && !/^(true|false|null|yes|no)$/i.test(String(v)) ? String(v) : JSON.stringify(String(v))
+
+// ---------- HTML that opens offline ----------
+
+const HTML_CSS = `:root{--ink:#151514;--muted:#6a6a64;--line:#e4e2dc;--panel:#fff;--bg:#faf9f6;--accent:#ffe452}
+@media (prefers-color-scheme:dark){:root{--ink:#f1f0ec;--muted:#a3a29b;--line:#34332f;--panel:#1d1d1b;--bg:#141413}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.6 -apple-system,"Segoe UI",Roboto,Arial,sans-serif}
+a{color:inherit}.wrap{display:grid;grid-template-columns:240px minmax(0,1fr);gap:32px;max-width:1120px;margin:0 auto;padding:24px 20px 64px}
+nav.side{font-size:14px;position:sticky;top:16px;align-self:start;max-height:calc(100vh - 32px);overflow:auto}nav.side ul{list-style:none;margin:0 0 8px;padding:0}nav.side ul ul{padding-left:12px}nav.side li{margin:2px 0}
+nav.side a{text-decoration:none;display:block;padding:3px 8px;border-radius:6px}nav.side a[aria-current]{background:var(--accent);color:#151514;font-weight:600}nav.side .grp{font-weight:700;margin-top:10px;padding:3px 8px}
+main{min-width:0;max-width:760px}h1{font-size:30px;line-height:1.2;letter-spacing:-.02em}h2{margin-top:2em}img{max-width:100%;height:auto}
+figure{margin:12px 0}figure img{display:block;border:1px solid var(--line);border-radius:10px}figcaption{font-size:13px;color:var(--muted);margin-top:4px}
+pre{background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:12px;overflow:auto}code{font-family:ui-monospace,Menlo,monospace;font-size:.92em}
+table{border-collapse:collapse}td,th{border:1px solid var(--line);padding:4px 8px}.pager{display:flex;justify-content:space-between;gap:12px;margin-top:40px;font-size:14px}.foot{color:var(--muted);font-size:12.5px;margin-top:40px}
+.release{border-top:1px solid var(--line);margin-top:28px;padding-top:8px}.missing{color:var(--muted);font-style:italic}
+@media (max-width:760px){.wrap{grid-template-columns:1fr;gap:12px}nav.side{position:static;max-height:none;border-bottom:1px solid var(--line);padding-bottom:8px}}
+@media print{nav.side,.pager{display:none}.wrap{display:block;max-width:none;padding:0}main{max-width:none}section.page{break-after:page}figure{break-inside:avoid}}`
+
+const doc = ({ lang, title, body }) => `<!doctype html><html lang="${esc(lang || 'en')}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(title)}</title><style>${HTML_CSS}</style></head><body>${body}</body></html>\n`
+
+function htmlPictures (imgs, { file, pictures, context }) {
+  return imgs.map((i) => {
+    const p = i.ref ? pictures.get(pictureKey(i.src, context)) : null
+    if (!i.ref) return /^https?:\/\//.test(i.src) ? `<p><a href="${esc(i.src)}" rel="noopener">${esc(i.alt || i.src)}</a></p>` : ''
+    if (!p?.ok) return `<p class="missing">${esc(i.alt || i.src)}</p>`
+    return `<figure><img src="${esc(relativePath(file, p.export_file))}" alt="${esc(i.alt || p.alt || '')}" loading="lazy"><figcaption>${esc(i.alt || p.step?.title || '')} · ${esc(p.locale)} · ${esc(p.viewport)}</figcaption></figure>`
+  }).join('')
+}
+
+/**
+ * A folder that opens from disk: index.html, one HTML file per page with the sidebar, changelog.html and print.html
+ * (every page in one document, for printing to PDF). Pictures are referenced relatively (assets/…).
+ */
+export function htmlExport (bundle) {
+  const b = { ...bundle, pictureMap: bundle.pictureMap || new Map() }
+  const pages = b.pages || []
+  const folders = foldersOf(pages)
+  const nav = buildNav(pages.map((p) => ({ path: p.path, title: p.title, order: p.order ?? null })))
+  const order = navOrder(nav)
+  const fileOf = (path) => pageFile(path, { folders, ext: '.html' })
+  const hasChangelog = (b.releases || []).length > 0
+  const cl = b.lang === 'cs' ? 'Co je nového' : 'Changelog'
+  const sidebar = (file, current) => `<nav class="side" aria-label="Docs"><ul>${nav.map((n) => {
+    const a = (path, title) => `<a href="${esc(relativePath(file, fileOf(path)))}"${path === current ? ' aria-current="page"' : ''}>${esc(title)}</a>`
+    if (!n.children.length) return `<li>${a(n.path, n.title || folderTitle(n.path))}</li>`
+    return `<li><div class="grp">${n.page ? a(n.path, n.title || folderTitle(n.path)) : esc(n.title || folderTitle(n.path))}</div><ul>${n.children.map((c) => `<li>${a(c.path, c.title)}</li>`).join('')}</ul></li>`
+  }).join('')}${hasChangelog ? `<li><a href="${esc(relativePath(file, 'changelog.html'))}"${current === '#changelog' ? ' aria-current="page"' : ''}>${esc(cl)}</a></li>` : ''}</ul></nav>`
+  const foot = `<p class="foot">${esc(productTitle(b))}${b.version ? ` · ${esc(b.version)}` : ''}${b.generated_at ? ` · ${esc(String(b.generated_at).slice(0, 10))}` : ''}</p>`
+  const pageBody = (p, file) => {
+    const { body } = frontMatter(p.md)
+    const link = (href) => { const t = docLink(p.path, href, { isIndex: folders.has(p.path) || p.path === '' }); return t && pages.some((x) => x.path === t.path) ? `${relativePath(file, fileOf(t.path))}${t.hash ? `#${t.hash}` : ''}` : href }
+    return renderMarkdown(body, { link, picture: (imgs) => htmlPictures(imgs, { file, pictures: b.pictureMap, context: null }) })
+  }
+  const files = []
+  for (const p of pages) {
+    const file = fileOf(p.path)
+    const i = order.indexOf(p.path)
+    const prev = i > 0 ? pages.find((x) => x.path === order[i - 1]) : null
+    const next = i >= 0 && i < order.length - 1 ? pages.find((x) => x.path === order[i + 1]) : null
+    const pager = `<div class="pager"><span>${prev ? `← <a href="${esc(relativePath(file, fileOf(prev.path)))}">${esc(prev.title)}</a>` : ''}</span><span>${next ? `<a href="${esc(relativePath(file, fileOf(next.path)))}">${esc(next.title)}</a> →` : ''}</span></div>`
+    files.push({ name: file, text: doc({ lang: b.lang, title: `${p.title} · ${productTitle(b)}`, body: `<div class="wrap">${sidebar(file, p.path)}<main>${pageBody(p, file)}${pager}${foot}</main></div>` }) })
+  }
+  if (!pages.some((p) => p.path === '')) {
+    const list = nav.map((n) => `<li><a href="${esc(fileOf(n.page ? n.path : n.children[0]?.path))}">${esc(n.title || folderTitle(n.path))}</a></li>`).join('')
+    files.push({ name: 'index.html', text: doc({ lang: b.lang, title: productTitle(b), body: `<div class="wrap">${sidebar('index.html', '')}<main><h1>${esc(productTitle(b))}</h1><ul>${list}</ul>${hasChangelog ? `<p><a href="changelog.html">${esc(cl)}</a></p>` : ''}${foot}</main></div>` }) })
+  }
+  const releasesHtml = (file) => (b.releases || []).map((r) => `<section class="release" id="v${esc(r.version)}"><h2>${esc(r.version)} <small>${esc(r.released_on || '')}</small></h2>${renderMarkdown(String(r.markdown || ''), { picture: (imgs) => htmlPictures(imgs, { file, pictures: b.pictureMap, context: r.version }) })}</section>`).join('')
+  if (hasChangelog) files.push({ name: 'changelog.html', text: doc({ lang: b.lang, title: `${cl} · ${productTitle(b)}`, body: `<div class="wrap">${sidebar('changelog.html', '#changelog')}<main><h1>${esc(cl)}</h1>${releasesHtml('changelog.html')}${foot}</main></div>` }) })
+  const all = order.map((path) => pages.find((p) => p.path === path)).filter(Boolean)
+  files.push({ name: 'print.html', text: doc({ lang: b.lang, title: productTitle(b), body: `<div class="wrap"><main>${all.map((p) => `<section class="page">${pageBody(p, 'print.html')}</section>`).join('')}${hasChangelog ? `<section class="page"><h1>${esc(cl)}</h1>${releasesHtml('print.html')}</section>` : ''}${foot}</main></div>` }) })
+  return files
+}
+
+// ---------- the structured changelog ----------
+
+/**
+ * The changelog as data (schema qawalk.changelog.v1): releases newest first with groups and items, each item with
+ * its pictures (step, locale, viewport, run, image link for signed-in readers, the file in an export when given).
+ */
+export function changelogJson (bundle) {
+  const b = { ...bundle, pictureMap: bundle.pictureMap || new Map() }
+  const pic = (ref, context) => {
+    const p = b.pictureMap.get(pictureKey(ref, context))
+    if (!p?.ok) return { ref, ok: false }
+    return { ref, ok: true, scenario: p.scenario, step: p.step?.id || p.step, title: p.step?.title || null, locale: p.locale, viewport: p.viewport, run: p.run?.id || null, version: p.version?.resolved || null, image: p.image?.url || null, canvas: p.canvas?.step || null }
+  }
+  return {
+    schema: 'qawalk.changelog.v1',
+    product: { slug: b.product?.slug, name: b.product?.name ?? null },
+    generated_at: b.generated_at || null,
+    releases: (b.releases || []).map((r) => {
+      const e = parseEntry(r.markdown || '')
+      return {
+        version: r.version, released_on: r.released_on || null, tag: r.tag || null, notes: e.notes || '',
+        groups: e.groups.map((g) => ({ name: g.name, heading: g.heading, items: g.items.map((it) => ({ text: it.replace(/!\[[^\]]*\]\([^)]*\)/g, '').replace(/<!--[\s\S]*?-->/g, '').replace(/\s+/g, ' ').trim(), pictures: findStepRefs(it).filter((x) => x.parsed).map((x) => pic(x.ref, r.version)) })) }))
+      }
+    }),
+    docs: (b.pages || []).map((p) => ({ path: p.path, lang: p.lang || null, title: p.title, kind: p.kind || null }))
+  }
+}
+
+// ---------- blocks for the PDF writer ----------
+
+/**
+ * A page body as neutral blocks the service turns into PDF blocks (worker/src/pdf.js): { type: 'h1'|'h2'|'h3'|'p'|
+ * 'li'|'code'|'pics', text, refs }. Inline Markdown is reduced to plain text.
+ */
+export function markdownBlocks (md) {
+  const plain = (s) => inlineHtml(s).replace(/<[^>]+>/g, '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+  const out = []
+  const lines = frontMatter(md).body.replace(/<!--[\s\S]*?-->/g, '').split('\n')
+  let para = []
+  const flush = () => {
+    if (!para.length) return
+    const t = para.join(' ')
+    const refs = findStepRefs(t).filter((r) => r.parsed)
+    const words = plain(t.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/\s+/g, ' ').trim())
+    if (words) out.push({ type: para.li ? 'li' : 'p', text: para.li ? `${para.li} ${words}` : words })
+    if (refs.length) out.push({ type: 'pics', refs: refs.map((r) => ({ ref: r.ref, alt: r.alt })) })
+    para = []
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i]
+    if (/^\s{0,3}(```|~~~)/.test(l)) {
+      flush(); const buf = []; i++
+      while (i < lines.length && !/^\s{0,3}(```|~~~)/.test(lines[i])) buf.push(lines[i++])
+      out.push({ type: 'code', text: buf.join('\n') })
+      continue
+    }
+    const h = l.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/)
+    if (h) { flush(); out.push({ type: h[1].length === 1 ? 'h1' : h[1].length === 2 ? 'h2' : 'h3', text: plain(h[2]) }); continue }
+    const li = l.match(/^\s*([-*+]|\d+[.)])\s+(.*)$/)
+    if (li) { flush(); para = [li[2]]; para.li = /\d/.test(li[1]) ? li[1] : '•'; continue }
+    if (!l.trim()) { flush(); continue }
+    para.push(l.trim())
+  }
+  flush()
+  return out
+}
+
+export const GROUP_ORDER = GROUPS

package/src/lib/docs.mjs

@@ -0,0 +1,221 @@
+// `kaloko docs publish|check` and `kaloko export --format …` (docs/DOCS-CHANGELOG.md, phases 2 and 3): the Markdown
+// of a product's docs folder (Diátaxis folders, sibling translations guide.cs.md) sent to the service per version, the
+// checks an agent runs before a pull request (references, stale sections, translations, changelog pictures), and
+// exports the service builds (worker/src/docs-export.js) unpacked into a folder. Shared parsing: docs-core.mjs.
+import { readFile, readdir, writeFile, mkdir, mkdtemp, rm } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join, resolve, relative, dirname } from 'node:path'
+import { tmpdir } from 'node:os'
+import { UserError, sha256 } from './util.mjs'
+import { findStepRefs, cleanVersion } from './changelog-core.mjs'
+import { docFile, frontMatter, docTitle, kindOf, translationReport, itemsWithoutPictures, sections, MAX_PAGE, LANG } from './docs-core.mjs'
+import { FORMATS, ZIP_FORMATS } from './docs-export.mjs'
+import { changelogFile, productPayload, detectVersionSource } from './changelog.mjs'
+import { readZip } from './unzip.mjs'
+
+const run = promisify(execFile)
+const SKIP = new Set(['node_modules', '.git', '.vitepress', '.docusaurus', 'build', 'dist', 'site'])
+
+/** The docs folder of a product: products.<p>.docs.dir, else docs.dir, else docs/. */
+export const docsDir = (root, product) => resolve(root, product.docs?.dir || 'docs')
+
+/** Languages of a product's docs: docs.languages (the first is the originals'), else en plus the translations found. */
+export function docsLanguages (product, pages = []) {
+  const conf = (product.docs?.languages || []).filter((l) => LANG.test(l))
+  if (conf.length) return conf
+  const found = [...new Set(pages.map((p) => p.lang).filter(Boolean))].sort()
+  return ['en', ...found.filter((l) => l !== 'en')]
+}
+
+/** When each file of a folder last changed in git ({ relative path: ISO date }), one git call for the folder. */
+async function gitDates (root, dir) {
+  try {
+    const { stdout } = await run('git', ['log', '--format=@%cI', '--name-only', '--', relative(root, dir) || '.'], { cwd: root, maxBuffer: 50 * 1024 * 1024 })
+    const out = {}; let date = null
+    for (const line of stdout.split('\n')) {
+      if (line.startsWith('@')) { date = line.slice(1); continue }
+      if (line.trim() && date && !(line in out)) out[line.trim()] = date
+    }
+    return out
+  } catch { return {} }
+}
+
+/**
+ * The pages of a product's docs folder: [{ file, path, lang, md, hash, front, title, kind, refs, updated }], sorted by
+ * path then language. Files the service would not take (other extensions, hidden or _partials) are left out.
+ */
+export async function collectDocs (root, product) {
+  const dir = docsDir(root, product)
+  const files = []
+  const walk = async (d) => {
+    let entries = []
+    try { entries = await readdir(d, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || SKIP.has(e.name)) continue
+      const full = join(d, e.name)
+      if (e.isDirectory()) await walk(full); else files.push(full)
+    }
+  }
+  await walk(dir)
+  const dates = await gitDates(root, dir)
+  const pages = []; const seen = new Map()
+  for (const full of files.sort()) {
+    const rel = relative(dir, full).split('\\').join('/')
+    const f = docFile(rel)
+    if (!f) continue
+    const key = `${f.path}|${f.lang || ''}`
+    if (seen.has(key)) throw new UserError(`${relative(root, full)} and ${seen.get(key)} are the same page (${f.path || 'index'}); keep one (index.md or README.md).`)
+    seen.set(key, relative(root, full))
+    const md = await readFile(full, 'utf8')
+    if (md.length > MAX_PAGE) throw new UserError(`${relative(root, full)} is longer than 200 KB; split it.`)
+    const { data } = frontMatter(md)
+    pages.push({ file: relative(root, full), path: f.path, lang: f.lang, md, hash: sha256(md), front: data, title: docTitle(md, f.path), kind: kindOf(f.path), refs: findStepRefs(md), updated: dates[relative(root, full)] || null })
+  }
+  return { dir, pages: pages.sort((a, b) => a.path.localeCompare(b.path) || String(a.lang || '').localeCompare(String(b.lang || ''))) }
+}
+
+// ---------- the check ----------
+
+/**
+ * What needs attention in the docs, from the repository alone: broken references (not kaloko:<scenario>/<step>),
+ * references to scenarios or steps the scenario files do not have (`scenarios`: Map id → Set of step ids), short
+ * references without a default scenario, missing and outdated translations, and user-visible changelog items without a
+ * picture. Returns { pages, broken, unknown, translations, changelog_without_pictures }.
+ */
+export async function localCheck ({ root, product, scenarios = null }) {
+  const { dir, pages } = await collectDocs(root, product)
+  const broken = []; const unknown = []
+  for (const p of pages) {
+    for (const r of p.refs) {
+      if (!r.parsed) { broken.push({ file: p.file, ref: r.ref }); continue }
+      const sc = r.parsed.scenario || product.default_scenario
+      if (!sc) { unknown.push({ file: p.file, ref: r.ref, why: 'A short reference needs default_scenario on the product.' }); continue }
+      if (!scenarios) continue
+      if (!scenarios.has(sc)) unknown.push({ file: p.file, ref: r.ref, why: `No scenario ${sc} in the scenario files.` })
+      else if (!scenarios.get(sc).has(r.parsed.step)) unknown.push({ file: p.file, ref: r.ref, why: `Scenario ${sc} has no step ${r.parsed.step}.` })
+    }
+  }
+  const languages = docsLanguages(product, pages)
+  const translations = translationReport(pages.map((p) => ({ path: p.path, lang: p.lang, hash: p.hash, front: p.front, updated: p.updated })), languages)
+  let changelog = []
+  try { changelog = itemsWithoutPictures(await readFile(changelogFile(root, product), 'utf8')) } catch {}
+  return { dir, pages, languages, broken, unknown, translations, changelog_without_pictures: changelog }
+}
+
+/** The check with the service's half (stale sections, references without an accepted picture), when a client is given. */
+export async function docsCheck ({ root, config, product, client = null, scenarios = null, version = 'latest' }) {
+  const local = await localCheck({ root, product, scenarios })
+  let service = null; let serviceError = null
+  if (client && config.org) {
+    try { service = await client.request('GET', `/orgs/${config.org}/docs/check?${new URLSearchParams({ product: product.slug, version })}`) } catch (e) { serviceError = String(e.message || e).split('\n')[0].slice(0, 200) }
+  }
+  const errors = local.broken.length + local.unknown.length + (service ? service.stale.length + service.unresolved.length : 0)
+  const warnings = local.translations.missing.length + local.translations.outdated.length + local.changelog_without_pictures.length
+  return {
+    product: product.slug, version, dir: relative(root, local.dir) || '.', pages: local.pages.length, languages: local.languages,
+    broken: local.broken, unknown: local.unknown, translations: local.translations, changelog_without_pictures: local.changelog_without_pictures,
+    service: service ? { published: service.published, published_at: service.published_at || null, stale: service.stale, unresolved: service.unresolved, stale_checked: service.stale_checked !== false, url: service.url } : null,
+    service_error: serviceError, errors, warnings, ok: errors === 0
+  }
+}
+
+/** The report for people (kaloko docs check without --json). */
+export function formatCheck (r) {
+  const lines = [`${r.product}: ${r.pages} page(s) in ${r.dir}${r.languages.length > 1 ? ` (${r.languages.join(', ')})` : ''}`]
+  const list = (title, items, fmt) => { if (!items.length) return; lines.push(`  ${title}:`); for (const x of items.slice(0, 30)) lines.push(`    ${fmt(x)}`); if (items.length > 30) lines.push(`    … ${items.length - 30} more`) }
+  list('✗ broken step references', r.broken, (x) => `${x.file}: ${x.ref} (use kaloko:<scenario>/<step>)`)
+  list('✗ unknown steps', r.unknown, (x) => `${x.file}: ${x.ref} — ${x.why}`)
+  if (r.service) {
+    list('✗ stale sections (the screen changed since the text was published)', r.service.stale, (x) => `${x.path || 'index'}${x.lang ? ` (${x.lang})` : ''} § ${x.title || 'intro'}: the screen changed${x.refs[0]?.changed_in ? ` in ${x.refs[0].changed_in}` : ''} — check the text (${x.refs.map((y) => y.ref).join(', ')})`)
+    list('✗ references without an accepted picture', r.service.unresolved, (x) => `${x.path || 'index'}${x.lang ? ` (${x.lang})` : ''}: ${x.ref}`)
+    if (!r.service.published) lines.push('  · nothing published yet: kaloko docs publish')
+    else if (!r.service.stale_checked) lines.push('  · stale sections are checked on the Business plan')
+  } else lines.push(`  · ${r.service_error ? `service: ${r.service_error}` : 'offline: stale sections and pictures need a token'}`)
+  list('! missing translations', r.translations.missing, (x) => `${x.path || 'index'} → ${x.lang}`)
+  list('! outdated translations (the original changed later)', r.translations.outdated, (x) => `${x.path || 'index'} (${x.lang})${x.why === 'source_hash' ? ': source_hash differs' : ''}`)
+  list('! translations without an original', r.translations.orphans, (x) => `${x.path || 'index'} (${x.lang})`)
+  list('! user-visible changelog items without a picture', r.changelog_without_pictures, (x) => `${x.section} ${x.group}: ${x.item}`)
+  lines.push(r.ok ? (r.warnings ? `  ✓ references fine; ${r.warnings} warning(s)` : '  ✓ all fine') : `  ${r.errors} problem(s) to fix`)
+  return lines.join('\n')
+}
+
+// ---------- publishing ----------
+
+/**
+ * Sends the docs folder to the service for a version ('latest' by default, or a released version): the product is
+ * reported first (as kaloko release does), then every page. `reviewed` says the text was checked: stale notes clear.
+ */
+export async function publishDocs ({ root, config, product, client, version = 'latest', reviewed = false, dryRun = false, commit = null }) {
+  const { dir, pages } = await collectDocs(root, product)
+  if (!pages.length) throw new UserError(`No Markdown pages in ${relative(root, dir) || dir}. kaloko init --docs=full creates the folders, or set docs.dir in the config.`)
+  const v = !version || version === 'latest' ? 'latest' : cleanVersion(version)
+  const body = { product: product.slug, version: v, languages: docsLanguages(product, pages), reviewed: !!reviewed, ...(commit ? { commit } : {}), pages: pages.map((p) => ({ path: p.path, lang: p.lang, markdown: p.md })) }
+  const broken = pages.flatMap((p) => p.refs.filter((r) => !r.parsed).map((r) => `${p.file}: ${r.ref}`))
+  if (dryRun) return { dry_run: true, dir: relative(root, dir), version: v, pages: pages.length, languages: body.languages, broken, bytes: JSON.stringify(body).length }
+  const src = await detectVersionSource(root, product)
+  const saved = await client.request('POST', `/orgs/${config.org}/products`, await productPayload(root, product, src))
+  const res = await client.request('POST', `/orgs/${config.org}/docs`, body)
+  return { ...res, dir: relative(root, dir), notes: saved.notes || [], broken_local: broken }
+}
+
+// ---------- exports ----------
+
+/**
+ * Downloads an export from the service and writes it: a folder for md, docusaurus, vitepress, mkdocs and html (the
+ * zip unpacked into `out`), a file for json and pdf. `local` sends the repository's pages instead of the published
+ * ones. A PDF is printed from the offline HTML with the browser when one is installed (real pictures), else the
+ * service's PDF is taken.
+ */
+export async function exportDocs ({ root, config, product, client, format, version = 'latest', lang = null, what = 'all', out = null, local = false, printPdf = null, say = () => {} }) {
+  if (!FORMATS.includes(format)) throw new UserError(`--format must be one of ${FORMATS.join(', ')}.`)
+  const q = (f) => `/orgs/${config.org}/docs/export?${new URLSearchParams({ product: product.slug, format: f, ...(version && version !== 'latest' ? { version } : {}), ...(lang ? { lang } : {}), what })}`
+  const body = local ? { pages: (await collectDocs(root, product)).pages.map((p) => ({ path: p.path, lang: p.lang, markdown: p.md })) } : null
+  const fetchBytes = async (f) => {
+    const res = body ? await client.raw('POST', q(f), body) : await client.fetch(q(f))
+    return Buffer.from(await res.arrayBuffer())
+  }
+  const name = `${product.slug}-${version && version !== 'latest' ? version : 'latest'}${lang ? `-${lang}` : ''}`
+  if (format === 'json' || (format === 'pdf' && !printPdf)) {
+    const file = resolve(out || join(root, config.output || 'tmp/kaloko', 'exports', `${name}.${format}`))
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, await fetchBytes(format))
+    return { format, file, kind: 'file' }
+  }
+  if (format === 'pdf') {
+    // the offline HTML printed by the browser: the pictures as they are (the service's PDF only takes PNG and JPEG)
+    const tmp = await mkdtemp(join(tmpdir(), 'kaloko-pdf-'))
+    try {
+      await unpack(await fetchBytes('html'), tmp)
+      const file = resolve(out || join(root, config.output || 'tmp/kaloko', 'exports', `${name}.pdf`))
+      await mkdir(dirname(file), { recursive: true })
+      try { await printPdf(join(tmp, 'print.html'), file) } catch (e) {
+        say(`  (printing with the browser failed: ${String(e.message || e).split('\n')[0]}; taking the service's PDF)`)
+        await writeFile(file, await fetchBytes('pdf'))
+      }
+      return { format, file, kind: 'file' }
+    } finally { await rm(tmp, { recursive: true, force: true }) }
+  }
+  const dir = resolve(out || join(root, config.output || 'tmp/kaloko', 'exports', `${name}-${format}`))
+  const files = await unpack(await fetchBytes(format), dir)
+  let manifest = null
+  try { manifest = JSON.parse(await readFile(join(dir, 'kaloko-export.json'), 'utf8')) } catch {}
+  return { format, dir, files, kind: 'folder', manifest }
+}
+
+/** Writes the entries of a zip into a folder (paths that would leave it are refused). Returns the number of files. */
+export async function unpack (buf, dir) {
+  const entries = readZip(buf)
+  let n = 0
+  for (const [name, read] of entries) {
+    if (name.endsWith('/')) continue
+    const target = resolve(dir, name)
+    if (!target.startsWith(resolve(dir) + '/')) throw new UserError(`The export holds a path outside its folder: ${name}`)
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, read())
+    n++
+  }
+  return n
+}
+
+export { ZIP_FORMATS, sections }