@widgetic/cli 0.0.0-stage → 0.1.1

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,31 @@
+/**
+ * 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);
+}

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}`;
+}

package/dist/rest/execute.js

@@ -0,0 +1,67 @@
+import { usageError } from "../errors.js";
+import { errorFromAnswer, networkFailure, readAnswer } from "../http.js";
+import { withRetries } from "../retry.js";
+async function filePart(environment, file) {
+    let bytes;
+    try {
+        bytes = await environment.fs.readFile(file.path);
+    }
+    catch (error) {
+        throw usageError(`The file ${file.path} cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return new Blob([bytes], { type: file.contentType });
+}
+async function bodyOf(environment, plan) {
+    switch (plan.body.kind) {
+        case 'json':
+            return JSON.stringify(plan.body.value);
+        case 'binary':
+            return filePart(environment, plan.body.file);
+        case 'multipart': {
+            const form = new FormData();
+            for (const field of plan.body.fields) {
+                if ('file' in field)
+                    form.append(field.name, await filePart(environment, field.file), field.file.name);
+                else
+                    form.append(field.name, field.value);
+            }
+            return form;
+        }
+        default:
+            return undefined;
+    }
+}
+/** Whether a second try of the call cannot do anything twice: it reads, or it carries an idempotency key. */
+export function isSafeToRepeat(plan) {
+    return (plan.method === 'GET' ||
+        plan.method === 'HEAD' ||
+        plan.method === 'OPTIONS' ||
+        plan.idempotencyKey !== undefined);
+}
+/** Sends the request (again, for the failures worth another try) and returns the answer, or throws what it stands for. */
+export async function sendRestRequest(environment, plan, options) {
+    const attempt = async () => {
+        const headers = new Headers(plan.headers);
+        if (plan.authenticated && options.apiKey !== undefined)
+            headers.set('authorization', `Bearer ${options.apiKey}`);
+        // Read before the request starts, so a file that cannot be read is a mistake of the command line and not a network failure.
+        const body = await bodyOf(environment, plan);
+        let answer;
+        try {
+            const response = await environment.fetch(plan.url, {
+                method: plan.method,
+                headers,
+                body,
+                signal: AbortSignal.timeout(options.timeoutMilliseconds)
+            });
+            answer = await readAnswer(response);
+        }
+        catch (error) {
+            throw networkFailure(error, plan.url, options.timeoutMilliseconds);
+        }
+        if (answer.status >= 200 && answer.status < 300)
+            return answer;
+        throw errorFromAnswer(answer, environment.now(), options.keySource);
+    };
+    return withRetries(environment, { safeToRepeat: isSafeToRepeat(plan), hasIdempotencyKey: plan.idempotencyKey !== undefined }, attempt, options.onRetry);
+}

package/dist/rest/mime.js

@@ -0,0 +1,37 @@
+import { extname } from 'node:path';
+/**
+ * The content type of a file, from its extension, for the files the API takes (images, audio, video, documents). A file
+ * with an extension this list does not know is sent as `application/octet-stream`; `--content-type` says otherwise.
+ */
+const BY_EXTENSION = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.heic': 'image/heic',
+    '.heif': 'image/heif',
+    '.avif': 'image/avif',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.aac': 'audio/aac',
+    '.flac': 'audio/flac',
+    '.m4a': 'audio/mp4',
+    '.json': 'application/json',
+    '.csv': 'text/csv',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.html': 'text/html',
+    '.zip': 'application/zip'
+};
+export const UNKNOWN_CONTENT_TYPE = 'application/octet-stream';
+/** The content type a file name suggests, or `undefined` when its extension is not one the list knows. */
+export function contentTypeOfFile(path) {
+    return BY_EXTENSION[extname(path).toLowerCase()];
+}

package/dist/rest/plan.js

@@ -0,0 +1,185 @@
+import { basename, resolve } from 'node:path';
+import { usageError } from "../errors.js";
+import { readDocument } from "../input.js";
+import { redactSecrets, withSecrets } from "../secrets.js";
+import { namedByFlag, requireValid } from "../validate.js";
+import { identityHeaders } from "../version.js";
+import { contentTypeOfFile, UNKNOWN_CONTENT_TYPE } from "./mime.js";
+/** A list is the parameter repeated; `pairs` are `name[key]=value` (the form the gateway reads for an object of strings). */
+function appendQuery(query, parameter, value) {
+    if (parameter.type === 'pairs') {
+        for (const [key, text] of Object.entries(value))
+            query.append(`${parameter.name}[${key}]`, text);
+        return;
+    }
+    for (const item of Array.isArray(value) ? value : [value])
+        query.append(parameter.name, String(item));
+}
+async function plannedFile(environment, path, flag, contentType) {
+    const absolute = resolve(environment.cwd, path);
+    const found = await environment.fs.stat(absolute);
+    if (!found)
+        throw usageError(`--${flag}: there is no file at ${absolute}.`);
+    if (!found.isFile)
+        throw usageError(`--${flag}: ${absolute} is not a file.`);
+    return {
+        path: absolute,
+        name: basename(absolute),
+        size: found.size,
+        contentType: contentType ?? contentTypeOfFile(absolute) ?? UNKNOWN_CONTENT_TYPE
+    };
+}
+async function planJsonBody(input, body) {
+    const { environment, command, data } = input;
+    // A secret flag holds `-` or `@path`: the secret it names is read first, so two readers of standard input are
+    // refused before either reads it, and a secret typed as text is refused before anything is sent.
+    const values = await withSecrets(environment, body.flags, input.values, {
+        canAsk: input.canAsk,
+        others: data === '-' ? ['data'] : []
+    });
+    const document = data === undefined ? {} : await readDocument(environment, data, 'data');
+    let given = data !== undefined;
+    for (const flag of body.flags) {
+        if (values.has(flag.flag)) {
+            // A flag is the same key of the document, and wins over the document's own.
+            document[flag.property] = values.get(flag.flag);
+            given = true;
+        }
+    }
+    if (!given && !body.required)
+        return { kind: 'none' };
+    const flagOf = new Map(body.flags.map((flag) => [flag.property, flag.flag]));
+    await requireValid(body.schema ?? {}, document, `The document of ${command.operationId}`, (path) => namedByFlag(path, flagOf));
+    return { kind: 'json', value: document };
+}
+async function planMultipartBody(input, body) {
+    const { environment, values } = input;
+    const fields = [];
+    const missing = [];
+    for (const flag of body.flags) {
+        const value = values.get(flag.flag);
+        if (value === undefined) {
+            if (flag.required)
+                missing.push(`--${flag.flag}`);
+            continue;
+        }
+        if (flag.type === 'file')
+            fields.push({
+                name: flag.property,
+                file: await plannedFile(environment, String(value), flag.flag, undefined)
+            });
+        else
+            fields.push({ name: flag.property, value: String(value) });
+    }
+    if (missing.length > 0)
+        throw usageError(`${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} required.`);
+    return { kind: 'multipart', fields };
+}
+async function planBinaryBody(input, body) {
+    const { environment, values } = input;
+    const path = values.get('file');
+    if (typeof path !== 'string')
+        throw usageError('--file is required: this command sends the bytes of a file.');
+    const accepted = body.contentTypes ?? [body.contentType];
+    const given = values.get('content-type');
+    let contentType = typeof given === 'string' ? given : undefined;
+    if (contentType !== undefined && !accepted.includes(contentType)) {
+        throw usageError(`--content-type ${contentType} is not one this command takes: ${accepted.join(', ')}.`);
+    }
+    if (contentType === undefined) {
+        const guessed = contentTypeOfFile(path);
+        if (guessed !== undefined && accepted.includes(guessed))
+            contentType = guessed;
+        else if (accepted.length === 1)
+            contentType = accepted[0];
+        else
+            throw usageError(`Say what kind of file it is with --content-type (one of: ${accepted.join(', ')}).`);
+    }
+    return { kind: 'binary', file: await plannedFile(environment, path, 'file', contentType) };
+}
+export async function planRestRequest(input) {
+    const { environment, command, settings, values } = input;
+    let path = command.path;
+    const query = new URLSearchParams();
+    const headers = { accept: 'application/json', ...identityHeaders(environment) };
+    let idempotencyKey;
+    for (const parameter of command.parameters) {
+        let value = values.get(parameter.flag);
+        if (value === undefined && parameter.role === 'idempotency-key') {
+            // A call that creates is made safe to repeat: one key for the call, the same on every try.
+            value = `cli-${environment.randomUUID()}`;
+        }
+        if (value === undefined)
+            continue;
+        if (parameter.in === 'path')
+            path = path.replace(`{${parameter.name}}`, encodeURIComponent(String(value)));
+        else if (parameter.in === 'query')
+            appendQuery(query, parameter, value);
+        else
+            headers[parameter.name.toLowerCase()] = String(value);
+        if (parameter.role === 'idempotency-key')
+            idempotencyKey = String(value);
+    }
+    let body = { kind: 'none' };
+    if (command.body) {
+        switch (command.body.kind) {
+            case 'json':
+                body = await planJsonBody(input, command.body);
+                break;
+            case 'multipart':
+                body = await planMultipartBody(input, command.body);
+                break;
+            case 'binary':
+                body = await planBinaryBody(input, command.body);
+                break;
+        }
+        if (body.kind === 'json')
+            headers['content-type'] = 'application/json';
+        if (body.kind === 'binary')
+            headers['content-type'] = body.file.contentType;
+    }
+    const base = command.server === 'root' ? settings.apiRootUrl : settings.apiUrl;
+    const queryText = query.toString();
+    return {
+        command,
+        method: command.method,
+        url: `${base}${path}${queryText === '' ? '' : `?${queryText}`}`,
+        headers,
+        authenticated: command.auth,
+        body,
+        idempotencyKey
+    };
+}
+/** What `--dry-run` prints: the request exactly as it would be sent, with the key left out. */
+export function describeRestPlan(plan) {
+    const headers = { ...plan.headers };
+    if (plan.authenticated)
+        headers.authorization = 'Bearer [redacted]';
+    const sorted = Object.fromEntries(Object.entries(headers).sort(([a], [b]) => a.localeCompare(b)));
+    const description = {
+        dryRun: true,
+        method: plan.method,
+        url: plan.url,
+        headers: sorted
+    };
+    switch (plan.body.kind) {
+        case 'json':
+            // A secret of the document is left out, wherever the contract has it (see `secrets.ts`).
+            description.body = redactSecrets(plan.body.value, plan.command.body?.schema);
+            break;
+        case 'multipart':
+            description.form = Object.fromEntries(plan.body.fields.map((field) => [
+                field.name,
+                'file' in field
+                    ? `@${field.file.path} (${field.file.size} bytes, ${field.file.contentType})`
+                    : field.value
+            ]));
+            break;
+        case 'binary':
+            description.file = `@${plan.body.file.path} (${plan.body.file.size} bytes, ${plan.body.file.contentType})`;
+            break;
+        default:
+            break;
+    }
+    return description;
+}