@widgetic/cli 0.0.0-stage → 0.1.2

package/dist/mcp/session.js

@@ -0,0 +1,186 @@
+import { KEY_REFUSED_HINT } from "../constants.js";
+import { CliError, EXIT_CODES, exitCodeForStatus } from "../errors.js";
+import { errorFromAnswer, isRecord, networkFailure, readAnswer } from "../http.js";
+import { cliVersion, identityHeaders } from "../version.js";
+/** Reads a `tools/call` result: the data, the text, whether it is a refusal. */
+export function outcomeOf(result) {
+    const record = isRecord(result) ? result : {};
+    const content = Array.isArray(record.content) ? record.content : [];
+    const text = content
+        .filter((block) => isRecord(block) && block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n\n');
+    const meta = isRecord(record._meta) ? record._meta : {};
+    return {
+        isError: record.isError === true,
+        structured: isRecord(record.structuredContent) ? record.structuredContent : undefined,
+        text,
+        authChallenge: 'mcp/www_authenticate' in meta
+    };
+}
+/** The error a refusal of a tool is: exit 3 when the key is not accepted, else exit 5 with the tool's own words. */
+export function refusalOf(outcome) {
+    if (outcome.authChallenge) {
+        return new CliError({
+            code: 'AUTH_REQUIRED',
+            message: outcome.text || 'The API key was not accepted.',
+            exitCode: EXIT_CODES.auth,
+            hint: KEY_REFUSED_HINT
+        });
+    }
+    return new CliError({
+        code: 'TOOL_ERROR',
+        message: outcome.text || 'The tool refused the call.',
+        exitCode: EXIT_CODES.rejected
+    });
+}
+const JSON_RPC = {
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    connectionClosed: -32000,
+    requestTimeout: -32001
+};
+function isMcpError(error) {
+    return (error instanceof Error &&
+        error.name === 'McpError' &&
+        typeof error.code === 'number');
+}
+function isHttpError(error) {
+    return error instanceof Error && error.name === 'StreamableHTTPError';
+}
+export class McpConnection {
+    /** The version the server reported when it was opened: the version of its tool contract. */
+    serverVersion;
+    client;
+    lastRefusal;
+    environment;
+    settings;
+    auth;
+    timeoutMilliseconds;
+    constructor(environment, settings, auth, timeoutMilliseconds) {
+        this.environment = environment;
+        this.settings = settings;
+        this.auth = auth;
+        this.timeoutMilliseconds = timeoutMilliseconds;
+    }
+    /** Calls a tool; throws a `CliError` for everything that is not an answer (a refusal of the tool is an answer: see `refusalOf`). */
+    async call(tool, args) {
+        this.lastRefusal = undefined;
+        try {
+            const client = await this.connected();
+            const result = await client.callTool({ name: tool, arguments: args }, undefined, {
+                timeout: this.timeoutMilliseconds
+            });
+            return outcomeOf(result);
+        }
+        catch (error) {
+            const failure = this.explain(error);
+            // A connection that failed is not trusted again: the next call opens its own.
+            await this.close();
+            throw failure;
+        }
+    }
+    /** The names of the tools the server offers (`tools/list`), to compare with the ones this CLI was built for. */
+    async listTools() {
+        this.lastRefusal = undefined;
+        try {
+            const client = await this.connected();
+            const names = [];
+            let cursor;
+            do {
+                const page = await client.listTools(cursor === undefined ? undefined : { cursor }, {
+                    timeout: this.timeoutMilliseconds
+                });
+                for (const tool of page.tools)
+                    names.push(tool.name);
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            return names;
+        }
+        catch (error) {
+            const failure = this.explain(error);
+            await this.close();
+            throw failure;
+        }
+    }
+    async close() {
+        const client = this.client;
+        this.client = undefined;
+        try {
+            await client?.close();
+        }
+        catch {
+            // Closing is a courtesy; the command's result does not depend on it.
+        }
+    }
+    async connected() {
+        if (this.client)
+            return this.client;
+        const [{ Client: SdkClient }, { StreamableHTTPClientTransport }] = await Promise.all([
+            import('@modelcontextprotocol/sdk/client/index.js'),
+            import('@modelcontextprotocol/sdk/client/streamableHttp.js')
+        ]);
+        const transport = new StreamableHTTPClientTransport(new URL(this.settings.mcpUrl), {
+            fetch: async (url, init) => {
+                const response = await this.environment.fetch(url, init);
+                // Only the answer to a message says why a call failed. The stream a client may open with GET is refused with a 405 by a server that keeps none, and that is not a failure.
+                if (!response.ok && init?.method === 'POST')
+                    this.lastRefusal = await readAnswer(response.clone());
+                return response;
+            },
+            requestInit: {
+                headers: { authorization: `Bearer ${this.auth.apiKey}`, ...identityHeaders(this.environment) }
+            }
+        });
+        const client = new SdkClient({ name: '@widgetic/cli', version: cliVersion() }, { capabilities: {} });
+        await client.connect(transport, { timeout: this.timeoutMilliseconds });
+        this.client = client;
+        this.serverVersion = client.getServerVersion()?.version;
+        return client;
+    }
+    /** What a failure of the SDK stands for, in the CLI's terms. */
+    explain(error) {
+        if (error instanceof CliError)
+            return error;
+        // The server refused at the HTTP layer (401, 403, 426, 429 …): its own envelope says what and why.
+        if (this.lastRefusal)
+            return errorFromAnswer(this.lastRefusal, this.environment.now(), this.auth.source);
+        if (isMcpError(error)) {
+            const message = error.message.replace(/^MCP error -?\d+:\s*/, '');
+            switch (error.code) {
+                case JSON_RPC.requestTimeout:
+                    return networkFailure(Object.assign(new Error(message), { name: 'TimeoutError' }), this.settings.mcpUrl, this.timeoutMilliseconds);
+                case JSON_RPC.connectionClosed:
+                    return networkFailure(error, this.settings.mcpUrl, this.timeoutMilliseconds);
+                case JSON_RPC.invalidParams:
+                case JSON_RPC.invalidRequest:
+                case JSON_RPC.methodNotFound:
+                    return new CliError({
+                        code: 'MCP_REJECTED',
+                        message,
+                        exitCode: EXIT_CODES.rejected,
+                        hint: 'The server did not accept the call. This CLI may be older than the server: `widgetic doctor` compares them.',
+                        cause: error
+                    });
+                default:
+                    return new CliError({
+                        code: `MCP_ERROR_${Math.abs(error.code)}`,
+                        message,
+                        exitCode: EXIT_CODES.failure,
+                        cause: error
+                    });
+            }
+        }
+        if (isHttpError(error) && typeof error.code === 'number' && error.code > 0) {
+            return new CliError({
+                code: `HTTP_${error.code}`,
+                message: error.message,
+                exitCode: exitCodeForStatus(error.code),
+                status: error.code,
+                cause: error
+            });
+        }
+        return networkFailure(error, this.settings.mcpUrl, this.timeoutMilliseconds);
+    }
+}

package/dist/mcp/wait.js

@@ -0,0 +1,68 @@
+import { CliError, EXIT_CODES } from "../errors.js";
+import { note } from "../output.js";
+import { WAIT_OVERLAY } from "../overlay.js";
+import { retryNotifier, withRetries } from "../retry.js";
+import { refusalOf } from "./session.js";
+/**
+ * `--wait`: a tool that starts a build answers at once with the widget's id and the phase it is in; the command then
+ * asks the poll tool again and again until the phase is one of the finished ones, and its result is the finished
+ * widget. What is waited for, and how often it is asked, is the overlay (`overlay.ts`), checked against the manifests.
+ */
+function phaseOf(outcome) {
+    const phase = outcome.structured?.[WAIT_OVERLAY.phaseProperty];
+    return typeof phase === 'string' ? phase : undefined;
+}
+export async function waitForBuild(environment, connection, started, json) {
+    const widgetId = started.structured?.[WAIT_OVERLAY.idProperty];
+    if (typeof widgetId !== 'string') {
+        throw new CliError({
+            code: 'WAIT_UNAVAILABLE',
+            message: `--wait: the answer names no widget (${WAIT_OVERLAY.idProperty}), so there is nothing to wait for.`,
+            exitCode: EXIT_CODES.failure,
+            details: started.structured
+        });
+    }
+    const readyPhases = WAIT_OVERLAY.readyPhases;
+    const failedPhases = WAIT_OVERLAY.failedPhases;
+    const clockStart = environment.now().getTime();
+    let waitedSeconds = 0;
+    let reported;
+    let outcome = started;
+    for (;;) {
+        const phase = phaseOf(outcome);
+        if (phase !== undefined && phase !== reported) {
+            reported = phase;
+            if (!json)
+                note(environment, `Widget ${widgetId}: ${phase}`);
+        }
+        if (phase !== undefined && readyPhases.includes(phase))
+            return outcome;
+        if (phase !== undefined && failedPhases.includes(phase)) {
+            throw new CliError({
+                code: 'BUILD_FAILED',
+                message: `The build of widget ${widgetId} ended in phase "${phase}".`,
+                exitCode: EXIT_CODES.rejected,
+                details: outcome.structured,
+                hint: `See the widget: widgetic mcp get-widget --${WAIT_OVERLAY.idProperty.replace(/_/g, '-')} ${widgetId}`
+            });
+        }
+        const elapsed = Math.max(waitedSeconds, (environment.now().getTime() - clockStart) / 1000);
+        if (elapsed >= WAIT_OVERLAY.defaultMaxSeconds) {
+            throw new CliError({
+                code: 'WAIT_TIMED_OUT',
+                message: `Widget ${widgetId} is still building (phase: ${phase ?? 'unknown'}) after ${Math.round(WAIT_OVERLAY.defaultMaxSeconds / 60)} minutes. It keeps going on the server.`,
+                exitCode: EXIT_CODES.failure,
+                details: outcome.structured,
+                hint: `Look again later: widgetic mcp get-widget --${WAIT_OVERLAY.idProperty.replace(/_/g, '-')} ${widgetId}`
+            });
+        }
+        await environment.sleep(WAIT_OVERLAY.pollIntervalSeconds * 1000);
+        waitedSeconds += WAIT_OVERLAY.pollIntervalSeconds;
+        outcome = await withRetries(environment, { safeToRepeat: true }, async () => {
+            const polled = await connection.call(WAIT_OVERLAY.pollTool, { [WAIT_OVERLAY.idProperty]: widgetId });
+            if (polled.isError)
+                throw refusalOf(polled);
+            return polled;
+        }, retryNotifier(environment, json));
+    }
+}

package/dist/options.js

@@ -0,0 +1,228 @@
+import { InvalidArgumentError, Option } from 'commander';
+import { HELP_DESCRIPTION_LIMIT } from "./constants.js";
+import { patternRequirement } from "./patterns.js";
+const COMMON_GROUP = 'Common options:';
+/** A cut text with no code span left open: what follows the last backtick is dropped when the backticks do not pair up. */
+function closed(text) {
+    const backticks = (text.match(/`/g) ?? []).length;
+    return backticks % 2 === 0 ? text : text.slice(0, text.lastIndexOf('`')).trimEnd();
+}
+/**
+ * The first paragraph of a text, cut at the end of a sentence when it is longer than `limit`. A cut never leaves a
+ * code span open (`409 MANAGED_USE…` with a lone backtick would turn the rest of a page into code).
+ */
+export function shorten(text, limit) {
+    const paragraph = (text.trim().split(/\n\s*\n/)[0] ?? '').replace(/\s*\n\s*/g, ' ').trim();
+    if (paragraph.length <= limit)
+        return paragraph;
+    const cut = paragraph.slice(0, limit);
+    const sentenceEnd = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('.\n'));
+    return sentenceEnd > limit / 2 ? closed(cut.slice(0, sentenceEnd + 1)) : `${closed(cut.trimEnd())}…`;
+}
+/**
+ * A paragraph of a description as one line per sentence run: the line breaks a contract's author wrapped it with are
+ * spaces again (the terminal wraps it to its own width), and the lines of a list stay lines.
+ */
+export function unwrap(paragraph) {
+    let text = '';
+    for (const line of paragraph.split('\n')) {
+        const trimmed = line.trim();
+        if (text === '')
+            text = trimmed;
+        else
+            text += /^(?:[-*•]|\d+[.)])\s/.test(trimmed) ? `\n${trimmed}` : ` ${trimmed}`;
+    }
+    return text;
+}
+/**
+ * The text a command shows in its own `--help`: whole paragraphs of its description while they fit, the first one cut
+ * at a sentence when even that is too long. The whole description, and every schema, is what `widgetic schema` prints.
+ */
+export function commandHelp(summary, description, schemaCommand, limit = HELP_DESCRIPTION_LIMIT) {
+    const full = description
+        .trim()
+        .split(/\n\s*\n/)
+        .map(unwrap)
+        .join('\n\n');
+    if (full === '')
+        return summary.trim();
+    if (full.length <= limit)
+        return full;
+    const kept = [];
+    let length = 0;
+    for (const paragraph of full.split(/\n\n/)) {
+        const next = length + paragraph.length + (kept.length > 0 ? 2 : 0);
+        if (kept.length > 0 && next > limit)
+            break;
+        kept.push(paragraph);
+        length = next;
+    }
+    const text = kept.join('\n\n');
+    return `${text.length > limit ? shorten(text, limit) : text}\n\nThe whole description and the schemas: ${schemaCommand}`;
+}
+/** How a flag shows what it takes: `<int>`, `<uuid>`, `<key=value>`; a secret takes `-` or a file, never the text itself. */
+export function placeholderOf(spec) {
+    if (spec.secret)
+        return '<@file|->';
+    switch (spec.type) {
+        case 'integer':
+            return '<int>';
+        case 'number':
+            return '<number>';
+        case 'file':
+            return '<path>';
+        case 'pairs':
+            return '<key=value>';
+        case 'string[]':
+            return '<values...>';
+        default:
+            return `<${spec.format ?? 'text'}>`;
+    }
+}
+/** Said by the help of every flag that takes a secret (`src/secrets.ts` explains why it is not typed as text). */
+const SECRET_NOTE = 'A secret: give @path to read it from a file, or - to type it where it is not shown (or to read it from standard input). It is never typed as text, and --dry-run leaves it out.';
+/** What a flag says about itself in `--help` (and in the reference generated from the same manifests). */
+export function describe(spec) {
+    const parts = [shorten(spec.description, 220)];
+    if (spec.cliDefault !== undefined) {
+        // The CLI does not do what the contract's default does (a build is a draft): say what it does, not both.
+        parts.push(`In this CLI it is ${String(spec.cliDefault)} unless you pass --${spec.flag}.`);
+    }
+    else {
+        if (spec.default !== undefined)
+            parts.push(`(default: ${String(spec.default)})`);
+        if (spec.type === 'boolean' && spec.default === true)
+            parts.push(`--no-${spec.flag} turns it off.`);
+    }
+    if (spec.type === 'pairs')
+        parts.push('Repeat it for more than one.');
+    if (spec.secret)
+        parts.push(SECRET_NOTE);
+    return parts.filter((part) => part !== '').join(' ');
+}
+/** The check a value of a flag has to pass: the contract's own limits, said as the flag. */
+function checkedString(spec, text) {
+    if (spec.minLength !== undefined && text.length < spec.minLength) {
+        throw new InvalidArgumentError(`it must have at least ${spec.minLength} characters.`);
+    }
+    if (spec.maxLength !== undefined && text.length > spec.maxLength) {
+        throw new InvalidArgumentError(`it must have at most ${spec.maxLength} characters.`);
+    }
+    if (spec.pattern !== undefined && !new RegExp(spec.pattern).test(text)) {
+        throw new InvalidArgumentError(`it must ${patternRequirement(spec.pattern)}.`);
+    }
+    return text;
+}
+function checkedNumber(spec, value) {
+    if (spec.minimum !== undefined && value < spec.minimum)
+        throw new InvalidArgumentError(`it must be at least ${spec.minimum}.`);
+    if (spec.maximum !== undefined && value > spec.maximum)
+        throw new InvalidArgumentError(`it must be at most ${spec.maximum}.`);
+    return value;
+}
+function parserFor(spec) {
+    // What a secret flag holds is `-` or `@path`, which the contract's limits say nothing about: the secret itself is
+    // checked with the rest of the document once it is read, and a text typed there is refused without being repeated.
+    if (spec.secret)
+        return undefined;
+    switch (spec.type) {
+        case 'integer':
+            return (text) => {
+                if (!/^-?\d+$/.test(text.trim()))
+                    throw new InvalidArgumentError('it must be a whole number.');
+                return checkedNumber(spec, Number(text));
+            };
+        case 'number':
+            return (text) => {
+                const value = Number(text);
+                if (text.trim() === '' || !Number.isFinite(value))
+                    throw new InvalidArgumentError('it must be a number.');
+                return checkedNumber(spec, value);
+            };
+        case 'string':
+            return spec.enum ? undefined : (text) => checkedString(spec, text);
+        case 'pairs':
+            return (text, previous) => {
+                const separator = text.indexOf('=');
+                if (separator <= 0)
+                    throw new InvalidArgumentError('it must be key=value.');
+                return {
+                    ...previous,
+                    [text.slice(0, separator)]: text.slice(separator + 1)
+                };
+            };
+        default:
+            return undefined;
+    }
+}
+export function addFlag(command, spec, options) {
+    const long = `--${spec.flag}`;
+    const label = describe(spec);
+    const text = spec.required && options.mandatory ? `${label} (required)` : label;
+    const option = spec.type === 'boolean' ? new Option(long, text) : new Option(`${long} ${placeholderOf(spec)}`, text);
+    if (spec.enum)
+        option.choices(spec.enum);
+    const parser = parserFor(spec);
+    if (parser)
+        option.argParser(parser);
+    if (options.mandatory && spec.required)
+        option.makeOptionMandatory();
+    option.helpGroup(options.group);
+    command.addOption(option);
+    if (spec.type === 'boolean') {
+        // `--no-x` is read, not listed: the description of `--x` says so when the contract's default is true.
+        command.addOption(new Option(`--no-${spec.flag}`, `The opposite of ${long}`).hideHelp());
+    }
+    return { spec, key: option.attributeName() };
+}
+/** The values the person typed, by flag name; a flag that was left out is not in the map. */
+export function readFlags(command, bindings) {
+    const options = command.opts();
+    const values = new Map();
+    for (const binding of bindings) {
+        const value = options[binding.key];
+        if (value !== undefined)
+            values.set(binding.spec.flag, value);
+    }
+    return values;
+}
+const jsonOption = () => new Option('--json', 'Print the result as one line of JSON; an error is {"error":{…}} on stderr; never ask anything.');
+const profileOption = () => new Option('--profile <name>', 'The saved API key to use (default: WIDGETIC_PROFILE, else "default").');
+const timeoutOption = () => new Option('--timeout <seconds>', 'Give up on a call after this many seconds (default: 60).').argParser((text) => {
+    if (!/^\d+$/.test(text.trim()) || Number(text) < 1)
+        throw new InvalidArgumentError('it must be a whole number of seconds, at least 1.');
+    return Number(text);
+});
+/** The options every generated command has, and `--yes` listed only where the command asks. */
+export function addCommonOptions(command, config) {
+    const add = (option) => {
+        command.addOption(option.helpGroup(COMMON_GROUP));
+    };
+    if (config.document) {
+        add(new Option(`--${config.document} <json|@file|->`, 'The document as JSON, @path to a file that holds it, or - for standard input. The flags above override its keys.'));
+    }
+    add(jsonOption());
+    add(new Option('--dry-run', 'Print what would be sent (the API key is left out) and send nothing.'));
+    const yes = new Option('--yes', 'Do not ask first: this command changes or removes something.');
+    add(config.asks ? yes : yes.hideHelp());
+    add(profileOption());
+    add(timeoutOption());
+}
+/** The options of the commands that are not generated (`auth`, `doctor`, `schema`): `--json`, and the two that go with a server. */
+export function addBasicOptions(command, config) {
+    command.addOption(jsonOption().helpGroup(COMMON_GROUP));
+    if (config.server) {
+        command.addOption(profileOption().helpGroup(COMMON_GROUP));
+        command.addOption(timeoutOption().helpGroup(COMMON_GROUP));
+    }
+}
+export function readCommon(command) {
+    const options = command.opts();
+    return {
+        json: options.json === true,
+        dryRun: options.dryRun === true,
+        yes: options.yes === true,
+        profile: typeof options.profile === 'string' ? options.profile : undefined,
+        timeout: typeof options.timeout === 'number' ? options.timeout : undefined
+    };
+}

package/dist/output.js

@@ -0,0 +1,90 @@
+import { CliError, EXIT_CODES } from "./errors.js";
+/**
+ * What a command prints, and where.
+ *
+ *   stdout   the result and nothing else (so `widgetic ... --json | jq` is always valid JSON)
+ *   stderr   everything about the run: errors, progress, notes, warnings
+ *
+ * With `--json` the result is one line of JSON and an error is one line of `{"error":{code,message,status,requestId}}`;
+ * no prompt is ever shown. Without it the result is printed for a person and an error is two or three lines.
+ */
+function withNewline(text) {
+    return text.endsWith('\n') ? text : `${text}\n`;
+}
+export function writeStdout(environment, text) {
+    environment.stdout.write(withNewline(text));
+}
+export function writeStderr(environment, text) {
+    environment.stderr.write(withNewline(text));
+}
+/** A line about the run (progress, a note) that is never part of the result. */
+export function note(environment, text) {
+    writeStderr(environment, text);
+}
+/**
+ * A line about what the CLI decided and why, for the person who asks (`WIDGETIC_DEBUG=1`); silent otherwise, so a
+ * decision that is made without a word (no look for an update on a pipe) can still be explained.
+ */
+export function debug(environment, text) {
+    if (environment.env.WIDGETIC_DEBUG === '1')
+        writeStderr(environment, `[widgetic] ${text}`);
+}
+/** Prints a result: one compact line with `--json`, readable text without. */
+export function printResult(environment, value, json) {
+    if (typeof value === 'string') {
+        writeStdout(environment, value);
+        return;
+    }
+    writeStdout(environment, json ? JSON.stringify(value) : JSON.stringify(value, null, 2));
+}
+/** What `{"error":{...}}` carries; keys without a value are left out. */
+export function errorPayload(error) {
+    const payload = { code: error.code, message: error.message };
+    if (error.status !== undefined)
+        payload.status = error.status;
+    if (error.requestId !== undefined)
+        payload.requestId = error.requestId;
+    if (error.retryAfter !== undefined)
+        payload.retryAfter = error.retryAfter;
+    if (error.details !== undefined)
+        payload.details = error.details;
+    if (error.hint !== undefined)
+        payload.hint = error.hint;
+    return { error: payload };
+}
+export function printError(environment, error, json) {
+    if (json) {
+        writeStderr(environment, JSON.stringify(errorPayload(error)));
+        return;
+    }
+    // A line of facts is for an answer from the server (its code, the status, the id to quote to support); a mistake
+    // on the command line is explained by its message alone.
+    const facts = error.status === undefined
+        ? []
+        : [
+            error.code,
+            `HTTP ${error.status}`,
+            error.requestId === undefined ? undefined : `request ${error.requestId}`,
+            error.retryAfter === undefined ? undefined : `retry after ${error.retryAfter}s`
+        ].filter((fact) => fact !== undefined);
+    const lines = [`error: ${error.message}`];
+    if (facts.length > 0)
+        lines.push(`  (${facts.join(', ')})`);
+    if (error.hint)
+        lines.push(`  ${error.hint}`);
+    writeStderr(environment, lines.join('\n'));
+}
+/** Anything thrown becomes a CliError: the ones we raise keep their exit code, the rest are exit 1. */
+export function asCliError(error, environment) {
+    if (error instanceof CliError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    const debug = environment.env.WIDGETIC_DEBUG === '1' && error instanceof Error ? `\n${error.stack ?? ''}` : '';
+    return new CliError({
+        code: 'INTERNAL_ERROR',
+        message: `${message}${debug}`,
+        exitCode: EXIT_CODES.failure,
+        hint: 'This is a bug in the CLI. Run again with WIDGETIC_DEBUG=1 and send the output to support.',
+        cause: error
+    });
+}

package/dist/overlay.js

@@ -0,0 +1,54 @@
+/**
+ * The few things about the commands that are ours and that no contract says. Everything else about a command comes
+ * from the manifests; this is the whole list, and `test/overlay.test.ts` checks every name in it against the manifests
+ * of the installed contracts, so a tool that is renamed or loses an argument fails the build instead of the command.
+ */
+/**
+ * `--wait` on the tools that start a build and answer at once: the command keeps asking the poll tool for the widget
+ * until its phase is one of the finished ones, and ends with the finished widget as its result. The contract's own
+ * words (the description of `get_widget`) are "call it every 5 to 10 seconds until phase is ready, failed or cancelled".
+ */
+export const WAIT_OVERLAY = {
+    /** The tools that get `--wait`. Each answers with the widget's id and phase. */
+    tools: ['create_widget', 'replicate_widget', 'revise_widget'],
+    /** The tool that is asked again and again. */
+    pollTool: 'get_widget',
+    /** The key of a start tool's answer that names the widget, and the argument of the poll tool that takes it. */
+    idProperty: 'widget_id',
+    /** The key of both tools' answers that says how far the build is. */
+    phaseProperty: 'phase',
+    /** The phase the build ends well in: the command exits 0 with the widget. */
+    readyPhases: ['ready'],
+    /** The phases it ends badly in: the command exits 5 with the widget as the error's details. */
+    failedPhases: ['failed', 'cancelled'],
+    /** Seconds between two asks. */
+    pollIntervalSeconds: 7,
+    /** Seconds `--wait` waits when it is given no number. */
+    defaultMaxSeconds: 900
+};
+export function isWaitTool(tool) {
+    return WAIT_OVERLAY.tools.includes(tool);
+}
+/**
+ * The line `widgetic api --help` shows beside each group of the REST API. The contract names the groups (they are the
+ * tags of its operations) and says nothing about them, so without these lines the list would be thirteen bare nouns and
+ * a person could not tell `compositions` from `canvases`. Each line is written from what the operations of the group
+ * say about themselves; a group that has none yet (a later contract adds one) is listed with the number of its commands
+ * and `test/overlay.test.ts` fails until somebody writes its line.
+ */
+export const API_GROUP_SUMMARIES = {
+    canvases: 'The canvases that hold your widgets: create, list, read, update and delete them.',
+    compositions: 'What is made from a widget: its content, design, preview, versions, data and embed settings.',
+    credits: "An account's credit balance and credit ledger.",
+    entitlements: 'The entitlements of a partner and of its managed users.',
+    invoices: "A partner's invoices.",
+    'managed-users': "A partner's managed users: their limits, design defaults and editor sessions.",
+    operations: 'The status of work that goes on after the call that started it has answered.',
+    partners: 'A partner account: analytics, billing, presets, notifications, storage and data.',
+    'public-embed': 'What the browser of a visitor calls to show and run a published widget; it needs no API key. Left out of the list.',
+    tokens: 'Check that the API key in use is valid.',
+    uploads: 'Upload files, list and delete them, and see the upload limits.',
+    users: 'Your account: API keys, the websites that may show your widgets, and adapter connections.',
+    widgets: 'Your library of widgets: list and create them, and start a composition from one.',
+    workflows: 'Workflows: create, edit, publish, pause and archive them, and restore their versions.'
+};

package/dist/patterns.js

@@ -0,0 +1,11 @@
+/**
+ * Saying what a `pattern` of a contract asks for. Nearly every pattern in the contracts is the one for an id (a UUID),
+ * and a person told to "match ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8]…" learns nothing from it.
+ */
+const UUID_PATTERN = /\[0-9a-fA-F\]\{8\}-\[0-9a-fA-F\]\{4\}-/;
+/** What the value has to be, to finish "it must …": `be a UUID`, `match the pattern ^[a-z]+$`. */
+export function patternRequirement(pattern) {
+    if (UUID_PATTERN.test(pattern))
+        return 'be a UUID (like 3f2b8c1e-5d4a-4b7e-9c1d-2a6f8e0b4c3d)';
+    return `match the pattern ${pattern}`;
+}