kaloko 0.16.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",
@@ -32,7 +32,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node scripts/test.mjs"
+    "test": "node scripts/test.mjs",
+    "version": "node scripts/cli-catalogue.mjs && git add worker/src/cli-latest.json"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/skills/kaloko/SKILL.md

@@ -210,9 +210,12 @@ only when a person says that value may be uploaded.
   tools (relative URLs, no CDNs, state in the URL, deterministic content,
   links between steps; what `kaloko design lint` checks):
   [reference/portable-html.md](reference/portable-html.md)
-- Command reference: `kaloko help`; when something does not work (Chrome,
+- Command reference: `kaloko help` (`kaloko help --json` lists every command,
+  sub-command and option as data); when something does not work (Chrome,
   token, environment URL, evaluator key), run `kaloko doctor` first and fix
-  what it marks ✕.
+  what it marks ✕. When a command answers "… is in kaloko X (you have Y)",
+  the project's kaloko is too old for it: tell the person and suggest the
+  update command from that line; change the dependency only when they agree.
 
 Project configuration is `kaloko.config.yml` in the repository root.
 Project skills may add conventions (paths, test data, locales); follow them

package/src/cli.mjs

@@ -39,7 +39,7 @@ import { formatReviewQueue, shareReviewLine } from './lib/review.mjs'
 import { healthCmd } from './lib/health.mjs'
 import { htmlViewAllowed } from './lib/htmlview.mjs'
 import { service, serviceUrl } from './lib/service.mjs'
-import { parseArgs, helpFor, checkOptions, closest } from './lib/cli-args.mjs'
+import { parseArgs, helpFor, checkOptions, closest, catalogue, unknownOptions, subcommandsFor, takesWords } from './lib/cli-args.mjs'
 import { issueCmd, scheduleCmd } from './lib/integrations-cli.mjs'
 import { login } from './lib/login.mjs'
 import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
@@ -67,6 +67,7 @@ import { startScope, scopeKeys, dimensionLine, baseViewports, engineKeys, appDev
 import { deviceConfig, prepareAndroid, readyAndroid, finishAndroid, prepareSimulator, applyAppAppearance } from './lib/apps/devices.mjs'
 import { attachAndroidWebView } from './lib/apps/webview.mjs'
 import { piiSettings, piiFindings, piiRequested, guardAllow, formatFindings } from './lib/pii.mjs'
+import { updateHint } from './lib/update-check.mjs'
 
 
 /** Options every command takes and the exit codes; the end of kaloko help and of the help of each command. */
@@ -78,9 +79,10 @@ const COMMON_HELP = `Common options (every command)
                                     JSON, progress and notes go to stderr, and an error is one line on stderr:
                                     {"error":{"message":"…","code":"…","next":"…"}} with the exit code below
   --help, -h                        Help for one command, like kaloko help <command> (kaloko help export run: one
-                                    sub-command)
+                                    sub-command); kaloko help --json lists every command, sub-command and option
   --version, -v                     The version of kaloko (also kaloko version)
   KALOKO_AGENT=<name>               Labels writes by an agent
+  KALOKO_NO_UPDATE_CHECK=1          An unknown command or option does not ask kaloko.app whether a newer kaloko has it
   Durations (--timeout, --wait, --expires, --older-than) take a number in the option's unit or one with s, m, h or d:
   90s, 10m, 2h, 14d
 
@@ -2722,11 +2724,18 @@ const commands = {
   /** `kaloko help [command]`: everything, or the entries of one command with the common options. */
   async help (args = { _: [] }) {
     const topic = args._?.[0]
+    // kaloko help --json: every command, sub-command and option as data (kaloko help prune --json: that command)
+    if (args.json) {
+      const all = await cliCatalogue()
+      if (!topic) { say(JSON.stringify(all, null, 2)); return }
+      if (all.commands[topic]) { say(JSON.stringify({ version: all.version, commands: { [topic]: all.commands[topic] } }, null, 2)); return }
+      return unknownCommand(topic, true, args)
+    }
     if (!topic) { say(HELP); return }
     // kaloko help export run: the entries of that sub-command (all of the command's when it has none by that name)
     const text = commands[topic] && topic !== 'help' ? helpFor(HELP, topic, COMMON_HELP, args._?.[1]) : null
     if (text) { say(text); return }
-    unknownCommand(topic)
+    return unknownCommand(topic, false, args)
   }
 }
 
@@ -2735,14 +2744,41 @@ async function packageVersion () {
   return JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
 }
 
-/** "There is no command": the nearest command when it looks like a typo, the full help, exit code 2. */
-function unknownCommand (name, json = false) {
-  const guess = closest(name, Object.keys(commands))
-  const message = `There is no command "${name}".${guess ? ` Did you mean kaloko ${guess}?` : ''}`
-  if (json) { console.error(JSON.stringify(jsonError(new UsageError(message, { next: 'kaloko help lists the commands.' })))); process.exitCode = EXIT.usage; return }
+/** Every command, sub-command and option of this kaloko as data: kaloko help --json, and the service's /cli/latest.json. */
+export async function cliCatalogue () {
+  return catalogue(HELP, [...Object.keys(commands), 'version'], await packageVersion())
+}
+
+/**
+ * "There is no command": when a newer kaloko has it, the line that says which version and how to update; else the
+ * nearest command when it looks like a typo and the full help. Exit code 2 either way.
+ */
+async function unknownCommand (name, json = false, args = {}) {
+  process.exitCode = EXIT.usage
+  const update = await newerKaloko({ command: name }, args)
+  const guess = update ? null : closest(name, Object.keys(commands))
+  const message = `There is no command "${name}"${update ? ' in this kaloko' : ''}.${guess ? ` Did you mean kaloko ${guess}?` : ''}`
+  if (json) { console.error(JSON.stringify(jsonError(new UsageError(message, { next: update || 'kaloko help lists the commands.' })))); return }
+  if (update) { console.error(`${message}\n${update}`); return }
   console.error(`${message} The commands are below; kaloko help <command> explains one.\n`)
   say(HELP)
-  process.exitCode = EXIT.usage
+}
+
+/** A usage error whose next step is updating kaloko (printed on its own line). */
+const updateError = (reason, update) => Object.assign(new UsageError(reason, { next: update }), { update: true })
+
+/**
+ * The update line for what this kaloko does not know ({ command, sub, options }), or null: only when the newest
+ * released kaloko (the service's /cli/latest.json, cached for a day) is newer and has exactly that. With `detail`:
+ * { update: line, newer: [options the newer kaloko takes] }.
+ */
+async function newerKaloko (typed, args = {}, detail = false) {
+  try {
+    let config = {}
+    try { ({ config } = await loadConfig(process.cwd(), typeof args.config === 'string' ? args.config : undefined)) } catch {}
+    const r = await updateHint(typed, { installed: await packageVersion(), config, root: packageRoot, args })
+    return detail ? r : r?.line || null
+  } catch { return null }
 }
 
 /** A line of output that is a JSON document (the --json answer), told apart from progress and notes. */
@@ -2782,13 +2818,27 @@ async function runCommand (args, json) {
   if ((!args._.length && args.version) || args._[0] === 'version') { say(json ? JSON.stringify({ version: await packageVersion() }) : await packageVersion()); return }
   const name = args._.shift() || 'help'
   const cmd = commands[name]
-  if (!cmd) { if (args.help) say(HELP); else unknownCommand(name, json); return }
+  if (!cmd) { if (args.help) say(HELP); else await unknownCommand(name, json, args); return }
   // kaloko <command> --help: the command's help instead of running it
   if (args.help && name !== 'help') { say(helpFor(HELP, name, COMMON_HELP, args._[0]) || HELP); return }
+  // what this kaloko does not know: a word after a command that takes none (kaloko projects create) and options its
+  // help does not name. A newer kaloko may have them; only then a line says which version and how to update.
+  const word = name !== 'help' && typeof args._[0] === 'string' && !subcommandsFor(HELP, name).has(args._[0]) ? args._[0] : null
+  const unknown = unknownOptions(HELP, name, args)
   try {
-    for (const line of checkOptions(HELP, name, args)) console.error(line)
+    if (word && !takesWords(HELP, name)) {
+      const update = await newerKaloko({ command: name, sub: word }, args)
+      if (update) throw updateError(`There is no "kaloko ${name} ${word}" in this kaloko.`, update)
+    }
+    const newer = unknown.length ? await newerKaloko({ command: name, options: unknown }, args, true) : null
+    for (const line of checkOptions(HELP, name, args, newer || {})) console.error(line)
     await cmd(args)
   } catch (error) {
+    // a usage error over a sub-command a newer kaloko has (kaloko tokens <new>): say so instead of only the help
+    if (error instanceof UsageError && !error.update && !error.next && word) {
+      const update = await newerKaloko({ command: name, sub: word }, args)
+      if (update) error = updateError(error.reason, update)
+    }
     const known = error instanceof UserError
     if (json) {
       // the reason in one JSON line on stderr, the documented exit code; a bug also prints its stack before it
@@ -2798,7 +2848,7 @@ async function runCommand (args, json) {
       return
     }
     // a usage mistake: the command's help says what is wrong; no support line, exit code 2
-    if (error instanceof UsageError) { console.error(`${error.message}${/kaloko help /.test(error.message) ? '' : `\nkaloko help ${name} shows how to use it.`}`); process.exitCode = EXIT.usage } else if (known) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = exitCodeOf(error) } else {
+    if (error instanceof UsageError && error.update) { console.error(`${error.reason}\n${error.next}`); process.exitCode = EXIT.usage } else if (error instanceof UsageError) { console.error(`${error.message}${/kaloko help /.test(error.message) ? '' : `\nkaloko help ${name} shows how to use it.`}`); process.exitCode = EXIT.usage } else if (known) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = exitCodeOf(error) } else {
       console.error(`Kaloko stopped on an unexpected error (a bug on our side). Send the output below to ${SUPPORT_EMAIL} with the command you ran.`)
       throw error
     }

package/src/lib/cli-args.mjs

@@ -136,13 +136,76 @@ export function closest (word, words) {
 
 /**
  * Options `args` has that `name` does not take: a UsageError for commands in STRICT (nothing has happened yet), a
- * list of warning lines for the others (they run as before, without the unknown option).
+ * list of warning lines for the others (they run as before, without the unknown option). `update` is the line that
+ * says a newer kaloko takes the options in `newer`: those get no "Did you mean", and the line comes last (as the next
+ * step of the error, or as the last warning).
  */
-export function checkOptions (help, name, args) {
+export function checkOptions (help, name, args, { update = null, newer = [] } = {}) {
   const known = optionsFor(help, name)
-  const unknown = Object.keys(args).filter((k) => k !== '_' && k !== '' && !known.has(k))
+  const unknown = unknownOptions(help, name, args)
   if (!unknown.length) return []
-  const lines = unknown.map((k) => { const guess = closest(k, [...known]); return `kaloko ${name} does not take --${k}.${guess ? ` Did you mean --${guess}?` : ''}` })
-  if (STRICT.has(name) || STRICT.has(`${name} ${args._?.[0]}`)) throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
-  return lines.map((l) => `! ${l} It is ignored (kaloko help ${name} lists the options).`)
+  const lines = unknown.map((k) => {
+    if (update && newer.includes(k)) return `kaloko ${name} does not take --${k} in this kaloko.`
+    const guess = closest(k, [...known]); return `kaloko ${name} does not take --${k}.${guess ? ` Did you mean --${guess}?` : ''}`
+  })
+  if (STRICT.has(name) || STRICT.has(`${name} ${args._?.[0]}`)) {
+    if (update) throw Object.assign(new UsageError(`${lines.join('\n')}\nNothing was changed.`, { next: update }), { update: true })
+    throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
+  }
+  return [...lines.map((l) => `! ${l} It is ignored (kaloko help ${name} lists the options).`), ...(update ? [update] : [])]
+}
+
+/** The usage part of an entry's first line: what follows "  <name> " up to the description column. */
+const usageOf = (entry, name) => entry.lines[0].slice(name.length + 3).split(/\s{3,}/)[0]
+
+/** The help entries that start with `name` (not the ones that only mention it after " | "). */
+const ownEntries = (help, name) => helpEntries(help).filter((e) => e.lines[0].startsWith(`  ${name} `) || e.lines[0] === `  ${name}`)
+
+/**
+ * The sub-commands of a command with the options each one's help names: "tokens pull|push|check|validate",
+ * "export run …", and after the first one the words after " | " ("video list | trace --step <id> | tools").
+ */
+export function subcommandsFor (help, name) {
+  const subs = new Map()
+  for (const e of ownEntries(help, name)) {
+    const [first, ...rest] = usageOf(e, name).split(' | ')
+    const words = first.match(/^([a-z][a-z-]*(?:\|[a-z][a-z-]*)*)(?=\s|$)/)?.[1].split('|') || []
+    if (words.length) for (const seg of rest) { const w = seg.match(/^([a-z][a-z-]*)(?=\s|$)/)?.[1]; if (w) words.push(w) }
+    const flags = e.lines.join('\n').match(/--[a-z][a-z0-9-]*/g) || []
+    for (const w of words) { if (!subs.has(w)) subs.set(w, new Set()); for (const f of flags) subs.get(w).add(f.slice(2)) }
+  }
+  return subs
+}
+
+/**
+ * Whether a command takes a word of its own after its name other than a sub-command: "validate <scenario.yml>",
+ * "spec [step]", "release [<version>]". "projects [--json]" and "doctor [--json] [--fix]" take none.
+ */
+export function takesWords (help, name) {
+  return ownEntries(help, name).some((e) => { const u = usageOf(e, name); return !/^[a-z]/.test(u) && /(^|[\s[(])<|\[(?!-)/.test(u) })
+}
+
+/**
+ * The commands of this kaloko as data (kaloko help --json, and the service's /cli/latest.json): each documented
+ * command with its documented and common options and its sub-commands with theirs. Hidden aliases stay out.
+ */
+export function catalogue (help, names, version) {
+  const commands = {}
+  for (const name of [...names].sort()) {
+    const entries = helpEntries(help).filter((e) => e.commands.has(name))
+    if (!entries.length && name !== 'help' && name !== 'version') continue
+    const named = entries.flatMap((e) => e.lines.join('\n').match(/--[a-z][a-z0-9-]*/g) || []).map((f) => f.slice(2))
+    const subs = [...subcommandsFor(help, name)].sort(([a], [b]) => a.localeCompare(b))
+    commands[name] = {
+      flags: [...new Set([...named, ...COMMON_OPTIONS])].sort(),
+      ...(subs.length ? { subcommands: Object.fromEntries(subs.map(([s, f]) => [s, { flags: [...f].sort() }])) } : {})
+    }
+  }
+  return { version, commands }
+}
+
+/** The options in `args` that `name` does not take. */
+export function unknownOptions (help, name, args) {
+  const known = optionsFor(help, name)
+  return Object.keys(args).filter((k) => k !== '_' && k !== '' && !known.has(k))
 }

package/src/lib/doctor.mjs

@@ -15,6 +15,8 @@ import { visionSettings, VISION_WEIGHT } from './vision-core.mjs'
 import { serviceUrl } from './service.mjs'
 import { videoTools, recordingChecks } from './video.mjs'
 import { productChecks } from './changelog.mjs'
+import { versionCheck } from './update-check.mjs'
+import { packageRoot } from './schema.mjs'
 
 const portFree = (port) => new Promise((done) => {
   const s = createServer().once('error', () => done(false)).once('listening', () => s.close(() => done(true)))
@@ -43,8 +45,10 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {boolean} [o.fix] repair what can be repaired here: install missing Playwright browsers, create the run and
  *   scenario folders, write org: from the token into the config, ask macOS for permissions
  * @param {Function} [o.installBrowser] async (engine) => void — installs a Playwright engine (--fix)
+ * @param {Function} [o.newest] async () => { detail } — this kaloko and the newest one (default: the service's
+ *   /cli/latest.json, cached for a day; never a failure)
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [], installBrowser = defaultInstall, legacy = [] }) {
+export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [], installBrowser = defaultInstall, legacy = [], newest = null }) {
   const checks = []
   const add = (name, ok, detail = '', hint = '', fixed = null) => checks.push({ name, ok, detail, hint, ...(fixed ? { fixed } : {}) })
   // --fix: install an engine, then look again; returns the version or throws what the install said
@@ -52,6 +56,12 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
 
   const major = Number(process.versions.node.split('.')[0])
   add('node', major >= 20, `Node ${process.versions.node}`, major >= 20 ? '' : 'Kaloko needs Node 20 or newer.')
+  // this kaloko, and the newest released one when it is newer: information, never a failure
+  try {
+    const installed = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
+    const v = newest ? await newest(installed) : await versionCheck({ installed, config, env: { ...process.env, ...env }, fetchImpl, root: packageRoot })
+    add('kaloko', true, v.detail)
+  } catch {}
 
   add('config', true, `${file || `${root}/kaloko.config.yml`} · org ${config.org || '—'} · ${Object.keys(config.environments || {}).length} environments`)
   // names from before the rename that still work (legacy.mjs): listed with their new names, never a failure

package/src/lib/update-check.mjs

@@ -0,0 +1,132 @@
+// "Is this in a newer kaloko?": when someone types a command, sub-command or option this kaloko does not know, the
+// commands of the newest released kaloko (GET <service>/cli/latest.json, cached for a day) say whether updating
+// helps. A line says so only when that version is newer than this one and has exactly what was typed; offline, a
+// slow answer, an odd answer or KALOKO_NO_UPDATE_CHECK=1 mean no line, never an error or a wait over 1.5 s.
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname, sep } from 'node:path'
+import { serviceUrl } from './service.mjs'
+import { compareVersions } from './changelog-core.mjs'
+
+export const CATALOGUE_PATH = '/cli/latest.json'
+export const TIMEOUT_MS = 1500
+const FRESH_MS = 24 * 3600e3 // a catalogue read from the service
+const RETRY_MS = 3600e3 // no answer: ask again after an hour, not on every typo
+const NAME = /^[a-z][a-z0-9-]*$/
+
+/** Off with KALOKO_NO_UPDATE_CHECK=1 (or NO_UPDATE_NOTIFIER, the npm convention) and with --offline. */
+export const updateCheckOff = (env = process.env, args = {}) => !!(truthy(env.KALOKO_NO_UPDATE_CHECK) || truthy(env.NO_UPDATE_NOTIFIER) || args.offline)
+const truthy = (v) => v !== undefined && v !== '' && v !== '0' && v !== 'false'
+
+/** Where the catalogue is kept: KALOKO_CACHE_DIR, else the OS cache folder (~/.cache/kaloko, %LOCALAPPDATA%\kaloko). */
+export function cacheDir (env = process.env, os = process.platform) {
+  if (env.KALOKO_CACHE_DIR) return env.KALOKO_CACHE_DIR
+  if (os === 'win32' && env.LOCALAPPDATA) return join(env.LOCALAPPDATA, 'kaloko', 'cache')
+  return join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'kaloko')
+}
+
+/** A catalogue as the service sends it, or null when it is not one: { version, commands: { name: { flags, subcommands } } }. */
+export function validCatalogue (c) {
+  if (!c || typeof c !== 'object' || typeof c.version !== 'string' || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(c.version)) return null
+  if (!c.commands || typeof c.commands !== 'object' || Array.isArray(c.commands)) return null
+  const names = (list) => Array.isArray(list) && list.every((f) => typeof f === 'string' && NAME.test(f))
+  for (const [name, cmd] of Object.entries(c.commands)) {
+    if (!NAME.test(name) || !cmd || !names(cmd.flags)) return null
+    if (cmd.subcommands !== undefined && (typeof cmd.subcommands !== 'object' || !Object.entries(cmd.subcommands).every(([s, v]) => NAME.test(s) && v && names(v.flags)))) return null
+  }
+  return c
+}
+
+/**
+ * The newest kaloko's catalogue: from the cache while it is fresh, else from the service (one try, `timeout` ms).
+ * Null when the check is off or nothing usable came back.
+ */
+export async function newestCatalogue ({ config = {}, env = process.env, fetchImpl = fetch, now = Date.now(), timeout = TIMEOUT_MS, args = {} } = {}) {
+  if (updateCheckOff(env, args)) return null
+  let url
+  try { url = `${serviceUrl(config, env)}${CATALOGUE_PATH}` } catch { return null }
+  const file = join(cacheDir(env), 'cli-latest.json')
+  let cached = null
+  try { cached = JSON.parse(await readFile(file, 'utf8')) } catch {}
+  if (cached?.url === url && typeof cached.fetched_at === 'number' && cached.fetched_at <= now) {
+    const age = now - cached.fetched_at
+    if (cached.catalogue && age < FRESH_MS) return validCatalogue(cached.catalogue)
+    if (!cached.catalogue && age < RETRY_MS) return null
+  }
+  let catalogue = null
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(), timeout)
+  try {
+    const res = await fetchImpl(url, { signal: ctl.signal, redirect: 'follow', headers: { Accept: 'application/json', 'User-Agent': 'kaloko-cli' } })
+    if (res.ok) catalogue = validCatalogue(JSON.parse(await res.text()))
+  } catch {} finally { clearTimeout(timer) }
+  try { await mkdir(dirname(file), { recursive: true }); await writeFile(file, JSON.stringify({ url, fetched_at: now, catalogue })) } catch {}
+  return catalogue
+}
+
+/**
+ * What a newer kaloko has of what was typed, or null: `catalogue` must be newer than `installed` and have the command,
+ * the sub-command or the options exactly. { words: 'projects create', version } or { words: 'init --site', version }.
+ */
+export function newerHas (catalogue, installed, { command, sub = null, options = [] }) {
+  if (!validCatalogue(catalogue) || !installed || compareVersions(catalogue.version, installed) <= 0) return null
+  const cmd = Object.hasOwn(catalogue.commands, command) ? catalogue.commands[command] : null
+  if (!cmd) return null
+  const out = (words) => ({ words: `${command} ${words}`.trim(), version: catalogue.version })
+  if (sub && cmd.subcommands && Object.hasOwn(cmd.subcommands, sub)) return out(sub)
+  const known = options.filter((o) => cmd.flags.includes(o))
+  if (known.length) return { ...out(known.map((o) => `--${o}`).join(' ')), options: known }
+  if (!sub && !options.length) return out('')
+  return null
+}
+
+/**
+ * How this project gets a newer kaloko: the package manager's add command when package.json lists kaloko (lockfile
+ * decides npm, pnpm, yarn or bun), npx kaloko@latest when this kaloko runs from the npx cache, else both.
+ */
+export function installCommand ({ cwd = process.cwd(), root = null, words = '' } = {}) {
+  const npx = `npx kaloko@latest${words ? ` ${words}` : ''}`
+  if (root && root.split(sep).includes('_npx')) return { run: npx }
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    const pkg = join(dir, 'package.json')
+    if (existsSync(pkg)) {
+      let p = null
+      try { p = JSON.parse(readFileSync(pkg, 'utf8')) } catch {}
+      const dev = !!p?.devDependencies?.kaloko
+      if (!dev && !p?.dependencies?.kaloko) break
+      const d = dev ? ' -D' : ''
+      const pm = existsSync(join(dir, 'pnpm-lock.yaml')) ? `pnpm add${d}` : existsSync(join(dir, 'yarn.lock')) ? `yarn add${d}` : existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock')) ? `bun add${dev ? ' -d' : ''}` : `npm i${d}`
+      return { update: `${pm} kaloko@latest` }
+    }
+    if (dirname(dir) === dir) break
+  }
+  return { update: 'npm i -D kaloko@latest', run: npx }
+}
+
+/** "kaloko projects create is in kaloko 0.16.0 (you have 0.15.0). Update: npm i -D kaloko@latest" */
+export function updateLine ({ words, version }, installed, how) {
+  const what = `kaloko ${words} ${/ --\S+ --/.test(` ${words}`) ? 'are' : 'is'} in kaloko ${version} (you have ${installed}).`
+  if (how.update && how.run) return `${what} Update: ${how.update} (or run ${how.run})`
+  return how.update ? `${what} Update: ${how.update}` : `${what} Run it with ${how.run}`
+}
+
+/**
+ * For something this kaloko does not know (`typed`: { command, sub, options }), or null: the cached or fetched
+ * catalogue must be newer and have it. { line, update: line, newer: [the options it takes] }.
+ */
+export async function updateHint (typed, { installed, config = {}, env = process.env, fetchImpl = fetch, cwd = process.cwd(), root = null, args = {}, now } = {}) {
+  const catalogue = await newestCatalogue({ config, env, fetchImpl, args, ...(now ? { now } : {}) })
+  const has = catalogue && newerHas(catalogue, installed, typed)
+  if (!has) return null
+  const line = updateLine(has, installed, installCommand({ cwd, root, words: has.words }))
+  return { line, update: line, newer: has.options || [] }
+}
+
+/** The doctor line: this version, and the newest one when it is newer (from the same cached catalogue). */
+export async function versionCheck ({ installed, config = {}, env = process.env, fetchImpl = fetch, cwd = process.cwd(), root = null }) {
+  const catalogue = await newestCatalogue({ config, env, fetchImpl })
+  if (!catalogue || compareVersions(catalogue.version, installed) <= 0) return { installed, newest: catalogue?.version || null, newer: false, detail: catalogue ? `${installed} (the newest)` : installed }
+  const how = installCommand({ cwd, root })
+  return { installed, newest: catalogue.version, newer: true, detail: `${installed} · a newer kaloko is available: ${catalogue.version} (${how.update ? how.update : how.run})` }
+}