kaloko 0.3.0

package/src/lib/util.mjs

@@ -0,0 +1,97 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { mkdir, readFile, writeFile, appendFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export const sha256 = (value) => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex')
+export const shortId = () => randomBytes(3).toString('hex')
+
+export function slugify (value) {
+  return String(value)
+    .normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+}
+
+export function today (date = new Date()) {
+  return date.toISOString().slice(0, 10)
+}
+
+/** Pick a localized value: string, or object keyed by locale with optional `default`. */
+export function localized (value, locale) {
+  if (value == null) return ''
+  if (typeof value === 'string') return value
+  return value[locale] ?? value.default ?? Object.values(value)[0] ?? ''
+}
+
+export async function readJson (file, fallback) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'))
+  } catch (error) {
+    if (fallback !== undefined && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return fallback
+    throw error
+  }
+}
+
+export async function writeJson (file, data) {
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, JSON.stringify(data, null, 2) + '\n')
+}
+
+export async function appendJsonl (file, data) {
+  await mkdir(dirname(file), { recursive: true })
+  await appendFile(file, JSON.stringify(data) + '\n')
+}
+
+export async function readJsonl (file) {
+  try {
+    const text = await readFile(file, 'utf8')
+    return text.split('\n').filter(Boolean).map((line) => JSON.parse(line))
+  } catch (error) {
+    if (error.code === 'ENOENT') return []
+    throw error
+  }
+}
+
+/** Minimal glob → RegExp for path patterns: `*` within a segment, `**` across segments. */
+export function globToRegExp (glob) {
+  let out = ''
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === '*' && glob[i + 1] === '*') { out += '.*'; i++; if (glob[i + 1] === '/') i++ }
+    else if (c === '*') out += '[^/]*'
+    else if (c === '?') out += '[^/]'
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp('^' + out + '$')
+}
+
+export class UserError extends Error {}
+
+/**
+ * Tracks consecutive step failures per session. When `limit` steps in a row fail with the same first
+ * error line, the remaining steps of that session are almost certainly failing on a shared
+ * precondition (sign-in, gate, environment down); walking them only repeats it, and repeated
+ * sign-in attempts can lock an account. `record` returns true once the streak reaches the limit.
+ */
+export function failureStreak (limit = 3) {
+  const streaks = new Map()
+  return {
+    record (key, message) {
+      const line = String(message || '').split('\n')[0]
+      const s = streaks.get(key)
+      const next = s && s.line === line ? { line, n: s.n + 1 } : { line, n: 1 }
+      streaks.set(key, next)
+      return limit > 0 && next.n >= limit
+    },
+    ok (key) { streaks.delete(key) },
+    stopped (key) { const s = streaks.get(key); return !!(s && limit > 0 && s.n >= limit) },
+    line (key) { return streaks.get(key)?.line }
+  }
+}
+
+/** Message when the service granted a shorter share lifetime than requested (plan retention cap), else null. */
+export function expiryNote (requested, granted) {
+  if (!Number.isFinite(requested) || !Number.isFinite(granted) || granted >= requested) return null
+  return `Requested ${requested} days, but the organization's plan keeps shared runs for at most ${granted} days. ` +
+    `The run expires in ${granted} days; use \`kaloko export\` before then to keep a copy.`
+}

package/templates/ACCEPTANCE.md

@@ -0,0 +1,55 @@
+# Acceptance plan TASK-<id>
+
+Source of truth for intent. Machine scenario: `qa/scenario.yml`.
+
+## Goal and scope
+
+What this plan verifies and what it does not.
+
+## Flow
+
+```mermaid
+flowchart LR
+  A[Step] --> D{Decision}
+  D -->|yes| B[Step]
+  D -->|no| C[Step]
+```
+
+## Steps and criteria
+
+Session: the first screen is captured as a new visitor with the consent
+dialog not yet accepted (when the site has one); the next step accepts it and
+later screens run without it. Change this here when the plan tests consent
+itself or needs another session state.
+
+### <step-id> — <title> (`screen` | `email` | `external`)
+
+- Path: `/...` (per locale)
+- Purpose: what the screen must achieve for the user.
+- AC1: measurable criterion.
+- AC2: measurable criterion.
+
+## Variants
+
+Branches of the flow and the data that triggers them.
+
+## Locales and viewports
+
+Locales; desktop 1280 × 800, mobile 390 × 844.
+
+## Environments and limits
+
+Where the plan may run, whether it is `readonly`, which data it needs.
+Production: `readonly` only, as an ordinary user.
+
+## Execution
+
+| Step | Strategy | Why |
+|---|---|---|
+| <step-id> | playwright / agent / manual | reason |
+
+## Change log
+
+| Date | Commit | Change |
+|---|---|---|
+| YYYY-MM-DD | — | First version |

package/templates/cs/ACCEPTANCE.md

@@ -0,0 +1,55 @@
+# Akceptační plán TASK-<id>
+
+Zdroj pravdy pro záměr. Strojový scénář: `qa/scenario.yml`.
+
+## Cíl a rozsah běhu
+
+Co tento plán ověřuje a co ne.
+
+## Flow
+
+```mermaid
+flowchart LR
+  A[Krok] --> D{Rozhodnutí}
+  D -->|ano| B[Krok]
+  D -->|ne| C[Krok]
+```
+
+## Kroky a kritéria
+
+Session: první obrazovku snímáme jako nový návštěvník s dosud nepřijatým
+consent dialogem (pokud ho web má); další krok ho přijme a další obrazovky
+běží bez něj. Pokud plán testuje consent samotný nebo potřebuje jiný stav
+session, změňte to zde.
+
+### <id-kroku> — <název> (`screen` | `email` | `external`)
+
+- Cesta: `/cs/...` (pro každý jazyk)
+- Účel: co musí obrazovka splnit pro uživatele.
+- AC1: měřitelné kritérium.
+- AC2: měřitelné kritérium.
+
+## Varianty
+
+Větve flow a data, která je vyvolají.
+
+## Jazyky a viewporty
+
+Seznam jazyků; desktop 1280 × 800, mobil 390 × 844.
+
+## Prostředí a omezení
+
+Kde plán smí běžet, zda je `readonly`, jaká data potřebuje.
+Na produkci jen `readonly` jako běžný uživatel.
+
+## Způsob provedení
+
+| Krok | Způsob | Důvod |
+|---|---|---|
+| <id-kroku> | playwright / agent / manual | proč |
+
+## Historie změn
+
+| Datum | Commit | Změna |
+|---|---|---|
+| RRRR-MM-DD | — | První verze |

package/templates/kaloko.config.yml

@@ -0,0 +1,76 @@
+schema: qawalk.config.v1
+# Organization slug on kaloko.app
+org: my-org
+project: my-project
+
+# Where scenarios live: next to tasks and as long-lived flows
+scenarios:
+  - docs/tasks/*/qa/scenario.yml
+  - qa/flows/*.yml
+
+output: tmp/kaloko
+
+browser:
+  # Use an installed Chrome instead of downloading Playwright's Chromium
+  channel: chrome
+  port: 9333
+
+environments:
+  local:
+    base_url:
+      default: http://localhost:3000
+    mail:
+      provider: mailpit
+      url: http://localhost:8025
+      address: qa+{run}@example.test
+  # An app instead of (or next to) a web base URL, for scenarios with platform: android | ios | electron | desktop
+  # emulator:
+  #   app:
+  #     android: { package: com.example.app.debug, apk: app/build/outputs/apk/debug/app-debug.apk, reset: true }
+  #     ios: { bundle: com.example.app, app: build/Example.app, device: iPhone 17 }
+  #     electron: { main: dist/main.js }
+  #     desktop: { name: Example }            # a macOS app by its window owner name
+  staging:
+    base_url: https://staging.example.com
+    # Secrets are never written here: every *_env and { env: NAME } names a variable you choose,
+    # read from the environment, the project .env or ~/.config/kaloko/.env.
+    # Protection in front of the whole environment, sent to these origins only:
+    # access:
+    #   origins: [https://staging.example.com, https://api.staging.example.com]
+    #   basic: { user_env: STAGING_USER, password_env: STAGING_PASSWORD }
+    #   headers:                                  # service tokens, e.g. Cloudflare Access, Vercel
+    #     CF-Access-Client-Id: { env: CF_ACCESS_CLIENT_ID }
+    #     CF-Access-Client-Secret: { env: CF_ACCESS_CLIENT_SECRET }
+    #   client_certificate: { cert_file: certs/qa.pem, key_env: QA_CLIENT_KEY }   # mutual TLS
+    # People who sign in, keyed like `account` of the scenario sessions:
+    # accounts:
+    #   member: { user: member@example.test, password_env: STAGING_MEMBER_PASSWORD }
+    #   admin:  { user_env: STAGING_ADMIN_USER, password_env: STAGING_ADMIN_PASSWORD, totp_env: STAGING_ADMIN_TOTP }
+    #   sso:    {}                                # SSO/MFA: a person runs kaloko auth save --env staging --account sso
+    mail:
+      provider: mailpit
+      url: https://mailpit.example.com
+      auth: { basic: { user_env: MAILPIT_USER, password_env: MAILPIT_PASSWORD } }
+      address: qa+{run}@example.test
+      # Any other mailbox: a project adapter (letter_opener, Mailosaur, IMAP, the app's own API):
+      # provider: script
+      # script: qa/mail/inbox.mjs                 # see templates/mail/letter-opener.mjs in the package
+  # review:                                    # review apps: the URL comes from CI
+  #   base_url: https://${REVIEW_HOST}
+  production:
+    # production is always readonly: no data creation, no admin, no writes
+    base_url: https://www.example.com
+    readonly: true
+    blocked_paths: ["/admin/**", "/console/**", "/users/sign_in"]
+    allowed_post_paths: ["/cart/**"]
+
+evaluators:
+  jev:
+    model: jev-1.13.0
+    api_key_env: TYPESAFE_API_KEY
+    thresholds: { pass: 0.85, fail: 0.15 }
+
+share:
+  url: https://kaloko.app
+  token_env: KALOKO_TOKEN
+  expires_days: 30

package/templates/mail/letter-opener.mjs

@@ -0,0 +1,47 @@
+// Mail adapter for Rails letter_opener (and letter_opener_web): one directory per message under
+// options.path (default tmp/letter_opener) with rich.html and/or plain.html.
+// Copy it into the project and point the environment at it:
+//
+//   mail:
+//     provider: script
+//     script: qa/mail/letter-opener.mjs
+//     options: { path: tmp/letter_opener }
+//     address: qa+{run}@example.test
+//
+// The contract for any adapter: default export async ({ to, subject, since, options, root, env })
+// returning the newest matching message { id, subject, from, to: [address], date, html, text } or null.
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+const decode = (text) => text.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&')
+// the header block of the template: <dt>Subject:</dt> <dd>…</dd>
+const header = (html, name) => {
+  const m = html.match(new RegExp(`<dt>${name}:</dt>\\s*<dd>([\\s\\S]*?)</dd>`))
+  return m ? decode(m[1].replace(/<[^>]+>/g, '')).trim() : ''
+}
+const addresses = (value) => value.split(',').map((v) => v.trim()).filter(Boolean).map((v) => v.replace(/^.*<([^>]+)>.*$/, '$1'))
+
+async function parse (dir, name) {
+  const folder = join(dir, name)
+  const html = await readFile(join(folder, 'rich.html'), 'utf8').catch(() => null)
+  const plain = await readFile(join(folder, 'plain.html'), 'utf8').catch(() => null)
+  const source = html || plain
+  if (!source) return null
+  const body = html
+    ? decode((html.match(/srcdoc="<base target='_top'>([\s\S]*?)"><\/iframe>/) || [])[1] || '')
+    : decode((plain.match(/<pre id="message_body">([\s\S]*?)<\/pre>/) || [])[1] || '').replace(/<[^>]+>/g, '')
+  const date = (await stat(folder)).mtime
+  return { id: name, subject: header(source, 'Subject'), from: header(source, 'From'), to: addresses(header(source, 'To')), date: date.toISOString(), html: html ? body : null, text: html ? null : body }
+}
+
+export default async function find ({ to, subject, since, options = {}, root }) {
+  const dir = resolve(root, options.path || 'tmp/letter_opener')
+  const names = await readdir(dir).catch(() => [])
+  const messages = (await Promise.all(names.map((n) => parse(dir, n)))).filter(Boolean)
+  const wantTo = (to || '').toLowerCase()
+  const wantSubject = (subject || '').toLowerCase()
+  return messages
+    .filter((m) => !since || m.date >= since)
+    .filter((m) => (!wantTo || m.to.some((t) => t.toLowerCase() === wantTo)) && (!wantSubject || m.subject.toLowerCase().includes(wantSubject)))
+    .sort((a, b) => (a.date < b.date ? 1 : -1))[0] || null
+}

package/templates/scenario.yml

@@ -0,0 +1,119 @@
+schema: qawalk.scenario.v1
+id: TASK-123-example-flow
+title: Example flow
+kind: task                 # task | flow
+source: docs/tasks/TASK-123-example/ACCEPTANCE.md
+# project: shop           # optional: sort this flow into a project other than the config's / repository's
+version: 1
+locales: [en]
+viewports:
+  desktop: [1280, 800]
+  mobile: [390, 844]
+environments: [local, staging]
+# platform: android          # web (default) | android | ios | electron | desktop — an app instead of pages:
+#                            # the environment's app block in kaloko.config.yml names it, paths are deep links
+#                            # (shop://product/42), step scripts get `app` (tap, type, wait, link); see the skill's apps reference
+# capture: { format: png, scale: 2, mask: ["[data-qa=email]"], annotate: true }   # print quality for documentation runs
+readonly: false
+lanes: [Main path, Alternative]
+# People in the flow (optional). With `sessions`, every non-decision node names one;
+# `kaloko walk` keeps a separate browser context (cookies, sign-in) per session and locale,
+# e-mail nodes default to the session's mailbox, and the canvas groups steps by person.
+# sessions:
+#   visitor: { title: New visitor, mailbox: "qa+{run}-visitor@example.com" }
+#   member:  { title: Signed-in member, account: member }      # `account` is a project key for step scripts
+# nodes then carry `session: visitor` / `session: member`; an edge between sessions is a hand-off.
+
+nodes:
+  - id: landing
+    kind: screen
+    title: Landing page
+    path: /
+    purpose: A visitor understands the offer and can start the flow.
+    # packs: [seo, usability]   # adds the SEO basics (AC101…) and usability questions (AC201…) to this step
+    execution:
+      strategy: playwright   # playwright | agent | manual
+      script: steps/landing.mjs
+      instructions: Open the landing page as an anonymous visitor.
+    criteria:
+      - id: AC1
+        text: The page has exactly one main heading.
+        check: { type: deterministic, assert: count, selector: h1, min: 1, max: 1 }
+      - id: AC2
+        text: The primary call to action is clear.
+        check:
+          type: semantic
+          question: Does the page show one clear primary call to action that starts the flow?
+          scope: main
+      - id: AC3
+        text: No horizontal overflow on mobile.
+        check: { type: deterministic, assert: no_overflow }
+      - id: AC4
+        text: The consent dialog is shown to a new visitor.   # drop AC4 and the consent step when the site has no consent dialog
+        check: { type: deterministic, assert: exists, selector: "#cm, #CybotCookiebotDialog, #onetrust-banner-sdk" }
+
+  - id: consent
+    kind: screen
+    title: Consent accepted
+    path: /
+    purpose: The visitor accepts cookies once; the dialog does not return on later screens.
+    execution:
+      strategy: playwright
+      script: steps/consent.mjs
+      instructions: Accept the consent dialog and stay on the page.
+    criteria:
+      - id: AC1
+        text: The consent dialog is gone after accepting.
+        check: { type: deterministic, assert: absent, selector: "#cm, #CybotCookiebotDialog, #onetrust-banner-sdk" }
+
+  - id: choice
+    kind: decision
+    title: Is the visitor signed in?
+
+  - id: signup
+    kind: screen
+    title: Sign-up
+    path: /signup
+    purpose: A new visitor can create an account.
+    execution:
+      strategy: agent
+      instructions: Click the primary call to action as a new visitor and stop on the sign-up form.
+    criteria:
+      - id: AC1
+        text: Marketing consent is separate and unchecked.
+        check:
+          type: semantic
+          question: Is there a marketing consent checkbox that is unchecked by default and separate from the terms?
+
+  - id: welcome-mail
+    kind: email
+    title: Welcome e-mail
+    mail: { subject: Welcome }
+    execution:
+      strategy: agent
+      instructions: After sign-up, capture the welcome e-mail with "kaloko mail --step welcome-mail".
+    criteria:
+      - id: AC1
+        text: The e-mail links back to the account.
+        check: { type: deterministic, assert: exists, selector: "a[href*='/account']" }
+
+  # Many pages of one template (articles, products, an SEO catalogue): one stack step, every page captured
+  # with these criteria; the canvas shows a stack with a searchable index. See the skill's reference/stacks.md.
+  # - id: articles
+  #   kind: stack
+  #   title: Articles
+  #   purpose: Every article reads well and is findable.
+  #   packs: [seo]
+  #   items: { sitemap: /sitemap.xml, match: '^/blog/', limit: 500, semantic_sample: 20 }
+  #   fields:
+  #     - { id: title, label: Title, from: title }
+  #     - { id: words, label: Words, from: words }
+  #     - { id: http, label: HTTP, from: http }
+  #   criteria:
+  #     - { id: AC1, text: Has a cover image, check: { type: deterministic, assert: exists, selector: "article img" } }
+
+edges:
+  - { from: landing, to: consent, label: accept cookies }
+  - { from: consent, to: choice }
+  - { from: choice, to: signup, label: no }
+  - { from: signup, to: welcome-mail, label: submit }

package/templates/steps/consent.mjs

@@ -0,0 +1,33 @@
+// Accepts the cookie/consent dialog on the current page, if the site has one.
+// Default first action of a session (see skills/kaloko/reference/acceptance.md);
+// when no dialog is found the step just captures the page as it is.
+const ACCEPT = [
+  '#c-p-bn', '#cc-main .cm__btn[data-role="all"]', // orestbida cookieconsent v2 / v3
+  '#CybotCookiebotDialogBodyLevelButtonLevelOptinAllowAll', '#CybotCookiebotDialogBodyButtonAccept', // Cookiebot
+  '#onetrust-accept-btn-handler', // OneTrust
+  '.cm-btn-accept-all', '.cm-btn-accept', // Klaro
+  '.cc-btn.cc-allow', '.cc-btn.cc-dismiss', // insites cookieconsent
+  '#tarteaucitronPersonalize2', // tarteaucitron
+  '[data-cookieconsent="accept"]', '[data-consent="accept"]', '[data-testid*="accept" i]',
+  'button:has-text(/^(accept( all)?|allow( all)?|agree|i agree|ok(ay)?|souhlasím|přijmout( vše)?|povolit( vše)?|prijať( všetko)?|súhlasím|akzeptieren|alle akzeptieren|aceptar( todo)?|accepter( tout)?|accetta( tutto)?)$/i)'
+]
+
+export async function acceptConsent (page, { timeout = 4000 } = {}) {
+  for (const selector of ACCEPT) {
+    const button = page.locator(selector).first()
+    if (!(await button.isVisible().catch(() => false))) continue
+    await button.click({ timeout })
+    await button.waitFor({ state: 'hidden', timeout }).catch(() => {})
+    return selector
+  }
+  // dialogs often render after load; wait once for the most common ones
+  const late = page.locator(ACCEPT.slice(0, 6).join(', ')).first()
+  if (await late.waitFor({ state: 'visible', timeout }).then(() => true, () => false)) return acceptConsent(page, { timeout })
+  return null
+}
+
+export default async ({ page, url }) => {
+  if (page.url() !== url()) await page.goto(url(), { waitUntil: 'domcontentloaded' })
+  const used = await acceptConsent(page)
+  console.log(used ? `  consent accepted via ${used}` : '  no consent dialog found; capturing as is')
+}