kaloko 0.4.8 → 0.4.10

package/src/lib/ci.mjs

@@ -0,0 +1,207 @@
+// Packaged CI (#15): `kaloko ci github|gitlab` writes a workflow into the customer's repository that walks the
+// affected scenarios on the pull request's preview deployment and comments on the PR; `kaloko ci preview-url` finds
+// that deployment at run time (Vercel, Netlify, Cloudflare Pages and anything that reports GitHub deployments).
+import { readFile, appendFile } from 'node:fs/promises'
+
+const clean = (u) => (u ? (/^https?:\/\//.test(u) ? u : `https://${u}`).replace(/\/$/, '') : null)
+
+/** Preview URL from variables CI and hosting providers set; { url, source } or null. */
+export function previewFromEnv (vars = process.env, event = null) {
+  if (vars.KALOKO_PREVIEW_URL) return { url: clean(vars.KALOKO_PREVIEW_URL), source: 'KALOKO_PREVIEW_URL' }
+  const ds = event?.deployment_status
+  if (ds && ds.state === 'success' && (ds.environment_url || ds.target_url)) return { url: clean(ds.environment_url || ds.target_url), source: `deployment_status (${ds.environment || event.deployment?.environment || 'deployment'})` }
+  for (const [name, label] of [['VERCEL_BRANCH_URL', 'Vercel'], ['VERCEL_URL', 'Vercel'], ['DEPLOY_PRIME_URL', 'Netlify'], ['DEPLOY_URL', 'Netlify'], ['CF_PAGES_URL', 'Cloudflare Pages'], ['CI_ENVIRONMENT_URL', 'GitLab environment'], ['RENDER_EXTERNAL_URL', 'Render'], ['RAILWAY_PUBLIC_DOMAIN', 'Railway']]) {
+    if (vars[name]) return { url: clean(vars[name]), source: `${name} (${label})` }
+  }
+  return null
+}
+
+async function readEvent (vars) {
+  if (!vars.GITHUB_EVENT_PATH) return null
+  try { return JSON.parse(await readFile(vars.GITHUB_EVENT_PATH, 'utf8')) } catch { return null }
+}
+
+function github (vars, fetchImpl) {
+  const api = (vars.GITHUB_API_URL || 'https://api.github.com').replace(/\/$/, '')
+  const token = vars.GITHUB_TOKEN || vars.GH_TOKEN
+  return async (path) => {
+    const res = await fetchImpl(`${api}${path}`, { headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', ...(token ? { Authorization: `Bearer ${token}` } : {}) } })
+    if (!res.ok) throw new Error(`GitHub ${path} → HTTP ${res.status}`)
+    return res.json()
+  }
+}
+
+/** The pull request a CI run belongs to: { number, base, head, sha } from the event or, for a deployment, its commit. */
+export async function pullRequestOf ({ vars = process.env, event = undefined, fetchImpl = fetch } = {}) {
+  event = event === undefined ? await readEvent(vars) : event
+  if (vars.KALOKO_PR) return { number: Number(vars.KALOKO_PR), base: vars.KALOKO_BASE?.replace(/^origin\//, '') || null, sha: vars.GITHUB_SHA || null }
+  if (event?.pull_request) return { number: event.pull_request.number, base: event.pull_request.base?.ref || null, head: event.pull_request.head?.ref || null, sha: event.pull_request.head?.sha || null }
+  if (vars.CI_MERGE_REQUEST_IID) return { number: Number(vars.CI_MERGE_REQUEST_IID), base: vars.CI_MERGE_REQUEST_TARGET_BRANCH_NAME || null, head: vars.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME || null, sha: vars.CI_COMMIT_SHA || null }
+  const sha = event?.deployment?.sha || vars.GITHUB_SHA
+  if (sha && vars.GITHUB_REPOSITORY) {
+    try {
+      const pulls = await github(vars, fetchImpl)(`/repos/${vars.GITHUB_REPOSITORY}/commits/${sha}/pulls`)
+      const pr = pulls.find((p) => p.state === 'open') || pulls[0]
+      if (pr) return { number: pr.number, base: pr.base?.ref || null, head: pr.head?.ref || null, sha }
+    } catch {}
+  }
+  return null
+}
+
+/**
+ * The preview deployment of this commit: variables first, then GitHub deployments of the commit (Vercel, Netlify and
+ * Cloudflare Pages report theirs there), polled until one succeeds or `wait` seconds pass. Production is skipped.
+ */
+export async function findPreview ({ vars = process.env, fetchImpl = fetch, wait = 0, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), say = () => {} } = {}) {
+  const event = await readEvent(vars)
+  const direct = previewFromEnv(vars, event)
+  if (direct) return direct
+  const sha = event?.pull_request?.head?.sha || event?.deployment?.sha || vars.GITHUB_SHA
+  if (!sha || !vars.GITHUB_REPOSITORY) return null
+  const gh = github(vars, fetchImpl)
+  const until = Date.now() + wait * 1000
+  for (let round = 0; ; round++) {
+    try {
+      const deployments = await gh(`/repos/${vars.GITHUB_REPOSITORY}/deployments?sha=${sha}&per_page=30`)
+      for (const d of deployments.filter((x) => !/^prod/i.test(x.environment || '') && !x.production_environment)) {
+        const statuses = await gh(`/repos/${vars.GITHUB_REPOSITORY}/deployments/${d.id}/statuses?per_page=10`)
+        const ok = statuses.find((s) => s.state === 'success' && (s.environment_url || s.target_url))
+        if (ok) return { url: clean(ok.environment_url || ok.target_url), source: `GitHub deployment ${d.environment}` }
+      }
+    } catch (e) { if (round === 0) say(`  (GitHub deployments not readable: ${e.message})`) }
+    if (Date.now() >= until) return null
+    if (round === 0) say(`Waiting up to ${wait} s for a preview deployment of ${sha.slice(0, 7)}…`)
+    await sleep(10000)
+  }
+}
+
+/** Lines for $GITHUB_ENV (or a dotenv file): the preview URL, the PR and its base for --affected and share --pr. */
+export function envLines ({ preview, pr }) {
+  return [
+    preview && `KALOKO_PREVIEW_URL=${preview.url}`,
+    pr?.number && `KALOKO_PR=${pr.number}`,
+    pr?.base && `KALOKO_BASE=origin/${pr.base}`,
+    pr?.head && `KALOKO_BRANCH=${pr.head}`
+  ].filter(Boolean)
+}
+
+export const writeEnvFile = (file, lines) => appendFile(file, lines.map((l) => l + '\n').join(''))
+
+const q = (s) => /^[A-Za-z0-9_./-]+$/.test(s) ? s : JSON.stringify(s)
+
+/** How the workflow runs kaloko: through the project's package manager when kaloko is a dependency, else npx. */
+export function runner ({ pm = 'npm', dependency = true, version = 'latest' }) {
+  if (!dependency) return { install: null, kaloko: `npx --yes kaloko@${version}` }
+  return {
+    install: { npm: 'npm ci', pnpm: 'pnpm install --frozen-lockfile', yarn: 'yarn install --frozen-lockfile', bun: 'bun install --frozen-lockfile' }[pm] || 'npm ci',
+    kaloko: { npm: 'npx kaloko', pnpm: 'pnpm exec kaloko', yarn: 'yarn kaloko', bun: 'bunx kaloko' }[pm] || 'npx kaloko'
+  }
+}
+
+/** The loop over scenarios both workflows run: walk what the change reaches, share, comment on the PR. */
+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`] : []),
+    `  ${k} start --scenario "$s" --env ${env}`,
+    `  ${k} walk --ephemeral${affected ? ' --affected' : ''} || status=1`,
+    `  ${k} share --pr || status=1`,
+    'done',
+    'exit $status'
+  ]
+}
+
+/** .github/workflows/kaloko.yml */
+export function githubWorkflow ({ scenarios, env = 'preview', trigger = 'deployment', affected = true, pm = 'npm', dependency = true, version = 'latest', node = 22 }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
+  const on = trigger === 'deployment'
+    ? '  # Vercel, Netlify and Cloudflare Pages report each preview as a GitHub deployment\n  deployment_status:\n  workflow_dispatch:'
+    : '  pull_request:\n  workflow_dispatch:'
+  const guard = trigger === 'deployment'
+    ? "    if: github.event_name != 'deployment_status' || (github.event.deployment_status.state == 'success' && !startsWith(github.event.deployment_status.environment, 'Production') && !startsWith(github.event.deployment_status.environment, 'production'))\n"
+    : ''
+  return `# Kaloko: walk the scenarios this pull request affects on its preview deployment and comment on the PR.
+# Written by kaloko ci github. Secrets: KALOKO_TOKEN (tester role, upload scope; on Enterprise a service account's);
+# TYPESAFE_API_KEY only if semantic criteria should use your own evaluator key.
+name: Kaloko
+on:
+${on}
+concurrency:
+  group: kaloko-\${{ github.event.deployment.sha || github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+  deployments: read
+  pull-requests: write
+jobs:
+  walk:
+${guard}    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
+      GH_TOKEN: \${{ github.token }}
+      KALOKO_AGENT: github-actions
+      KALOKO_BROWSER_CHANNEL: chromium
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.deployment.sha || github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 0   # walk --affected compares with the pull request's base
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${node}
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}      - run: ${k} browser install --with-deps   # the Chromium of kaloko's own Playwright
+      - name: Preview deployment
+        # the deployment's URL, the pull request and its base; waits for the preview when it is still building
+        run: ${k} ci preview-url --wait 600 --github-env
+      - name: Walk, share, comment
+        run: |
+${indent(walkScript({ scenarios, env, affected, k }), 10)}
+`
+}
+
+/** kaloko.gitlab-ci.yml, included from .gitlab-ci.yml */
+export function gitlabJob ({ scenarios, env = 'preview', affected = true, pm = 'npm', dependency = true, version = 'latest', playwright = '1.55.0' }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
+  return `# Kaloko: walk the scenarios a merge request affects on its review app and comment on the MR.
+# Written by kaloko ci gitlab. Include it from .gitlab-ci.yml:  include: { local: kaloko.gitlab-ci.yml }
+# CI/CD variables (masked): KALOKO_TOKEN (tester role, upload scope); KALOKO_GITLAB_TOKEN (project access
+# token with the api scope) for the MR comment; TYPESAFE_API_KEY optional.
+kaloko:
+  stage: test        # run it after the job that deploys the review app (needs: [deploy_review])
+  image: mcr.microsoft.com/playwright:v${playwright}-noble
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    GIT_DEPTH: "0"   # walk --affected compares with the target branch
+    KALOKO_BROWSER_CHANNEL: chromium
+    KALOKO_AGENT: gitlab-ci
+    # KALOKO_PREVIEW_URL: https://$CI_COMMIT_REF_SLUG.review.example.com   # when the review app URL is known
+  script:
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '    - corepack enable\n' : ''}    - ${install}\n` : ''}    - ${k} browser install
+    - export KALOKO_PREVIEW_URL="$(${k} ci preview-url --wait 600)"
+    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+    - |
+${indent(walkScript({ scenarios, env, affected, k }), 6)}
+`
+}
+
+/** Adds the preview environment to kaloko.config.yml text (block style); null when it cannot be placed safely. */
+export function addPreviewEnvironment (text, name = 'preview') {
+  if (new RegExp(`^  ${name}:`, 'm').test(text)) return text
+  const m = text.match(/^environments:\s*$/m)
+  if (!m) return null
+  const block = [
+    `  ${name}:                                    # pull request previews (kaloko ci): the URL comes from CI`,
+    '    base_url: ${KALOKO_PREVIEW_URL}',
+    '    # access:                                 # Vercel deployment protection: a bypass for automation',
+    '    #   headers:',
+    '    #     x-vercel-protection-bypass: { env: VERCEL_AUTOMATION_BYPASS_SECRET }'
+  ].join('\n')
+  const at = m.index + m[0].length
+  return text.slice(0, at) + '\n' + block + text.slice(at)
+}

package/src/lib/config.mjs

@@ -48,6 +48,8 @@ export async function loadConfig (start = process.cwd(), explicit) {
   config.output ||= !(await exists(join(dirname(file), 'tmp', 'kaloko'))) && (await exists(join(dirname(file), 'tmp', 'qawalk'))) ? 'tmp/qawalk' : 'tmp/kaloko'
   config.browser ||= {}
   config.browser.port ||= 9333
+  // CI runs the bundled Chromium without a separate config: KALOKO_BROWSER_CHANNEL=chromium (or chrome, msedge)
+  if (process.env.KALOKO_BROWSER_CHANNEL != null) config.browser.channel = ['', 'chromium', 'bundled'].includes(process.env.KALOKO_BROWSER_CHANNEL) ? undefined : process.env.KALOKO_BROWSER_CHANNEL
   return { config, root: dirname(file), file }
 }
 

package/src/lib/design-cli.mjs

@@ -7,6 +7,7 @@ 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 { loadTokens } from './drift.mjs'
 import { layout } from './scenario.mjs'
 import { launchEphemeral } from './browser.mjs'
 import { observeConsole } from './console.mjs'
@@ -45,6 +46,8 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
   const browser = await launchEphemeral(config)
   const paths = runPaths(run.dir)
   const mode = env.tokens_mode || ''
+  // the design folder's own set names the values in the step spec (the one its live pages reference)
+  const tokens = await loadTokens({ client: null, config, root, designDir: dir })
   let rendered = 0, reused = 0
   try {
     const page = await (await browser.newContext()).newPage()
@@ -58,7 +61,8 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
       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)) {
+        // a capture from before the step spec existed renders again, so Dev mode and `kaloko spec` have it
+        if (cached && cached.record.criteria_hash === criteriaHash(node) && cached.record.spec) {
           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)
@@ -69,7 +73,7 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
       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 })
+        const results = await captureStep({ page, node, locale: rev.locale, viewports: todo, run, maxChars: config.evaluators?.jev?.max_state_chars, since, extra: { live }, designSummary: true, tokens })
         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)'}`)
@@ -231,7 +235,7 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
           out[k] = h
         }
         const stored = await readJson(runPaths(run.dir).step(rev.node, rev.locale, vp, 'eval.json'), null)
-        out.record = slimCapture(rec)
+        out.record = { ...slimCapture(rec), ...(rec.spec ? { spec: rec.spec } : {}) }
         out.evaluation = stored?.source === evaluationSource(node, rec) ? stored : null
         out.mode = env.tokens_mode || ''
         out.renderer = RENDERER