@widgetic/cli 0.0.0-stage → 0.1.1

package/dist/rest/register.js

@@ -0,0 +1,139 @@
+import { resolveSettings, timeoutMilliseconds } from "../config.js";
+import { confirmOrStop } from "../confirm.js";
+import { requireApiKey } from "../credentials.js";
+import { addCommonOptions, addFlag, commandHelp, readCommon, readFlags, shorten } 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`. */
+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(group.title)
+            .description(shorten(group.description || group.title, 300));
+        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`);
+}

package/dist/update/installation.js

@@ -0,0 +1,83 @@
+import { join } from 'node:path';
+import { isRecord } from "../http.js";
+import { isReleaseVersion } from "./version.js";
+export function describeInstallation(packageFolder) {
+    // One separator for every platform, and no case: Windows paths and macOS volumes do not agree on either.
+    const path = `${packageFolder.replaceAll('\\', '/').toLowerCase().replace(/\/+$/, '')}/`;
+    if (!path.includes('/node_modules/'))
+        return { kind: 'checkout' };
+    if (path.includes('/_npx/') ||
+        path.includes('/pnpm/dlx/') ||
+        path.includes('/dlx-') ||
+        path.includes('/bunx-')) {
+        return { kind: 'transient' };
+    }
+    if (path.includes('/.bun/install/global/node_modules/'))
+        return { kind: 'global', manager: 'bun' };
+    if (path.includes('/pnpm/global/'))
+        return { kind: 'global', manager: 'pnpm' };
+    if (path.includes('/yarn/global/node_modules/') || path.includes('/yarn/data/global/node_modules/')) {
+        return { kind: 'global', manager: 'yarn' };
+    }
+    // npm: `<prefix>/lib/node_modules/@widgetic/cli` (macOS, Linux, nvm, fnm, Volta) or
+    // `%AppData%/npm/node_modules/@widgetic/cli` (Windows).
+    if (path.endsWith('/lib/node_modules/@widgetic/cli/') ||
+        path.endsWith('/npm/node_modules/@widgetic/cli/')) {
+        return { kind: 'global', manager: 'npm' };
+    }
+    return { kind: 'unknown' };
+}
+/**
+ * The command that installs exactly `version` (the one that was shown and agreed to, not "latest": a release that
+ * lands between the question and the answer is not what was said yes to).
+ */
+export function updateCommand(manager, packageName, version) {
+    // A version comes from the network and the command may be run through a shell on Windows: three numbers only.
+    if (!isReleaseVersion(version) || !/^@?[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)?$/.test(packageName)) {
+        throw new Error(`refusing to build an install command for ${packageName}@${version}`);
+    }
+    const target = `${packageName}@${version}`;
+    const args = {
+        npm: ['install', '-g', target],
+        pnpm: ['add', '-g', target],
+        yarn: ['global', 'add', target],
+        bun: ['add', '-g', target]
+    };
+    return { program: manager, args: args[manager], text: [manager, ...args[manager]].join(' ') };
+}
+/** The version in the installed package's own `package.json`, or undefined when it cannot be read. */
+export async function installedVersionOf(environment, packageFolder) {
+    try {
+        const bytes = await environment.fs.readFile(join(packageFolder, 'package.json'));
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        return isRecord(parsed) && typeof parsed.version === 'string' ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Runs the update command and checks the result by reading the installed copy again: a package manager that exits 0
+ * without changing the copy that is run (two Node versions, two prefixes) is the one failure that is easy to miss.
+ */
+export async function installVersion(environment, command, expectedVersion, options) {
+    let exitCode;
+    try {
+        exitCode = await environment.runProgram(command.program, command.args, {
+            showOutput: options.showOutput
+        });
+    }
+    catch {
+        exitCode = null;
+    }
+    if (exitCode === null) {
+        return { ok: false, reason: 'not-started', exitCode: null, installedVersion: undefined };
+    }
+    const installedVersion = await installedVersionOf(environment, environment.packageFolder);
+    if (exitCode !== 0)
+        return { ok: false, reason: 'exit-code', exitCode, installedVersion };
+    if (installedVersion !== undefined && installedVersion !== expectedVersion) {
+        return { ok: false, reason: 'unchanged', exitCode, installedVersion };
+    }
+    return { ok: true, installedVersion };
+}

package/dist/update/lookup.js

@@ -0,0 +1,128 @@
+import { configDirectory, npmRegistryUrl } from "../config.js";
+import { UPDATE_CHECK_CONFIG } from "../constants.js";
+import { isRecord } from "../http.js";
+import { debug } from "../output.js";
+import { readState, writeStateKey } from "../state.js";
+import { cliIdentity, cliPackageName } from "../version.js";
+import { fetchLatestVersion } from "./registry.js";
+import { isReleaseVersion } from "./version.js";
+/**
+ * What the CLI remembers about the newest version, and the one place that asks npm for it.
+ *
+ * Kept in `state.json` under `updateCheck` (see `src/state.ts`), so a run that already knows the answer asks nobody:
+ *
+ *   "updateCheck": {
+ *     "checkedAt": "2026-10-29T15:00:00.000Z",   when npm was last asked
+ *     "ok": true,                                whether that worked (a failed look is retried after an hour, not a day)
+ *     "latest": "0.2.0",                         what npm said is the newest release
+ *     "notifiedVersion": "0.2.0",                the version the person was last asked about...
+ *     "notifiedAt": "2026-10-29T15:00:02.000Z"   ...and when: a "no" is remembered for a week
+ *   }
+ */
+const STATE_KEY = 'updateCheck';
+const HOUR_MILLISECONDS = 60 * 60 * 1000;
+const DAY_MILLISECONDS = 24 * HOUR_MILLISECONDS;
+/** A record read from disk is only as good as its fields: anything else is the same as no record. */
+export function parseUpdateRecord(value) {
+    if (!isRecord(value) || typeof value.checkedAt !== 'string' || Number.isNaN(Date.parse(value.checkedAt))) {
+        return undefined;
+    }
+    const record = { checkedAt: value.checkedAt, ok: value.ok === true };
+    // A version that is not three numbers is dropped, so a hand-edited file cannot put text in a command line.
+    if (typeof value.latest === 'string' && isReleaseVersion(value.latest))
+        record.latest = value.latest;
+    if (typeof value.notifiedVersion === 'string' && isReleaseVersion(value.notifiedVersion)) {
+        record.notifiedVersion = value.notifiedVersion;
+        if (typeof value.notifiedAt === 'string' && !Number.isNaN(Date.parse(value.notifiedAt))) {
+            record.notifiedAt = value.notifiedAt;
+        }
+    }
+    return record;
+}
+export async function readUpdateRecord(environment, configDir) {
+    return parseUpdateRecord((await readState(environment, configDir))[STATE_KEY]);
+}
+/** Saves the record; a folder that cannot be written is not an error, the next run just asks npm again. */
+export async function saveUpdateRecord(environment, configDir, record) {
+    try {
+        await writeStateKey(environment, configDir, STATE_KEY, record);
+        return true;
+    }
+    catch (error) {
+        debug(environment, `could not save ${STATE_KEY} in the state file: ${error.message}`);
+        return false;
+    }
+}
+/** Whether npm should be asked again: never asked, or the last answer is older than its interval. */
+export function isLookupDue(record, now) {
+    if (record === undefined)
+        return true;
+    const intervalHours = record.ok
+        ? UPDATE_CHECK_CONFIG.CHECK_INTERVAL_HOURS
+        : UPDATE_CHECK_CONFIG.RETRY_AFTER_FAILURE_HOURS;
+    const age = now.getTime() - Date.parse(record.checkedAt);
+    // A clock that was set back makes the age negative: ask again rather than stay quiet for ever.
+    return age < 0 || age >= intervalHours * HOUR_MILLISECONDS;
+}
+/** Whether the person already said no to this very version, less than `SNOOZE_DAYS` ago. */
+export function isSnoozed(record, version, now) {
+    if (record?.notifiedVersion !== version || record.notifiedAt === undefined)
+        return false;
+    const age = now.getTime() - Date.parse(record.notifiedAt);
+    return age >= 0 && age < UPDATE_CHECK_CONFIG.SNOOZE_DAYS * DAY_MILLISECONDS;
+}
+/**
+ * The newest version of this package. Never rejects: whatever goes wrong comes back as `failure`, because the routine
+ * look runs beside a command and must not be able to change what the command does.
+ */
+export async function lookUpLatestVersion(environment, options) {
+    try {
+        const configDir = configDirectory(environment);
+        const previous = await readUpdateRecord(environment, configDir);
+        const now = environment.now();
+        if (!options.force && !isLookupDue(previous, now)) {
+            debug(environment, `newest version from the saved look at ${previous?.checkedAt}: ${previous?.latest}`);
+            return { latest: previous?.latest, record: previous, asked: false, failure: undefined };
+        }
+        const registryUrl = npmRegistryUrl(environment);
+        debug(environment, `asking ${registryUrl} for the newest ${cliPackageName()}`);
+        const result = await fetchLatestVersion(environment, {
+            packageName: cliPackageName(),
+            registryUrl,
+            timeoutMilliseconds: options.timeoutMilliseconds,
+            userAgent: `${cliIdentity()} (update check)`
+        });
+        // The answer replaces what was known only when it is one; a failure keeps the last good version.
+        const record = {
+            checkedAt: now.toISOString(),
+            ok: result.ok,
+            ...(result.ok
+                ? { latest: result.version }
+                : previous?.latest !== undefined
+                    ? { latest: previous.latest }
+                    : {}),
+            ...(previous?.notifiedVersion !== undefined
+                ? {
+                    notifiedVersion: previous.notifiedVersion,
+                    ...(previous.notifiedAt !== undefined ? { notifiedAt: previous.notifiedAt } : {})
+                }
+                : {})
+        };
+        await saveUpdateRecord(environment, configDir, record);
+        if (!result.ok) {
+            debug(environment, `no newest version: ${result.detail}`);
+            return { latest: record.latest, record, asked: true, failure: result };
+        }
+        debug(environment, `npm says the newest is ${result.version}`);
+        return { latest: result.version, record, asked: true, failure: undefined };
+    }
+    catch (error) {
+        debug(environment, `looking for the newest version failed: ${error.message}`);
+        return {
+            latest: undefined,
+            record: undefined,
+            asked: false,
+            failure: { ok: false, reason: 'unexpected', detail: error.message }
+        };
+    }
+}