kaloko 0.5.2 → 0.6.0

package/src/lib/integrations-cli.mjs

@@ -0,0 +1,211 @@
+// Batch H in the CLI: `kaloko issue create|list` (Jira and Linear, #21) and `kaloko schedule …` (hosted runs, #16):
+// add a read-only scenario to Kaloko's own browsers, list, run, pause, resume and remove schedules, or write a GitHub
+// Actions workflow that walks it on a schedule with the full CLI (`schedule export github`).
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve, relative, dirname, join } from 'node:path'
+import { UserError } from './util.mjs'
+import { gateOf, accountFor } from './access.mjs'
+import { secret } from './secrets.mjs'
+import { runner } from './ci.mjs'
+
+const RUN_ID = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]{3,120}$/
+const WEEKDAYS = { mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6, sun: 7 }
+
+// ---------- kaloko issue ----------
+
+const issueLine = (i) => `${i.key.padEnd(10)} ${String(i.state).padEnd(8)} step ${i.step}${i.criterion ? ` (${i.criterion})` : ''} · ${i.title}\n           ${i.url}`
+
+/**
+ * `kaloko issue create --step <id> --to jira|linear [--criterion AC2] [--title …] [--note …] [--run id] [--locale l]
+ * [--viewport v] [--target KEY] [--json]` and `kaloko issue list [--run id] [--scenario id] [--state open] [--json]`.
+ */
+export async function issueCmd ({ args, config, client, runId, say }) {
+  const sub = args._[0]
+  const org = config.org
+  if (!org) throw new UserError('Set org: in the config first.')
+  if (sub === 'list') {
+    const q = new URLSearchParams(Object.entries({ run: typeof args.run === 'string' ? args.run : null, scenario: typeof args.scenario === 'string' ? args.scenario : null, state: typeof args.state === 'string' ? args.state : null }).filter(([, v]) => v))
+    const items = await client.request('GET', `/orgs/${org}/issues${q.size ? `?${q}` : ''}`)
+    if (args.json) { say(JSON.stringify(items, null, 2)); return items }
+    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]')
+  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.')
+  const run = typeof args.run === 'string' ? args.run : runId
+  if (!run || !RUN_ID.test(run)) throw new UserError('No shared run: pass --run <id>, or share the current run first (kaloko share).')
+  const body = { run_id: run, step: args.step, to, ...Object.fromEntries(['criterion', 'title', 'note', 'locale', 'viewport', 'target'].filter((k) => typeof args[k] === 'string' && args[k]).map((k) => [k, args[k]])) }
+  const issue = await client.request('POST', `/orgs/${org}/issues`, body)
+  if (args.json) { say(JSON.stringify(issue, null, 2)); return issue }
+  say(`✓ ${issue.key} in ${to === 'jira' ? 'Jira' : 'Linear'}${issue.screenshot ? ', with the screenshot' : ''}: ${issue.url}\n  The step got a comment that is resolved when the issue is done.`)
+  return issue
+}
+
+// ---------- kaloko schedule ----------
+
+/** A step script that only opens its page (export default async ({ page, url }) => { await page.goto(url(…)) }). */
+export function onlyNavigates (code) {
+  const s = String(code || '').replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1').trim()
+  return /^export\s+default\s+async\s*(?:function\s*\w*\s*)?\(\s*\{\s*page\s*,\s*url\s*\}\s*\)\s*(?:=>)?\s*\{\s*(?:await\s+page\.goto\(\s*url\(\s*\)\s*(?:,\s*\{[^{}]*\})?\s*\)\s*;?\s*)\}\s*;?$/.test(s)
+}
+
+/** The scenario as the service takes it: packs expanded, steps whose script only navigates marked hosted: open. */
+export async function hostedScenario (scenario, scenarioFile) {
+  const out = JSON.parse(JSON.stringify(scenario))
+  for (const n of out.nodes || []) {
+    const script = n.execution?.script
+    if (!script || /^open\.(m?js|cjs)$/.test(String(script).split('/').pop())) continue
+    try { if (onlyNavigates(await readFile(resolve(dirname(scenarioFile), script), 'utf8'))) n.hosted = 'open' } catch {}
+  }
+  return out
+}
+
+/** How the hosted browser gets past the environment's gate: HTTP Basic from its variables, or an account's cookies. */
+export async function hostedAuth ({ env, account = null, root, config, vars = process.env }) {
+  if (account) {
+    const file = accountFor(env, account, { root, config }).storage_state
+    let state
+    try { state = JSON.parse(await readFile(file, 'utf8')) } catch { throw new UserError(`No saved session for ${account} in ${env.name} (${relative(process.cwd(), file)}). Sign in once with kaloko auth save --env ${env.name} --account ${account}, then schedule again.`) }
+    return { cookies: (state.cookies || []).map(({ name, value, domain, path, expires, httpOnly, secure, sameSite }) => ({ name, value, domain, path, expires, httpOnly, secure, sameSite })) }
+  }
+  const gate = gateOf(env)
+  if (gate.basic) return { basic: { user: secret(gate.basic.user_env, `HTTP Basic user for ${env.name}`, vars), password: secret(gate.basic.password_env, `HTTP Basic password for ${env.name}`, vars) } }
+  if (gate.headers && Object.keys(gate.headers).length) throw new UserError(`${env.name} is behind header credentials (access.headers); hosted runs send HTTP Basic or a saved session only. Walk it in CI: kaloko schedule export github.`)
+  return null
+}
+
+const atHour = (v, d = 5) => { const n = Number(String(v ?? '').split(':')[0]); return Number.isInteger(n) && n >= 0 && n <= 23 ? n : d }
+const weekdayOf = (v, d = 1) => WEEKDAYS[String(v || '').slice(0, 3).toLowerCase()] || (Number(v) >= 1 && Number(v) <= 7 ? Number(v) : d)
+const when = (s) => s.every === 'manual' ? 'on demand' : `${s.every === 'week' ? `weekly on ${Object.keys(WEEKDAYS)[s.weekday - 1]}` : 'daily'} at ${String(s.at_hour).padStart(2, '0')}:00 UTC`
+const scheduleLine = (s) => `${s.id}  ${s.scenario_id} on ${s.environment} (${s.base_url}) · ${when(s)}${s.enabled ? '' : ' · paused'}${s.pages_per_run ? ` · ${s.pages_per_run} pages` : ''}\n  next ${s.enabled && s.next_run_at ? s.next_run_at.slice(0, 16).replace('T', ' ') : '—'} · last ${s.last_run_at ? `${s.last_run_at.slice(0, 16).replace('T', ' ')} ${s.last_status}${s.last_run_id ? ` ${s.last_run_id}` : ''}` : '—'}${s.last_error ? `\n  ! ${s.last_error}` : ''}`
+
+/** The GitHub Actions workflow that walks a scenario on a schedule with the full CLI and shares the run. */
+export function githubScheduleWorkflow ({ scenario, scenarioId, env, every = 'day', at_hour = 5, weekday = 1, pm = 'npm', dependency = true, version = 'latest', node = 22, browsers = ['chromium'], secrets = [] }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const cron = every === 'week' ? `0 ${at_hour} * * ${weekday % 7}` : `0 ${at_hour} * * *`
+  const engines = browsers.some((b) => b !== 'chromium') ? ` --browsers ${browsers.join(',')}` : ''
+  const names = [...new Set(secrets.filter((n) => /^[A-Z_][A-Z0-9_]*$/.test(n)))]
+  return `# Kaloko: walk ${scenarioId} on ${env} ${every === 'week' ? 'every week' : 'every day'} and share the run.
+# Written by kaloko schedule export github. Secrets: KALOKO_TOKEN (tester role, upload scope; on Enterprise a service
+# account's)${names.length ? `; ${names.join(', ')} (the environment's credentials, as in kaloko.config.yml)` : ''}.
+name: Kaloko ${scenarioId} on ${env}
+on:
+  schedule:
+    - cron: '${cron}'   # UTC
+  workflow_dispatch:
+concurrency:
+  group: kaloko-schedule-${scenarioId}-${env}
+  cancel-in-progress: false
+permissions:
+  contents: read
+jobs:
+  walk:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
+      KALOKO_AGENT: github-actions
+${names.map((n) => `      ${n}: \${{ secrets.${n} }}`).join('\n')}${names.length ? '\n' : ''}    steps:
+      - uses: actions/checkout@v4
+      - 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${engines}
+      - name: Walk, evaluate, share
+        run: |
+          ${k} start --scenario ${scenario} --env ${env}
+          ${k} walk
+          ${k} evaluate
+          ${k} share
+`
+}
+
+/** Variable names the environment and the scenario's accounts read their secrets from. */
+export function secretNames (env, scenario = {}) {
+  const out = []
+  const gate = gateOf(env)
+  if (gate.basic) out.push(gate.basic.user_env, gate.basic.password_env)
+  for (const spec of Object.values(gate.headers || {})) if (spec && typeof spec === 'object' && spec.env) out.push(spec.env)
+  const used = new Set(Object.values(scenario.sessions || {}).map((s) => s?.account).filter(Boolean))
+  for (const [key, a] of Object.entries(env.accounts || {})) if (used.has(key)) out.push(a.user_env, a.password_env, a.totp_env)
+  return out.filter(Boolean)
+}
+
+/**
+ * `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>`.
+ * deps: { loadScenario, environment, baseUrl, projectAndIssue, packageRoot, service }.
+ */
+export async function scheduleCmd ({ args, config, root, say, deps }) {
+  const [sub, id] = args._
+  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]')
+    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
+    if (!envName) throw new UserError('--env <name> names the environment (production, staging …).')
+    const scenario = await deps.loadScenario(file)
+    // only the names of its variables are needed here: the workflow reads the values from repository secrets
+    if (!config.environments?.[envName]) throw new UserError(`Unknown environment "${envName}". Known: ${Object.keys(config.environments || {}).join(', ')}`)
+    const env = { name: envName, ...config.environments[envName] }
+    if (scenario.environments && !scenario.environments.includes(envName)) throw new UserError(`${relative(root, file)} allows environments [${scenario.environments.join(', ')}], not ${envName}.`)
+    let pkg = null
+    try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) } catch {}
+    const pm = existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : existsSync(join(root, 'bun.lockb')) || existsSync(join(root, 'bun.lock')) ? 'bun' : 'npm'
+    const version = JSON.parse(await readFile(join(deps.packageRoot, 'package.json'), 'utf8')).version
+    const every = args.every === 'week' ? 'week' : 'day'
+    const content = githubScheduleWorkflow({ scenario: relative(root, file), scenarioId: scenario.id, env: envName, every, at_hour: atHour(args.at), weekday: weekdayOf(args.weekday), pm, dependency: !!(pkg && ({ ...pkg.dependencies, ...pkg.devDependencies }).kaloko), version: `^${version}`, browsers: [...new Set(['chromium', ...(scenario.browsers || []), ...(config.walk?.browsers || [])])], secrets: secretNames(env, scenario) })
+    if (args.print) { say(content); return { content } }
+    const out = resolve(root, typeof args.out === 'string' ? args.out : `.github/workflows/kaloko-${scenario.id.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${envName}.yml`)
+    if (existsSync(out) && !args.force) throw new UserError(`${relative(process.cwd(), out)} exists; pass --force to replace it (or --print to compare).`)
+    await mkdir(dirname(out), { recursive: true })
+    await writeFile(out, content)
+    say(`Wrote ${relative(process.cwd(), out)}: ${scenario.id} on ${envName} ${every === 'week' ? 'every week' : 'every day'} at ${String(atHour(args.at)).padStart(2, '0')}:00 UTC with the full walk (clicks, forms, every criterion).\nNext: add the repository secret KALOKO_TOKEN${secretNames(env, scenario).length ? ` and ${secretNames(env, scenario).join(', ')}` : ''}, then commit the workflow.`)
+    return { file: out }
+  }
+  if (!org) throw new UserError('Set org: in the config first.')
+  if (sub === 'list' || !sub) {
+    const data = await client().request('GET', `/orgs/${org}/schedules`)
+    if (args.json) { say(JSON.stringify(data, null, 2)); return data }
+    if (!data.configured) { say('Hosted runs are not enabled on this service. Walk on a schedule in CI: kaloko schedule export github --scenario <file> --env <name>'); return data }
+    say(`${data.usage.pages} of ${data.usage.budget} hosted pages used in ${data.usage.month}${data.plan_allows ? '' : ' (hosted runs come with the Business plan)'}`)
+    say(data.schedules.length ? data.schedules.map(scheduleLine).join('\n') : 'No schedules yet: kaloko schedule add --scenario <file> --env <name> --every day')
+    return data
+  }
+  if (sub === 'add') {
+    const file = typeof args.scenario === 'string' ? resolve(root, args.scenario) : null
+    if (!file) throw new UserError('--scenario <file> names a read-only scenario.')
+    const envName = typeof args.env === 'string' ? args.env : null
+    if (!envName) throw new UserError('--env <name> names the environment (its base_url is what the hosted browser opens).')
+    const scenario = await deps.loadScenario(file)
+    const env = deps.environment(config, envName)
+    if (scenario.environments && !scenario.environments.includes(envName)) throw new UserError(`${relative(root, file)} allows environments [${scenario.environments.join(', ')}], not ${envName}.`)
+    if (env.kind === 'design' || env.base_url == null) throw new UserError(`${envName} has no web address; hosted runs open web pages.`)
+    if (typeof env.base_url !== 'string') throw new UserError(`${envName} has a base_url per locale; hosted runs take one address. Walk it in CI: kaloko schedule export github.`)
+    const every = ['day', 'week', 'manual'].includes(args.every) ? args.every : 'day'
+    const { project } = await deps.projectAndIssue({ cwd: root, config, scenario, branch: null })
+    const body = { scenario: await hostedScenario(scenario, file), environment: envName, base_url: deps.baseUrl(env), every, at_hour: atHour(args.at), weekday: weekdayOf(args.weekday), project: project?.slug || null, auth: await hostedAuth({ env, account: typeof args.account === 'string' ? args.account : null, root, config }) }
+    let s
+    try { s = await client().request('POST', `/orgs/${org}/schedules`, body) } catch (e) {
+      if (/HTTP 404/.test(e.message)) throw new UserError(`${e.message}\nWalk it on a schedule in CI instead: kaloko schedule export github --scenario ${relative(root, file)} --env ${envName}`)
+      throw e
+    }
+    if (args.json) { say(JSON.stringify(s, null, 2)); return s }
+    say(`✓ ${s.created ? 'Scheduled' : 'Updated'} ${s.scenario_id} on ${envName} ${when(s)}: ${s.pages_per_run} pages per run${s.auth !== 'none' ? ` (${s.auth === 'basic' ? 'HTTP Basic' : 'saved session'})` : ''}. Runs are shared as you and land in the inbox.`)
+    for (const k of s.skipped || []) say(`  - ${k.id}: not walked (${k.reason})`)
+    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)`)
+  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)')
+}

package/src/lib/screens-cli.mjs

@@ -0,0 +1,36 @@
+// `kaloko screens`: the screen library from the terminal (batch G): the newest capture of every step of the
+// organization's flows, searched on the service (GET /orgs/<org>/screens), one line per screen with its canvas link.
+import { UserError } from './util.mjs'
+
+const FILTERS = ['project', 'product', 'module', 'scenario', 'locale', 'viewport', 'device', 'status', 'environment', 'limit', 'cursor']
+
+/** The query string of a search from CLI arguments: words are the query, --designs adds design versions. */
+export function screensQuery (args) {
+  const p = new URLSearchParams()
+  const q = (args._ || []).join(' ').trim() || (typeof args.q === 'string' ? args.q : '')
+  if (q) p.set('q', q)
+  for (const k of FILTERS) if (typeof args[k] === 'string' || typeof args[k] === 'number') p.set(k, String(args[k]))
+  if (args.designs || args.source === 'all') p.set('source', 'all')
+  else if (args.source === 'design') p.set('source', 'design')
+  if (args.all) p.set('group', 'none')
+  return p
+}
+
+export function formatScreens (r) {
+  if (!r.items.length) return 'No screen matches.'
+  const lines = r.items.map((it) => {
+    const where = [it.locale, it.viewport].filter(Boolean).join('/')
+    const st = it.status ? `${it.status}`.padEnd(8) : ''.padEnd(8)
+    const tag = it.source === 'design' ? ` [design${it.version ? ` v${it.version}` : ''}]` : ''
+    return `${st} ${it.scenario.id}/${it.step.id} ${where}${tag}  ${it.step.title || ''}${it.url ? `  ${it.url}` : it.path ? `  ${it.path}` : ''}\n         ${it.canvas}`
+  })
+  if (r.next) lines.push(`… more: kaloko screens ${r.filters?.q ? `"${r.filters.q}" ` : ''}--cursor ${r.next}`)
+  return lines.join('\n')
+}
+
+export async function screensCmd ({ config, client, args, say }) {
+  if (!config.org) throw new UserError('Set org: in kaloko.config.yml (or run kaloko login) to search the screen library.')
+  const r = await client.request('GET', `/orgs/${config.org}/screens?${screensQuery(args)}`)
+  say(args.json ? JSON.stringify(r, null, 2) : formatScreens(r))
+  return r
+}

package/src/lib/service.mjs

@@ -7,13 +7,26 @@ export function serviceUrl (config, vars = process.env) {
   return url.replace(/^https:\/\/app\.qawalk\.com$/, 'https://kaloko.app')
 }
 
+/** Which CI runs this (github, gitlab, …), or null on a laptop: the service counts a team's first run from CI. */
+export function ciName (vars = process.env) {
+  if (vars.GITHUB_ACTIONS === 'true') return 'github'
+  if (vars.GITLAB_CI) return 'gitlab'
+  if (vars.CIRCLECI) return 'circleci'
+  if (vars.BUILDKITE) return 'buildkite'
+  if (vars.JENKINS_URL) return 'jenkins'
+  if (vars.BITBUCKET_BUILD_NUMBER) return 'bitbucket'
+  if (vars.TF_BUILD) return 'azure'
+  return vars.CI && vars.CI !== 'false' ? 'ci' : null
+}
+
 export function service (config) {
   const base = serviceUrl(config) + '/api/v1'
   const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
   const token = process.env[tokenEnv]
   if (!token) throw new UserError(`Set ${tokenEnv} (create a token in Kaloko → Settings).`)
   // an agent names itself (KALOKO_AGENT, e.g. "claude-code"); the service shows it in presence, history and audit (#42)
-  const headers = { Authorization: `Bearer ${token}`, ...(process.env.KALOKO_AGENT ? { 'X-QAwalk-Agent': process.env.KALOKO_AGENT.slice(0, 60) } : {}) }
+  const ci = ciName()
+  const headers = { Authorization: `Bearer ${token}`, ...(process.env.KALOKO_AGENT ? { 'X-QAwalk-Agent': process.env.KALOKO_AGENT.slice(0, 60) } : {}), ...(ci ? { 'X-Kaloko-CI': ci } : {}) }
   const check = async (res, what) => {
     if (res.ok) return res.json()
     const body = await res.json().catch(() => ({}))
@@ -36,6 +49,12 @@ export function service (config) {
       const res = await limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined }))
       return check(res, `${method} ${path}`)
     },
+    /** A request whose answer is not JSON (an export): the response, or an error with the service's message. */
+    async raw (method, path, body) {
+      const res = await limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined }))
+      if (!res.ok) { const b = await res.json().catch(() => ({})); throw new UserError(`${method} ${path} → HTTP ${res.status}: ${b.error || res.statusText}`) }
+      return res
+    },
     async fetch (path) {
       const res = await fetch(base + path, { headers })
       if (!res.ok) { const body = await res.json().catch(() => ({})); throw new UserError(`GET ${path} → HTTP ${res.status}: ${body.error || res.statusText}`) }