@widgetic/cli 0.0.0-stage → 0.1.1

package/dist/commands/verify.js

@@ -0,0 +1,64 @@
+import { errorFromAnswer, isRecord, networkFailure, readAnswer } from "../http.js";
+import { withRetries } from "../retry.js";
+import { identityHeaders } from "../version.js";
+/** What the answer of `/tokens/validate` says about the key; a field the server did not send is `undefined`. */
+export function keyCheckOf(body) {
+    const data = isRecord(body) && isRecord(body.data) ? body.data : {};
+    return {
+        tokenType: typeof data.tokenType === 'string' ? data.tokenType : undefined,
+        scopes: Array.isArray(data.scopes)
+            ? data.scopes.filter((scope) => typeof scope === 'string')
+            : [],
+        userId: typeof data.userId === 'string' ? data.userId : undefined,
+        expiresAt: typeof data.expiresAt === 'string' ? data.expiresAt : undefined
+    };
+}
+/** The address a key is checked at. */
+export function validateUrl(settings) {
+    return `${settings.apiUrl}/tokens/validate`;
+}
+/** Resolves with what the server says about the key, or throws what its refusal (or its silence) stands for. */
+export async function verifyApiKey(environment, settings, apiKey, options) {
+    const url = validateUrl(settings);
+    const attempt = async () => {
+        let answer;
+        try {
+            const response = await environment.fetch(url, {
+                method: 'GET',
+                headers: {
+                    accept: 'application/json',
+                    authorization: `Bearer ${apiKey}`,
+                    ...identityHeaders(environment)
+                },
+                signal: AbortSignal.timeout(options.timeoutMilliseconds)
+            });
+            answer = await readAnswer(response);
+        }
+        catch (error) {
+            throw networkFailure(error, url, options.timeoutMilliseconds);
+        }
+        if (answer.status < 200 || answer.status >= 300) {
+            throw errorFromAnswer(answer, environment.now(), options.keySource);
+        }
+        return answer;
+    };
+    const answer = await withRetries(environment, { safeToRepeat: true }, attempt, options.onRetry);
+    return keyCheckOf(answer.body);
+}
+/** Whether a server answers at all at an address, whatever it says: the answer's status, and how long it took. */
+export async function probe(environment, url, init, timeoutMilliseconds) {
+    const started = environment.now().getTime();
+    try {
+        const response = await environment.fetch(url, {
+            ...init,
+            headers: { ...init.headers, ...identityHeaders(environment) },
+            signal: AbortSignal.timeout(timeoutMilliseconds)
+        });
+        // The body is of no interest, and an unread one holds the connection.
+        await response.body?.cancel();
+        return { status: response.status, milliseconds: environment.now().getTime() - started };
+    }
+    catch (error) {
+        throw networkFailure(error, url, timeoutMilliseconds);
+    }
+}

package/dist/config.js

@@ -0,0 +1,98 @@
+import { join, resolve } from 'node:path';
+import { DEFAULT_MCP_URL, DEFAULT_PROFILE, DEFAULT_TIMEOUT_SECONDS, PROFILE_NAME, UPDATE_CHECK_CONFIG } from "./constants.js";
+import { usageError } from "./errors.js";
+import { loadContractsInfo } from "./manifest/load.js";
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** An address from the environment: https, or http only for this machine, so a key is never sent in the clear to another. */
+function checkedUrl(name, value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw usageError(`${name} is not an address: ${value}`);
+    }
+    const local = LOCAL_HOSTS.has(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
+        throw usageError(`${name} must be an https address (http is only accepted for localhost): ${value}`);
+    }
+    return url;
+}
+export function configDirectory(environment) {
+    const explicit = environment.env.WIDGETIC_CONFIG_DIR?.trim();
+    if (explicit)
+        return resolve(environment.cwd, explicit);
+    if (environment.platform === 'win32') {
+        return join(environment.env.APPDATA?.trim() || join(environment.homeDir, 'AppData', 'Roaming'), 'widgetic');
+    }
+    return join(environment.env.XDG_CONFIG_HOME?.trim() || join(environment.homeDir, '.config'), 'widgetic');
+}
+/** A switch variable is on when it is set to something other than nothing, `0`, `false`, `no` or `off`. */
+function isSwitchedOn(value) {
+    const text = value?.trim().toLowerCase() ?? '';
+    return text !== '' && !['0', 'false', 'no', 'off'].includes(text);
+}
+/**
+ * Whether the environment says this run must not look for a newer version: a person turned it off
+ * (`NO_UPDATE_NOTIFIER`, `WIDGETIC_NO_UPDATE_CHECK`), or it is a CI job (`CI`). The word is the reason, for `WIDGETIC_DEBUG`.
+ */
+export function updateCheckSwitchedOffBy(environment) {
+    for (const name of ['NO_UPDATE_NOTIFIER', 'WIDGETIC_NO_UPDATE_CHECK', 'CI']) {
+        if (isSwitchedOn(environment.env[name]))
+            return name;
+    }
+    return undefined;
+}
+/**
+ * The registry the look for a newer version asks: `npm_config_registry` (npm's own variable) when it is an https
+ * address (http only for this machine), else the public registry. A value that is not an address, or that carries a
+ * user name or password (which would end up in a debug line), is ignored, not an error: a look for an update is never
+ * the reason a command fails.
+ */
+export function npmRegistryUrl(environment) {
+    const configured = (environment.env.npm_config_registry ?? environment.env.NPM_CONFIG_REGISTRY)?.trim();
+    if (configured) {
+        try {
+            const url = new URL(configured);
+            const local = LOCAL_HOSTS.has(url.hostname);
+            const carriesCredentials = url.username !== '' || url.password !== '';
+            if (!carriesCredentials && (url.protocol === 'https:' || (url.protocol === 'http:' && local))) {
+                return url.href.replace(/\/+$/, '');
+            }
+        }
+        catch {
+            // Not an address: the public registry is asked.
+        }
+    }
+    return UPDATE_CHECK_CONFIG.REGISTRY_URL;
+}
+/** The profile named by `--profile`, else by `WIDGETIC_PROFILE`, else the default one. */
+export function profileName(environment, fromFlag) {
+    const name = fromFlag?.trim() || environment.env.WIDGETIC_PROFILE?.trim() || DEFAULT_PROFILE;
+    if (!PROFILE_NAME.test(name)) {
+        throw usageError(`"${name}" is not a profile name: use letters, digits, dots, hyphens and underscores (at most 64).`);
+    }
+    return name;
+}
+/**
+ * `manifestApiUrl` is the server of the REST manifest when the command has it loaded; the others (the MCP commands,
+ * `auth`, `doctor`) read the same address from the small `contracts.json` and never load the whole description.
+ */
+export function resolveSettings(environment, options) {
+    const contractUrl = options.manifestApiUrl ?? loadContractsInfo().openApi.servers[0];
+    if (!contractUrl)
+        throw new Error('generated/contracts.json names no server: this build of @widgetic/cli is incomplete.');
+    const apiUrl = checkedUrl('WIDGETIC_API_URL', environment.env.WIDGETIC_API_URL?.trim() || contractUrl);
+    const mcpUrl = checkedUrl('WIDGETIC_MCP_URL', environment.env.WIDGETIC_MCP_URL?.trim() || DEFAULT_MCP_URL);
+    return {
+        profile: profileName(environment, options.profile),
+        apiUrl: apiUrl.href.replace(/\/+$/, ''),
+        apiRootUrl: apiUrl.origin,
+        mcpUrl: mcpUrl.href,
+        configDir: configDirectory(environment)
+    };
+}
+/** The seconds `--timeout` gave, or the default; the flag is checked when it is parsed. */
+export function timeoutMilliseconds(seconds) {
+    return (seconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000;
+}

package/dist/confirm.js

@@ -0,0 +1,15 @@
+import { CliError, EXIT_CODES, usageError } from "./errors.js";
+export async function confirmOrStop(environment, input) {
+    if (input.yes)
+        return;
+    if (input.json || environment.confirm === undefined) {
+        throw usageError(`${input.what}, and there is nobody to ask: nothing was sent.`, 'Run it again with --yes to go ahead.');
+    }
+    if (await environment.confirm(`${input.what}. Continue?`))
+        return;
+    throw new CliError({
+        code: 'CANCELLED',
+        message: 'Cancelled: nothing was sent.',
+        exitCode: EXIT_CODES.failure
+    });
+}

package/dist/constants.js

@@ -0,0 +1,51 @@
+/**
+ * Settings of the CLI that are not secrets: addresses, limits, intervals. They are constants, read where they are used,
+ * and the same for everybody; the only things a person sets are an API key, to point the CLI at another environment
+ * the two addresses (`WIDGETIC_API_URL`, `WIDGETIC_MCP_URL`), and, to stop it looking for a newer version of itself,
+ * `NO_UPDATE_NOTIFIER` or `WIDGETIC_NO_UPDATE_CHECK`.
+ */
+/** The public MCP endpoint. The REST address is not here: it is the server of the OpenAPI description the CLI was generated from. */
+export const DEFAULT_MCP_URL = 'https://mcp.widgetic.com/';
+/** The profile that holds the key `widgetic auth login` saved when no other is named. */
+export const DEFAULT_PROFILE = 'default';
+/** A profile is named like a file: letters, digits, dots, hyphens and underscores. */
+export const PROFILE_NAME = /^[A-Za-z0-9._-]{1,64}$/;
+/** What a Widgetic API key looks like (`wgt_usr_…`, `wgt_prt_…`, `wdg_org_…`): used to warn about a value that is not one, never to refuse one. */
+export const API_KEY_SHAPE = /^(?:wgt_(?:adm|prt|usr)|wdg_org)_[A-Za-z0-9]{16,}$/;
+/** Seconds a call may take before the CLI gives up on it; `--timeout` changes it. */
+export const DEFAULT_TIMEOUT_SECONDS = 60;
+/**
+ * Retries. A call is tried at most `MAX_ATTEMPTS` times, waiting `BASE_DELAY_MS`, then three times as long, between
+ * tries; a server that says how long to wait (`Retry-After`) is believed, up to `MAX_RETRY_AFTER_SECONDS`: a longer
+ * wait is the error's business and is reported with the exit code for "rate limited".
+ */
+export const RETRY_CONFIG = {
+    MAX_ATTEMPTS: 3,
+    BASE_DELAY_MS: 500,
+    GROWTH_FACTOR: 3,
+    MAX_RETRY_AFTER_SECONDS: 30
+};
+/** How long after it said so the CLI stays quiet about a server whose tool contract is not the one it was built for. */
+export const CONTRACT_NOTE_INTERVAL_HOURS = 24;
+/**
+ * Looking for a newer version of the CLI and offering it (`src/update`). The look is one small request to npm, made
+ * beside a command on a terminal, at most once a day; the offer is a question, asked after the command has finished.
+ */
+export const UPDATE_CHECK_CONFIG = {
+    /** The public npm registry. `npm_config_registry` replaces it for a person whose installs come from a mirror. */
+    REGISTRY_URL: 'https://registry.npmjs.org',
+    /** After a look that worked, how long its answer is believed before npm is asked again. */
+    CHECK_INTERVAL_HOURS: 24,
+    /** After a look that failed (offline, npm down), how long before the next try. */
+    RETRY_AFTER_FAILURE_HOURS: 1,
+    /** How long npm has to answer the look that runs beside a command: a slow registry must not slow a command. */
+    BACKGROUND_TIMEOUT_MILLISECONDS: 2_000,
+    /** How long `widgetic update`, which a person asked for, waits for npm. */
+    COMMAND_TIMEOUT_MILLISECONDS: 15_000,
+    /** After a no (or no answer), how long the same version is not offered again; a newer one is offered at once. */
+    SNOOZE_DAYS: 7,
+    /** How long the question waits before it counts as a no: an agent in a pseudo-terminal cannot answer it. */
+    PROMPT_TIMEOUT_SECONDS: 20
+};
+/** Longest stretch of a command's description shown in `--help`; the whole text is in `widgetic schema`. */
+export const HELP_DESCRIPTION_LIMIT = 700;

package/dist/contract-note.js

@@ -0,0 +1,42 @@
+import { CONTRACT_NOTE_INTERVAL_HOURS } from "./constants.js";
+import { isRecord } from "./http.js";
+import { note } from "./output.js";
+import { readState, writeStateKey } from "./state.js";
+/**
+ * The one thing the CLI says unasked about the server: its tool contract is not the one this build was generated from,
+ * so a command may be missing or a flag may have changed. It is said once in 24 hours for the same pair of versions, on
+ * stderr, never with `--json` (the stderr of a program that asked for JSON holds errors only).
+ *
+ * What was said, and when, is kept under `contractNote` in `state.json` beside the credentials (`state.ts`). A state that
+ * cannot be read or written is not a problem: the note is simply said again.
+ */
+const STATE_KEY = 'contractNote';
+async function readRecord(environment, configDir) {
+    const record = (await readState(environment, configDir))[STATE_KEY];
+    if (isRecord(record) &&
+        typeof record.server === 'string' &&
+        typeof record.expected === 'string' &&
+        typeof record.at === 'string') {
+        return { server: record.server, expected: record.expected, at: record.at };
+    }
+    return undefined;
+}
+export async function noteContractDifference(environment, settings, input) {
+    if (input.json || input.server === undefined || input.server === input.expected)
+        return;
+    const last = await readRecord(environment, settings.configDir);
+    const now = environment.now();
+    if (last && last.server === input.server && last.expected === input.expected) {
+        const age = now.getTime() - Date.parse(last.at);
+        if (age >= 0 && age < CONTRACT_NOTE_INTERVAL_HOURS * 3_600_000)
+            return;
+    }
+    note(environment, `note: the Widgetic server speaks tool contract ${input.server}; this CLI was built for ${input.expected}, so a command or a flag may be missing or different. Update it: npm install -g @widgetic/cli@latest`);
+    try {
+        const record = { server: input.server, expected: input.expected, at: now.toISOString() };
+        await writeStateKey(environment, settings.configDir, STATE_KEY, record);
+    }
+    catch {
+        // Not remembered: said again next time, which is harmless.
+    }
+}

package/dist/credentials.js

@@ -0,0 +1,111 @@
+import { join } from 'node:path';
+import { DEFAULT_PROFILE } from "./constants.js";
+import { CliError, EXIT_CODES } from "./errors.js";
+const FILE_NAME = 'credentials.json';
+function damaged(path, why) {
+    return new CliError({
+        code: 'CREDENTIALS_FILE_INVALID',
+        message: `The credentials file ${path} cannot be used: ${why}`,
+        exitCode: EXIT_CODES.auth,
+        hint: 'Delete it and run `widgetic auth login` again, or set WIDGETIC_API_KEY.'
+    });
+}
+function isStoredProfile(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.apiKey === 'string' &&
+        typeof value.savedAt === 'string');
+}
+export class CredentialStore {
+    path;
+    environment;
+    constructor(environment, directory) {
+        this.environment = environment;
+        this.path = join(directory, FILE_NAME);
+    }
+    /** The saved profiles; no file is an empty list, a file that is not ours is an error (nothing is overwritten by guessing). */
+    async read() {
+        const found = await this.environment.fs.stat(this.path);
+        if (!found)
+            return { version: 1, profiles: {} };
+        let parsed;
+        try {
+            parsed = JSON.parse(new TextDecoder().decode(await this.environment.fs.readFile(this.path)));
+        }
+        catch (error) {
+            throw damaged(this.path, error instanceof Error ? error.message : String(error));
+        }
+        const profiles = parsed?.profiles;
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            parsed.version !== 1 ||
+            typeof profiles !== 'object' ||
+            profiles === null) {
+            throw damaged(this.path, 'it is not a credentials file of this version of the CLI.');
+        }
+        for (const [name, profile] of Object.entries(profiles)) {
+            if (!isStoredProfile(profile))
+                throw damaged(this.path, `the profile "${name}" has no key.`);
+        }
+        return { version: 1, profiles: { ...profiles } };
+    }
+    async get(profile) {
+        return (await this.read()).profiles[profile];
+    }
+    async save(profile, apiKey) {
+        const file = await this.read();
+        file.profiles[profile] = { apiKey, savedAt: this.environment.now().toISOString() };
+        await this.environment.fs.writeFilePrivately(this.path, `${JSON.stringify(file, null, 2)}\n`);
+    }
+    /** Forgets a profile; `false` when there was none. The file goes with its last profile. */
+    async remove(profile) {
+        const file = await this.read();
+        if (!(profile in file.profiles))
+            return false;
+        delete file.profiles[profile];
+        if (Object.keys(file.profiles).length === 0)
+            await this.environment.fs.remove(this.path);
+        else
+            await this.environment.fs.writeFilePrivately(this.path, `${JSON.stringify(file, null, 2)}\n`);
+        return true;
+    }
+    /** Whether other users of this machine can read the file (POSIX permissions); `false` where there are none to read. */
+    async isReadableByOthers() {
+        if (this.environment.platform === 'win32')
+            return false;
+        const found = await this.environment.fs.stat(this.path);
+        return found !== undefined && (found.mode & 0o077) !== 0;
+    }
+}
+/** The key a call is made with, or `undefined` when there is none; `WIDGETIC_API_KEY` wins over a saved one. */
+export async function resolveApiKey(environment, store, profile) {
+    const fromEnvironment = environment.env.WIDGETIC_API_KEY?.trim();
+    if (fromEnvironment)
+        return { apiKey: fromEnvironment, source: 'environment', profile };
+    const saved = await store.get(profile);
+    return saved ? { apiKey: saved.apiKey, source: 'file', profile } : undefined;
+}
+/** The error for a call that needs a key and has none (exit 3, nothing was sent). */
+export function noApiKey(settings) {
+    return new CliError({
+        code: 'NO_API_KEY',
+        message: settings.profile === DEFAULT_PROFILE
+            ? 'No API key.'
+            : `No API key is saved for the profile "${settings.profile}".`,
+        exitCode: EXIT_CODES.auth,
+        hint: 'Run `widgetic auth login` with an API key, or set WIDGETIC_API_KEY.'
+    });
+}
+/** The key for a call that carries one, or the error that says how to get one (exit 3, nothing was sent). */
+export async function requireApiKey(environment, settings) {
+    const found = await resolveApiKey(environment, new CredentialStore(environment, settings.configDir), settings.profile);
+    if (found)
+        return found;
+    throw noApiKey(settings);
+}
+/** `wgt_usr_…a1b2`: enough to tell two keys apart, nothing that works as a key. */
+export function maskKey(apiKey) {
+    if (apiKey.length <= 12)
+        return '…';
+    return `${apiKey.slice(0, 8)}…${apiKey.slice(-4)}`;
+}

package/dist/environment.js

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+/** Whether a person is at the terminal: both ends of a question are terminals. */
+function hasTerminal() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+/**
+ * Asks one question on the terminal and answers what was typed. It rejects when the question is closed before it is
+ * answered (Ctrl-C or Ctrl-D): the caller decides what that means.
+ */
+export function askOnTerminal(question, options = {}) {
+    const hidden = options.hidden === true;
+    const streams = options.streams ?? { input: process.stdin, output: process.stderr };
+    return new Promise((resolve, reject) => {
+        const readline = createInterface({ input: streams.input, output: streams.output, terminal: true });
+        let timer;
+        let timedOut = false;
+        let answered = false;
+        if (hidden) {
+            // Muting the echo: the question is written once, then every character the person types is swallowed.
+            const mutable = readline;
+            const original = mutable._writeToOutput.bind(readline);
+            let questionWritten = false;
+            mutable._writeToOutput = (text) => {
+                if (!questionWritten) {
+                    questionWritten = true;
+                    original(text);
+                }
+            };
+        }
+        readline.question(question, (answer) => {
+            // Said before the interface is closed: closing it emits 'close' at once, and that handler must know that this
+            // is an answer and not a question that was given up (it used to reject every answered question).
+            answered = true;
+            clearTimeout(timer);
+            readline.close();
+            if (hidden)
+                streams.output.write('\n');
+            resolve(answer);
+        });
+        readline.once('close', () => {
+            clearTimeout(timer);
+            if (answered)
+                return;
+            if (timedOut)
+                resolve('');
+            else
+                reject(new Error('the question was closed before it was answered'));
+        });
+        if (options.timeoutMilliseconds !== undefined) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                // The question was left on its line: the next text starts on a new one.
+                streams.output.write('\n');
+                readline.close();
+            }, options.timeoutMilliseconds);
+        }
+    });
+}
+const isMissing = (error) => typeof error === 'object' && error !== null && error.code === 'ENOENT';
+/** The files of this machine. */
+export function realFileSystem() {
+    return {
+        readFile: async (path) => new Uint8Array(await readFile(path)),
+        stat: async (path) => {
+            try {
+                const found = await stat(path);
+                return {
+                    size: found.size,
+                    mode: found.mode & 0o777,
+                    isFile: found.isFile(),
+                    isDirectory: found.isDirectory()
+                };
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return undefined;
+                throw error;
+            }
+        },
+        writeFilePrivately: async (path, text) => {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            // Written beside the file and moved over it: a reader sees the old file or the new one, never half of one.
+            const scratch = `${path}.${process.pid}.tmp`;
+            try {
+                await writeFile(scratch, text, { mode: 0o600 });
+                // `mode` above is subject to the umask and to a scratch file that already existed: say it again.
+                await chmod(scratch, 0o600);
+                await rename(scratch, path);
+            }
+            catch (error) {
+                await rm(scratch, { force: true });
+                throw error;
+            }
+        },
+        remove: async (path) => {
+            await rm(path, { force: true });
+        }
+    };
+}
+/** The real thing: this process. */
+export function realEnvironment() {
+    const terminal = hasTerminal();
+    return {
+        env: process.env,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        stdin: process.stdin,
+        fs: realFileSystem(),
+        fetch: globalThis.fetch.bind(globalThis),
+        now: () => new Date(),
+        sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        randomUUID,
+        homeDir: homedir(),
+        platform: process.platform,
+        cwd: process.cwd(),
+        nodeVersion: process.versions.node,
+        // `dist/` and `src/` are both one folder below the package root (the same fact `version.ts` relies on).
+        packageFolder: resolve(fileURLToPath(new URL('../', import.meta.url))),
+        confirm: terminal
+            ? async (question, options) => /^y(es)?$/i.test((await askOnTerminal(`${question} [y/N] `, {
+                timeoutMilliseconds: options?.timeoutMilliseconds
+            })).trim())
+            : undefined,
+        promptSecret: terminal ? (question) => askOnTerminal(question, { hidden: true }) : undefined,
+        runProgram: (command, args, options) => new Promise((resolveExitCode) => {
+            const child = spawn(command, [...args], {
+                stdio: options?.showOutput === false ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+                // npm is `npm.cmd` on Windows, which Node starts only through a shell. What is run there is fixed
+                // words and a version that was checked to be digits and dots, so nothing a server sent reaches a shell.
+                shell: process.platform === 'win32'
+            });
+            child.once('error', () => resolveExitCode(null));
+            child.once('close', (code) => resolveExitCode(code));
+        })
+    };
+}
+/** Reads a stream to its end as UTF-8 text (a document given on stdin with `-`). */
+export async function readAll(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}

package/dist/errors.js

@@ -0,0 +1,67 @@
+/**
+ * Exit codes and the error every command ends in.
+ *
+ * An agent that runs `widgetic` reads the exit code before it reads anything else, so the table is the contract:
+ *
+ *   0  ok
+ *   1  anything else (a bug, a 5xx that is not "unavailable", a build that did not finish in time)
+ *   2  usage or validation: the command line, a flag value or a JSON document is wrong; nothing was sent
+ *   3  authentication or plan refusal: no key, 401, 402, 403 (a key without the scope, a plan without API access)
+ *   4  not found (404, 410)
+ *   5  rejected by the server: 400, 409, 422 and the other 4xx answers; an MCP tool result with `isError`
+ *   6  rate limited or unavailable: 429, 502, 503, 504, a timeout or a network that cannot be reached (honours Retry-After)
+ *   7  this CLI is too old: 426 (the gateway's SDK version gate); the error carries the upgrade command
+ */
+export const EXIT_CODES = {
+    ok: 0,
+    failure: 1,
+    usage: 2,
+    auth: 3,
+    notFound: 4,
+    rejected: 5,
+    unavailable: 6,
+    upgrade: 7
+};
+export class CliError extends Error {
+    code;
+    exitCode;
+    status;
+    requestId;
+    retryAfter;
+    details;
+    hint;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = 'CliError';
+        this.code = init.code;
+        this.exitCode = init.exitCode;
+        this.status = init.status;
+        this.requestId = init.requestId;
+        this.retryAfter = init.retryAfter;
+        this.details = init.details;
+        this.hint = init.hint;
+    }
+}
+/** The command line, a flag value or a document is wrong. Nothing was sent. */
+export function usageError(message, hint) {
+    return new CliError({ code: 'USAGE_ERROR', message, exitCode: EXIT_CODES.usage, hint });
+}
+/** A document the user gave does not match the contract's schema. Nothing was sent. */
+export function validationError(message, details, hint) {
+    return new CliError({ code: 'VALIDATION_ERROR', message, exitCode: EXIT_CODES.usage, details, hint });
+}
+/** The exit code of an HTTP answer that was not a success. */
+export function exitCodeForStatus(status) {
+    if (status === 401 || status === 402 || status === 403)
+        return EXIT_CODES.auth;
+    if (status === 404 || status === 410)
+        return EXIT_CODES.notFound;
+    if (status === 426)
+        return EXIT_CODES.upgrade;
+    if (status === 408 || status === 429 || status === 502 || status === 503 || status === 504) {
+        return EXIT_CODES.unavailable;
+    }
+    if (status >= 400 && status < 500)
+        return EXIT_CODES.rejected;
+    return EXIT_CODES.failure;
+}