kaloko 0.12.2 → 0.14.0

package/src/lib/screens-cli.mjs

@@ -1,6 +1,6 @@
 // `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'
+import { UserError, NO_ORG } from './util.mjs'
 
 const FILTERS = ['project', 'product', 'module', 'scenario', 'locale', 'viewport', 'device', 'status', 'environment', 'limit', 'cursor']
 
@@ -10,6 +10,8 @@ export function screensQuery (args) {
   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]))
+  // --env is the environment, as in every other command (--environment still works)
+  if (typeof args.env === 'string') p.set('environment', args.env)
   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')
@@ -29,7 +31,7 @@ export function formatScreens (r) {
 }
 
 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.')
+  if (!config.org) throw new UserError(NO_ORG)
   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

@@ -1,5 +1,5 @@
 // Client of the Kaloko service API (kaloko.app or KALOKO_URL) with the organization token.
-import { UserError } from './util.mjs'
+import { UserError, NO_ORG, EXIT } from './util.mjs'
 
 /** Base URL of the service; configs written before the rename name app.qawalk.com, which now means kaloko.app. */
 export function serviceUrl (config, vars = process.env) {
@@ -19,8 +19,20 @@ export function ciName (vars = process.env) {
   return vars.CI && vars.CI !== 'false' ? 'ci' : null
 }
 
-/** What to do after the service answered `status`; '' when its own message says enough. */
-export function nextStepFor (status, { tokenEnv = 'KALOKO_TOKEN', url = 'https://kaloko.app' } = {}) {
+/** Plan & billing of the organization on the service (the service names it for 402 answers). */
+export const billingUrl = (url, org) => `${url}${org ? `/${org}` : ''}/billing`
+
+/**
+ * What to do after the service answered `status` (and `code`, when it names the reason); '' when its own message
+ * says enough. `message` is the service's message: a link it already holds is not repeated.
+ */
+export function nextStepFor (status, { tokenEnv = 'KALOKO_TOKEN', url = 'https://kaloko.app', code = null, billing = null, org = null, message = '' } = {}) {
+  const plan = billing || billingUrl(url, org)
+  const link = message.includes(plan) ? '' : ` Plan & billing: ${plan}`
+  if (code === 'billing_restricted') return `Billing of the organization is restricted until the payment is fixed; an admin updates it.${link}`
+  if (code === 'seat_limit') return `An admin buys seats or upgrades the plan.${link}`
+  if (code === 'sso_required') return 'Sign in through your company sign-in on kaloko.app in the browser, then run kaloko login.'
+  if (status === 402 || code === 'plan') return `Your plan does not include this.${link}`
   if (status === 401) return `The token in ${tokenEnv} is invalid, expired or revoked. Run kaloko login for a new one (or put a fresh token from Settings → API tokens into .env).`
   if (status === 403) return 'Your role or the token\'s scopes do not allow this; ask an admin of the organization, or use a token that may do it.'
   if (status === 413) return 'The file is larger than the service takes; leave it out of the run or make it smaller.'
@@ -30,17 +42,20 @@ export function nextStepFor (status, { tokenEnv = 'KALOKO_TOKEN', url = 'https:/
 }
 
 /** A UserError for an HTTP answer: what failed, the service's message, what to do next; `status` kept for callers. */
-export function httpError (what, status, message, opts) {
-  const err = new UserError([`${what} → HTTP ${status}: ${message}`, nextStepFor(status, opts)].filter(Boolean).join(' '))
+export function httpError (what, status, message, opts = {}) {
+  const err = new UserError(`${what} → HTTP ${status}: ${message}`, { next: nextStepFor(status, { ...opts, message: String(message || '') }) })
   err.status = status
   err.serviceMessage = message
+  if (opts.code) err.code = opts.code
+  // 401: the token is missing, invalid, expired or revoked (exit code 4); other answers are a failed command (1)
+  if (status === 401) { err.exitCode = EXIT.auth; err.code ||= 'unauthorized' }
   return err
 }
 
 /** A UserError for a request that got no answer at all (offline, DNS, refused, TLS). */
 export function unreachable (url, e) {
   const code = e?.cause?.code || e?.code || e?.message || 'no answer'
-  const err = new UserError(`Cannot reach ${url} (${code}). Check your network or VPN and run the command again; KALOKO_URL points the CLI to another service.`)
+  const err = new UserError(`Cannot reach ${url} (${code}). Check your network or VPN and run the command again; KALOKO_URL points the CLI to another service.`, { code: 'unreachable', exitCode: EXIT.unreachable })
   err.offline = true
   return err
 }
@@ -50,16 +65,24 @@ export function service (config) {
   const base = root + '/api/v1'
   const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
   const token = process.env[tokenEnv]
-  if (!token) throw new UserError(`${tokenEnv} is not set, so the CLI cannot reach your organization on ${root}. Run kaloko login, or create a token in Settings → API tokens and put ${tokenEnv}=… into .env.`)
-  const opts = { tokenEnv, url: root }
-  // an agent names itself (KALOKO_AGENT, e.g. "claude-code"); the service shows it in presence, history and audit (#42)
+  if (!token) throw new UserError(`${tokenEnv} is not set, so the CLI cannot reach your organization on ${root}. Run kaloko login, or create a token in Settings → API tokens and put ${tokenEnv}=… into .env.`, { code: 'no_token', exitCode: EXIT.auth })
+  const opts = { tokenEnv, url: root, org: config.org || null }
+  // an agent names itself (KALOKO_AGENT, e.g. "claude-code"); the service shows it in presence, history and audit (#42).
+  // Both header names: services before the rename read X-QAwalk-Agent only
   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 agent = process.env.KALOKO_AGENT ? process.env.KALOKO_AGENT.slice(0, 60) : null
+  const headers = { Authorization: `Bearer ${token}`, ...(agent ? { 'X-Kaloko-Agent': agent, 'X-QAwalk-Agent': agent } : {}), ...(ci ? { 'X-Kaloko-CI': ci } : {}) }
+  // an error answer: its message, and the reason code and billing link the service adds ({ error, code?, billing_url? })
+  const failed = async (res, what) => {
+    const body = await res.json().catch(() => ({}))
+    return httpError(what, res.status, body.error || res.statusText, { ...opts, code: body.code || null, billing: body.billing_url || null })
+  }
   const check = async (res, what) => {
     if (res.ok) return res.json()
-    const body = await res.json().catch(() => ({}))
-    throw httpError(what, res.status, body.error || res.statusText, opts)
+    throw await failed(res, what)
   }
+  // no org: in the config would ask for /orgs/undefined/…: say where the slug comes from instead
+  const orgOf = (path) => { if (/^\/orgs\/(?:undefined|null)?(?:[/?]|$)/.test(path)) throw new UserError(NO_ORG) }
   // fetch rejects without an answer (offline, refused, DNS): say so instead of a stack trace
   const call = (send) => send().catch((e) => { if (e instanceof UserError) throw e; throw unreachable(root, e) })
   // the service limits requests per token (HTTP 429, nothing was processed): wait as told and try again
@@ -76,26 +99,40 @@ export function service (config) {
   }
   return {
     async request (method, path, body) {
+      orgOf(path)
       const res = await call(() => limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined })))
       return check(res, `${method} ${path}`)
     },
+    /**
+     * One page of a list endpoint: { data, next }. `next` is the cursor of the following page (X-Next-Cursor, or
+     * `next` in an object answer), null on the last page and from services that do not page yet.
+     */
+    async page (path) {
+      orgOf(path)
+      const res = await call(() => limited(() => fetch(base + path, { headers })))
+      const data = await check(res, `GET ${path}`)
+      return { data, next: res.headers.get('X-Next-Cursor') || (data && !Array.isArray(data) && typeof data.next === 'string' ? data.next : null) }
+    },
     /** A request whose answer is not JSON (an export): the response, or an error with the service's message. */
     async raw (method, path, body) {
+      orgOf(path)
       const res = await call(() => 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 httpError(`${method} ${path}`, res.status, b.error || res.statusText, opts) }
+      if (!res.ok) throw await failed(res, `${method} ${path}`)
       return res
     },
     async fetch (path) {
+      orgOf(path)
       const res = await call(() => limited(() => fetch(base + path, { headers })))
-      if (!res.ok) { const body = await res.json().catch(() => ({})); throw httpError(`GET ${path}`, res.status, body.error || res.statusText, opts) }
+      if (!res.ok) throw await failed(res, `GET ${path}`)
       return res
     },
     async upload (path, data, name, extra = {}) {
+      orgOf(path)
       for (let attempt = 0; ; attempt++) {
         // a dropped connection (flaky Wi-Fi, CI runner hiccup) is tried again like a 5xx; the next share resumes otherwise
         let res
         try { res = await limited(() => fetch(base + path, { method: 'PUT', headers: { ...headers, ...extra }, body: data })) } catch (e) {
-          if (attempt >= 3) throw new UserError(`The upload of ${name} broke off (${e.cause?.code || e.message}). Check your network and run kaloko share again: files already stored are not sent twice.`)
+          if (attempt >= 3) throw new UserError(`The upload of ${name} broke off (${e.cause?.code || e.message}). Check your network and run kaloko share again: files already stored are not sent twice.`, { code: 'unreachable', exitCode: EXIT.unreachable })
           await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)))
           continue
         }

package/src/lib/signoff.mjs

@@ -3,7 +3,7 @@
 // record someone handed over, without a token. The keys come from <service>/.well-known/kaloko-signoff.json.
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
-import { UserError } from './util.mjs'
+import { UserError, UsageError } from './util.mjs'
 import { serviceUrl } from './service.mjs'
 import { verifyRecord, recordSha256, extractRecordFromPdf, canonicalJson } from './signoff-core.mjs'
 
@@ -64,7 +64,7 @@ export async function signoffCmd ({ config, args, say, client = null, runId = nu
     if (!check.ok) throw new UserError(`The sign-off record in ${args.verify} does not verify: ${check.reason}`)
     return check
   }
-  if (!runId) throw new UserError('Usage: kaloko signoff <run-id> [--out dir] [--lang cs|en] | kaloko signoff --verify <file.json|file.pdf> [--key file|url]')
+  if (!runId) throw new UsageError('Usage: kaloko signoff <run-id> [--out dir] [--lang cs|en] | kaloko signoff --verify <file.json|file.pdf> [--key file|url]')
   if (!client) throw new UserError('Downloading a sign-off record needs the service token (KALOKO_TOKEN).')
   const base = `/orgs/${config.org}/runs/${encodeURIComponent(runId)}`
   const lang = args.lang === 'cs' ? 'cs' : 'en'

package/src/lib/spec-cli.mjs

@@ -3,7 +3,7 @@
 // interaction states). The spec comes from the service (design reference, draft, a version or a shared run) or from
 // a local run's captures; drift compares the local implementation run with the reference from the service.
 import { join } from 'node:path'
-import { readJson, UserError } from './util.mjs'
+import { readJson, UserError, UsageError } from './util.mjs'
 import { readCaptures } from './run.mjs'
 import { latestCaptures } from './evaluate.mjs'
 import { specText, specDrift, driftText } from './devspec.mjs'
@@ -31,7 +31,7 @@ export async function specCmd ({ config, client, run, scenario, scenarioId, args
   // a step state (#46): its captures (keys <viewport>.state-<name>); default otherwise
   const state = typeof args.state === 'string' ? args.state : null
   const steps = step ? [step] : (scenario?.nodes || []).filter((n) => n.kind !== 'decision' && n.kind !== 'external').map((n) => n.id)
-  if (!steps.length) throw new UserError('Usage: kaloko spec <step> [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--state s] [--local] [--json]')
+  if (!steps.length) throw new UsageError('Usage: kaloko spec <step> [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--state s] [--local] [--json]')
   const out = []
   for (const s of steps) {
     if (args.local || !client) {
@@ -66,7 +66,7 @@ export async function driftCmd ({ config, client, run, scenarioId, args, say })
   if (!client) throw new UserError('kaloko drift compares with the approved design on the service: set org and a token (kaloko login).')
   const results = []
   if (args.remote) {
-    if (!step) throw new UserError('Usage: kaloko drift <step> --remote <run id|latest>')
+    if (!step) throw new UsageError('Usage: kaloko drift <step> --remote <run id|latest>')
     const q = new URLSearchParams(Object.entries({ run: typeof args.remote === 'string' ? args.remote : 'latest', ref, locale, viewport }).filter(([, v]) => v))
     const d = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/steps/${enc(step)}/drift?${q}`)
     results.push({ node: step, locale: d.locale, viewport: d.viewport, ref: d.ref, findings: d.findings, text: d.text })

package/src/lib/upload.mjs

@@ -71,7 +71,7 @@ export async function uploadRunFiles ({ client, org, runId, dir, entries, missin
     const tick = progressLine(write, 'uploaded')
     await pool([...byHash.values()], workers, async (e) => {
       const { data, gz } = encode(e.path, await readFile(join(dir, e.path)))
-      await client.upload(`/orgs/${org}/blobs/${e.hash}`, data, e.path, { 'X-QAwalk-Type': e.ext, ...(gz ? { 'Content-Encoding': 'gzip' } : {}) })
+      await client.upload(`/orgs/${org}/blobs/${e.hash}`, data, e.path, { 'X-Kaloko-Type': e.ext, 'X-QAwalk-Type': e.ext, ...(gz ? { 'Content-Encoding': 'gzip' } : {}) })
       sent += data.length
     }, () => tick(++done, byHash.size, sent))
     // 2. the run's file list points at the blobs; a service that does not know references says so by leaving out `blobs`

package/src/lib/util.mjs

@@ -65,7 +65,46 @@ export function globToRegExp (glob) {
   return new RegExp('^' + out + '$')
 }
 
-export class UserError extends Error {}
+/**
+ * An error the person can act on: what happened, then (`next`) what to do about it, in one format for every command:
+ * "<what happened> <what to do next>". `reason` and `next` stay apart for callers that show them separately.
+ */
+export class UserError extends Error {
+  constructor (message, { next = '', code = null, exitCode = null, ...options } = {}) {
+    super([message, next].filter(Boolean).join(' '), options)
+    this.reason = message
+    this.next = next || ''
+    if (code) this.code = code
+    if (exitCode) this.exitCode = exitCode
+  }
+}
+
+/** A command used the wrong way (unknown option, missing argument): exit code 2 and the command's help, no support line. */
+export class UsageError extends UserError {
+  constructor (message, options = {}) { super(message, { code: 'usage', exitCode: EXIT.usage, ...options }) }
+}
+
+/**
+ * Exit codes of every command (kaloko help, help/reference/cli.md, skills/kaloko/reference/ci.md). 3 and 4 are only
+ * for the Kaloko service: no connection at all (3), and no, an invalid or an expired token (4). An HTTP error answer
+ * other than 401 is 1, like any failed command.
+ */
+export const EXIT = { ok: 0, failed: 1, usage: 2, unreachable: 3, auth: 4 }
+
+const UNIT_SECONDS = { s: 1, m: 60, h: 3600, d: 86400 }
+const UNIT_NAMES = { s: 'seconds', m: 'minutes', h: 'hours', d: 'days' }
+
+/**
+ * A duration option (--timeout, --wait, --expires, --older-than): a bare number in the option's own `unit` (what it
+ * always meant), or a number with s, m, h or d (90s, 10m, 2h, 14d). Returns the value in `unit`; null when the option
+ * is absent or has no value; a UsageError naming `flag` for anything else.
+ */
+export function parseDuration (value, unit, flag) {
+  if (value == null || value === true || value === '') return null
+  const m = String(value).trim().match(/^(\d+(?:\.\d+)?)\s*([smhd])?$/i)
+  if (!m) throw new UsageError(`--${flag} takes a duration: a number of ${UNIT_NAMES[unit]}, or one with s, m, h or d (90s, 10m, 2h, 14d); not "${value}".`)
+  return Number(m[1]) * UNIT_SECONDS[(m[2] || unit).toLowerCase()] / UNIT_SECONDS[unit]
+}
 
 /** Every CLI error ends with a way to a person (docs/HARDENING.md phase 6, item 12). */
 export const SUPPORT_EMAIL = 'support@sinfin.cz'

package/src/lib/video-cli.mjs

@@ -8,7 +8,7 @@ import { resolveRun, addCapture } from './run.mjs'
 import { loadScenario } from './scenario.mjs'
 import { buildManifest } from './build.mjs'
 import { launchEphemeral } from './browser.mjs'
-import { readJson, localized, UserError } from './util.mjs'
+import { readJson, localized, UserError, UsageError, parseDuration } from './util.mjs'
 import { videoTools, encoderCaps, ffmpeg, preset, installHint, outputSize } from './video.mjs'
 import { formatTrace } from './trace.mjs'
 
@@ -115,7 +115,7 @@ export async function exportWalkthrough ({ config, root, args, say }) {
   const P = preset(args.quality || 'medium')
   const fps = format === 'gif' ? 10 : P.fps
   const [width, height] = format === 'gif' ? outputSize(1280, 800, 800) : outputSize(1280, 800, Math.min(P.width, 1280))
-  const card = Math.max(0.5, Math.min(6, Number(args['card-seconds']) || 1.6))
+  const card = Math.max(0.5, Math.min(6, parseDuration(args['card-seconds'], 's', 'card-seconds') || 1.6))
   const browser = await launchEphemeral(config)
   const tmp = await mkdtemp(join(tmpdir(), 'kaloko-walkthrough-'))
   const defaultOut = join(run.dir, 'attachments', `walkthrough.rec.${format}`)
@@ -189,7 +189,7 @@ export async function videoCmd ({ config, root, args, say }) {
   if (sub === 'trace') {
     const step = typeof args.step === 'string' ? args.step : null
     const n = manifest.nodes.find((x) => x.id === step)
-    if (!n) throw new UserError(`Usage: kaloko video trace --step <id> [--locale l] [--viewport v] [--json]. Steps: ${manifest.nodes.map((x) => x.id).join(', ')}`)
+    if (!n) throw new UsageError(`Usage: kaloko video trace --step <id> [--locale l] [--viewport v] [--json]. Steps: ${manifest.nodes.map((x) => x.id).join(', ')}`)
     const loc = typeof args.locale === 'string' ? args.locale : Object.keys(n.captures || {})[0]
     const vps = n.captures?.[loc] || {}
     const vp = typeof args.viewport === 'string' ? args.viewport : Object.keys(vps).find((v) => vps[v]?.trace)