kaloko 0.3.0

package/src/lib/design-cli.mjs

@@ -0,0 +1,440 @@
+// CLI side of Kaloko Design (#42): walking a design environment (render only what changed), syncing
+// revisions with the shared draft, publishing versions, history, references, token sets, live export.
+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 { readCaptures, addCapture, runPaths } from './run.mjs'
+import { latestCaptures, criteriaHash, evaluationSource } from './evaluate.mjs'
+import { captureStep } from './capture.mjs'
+import { layout } from './scenario.mjs'
+import { launchEphemeral } from './browser.mjs'
+import { observeConsole } from './console.mjs'
+import { slimCapture } from './manifest-core.mjs'
+import { captureKey, sha256Hex, extOf, TEXT_TYPES, RENDERER } from './design-core.mjs'
+import { designDir, revisionOf, serveDesign, copyLive, fromCache, toCache, restoreCached, readBase, writeBase, headKey, tokensRef } from './design.mjs'
+
+const enc = encodeURIComponent
+const screensOf = (scenario) => scenario.nodes.filter((n) => n.kind !== 'decision' && n.kind !== 'external')
+
+/** Local revisions of every step and locale of the scenario (fresh from the design folder). */
+export async function localRevisions ({ dir, scenario, locales, allLocales, project, pick = null }) {
+  const tokens = await tokensRef(dir, project)
+  const out = {}
+  for (const locale of locales) {
+    for (const node of screensOf(scenario)) {
+      if (pick && !pick.includes(node.id)) continue
+      const rev = await revisionOf({ dir, scenario: scenario.id, node: node.id, locale, locales: allLocales, tokens })
+      if (rev) out[headKey(node.id, locale)] = rev
+    }
+  }
+  return out
+}
+
+/**
+ * Walk of a design environment: serves the folder, renders each step and locale in every viewport, and reuses
+ * captures of revisions that were already rendered (content cache). Writes revisions.json into the run.
+ */
+export async function walkDesign ({ config, root, run, scenario, env, pick, locales, viewports, say, noCache = false }) {
+  const dir = designDir(env, root)
+  const revisions = await readJson(join(run.dir, 'revisions.json'), {})
+  const fresh = await localRevisions({ dir, scenario, locales, allLocales: run.meta.scope.locales, project: run.meta.project?.slug, pick })
+  const missing = []
+  for (const locale of locales) for (const node of screensOf(scenario)) if ((!pick || pick.includes(node.id)) && !fresh[headKey(node.id, locale)]) missing.push(`${node.id} (${locale}): add ${node.id}/index.html to ${relative(process.cwd(), dir)}/`)
+  const server = await serveDesign(dir)
+  const browser = await launchEphemeral(config)
+  const paths = runPaths(run.dir)
+  const mode = env.tokens_mode || ''
+  let rendered = 0, reused = 0
+  try {
+    const page = await (await browser.newContext()).newPage()
+    observeConsole(page)
+    for (const [key, rev] of Object.entries(fresh)) {
+      const node = scenario.nodes.find((n) => n.id === rev.node)
+      revisions[key] = rev
+      await copyLive(run.dir, dir, rev)
+      const live = { revision: rev.id, entry: rev.entry }
+      const todo = {}
+      for (const [vp, size] of Object.entries(viewports)) {
+        const ck = captureKey(rev.id, vp, mode)
+        const cached = noCache ? null : await fromCache({ root, output: config.output, key: ck })
+        if (cached && cached.record.criteria_hash === criteriaHash(node)) {
+          const record = await restoreCached({ cached, runDir: run.dir, paths, node: node.id, locale: rev.locale, viewport: vp })
+          const file = paths.step(node.id, rev.locale, vp, 'capture.json')
+          await writeJson(file, record)
+          await addCapture(run.dir, { type: 'capture', node: node.id, locale: rev.locale, viewport: vp, file: relative(run.dir, file), at: new Date().toISOString() })
+          reused++
+        } else todo[vp] = size
+      }
+      if (Object.keys(todo).length) {
+        const since = new Date().toISOString()
+        await page.goto(`${server.url}/${rev.entry}`, { waitUntil: 'load' })
+        const results = await captureStep({ page, node, locale: rev.locale, viewports: todo, run, maxChars: config.evaluators?.jev?.max_state_chars, since, extra: { live }, designSummary: true })
+        for (const r of results) { await toCache({ root, output: config.output, key: captureKey(rev.id, r.viewport, mode), runDir: run.dir, record: r }); rendered++ }
+      }
+      say(`✓ ${node.id} ${rev.locale}  revision ${rev.id.slice(0, 8)}${Object.keys(todo).length ? '' : '  (unchanged, reused)'}`)
+    }
+  } finally {
+    await browser.close()
+    await server.close()
+  }
+  await writeJson(join(run.dir, 'revisions.json'), revisions)
+  say(`\nRendered ${rendered} capture(s), reused ${reused} from unchanged revisions.`)
+  if (missing.length) { say(`\nSteps without a design yet:\n  - ${missing.join('\n  - ')}`) }
+  return { rendered, reused, revisions }
+}
+
+/** Scenario snapshot the service keeps with the draft (so it can compose versions without the CLI). */
+export function snapshotOf (scenario, run) {
+  const pos = Object.fromEntries(layout(scenario).map((p) => [p.id, { col: p.col, lane: p.lane }]))
+  return { title: scenario.title, kind: scenario.kind || 'task', source: scenario.source || null, file: run.meta.scenario_file, project: run.meta.project || null, nodes: scenario.nodes, edges: scenario.edges, lanes: scenario.lanes || [], sessions: scenario.sessions || null, layout: pos }
+}
+
+export async function uploadBlobs ({ client, org, files, say }) {
+  // files: Map hash → { abs, ext }
+  const hashes = [...files.keys()]
+  const missing = new Set()
+  for (let i = 0; i < hashes.length; i += 1000) for (const h of (await client.request('POST', `/orgs/${org}/blobs/missing`, { hashes: hashes.slice(i, i + 1000) })).missing) missing.add(h)
+  let bytes = 0
+  const queue = [...missing]
+  const worker = async () => {
+    while (queue.length) {
+      const h = queue.shift()
+      const f = files.get(h)
+      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' } : {}) })
+      bytes += body.length
+    }
+  }
+  await Promise.all(Array.from({ length: 6 }, worker))
+  say(`Uploaded ${missing.size} new file(s) (${Math.round(bytes / 1024)} kB); ${files.size - missing.size} already stored.`)
+}
+
+/**
+ * Two-way sync of the current design run with the shared draft. Steps changed locally are pushed as
+ * revisions (with captures), steps changed only in the draft are pulled into the folder, steps changed on
+ * both sides are conflicts unless --mine or --theirs names them.
+ */
+export async function syncDesign ({ config, root, run, scenario, env, client, args, say, push = true, pull = true, render }) {
+  if (env.kind !== 'design') throw new UserError(`sync works on design environments; the current run is on ${env.name}.`)
+  const dir = designDir(env, root)
+  const org = config.org
+  const branch = typeof args.branch === 'string' ? args.branch : 'main'
+  const sid = enc(scenario.id)
+  const locales = run.meta.scope.locales
+  const bases = (await readBase(dir)) || {}
+  const baseKey = `${scenario.id}@${branch}`
+  const base = bases[baseKey]?.heads || {}
+  const remote = await client.request('GET', `/orgs/${org}/scenarios/${sid}/draft?branch=${enc(branch)}`)
+  const remoteHeads = Object.fromEntries((remote.heads || []).map((h) => [headKey(h.node, h.locale, h.state), h.revision]))
+  const remoteCaps = Object.fromEntries((remote.heads || []).map((h) => [headKey(h.node, h.locale, h.state), h.captures || {}]))
+  const snapshot = snapshotOf(scenario, run)
+  const snapshotChanged = !remote.exists || remote.snapshot_hash !== await sha256Hex(JSON.stringify(snapshot))
+  let local = await localRevisions({ dir, scenario, locales, allLocales: locales, project: run.meta.project?.slug })
+  // the folder mirrors one branch at a time (like a git checkout): steps that mirror another branch are
+  // taken from this one instead of being pushed into it
+  const folderKey = bases.folder || baseKey
+  const mirror = folderKey !== baseKey ? (bases[folderKey]?.heads || {}) : null
+  if (mirror) say(`Switching the folder from ${folderKey.split('@')[1]} to ${branch}.`)
+  const mine = new Set(typeof args.mine === 'string' ? args.mine.split(',') : [])
+  const theirs = new Set(typeof args.theirs === 'string' ? args.theirs.split(',') : [])
+  const toPush = [], toPull = [], conflicts = []
+  for (const key of new Set([...Object.keys(local), ...Object.keys(remoteHeads)])) {
+    const l = local[key]?.id || null, b = base[key] || null, r = remoteHeads[key] || null
+    const node = key.split('|')[0]
+    if (l && l === r) continue
+    const switching = mirror && l && l === mirror[key] && l !== r
+    const localChanged = l && l !== b && !switching
+    const remoteChanged = (r && r !== b) || switching
+    if (localChanged && remoteChanged && !mine.has(node) && !theirs.has(node)) conflicts.push({ key, local: l, remote: r })
+    else if (localChanged && !theirs.has(node)) toPush.push(key)
+    else if (remoteChanged || theirs.has(node)) toPull.push(key)
+  }
+  if (conflicts.length) {
+    say(`Steps changed both here and in the draft (another person or agent):\n  - ${conflicts.map((c) => `${c.key.split('|').slice(0, 2).join(' ')}: yours ${c.local.slice(0, 8)}, draft ${c.remote.slice(0, 8)}`).join('\n  - ')}\nKeep yours with --mine <step,…> or take the draft with --theirs <step,…>, then sync again.`)
+    process.exitCode = 1
+    if (!push || args.strict) return { conflicts }
+  }
+  // pull first: those steps are unchanged locally
+  if (pull && toPull.length) {
+    for (const key of toPull) {
+      const rev = await client.request('GET', `/orgs/${org}/revisions/${remoteHeads[key]}`)
+      const [node, locale] = key.split('|')
+      // files of this step's own folders (never _shared/ or another locale's folder) that the pulled revision no longer has are removed
+      const own = (p) => p.startsWith(`${node}/${locale}/`) || (p.startsWith(`${node}/`) && !locales.includes(p.split('/')[1]))
+      const usedElsewhere = new Set(Object.entries(local).filter(([k]) => k !== key && k.startsWith(`${node}|`)).flatMap(([, r]) => Object.keys(r.files)))
+      for (const p of Object.keys(local[key]?.files || {})) if (own(p) && !(p in rev.files) && !usedElsewhere.has(p)) await rm(join(dir, p), { force: true })
+      for (const [p, hash] of Object.entries(rev.files)) {
+        const target = join(dir, p)
+        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)
+        await mkdir(dirname(target), { recursive: true })
+        await writeFile(target, buf)
+      }
+      say(`↓ ${node} ${locale}  took the draft's revision ${rev.id.slice(0, 8)} (by ${rev.actor}${rev.agent ? ` via ${rev.agent}` : ''})`)
+    }
+    local = await localRevisions({ dir, scenario, locales, allLocales: locales, project: run.meta.project?.slug })
+  }
+  let result = null
+  // same revision, but its draft captures were rendered by another renderer or for other criteria: send them again
+  const vpsAll = Object.keys(run.meta.scope.viewports)
+  const toRefresh = push ? Object.keys(local).filter((key) => local[key].id === remoteHeads[key] && !toPush.includes(key) && vpsAll.some((vp) => { const rc = remoteCaps[key]?.[vp]; const node = scenario.nodes.find((n) => n.id === local[key].node); return !rc || rc.renderer !== RENDERER || rc.criteria_hash !== criteriaHash(node) })) : []
+  if (push && (toPush.length || toRefresh.length || snapshotChanged)) {
+    // steps to push need captures of their current revision in every viewport of the run
+    const vps = Object.keys(run.meta.scope.viewports)
+    const capturesByKey = async () => new Map(latestCaptures(await readCaptures(run.dir)).map((c) => [`${c.node}|${c.locale}|${c.viewport}`, c]))
+    let byKey = await capturesByKey()
+    const stale = []
+    const sending = [...toPush, ...toRefresh]
+    for (const key of sending) {
+      const [node, locale] = key.split('|')
+      const want = criteriaHash(scenario.nodes.find((n) => n.id === node))
+      for (const vp of vps) {
+        const c = byKey.get(`${node}|${locale}|${vp}`)
+        const rec = c ? await readJson(join(run.dir, c.file), null) : null
+        if (!rec || rec.live?.revision !== local[key].id || rec.criteria_hash !== want || !rec.design) stale.push(node)
+      }
+    }
+    if (stale.length) { await render([...new Set(stale)]); byKey = await capturesByKey() }
+    // every pushed capture carries a valid evaluation of the scenario's criteria (deterministic checks are free)
+    let unevaluated = false
+    for (const key of sending) for (const vp of vps) {
+      const [node, locale] = key.split('|')
+      const c = byKey.get(`${node}|${locale}|${vp}`)
+      const rec = c && await readJson(join(run.dir, c.file), null)
+      const ev = await readJson(runPaths(run.dir).step(node, locale, vp, 'eval.json'), null)
+      if (rec && ev?.source !== evaluationSource(scenario.nodes.find((n) => n.id === node), rec)) unevaluated = true
+    }
+    if (unevaluated) { const { evaluateRun } = await import('./evaluate.mjs'); await evaluateRun({ run, scenario, config, root }); say('Evaluated the new captures against the scenario criteria.') }
+    const files = new Map()
+    const revisions = []
+    for (const key of sending) {
+      const rev = local[key]
+      const node = scenario.nodes.find((n) => n.id === rev.node)
+      for (const [p, h] of Object.entries(rev.files)) files.set(h, { abs: join(dir, p), ext: extOf(p) })
+      const captures = {}
+      for (const vp of vps) {
+        const c = byKey.get(`${rev.node}|${rev.locale}|${vp}`)
+        if (!c) throw new UserError(`${rev.node} ${rev.locale} ${vp}: no capture; run kaloko walk first.`)
+        const rec = await readJson(join(run.dir, c.file))
+        if (rec.live?.revision !== rev.id) throw new UserError(`${rev.node} ${rev.locale} ${vp}: capture does not match the folder; run kaloko walk again.`)
+        const out = {}
+        for (const [k, rel] of [['image', rec.files.image], ['thumb', rec.files.thumb], ['html', rec.files.html]]) {
+          if (!rel) continue
+          const abs = join(run.dir, rel)
+          const h = await sha256Hex(await readFile(abs))
+          files.set(h, { abs, ext: extOf(rel) })
+          out[k] = h
+        }
+        const stored = await readJson(runPaths(run.dir).step(rev.node, rev.locale, vp, 'eval.json'), null)
+        out.record = slimCapture(rec)
+        out.evaluation = stored?.source === evaluationSource(node, rec) ? stored : null
+        out.mode = env.tokens_mode || ''
+        out.renderer = RENDERER
+        captures[vp] = out
+      }
+      revisions.push({ id: rev.id, node: rev.node, locale: rev.locale, state: rev.state, entry: rev.entry, files: rev.files, tokens: rev.tokens, based_on: base[key] || remoteHeads[key] || null, captures })
+    }
+    await uploadBlobs({ client, org, files, say })
+    const heads = toPush.map((key) => ({ node: local[key].node, locale: local[key].locale, state: local[key].state, revision: local[key].id, base: remoteHeads[key] || null }))
+    try {
+      result = await client.request('POST', `/orgs/${org}/scenarios/${sid}/draft`, { branch, snapshot, scope: { locales, viewports: run.meta.scope.viewports }, environment: env.name, git_branch: run.meta.git?.branch || null, revisions, heads })
+    } catch (e) {
+      if (/HTTP 409/.test(e.message)) { say(`${e.message}\nSomeone changed these steps a moment ago; sync again to see them.`); process.exitCode = 1; return { conflicts: true } }
+      throw e
+    }
+    for (const m of result.moved) say(`↑ ${m.node} ${m.locale}  revision ${m.revision.slice(0, 8)} saved to the draft`)
+    if (toRefresh.length) say(`↑ captures of ${toRefresh.length} unchanged step(s) re-rendered (renderer ${RENDERER} or criteria changed)`)
+    if (snapshotChanged && remote.exists) say('↑ scenario snapshot updated (steps, criteria or layout changed)')
+  } else if (push && !toPush.length && !remote.exists) {
+    // first sync of a new draft with nothing rendered yet
+    say('Nothing to sync yet: walk the design first (kaloko walk).')
+  }
+  const after = await client.request('GET', `/orgs/${org}/scenarios/${sid}/draft?branch=${enc(branch)}`)
+  bases.folder = baseKey
+  bases[baseKey] = { seq: after.seq, synced_at: new Date().toISOString(), heads: Object.fromEntries((after.heads || []).map((h) => [headKey(h.node, h.locale, h.state), h.revision])) }
+  await writeBase(dir, bases)
+  const moved = new Set([...toPush, ...toPull])
+  const unchanged = Object.keys(local).filter((k) => !moved.has(k) && local[k].id === bases[baseKey].heads[k]).length
+  say(`Draft ${scenario.id}${branch !== 'main' ? `@${branch}` : ''} at #${after.seq}: ${toPush.length} pushed, ${toPull.length} pulled, ${unchanged} unchanged.`)
+  return { pushed: toPush.length, pulled: toPull.length, conflicts: conflicts.length ? conflicts : null, seq: after.seq }
+}
+
+/** Publishes the draft head as a version (a run of the design environment). */
+export async function publishVersion ({ config, scenario, client, args, say }) {
+  const branch = typeof args.branch === 'string' ? args.branch : 'main'
+  const r = await client.request('POST', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions`, { branch, ...(typeof args.name === 'string' ? { name: args.name } : {}) })
+  say(`Version v${r.version}${r.name ? ` "${r.name}"` : ''} · ${r.changed} changed, ${r.unchanged} unchanged${r.changed_steps.length ? ` (${r.changed_steps.join(', ')})` : ''}\n${r.url}`)
+  return r
+}
+
+export async function historyCmd ({ config, scenarioId, client, args, say }) {
+  const q = new URLSearchParams({ ...(typeof args.step === 'string' ? { step: args.step } : {}), ...(typeof args.locale === 'string' ? { locale: args.locale } : {}) })
+  const h = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/history?${q}`)
+  if (args.json) { say(JSON.stringify(h, null, 2)); return }
+  say(`Versions of ${scenarioId}:`)
+  for (const v of h.versions) say(`  v${String(v.version).padEnd(4)} ${v.at.slice(0, 16).replace('T', ' ')}  ${v.verdict.padEnd(9)} ${v.by}${v.name ? `  "${v.name}"` : ''}${v.branch && v.branch !== 'main' ? `  @${v.branch}` : ''}  ${v.id}`)
+  if (!h.versions.length) say('  none yet (kaloko share on the design environment publishes one)')
+  if (h.revisions) {
+    say(`\nRevisions of step ${args.step}:`)
+    for (const r of h.revisions) say(`  ${r.id.slice(0, 8)} ${r.locale.padEnd(6)} ${r.at.slice(0, 16).replace('T', ' ')}  ${r.by}${r.agent ? ` via ${r.agent}` : ''}${r.versions.length ? `  in v${r.versions.join(', v')}` : ''}`)
+  }
+}
+
+export async function referenceCmd ({ config, scenarioId, client, args, say }) {
+  const path = `/orgs/${config.org}/scenarios/${enc(scenarioId)}/references`
+  const kind = args.design ? 'design' : args.baseline ? 'baseline' : null
+  let refs
+  if (kind) {
+    let runId = typeof args.run === 'string' ? args.run : null
+    if (!runId && typeof args.version === 'string') runId = (await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/versions`)).find((v) => String(v.version) === String(args.version).replace(/^v/, ''))?.id
+    if (!runId && !args.off) throw new UserError('Name the run with --run <id> or the version with --version <n> (or pass --off).')
+    refs = await client.request('PUT', path, { kind, run_id: args.off ? null : runId, ...(typeof args.branch === 'string' ? { branch: args.branch } : {}) })
+  } else refs = await client.request('GET', path)
+  if (args.json) { say(JSON.stringify(refs, null, 2)); return }
+  say(`References of ${scenarioId}:\n  baseline  ${refs.baseline || '—'}\n  design    ${refs.design || '—'}${Object.keys(refs.design_by_branch || {}).filter((b) => b !== 'main').map((b) => `\n  design@${b}  ${refs.design_by_branch[b]}`).join('')}`)
+}
+
+export async function tokensCmd ({ config, root, env, client, args, say, project }) {
+  const action = args._[0]
+  const tk = await import('./tokens.mjs')
+  // tokens.json, or a DTCG resolver (tokens.resolver.json with sets and a theme modifier) next to it
+  const folder = env?.kind === 'design' ? designDir(env, root) : root
+  let file = typeof args.file === 'string' ? args.file : join(folder, 'tokens.json')
+  if (typeof args.file !== 'string') { try { await readFile(join(folder, 'tokens.resolver.json')); file = join(folder, 'tokens.resolver.json') } catch {} }
+  /** The set as stored: a resolver gets its file sources inlined so the service holds one document. */
+  const readSet = async () => {
+    const doc = JSON.parse(await readFile(file, 'utf8'))
+    return tk.isResolver(doc) ? tk.inlineResolver(doc, (ref) => readFile(join(dirname(file), ref), 'utf8')) : doc
+  }
+  const listProblems = (problems) => { if (problems.length) say(`${problems.length} problem(s) in ${relative(process.cwd(), file)}:\n  - ${problems.slice(0, 40).join('\n  - ')}`) }
+  if (action === 'validate') {
+    const set = await readSet()
+    const problems = tk.validateTokens(set)
+    if (args.json) { say(JSON.stringify({ file, problems, modes: tk.modesOf(set), tokens: tk.flattenTokens(set).length }, null, 2)); if (problems.length) process.exitCode = 1; return }
+    if (!problems.length) say(`✓ ${relative(process.cwd(), file)}: ${tk.flattenTokens(set).length} tokens${tk.modesOf(set).length ? `, modes ${tk.modesOf(set).join(', ')}` : ''}; names, references and values are fine.`)
+    else { listProblems(problems); process.exitCode = 1 }
+    return
+  }
+  if (!project) throw new UserError('Token sets belong to a project: set project: in kaloko.config.yml or pass --project <slug>.')
+  const path = `/orgs/${config.org}/projects/${enc(project)}/tokens`
+  if (action === 'pull') {
+    const t = await client.request('GET', path + (typeof args.version === 'string' ? `?version=${enc(args.version)}` : ''))
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, JSON.stringify(t.tokens, null, 2) + '\n')
+    say(`Token set ${project} v${t.version} → ${relative(process.cwd(), file)}`)
+  } else if (action === 'push') {
+    const tokens = await readSet()
+    const problems = tk.validateTokens(tokens)
+    if (problems.length) { listProblems(problems); throw new UserError('Fix the token set first (kaloko tokens validate).') }
+    const r = await client.request('PUT', path, { tokens })
+    say(r.unchanged ? `Token set ${project} is unchanged (v${r.version}).` : `Token set ${project} v${r.version} saved.`)
+  } else if (action === 'check') {
+    const { checkTokens } = tk
+    const tokens = await readSet()
+    listProblems(tk.validateTokens(tokens))
+    const dir = env?.kind === 'design' ? designDir(env, root) : null
+    if (!dir) throw new UserError('tokens check reads the live folder of a design environment: pass --env <design env>.')
+    const report = await checkTokens({ dir, tokens, mode: typeof args.mode === 'string' ? args.mode : env.tokens_mode })
+    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]')
+}
+
+/** Writes the live files of a version (or the draft) into a folder: the handoff, or taking back canvas edits. */
+export async function exportLive ({ config, scenarioId, client, args, say, out }) {
+  const ref = args.draft ? 'draft' : typeof args.version === 'string' ? `v${String(args.version).replace(/^v/, '')}` : typeof args.run === 'string' ? args.run : 'design'
+  const data = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/revisions?ref=${enc(ref)}`)
+  if (args.views) return forkViews({ config, scenarioId, client, args, say, out, data })
+  let written = 0
+  const seen = new Set()
+  for (const s of data.steps) {
+    for (const [p, hash] of Object.entries(s.files)) {
+      if (seen.has(p)) continue
+      seen.add(p)
+      const target = join(out, p)
+      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)
+      await mkdir(dirname(target), { recursive: true })
+      await writeFile(target, buf)
+      written++
+    }
+  }
+  say(`Live files of ${scenarioId} at ${ref} → ${relative(process.cwd(), out) || '.'} (${written} written, ${seen.size - written} already up to date, ${data.steps.length} step×locale)`)
+}
+
+export async function listDesignFolder (dir) { try { return (await readdir(dir)).filter((n) => !n.startsWith('.')) } catch { return [] } }
+
+/** Branches of a design draft: list, create from a version or the draft (optionally linked to a git branch), merge per step. */
+export async function branchCmd ({ config, scenarioId, client, args, say }) {
+  const [action, name] = args._
+  const base = `/orgs/${config.org}/scenarios/${enc(scenarioId)}/branches`
+  if (!action || action === 'list') {
+    const list = await client.request('GET', base)
+    if (args.json) { say(JSON.stringify(list, null, 2)); return }
+    for (const b of list) say(`${b.branch.padEnd(24)} #${String(b.seq).padEnd(4)} ${b.based_on_version ? `from ${b.based_on_version}` : ''}${b.git_branch ? `  git:${b.git_branch}` : ''}${b.merged_at ? `  merged ${b.merged_at.slice(0, 10)}` : ''}`)
+    return
+  }
+  if (action === 'create') {
+    if (!name) throw new UserError('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]')
+    const choices = {}
+    try {
+      const r = await client.request('POST', `${base}/${enc(name)}/merge`, { choices: await choicesFrom(args, client, config, scenarioId, name) })
+      say(`Merged ${r.merged} into main: ${r.moved.length} step×locale moved.`)
+    } catch (e) {
+      if (!/HTTP 409/.test(e.message)) throw e
+      say(`${e.message}\nDecide per step: --take-branch <step,…> (the branch wins) or --keep-main <step,…>.`)
+      process.exitCode = 1
+    }
+    return choices
+  }
+  throw new UserError('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) {
+  const take = new Set(typeof args['take-branch'] === 'string' ? args['take-branch'].split(',') : [])
+  const keep = new Set(typeof args['keep-main'] === 'string' ? args['keep-main'].split(',') : [])
+  if (!take.size && !keep.size) return {}
+  const heads = (await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/draft?branch=${enc(name)}`)).heads || []
+  const out = {}
+  for (const h of heads) { const k = `${h.node}|${h.locale}|${h.state}`; if (take.has(h.node)) out[k] = 'branch'; else if (keep.has(h.node)) out[k] = 'main' }
+  return out
+}
+
+/**
+ * Fork into a draft (#42): the HTML views of an app run become design steps in a folder, so a redesign starts
+ * from the product as it is. One viewport per step (desktop by default); the first locale is the default page.
+ */
+async function forkViews ({ config, client, args, say, out, data }) {
+  const vp = typeof args.viewport === 'string' ? args.viewport : 'desktop'
+  const views = data.steps.filter((s) => s.state === `view:${vp}`)
+  if (!views.length) throw new UserError(`Run ${data.ref} has no ${vp} HTML views (html_view: true on the environment captures them).`)
+  const locales = [...new Set(views.map((v) => v.locale))]
+  let written = 0
+  for (const v of views) {
+    const prefix = v.locale === locales[0] ? `${v.node}/` : `${v.node}/${v.locale}/`
+    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)
+      const target = join(out, prefix, p)
+      await mkdir(dirname(target), { recursive: true })
+      await writeFile(target, buf)
+      written++
+    }
+  }
+  say(`Forked ${views.length} HTML view(s) of ${data.ref} into ${relative(process.cwd(), out) || '.'} as design steps (${written} files). Walk and sync the design environment to start the draft.`)
+}

package/src/lib/design-core.mjs

@@ -0,0 +1,163 @@
+// Kaloko Design core (#42): the bundle contract (qawalk.bundle.v1), revision identity and the
+// reference scanner. Pure and dependency-free (WebCrypto only) so the CLI and the Worker share it.
+
+export const BUNDLE_SCHEMA = 'qawalk.bundle.v1'
+export const REVISION_SCHEMA = 'qawalk.revision.v1'
+/** Bumped when captures of the same revision would render differently (probe, encoder, settle). */
+export const RENDERER = 'r3'
+
+/** Allowed live file types: extension → content type. Anything else is refused on both sides. */
+export const LIVE_TYPES = {
+  html: 'text/html; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  js: 'text/javascript; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  svg: 'image/svg+xml',
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  gif: 'image/gif',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  txt: 'text/plain; charset=utf-8'
+}
+export const TEXT_TYPES = new Set(['html', 'css', 'js', 'mjs', 'json', 'svg', 'txt'])
+
+/** Limits of one revision; plans may lower the per-file size, never raise these. */
+export const BUNDLE_LIMITS = { max_files: 400, max_file_bytes: 10 * 1024 * 1024, max_revision_bytes: 40 * 1024 * 1024, max_path: 240, max_depth: 8 }
+
+// bundle-relative paths: no leading slash, no dot segments, no hidden files, conservative characters
+const PATH = /^(?!\/)(?!.*(?:^|\/)\.)[A-Za-z0-9_][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_][A-Za-z0-9._-]*)*$/
+export const SHARED_DIR = '_shared'
+export const TOKENS_FILE = 'tokens.json'
+
+export const extOf = (path) => (path.match(/\.([a-z0-9]+)$/i)?.[1] || '').toLowerCase()
+export const contentTypeOf = (path) => LIVE_TYPES[extOf(path)] || null
+
+/** Problems with one bundle path (empty when valid). */
+export function pathProblem (path) {
+  if (typeof path !== 'string' || !path) return 'empty path'
+  if (path.length > BUNDLE_LIMITS.max_path) return `path longer than ${BUNDLE_LIMITS.max_path} characters`
+  if (!PATH.test(path) || path.includes('..')) return 'path must be relative, without dot segments, hidden files or unusual characters'
+  if (path.split('/').length > BUNDLE_LIMITS.max_depth) return `path deeper than ${BUNDLE_LIMITS.max_depth} folders`
+  if (!contentTypeOf(path)) return `file type .${extOf(path) || '?'} is not allowed (allowed: ${Object.keys(LIVE_TYPES).join(', ')})`
+  return null
+}
+
+/**
+ * Validates the file list of one revision: [{ path, bytes }]. Returns a list of problems.
+ * The entry must be an HTML file in the list.
+ */
+export function bundleProblems (files, entry, limits = BUNDLE_LIMITS) {
+  const problems = []
+  if (!Array.isArray(files) || !files.length) return ['a revision needs at least its entry file']
+  if (files.length > limits.max_files) problems.push(`more than ${limits.max_files} files`)
+  let total = 0
+  const seen = new Set()
+  for (const f of files) {
+    const p = pathProblem(f.path)
+    if (p) problems.push(`${f.path}: ${p}`)
+    if (seen.has(f.path)) problems.push(`${f.path}: listed twice`)
+    seen.add(f.path)
+    if (!(Number.isInteger(f.bytes) && f.bytes >= 0)) problems.push(`${f.path}: size missing`)
+    else if (f.bytes > limits.max_file_bytes) problems.push(`${f.path}: larger than ${Math.round(limits.max_file_bytes / 1048576)} MB`)
+    total += f.bytes || 0
+  }
+  if (total > limits.max_revision_bytes) problems.push(`revision larger than ${Math.round(limits.max_revision_bytes / 1048576)} MB`)
+  if (!entry || extOf(entry) !== 'html') problems.push('entry must be an .html file')
+  else if (!seen.has(entry)) problems.push(`entry ${entry} is not among the files`)
+  return problems
+}
+
+/** sha256 hex of bytes (Uint8Array | ArrayBuffer | string). */
+export async function sha256Hex (data) {
+  const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data instanceof Uint8Array ? data : new Uint8Array(data)
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+export const HASH = /^[0-9a-f]{64}$/
+export const REVISION_ID = /^[0-9a-f]{32}$/
+
+/**
+ * Identity of a revision: same content, same id, on every machine. `files` maps bundle paths to
+ * blob hashes; `tokens` is the token set reference ({ project, version, hash }) or null.
+ */
+export async function revisionId ({ scenario, node, locale, state = 'default', kind = 'design', entry, files, tokens = null }) {
+  const canonical = JSON.stringify({ v: 1, scenario, node, locale, state, kind, entry, files: Object.keys(files).sort().map((k) => [k, files[k]]), tokens: tokens ? tokens.hash || null : null })
+  return (await sha256Hex(canonical)).slice(0, 32)
+}
+
+/** Key of a rendered capture: a revision rendered in one viewport and token mode by one renderer. */
+export const captureKey = (revision, viewport, mode = '') => `${revision}|${viewport}|${mode}|${RENDERER}`
+
+// ---- reference scanner: which bundle files an entry needs ----
+
+const STRIP_QUERY = (u) => u.split('#')[0].split('?')[0]
+const isExternal = (u) => /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(u) // http:, data:, mailto:, protocol-relative
+
+/** Relative references found in one text file (unresolved). */
+export function referencesIn (path, text) {
+  const ext = extOf(path)
+  const out = new Set()
+  const add = (u) => { if (u && !isExternal(u.trim()) && !u.trim().startsWith('#')) out.add(STRIP_QUERY(u.trim())) }
+  const cssUrls = (t) => {
+    for (const m of t.matchAll(/url\(\s*(['"]?)([^'")]+)\1\s*\)/gi)) add(m[2])
+    for (const m of t.matchAll(/@import\s+(['"])([^'"]+)\1/gi)) add(m[2])
+  }
+  if (ext === 'html' || ext === 'svg') {
+    // resources only: navigation links (<a href>, <area href>, <form action>) point at other steps, not files this step needs
+    for (const m of text.matchAll(/\s(?:src|poster|data-src)\s*=\s*(['"])([^'"]*)\1/gi)) add(m[2])
+    for (const m of text.matchAll(/<link\b[^>]*\shref\s*=\s*(['"])([^'"]*)\1/gi)) add(m[2])
+    for (const m of text.matchAll(/<(?:use|image|feImage)\b[^>]*\s(?:xlink:)?href\s*=\s*(['"])([^'"]*)\1/gi)) add(m[2])
+    for (const m of text.matchAll(/\ssrcset\s*=\s*(['"])([^'"]*)\1/gi)) for (const part of m[2].split(',')) add(part.trim().split(/\s+/)[0])
+    for (const m of text.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) cssUrls(m[1])
+    for (const m of text.matchAll(/\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) cssUrls(m[1] ?? m[2])
+    for (const m of text.matchAll(/<script[^>]*type=["']module["'][^>]*>([\s\S]*?)<\/script>/gi)) for (const r of jsImports(m[1])) add(r)
+  } else if (ext === 'css') cssUrls(text)
+  else if (ext === 'js' || ext === 'mjs') for (const r of jsImports(text)) add(r)
+  return [...out]
+}
+function jsImports (t) {
+  const out = []
+  for (const m of t.matchAll(/(?:import|export)\s[^'"]*?from\s*(['"])([^'"]+)\1/g)) out.push(m[2])
+  for (const m of t.matchAll(/import\s*\(\s*(['"])([^'"]+)\1\s*\)/g)) out.push(m[2])
+  for (const m of t.matchAll(/fetch\(\s*(['"])([^'"]+)\1/g)) out.push(m[2])
+  return out.filter((u) => u.startsWith('.') || u.startsWith('/'))
+}
+
+/** Resolves a reference against the file that contains it; returns a bundle path or null. */
+export function resolveRef (from, ref) {
+  const parts = ref.startsWith('/') ? [] : from.split('/').slice(0, -1)
+  for (const seg of ref.replace(/^\/+/, '').split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') { if (!parts.length) return null; parts.pop() } else parts.push(seg)
+  }
+  let path
+  try { path = decodeURIComponent(parts.join('/')) } catch { return null }
+  return path || null
+}
+
+/**
+ * Files one step needs: everything in its own folders plus every bundle file reachable by references
+ * from them (typically _shared/…). `read(path)` returns text for text files; `exists(path)` checks.
+ */
+export async function closure ({ roots, read, exists }) {
+  const need = new Set()
+  const queue = [...roots]
+  while (queue.length) {
+    const p = queue.shift()
+    if (need.has(p) || !(await exists(p))) continue
+    need.add(p)
+    if (!TEXT_TYPES.has(extOf(p))) continue
+    for (const ref of referencesIn(p, await read(p))) {
+      const r = resolveRef(p, ref)
+      if (r && !need.has(r)) queue.push(r)
+    }
+  }
+  return [...need].sort()
+}