@contextretrieval-net/cli 0.0.0-stage → 0.0.0

package/src/http.js

@@ -0,0 +1,96 @@
+// @ts-check
+/**
+ * One API call. A request that carries an Idempotency-Key (or is a GET) is repeated after a network error, a cut 2xx
+ * answer, a 429 or a 5xx: the key makes the repeat rejoin the first request instead of being charged again. A 202
+ * "pending" answer (a fetch still running after ~100 s) is repeated with the same key after Retry-After until the
+ * result arrives or maxWaitMs runs out.
+ */
+
+/**
+ * @typedef {object} Outcome
+ * @property {"ok" | "api" | "pending" | "network"} kind
+ * @property {number} status        0 for network
+ * @property {any} body             parsed JSON, else the text
+ * @property {string | null} requestId
+ * @property {string} [error]       network: what went wrong
+ */
+
+const sleep = (/** @type {number} */ ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Exponential backoff with jitter: ~0.5 s, 1 s, 2 s (capped at 8 s). */
+const backoffMs = (/** @type {number} */ attempt) => {
+  const base = Math.min(8000, 500 * 2 ** attempt);
+  return base / 2 + Math.random() * (base / 2);
+};
+
+const isPending = (/** @type {any} */ body) => !!body && typeof body === "object" && body.status === "pending";
+
+/**
+ * @param {object} o
+ * @param {URL} o.url
+ * @param {string} o.method
+ * @param {Record<string, string>} o.headers
+ * @param {any} [o.body]
+ * @param {boolean} o.repeatable      safe to send again (GET, or an Idempotency-Key is set)
+ * @param {number} o.timeoutMs        per attempt
+ * @param {number} o.maxWaitMs        202 repeats
+ * @param {number} [o.retries]
+ * @param {(info: { retryAfter: number, idempotencyKey: string | null }) => void} [o.onPending]
+ * @param {typeof fetch} [o.fetchImpl]
+ * @returns {Promise<Outcome>}
+ */
+export async function send(o) {
+  const fetchImpl = o.fetchImpl ?? fetch;
+  const retries = o.retries ?? 2;
+  const until = Date.now() + o.maxWaitMs;
+  const payload = o.body === undefined ? undefined : JSON.stringify(o.body);
+  const headers = { ...o.headers, ...(payload !== undefined && { "Content-Type": "application/json" }) };
+
+  for (let attempt = 0; ; ) {
+    const canRetry = o.repeatable && attempt < retries;
+    /** @type {Response} */
+    let res;
+    try {
+      res = await fetchImpl(o.url, { method: o.method.toUpperCase(), headers, body: payload, signal: AbortSignal.timeout(o.timeoutMs) });
+    } catch (e) {
+      if (canRetry) {
+        await sleep(backoffMs(attempt++));
+        continue;
+      }
+      const err = /** @type {Error} */ (e);
+      return { kind: "network", status: 0, body: null, requestId: null, error: err.name === "TimeoutError" ? `no answer within ${Math.round(o.timeoutMs / 1000)} s` : String(err.cause ?? err.message) };
+    }
+    const requestId = res.headers.get("x-request-id");
+    const json = /json/i.test(res.headers.get("content-type") ?? "");
+    /** @type {any} */
+    let body;
+    try {
+      const text = await res.text();
+      body = json ? JSON.parse(text) : text;
+    } catch (e) {
+      // A cut 2xx answer is a lost answer, not a result: repeat with the same key, then report it as a network error.
+      if (res.ok && canRetry) {
+        await sleep(backoffMs(attempt++));
+        continue;
+      }
+      if (res.ok) return { kind: "network", status: 0, body: null, requestId, error: `HTTP ${res.status} answer cut or not JSON: ${/** @type {Error} */ (e).message}` };
+      body = null;
+    }
+
+    if (res.status === 202 && isPending(body)) {
+      const retryAfter = Math.min(30, Math.max(1, Number(res.headers.get("retry-after") ?? body.retryAfter) || 1));
+      if (!o.repeatable || Date.now() + retryAfter * 1000 >= until) return { kind: "pending", status: 202, body, requestId };
+      o.onPending?.({ retryAfter, idempotencyKey: body.idempotencyKey ?? null });
+      await sleep(retryAfter * 1000);
+      continue;
+    }
+    if (res.ok) return { kind: "ok", status: res.status, body, requestId };
+    if ((res.status === 429 || res.status >= 500) && canRetry) {
+      const ra = Number(res.headers.get("retry-after"));
+      await sleep(Number.isFinite(ra) && ra > 0 ? Math.min(ra, 30) * 1000 : backoffMs(attempt));
+      attempt++;
+      continue;
+    }
+    return { kind: "api", status: res.status, body, requestId };
+  }
+}

package/src/main.js

@@ -0,0 +1,282 @@
+// @ts-check
+/**
+ * The CLI: global options, the built-in commands (help, login, logout, spec) and one command per API operation.
+ * Exit codes: 0 ok, 1 API error (or every item failed with -o text, or still pending), 2 usage, 3 network.
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildCommands, buildRequest, findCommand, requestUrl, UsageError } from "./commands.js";
+import { cacheDir, configFile, envValue, loadBrand, loadVersion, removeApiKey, resolveApiKey, ROOT, saveApiKey } from "./config.js";
+import { commandHelp, mainHelp } from "./help.js";
+import { send } from "./http.js";
+import { json, render } from "./output.js";
+import { loadSpec } from "./spec.js";
+import { updateNotice } from "./update.js";
+
+/**
+ * @typedef {object} IO
+ * @property {Record<string, string | undefined>} env
+ * @property {NodeJS.ReadStream | { isTTY?: boolean } & AsyncIterable<any>} stdin
+ * @property {{ write(s: string): unknown, isTTY?: boolean }} stdout
+ * @property {{ write(s: string): unknown, isTTY?: boolean }} stderr
+ * @property {string} [root]       package root (brand.json, package.json, openapi.json)
+ * @property {typeof fetch} [fetchImpl]
+ */
+
+/** @typedef {{ apiKey?: string, baseUrl?: string, specUrl?: string, offline: boolean, output: string, data?: string, timeout?: number, maxWait?: number, help: boolean, version: boolean, rest: string[] }} Globals */
+
+const VALUE_OPTIONS = /** @type {const} */ ({ "--api-key": "apiKey", "--base-url": "baseUrl", "--spec-url": "specUrl", "-o": "output", "--output": "output", "-d": "data", "--data": "data", "--timeout": "timeout", "--max-wait": "maxWait" });
+
+/** Takes the global options out of argv, anywhere before `--`. */
+export function parseGlobals(/** @type {string[]} */ argv) {
+  /** @type {Globals} */
+  const g = { offline: false, output: "json", help: false, version: false, rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      g.rest.push(...argv.slice(i));
+      break;
+    }
+    if (arg === "-h" || arg === "--help") g.help = true;
+    else if (arg === "-v" || arg === "--version") g.version = true;
+    else if (arg === "--offline") g.offline = true;
+    else {
+      const eq = arg.startsWith("--") ? arg.indexOf("=") : -1;
+      const name = eq === -1 ? arg : arg.slice(0, eq);
+      const key = /** @type {Record<string, string>} */ (VALUE_OPTIONS)[name];
+      if (!key) {
+        g.rest.push(arg);
+        continue;
+      }
+      let value;
+      if (eq !== -1) value = arg.slice(eq + 1);
+      else if (i + 1 < argv.length) value = argv[++i];
+      else throw new UsageError(`${name} needs a value`);
+      if (key === "timeout" || key === "maxWait") {
+        const n = Number(value);
+        if (!Number.isFinite(n) || n <= 0) throw new UsageError(`${name} needs a number of seconds, got "${value}"`);
+        /** @type {any} */ (g)[key] = n;
+      } else /** @type {any} */ (g)[key] = value;
+    }
+  }
+  return g;
+}
+
+async function readAll(/** @type {AsyncIterable<any>} */ stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** --data: JSON, @file or - (stdin). */
+async function readData(/** @type {string} */ raw, /** @type {IO} */ io) {
+  let text = raw;
+  if (raw === "-") text = await readAll(/** @type {AsyncIterable<any>} */ (io.stdin));
+  else if (raw.startsWith("@")) {
+    try {
+      text = readFileSync(raw.slice(1), "utf8");
+    } catch (e) {
+      throw new UsageError(`--data ${raw}: ${/** @type {Error} */ (e).message}`);
+    }
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new UsageError(`--data is not valid JSON`);
+  }
+}
+
+/** Reads a line without echo (the API key). */
+function promptHidden(/** @type {string} */ question, /** @type {any} */ stdin, /** @type {IO["stderr"]} */ stderr) {
+  return new Promise((resolve, reject) => {
+    stderr.write(question);
+    let value = "";
+    const done = () => {
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      stderr.write("\n");
+    };
+    const onData = (/** @type {string} */ chunk) => {
+      for (const ch of chunk) {
+        if (ch === "\r" || ch === "\n" || ch === "\u0004") {
+          done();
+          return resolve(value);
+        }
+        if (ch === "\u0003") {
+          done();
+          return reject(new UsageError("cancelled"));
+        }
+        if (ch === "\u007f" || ch === "\b") value = value.slice(0, -1);
+        else value += ch;
+      }
+    };
+    stdin.setRawMode?.(true);
+    stdin.setEncoding("utf8");
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
+
+const BUILTIN_HELP = {
+  login: (/** @type {string} */ b) => `Usage: ${b} login [--api-key <key>]\n\nSaves your API key (asked without echo, or piped in: echo $KEY | ${b} login) to ~/.config/${b}/config.json, readable\nonly by you. --api-key and env LIVE_WEB_DATA_API_KEY take precedence over the saved key.\n`,
+  logout: (/** @type {string} */ b) => `Usage: ${b} logout\n\nRemoves the saved API key.\n`,
+  spec: (/** @type {string} */ b) => `Usage: ${b} spec [refresh]\n\nShows where the commands come from: the live API spec, cached for an hour, or the copy bundled with this version.\n\`refresh\` downloads it now.\n`,
+};
+
+const ago = (/** @type {number} */ ms) => (ms < 90_000 ? `${Math.round(ms / 1000)} s ago` : ms < 5_400_000 ? `${Math.round(ms / 60_000)} min ago` : `${Math.round(ms / 3_600_000)} h ago`);
+
+/**
+ * @param {string[]} argv
+ * @param {IO} io
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, io) {
+  const root = io.root ?? ROOT;
+  const brand = loadBrand(root);
+  const version = loadVersion(root);
+  const { env, stdout, stderr } = io;
+  const fail = (/** @type {Error} */ e) => {
+    stderr.write(`${brand.bin}: ${e.message}\n`);
+    return 2;
+  };
+
+  /** @type {Globals} */
+  let g;
+  try {
+    g = parseGlobals(argv);
+  } catch (e) {
+    return fail(/** @type {Error} */ (e));
+  }
+  if (g.version) {
+    stdout.write(`${version}\n`);
+    return 0;
+  }
+
+  const userAgent = `${brand.bin}-cli/${version} (+https://${brand.domain})`;
+  const cache = cacheDir(env, brand.bin);
+  const notice = updateNotice({ bin: brand.bin, npm: brand.npm, version, cacheDir: cache, env, isTTY: !!stderr.isTTY, fetchImpl: io.fetchImpl });
+  let code;
+  try {
+    code = await run(g);
+  } catch (e) {
+    if (!(e instanceof UsageError)) throw e;
+    code = fail(e);
+  }
+  const line = await notice;
+  if (line) stderr.write(`${line}\n`);
+  return code;
+
+  /** @param {Globals} g */
+  async function run(g) {
+    const [name, ...args] = g.rest;
+    const spec = () =>
+      loadSpec({
+        url: g.specUrl ?? envValue(env, "LIVE_WEB_DATA_SPEC_URL") ?? brand.specUrl,
+        cacheDir: cache,
+        bundledPath: join(root, "openapi.json"),
+        offline: g.offline,
+        headers: { "User-Agent": userAgent },
+        fetchImpl: io.fetchImpl,
+      });
+
+    const builtin = BUILTIN_HELP[/** @type {keyof typeof BUILTIN_HELP} */ (name === "help" ? args[0] : name)];
+    if (builtin && (g.help || name === "help")) {
+      stdout.write(builtin(brand.bin));
+      return 0;
+    }
+    if (name === "login") {
+      let key = g.apiKey;
+      if (!key) key = io.stdin.isTTY ? await promptHidden("API key: ", io.stdin, stderr) : (await readAll(/** @type {AsyncIterable<any>} */ (io.stdin))).trim();
+      if (!key || /\s/.test(key)) throw new UsageError("no API key given (paste it at the prompt, pipe it in, or pass --api-key)");
+      const file = configFile(env, brand.bin);
+      saveApiKey(file, key);
+      stderr.write(`Saved the API key to ${file} (readable only by you).\n`);
+      return 0;
+    }
+    if (name === "logout") {
+      const file = configFile(env, brand.bin);
+      stderr.write(removeApiKey(file) ? `Removed the saved API key from ${file}.\n` : "No saved API key.\n");
+      return 0;
+    }
+    if (name === "spec") {
+      if (args[0] !== undefined && args[0] !== "refresh") throw new UsageError(`unknown "spec ${args[0]}" (spec, spec refresh)`);
+      const refresh = args[0] === "refresh";
+      if (refresh && g.offline) throw new UsageError("spec refresh cannot run --offline");
+      const loaded = refresh
+        ? await loadSpec({ url: g.specUrl ?? envValue(env, "LIVE_WEB_DATA_SPEC_URL") ?? brand.specUrl, cacheDir: cache, bundledPath: join(root, "openapi.json"), force: true, headers: { "User-Agent": userAgent }, fetchImpl: io.fetchImpl })
+        : await spec();
+      const commands = buildCommands(loaded.spec);
+      stdout.write(
+        [
+          `Spec:     ${loaded.url}`,
+          `Source:   ${loaded.source}${loaded.fetchedAt ? ` (downloaded or checked ${ago(Date.now() - loaded.fetchedAt)})` : " (bundled with this version)"}${loaded.etag ? `, ETag ${loaded.etag}` : ""}`,
+          `API:      ${loaded.spec.info?.title ?? "?"} ${loaded.spec.info?.version ?? ""}`.trimEnd(),
+          `Commands: ${commands.map((c) => c.name).join(", ")}`,
+          ...(loaded.error ? [`Note:     could not download it: ${loaded.error}`] : []),
+          "",
+        ].join("\n"),
+      );
+      return refresh && loaded.error ? 3 : 0;
+    }
+
+    const loaded = await spec();
+    const commands = buildCommands(loaded.spec);
+    if (name === undefined || (name === "help" && args.length === 0)) {
+      stdout.write(mainHelp(brand, commands, loaded));
+      return 0;
+    }
+    const helpFor = name === "help" ? args[0] : g.help ? name : null;
+    const command = findCommand(commands, helpFor ?? name);
+    if (!command) {
+      const known = [...commands.flatMap((c) => [c.name, ...c.aliases]), "login", "logout", "spec"];
+      throw new UsageError(`unknown command "${helpFor ?? name}". Commands: ${known.join(", ")} (see ${brand.bin} --help)`);
+    }
+    if (helpFor) {
+      stdout.write(commandHelp(brand, command));
+      return 0;
+    }
+
+    const data = g.data !== undefined ? await readData(g.data, io) : undefined;
+    const req = buildRequest(command, args, data);
+    let idempotencyKey = req.idempotencyKey;
+    if (command.idempotencyKey && !idempotencyKey) {
+      idempotencyKey = `cli_${randomUUID()}`;
+      req.headers[command.idempotencyKey.path[0]] = idempotencyKey;
+    }
+    const baseUrl = g.baseUrl ?? envValue(env, "LIVE_WEB_DATA_API_BASE_URL", "TENEO_API_BASE_URL") ?? brand.apiBaseUrl;
+    if (!/^https?:\/\/[^/]/.test(baseUrl)) throw new UsageError(`the base URL must be http(s)://…, got "${baseUrl}"`);
+    // The target comes from the base URL only: never from the spec's servers.
+    const url = requestUrl(baseUrl, command, req);
+    const { apiKey } = resolveApiKey(g.apiKey, env, brand.bin);
+    if (!apiKey && command.needsAuth) stderr.write(`${brand.bin}: no API key. Run \`${brand.bin} login\` or set LIVE_WEB_DATA_API_KEY.\n`);
+
+    const outcome = await send({
+      url,
+      method: command.method,
+      headers: { Accept: "application/json", "User-Agent": userAgent, ...(apiKey && { Authorization: `Bearer ${apiKey}` }), ...req.headers },
+      body: req.body,
+      repeatable: command.method === "get" || !!idempotencyKey,
+      timeoutMs: (g.timeout ?? 120) * 1000,
+      maxWaitMs: (g.maxWait ?? 300) * 1000,
+      onPending: ({ retryAfter }) => stderr.write(`${brand.bin}: still fetching, asking again in ${retryAfter} s (Idempotency-Key ${idempotencyKey})\n`),
+      fetchImpl: io.fetchImpl,
+    });
+    const again = idempotencyKey ? `Run the same command again with --idempotency-key ${idempotencyKey} within 15 minutes to get the result without a new charge.` : undefined;
+
+    if (outcome.kind === "ok") {
+      const out = render(outcome.body, g.output, command.cli.output);
+      stdout.write(out.stdout);
+      if (out.stderr) stderr.write(out.stderr);
+      return out.failed ? 1 : 0;
+    }
+    if (outcome.kind === "network") {
+      stderr.write(json({ error: { tag: "CONNECTION_ERROR", message: outcome.error }, requestId: outcome.requestId, ...(idempotencyKey && { idempotencyKey, hint: `The API may have received the request. ${again}` }) }));
+      return 3;
+    }
+    const body = outcome.body && typeof outcome.body === "object" && !Array.isArray(outcome.body) ? outcome.body : { error: { message: String(outcome.body ?? "").slice(0, 2000) } };
+    stderr.write(json({ status: outcome.status, ...body, requestId: body.requestId ?? outcome.requestId, ...(idempotencyKey && { idempotencyKey }), ...(outcome.kind === "pending" && again && { hint: `Still fetching. ${again}` }) }));
+    return 1;
+  }
+}

package/src/output.js

@@ -0,0 +1,57 @@
+// @ts-check
+/**
+ * Output modes. `json` (default): the answer as pretty JSON. `text`: with an `x-cli.output` hint, the content of each
+ * item (the first non-empty of hint.fields, e.g. markdown, then text, then html), and failed entries of hint.errors on
+ * stderr; without a hint, one `key.path: value` line per field. Any other mode names one field of each item
+ * (`-o html`, `-o title`).
+ */
+
+/**
+ * @typedef {object} OutputHint
+ * @property {string} [items]     array of the answer to print, e.g. "results"
+ * @property {string[]} [fields]  content fields in order of preference
+ * @property {string} [heading]   item field shown above each item when there are several, e.g. "url"
+ * @property {string} [errors]    array of per-item statuses whose `error` is printed on stderr, e.g. "statuses"
+ */
+
+export const json = (/** @type {any} */ v) => JSON.stringify(v, null, 2) + "\n";
+
+/** Leaf values as `a.b: value` lines. */
+export function flatten(/** @type {any} */ v, prefix = "", /** @type {string[]} */ out = []) {
+  if (v && typeof v === "object") {
+    const entries = Array.isArray(v) ? v.map((x, i) => [String(i), x]) : Object.entries(v);
+    if (!entries.length) out.push(`${prefix}: ${Array.isArray(v) ? "[]" : "{}"}`);
+    for (const [k, x] of entries) flatten(x, prefix ? `${prefix}.${k}` : k, out);
+  } else out.push(`${prefix}: ${v === null ? "null" : String(v)}`);
+  return out;
+}
+
+const asText = (/** @type {any} */ v) => (typeof v === "string" ? v : v === null || v === undefined ? "" : JSON.stringify(v));
+const withNewline = (/** @type {string} */ s) => (s.endsWith("\n") ? s : `${s}\n`);
+
+/**
+ * @param {any} body
+ * @param {string} mode
+ * @param {OutputHint | undefined} hint
+ * @returns {{ stdout: string, stderr: string, failed: boolean }}  failed: nothing printed and every item failed
+ */
+export function render(body, mode, hint) {
+  if (mode === "json") return { stdout: json(body), stderr: "", failed: false };
+  if (typeof body === "string") return { stdout: withNewline(body), stderr: "", failed: false };
+  const items = hint?.items && Array.isArray(body?.[hint.items]) ? body[hint.items] : null;
+  if (!items) {
+    if (mode !== "text") return { stdout: withNewline(asText(body?.[mode])), stderr: "", failed: false };
+    return { stdout: flatten(body).join("\n") + "\n", stderr: "", failed: false };
+  }
+  const fields = mode === "text" ? hint?.fields ?? [] : [mode];
+  const parts = items.map((/** @type {any} */ item) => {
+    const value = fields.map((f) => item?.[f]).find((v) => v !== undefined && v !== null && v !== "");
+    return value === undefined && mode === "text" && !fields.length ? json(item) : withNewline(asText(value));
+  });
+  const stdout = items.length > 1 && hint?.heading
+    ? items.map((/** @type {any} */ item, /** @type {number} */ i) => `==> ${asText(item?.[/** @type {string} */ (hint.heading)])} <==\n${parts[i]}`).join("\n")
+    : parts.join("\n");
+  const errors = (hint?.errors && Array.isArray(body?.[hint.errors]) ? body[hint.errors] : []).filter((/** @type {any} */ s) => s?.error);
+  const stderr = errors.map((/** @type {any} */ s) => `${s.id ?? s.url ?? "?"}: ${s.error.tag ?? "ERROR"}: ${s.error.message ?? ""}\n`).join("");
+  return { stdout, stderr, failed: items.length === 0 && errors.length > 0 };
+}

package/src/spec.js

@@ -0,0 +1,109 @@
+// @ts-check
+/**
+ * The API spec the commands come from. Read at run time so an API change reaches every installed CLI without a new
+ * release: a cache younger than SPEC_TTL_MS, else a conditional GET of the live spec (If-None-Match), else the stale
+ * cache, else the copy bundled with the package. The spec only describes commands and flags: requests go to the base
+ * URL (brand.apiBaseUrl / --base-url), never to the spec's `servers`.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const SPEC_TTL_MS = 60 * 60 * 1000;
+export const SPEC_TIMEOUT_MS = 3000;
+
+/** @typedef {{ url: string, etag: string | null, fetchedAt: number }} SpecMeta */
+/**
+ * @typedef {object} LoadedSpec
+ * @property {any} spec
+ * @property {"cache" | "network" | "stale-cache" | "bundled"} source
+ * @property {string} url          the spec URL asked for
+ * @property {string | null} etag
+ * @property {number | null} fetchedAt  ms epoch of the last download or revalidation (null: bundled)
+ * @property {string} [error]      why the network was not used, when it was tried
+ */
+
+/** Minimal shape check before a downloaded spec replaces the cache. */
+export function isSpec(/** @type {any} */ x) {
+  return (
+    !!x && typeof x === "object" && typeof x.openapi === "string" && /^3\./.test(x.openapi) &&
+    !!x.paths && typeof x.paths === "object" && !Array.isArray(x.paths)
+  );
+}
+
+const readJson = (/** @type {string} */ file) => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/** Atomic write; a read-only cache directory is not an error. */
+function writeAtomic(/** @type {string} */ file, /** @type {string} */ text) {
+  try {
+    mkdirSync(join(file, ".."), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, text);
+    renameSync(tmp, file);
+  } catch {
+    // no cache then
+  }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.url
+ * @param {string} o.cacheDir
+ * @param {string} o.bundledPath
+ * @param {boolean} [o.offline]   cache or bundled copy only
+ * @param {boolean} [o.force]     ignore the TTL (spec refresh)
+ * @param {number} [o.now]
+ * @param {number} [o.ttlMs]
+ * @param {number} [o.timeoutMs]
+ * @param {Record<string, string>} [o.headers]
+ * @param {typeof fetch} [o.fetchImpl]
+ * @returns {Promise<LoadedSpec>}
+ */
+export async function loadSpec(o) {
+  const now = o.now ?? Date.now();
+  const specFile = join(o.cacheDir, "openapi.json");
+  const metaFile = join(o.cacheDir, "openapi.meta.json");
+  /** @type {SpecMeta | null} */
+  const meta = readJson(metaFile);
+  const cachedSpec = meta && meta.url === o.url ? readJson(specFile) : null;
+  const cached = meta && isSpec(cachedSpec) ? { spec: cachedSpec, meta } : null;
+  const bundled = () => {
+    const spec = JSON.parse(readFileSync(o.bundledPath, "utf8"));
+    return { spec, url: o.url, etag: null, fetchedAt: null };
+  };
+
+  if (cached && !o.force && (o.offline || now - cached.meta.fetchedAt < (o.ttlMs ?? SPEC_TTL_MS))) {
+    return { spec: cached.spec, source: o.offline && now - cached.meta.fetchedAt >= (o.ttlMs ?? SPEC_TTL_MS) ? "stale-cache" : "cache", url: o.url, etag: cached.meta.etag, fetchedAt: cached.meta.fetchedAt };
+  }
+  if (o.offline) return { ...bundled(), source: "bundled" };
+
+  let error;
+  try {
+    const res = await (o.fetchImpl ?? fetch)(o.url, {
+      headers: { Accept: "application/json", ...o.headers, ...(cached?.meta.etag ? { "If-None-Match": cached.meta.etag } : {}) },
+      signal: AbortSignal.timeout(o.timeoutMs ?? SPEC_TIMEOUT_MS),
+    });
+    if (res.status === 304 && cached) {
+      const fresh = { ...cached.meta, fetchedAt: now };
+      writeAtomic(metaFile, JSON.stringify(fresh) + "\n");
+      return { spec: cached.spec, source: "cache", url: o.url, etag: fresh.etag, fetchedAt: now };
+    }
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const text = await res.text();
+    const spec = JSON.parse(text);
+    if (!isSpec(spec)) throw new Error("not an OpenAPI 3 document");
+    const etag = res.headers.get("etag");
+    writeAtomic(specFile, text);
+    writeAtomic(metaFile, JSON.stringify({ url: o.url, etag, fetchedAt: now }) + "\n");
+    return { spec, source: "network", url: o.url, etag, fetchedAt: now };
+  } catch (e) {
+    error = /** @type {Error} */ (e).name === "TimeoutError" ? `timeout after ${o.timeoutMs ?? SPEC_TIMEOUT_MS} ms` : /** @type {Error} */ (e).message;
+  }
+  if (cached) return { spec: cached.spec, source: "stale-cache", url: o.url, etag: cached.meta.etag, fetchedAt: cached.meta.fetchedAt, error };
+  return { ...bundled(), source: "bundled", error };
+}

package/src/update.js

@@ -0,0 +1,71 @@
+// @ts-check
+/**
+ * Update notice: at most once a day, ask the npm registry for the latest version of this package and print one line on
+ * stderr when it is newer. Never in CI, never when stderr is not a terminal, never with <BIN>_NO_UPDATE_NOTIFIER or
+ * NO_UPDATE_NOTIFIER set. Commands do not depend on it: they follow the live spec anyway.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const UPDATE_CHECK_MS = 24 * 60 * 60 * 1000;
+export const REGISTRY = "https://registry.npmjs.org";
+
+/** FETCHMCP_NO_UPDATE_NOTIFIER for bin "fetchmcp". */
+export const noUpdateVar = (/** @type {string} */ bin) => `${bin.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_NO_UPDATE_NOTIFIER`;
+
+/** a > b for x.y.z versions (a pre-release suffix counts as older). */
+export function newer(/** @type {string} */ a, /** @type {string} */ b) {
+  const parse = (/** @type {string} */ v) => {
+    const [core, pre] = String(v).replace(/^v/, "").split("-", 2);
+    return { nums: core.split(".").map((n) => Number(n) || 0), pre: pre !== undefined };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < 3; i++) if ((x.nums[i] ?? 0) !== (y.nums[i] ?? 0)) return (x.nums[i] ?? 0) > (y.nums[i] ?? 0);
+  return !x.pre && y.pre;
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.bin
+ * @param {string} o.npm
+ * @param {string} o.version
+ * @param {string} o.cacheDir
+ * @param {Record<string, string | undefined>} o.env
+ * @param {boolean} o.isTTY
+ * @param {number} [o.now]
+ * @param {string} [o.registry]
+ * @param {typeof fetch} [o.fetchImpl]
+ * @returns {Promise<string | null>}
+ */
+export async function updateNotice(o) {
+  if (!o.isTTY || o.env.CI || o.env[noUpdateVar(o.bin)] || o.env.NO_UPDATE_NOTIFIER) return null;
+  const now = o.now ?? Date.now();
+  const file = join(o.cacheDir, "update-check.json");
+  let latest = null;
+  try {
+    const cached = JSON.parse(readFileSync(file, "utf8"));
+    if (now - cached.checkedAt < UPDATE_CHECK_MS) latest = cached.latest;
+  } catch {
+    // no check yet
+  }
+  if (latest === null) {
+    try {
+      const res = await (o.fetchImpl ?? fetch)(`${o.registry ?? REGISTRY}/${encodeURIComponent(o.npm).replace(/^%40/, "@")}/latest`, {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(1500),
+      });
+      latest = res.ok ? String((await res.json()).version ?? "") : "";
+    } catch {
+      latest = "";
+    }
+    try {
+      mkdirSync(o.cacheDir, { recursive: true });
+      writeFileSync(file, JSON.stringify({ checkedAt: now, latest }) + "\n");
+    } catch {
+      // checked again next time
+    }
+  }
+  if (!latest || !newer(latest, o.version)) return null;
+  return `${o.bin} ${latest} is available (you have ${o.version}). Update: npm install -g ${o.npm}`;
+}