@wevion/cli 1.0.2 → 1.0.3

package/src/index.mjs

@@ -12,7 +12,6 @@
 import { parseArgs } from 'node:util'
 import {
   chmodSync,
-  existsSync,
   mkdirSync,
   readFileSync,
   realpathSync,
@@ -24,6 +23,7 @@ import { homedir } from 'node:os'
 import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
+import { spawn } from 'node:child_process'
 
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete']
 const JSON_CONTENT_TYPE = 'application/json'
@@ -31,6 +31,7 @@ const SUPPORTED_AUTH_SCHEMES = new Set(['apiKeyAuth'])
 // ponytail: hardcoded prod default; stage via --base-url / WEVION_BASE_URL / config.
 const DEFAULT_BASE_URL = 'https://api.wevion.ai'
 const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_SPEC_TIMEOUT_MS = 3000
 
 // ~/.config/wevion/config.json (honours XDG_CONFIG_HOME). Stores { apiKey, baseUrl }.
 export function configPath(env = process.env, platform = process.platform) {
@@ -162,6 +163,188 @@ function logout() {
   return 0
 }
 
+// ── Update notifier ──────────────────────────────────────────────
+// Zero-dep: a detached background process refreshes a cached "latest" at most
+// once/day; the notice (stderr only, never stdout) shows on the next run.
+
+function pkgInfo() {
+  try {
+    const p = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
+    const { name, version } = JSON.parse(readFileSync(p, 'utf8'))
+    return { name, version }
+  } catch {
+    return {}
+  }
+}
+
+export function updateCheckPath(env = process.env, platform = process.platform) {
+  return join(dirname(configPath(env, platform)), 'update-check.json')
+}
+
+function parseSemver(v) {
+  const match = String(v).match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/)
+  if (!match) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : [],
+  }
+}
+
+function comparePrerelease(a, b) {
+  if (!a.length && !b.length) return 0
+  if (!a.length) return 1
+  if (!b.length) return -1
+  const len = Math.max(a.length, b.length)
+  for (let i = 0; i < len; i++) {
+    const ai = a[i]
+    const bi = b[i]
+    if (ai == null) return -1
+    if (bi == null) return 1
+    const an = /^\d+$/.test(ai) ? Number(ai) : null
+    const bn = /^\d+$/.test(bi) ? Number(bi) : null
+    if (an !== null && bn !== null && an !== bn) return an - bn
+    if (an !== null && bn === null) return -1
+    if (an === null && bn !== null) return 1
+    if (an === null && bn === null && ai !== bi) return ai < bi ? -1 : 1
+  }
+  return 0
+}
+
+// Minimal semver compare: numeric core, prerelease lower than release.
+export function compareVersions(a, b) {
+  const pa = parseSemver(a)
+  const pb = parseSemver(b)
+  if (!pa || !pb) return 0
+  return pa.major - pb.major || pa.minor - pb.minor || pa.patch - pb.patch || comparePrerelease(pa.prerelease, pb.prerelease)
+}
+
+export function isSafeVersion(v) {
+  return typeof v === 'string' && /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(v)
+}
+
+export function updateCheckEnv(env = process.env) {
+  const allowlist = [
+    'HOME',
+    'USERPROFILE',
+    'APPDATA',
+    'XDG_CONFIG_HOME',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'NO_PROXY',
+    'http_proxy',
+    'https_proxy',
+    'no_proxy',
+    'NODE_EXTRA_CA_CERTS',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'SystemRoot',
+    'WINDIR',
+    'TEMP',
+    'TMP',
+  ]
+  return Object.fromEntries(allowlist.filter((key) => env[key]).map((key) => [key, env[key]]))
+}
+
+function readUpdateCache() {
+  try {
+    const cache = JSON.parse(readFileSync(updateCheckPath(), 'utf8'))
+    return cache && typeof cache === 'object' ? cache : {}
+  } catch {
+    return {}
+  }
+}
+
+function writePrivateJsonFile(p, payload) {
+  const dir = dirname(p)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  try {
+    chmodSync(dir, 0o700)
+  } catch {
+    /* best effort on platforms without POSIX modes */
+  }
+  const tmp = `${p}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, JSON.stringify(payload) + '\n', { mode: 0o600 })
+    renameSync(tmp, p)
+    try {
+      chmodSync(p, 0o600)
+    } catch {
+      /* best effort on platforms without POSIX modes */
+    }
+  } catch (err) {
+    try {
+      rmSync(tmp, { force: true })
+    } catch {
+      /* ignore cleanup failure */
+    }
+    throw err
+  }
+}
+
+function writeUpdateCache(cache) {
+  writePrivateJsonFile(updateCheckPath(), cache)
+}
+
+// Hidden `__update-check` subcommand: fetch latest from npm, cache it. Best-effort.
+async function refreshUpdateCache() {
+  const cache = readUpdateCache()
+  try {
+    const { name } = pkgInfo()
+    if (!name) return 0
+    const ctrl = new AbortController()
+    const t = setTimeout(() => ctrl.abort(), 5000)
+    const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}`, {
+      headers: { accept: 'application/vnd.npm.install-v1+json' },
+      signal: ctrl.signal,
+    }).finally(() => clearTimeout(t))
+    if (!res.ok) return 0
+    const data = await res.json()
+    const latest = data?.['dist-tags']?.latest
+    if (isSafeVersion(latest)) cache.latest = latest
+  } catch {
+    /* offline / registry down — never surface */
+  } finally {
+    try {
+      writeUpdateCache({ ...cache, lastCheck: Date.now() })
+    } catch {
+      /* cache is best-effort */
+    }
+  }
+  return 0
+}
+
+// Print an update notice from cache (if any) and kick off a background refresh
+// when the cache is stale. Must never block or throw, and never write to stdout.
+function notifyUpdate() {
+  try {
+    if (process.env.NO_UPDATE_NOTIFIER || process.env.CI || !process.stdout.isTTY || !process.stderr.isTTY) return
+    const { name, version } = pkgInfo()
+    if (!name || !version) return
+    const cache = readUpdateCache()
+    if (isSafeVersion(cache.latest) && compareVersions(cache.latest, version) > 0) {
+      process.stderr.write(
+        `\nUpdate available for ${name}: ${version} → ${cache.latest}\n` +
+          `Run: npm i -g ${name}@latest\n\n`,
+      )
+    }
+    const DAY_MS = 86_400_000
+    const lastCheck = Number(cache.lastCheck)
+    if (!Number.isFinite(lastCheck) || Date.now() - lastCheck > DAY_MS) {
+      const child = spawn(process.execPath, [fileURLToPath(import.meta.url), '__update-check'], {
+        detached: true,
+        stdio: 'ignore',
+        env: updateCheckEnv(),
+        windowsHide: true,
+      })
+      child.unref()
+    }
+  } catch {
+    /* never break the CLI over an update check */
+  }
+}
+
 export function kebab(s) {
   return s
     .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
@@ -368,15 +551,139 @@ function validateSpec(spec, source) {
   return spec
 }
 
-function loadSpec(baseUrl) {
-  // Prefer the bundled snapshot (offline help, reproducible per release).
+// The API changes often (with breaking changes), so the live spec is the source
+// of truth: commands/params always match the API. The bundled snapshot is only
+// an offline fallback. A short on-disk cache avoids re-downloading the (large)
+// spec on every command.
+const CLI_VERSION_HEADER = 'x-wevion-cli-version'
+const MIN_CLI_VERSION_HEADER = 'x-wevion-min-cli-version'
+
+class UpgradeRequiredError extends Error {}
+
+function cliVersion() {
+  return pkgInfo().version || '0.0.0'
+}
+
+function specCachePath(env = process.env, platform = process.platform) {
+  return join(dirname(configPath(env, platform)), 'spec-cache.json')
+}
+
+function specTtlMs(env = process.env) {
+  const parsed = Number(env.WEVION_SPEC_TTL_MS)
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 300_000 // 5 min
+}
+
+function specTimeoutMs(env = process.env) {
+  const parsed = Number(env.WEVION_SPEC_TIMEOUT_MS)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_SPEC_TIMEOUT_MS
+}
+
+function specSignalFromEnv(env = process.env) {
+  return AbortSignal.timeout(specTimeoutMs(env))
+}
+
+// Extract the server's upgrade message (426 body), or a sensible default.
+export function upgradeMessage(text, minVersion) {
+  try {
+    const j = JSON.parse(text)
+    if (j && typeof j.message === 'string') return j.message
+  } catch {
+    /* not JSON */
+  }
+  return (
+    `This @wevion/cli version (${cliVersion()}) is no longer supported.` +
+    `${minVersion ? ` Minimum: ${minVersion}.` : ''} Run: npm i -g @wevion/cli@latest`
+  )
+}
+
+function readSpecCache(cachePath) {
+  try {
+    const cache = JSON.parse(readFileSync(cachePath, 'utf8'))
+    return cache && typeof cache === 'object' ? cache : null
+  } catch {
+    return null
+  }
+}
+
+function validCachedSpec(cache, baseUrl, cachePath) {
+  if (!cache || cache.baseUrl !== baseUrl || !Number.isFinite(Number(cache.fetchedAt))) return null
+  try {
+    return validateSpec(cache.spec, cachePath)
+  } catch {
+    return null
+  }
+}
+
+async function assertCliVersionSupported(baseUrl) {
+  const url = `${baseUrl.replace(/\/$/, '')}/docs/json`
+  try {
+    const res = await fetch(url, {
+      method: 'HEAD',
+      headers: { [CLI_VERSION_HEADER]: cliVersion() },
+      signal: specSignalFromEnv(),
+    })
+    if (res.status === 426) {
+      throw new UpgradeRequiredError(upgradeMessage('', res.headers.get(MIN_CLI_VERSION_HEADER)))
+    }
+  } catch (err) {
+    if (err instanceof UpgradeRequiredError) throw err
+    /* A failed probe is not fatal; the cached spec still preserves offline list/help. */
+  }
+}
+
+function fallbackSpec(err, cacheSpec) {
+  if (cacheSpec) {
+    process.stderr.write(`warning: API spec unreachable, using cached copy (${err.message})\n`)
+    return { spec: cacheSpec, source: 'stale-cache' }
+  }
   const bundled = join(dirname(fileURLToPath(import.meta.url)), '..', 'openapi.json')
   try {
-    return { spec: validateSpec(JSON.parse(readFileSync(bundled, 'utf8')), bundled), source: 'bundled' }
+    const spec = validateSpec(JSON.parse(readFileSync(bundled, 'utf8')), bundled)
+    process.stderr.write(`warning: API spec unreachable, using bundled snapshot (${err.message})\n`)
+    return { spec, source: 'bundled' }
+  } catch {
+    throw err
+  }
+}
+
+async function resolveSpec(baseUrl) {
+  const cachePath = specCachePath()
+  const cache = readSpecCache(cachePath)
+  const cacheSpec = validCachedSpec(cache, baseUrl, cachePath)
+  if (cacheSpec && Date.now() - Number(cache.fetchedAt) < specTtlMs()) {
+    await assertCliVersionSupported(baseUrl)
+    return { spec: cacheSpec, source: 'cache' }
+  }
+
+  const url = `${baseUrl.replace(/\/$/, '')}/docs/json`
+  let res
+  let text
+  try {
+    res = await fetch(url, {
+      headers: { [CLI_VERSION_HEADER]: cliVersion() },
+      signal: specSignalFromEnv(),
+    })
+    text = await res.text()
+  } catch (err) {
+    return fallbackSpec(err, cacheSpec)
+  }
+
+  if (res.status === 426) throw new UpgradeRequiredError(upgradeMessage(text, res.headers.get(MIN_CLI_VERSION_HEADER)))
+  if (!res.ok) return fallbackSpec(new Error(`cannot fetch spec from ${url}: ${res.status}`), cacheSpec)
+
+  let spec
+  try {
+    spec = validateSpec(JSON.parse(text), url)
   } catch (err) {
-    if (existsSync(bundled)) throw err
-    return { source: 'remote', url: `${baseUrl.replace(/\/$/, '')}/docs/json` }
+    return fallbackSpec(new Error(`invalid OpenAPI spec from ${url}: ${err.message}`), cacheSpec)
   }
+
+  try {
+    writePrivateJsonFile(cachePath, { fetchedAt: Date.now(), baseUrl, spec })
+  } catch {
+    /* cache is best-effort */
+  }
+  return { spec, source: 'live' }
 }
 
 function timeoutMs(env = process.env) {
@@ -388,6 +695,37 @@ function signalFromEnv(env = process.env) {
   return AbortSignal.timeout(timeoutMs(env))
 }
 
+function isLoopbackHostname(hostname) {
+  const h = hostname.toLowerCase()
+  return h === 'localhost' || h === '::1' || h === '[::1]' || /^127\./.test(h)
+}
+
+function assertSafeAuthenticatedUrl(rawUrl) {
+  const url = new URL(rawUrl)
+  if (url.username || url.password) {
+    throw new Error('base URL must not include credentials')
+  }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHostname(url.hostname))) {
+    throw new Error('refusing to send API key to a non-HTTPS base URL')
+  }
+}
+
+function redactUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl)
+    if (url.username) url.username = '[REDACTED]'
+    if (url.password) url.password = '[REDACTED]'
+    for (const key of [...url.searchParams.keys()]) {
+      if (/token|secret|password|api[-_]?key|authorization|code/i.test(key)) {
+        url.searchParams.set(key, '[REDACTED]')
+      }
+    }
+    return url.toString()
+  } catch {
+    return rawUrl
+  }
+}
+
 function resolveBaseUrl(argv, config, env = process.env) {
   const globalOptions = { 'base-url': { type: 'string' } }
   try {
@@ -397,12 +735,127 @@ function resolveBaseUrl(argv, config, env = process.env) {
       allowPositionals: true,
       strict: false,
     })
-    return values['base-url'] || env.WEVION_BASE_URL || config.baseUrl || DEFAULT_BASE_URL
+    return (typeof values['base-url'] === 'string' && values['base-url']) || env.WEVION_BASE_URL || config.baseUrl || DEFAULT_BASE_URL
   } catch {
     return env.WEVION_BASE_URL || config.baseUrl || DEFAULT_BASE_URL
   }
 }
 
+function stripLeadingGlobalOptions(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--base-url') {
+      i += 1
+      continue
+    }
+    if (arg.startsWith('--base-url=')) continue
+    return argv.slice(i)
+  }
+  return []
+}
+
+function parseJsonOutputFlag(args) {
+  const { values } = parseArgs({
+    args,
+    options: { json: { type: 'boolean' }, 'base-url': { type: 'string' } },
+    allowPositionals: false,
+  })
+  return Boolean(values.json)
+}
+
+function schemaMeta(schema = {}) {
+  return {
+    type: schema.type || 'string',
+    ...(schema.format ? { format: schema.format } : {}),
+    ...(schema.default !== undefined ? { default: schema.default } : {}),
+    ...(schema.enum ? { enum: schema.enum } : {}),
+    ...(schema.description ? { description: schema.description } : {}),
+    ...(schema.items ? { items: schemaMeta(schema.items) } : {}),
+  }
+}
+
+// Machine-readable view of a command, for agents (list --json / help --json).
+export function opToJson(op) {
+  return {
+    command: op.id,
+    method: op.method,
+    path: op.path,
+    summary: op.summary,
+    tags: op.tags,
+    params: op.params
+      .filter((p) => p.in === 'path' || p.in === 'query' || p.in === 'header')
+      .map((p) => ({
+        flag: `--${p.name}`,
+        in: p.in,
+        required: Boolean(p.required),
+        ...(p.description && !p.schema?.description ? { description: p.description } : {}),
+        ...schemaMeta(p.schema),
+        array: p.schema?.type === 'array',
+      })),
+    body: op.bodyFields.length
+      ? {
+          flags: op.bodyFields.map((f) => ({
+            flag: `--${f.flag}`,
+            field: f.name,
+            required: op.bodyRequired.includes(f.name),
+            ...schemaMeta(f.schema),
+          })),
+          raw: "--json '<json>'",
+        }
+      : null,
+    ...(op.unsupported ? { unsupported: op.unsupported } : {}),
+  }
+}
+
+// One-shot primer so an LLM/agent with no Wevion knowledge can use the CLI.
+function printAgent() {
+  const { name = '@wevion/cli', version = '?' } = pkgInfo()
+  process.stdout.write(`# ${name} — agent guide (v${version})
+
+Command-line access to the Wevion advertising API. Everything you need is here;
+no prior Wevion knowledge required.
+
+## Model
+- Every command maps to ONE Wevion REST endpoint. The command id is the
+  kebab-case operationId, e.g. \`get-api-v1-ad-accounts\` -> GET /api/v1/ad-accounts.
+- Commands are derived LIVE from the API's OpenAPI spec, so they always match
+  the current API.
+
+## Auth
+- Set the API key: \`WEVION_API_KEY=<key>\` (env) or run \`wevion login\`.
+- Create a key in the Wevion app under Settings → API keys (permission-scoped).
+
+## Discover (machine-readable)
+- \`wevion list --json\`             → all commands: [{command, method, path, summary, tags, params, body}]
+- \`wevion help <command> --json\`   → one command's exact params/body schema
+
+## Invoke
+- Path, query and supported header params are flags using the exact OpenAPI
+  name. Names can be camelCase or snake_case (\`--accountId\`, \`--ad_id\`,
+  \`--folderId\`, \`--limit\`). Get exact names from \`help <command> --json\`;
+  do not guess.
+- Array params: repeat the flag or pass a comma-separated list.
+- Request body: pass fields as flags, or the whole JSON via \`--json '<json>'\`.
+
+## Output & exit codes
+- Success: JSON on stdout, exit 0.
+- API error: request line + JSON body on stderr, exit 1.
+- Usage error (unknown command / missing required flag / no API key): exit 2.
+- Upgrade required (CLI too old for the API): message on stderr, exit 3
+  → run \`npm i -g ${name}@latest\`.
+
+## Config
+- Base URL: \`--base-url\` | \`WEVION_BASE_URL\` | stored login config |
+  default ${DEFAULT_BASE_URL} (staging: https://api-stage.wevion.ai).
+
+## Typical flow
+1. wevion agent                        # this guide
+2. wevion list --json                  # find the command
+3. wevion help <command> --json        # get its params
+4. wevion <command> --flag value ...   # run it; parse JSON from stdout
+`)
+}
+
 function printList(ops) {
   const byTag = new Map()
   for (const op of ops.values()) {
@@ -435,33 +888,55 @@ function printHelp(op) {
 }
 
 async function main(argv) {
-  const [cmd, ...rest] = argv
+  const commandArgv = stripLeadingGlobalOptions(argv)
+  const [cmd, ...rest] = commandArgv
 
+  if (cmd === '__update-check') return refreshUpdateCache()
   if (cmd === 'login') return login(rest)
   if (cmd === 'logout') return logout()
+  if (cmd === 'agent') {
+    printAgent()
+    return 0
+  }
 
   const config = readConfig()
   const baseUrl = resolveBaseUrl(argv, config)
 
-  const loaded = loadSpec(baseUrl)
-  const spec =
-    loaded.spec ||
-    (await fetch(loaded.url, { signal: signalFromEnv() }).then((r) => {
-      if (!r.ok) throw new Error(`cannot fetch spec from ${loaded.url}: ${r.status}`)
-      return r.json().then((json) => validateSpec(json, loaded.url))
-    }))
+  const { spec, source } = await resolveSpec(baseUrl)
   const ops = listOperations(spec)
 
   if (!cmd || cmd === 'list' || cmd === '--help' || cmd === '-h') {
-    process.stdout.write(`Wevion CLI — ${ops.size} commands (${loaded.source} spec)\n`)
+    let asJson = false
+    try {
+      asJson = parseJsonOutputFlag(rest)
+    } catch (err) {
+      return fail(err.message)
+    }
+    if (asJson) {
+      process.stdout.write(`${JSON.stringify([...ops.values()].map(opToJson), null, 2)}\n`)
+      return 0
+    }
+    process.stdout.write(`Wevion CLI — ${ops.size} commands (${source} spec)\n`)
     printList(ops)
     process.stdout.write(`\nUsage: wevion <command> [--param value ...]\n`)
-    process.stdout.write(`       wevion login | logout | help <command>\n`)
+    process.stdout.write(`       wevion agent                  # guide for LLMs/agents\n`)
+    process.stdout.write(`       wevion list --json | help <command> [--json]\n`)
+    process.stdout.write(`       wevion login | logout\n`)
     return 0
   }
   if (cmd === 'help') {
     const op = ops.get(rest[0])
     if (!op) return fail(`unknown command: ${rest[0] || '(none)'}`)
+    let asJson = false
+    try {
+      asJson = parseJsonOutputFlag(rest.slice(1))
+    } catch (err) {
+      return fail(err.message)
+    }
+    if (asJson) {
+      process.stdout.write(`${JSON.stringify(opToJson(op), null, 2)}\n`)
+      return 0
+    }
     printHelp(op)
     return 0
   }
@@ -469,32 +944,62 @@ async function main(argv) {
   const op = ops.get(cmd)
   if (!op) return fail(`unknown command: ${cmd} (try "wevion list")`)
 
-  const { values } = parseArgs({
-    args: rest,
-    options: buildParseOptions(op),
-    allowPositionals: false,
-  })
+  let values
+  try {
+    ;({ values } = parseArgs({
+      args: rest,
+      options: buildParseOptions(op),
+      allowPositionals: false,
+    }))
+  } catch (err) {
+    return fail(err.message)
+  }
 
   const apiKey = resolveApiKey(process.env, config)
   if (!apiKey) return fail('no API key — run "wevion login" or set WEVION_API_KEY')
 
-  const req = buildRequest(op, values, values['base-url'] || baseUrl)
+  let req
+  try {
+    req = buildRequest(op, values, values['base-url'] || baseUrl)
+    assertSafeAuthenticatedUrl(req.url)
+  } catch (err) {
+    return fail(err.message)
+  }
   const res = await fetch(req.url, {
     method: req.method,
     headers: {
       ...req.headers,
       'x-api-key': apiKey,
+      [CLI_VERSION_HEADER]: cliVersion(),
       ...(req.body ? { 'content-type': 'application/json' } : {}),
     },
     body: req.body,
     signal: signalFromEnv(),
   })
-  const text = await res.text()
+  const bytes = Buffer.from(await res.arrayBuffer())
+  const text = bytes.toString('utf8')
+  if (res.status === 426) throw new UpgradeRequiredError(upgradeMessage(text, res.headers.get(MIN_CLI_VERSION_HEADER)))
   if (!res.ok) {
-    process.stderr.write(`${req.method} ${req.url} -> ${res.status}\n`)
+    process.stderr.write(`${req.method} ${redactUrl(req.url)} -> ${res.status}\n`)
     if (text) process.stderr.write(text.endsWith('\n') ? text : text + '\n')
     return 1
   }
+  const contentType = res.headers.get('content-type') || ''
+  if (res.status === 204 || bytes.length === 0) {
+    process.stdout.write(`${JSON.stringify({ ok: true, status: res.status })}\n`)
+    return 0
+  }
+  if (!contentType.includes('application/json')) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, status: res.status, contentType, bodyBase64: bytes.toString('base64') })}\n`,
+    )
+    return 0
+  }
+  try {
+    JSON.parse(text)
+  } catch {
+    throw new Error(`API returned invalid JSON for ${req.method} ${req.url}`)
+  }
   process.stdout.write(text.endsWith('\n') ? text : text + '\n')
   return 0
 }
@@ -515,9 +1020,17 @@ function isExecutedAsBin() {
 
 // Run only when executed as a bin, not when imported by selftest.
 if (isExecutedAsBin()) {
-  main(process.argv.slice(2))
-    .then((code) => process.exit(code))
+  const cliArgs = process.argv.slice(2)
+  main(cliArgs)
+    .then((code) => {
+      if (cliArgs[0] !== '__update-check') notifyUpdate()
+      process.exit(code)
+    })
     .catch((err) => {
+      if (err instanceof UpgradeRequiredError) {
+        process.stderr.write(`\n${err.message}\n\n`)
+        process.exit(3)
+      }
       process.stderr.write(`error: ${err.message}\n`)
       process.exit(1)
     })