kaloko 0.12.2 → 0.14.0

package/src/lib/changelog-core.mjs

@@ -10,15 +10,18 @@ const PARAMS = {
   locale: /^[A-Za-z0-9_-]{1,20}$/,
   viewport: /^[A-Za-z0-9._-]{1,80}$/,
   version: /^[A-Za-z0-9._+-]{1,80}$/,
-  state: /^[A-Za-z0-9._-]{1,60}$/
+  state: /^[A-Za-z0-9._-]{1,60}$/,
+  media: /^(video|image)$/
 }
 export const REF_SCHEME = 'kaloko:'
 
 /**
- * A step reference `kaloko:<scenario>/<step>[?locale=&viewport=&version=&state=]`, or the short `kaloko:<step>` that
- * means a step of the product's default scenario. `version` is a released version, `latest` (default) or `prev` (the
- * release before the one the text belongs to); `state` picks a variant of the capture (dark, webkit, reduce: the
- * dimension values in the capture key). Returns null for anything else.
+ * A step reference `kaloko:<scenario>/<step>[?locale=&viewport=&version=&state=&media=]`, or the short `kaloko:<step>`
+ * that means a step of the product's default scenario. `version` is a released version, `latest` (default) or `prev`
+ * (the release before the one the text belongs to); `state` picks a variant of the capture (dark, webkit, reduce: the
+ * dimension values in the capture key); `media` is `video` (play the step's recording; docs check warns when the
+ * accepted run has none) or `image` (never play it). Without `media` the recording plays when the run has one.
+ * Returns null for anything else.
  */
 export function parseStepRef (ref) {
   const s = String(ref || '').trim()
@@ -29,7 +32,7 @@ export function parseStepRef (ref) {
   let parts
   try { parts = path.split('/').map((p) => decodeURIComponent(p)) } catch { return null }
   if (!parts.length || parts.length > 2 || parts.some((p) => !ID.test(p))) return null
-  const out = { scenario: parts.length === 2 ? parts[0] : null, step: parts[parts.length - 1], locale: null, viewport: null, version: null, state: null }
+  const out = { scenario: parts.length === 2 ? parts[0] : null, step: parts[parts.length - 1], locale: null, viewport: null, version: null, state: null, media: null }
   const q = new URLSearchParams(qi < 0 ? '' : rest.slice(qi + 1))
   for (const [k, v] of q) {
     if (!(k in PARAMS)) return null
@@ -41,9 +44,9 @@ export function parseStepRef (ref) {
 }
 
 /** The reference text of a parsed (or hand-built) reference; parameters in a fixed order. */
-export function formatStepRef ({ scenario = null, step, locale = null, viewport = null, version = null, state = null }) {
+export function formatStepRef ({ scenario = null, step, locale = null, viewport = null, version = null, state = null, media = null }) {
   const path = `${scenario ? `${encodeURIComponent(scenario)}/` : ''}${encodeURIComponent(step)}`
-  const q = Object.entries({ locale, viewport, version, state }).filter(([, v]) => v != null && v !== '')
+  const q = Object.entries({ locale, viewport, version, state, media }).filter(([, v]) => v != null && v !== '')
   return `${REF_SCHEME}${path}${q.length ? `?${q.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}` : ''}`
 }
 

package/src/lib/ci.mjs

@@ -103,7 +103,7 @@ function walkScript ({ scenarios, env, affected, k }) {
   return [
     'status=0',
     `for s in ${scenarios.map(q).join(' ')}; do`,
-    ...(affected ? [`  if ! ${k} affected --scenario "$s" --check; then echo "Nothing in $s is affected; skipped."; continue; fi`] : []),
+    ...(affected ? [`  if ! ${k} affected --scenario "$s" --fail-if-none; then echo "Nothing in $s is affected; skipped."; continue; fi`] : []),
     `  ${k} start --scenario "$s" --env ${env}`,
     `  ${k} walk --ephemeral${affected ? ' --affected' : ''} || status=1`,
     `  ${k} share --pr || status=1`,

package/src/lib/cli-args.mjs

@@ -0,0 +1,144 @@
+// The command line of kaloko: arguments, the help of one command and the options each command takes. Both come from
+// the help text (src/cli.mjs HELP), so a documented option is an accepted one; HIDDEN adds aliases and options kept
+// for older scripts that the help no longer shows.
+import { UsageError } from './util.mjs'
+
+/** Options every command takes (Common options in the help). */
+export const COMMON_OPTIONS = ['run', 'config', 'org', 'json', 'help']
+
+/**
+ * Accepted options the help does not show: aliases of renamed ones (--environment is --env, --undo is --off) and
+ * options of sub-commands or older scripts. Each name here is read by the command's code.
+ */
+export const HIDDEN = {
+  prune: ['environment', 'project'],
+  runs: ['environment'],
+  screens: ['environment', 'q', 'source', 'limit'],
+  archive: ['undo'],
+  start: ['note', 'color_schemes', 'reduced_motion', 'forced_colors', 'display_modes', 'token_modes'],
+  design: ['dir', 'token', 'name', 'notes', 'branch', 'allow-pii', 'env'],
+  export: ['server-pdf', 'branch', 'live', 'design'],
+  walk: ['items', 'viewports', 'no-cache', 'record-quality', 'trace', 'offline', 'files'],
+  affected: ['no-upstream', 'check'],
+  open: ['page'],
+  mail: ['viewports'],
+  issue: ['locale', 'viewport', 'target', 'state'],
+  video: ['quality', 'card-seconds', 'viewport'],
+  spec: ['remote', 'scenario', 'version', 'step'],
+  drift: ['locale', 'viewport', 'version', 'scenario', 'step'],
+  history: ['lang'],
+  tokens: ['env', 'version'],
+  stability: ['scenario'],
+  status: ['branch'],
+  feedback: ['branch'],
+  share: ['branch', 'name', 'notes', 'notes-preview', 'strict', 'mine', 'theirs', 'lang'],
+  sync: ['mine', 'theirs', 'branch', 'strict'],
+  reference: ['branch'],
+  branch: ['from', 'git', 'take-branch', 'keep-main', 'scenario'],
+  schedule: ['force'],
+  comment: ['locale'],
+  capture: ['stability'],
+  import: ['executor', 'config', 'locales', 'viewports', 'id', 'title', 'force'],
+  browser: ['env', 'run'],
+  ci: ['wait', 'github-env', 'dotenv']
+}
+
+/** Commands whose unknown options stop the command instead of a warning: they delete, publish or change access. */
+export const STRICT = new Set(['prune', 'trash', 'restore', 'keep', 'archive', 'public', 'release', 'comment'])
+
+/**
+ * argv → { _: positional, <option>: value | true }. `--key=value` splits at the first `=` only; `--key value` takes
+ * the next word unless it is another option; `-h` and `-v` are --help and --version.
+ */
+export function parseArgs (argv) {
+  const args = { _: [] }
+  const short = { '-h': 'help', '-v': 'version' }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=')
+      const k = eq < 0 ? a.slice(2) : a.slice(2, eq)
+      const next = argv[i + 1]
+      if (eq >= 0) args[k] = a.slice(eq + 1)
+      else if (next && !next.startsWith('--') && !short[next]) args[k] = argv[++i]
+      else args[k] = true
+    } else if (short[a]) args[short[a]] = true
+    else args._.push(a)
+  }
+  return args
+}
+
+/**
+ * The help text as entries: each "  <command> …" line with its continuation lines, the commands it documents (the
+ * first word, and words after " | " such as "trash … | restore") and its section heading.
+ */
+export function helpEntries (help) {
+  const out = []
+  let section = ''
+  let cur = null
+  for (const line of help.split('\n')) {
+    if (/^[A-Z]/.test(line)) { section = line; cur = null; continue }
+    const m = line.match(/^ {2}([a-z][a-z-]*)/)
+    if (m) {
+      cur = { section, commands: new Set([m[1], ...[...line.matchAll(/ \| ([a-z][a-z-]*)/g)].map((x) => x[1])]), lines: [line] }
+      out.push(cur)
+    } else if (cur && /^ {3,}\S/.test(line)) cur.lines.push(line)
+    else cur = null
+  }
+  return out
+}
+
+/**
+ * The help of one command: its entries under their section headings, then `common`; null for an unknown one. With
+ * `sub` (kaloko help export run, kaloko export run --help) only the entries of that sub-command, when it has any.
+ */
+export function helpFor (help, name, common = '', sub = null) {
+  let entries = helpEntries(help).filter((e) => e.commands.has(name))
+  if (!entries.length) return null
+  const own = typeof sub === 'string' ? entries.filter((e) => (e.lines[0].match(new RegExp(`^ {2}${name} ([a-z][a-z|-]*)`))?.[1] || '').split('|').includes(sub)) : []
+  if (own.length) { entries = own; name = `${name} ${sub}` }
+  const parts = []
+  let section = null
+  for (const e of entries) {
+    if (e.section !== section) { section = e.section; parts.push(`${parts.length ? '\n' : ''}${section}`) }
+    parts.push(...e.lines)
+  }
+  return `Usage: kaloko ${name} [options]\n\n${parts.join('\n')}\n${common ? `\n${common}` : ''}`
+}
+
+/** The options a command takes: the ones its help names, the hidden ones and the common ones. */
+export function optionsFor (help, name) {
+  const named = helpEntries(help).filter((e) => e.commands.has(name)).flatMap((e) => e.lines.join('\n').match(/--[a-z][a-z0-9-]*/g) || [])
+  return new Set([...named.map((f) => f.slice(2)), ...(HIDDEN[name] || []), ...COMMON_OPTIONS])
+}
+
+/** Edit distance (insertions, deletions, substitutions) between two short words. */
+export function distance (a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    prev = row
+  }
+  return prev[b.length]
+}
+
+/** The closest of `words` to `word` within 2 edits (a typo), or null. */
+export function closest (word, words) {
+  let best = null; let d = 3
+  for (const w of words) { const x = distance(word, w); if (x < d) { d = x; best = w } }
+  return best
+}
+
+/**
+ * Options `args` has that `name` does not take: a UsageError for commands in STRICT (nothing has happened yet), a
+ * list of warning lines for the others (they run as before, without the unknown option).
+ */
+export function checkOptions (help, name, args) {
+  const known = optionsFor(help, name)
+  const unknown = Object.keys(args).filter((k) => k !== '_' && k !== '' && !known.has(k))
+  if (!unknown.length) return []
+  const lines = unknown.map((k) => { const guess = closest(k, [...known]); return `kaloko ${name} does not take --${k}.${guess ? ` Did you mean --${guess}?` : ''}` })
+  if (STRICT.has(name)) throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
+  return lines.map((l) => `! ${l} It is ignored (kaloko help ${name} lists the options).`)
+}

package/src/lib/config.mjs

@@ -1,9 +1,10 @@
 import { readFile, access } from 'node:fs/promises'
-import { join, dirname, resolve } from 'node:path'
+import { join, dirname, resolve, basename } from 'node:path'
 import { homedir } from 'node:os'
 import yaml from 'js-yaml'
 import { schemaErrors } from './schema.mjs'
 import { UserError, localized, globToRegExp } from './util.mjs'
+import { noteLegacy, legacyVariables } from './legacy.mjs'
 
 export const CONFIG_FILE = 'kaloko.config.yml'
 /** The file name before the rename to Kaloko; still found, so existing projects keep working. */
@@ -17,8 +18,13 @@ export function aliasLegacyEnv (vars = process.env) {
     if (m && vars[`${m[1] === 'QAWALK' ? 'KALOKO' : 'QAWALK'}_${m[2]}`] == null) vars[`${m[1] === 'QAWALK' ? 'KALOKO' : 'QAWALK'}_${m[2]}`] = v
   }
 }
+// the variables as the shell gave them, before aliasing: QAWALK_* names someone still sets (kaloko doctor, legacy.mjs)
+const shellVars = { ...process.env }
 aliasLegacyEnv()
 
+/** QAWALK_* variables set in the shell (not copies of KALOKO_* ones). */
+export const legacyShellVariables = () => legacyVariables(shellVars)
+
 async function exists (file) {
   try { await access(file); return true } catch { return false }
 }
@@ -37,13 +43,17 @@ export async function loadConfig (start = process.cwd(), explicit) {
     }
   }
   if (!file) throw new UserError(`${CONFIG_FILE} not found. Run "kaloko init" in the project root.`)
+  if (basename(file) === LEGACY_CONFIG_FILE) noteLegacy(LEGACY_CONFIG_FILE, CONFIG_FILE)
+  for (const k of legacyShellVariables()) noteLegacy(k, `KALOKO_${k.slice(7)}`)
   // the user-level file holds personal keys and tokens: tests (node --test) and KALOKO_USER_ENV=0 leave it out
   const userEnv = process.env.KALOKO_USER_ENV !== '0' && !process.env.NODE_TEST_CONTEXT
+  if (userEnv && await exists(join(homedir(), '.config', 'qawalk', '.env'))) noteLegacy('~/.config/qawalk/.env', '~/.config/kaloko/.env')
   await loadEnvFiles([join(dirname(file), '.env'), ...(userEnv ? [join(homedir(), '.config', 'kaloko', '.env'), join(homedir(), '.config', 'qawalk', '.env')] : [])])
   aliasLegacyEnv()
   const config = yaml.load(await readFile(file, 'utf8'))
   const problems = schemaErrors('config.v1', config)
   if (problems.length) throw new UserError(`${file} is invalid:\n  - ${problems.join('\n  - ')}`)
+  aliasConfigKeys(config, file)
   // projects started before the rename keep their run folder (it is in their .gitignore)
   config.output ||= !(await exists(join(dirname(file), 'tmp', 'kaloko'))) && (await exists(join(dirname(file), 'tmp', 'qawalk'))) ? 'tmp/qawalk' : 'tmp/kaloko'
   config.browser ||= {}
@@ -53,6 +63,19 @@ export async function loadConfig (start = process.cwd(), explicit) {
   return { config, root: dirname(file), file }
 }
 
+/**
+ * Config keys with a newer name: environments.<env>.default_token_mode is read as tokens_mode (its older name, which
+ * the code reads and which keeps working). Both with different values is a mistake worth stopping for.
+ */
+export function aliasConfigKeys (config, file = CONFIG_FILE) {
+  for (const [name, env] of Object.entries(config.environments || {})) {
+    if (env?.default_token_mode == null) continue
+    if (env.tokens_mode != null && env.tokens_mode !== env.default_token_mode) throw new UserError(`${file}: environments.${name} sets default_token_mode: ${env.default_token_mode} and tokens_mode: ${env.tokens_mode}. tokens_mode is the older name of default_token_mode; keep one.`)
+    env.tokens_mode = env.default_token_mode
+  }
+  return config
+}
+
 export function environment (config, name, vars = process.env) {
   const env = config.environments[name]
   if (!env) throw new UserError(`Unknown environment "${name}". Known: ${Object.keys(config.environments).join(', ')}`)
@@ -116,6 +139,7 @@ export async function loadEnvFiles (files) {
     try { text = await readFile(file, 'utf8') } catch { continue }
     for (const line of text.split('\n')) {
       const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/)
+      if (m && /^QAWALK_[A-Z0-9_]+$/.test(m[1])) noteLegacy(m[1], `KALOKO_${m[1].slice(7)}`)
       if (!m || process.env[m[1]] !== undefined) continue
       process.env[m[1]] = m[2].replace(/^(['"])(.*)\1$/, '$2')
     }

package/src/lib/design-cli.mjs

@@ -3,7 +3,7 @@
 import { readFile, writeFile, mkdir, rm, readdir } from 'node:fs/promises'
 import { gzipSync, gunzipSync } from 'node:zlib'
 import { join, dirname, relative } from 'node:path'
-import { readJson, writeJson, UserError } from './util.mjs'
+import { readJson, writeJson, UserError, UsageError } from './util.mjs'
 import { readCaptures, addCapture, runPaths } from './run.mjs'
 import { latestCaptures, criteriaHash, evaluationSource } from './evaluate.mjs'
 import { captureStep } from './capture.mjs'
@@ -198,7 +198,7 @@ export async function uploadBlobs ({ client, org, files, say }) {
       const raw = await readFile(f.abs)
       const gz = TEXT_TYPES.has(f.ext) && raw.length > 512
       const body = gz ? gzipSync(raw, { level: 6 }) : raw
-      await client.upload(`/orgs/${org}/blobs/${h}`, body, f.abs, { 'X-QAwalk-Type': f.ext, ...(gz ? { 'Content-Encoding': 'gzip' } : {}) })
+      await client.upload(`/orgs/${org}/blobs/${h}`, body, f.abs, { 'X-Kaloko-Type': f.ext, 'X-QAwalk-Type': f.ext, ...(gz ? { 'Content-Encoding': 'gzip' } : {}) })
       bytes += body.length
     }
   }
@@ -267,7 +267,7 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
         try { if (await sha256Hex(await readFile(target)) === hash) continue } catch {}
         const res = await client.fetch(`/orgs/${org}/revisions/${rev.id}/files/${p.split('/').map(enc).join('/')}`)
         let buf = Buffer.from(await res.arrayBuffer())
-        if (res.headers.get('X-QAwalk-Encoding') === 'gzip') buf = gunzipSync(buf)
+        if ((res.headers.get('X-Kaloko-Encoding') || res.headers.get('X-QAwalk-Encoding')) === 'gzip') buf = gunzipSync(buf)
         await mkdir(dirname(target), { recursive: true })
         await writeFile(target, buf)
       }
@@ -470,7 +470,7 @@ export async function tokensCmd ({ config, root, env, client, args, say, project
     if (args.json) { say(JSON.stringify(report, null, 2)); return }
     if (!report.offenders.length) say(`✓ Every color, font, size, spacing and radius in ${relative(process.cwd(), dir)} comes from the token set (${report.checked} values).`)
     else { say(`${report.offenders.length} raw value(s) outside the token set:\n  - ${report.offenders.slice(0, 40).map((o) => `${o.file}:${o.line} ${o.property}: ${o.value}${o.deprecated ? ` (deprecated token ${o.deprecated}${o.note ? `: ${o.note}` : ''})` : ''}${o.suggest ? `  → ${o.suggest}` : ''}`).join('\n  - ')}`); process.exitCode = 1 }
-  } else throw new UserError('Usage: kaloko tokens pull|push|check|validate [--project p] [--file tokens.json|tokens.resolver.json] [--mode m] [--json]')
+  } else throw new UsageError('Usage: kaloko tokens pull|push|check|validate [--project p] [--file tokens.json|tokens.resolver.json] [--mode m] [--json]')
 }
 
 /** Writes the live files of a version (or the draft) into a folder: the handoff, or taking back canvas edits. */
@@ -488,7 +488,7 @@ export async function exportLive ({ config, scenarioId, client, args, say, out }
       try { if (await sha256Hex(await readFile(target)) === hash) continue } catch {}
       const res = await client.fetch(`/orgs/${config.org}/revisions/${s.revision}/files/${p.split('/').map(enc).join('/')}`)
       let buf = Buffer.from(await res.arrayBuffer())
-      if (res.headers.get('X-QAwalk-Encoding') === 'gzip') buf = gunzipSync(buf)
+      if ((res.headers.get('X-Kaloko-Encoding') || res.headers.get('X-QAwalk-Encoding')) === 'gzip') buf = gunzipSync(buf)
       await mkdir(dirname(target), { recursive: true })
       await writeFile(target, buf)
       written++
@@ -510,13 +510,13 @@ export async function branchCmd ({ config, scenarioId, client, args, say }) {
     return
   }
   if (action === 'create') {
-    if (!name) throw new UserError('Usage: kaloko branch create <name> [--from vN|draft] [--git <branch>]')
+    if (!name) throw new UsageError('Usage: kaloko branch create <name> [--from vN|draft] [--git <branch>]')
     const r = await client.request('POST', base, { name, ...(typeof args.from === 'string' ? { from: args.from } : {}), ...(typeof args.git === 'string' ? { git_branch: args.git } : {}) })
     say(`Branch ${r.branch} created from ${r.based_on_version || 'the draft'} (${r.steps} step×locale). Work on it with --branch ${r.branch}.`)
     return
   }
   if (action === 'merge') {
-    if (!name) throw new UserError('Usage: kaloko branch merge <name> [--take-branch a,b] [--keep-main c]')
+    if (!name) throw new UsageError('Usage: kaloko branch merge <name> [--take-branch a,b] [--keep-main c]')
     const choices = {}
     try {
       const r = await client.request('POST', `${base}/${enc(name)}/merge`, { choices: await choicesFrom(args, client, config, scenarioId, name) })
@@ -528,7 +528,7 @@ export async function branchCmd ({ config, scenarioId, client, args, say }) {
     }
     return choices
   }
-  throw new UserError('Usage: kaloko branch list | create <name> [--from vN] [--git <branch>] | merge <name> [--take-branch a,b] [--keep-main c]')
+  throw new UsageError('Usage: kaloko branch list | create <name> [--from vN] [--git <branch>] | merge <name> [--take-branch a,b] [--keep-main c]')
 }
 
 async function choicesFrom (args, client, config, scenarioId, name) {
@@ -556,7 +556,7 @@ async function forkViews ({ config, client, args, say, out, data }) {
     for (const [p] of Object.entries(v.files)) {
       const res = await client.fetch(`/orgs/${config.org}/revisions/${v.revision}/files/${p.split('/').map(enc).join('/')}`)
       let buf = Buffer.from(await res.arrayBuffer())
-      if (res.headers.get('X-QAwalk-Encoding') === 'gzip') buf = gunzipSync(buf)
+      if ((res.headers.get('X-Kaloko-Encoding') || res.headers.get('X-QAwalk-Encoding')) === 'gzip') buf = gunzipSync(buf)
       const target = join(out, prefix, p)
       await mkdir(dirname(target), { recursive: true })
       await writeFile(target, buf)

package/src/lib/design-export.mjs

@@ -136,7 +136,7 @@ export async function exportDesign ({ config, scenarioId, client, ref = 'design'
   for (const [p, { revision }] of paths) {
     const res = await client.fetch(`/orgs/${org}/revisions/${revision}/files/${p.split('/').map(enc).join('/')}`)
     let buf = Buffer.from(await res.arrayBuffer())
-    if (res.headers.get('X-QAwalk-Encoding') === 'gzip') buf = gunzipSync(buf)
+    if ((res.headers.get('X-Kaloko-Encoding') || res.headers.get('X-QAwalk-Encoding')) === 'gzip') buf = gunzipSync(buf)
     await sink.put(p, buf)
   }
   const steps = []

package/src/lib/docs-export.mjs

@@ -18,6 +18,17 @@ export function assetFile (pic) {
   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 files of a step's recording inside an export, next to its picture (assetFile with .mp4 / .webm), or null when
+ * the resolved reference carries no recording ({ video: { files: { mp4, webm } } }).
+ */
+export function videoAssets (pic) {
+  const files = pic?.video?.files
+  if (!files || !(files.mp4 || files.webm)) return null
+  const base = assetFile(pic).replace(/\.[a-z]+$/, '')
+  return { mp4: files.mp4 ? `${base}.mp4` : null, webm: files.webm ? `${base}.webm` : null }
+}
+
 /** 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}`
 
@@ -37,14 +48,33 @@ export function relativePath (from, 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.
+ * A step's recording in exported Markdown (`p.export_video`): a player with the picture as its poster. Docusaurus
+ * gets JSX whose require() bundles the files; VitePress HTML with ./ paths (Vue turns them into imports); MkDocs, whose
+ * page addresses are folders (raw HTML paths would miss), the picture linked to the recording; plain Markdown the
+ * player with that linked picture inside, which renderers without <video> (GitHub) show instead.
+ */
+function videoMarkdown (p, alt, { file, root, flavor }) {
+  const rel = (f) => { const r = relativePath(file, `${root}/${f}`); return flavor === 'vitepress' && !r.startsWith('.') ? `./${r}` : r }
+  const poster = rel(p.export_file); const v = p.export_video
+  const linked = `[![${alt}](${poster})](${rel(v.mp4 || v.webm)})`
+  if (flavor === 'mkdocs') return linked
+  if (flavor === 'docusaurus') {
+    const req = (f) => `{require('${rel(f).replace(/'/g, "\\'")}').default}`
+    return `<video controls muted playsInline preload="none" poster=${req(p.export_file)} title=${JSON.stringify(alt)}>${v.mp4 ? `<source src=${req(v.mp4)} type="video/mp4" />` : ''}${v.webm ? `<source src=${req(v.webm)} type="video/webm" />` : ''}</video>`
+  }
+  return `<video controls muted playsinline preload="none" poster="${esc(poster)}" title="${esc(alt)}">${v.mp4 ? `<source src="${esc(rel(v.mp4))}" type="video/mp4">` : ''}${v.webm ? `<source src="${esc(rel(v.webm))}" type="video/webm">` : ''}${flavor === 'md' ? linked : ''}</video>`
+}
+
+/**
+ * Markdown with its step references replaced by files of the export: `![alt](kaloko:…)` → `![alt](../assets/…)`, or
+ * a player for a step whose recording plays (videoMarkdown). 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 }) {
+export function localizeMarkdown (md, { file, pictures, context = null, root = 'docs', link = null, flavor = 'md' }) {
   let out = String(md || '').replace(/!\[([^\]]*)\]\((kaloko:[^)\s]+)\)/g, (_, alt, ref) => {
     const p = pictures.get(pictureKey(ref, context))
     if (!p?.ok) return `*${alt || 'picture'}*`
+    if (p.export_video) return videoMarkdown(p, alt || p.alt || '', { file, root, flavor })
     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})` })
@@ -61,9 +91,9 @@ export function bundleRefs (bundle) {
 }
 
 const productTitle = (b) => typeof b.product?.name === 'string' ? b.product.name : b.product?.slug || 'Docs'
-const changelogMarkdown = (b, file, root) => {
+const changelogMarkdown = (b, file, root, flavor) => {
   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')}`
+  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, flavor })}\n`).join('\n')}`
 }
 
 /**
@@ -86,7 +116,7 @@ export function markdownExport (bundle, flavor = 'md') {
     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 })
+    let text = localizeMarkdown(body, { file, pictures: b.pictureMap, link, flavor })
     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`
@@ -96,7 +126,7 @@ export function markdownExport (bundle, flavor = 'md') {
   const hasChangelog = (b.releases || []).length > 0
   if (hasChangelog) {
     const file = flavor === 'md' ? 'CHANGELOG.md' : 'docs/changelog.md'
-    let text = changelogMarkdown(b, file, 'docs')
+    let text = changelogMarkdown(b, file, 'docs', flavor)
     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 })
   }
@@ -139,7 +169,7 @@ a{color:inherit}.wrap{display:grid;grid-template-columns:240px minmax(0,1fr);gap
 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}
+figure{margin:12px 0}figure video{display:block;max-width:100%;height:auto;border:1px solid var(--line);border-radius:10px;background:#111}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}
@@ -153,6 +183,10 @@ function htmlPictures (imgs, { file, pictures, context }) {
     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>`
+    // a step's recording: the player with the picture as poster; it plays when the reader starts it
+    // print.html (the CLI's PDF is printed from it) keeps the picture: a PDF cannot play anything
+    const v = file === 'print.html' ? null : p.export_video
+    if (v) return `<figure><video controls muted playsinline preload="none" poster="${esc(relativePath(file, p.export_file))}" title="${esc(i.alt || p.alt || '')}">${v.mp4 ? `<source src="${esc(relativePath(file, v.mp4))}" type="video/mp4">` : ''}${v.webm ? `<source src="${esc(relativePath(file, v.webm))}" type="video/webm">` : ''}<img src="${esc(relativePath(file, p.export_file))}" alt="${esc(i.alt || p.alt || '')}"></video><figcaption>${esc(i.alt || p.step?.title || '')} · ${esc(p.locale)} · ${esc(p.viewport)}</figcaption></figure>`
     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('')
 }
@@ -212,7 +246,7 @@ export function changelogJson (bundle) {
   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 { 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, ...(p.video ? { video: { mp4: p.video.mp4 || null, webm: p.video.webm || null, duration_ms: p.video.duration_ms ?? null } } : {}), canvas: p.canvas?.step || null }
   }
   return {
     schema: 'qawalk.changelog.v1',

package/src/lib/docs.mjs

@@ -111,11 +111,11 @@ export async function docsCheck ({ root, config, product, client = null, scenari
     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
+  const warnings = local.translations.missing.length + local.translations.outdated.length + local.changelog_without_pictures.length + (service?.no_recording?.length || 0)
   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: service ? { published: service.published, published_at: service.published_at || null, stale: service.stale, unresolved: service.unresolved, no_recording: service.no_recording || [], stale_checked: service.stale_checked !== false, url: service.url } : null,
     service_error: serviceError, errors, warnings, ok: errors === 0
   }
 }
@@ -129,6 +129,7 @@ export function formatCheck (r) {
   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}`)
+    list('! media=video, but the accepted run has no recording of the step (readers see the picture; walk it with --record)', r.service.no_recording || [], (x) => `${x.release ? `changelog ${x.release}` : `${x.path || 'index'}${x.lang ? ` (${x.lang})` : ''}`}: ${x.ref}${x.run ? ` (run ${x.run})` : ''}`)
     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'}`)

package/src/lib/doctor.mjs

@@ -44,7 +44,7 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  *   scenario folders, write org: from the token into the config, ask macOS for permissions
  * @param {Function} [o.installBrowser] async (engine) => void — installs a Playwright engine (--fix)
  */
-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 = [], installBrowser = defaultInstall }) {
+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 = [], installBrowser = defaultInstall, legacy = [] }) {
   const checks = []
   const add = (name, ok, detail = '', hint = '', fixed = null) => checks.push({ name, ok, detail, hint, ...(fixed ? { fixed } : {}) })
   // --fix: install an engine, then look again; returns the version or throws what the install said
@@ -54,6 +54,8 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   add('node', major >= 20, `Node ${process.versions.node}`, major >= 20 ? '' : 'Kaloko needs Node 20 or newer.')
 
   add('config', true, `${file || `${root}/kaloko.config.yml`} · org ${config.org || '—'} · ${Object.keys(config.environments || {}).length} environments`)
+  // names from before the rename that still work (legacy.mjs): listed with their new names, never a failure
+  if (legacy.length) add('old names', true, `${legacy.map((x) => `${x.old} → ${x.now}`).join(', ')} (they still work; rename them when convenient)`)
   if (!config.org) add('org', false, 'no org in config', 'Set org: <slug> (the part after kaloko.app/ when you are signed in), or run kaloko doctor --fix with a token to fill it in.')
   await folderChecks({ config, root, fix, add })
 

package/src/lib/integrations-cli.mjs

@@ -4,7 +4,7 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { resolve, relative, dirname, join } from 'node:path'
-import { UserError, NO_ORG } from './util.mjs'
+import { UserError, UsageError, NO_ORG } from './util.mjs'
 import { gateOf, accountFor } from './access.mjs'
 import { secret } from './secrets.mjs'
 import { runner } from './ci.mjs'
@@ -31,7 +31,7 @@ export async function issueCmd ({ args, config, client, runId, say }) {
     say(items.length ? items.map(issueLine).join('\n') : 'No issues created from steps yet.')
     return items
   }
-  if (sub !== 'create') throw new UserError('Usage: kaloko issue create --step <id> --to jira|linear [--criterion AC2] [--title "…"] [--note "…"] [--run id]\n       kaloko issue list [--run id] [--scenario id] [--state open|done|canceled] [--json]')
+  if (sub !== 'create') throw new UsageError('Usage: kaloko issue create --step <id> --to jira|linear [--criterion AC2] [--title "…"] [--note "…"] [--run id]\n       kaloko issue list [--run id] [--scenario id] [--state open|done|canceled] [--json]')
   const to = String(args.to || '')
   if (!['jira', 'linear'].includes(to)) throw new UserError('--to jira or --to linear says where the issue goes.')
   if (typeof args.step !== 'string' || !args.step) throw new UserError('--step <id> names the step the issue is about.')
@@ -137,7 +137,8 @@ export function secretNames (env, scenario = {}) {
 
 /**
  * `kaloko schedule add --scenario <file> --env <name> [--every day|week|manual] [--at 5] [--weekday mon] [--account key]`,
- * `list`, `run <id>`, `pause <id>`, `resume <id>`, `remove <id>`, `export github --scenario <file> --env <name>`.
+ * `list`, `run <id>`, `pause <id>`, `resume <id>`, `remove <id>`, `hook <id> [--remove] [--json]`,
+ * `export github --scenario <file> --env <name>`.
  * deps: { loadScenario, environment, baseUrl, projectAndIssue, packageRoot, service }.
  */
 export async function scheduleCmd ({ args, config, root, say, deps }) {
@@ -145,7 +146,7 @@ export async function scheduleCmd ({ args, config, root, say, deps }) {
   const org = config.org
   const client = () => deps.service(config)
   if (sub === 'export') {
-    if (id !== 'github') throw new UserError('Usage: kaloko schedule export github --scenario <file> --env <name> [--every day|week] [--at 5] [--weekday mon] [--out file] [--print] [--force]')
+    if (id !== 'github') throw new UsageError('Usage: kaloko schedule export github --scenario <file> --env <name> [--every day|week] [--at 5] [--weekday mon] [--out file] [--print] [--force]')
     const file = typeof args.scenario === 'string' ? resolve(root, args.scenario) : null
     if (!file) throw new UserError('--scenario <file> names the scenario to walk.')
     const envName = typeof args.env === 'string' ? args.env : null
@@ -202,10 +203,18 @@ export async function scheduleCmd ({ args, config, root, say, deps }) {
     if ((s.skipped || []).length) say('  Steps that click or type need the full walk: kaloko schedule export github')
     return s
   }
-  if (!id) throw new UserError(`Usage: kaloko schedule ${sub} <schedule id> (kaloko schedule list shows them)`)
+  if (!id) throw new UsageError(`Usage: kaloko schedule ${sub} <schedule id> (kaloko schedule list shows them)`)
   const path = `/orgs/${org}/schedules/${encodeURIComponent(id)}`
   if (sub === 'run') { await client().request('POST', `${path}/run`); say(`✓ ${id} starts within 15 minutes; the run lands in your inbox.`); return }
   if (sub === 'pause' || sub === 'resume') { const s = await client().request('PATCH', path, { enabled: sub === 'resume' }); say(`✓ ${id} ${s.enabled ? `resumed: ${when(s)}` : 'paused'}`); return s }
   if (sub === 'remove') { await client().request('DELETE', path); say(`✓ ${id} removed; its runs stay.`); return }
-  throw new UserError('Usage: kaloko schedule add|list|run|pause|resume|remove|export github (kaloko help)')
+  // the webhook trigger: a deploy or CI job starts the run with the secret (shown once, here)
+  if (sub === 'hook') {
+    if (args.remove) { await client().request('DELETE', `${path}/hook`); say(`✓ The trigger of ${id} is removed; calls to its URL fail from now on.`); return { id, hook: null } }
+    const h = await client().request('POST', `${path}/hook`)
+    if (args.json) { say(JSON.stringify(h, null, 2)); return h }
+    say(`✓ ${h.rotated ? 'New secret for' : 'Trigger for'} ${id}${h.rotated ? ' (the old one stopped working)' : ''}.\n  URL     ${h.url}\n  Secret  ${h.secret}\nStore the secret in your CI or hosting secrets now (Kaloko shows it only once), then call:\n  curl -X POST ${h.url} -H "Authorization: Bearer $KALOKO_HOOK_SECRET"`)
+    return h
+  }
+  throw new UsageError('Usage: kaloko schedule add|list|run|pause|resume|remove|hook|export github (kaloko help)')
 }

package/src/lib/legacy.mjs

@@ -0,0 +1,28 @@
+// Names from before the rename to Kaloko that still work: the qawalk command, QAWALK_* variables, qawalk.config.yml
+// and ~/.config/qawalk/.env. Each one used in a run is noted here; the CLI prints one line about them on stderr at the
+// end of the command (once per run) and kaloko doctor lists them with their new names.
+
+const seen = new Map() // old name → new name
+
+/** Notes an old name in use and the name that replaces it. */
+export function noteLegacy (old, now) { if (!seen.has(old)) seen.set(old, now) }
+
+/** [{ old, now }] noted in this run. */
+export const legacyInUse = () => [...seen].map(([old, now]) => ({ old, now }))
+
+/** Forgets what was noted (tests, and main() calls in one process). */
+export const resetLegacy = () => seen.clear()
+
+/** The one stderr line about old names, or null when none was used. */
+export function legacyHint (list = legacyInUse()) {
+  if (!list.length) return null
+  return `! Old names from before Kaloko still work, but will not forever: ${list.map((x) => `${x.old} → ${x.now}`).join(', ')}. kaloko doctor lists them.`
+}
+
+/**
+ * QAWALK_* variables someone set (in the shell or a .env file), not the copies the CLI makes of KALOKO_* ones: a
+ * QAWALK_X counts when KALOKO_X is unset or holds another value. `vars` is a snapshot taken before aliasing.
+ */
+export function legacyVariables (vars) {
+  return Object.keys(vars).filter((k) => /^QAWALK_[A-Z0-9_]+$/.test(k) && vars[k] !== vars[`KALOKO_${k.slice(7)}`]).sort()
+}

package/src/lib/login.mjs

@@ -34,7 +34,7 @@ export async function login (base, { org = null, print = false, open = true, tok
   base = base.replace(/\/$/, '')
   const post = async (path, body) => {
     let res
-    try { res = await fetchImpl(`${base}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body) }) } catch (e) { throw new UserError(`Cannot reach ${base} (${e.cause?.code || e.message}). Check your network or VPN and run kaloko login again; --url or KALOKO_URL points it to another service.`) }
+    try { res = await fetchImpl(`${base}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body) }) } catch (e) { throw new UserError(`Cannot reach ${base} (${e.cause?.code || e.message}). Check your network or VPN and run kaloko login again; --url or KALOKO_URL points it to another service.`, { code: 'unreachable', exitCode: 3 }) }
     return { status: res.status, body: await res.json().catch(() => ({})) }
   }
   const start = await post('/cli/device', { client: `kaloko${version ? ` ${version}` : ''} on ${hostname()}`.slice(0, 60) })