@widgetic/cli 0.0.0-stage → 0.1.1

package/dist/commands/doctor.js

@@ -0,0 +1,291 @@
+import { resolveSettings, timeoutMilliseconds } from "../config.js";
+import { API_KEY_SHAPE } from "../constants.js";
+import { CredentialStore, maskKey, resolveApiKey } from "../credentials.js";
+import { CliError, EXIT_CODES } from "../errors.js";
+import { loadContractsInfo, loadMcpManifest } from "../manifest/load.js";
+import { McpConnection } from "../mcp/session.js";
+import { addBasicOptions, readCommon } from "../options.js";
+import { printResult, writeStdout } from "../output.js";
+import { cliIdentity, isAtLeast, minimumNodeVersion } from "../version.js";
+import { probe, validateUrl, verifyApiKey } from "./verify.js";
+const UPDATE_HINT = 'Update the CLI: npm install -g @widgetic/cli@latest';
+function failure(id, title, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        id,
+        title,
+        status: 'fail',
+        message,
+        ...(error instanceof CliError && error.hint ? { hint: error.hint } : {})
+    };
+}
+function checkCli(context) {
+    const { environment } = context;
+    return {
+        id: 'cli',
+        title: 'CLI',
+        status: 'ok',
+        message: `${cliIdentity()} on Node ${environment.nodeVersion} (${environment.platform})`
+    };
+}
+function checkNode(context) {
+    const minimum = minimumNodeVersion();
+    const have = context.environment.nodeVersion;
+    if (minimum === undefined) {
+        return { id: 'node', title: 'Node', status: 'skip', message: 'The package names no minimum version.' };
+    }
+    if (isAtLeast(have, minimum)) {
+        return { id: 'node', title: 'Node', status: 'ok', message: `${have} (at least ${minimum} is needed)` };
+    }
+    return {
+        id: 'node',
+        title: 'Node',
+        status: 'fail',
+        message: `${have} is older than the ${minimum} this CLI needs.`,
+        hint: 'Install a current Node (https://nodejs.org) and run the CLI with it.'
+    };
+}
+function checkContracts() {
+    const info = loadContractsInfo();
+    const mcp = loadMcpManifest();
+    const details = {
+        package: info.package,
+        version: info.version,
+        commit: info.source.commit,
+        publishTag: info.publishTag,
+        operations: info.openApi.operations,
+        tools: info.mcp.tools,
+        toolContract: mcp.contractVersion
+    };
+    const message = `${info.package} ${info.version} (commit ${info.source.commit.slice(0, 8)}): ${info.openApi.operations} REST operations, ${info.mcp.tools} MCP tools, tool contract ${mcp.contractVersion}`;
+    if (info.publishTag !== 'latest' || info.source.dirty) {
+        return {
+            id: 'contracts',
+            title: 'Contracts',
+            status: 'warn',
+            message: `${message}. They are a pre-release, or were built from uncommitted code.`,
+            details,
+            hint: 'A released CLI is built from the contracts tagged latest.'
+        };
+    }
+    return { id: 'contracts', title: 'Contracts', status: 'ok', message, details };
+}
+async function checkCredentials(context) {
+    const { settings, store, key } = context;
+    const checks = [];
+    if (key === undefined) {
+        checks.push({
+            id: 'credentials',
+            title: 'API key',
+            status: 'warn',
+            message: `No API key for the profile "${settings.profile}", so the servers can only be asked whether they answer.`,
+            hint: 'Run `widgetic auth login`, or set WIDGETIC_API_KEY.'
+        });
+    }
+    else {
+        const where = key.source === 'environment' ? 'WIDGETIC_API_KEY' : store.path;
+        const unusual = !API_KEY_SHAPE.test(key.apiKey);
+        checks.push({
+            id: 'credentials',
+            title: 'API key',
+            status: unusual ? 'warn' : 'ok',
+            message: `${maskKey(key.apiKey)} from ${where} (profile "${settings.profile}")${unusual ? ', which does not look like a Widgetic key' : ''}`,
+            details: { profile: settings.profile, source: key.source, key: maskKey(key.apiKey) },
+            ...(unusual ? { hint: 'Keys start with wgt_usr_, wgt_prt_ or wdg_org_.' } : {})
+        });
+    }
+    if (await store.isReadableByOthers()) {
+        checks.push({
+            id: 'credentials-file',
+            title: 'Key file',
+            status: 'warn',
+            message: `${store.path} can be read by other users of this machine.`,
+            hint: `chmod 600 ${store.path}`
+        });
+    }
+    return checks;
+}
+async function checkRest(context) {
+    const { environment, settings, key } = context;
+    if (key !== undefined) {
+        try {
+            const check = await verifyApiKey(environment, settings, key.apiKey, {
+                timeoutMilliseconds: context.timeoutMilliseconds,
+                keySource: key.source
+            });
+            return {
+                id: 'rest',
+                title: 'REST API',
+                status: 'ok',
+                message: `${settings.apiUrl} accepted the key (${check.tokenType ?? 'key'}, ${check.scopes.length} scopes)`,
+                details: { url: settings.apiUrl, tokenType: check.tokenType, scopes: check.scopes }
+            };
+        }
+        catch (error) {
+            return {
+                ...failure('rest', 'REST API', error),
+                details: {
+                    url: settings.apiUrl,
+                    ...(error instanceof CliError ? { code: error.code, status: error.status } : {})
+                }
+            };
+        }
+    }
+    try {
+        const answer = await probe(environment, validateUrl(settings), { method: 'GET', headers: { accept: 'application/json' } }, context.timeoutMilliseconds);
+        return {
+            id: 'rest',
+            title: 'REST API',
+            status: 'ok',
+            message: `${settings.apiUrl} answers (HTTP ${answer.status} without a key, ${answer.milliseconds} ms)`,
+            details: { url: settings.apiUrl, status: answer.status }
+        };
+    }
+    catch (error) {
+        return failure('rest', 'REST API', error);
+    }
+}
+async function checkMcp(context) {
+    const { environment, settings, key } = context;
+    const manifest = loadMcpManifest();
+    if (key === undefined) {
+        try {
+            const answer = await probe(environment, settings.mcpUrl, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+                body: '{}'
+            }, context.timeoutMilliseconds);
+            return {
+                id: 'mcp',
+                title: 'MCP server',
+                status: 'ok',
+                message: `${settings.mcpUrl} answers (HTTP ${answer.status} without a key, ${answer.milliseconds} ms)`,
+                details: { url: settings.mcpUrl, status: answer.status }
+            };
+        }
+        catch (error) {
+            return failure('mcp', 'MCP server', error);
+        }
+    }
+    const connection = new McpConnection(environment, settings, { apiKey: key.apiKey, source: key.source }, context.timeoutMilliseconds);
+    try {
+        const offered = await connection.listTools();
+        const serverVersion = connection.serverVersion;
+        const known = new Set(manifest.commands.map((command) => command.tool));
+        const missingInCli = offered.filter((name) => !known.has(name)).sort();
+        const missingOnServer = [...known].filter((name) => !offered.includes(name)).sort();
+        const details = {
+            url: settings.mcpUrl,
+            serverVersion,
+            expectedVersion: manifest.contractVersion,
+            tools: offered.length,
+            missingInCli,
+            missingOnServer
+        };
+        const problems = [];
+        if (serverVersion !== manifest.contractVersion) {
+            problems.push(`It speaks tool contract ${serverVersion ?? 'unknown'}; this CLI was built for ${manifest.contractVersion}.`);
+        }
+        if (missingInCli.length > 0) {
+            problems.push(`Tools this CLI has no command for: ${missingInCli.join(', ')} (call one with \`widgetic mcp call <tool> --input '{…}'\`).`);
+        }
+        if (missingOnServer.length > 0) {
+            problems.push(`Tools of this CLI that the server does not offer: ${missingOnServer.join(', ')}.`);
+        }
+        if (problems.length > 0) {
+            return {
+                id: 'mcp',
+                title: 'MCP server',
+                status: 'warn',
+                message: `${settings.mcpUrl} answers. ${problems.join(' ')}`,
+                details,
+                hint: UPDATE_HINT
+            };
+        }
+        return {
+            id: 'mcp',
+            title: 'MCP server',
+            status: 'ok',
+            message: `${settings.mcpUrl} accepted the key; tool contract ${serverVersion}, the same as this CLI's, ${offered.length} tools`,
+            details
+        };
+    }
+    catch (error) {
+        return { ...failure('mcp', 'MCP server', error), details: { url: settings.mcpUrl } };
+    }
+    finally {
+        await connection.close();
+    }
+}
+const MARKS = { ok: '[ok]', warn: '[warn]', fail: '[fail]', skip: '[skip]' };
+function printReport(environment, checks, summary) {
+    const lines = [];
+    const width = Math.max(...checks.map((check) => check.title.length));
+    for (const check of checks) {
+        lines.push(`${MARKS[check.status].padEnd(7)}${check.title.padEnd(width + 2)}${check.message}`);
+        if (check.hint)
+            lines.push(`${' '.repeat(7 + width + 2)}${check.hint}`);
+    }
+    lines.push('', summary);
+    writeStdout(environment, lines.join('\n'));
+}
+async function runDoctor(environment, node) {
+    const common = readCommon(node);
+    const settings = resolveSettings(environment, { profile: common.profile });
+    const store = new CredentialStore(environment, settings.configDir);
+    const checks = [];
+    let key;
+    try {
+        key = await resolveApiKey(environment, store, settings.profile);
+    }
+    catch (error) {
+        checks.push(failure('credentials', 'API key', error));
+    }
+    const context = {
+        environment,
+        settings,
+        store,
+        key,
+        timeoutMilliseconds: timeoutMilliseconds(common.timeout)
+    };
+    checks.unshift(checkCli(context), checkNode(context));
+    try {
+        checks.splice(2, 0, checkContracts());
+    }
+    catch (error) {
+        checks.splice(2, 0, failure('contracts', 'Contracts', error));
+    }
+    if (!checks.some((check) => check.id === 'credentials'))
+        checks.push(...(await checkCredentials(context)));
+    checks.push(await checkRest(context), await checkMcp(context));
+    const failed = checks.filter((check) => check.status === 'fail').length;
+    const warned = checks.filter((check) => check.status === 'warn').length;
+    if (common.json) {
+        printResult(environment, { ok: failed === 0, warnings: warned, failures: failed, checks }, true);
+    }
+    else {
+        const summary = failed > 0
+            ? `${failed} of ${checks.length} checks failed.`
+            : warned > 0
+                ? `Nothing is broken; ${warned} ${warned === 1 ? 'thing is' : 'things are'} worth a look.`
+                : 'All checks passed.';
+        printReport(environment, checks, summary);
+    }
+    if (failed > 0) {
+        throw new CliError({
+            code: 'DOCTOR_FAILED',
+            message: `${failed} of ${checks.length} checks failed.`,
+            exitCode: EXIT_CODES.failure
+        });
+    }
+}
+/** Adds `doctor` under the root. */
+export function registerDoctorCommand(root, environment) {
+    const doctor = root
+        .command('doctor')
+        .description('Check the install and both servers: the CLI and its contracts, the API key, the REST API, and the MCP server (which tool contract it speaks and which tools it offers, compared with this CLI).\n\nExit code 0 when nothing failed, 1 when a check did; --json prints every check.');
+    addBasicOptions(doctor, { server: true });
+    doctor.action(async () => {
+        await runDoctor(environment, doctor);
+    });
+}

package/dist/commands/schema.js

@@ -0,0 +1,214 @@
+import { usageError } from "../errors.js";
+import { loadMcpManifest, loadRestManifest } from "../manifest/load.js";
+import { addBasicOptions, readCommon, unwrap } from "../options.js";
+import { printResult, writeStdout } from "../output.js";
+/** The number of single-character edits between two words (insert, delete, change). */
+export function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= a.length; row += 1) {
+        const current = [row];
+        for (let column = 1; column <= b.length; column += 1) {
+            const change = previous[column - 1] + (a[row - 1] === b[column - 1] ? 0 : 1);
+            current[column] = Math.min(change, previous[column] + 1, current[column - 1] + 1);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** A name without its separators or its case, so `getWidgt`, `get-widgt` and `get_widgt` are the same word. */
+const plain = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+/**
+ * Names that look like `word`, nearest first, to say "did you mean" when nothing matches: a name that contains it, or
+ * one a few characters away (a third of its length, at least two).
+ */
+export function suggest(word, candidates, limit = 5) {
+    const wanted = plain(word);
+    if (wanted === '')
+        return [];
+    const allowed = Math.max(2, Math.floor(wanted.length / 3));
+    const ranked = [];
+    for (const name of new Set(candidates)) {
+        const candidate = plain(name);
+        if (wanted.length >= 3 && candidate.includes(wanted)) {
+            ranked.push({ name, rank: 0 });
+            continue;
+        }
+        const distance = editDistance(wanted, candidate);
+        if (distance <= allowed)
+            ranked.push({ name, rank: distance });
+    }
+    return ranked
+        .sort((a, b) => a.rank - b.rank || a.name.localeCompare(b.name))
+        .slice(0, limit)
+        .map((entry) => entry.name);
+}
+function allRest(manifest) {
+    return manifest.groups.flatMap((group) => group.commands.map((command) => ({ group, command })));
+}
+/** `widgets get-widget` (a group and a command, or an alias), or `getWidget` / `get-widget` on its own. */
+export function findRestCommand(manifest, words) {
+    const everything = allRest(manifest);
+    if (words.length >= 2) {
+        const [groupName, commandName] = words;
+        return everything.find(({ group, command }) => group.name === groupName &&
+            (command.name === commandName ||
+                command.aliases.includes(commandName) ||
+                command.operationId === commandName));
+    }
+    const [word] = words;
+    const byOperation = everything.find(({ command }) => command.operationId === word);
+    if (byOperation)
+        return byOperation;
+    const byName = everything.filter(({ command }) => command.name === word);
+    return byName.length === 1 ? byName[0] : undefined;
+}
+/** `create-widget` or `create_widget`. */
+export function findMcpCommand(commands, word) {
+    const normalized = word.replace(/_/g, '-');
+    return commands.find((command) => command.name === normalized || command.tool === word);
+}
+function flagView(flag) {
+    const view = { flag: `--${flag.flag}`, type: flag.type, required: flag.required };
+    for (const key of [
+        'enum',
+        'default',
+        'cliDefault',
+        'minimum',
+        'maximum',
+        'minLength',
+        'maxLength',
+        'pattern',
+        'format'
+    ]) {
+        if (flag[key] !== undefined)
+            view[key] = flag[key];
+    }
+    view.description = flag.description;
+    return view;
+}
+export function restSchema(manifest, match) {
+    const { group, command } = match;
+    const base = command.server === 'root' ? new URL(manifest.apiUrl).origin : manifest.apiUrl;
+    const body = command.body;
+    return {
+        kind: 'rest',
+        command: `widgetic api ${group.name} ${command.name}`,
+        ...(command.aliases.length > 0
+            ? { aliases: command.aliases.map((alias) => `widgetic api ${group.name} ${alias}`) }
+            : {}),
+        operationId: command.operationId,
+        summary: command.summary,
+        method: command.method,
+        url: `${base}${command.path}`,
+        accessLevel: command.accessLevel,
+        authenticated: command.auth,
+        asksBeforeRunning: command.confirm,
+        description: command.description,
+        parameters: command.parameters.map((parameter) => ({
+            name: parameter.name,
+            in: parameter.in,
+            ...(parameter.role ? { role: parameter.role } : {}),
+            ...flagView(parameter)
+        })),
+        ...(body
+            ? {
+                body: {
+                    kind: body.kind,
+                    contentType: body.contentType,
+                    ...(body.contentTypes ? { contentTypes: body.contentTypes } : {}),
+                    required: body.required,
+                    flags: body.flags.map((flag) => ({ property: flag.property, ...flagView(flag) })),
+                    ...(body.schema ? { schema: body.schema } : {})
+                }
+            }
+            : {})
+    };
+}
+export function mcpSchema(manifest, command) {
+    return {
+        kind: 'mcp',
+        command: `widgetic mcp ${command.name}`,
+        tool: command.tool,
+        title: command.title,
+        toolContract: manifest.contractVersion,
+        scopes: command.scopes,
+        readOnly: command.readOnly,
+        destructive: command.destructive,
+        idempotent: command.idempotent,
+        asksBeforeRunning: command.confirm,
+        description: command.description,
+        flags: command.flags.map((flag) => ({ property: flag.property, ...flagView(flag) })),
+        inputOnly: command.inputOnly,
+        inputSchema: command.inputSchema
+    };
+}
+/** What a person reads: the title, the description as paragraphs, then the rest as JSON. */
+function printSchema(environment, schema, title, json) {
+    if (json) {
+        printResult(environment, schema, true);
+        return;
+    }
+    const { description, summary, ...rest } = schema;
+    const paragraphs = String(description ?? '')
+        .trim()
+        .split(/\n\s*\n/)
+        .map(unwrap)
+        .filter((paragraph) => paragraph !== '');
+    writeStdout(environment, [title, typeof summary === 'string' ? summary : '', ...paragraphs, JSON.stringify(rest, null, 2)]
+        .filter((part) => part !== '')
+        .join('\n\n'));
+}
+/** The mistake of naming something the contracts do not have, with the nearest names that exist. */
+function unknownName(what, word, candidates, list) {
+    const near = suggest(word, candidates);
+    return usageError(`There is no ${what} in the contracts this CLI was built from.`, near.length > 0 ? `Did you mean: ${near.join(', ')}?` : `${list} lists what there is.`);
+}
+/** Why `words` named no operation: the group is wrong, or the command in it is, or (one word) the operationId. */
+export function unknownOperation(manifest, words) {
+    if (words.length >= 2) {
+        const [groupName, commandName] = words;
+        const group = manifest.groups.find((candidate) => candidate.name === groupName);
+        if (!group) {
+            return unknownName(`group "${groupName}"`, groupName, manifest.groups.map((candidate) => candidate.name), '`widgetic api --help`');
+        }
+        return unknownName(`command "${commandName}" in the group ${group.name}`, commandName, group.commands.flatMap((command) => [command.name, ...command.aliases, command.operationId]), `\`widgetic api ${group.name} --help\``);
+    }
+    // The nearest names in the spelling that was typed: an operationId (getWidgetById), a command (get-widget-by-id), or either.
+    const word = words[0] ?? '';
+    const camel = /[A-Z]/.test(word) && !/[-_]/.test(word);
+    const kebab = /[-_]/.test(word) && !/[A-Z]/.test(word);
+    return unknownName(`operation "${word}"`, word, allRest(manifest).flatMap(({ command }) => camel ? [command.operationId] : kebab ? [command.name] : [command.operationId, command.name]), '`widgetic api --help`');
+}
+/** Adds `schema` and its two forms under the root. */
+export function registerSchemaCommand(root, environment) {
+    const schema = root
+        .command('schema')
+        .description('Print the whole description of one command and the schema its input is checked against.\n\nIt is the cheap way to find out what a command takes, for a person and for an agent: one command, not the whole API.');
+    const api = schema
+        .command('api')
+        .description('One operation of the REST API.')
+        .argument('<command...>', 'A group and a command (widgets get-widget), or an operationId (getWidget)');
+    addBasicOptions(api, { server: false });
+    api.action(async (words) => {
+        const common = readCommon(api);
+        const manifest = loadRestManifest();
+        const match = findRestCommand(manifest, words);
+        if (!match)
+            throw unknownOperation(manifest, words);
+        printSchema(environment, restSchema(manifest, match), `widgetic api ${match.group.name} ${match.command.name}`, common.json);
+    });
+    const mcp = schema
+        .command('mcp')
+        .description('One tool of the MCP server.')
+        .argument('<command>', 'The tool, as a command (create-widget) or as the server names it (create_widget)');
+    addBasicOptions(mcp, { server: false });
+    mcp.action(async (word) => {
+        const common = readCommon(mcp);
+        const manifest = loadMcpManifest();
+        const command = findMcpCommand(manifest.commands, word);
+        if (!command) {
+            throw unknownName(`tool "${word}"`, word, manifest.commands.map((candidate) => candidate.name), '`widgetic mcp --help`');
+        }
+        printSchema(environment, mcpSchema(manifest, command), `widgetic mcp ${command.name}`, common.json);
+    });
+}

package/dist/commands/update.js

@@ -0,0 +1,159 @@
+import { Option } from 'commander';
+import { UPDATE_CHECK_CONFIG } from "../constants.js";
+import { CliError, EXIT_CODES, usageError } from "../errors.js";
+import { addBasicOptions, readCommon } from "../options.js";
+import { debug, note, printResult, writeStdout } from "../output.js";
+import { describeInstallation, updateCommand } from "../update/installation.js";
+import { lookUpLatestVersion } from "../update/lookup.js";
+import { describeInstallFailure, performUpdate } from "../update/perform.js";
+import { isNewerVersion } from "../update/version.js";
+import { cliPackageName, cliVersion } from "../version.js";
+/**
+ * `widgetic update`: the same thing the question after a command does, whenever the person asks for it. It asks npm
+ * (always, not from what was saved), shows the version that is running and the newest one, and installs the newest
+ * after a yes. `--check` only reports; `--yes` installs without asking; `--json` never asks and so only reports unless
+ * `--yes` is given with it. The routine question is skipped for this command, so it is never asked twice in a row.
+ */
+/** Why the CLI does not run a package manager for this copy, and what the person can do instead. */
+const NOT_UPDATABLE = {
+    unknown: {
+        why: 'This copy of the CLI is not a global install by npm, pnpm, yarn or bun, so the CLI does not know which command updates it.',
+        hint: (command) => `Update it the way you installed it, for example: ${command} (without -g inside a project).`
+    },
+    transient: {
+        why: 'This copy was fetched to run once (npx, dlx or bunx), so there is no installed copy to update.',
+        hint: () => 'Run it as `npx @widgetic/cli@latest` to get the newest, or install it for good: npm install -g @widgetic/cli'
+    },
+    checkout: {
+        why: 'This copy of the CLI runs from a source checkout, not from an installed package.',
+        hint: () => 'In the repository: git pull, then npm install and npm run build.'
+    }
+};
+function lookupError(failure) {
+    const exitCode = failure.reason === 'not-published'
+        ? EXIT_CODES.notFound
+        : failure.reason === 'unreachable'
+            ? EXIT_CODES.unavailable
+            : EXIT_CODES.failure;
+    return new CliError({
+        code: 'UPDATE_CHECK_FAILED',
+        message: `Could not look for a newer version: ${failure.detail}.`,
+        exitCode,
+        hint: `\`npm view ${cliPackageName()} version\` asks the same registry with your npm settings (a proxy, a mirror).`
+    });
+}
+async function runUpdate(environment, node) {
+    const common = readCommon(node);
+    const checkOnly = node.opts().check === true;
+    if (checkOnly && common.yes) {
+        throw usageError('--check only looks and --yes installs: use one of them.', 'Run `widgetic update --check` to look, or `widgetic update --yes` to install without asking.');
+    }
+    const packageName = cliPackageName();
+    const current = cliVersion();
+    const knowledge = await lookUpLatestVersion(environment, {
+        force: true,
+        timeoutMilliseconds: UPDATE_CHECK_CONFIG.COMMAND_TIMEOUT_MILLISECONDS
+    });
+    // A look that failed is an error here, even when an older answer is saved: this is the person asking for the truth.
+    if (knowledge.failure !== undefined || knowledge.latest === undefined) {
+        throw lookupError(knowledge.failure ?? { ok: false, reason: 'unexpected', detail: 'npm did not name a version' });
+    }
+    const latest = knowledge.latest;
+    const updateAvailable = isNewerVersion(latest, current);
+    const installation = describeInstallation(environment.packageFolder);
+    const manager = installation.kind === 'global' ? installation.manager : undefined;
+    debug(environment, `installation: ${JSON.stringify(installation)}; ${current} -> ${latest}`);
+    // What installs the newest version: the manager of this copy, else npm as the example to give.
+    const command = updateAvailable ? updateCommand(manager ?? 'npm', packageName, latest) : undefined;
+    const status = {
+        package: packageName,
+        current,
+        latest,
+        updateAvailable,
+        updated: false,
+        installedWith: manager ?? null,
+        command: command?.text ?? null
+    };
+    if (command === undefined) {
+        if (common.json)
+            printResult(environment, status, true);
+        else if (current === latest)
+            writeStdout(environment, `${packageName} ${current} is up to date.`);
+        else {
+            writeStdout(environment, `${packageName} ${current} is not older than the latest release on npm (${latest}): nothing to update.`);
+        }
+        return;
+    }
+    const available = `A new version of the Widgetic CLI is available: ${current} → ${latest}`;
+    // Only looking: `--check`, or `--json` without `--yes` (a program is reading, so nobody is asked).
+    if (checkOnly || (common.json && !common.yes)) {
+        if (common.json)
+            printResult(environment, status, true);
+        else {
+            writeStdout(environment, manager === undefined
+                ? `${available}\nUpdate it the way you installed it, for example: ${command.text}`
+                : `${available}\nInstall it with \`widgetic update\`, or: ${command.text}`);
+        }
+        return;
+    }
+    if (installation.kind !== 'global') {
+        const reason = NOT_UPDATABLE[installation.kind];
+        throw new CliError({
+            code: 'UPDATE_NOT_POSSIBLE_HERE',
+            message: `${available}. ${reason.why}`,
+            exitCode: EXIT_CODES.failure,
+            hint: reason.hint(command.text)
+        });
+    }
+    if (!common.yes) {
+        const confirm = environment.confirm;
+        if (confirm === undefined) {
+            throw usageError(`${available}, and there is nobody to ask: nothing was changed.`, 'Run it again with --yes to install it, or with --check to only look.');
+        }
+        note(environment, available);
+        let agreed = false;
+        try {
+            agreed = await confirm(`Update now? (runs \`${command.text}\`)`, {
+                timeoutMilliseconds: UPDATE_CHECK_CONFIG.PROMPT_TIMEOUT_SECONDS * 1000
+            });
+        }
+        catch {
+            // Ctrl-C or Ctrl-D at the question is a "no".
+            note(environment, '');
+        }
+        if (!agreed) {
+            writeStdout(environment, 'Not updating.');
+            return;
+        }
+    }
+    const result = await performUpdate(environment, {
+        command,
+        packageName,
+        current,
+        latest,
+        quiet: common.json
+    });
+    if (!result.ok) {
+        throw new CliError({
+            code: 'UPDATE_FAILED',
+            message: describeInstallFailure(result, { command, packageName, latest }),
+            exitCode: EXIT_CODES.failure
+        });
+    }
+    if (common.json)
+        printResult(environment, { ...status, updated: true }, true);
+}
+/** Adds `update` under the root. */
+export function registerUpdateCommand(root, environment) {
+    const update = root
+        .command('update')
+        // The line the list of commands of `widgetic --help` shows; the whole text is the help of `update` itself.
+        .summary('Look for a newer version of this CLI and offer to install it.')
+        .description('Look on npm for a newer version of this CLI and, when there is one, show both versions and ask whether to install it.\n\nOnly a global install made by npm, pnpm, yarn or bun is updated by the CLI itself; for any other copy the command to run is printed. After a command, the CLI asks the same question by itself at most once a week for each new version, and only at a terminal: NO_UPDATE_NOTIFIER=1 or WIDGETIC_NO_UPDATE_CHECK=1 turns that off.\n\nExit code 0 when it is up to date, when you said no, and with --check; 1 when it could not update.');
+    update.addOption(new Option('--check', 'Only say whether a newer version exists; install nothing and ask nothing.'));
+    update.addOption(new Option('--yes', 'Install the newest version without asking.'));
+    addBasicOptions(update, { server: false });
+    update.action(async () => {
+        await runUpdate(environment, update);
+    });
+}