@agentscraper-cc/cli 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@agentscraper-cc/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "AgentScraper CLI: live web pages as clean Markdown, text or HTML in your terminal, through the Live Web Data API. The commands follow the live API spec.",
+  "keywords": [
+    "cli",
+    "web-scraping",
+    "markdown",
+    "llm",
+    "ai-agents",
+    "rag",
+    "mcp",
+    "live-web-data",
+    "agentscraper"
+  ],
+  "homepage": "https://agentscraper.cc",
+  "bugs": {
+    "url": "https://github.com/agentscraper-cc/cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentscraper-cc/cli.git"
+  },
+  "license": "MIT",
+  "author": "Teneo Labs Inc.",
+  "type": "module",
+  "bin": {
+    "agentscraper": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "openapi.json",
+    "brand.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "sync-spec": "node scripts/sync-spec.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands.js

@@ -0,0 +1,381 @@
+// @ts-check
+/**
+ * Commands and flags from the OpenAPI document. One command per operation: `x-cli.command`, else the operationId in
+ * kebab case without a leading get/list/create (getContents → contents). Flags come from the operation's parameters
+ * and the request body's properties, nested objects as dotted flags (--text.max-characters). A body field the API
+ * adds tomorrow is a flag tomorrow, without a new CLI release; --data covers anything a flag cannot express.
+ *
+ * Optional hints in the operation's `x-cli` object: command, aliases[], positional (the body property positional
+ * arguments fill), output { items, fields[], heading, errors } for `-o text`, hidden.
+ */
+
+export class UsageError extends Error {}
+
+const METHODS = ["get", "post", "put", "patch", "delete"];
+
+/** fooBar / Foo-Bar / foo_bar → foo-bar */
+export function kebab(/** @type {string} */ s) {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+/** getContents → contents, getAccount → account; without an operationId: post-v1-contents. */
+export function commandName(/** @type {string | undefined} */ operationId, /** @type {string} */ method, /** @type {string} */ path) {
+  if (operationId) return kebab(operationId).replace(/^(get|list|create)-(?=.)/, "");
+  return kebab(`${method} ${path}`);
+}
+
+/** Resolves a local $ref (#/…); anything else is returned as is. */
+export function deref(/** @type {any} */ spec, /** @type {any} */ schema, depth = 0) {
+  if (!schema || typeof schema !== "object" || typeof schema.$ref !== "string" || depth > 20) return schema;
+  if (!schema.$ref.startsWith("#/")) return {};
+  let node = spec;
+  for (const part of schema.$ref.slice(2).split("/")) node = node?.[part.replace(/~1/g, "/").replace(/~0/g, "~")];
+  return deref(spec, node ?? {}, depth + 1);
+}
+
+/**
+ * @typedef {object} Flag
+ * @property {string} name          kebab, dotted for nested body fields
+ * @property {"body" | "header" | "query" | "path"} in
+ * @property {string[]} path        body path, or [parameter name]
+ * @property {"string" | "integer" | "number" | "boolean" | "array" | "json"} kind
+ * @property {string} [itemKind]    array items
+ * @property {boolean} [toggle]     a boolean-or-object field: --x / --no-x plus nested flags
+ * @property {boolean} required
+ * @property {boolean} hidden
+ * @property {string} description
+ * @property {any[]} [enum]
+ * @property {string} [format]
+ */
+
+/**
+ * @typedef {object} Command
+ * @property {string} name
+ * @property {string[]} aliases
+ * @property {string} method
+ * @property {string} path
+ * @property {any} op
+ * @property {any} cli               the x-cli hints ({} without)
+ * @property {Flag[]} flags
+ * @property {string | null} positional  body property filled by positional arguments
+ * @property {boolean} hasBody
+ * @property {string[]} requiredBody
+ * @property {Flag | null} idempotencyKey
+ * @property {boolean} needsAuth
+ */
+
+const typeOf = (/** @type {any} */ s) => {
+  if (!s || typeof s !== "object") return undefined;
+  const t = Array.isArray(s.type) ? s.type.find((/** @type {string} */ x) => x !== "null") : s.type;
+  if (t) return t;
+  if ("const" in s) return typeof s.const === "number" ? (Number.isInteger(s.const) ? "integer" : "number") : typeof s.const;
+  if (Array.isArray(s.enum)) return typeof s.enum[0];
+  return undefined;
+};
+
+const leafKind = (/** @type {string | undefined} */ t) =>
+  t === "string" || t === "integer" || t === "number" || t === "boolean" ? t : "json";
+
+/** Body flags for one property, recursing into objects. */
+function bodyFlags(/** @type {any} */ spec, /** @type {any} */ raw, /** @type {string[]} */ path, /** @type {boolean} */ required, /** @type {Flag[]} */ out) {
+  const s = deref(spec, raw);
+  const name = path.map(kebab).join(".");
+  const description = String(s?.description ?? "").trim();
+  const hidden = s?.deprecated === true;
+  const variants = (s?.anyOf ?? s?.oneOf ?? []).map((/** @type {any} */ v) => deref(spec, v));
+  const object = [s, ...variants].find((v) => typeOf(v) === "object" && v.properties && typeof v.properties === "object");
+  const hasBool = variants.some((/** @type {any} */ v) => typeOf(v) === "boolean");
+
+  if (object) {
+    out.push({ name, in: "body", path, kind: hasBool ? "boolean" : "json", toggle: hasBool, required, hidden: hidden || !hasBool, description });
+    for (const [key, child] of Object.entries(object.properties)) bodyFlags(spec, child, [...path, key], false, out);
+    return;
+  }
+  const t = typeOf(s) ?? (variants.length ? typeOf(variants.find((/** @type {any} */ v) => typeOf(v))) : undefined);
+  if (t === "array") {
+    const items = deref(spec, s.items);
+    out.push({ name, in: "body", path, kind: "array", itemKind: leafKind(typeOf(items)), required, hidden, description, enum: items?.enum, format: items?.format });
+    return;
+  }
+  out.push({ name, in: "body", path, kind: leafKind(t), required, hidden, description, enum: s?.enum ?? ("const" in (s ?? {}) ? [s.const] : undefined), format: s?.format });
+}
+
+/** All commands of a spec, in document order. */
+export function buildCommands(/** @type {any} */ spec) {
+  /** @type {Command[]} */
+  const commands = [];
+  const taken = new Set();
+  for (const [path, rawItem] of Object.entries(spec?.paths ?? {})) {
+    const item = deref(spec, rawItem);
+    if (!item || typeof item !== "object") continue;
+    for (const method of METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== "object") continue;
+      const cli = op["x-cli"] && typeof op["x-cli"] === "object" ? op["x-cli"] : {};
+      if (cli.hidden === true) continue;
+      let name = typeof cli.command === "string" && cli.command ? kebab(cli.command) : commandName(op.operationId, method, path);
+      if (taken.has(name)) name = `${name}-${method}`;
+      taken.add(name);
+      /** @type {string[]} */
+      const aliases = (Array.isArray(cli.aliases) ? cli.aliases : []).map(String).map(kebab).filter((/** @type {string} */ a) => a && !taken.has(a));
+      aliases.forEach((a) => taken.add(a));
+
+      /** @type {Flag[]} */
+      const flags = [];
+      /** @type {Map<string, any>} */
+      const params = new Map();
+      for (const p of [...(item.parameters ?? []), ...(op.parameters ?? [])].map((p) => deref(spec, p))) {
+        if (p && typeof p.name === "string" && ["header", "query", "path"].includes(p.in)) params.set(`${p.in}:${p.name}`, p);
+      }
+      for (const p of params.values()) {
+        const s = deref(spec, p.schema);
+        const t = typeOf(s);
+        flags.push({
+          name: kebab(p.name),
+          in: p.in,
+          path: [p.name],
+          kind: t === "array" ? "array" : leafKind(t),
+          itemKind: t === "array" ? leafKind(typeOf(deref(spec, s.items))) : undefined,
+          required: p.required === true || p.in === "path",
+          hidden: p.deprecated === true,
+          description: String(p.description ?? s?.description ?? "").trim(),
+          enum: s?.enum,
+          format: s?.format,
+        });
+      }
+
+      const bodySchema = deref(spec, op.requestBody)?.content?.["application/json"]?.schema;
+      const body = deref(spec, bodySchema);
+      /** @type {string[]} */
+      const requiredBody = Array.isArray(body?.required) ? body.required.map(String) : [];
+      if (body?.properties && typeof body.properties === "object") {
+        const names = new Set(flags.map((f) => f.name));
+        /** @type {Flag[]} */
+        const fromBody = [];
+        for (const [key, child] of Object.entries(body.properties)) bodyFlags(spec, child, [key], requiredBody.includes(key), fromBody);
+        for (const f of fromBody) if (!names.has(f.name)) flags.push(f);
+      }
+
+      // Positional arguments fill x-cli.positional, else the only required array field of the body (urls).
+      let positional = typeof cli.positional === "string" && body?.properties?.[cli.positional] ? cli.positional : null;
+      if (!positional) {
+        const arrays = requiredBody.filter((k) => typeOf(deref(spec, body?.properties?.[k])) === "array");
+        if (arrays.length === 1) positional = arrays[0];
+      }
+
+      const security = op.security ?? spec.security ?? [];
+      commands.push({
+        name,
+        aliases,
+        method,
+        path,
+        op,
+        cli,
+        flags,
+        positional,
+        hasBody: !!bodySchema,
+        requiredBody,
+        idempotencyKey: flags.find((f) => f.in === "header" && f.name === "idempotency-key") ?? null,
+        needsAuth: Array.isArray(security) && security.length > 0 && security.every((r) => r && Object.keys(r).length > 0),
+      });
+    }
+  }
+  return commands;
+}
+
+export function findCommand(/** @type {Command[]} */ commands, /** @type {string} */ name) {
+  const k = kebab(name);
+  return commands.find((c) => c.name === k || c.aliases.includes(k)) ?? null;
+}
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["false", "0", "no", "off"]);
+
+/** One flag value from the command line into its JSON type. */
+export function coerce(/** @type {Flag} */ flag, /** @type {string} */ raw, /** @type {string} */ kind = flag.kind) {
+  /** @type {any} */
+  let v;
+  if (kind === "string") v = raw;
+  else if (kind === "integer") {
+    if (!/^-?\d+$/.test(raw.trim())) throw new UsageError(`--${flag.name} needs an integer, got "${raw}"`);
+    v = Number(raw);
+  } else if (kind === "number") {
+    v = Number(raw);
+    if (raw.trim() === "" || !Number.isFinite(v)) throw new UsageError(`--${flag.name} needs a number, got "${raw}"`);
+  } else if (kind === "boolean") {
+    const k = raw.trim().toLowerCase();
+    if (TRUE.has(k)) v = true;
+    else if (FALSE.has(k)) v = false;
+    else throw new UsageError(`--${flag.name} needs true or false, got "${raw}"`);
+  } else {
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      throw new UsageError(`--${flag.name} needs JSON, got "${raw}"`);
+    }
+  }
+  const allowed = kind === flag.kind || flag.kind === "array" ? flag.enum : undefined;
+  if (Array.isArray(allowed) && allowed.length && !allowed.includes(v)) {
+    throw new UsageError(`--${flag.name} must be one of ${allowed.map((a) => JSON.stringify(a)).join(", ")}, got ${JSON.stringify(v)}`);
+  }
+  return v;
+}
+
+const isObject = (/** @type {any} */ v) => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** Deep merge of plain objects; `over` wins. */
+export function merge(/** @type {any} */ base, /** @type {any} */ over) {
+  if (!isObject(base) || !isObject(over)) return over;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) out[k] = k in out ? merge(out[k], v) : v;
+  return out;
+}
+
+function setPath(/** @type {any} */ obj, /** @type {string[]} */ path, /** @type {any} */ value) {
+  let node = obj;
+  for (const key of path.slice(0, -1)) {
+    if (!isObject(node[key])) node[key] = {};
+    node = node[key];
+  }
+  node[path[path.length - 1]] = value;
+}
+
+/** Flag lookup accepting the kebab name and the spec's own spelling (--country-code, --countryCode). */
+function flagIndex(/** @type {Command} */ command) {
+  const index = new Map();
+  for (const f of command.flags) index.set(f.name, f);
+  return (/** @type {string} */ given) => index.get(given.split(".").map(kebab).join("."));
+}
+
+/**
+ * @typedef {object} Request
+ * @property {Record<string, string>} headers
+ * @property {Record<string, string | string[]>} query
+ * @property {Record<string, string>} pathParams
+ * @property {any} body          undefined when the operation takes none
+ * @property {string | null} idempotencyKey
+ */
+
+/**
+ * Command arguments (everything after the command name, global options already removed) into a request.
+ * @param {Command} command
+ * @param {string[]} args
+ * @param {any} [data]   parsed --data, merged under the flags
+ * @returns {Request}
+ */
+export function buildRequest(command, args, data) {
+  const find = flagIndex(command);
+  /** @type {string[]} */
+  const positionals = [];
+  /** @type {{ flag: Flag, value: any }[]} */
+  const toggles = [];
+  /** @type {{ flag: Flag, value: any }[]} */
+  const values = [];
+  /** @type {Map<Flag, any[]>} */
+  const arrays = new Map();
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") {
+      positionals.push(...args.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith("--") || arg === "-") {
+      if (arg.startsWith("-") && arg !== "-" && !/^-\d/.test(arg)) throw new UsageError(`unknown option ${arg}`);
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const given = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+    let flag = find(given);
+    let negated = false;
+    if (!flag && given.startsWith("no-")) {
+      const f = find(given.slice(3));
+      if (f && f.kind === "boolean") {
+        flag = f;
+        negated = true;
+      }
+    }
+    if (!flag) throw new UsageError(`unknown option --${given} for "${command.name}" (see ${command.name} --help)`);
+    if (flag.kind === "boolean") {
+      if (negated && eq !== -1) throw new UsageError(`--no-${flag.name} takes no value`);
+      const value = negated ? false : eq === -1 ? true : coerce(flag, arg.slice(eq + 1));
+      (flag.toggle ? toggles : values).push({ flag, value });
+      continue;
+    }
+    let raw;
+    if (eq !== -1) raw = arg.slice(eq + 1);
+    else {
+      if (i + 1 >= args.length) throw new UsageError(`--${flag.name} needs a value`);
+      raw = args[++i];
+    }
+    if (flag.kind === "array") {
+      const list = arrays.get(flag) ?? [];
+      list.push(coerce(flag, raw, flag.itemKind));
+      arrays.set(flag, list);
+    } else values.push({ flag, value: coerce(flag, raw) });
+  }
+
+  /** @type {Request} */
+  const req = { headers: {}, query: {}, pathParams: {}, body: undefined, idempotencyKey: null };
+  /** @type {any} */
+  let body = command.hasBody ? (isObject(data) ? structuredClone(data) : {}) : undefined;
+  if (data !== undefined && !command.hasBody) throw new UsageError(`"${command.name}" takes no request body (--data)`);
+  if (data !== undefined && !isObject(data)) body = data;
+
+  if (positionals.length) {
+    if (!command.positional) throw new UsageError(`"${command.name}" takes no arguments, got "${positionals[0]}"`);
+    const flag = command.flags.find((f) => f.in === "body" && f.path.length === 1 && f.path[0] === command.positional);
+    const list = arrays.get(/** @type {Flag} */ (flag)) ?? [];
+    for (const p of positionals) list.push(flag?.kind === "array" ? coerce(flag, p, flag.itemKind) : p);
+    if (flag?.kind === "array") arrays.set(flag, list);
+    else if (flag) values.push({ flag, value: coerce(flag, positionals.join(" ")) });
+  }
+
+  const assign = (/** @type {Flag} */ flag, /** @type {any} */ value) => {
+    if (flag.in === "body") {
+      if (!isObject(body)) throw new UsageError(`--${flag.name} cannot be combined with a non-object --data`);
+      setPath(body, flag.path, value);
+    } else if (flag.in === "header") req.headers[flag.path[0]] = String(value);
+    else if (flag.in === "query") req.query[flag.path[0]] = Array.isArray(value) ? value.map(String) : String(value);
+    else req.pathParams[flag.path[0]] = String(value);
+  };
+  // Toggles first (--text), so a nested flag (--text.max-characters) turns `true` into an object.
+  for (const { flag, value } of toggles) {
+    const nested = values.some((v) => v.flag.in === "body" && v.flag.path.length > flag.path.length && flag.path.every((k, j) => v.flag.path[j] === k));
+    if (value === false && nested) throw new UsageError(`--no-${flag.name} cannot be combined with --${flag.name}.* options`);
+    if (!nested) assign(flag, value);
+  }
+  for (const { flag, value } of values) assign(flag, value);
+  for (const [flag, list] of arrays) assign(flag, list);
+
+  for (const f of command.flags) {
+    if (!f.required) continue;
+    const present = f.in === "body" ? isObject(body) && body[f.path[0]] !== undefined : f.in === "header" ? f.path[0] in req.headers : f.in === "query" ? f.path[0] in req.query : f.path[0] in req.pathParams;
+    if (!present) {
+      const how = command.positional === f.path[0] ? `pass it as an argument or with --${f.name}` : `pass --${f.name}`;
+      throw new UsageError(`"${command.name}" needs ${f.path[0]}: ${how}`);
+    }
+  }
+  req.body = body;
+  if (command.idempotencyKey) req.idempotencyKey = req.headers[command.idempotencyKey.path[0]] ?? null;
+  return req;
+}
+
+/** The request URL on the base URL. Path parameters are encoded; the result must stay on the base URL's origin. */
+export function requestUrl(/** @type {string} */ baseUrl, /** @type {Command} */ command, /** @type {Request} */ req) {
+  const path = command.path.replace(/\{([^}]+)\}/g, (_, name) => {
+    if (!(name in req.pathParams)) throw new UsageError(`"${command.name}" needs --${kebab(name)}`);
+    return encodeURIComponent(req.pathParams[name]);
+  });
+  const base = new URL(baseUrl);
+  const url = new URL(baseUrl.replace(/\/+$/, "") + (path.startsWith("/") ? path : `/${path}`));
+  if (url.origin !== base.origin) throw new UsageError(`refusing a request outside ${base.origin}: ${url.href}`);
+  for (const [k, v] of Object.entries(req.query)) for (const one of Array.isArray(v) ? v : [v]) url.searchParams.append(k, one);
+  return url;
+}

package/src/config.js

@@ -0,0 +1,102 @@
+// @ts-check
+/**
+ * Brand, version, directories and the API key. The brand (brand.json) is the only thing that differs between the 7
+ * site CLIs; everything else is the same code.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * @typedef {object} Brand
+ * @property {string} name        site name, e.g. "FetchMCP"
+ * @property {string} tagline
+ * @property {string} domain      e.g. "fetchmcp.net"
+ * @property {string} bin         command name, e.g. "fetchmcp"
+ * @property {string} npm         npm package name
+ * @property {string} org         GitHub org
+ * @property {string} repo        GitHub repo in the org
+ * @property {string} siteUrl
+ * @property {string} docsUrl
+ * @property {string} apiName     "Live Web Data API"
+ * @property {string} apiBaseUrl  where requests (and the key) go
+ * @property {string} specUrl     where the commands come from
+ */
+
+/** The package root (bin/, src/, brand.json, openapi.json, package.json). */
+export const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** @returns {Brand} */
+export function loadBrand(root = ROOT) {
+  return JSON.parse(readFileSync(join(root, "brand.json"), "utf8"));
+}
+
+/** @returns {string} */
+export function loadVersion(root = ROOT) {
+  return JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+}
+
+export const BUNDLED_SPEC = join(ROOT, "openapi.json");
+
+/** @typedef {Record<string, string | undefined>} Env */
+
+/** First of `names` that is set and not empty. */
+export function envValue(/** @type {Env} */ env, /** @type {string[]} */ ...names) {
+  for (const name of names) if (env[name]) return env[name];
+  return undefined;
+}
+
+const home = (/** @type {Env} */ env) => env.HOME || homedir();
+
+/** `${XDG_CACHE_HOME:-~/.cache}/<bin>`: the spec cache and the update check. */
+export function cacheDir(/** @type {Env} */ env, /** @type {string} */ bin) {
+  return join(env.XDG_CACHE_HOME || join(home(env), ".cache"), bin);
+}
+
+/** `${XDG_CONFIG_HOME:-~/.config}/<bin>`: config.json with the saved key. */
+export function configDir(/** @type {Env} */ env, /** @type {string} */ bin) {
+  return join(env.XDG_CONFIG_HOME || join(home(env), ".config"), bin);
+}
+
+export const configFile = (/** @type {Env} */ env, /** @type {string} */ bin) => join(configDir(env, bin), "config.json");
+
+/** @returns {{ apiKey?: string }} */
+export function readConfig(/** @type {string} */ file) {
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8"));
+    return data && typeof data === "object" ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Writes the key readable by the owner only (0600, directory 0700), also when the file existed with wider modes. */
+export function saveApiKey(/** @type {string} */ file, /** @type {string} */ apiKey) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ ...readConfig(file), apiKey }, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+}
+
+/** @returns {boolean} whether a saved key was removed */
+export function removeApiKey(/** @type {string} */ file) {
+  if (!existsSync(file)) return false;
+  const { apiKey, ...rest } = readConfig(file);
+  if (Object.keys(rest).length) writeFileSync(file, JSON.stringify(rest, null, 2) + "\n", { mode: 0o600 });
+  else rmSync(file, { force: true });
+  return apiKey !== undefined;
+}
+
+/**
+ * The key, in this order: --api-key, LIVE_WEB_DATA_API_KEY, the legacy TENEO_API_KEY, the saved key.
+ * @returns {{ apiKey?: string, from?: string }}
+ */
+export function resolveApiKey(/** @type {string | undefined} */ flag, /** @type {Env} */ env, /** @type {string} */ bin) {
+  if (flag) return { apiKey: flag, from: "--api-key" };
+  for (const name of ["LIVE_WEB_DATA_API_KEY", "TENEO_API_KEY"]) if (env[name]) return { apiKey: env[name], from: name };
+  const file = configFile(env, bin);
+  const saved = readConfig(file).apiKey;
+  return saved ? { apiKey: saved, from: file } : {};
+}

package/src/help.js

@@ -0,0 +1,127 @@
+// @ts-check
+/** Help texts. Command help is generated from the spec: summary, description, flags, enums and the request examples. */
+import { kebab } from "./commands.js";
+
+const WIDTH = 100;
+
+/** Word wrap with a hanging indent. */
+export function wrap(/** @type {string} */ text, /** @type {number} */ indent, width = WIDTH) {
+  const lines = [];
+  for (const para of text.split("\n")) {
+    let line = "";
+    for (const word of para.split(/\s+/).filter(Boolean)) {
+      if (line && indent + line.length + 1 + word.length > width) {
+        lines.push(line);
+        line = word;
+      } else line = line ? `${line} ${word}` : word;
+    }
+    lines.push(line);
+  }
+  return lines.join("\n" + " ".repeat(indent));
+}
+
+/** Two columns: names padded to the longest (capped), descriptions wrapped under each other. */
+function columns(/** @type {[string, string][]} */ rows) {
+  const w = Math.min(34, Math.max(...rows.map(([a]) => a.length)) + 2);
+  return rows.map(([a, b]) => (a.length + 2 > w ? `  ${a}\n${" ".repeat(w + 2)}${wrap(b, w + 2)}` : `  ${a.padEnd(w)}${wrap(b, w + 2)}`)).join("\n");
+}
+
+/** @param {import("./commands.js").Flag} f */
+function placeholder(f) {
+  if (f.kind === "boolean") return "";
+  const one = (/** @type {string | undefined} */ kind) =>
+    Array.isArray(f.enum) && f.enum.length ? `<${f.enum.join("|")}>` : f.format === "uri" ? "<url>" : `<${kind === "json" ? "json" : kind}>`;
+  return f.kind === "array" ? ` ${one(f.itemKind)}…` : ` ${one(f.kind)}`;
+}
+
+/** @param {import("./commands.js").Flag} f */
+function flagLabel(f) {
+  if (f.kind === "boolean") return `--${f.name}, --no-${f.name}`;
+  return `--${f.name}${placeholder(f)}`;
+}
+
+/** The first request example of an operation as a command line, when every field maps to a flag. */
+export function exampleLine(/** @type {string} */ bin, /** @type {import("./commands.js").Command} */ c) {
+  const examples = c.op?.requestBody?.content?.["application/json"]?.examples;
+  const first = examples && typeof examples === "object" ? Object.values(examples)[0] : undefined;
+  const value = first?.value ?? c.op?.requestBody?.content?.["application/json"]?.example;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const parts = [bin, c.name];
+  const walk = (/** @type {any} */ obj, /** @type {string[]} */ path) => {
+    for (const [k, v] of Object.entries(obj)) {
+      const p = [...path, k];
+      const name = p.map(kebab).join(".");
+      const flag = c.flags.find((f) => f.name === name);
+      if (path.length === 0 && k === c.positional && Array.isArray(v)) parts.push(...v.map(String));
+      else if (flag?.kind === "array" && Array.isArray(v)) v.forEach((x) => parts.push(`--${name}`, String(x)));
+      else if (v && typeof v === "object" && !Array.isArray(v)) walk(v, p);
+      else if (flag?.kind === "boolean") parts.push(v ? `--${name}` : `--no-${name}`);
+      else if (flag) parts.push(`--${name}`, String(v));
+      else return false;
+    }
+    return true;
+  };
+  return walk(value, []) ? parts.join(" ") : null;
+}
+
+/**
+ * @param {import("./config.js").Brand} brand
+ * @param {import("./commands.js").Command[]} commands
+ * @param {{ source: string }} spec
+ */
+export function mainHelp(brand, commands, spec) {
+  const b = brand.bin;
+  const rows = /** @type {[string, string][]} */ ([
+    ...commands.map((c) => /** @type {[string, string]} */ ([[c.name, ...c.aliases].join(", "), String(c.op.summary ?? c.op.operationId ?? `${c.method.toUpperCase()} ${c.path}`)])),
+    ["login", "Save your API key for this CLI"],
+    ["logout", "Remove the saved API key"],
+    ["spec [refresh]", "Show or refresh the API spec the commands come from"],
+  ]);
+  return `${brand.name}: ${brand.tagline}
+${wrap(`The ${b} command line client for the ${brand.apiName}: live web pages as clean Markdown, text or HTML.`, 0)}
+
+Usage: ${b} <command> [options]
+
+Commands:
+${columns(rows)}
+
+Options for every command:
+${columns([
+  ["--api-key <key>", `API key. Default: env LIVE_WEB_DATA_API_KEY, then the key saved by \`${b} login\``],
+  ["--base-url <url>", `API base URL. Default: env LIVE_WEB_DATA_API_BASE_URL, then ${brand.apiBaseUrl}`],
+  ["--spec-url <url>", `API spec URL. Default: env LIVE_WEB_DATA_SPEC_URL, then ${brand.specUrl}`],
+  ["--offline", "Use the cached or bundled spec, do not download it"],
+  ["-o, --output <mode>", "json (default), text, or one field of each result, e.g. markdown, html, title"],
+  ["-d, --data <json>", "Request body as JSON, @file or - (stdin); options override its fields"],
+  ["--timeout <seconds>", "Per attempt. Default 120"],
+  ["--max-wait <seconds>", "How long to repeat a 202 (still fetching) answer. Default 300"],
+  ["-h, --help", `Help; for one command: ${b} <command> --help`],
+  ["-v, --version", "Print the version"],
+])}
+
+${wrap(`The commands and their options come from the live API spec (${spec.source === "bundled" ? "now: the copy bundled with this version" : "cached for an hour"}), so new API features show up here without an update.`, 0)}
+Docs: ${brand.docsUrl}
+`;
+}
+
+/** @param {import("./config.js").Brand} brand @param {import("./commands.js").Command} c */
+export function commandHelp(brand, c) {
+  // Body fields first, then headers and query/path parameters.
+  const visible = [...c.flags.filter((f) => !f.hidden && f.in === "body"), ...c.flags.filter((f) => !f.hidden && f.in !== "body")];
+  const usage = `${brand.bin} ${c.name}${c.positional ? ` <${kebab(c.positional)}…>` : ""}${visible.length ? " [options]" : ""}`;
+  const rows = visible.map((f) => /** @type {[string, string]} */ ([flagLabel(f), `${f.required ? "Required. " : ""}${f.in === "header" ? "(header) " : f.in === "query" ? "(query) " : ""}${f.description}`]));
+  const example = exampleLine(brand.bin, c);
+  return [
+    `${brand.bin} ${c.name}: ${c.op.summary ?? ""}`.trimEnd(),
+    c.aliases.length ? `Alias: ${c.aliases.join(", ")}` : "",
+    "",
+    `Usage: ${usage}`,
+    c.op.description ? `\n${wrap(String(c.op.description), 0)}` : "",
+    rows.length ? `\nOptions:\n${columns(rows)}` : "",
+    c.hasBody ? `\n${wrap("-d/--data takes the whole request body as JSON (or @file, or - for stdin); options override its fields. Any API field works there, also one without an option.", 0)}` : "",
+    example ? `\nExample:\n  ${example}` : "",
+    "",
+  ]
+    .filter((s, i, all) => s !== "" || (i > 0 && all[i - 1] !== ""))
+    .join("\n");
+}