@widgetic/cli 0.0.0-stage → 0.1.2

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

package/dist/rest/register.js

@@ -0,0 +1,144 @@
+import { resolveSettings, timeoutMilliseconds } from "../config.js";
+import { confirmOrStop } from "../confirm.js";
+import { requireApiKey } from "../credentials.js";
+import { apiGroupSummary } from "../help.js";
+import { addCommonOptions, addFlag, commandHelp, readCommon, readFlags } from "../options.js";
+import { note, printResult } from "../output.js";
+import { retryNotifier } from "../retry.js";
+import { sendRestRequest } from "./execute.js";
+import { describeRestPlan, planRestRequest } from "./plan.js";
+/**
+ * The `api` namespace: one command for every operation of the public OpenAPI description, built from the manifest the
+ * generator wrote. A command is a group (the operation's tag) and a name (its operationId in kebab case); a path,
+ * query or header parameter is a flag, and so is each simple property of a JSON document (`--data` takes the rest).
+ */
+const PARAMETER_GROUPS = {
+    path: 'Path parameters:',
+    query: 'Query parameters:',
+    header: 'Headers:'
+};
+/** What a command prints when the server answered with something: the body as the server sent it. */
+function printAnswer(environment, answer, json) {
+    if (answer.body === undefined) {
+        // An empty answer (204): the exit code says it worked, and `--json` stdout stays empty for a program to read.
+        if (!json)
+            note(environment, 'Done.');
+        return;
+    }
+    printResult(environment, answer.body, json);
+}
+/** Runs one command: plan, then (unless `--dry-run`) confirm, find the key, send, print. */
+export async function runRestCommand(run, command, node, bindings) {
+    const { environment, manifest } = run;
+    const common = readCommon(node);
+    const values = readFlags(node, bindings);
+    const options = node.opts();
+    const data = typeof options.data === 'string' ? options.data : undefined;
+    const settings = resolveSettings(environment, { profile: common.profile, manifestApiUrl: manifest.apiUrl });
+    const plan = await planRestRequest({ environment, command, settings, values, data, canAsk: !common.json });
+    if (common.dryRun) {
+        printResult(environment, describeRestPlan(plan), common.json);
+        return;
+    }
+    if (command.confirm) {
+        await confirmOrStop(environment, {
+            what: `${plan.method} ${new URL(plan.url).pathname} changes or removes something`,
+            yes: common.yes,
+            json: common.json
+        });
+    }
+    const key = plan.authenticated ? await requireApiKey(environment, settings) : undefined;
+    const answer = await sendRestRequest(environment, plan, {
+        apiKey: key?.apiKey,
+        keySource: key?.source,
+        timeoutMilliseconds: timeoutMilliseconds(common.timeout),
+        onRetry: retryNotifier(environment, common.json)
+    });
+    printAnswer(environment, answer, common.json);
+}
+/**
+ * What the flag of an idempotency key says. The contract's own text starts with "Required: a call without it is refused",
+ * which is true of the API and not of the CLI, and it is too long for `--help` to show whole: the limits are checked
+ * against the contract and named by the error when a key is wrong, so they are not repeated here.
+ */
+const IDEMPOTENCY_KEY_HELP = 'Names this one request, so a repeat of it is carried out once. The CLI makes a key when this is left out and sends the same one on every try; give your own (a UUID is ideal) to repeat the call by hand later.';
+/**
+ * A parameter as the flag shows it (in `--help` and in the generated reference): the CLI makes the idempotency key
+ * itself, so it is never demanded.
+ */
+export function flagSpecOf(parameter) {
+    if (parameter.role !== 'idempotency-key')
+        return parameter;
+    return { ...parameter, required: false, description: IDEMPOTENCY_KEY_HELP };
+}
+/**
+ * The kind of key an operation needs, when it is not just any: said at the end of its help (so a limit on the length of
+ * the description cannot cut it), because a 403 is the only other way to learn it.
+ */
+export function accessNote(command) {
+    if (command.accessLevel === 'partner')
+        return 'Needs a partner API key (wgt_prt_…).';
+    if (!command.auth)
+        return 'Needs no API key: browsers call it, and none is sent.';
+    return undefined;
+}
+function registerCommand(parent, group, command, run) {
+    const access = accessNote(command);
+    const help = commandHelp(command.summary, command.description, `widgetic schema api ${group.name} ${command.name}`);
+    const node = parent
+        .command(command.name, { hidden: command.hidden })
+        .summary(command.summary)
+        .description(access === undefined ? help : `${help}\n\n${access}`);
+    for (const alias of command.aliases)
+        node.alias(alias);
+    const bindings = [];
+    for (const parameter of command.parameters) {
+        bindings.push(addFlag(node, flagSpecOf(parameter), { mandatory: true, group: PARAMETER_GROUPS[parameter.in] }));
+    }
+    const body = command.body;
+    if (body?.kind === 'json') {
+        for (const flag of body.flags)
+            bindings.push(addFlag(node, flag, { mandatory: false, group: 'Fields of the document:' }));
+    }
+    else if (body?.kind === 'multipart') {
+        for (const flag of body.flags)
+            bindings.push(addFlag(node, flag, { mandatory: true, group: 'Form fields:' }));
+    }
+    else if (body?.kind === 'binary') {
+        const accepted = body.contentTypes ?? [body.contentType];
+        bindings.push(addFlag(node, {
+            flag: 'file',
+            name: 'file',
+            type: 'file',
+            required: true,
+            description: 'The file to send: its bytes are the body of the request.'
+        }, { mandatory: true, group: 'The file:' }), addFlag(node, {
+            flag: 'content-type',
+            name: 'content-type',
+            type: 'string',
+            required: false,
+            description: 'What kind of file it is; guessed from the file name when left out.',
+            enum: accepted
+        }, { mandatory: false, group: 'The file:' }));
+    }
+    addCommonOptions(node, { asks: command.confirm, document: body?.kind === 'json' ? 'data' : undefined });
+    node.action(async () => {
+        await runRestCommand(run, command, node, bindings);
+    });
+}
+/**
+ * Adds the groups of the manifest, and their commands, under `api`. A group is listed with the line of
+ * `apiGroupSummary` (what it works on, and the key it needs when that is a partner's), which is also the first line
+ * of its own help: the contract names the group and says nothing else about it.
+ */
+export function registerRestCommands(api, manifest, environment) {
+    const run = { environment, manifest };
+    for (const group of manifest.groups) {
+        const node = api
+            .command(group.name, { hidden: group.hidden })
+            .summary(apiGroupSummary(group))
+            .description(apiGroupSummary(group));
+        for (const command of group.commands)
+            registerCommand(node, group, command, run);
+    }
+}

package/dist/retry.js

@@ -0,0 +1,49 @@
+import { RETRY_CONFIG } from "./constants.js";
+import { CliError } from "./errors.js";
+import { note } from "./output.js";
+const UNPROCESSED = new Set([429]);
+const LOST = new Set([502, 503, 504]);
+/** Milliseconds to wait before the next try, or `undefined` when the failure is not one to try again. */
+export function retryDelay(error, attempt, rules) {
+    if (attempt >= RETRY_CONFIG.MAX_ATTEMPTS)
+        return undefined;
+    const status = error.status;
+    const lost = error.code === 'NETWORK_ERROR' || error.code === 'TIMEOUT' || (status !== undefined && LOST.has(status));
+    const refusedFirst = (status !== undefined && UNPROCESSED.has(status)) ||
+        (status === 409 && rules.hasIdempotencyKey === true && error.code === 'CONFLICT_IDEMPOTENCY_IN_PROGRESS');
+    if (!refusedFirst && !(lost && rules.safeToRepeat))
+        return undefined;
+    if (error.retryAfter !== undefined) {
+        // A server that asks for a long wait is believed, and reported: the caller decides whether to wait that long.
+        if (error.retryAfter > RETRY_CONFIG.MAX_RETRY_AFTER_SECONDS)
+            return undefined;
+        return Math.max(error.retryAfter, 0) * 1000;
+    }
+    return RETRY_CONFIG.BASE_DELAY_MS * RETRY_CONFIG.GROWTH_FACTOR ** (attempt - 1);
+}
+/** The note a person reads while the CLI waits to try again; `--json` gets none, its stderr holds errors only. */
+export function retryNotifier(environment, json) {
+    return (error, delayMilliseconds, nextAttempt) => {
+        if (json)
+            return;
+        const seconds = Math.max(1, Math.round(delayMilliseconds / 1000));
+        note(environment, `${error.message} Trying again in ${seconds}s (attempt ${nextAttempt} of ${RETRY_CONFIG.MAX_ATTEMPTS}).`);
+    };
+}
+/** Runs `attempt` until it succeeds or fails for good; `onRetry` hears about each wait (for a note on stderr). */
+export async function withRetries(environment, rules, attempt, onRetry) {
+    for (let tries = 1;; tries += 1) {
+        try {
+            return await attempt();
+        }
+        catch (error) {
+            if (!(error instanceof CliError))
+                throw error;
+            const delay = retryDelay(error, tries, rules);
+            if (delay === undefined)
+                throw error;
+            onRetry?.(error, delay, tries + 1);
+            await environment.sleep(delay);
+        }
+    }
+}

package/dist/secrets.js

@@ -0,0 +1,149 @@
+import { resolve } from 'node:path';
+import { readAll } from "./environment.js";
+import { usageError } from "./errors.js";
+/**
+ * Secrets. A value the contract says is a secret (`format: password`, or `writeOnly`: the server takes it and never
+ * gives it back) is the key of an adapter, the secret half of a storage key or a database connection string. It is
+ * handled in three ways, so that it does not end up where a person did not look:
+ *
+ *  - it is never the text of a flag: what is typed on a command line stays in the shell's history and in the list of
+ *    processes. The flag takes `-` (ask on the terminal, or read standard input) or `@path` (read a file), the way
+ *    `--data` does, and a value typed on the command line is refused without being repeated;
+ *  - `--dry-run` prints `[redacted]` in its place, whether it came from a flag or from the document of `--data`;
+ *  - nothing else prints it: an error names the flag, never the value.
+ *
+ * Which values are secrets is the contract's word, not a list of names in this program: a new secret field is covered
+ * the day the gateway marks it, and the generator stops (`scripts/lib/`) at a secret it has no safe way to take.
+ */
+/** What `--dry-run` prints in the place of a secret. */
+export const REDACTED = '[redacted]';
+/** A secret the person gave as the text of a flag: refused, and the text is not repeated. */
+function typedOnTheCommandLine(flag) {
+    return usageError(`--${flag} takes a secret, and a secret typed on the command line stays in the shell's history: give @path to read it from a file, or - to type it where it is not shown (or to read it from standard input).`, 'Or put it in the document of --data, which a file or standard input can hold.');
+}
+/** Whether a `-` asks on the terminal (hidden): there is a terminal, and the command may ask (`--json` never does). */
+function asksOnTerminal(environment, canAsk) {
+    return canAsk && environment.promptSecret !== undefined;
+}
+/**
+ * The secret a flag names: `-` asks on the terminal (hidden) when there is one and the command may ask, and reads
+ * standard input when not; `@path` reads a file. The line break at the end of a file or a pipe is not part of the secret.
+ */
+export async function readSecret(environment, source, flag, canAsk) {
+    let text;
+    if (source === '-') {
+        text =
+            canAsk && environment.promptSecret !== undefined
+                ? await environment.promptSecret(`--${flag} (it is not shown): `)
+                : await readAll(environment.stdin);
+    }
+    else if (source.startsWith('@') && source.length > 1) {
+        const path = resolve(environment.cwd, source.slice(1));
+        try {
+            text = new TextDecoder().decode(await environment.fs.readFile(path));
+        }
+        catch {
+            throw usageError(`--${flag}: the file ${path} cannot be read.`);
+        }
+    }
+    else {
+        throw typedOnTheCommandLine(flag);
+    }
+    const secret = text.replace(/[\r\n]+$/, '');
+    if (secret === '')
+        throw usageError(`--${flag}: the secret is empty.`);
+    return secret;
+}
+/**
+ * The values the person typed, with the `-` or `@path` of each secret flag replaced by the secret it names. Only one
+ * source can be standard input: two readers of it are stopped before either reads. (A `-` that asks on the terminal
+ * does not read standard input, so nothing is shared then.)
+ */
+export async function withSecrets(environment, flags, values, options) {
+    const resolved = new Map(values);
+    const given = flags.filter((flag) => flag.secret === true && typeof values.get(flag.flag) === 'string');
+    if (!asksOnTerminal(environment, options.canAsk)) {
+        const dashed = given.filter((flag) => values.get(flag.flag) === '-').map((flag) => flag.flag);
+        const readers = [...(options.others ?? []), ...dashed];
+        if (readers.length > 1) {
+            throw usageError(`${readers.map((name) => `--${name}`).join(' and ')} all read standard input, and only one of them can.`, 'Give the others as @path.');
+        }
+    }
+    for (const flag of given) {
+        resolved.set(flag.flag, await readSecret(environment, String(values.get(flag.flag)), flag.flag, options.canAsk));
+    }
+    return resolved;
+}
+// ------------------------------------------------------------------------------------------------------- REDACTION
+/** How deep a schema is followed: a cycle of `$ref`s ends here instead of never. */
+const MOST_NESTING = 16;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The schema a `$ref` of this document points at (`#`, `#/$defs/Name`, `#/definitions/Name`), or the schema itself. */
+function followed(root, schema) {
+    let current = schema;
+    for (let hops = 0; hops < MOST_NESTING; hops += 1) {
+        const ref = current?.$ref;
+        if (current === undefined || typeof ref !== 'string')
+            return current;
+        if (ref === '#') {
+            current = root;
+            continue;
+        }
+        if (!ref.startsWith('#/'))
+            return undefined;
+        let node = root;
+        for (const segment of ref.slice(2).split('/')) {
+            node = isRecord(node) ? node[segment.replace(/~1/g, '/').replace(/~0/g, '~')] : undefined;
+        }
+        current = isRecord(node) ? node : undefined;
+    }
+    return undefined;
+}
+function redact(value, schema, root, depth) {
+    if (value === null || value === undefined || depth > MOST_NESTING)
+        return value;
+    const resolved = followed(root, schema);
+    if (resolved === undefined)
+        return value;
+    // The value itself is a secret, whatever its type.
+    if (resolved.format === 'password' || resolved.writeOnly === true)
+        return REDACTED;
+    let result = value;
+    // Alternatives: a secret in any of them is hidden, even when another one is the shape the value really has.
+    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+        const alternatives = resolved[keyword];
+        if (!Array.isArray(alternatives))
+            continue;
+        for (const alternative of alternatives) {
+            if (isRecord(alternative))
+                result = redact(result, alternative, root, depth + 1);
+        }
+    }
+    if (Array.isArray(result) && isRecord(resolved.items)) {
+        const items = resolved.items;
+        result = result.map((item) => redact(item, items, root, depth + 1));
+    }
+    if (isRecord(result)) {
+        const properties = isRecord(resolved.properties) ? resolved.properties : {};
+        const rest = isRecord(resolved.additionalProperties) ? resolved.additionalProperties : undefined;
+        const copy = { ...result };
+        for (const [key, entry] of Object.entries(result)) {
+            const own = properties[key];
+            const schemaOfEntry = isRecord(own) ? own : rest;
+            if (schemaOfEntry !== undefined)
+                copy[key] = redact(entry, schemaOfEntry, root, depth + 1);
+        }
+        result = copy;
+    }
+    return result;
+}
+/**
+ * A copy of `value` in which every part the schema calls a secret is `[redacted]`: what `--dry-run` prints of a
+ * document. The schema is the contract's own (`$ref`s into its `$defs` are followed), so a secret is found wherever
+ * the contract puts it, not only at the top; a part the schema does not describe is left as it is.
+ */
+export function redactSecrets(value, schema) {
+    return schema === undefined ? value : redact(value, schema, schema, 0);
+}

package/dist/state.js

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+import { isRecord } from "./http.js";
+/**
+ * `state.json`, beside the credentials: what the CLI remembers between two runs that is not a secret. It is one JSON
+ * object with a key for each thing remembered (`contractNote`, `updateCheck`), and every writer changes only its own key,
+ * so one feature never erases what another kept.
+ *
+ * Nothing in it is needed: a file that is missing, cannot be read or is not an object is the same as an empty one, and
+ * a write that fails is not an error of the command that asked for it (the CLI only says the thing again, or looks again).
+ */
+const STATE_FILE = 'state.json';
+export function statePath(configDir) {
+    return join(configDir, STATE_FILE);
+}
+/** Everything that was remembered; an empty object when there is no file or it is damaged. */
+export async function readState(environment, configDir) {
+    const path = statePath(configDir);
+    try {
+        if (!(await environment.fs.stat(path)))
+            return {};
+        const parsed = JSON.parse(new TextDecoder().decode(await environment.fs.readFile(path)));
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        // A damaged state file is the same as none.
+        return {};
+    }
+}
+/**
+ * Sets one key and leaves the others as they are (the file is read again just before it is written, so a record that
+ * another run saved a moment ago is kept). Rejects when the file cannot be written: the caller decides whether that matters.
+ */
+export async function writeStateKey(environment, configDir, key, value) {
+    const state = await readState(environment, configDir);
+    state[key] = value;
+    await environment.fs.writeFilePrivately(statePath(configDir), `${JSON.stringify(state, null, 2)}\n`);
+}