@widgetic/cli 0.0.0-stage → 0.1.1

package/dist/update/offer.js

@@ -0,0 +1,165 @@
+import { configDirectory, updateCheckSwitchedOffBy } from "../config.js";
+import { UPDATE_CHECK_CONFIG } from "../constants.js";
+import { EXIT_CODES } from "../errors.js";
+import { debug, note } from "../output.js";
+import { cliPackageName, cliVersion } from "../version.js";
+import { describeInstallation, updateCommand } from "./installation.js";
+import { isSnoozed, lookUpLatestVersion, saveUpdateRecord } from "./lookup.js";
+import { performUpdate } from "./perform.js";
+import { isNewerVersion } from "./version.js";
+/**
+ * The routine part of updating: while a command runs, the CLI finds out whether npm has a newer version; when the
+ * command has finished, it says so, shows both versions and asks whether to update.
+ *
+ * Two promises are kept so that this can never get in the way of the work:
+ *
+ *   - It changes nothing about the command. The look for the newest version starts before the command and runs beside
+ *     it (a 2 s limit, and the answer is kept for a day); the question comes after the command has printed its result and
+ *     its exit code is final, and the exit code is never changed by what is answered or by anything that goes wrong here.
+ *   - It asks only a person. Not with `--json`, `--yes`, `CI`, `NO_UPDATE_NOTIFIER` or `WIDGETIC_NO_UPDATE_CHECK`, not
+ *     when any of the three streams is not a terminal, not for `--help`, `--version`, `help`, `completion` (the
+ *     shell calls it on every Tab) or `update` itself, and not for a copy that is a source checkout or was fetched by
+ *     `npx` to run once. `WIDGETIC_DEBUG=1` says which of these applied.
+ */
+/** Commands that only print text that is wanted (or are called by a program), and are never followed by a question. */
+const QUIET_COMMANDS = new Set(['help', 'completion', '__complete', 'update']);
+const QUIET_FLAGS = new Set(['--help', '-h', '--version', '-V']);
+/** `widgetic`, `widgetic --help`, `widgetic completion bash`, `widgetic update`: the arguments of a run that never asks. */
+export function isQuietInvocation(argv) {
+    if (argv.length === 0)
+        return true;
+    if (argv.some((word) => QUIET_FLAGS.has(word)))
+        return true;
+    const command = argv.find((word) => !word.startsWith('-'));
+    return command === undefined || QUIET_COMMANDS.has(command);
+}
+/** Why this run neither looks for an update nor asks about one, or `undefined` when it may. */
+export function whyNoUpdateCheck(environment, argv) {
+    const switchedOffBy = updateCheckSwitchedOffBy(environment);
+    if (switchedOffBy !== undefined)
+        return `${switchedOffBy} is set`;
+    if (isQuietInvocation(argv)) {
+        return 'the command only prints help, a version, a completion or updates';
+    }
+    if (argv.includes('--json') || argv.includes('--yes')) {
+        return '--json or --yes says that nobody is there to ask';
+    }
+    if (environment.confirm === undefined || environment.stdout.isTTY !== true) {
+        return 'input, output and errors are not all a terminal';
+    }
+    if (environment.env.TERM === 'dumb')
+        return 'the terminal is dumb';
+    const installation = describeInstallation(environment.packageFolder);
+    if (installation.kind === 'checkout')
+        return 'this is a source checkout, not an installed package';
+    if (installation.kind === 'transient')
+        return 'this copy was fetched to run once (npx, dlx, bunx), not installed';
+    return undefined;
+}
+/**
+ * Starts the look, or says (under `WIDGETIC_DEBUG`) why it is not made. Call it before the command, hand the result to
+ * `offerUpdate` after it.
+ */
+export function startUpdateCheck(environment, argv) {
+    try {
+        const reason = whyNoUpdateCheck(environment, argv);
+        if (reason !== undefined) {
+            debug(environment, `no look for a newer version: ${reason}`);
+            return undefined;
+        }
+        return lookUpLatestVersion(environment, {
+            force: false,
+            timeoutMilliseconds: UPDATE_CHECK_CONFIG.BACKGROUND_TIMEOUT_MILLISECONDS
+        });
+    }
+    catch (error) {
+        // Looking for an update must never stop the command it comes with from running.
+        debug(environment, `the look for a newer version could not start: ${error.message}`);
+        return undefined;
+    }
+}
+/** What to tell someone whose copy the CLI cannot update itself. */
+function manualInstructions(installation, latest) {
+    const command = updateCommand('npm', cliPackageName(), latest).text;
+    const where = installation.kind === 'unknown'
+        ? 'It is not a global install that the CLI knows how to update (npm, pnpm, yarn or bun).'
+        : 'It cannot be updated from here.';
+    return `${where} Update it the way you installed it, for example: ${command} (without -g inside a project).`;
+}
+/** Remembers that the person was asked about `version`: a "no" is not asked again for a week. */
+async function rememberAsked(environment, record, version) {
+    await saveUpdateRecord(environment, configDirectory(environment), {
+        checkedAt: record?.checkedAt ?? environment.now().toISOString(),
+        ok: record?.ok ?? true,
+        ...(record?.latest !== undefined ? { latest: record.latest } : {}),
+        notifiedVersion: version,
+        notifiedAt: environment.now().toISOString()
+    });
+}
+/** Shows both versions and asks. The answer (or a silence, or Ctrl-C) never reaches the exit code of the command. */
+async function presentOffer(environment, knowledge, current, latest) {
+    const confirm = environment.confirm;
+    if (confirm === undefined)
+        return;
+    const packageName = cliPackageName();
+    const installation = describeInstallation(environment.packageFolder);
+    note(environment, `\nA new version of the Widgetic CLI is available: ${current} → ${latest}`);
+    if (installation.kind !== 'global') {
+        note(environment, manualInstructions(installation, latest));
+        await rememberAsked(environment, knowledge.record, latest);
+        return;
+    }
+    const command = updateCommand(installation.manager, packageName, latest);
+    let agreed = false;
+    try {
+        agreed = await confirm(`Update now? (runs \`${command.text}\`)`, {
+            timeoutMilliseconds: UPDATE_CHECK_CONFIG.PROMPT_TIMEOUT_SECONDS * 1000
+        });
+    }
+    catch (error) {
+        // Ctrl-C or Ctrl-D at the question is "no": the command already did its work.
+        debug(environment, `the question was not answered: ${error.message}`);
+        note(environment, '');
+    }
+    // Asked once: yes, no, silence and a failed install all mean the same question is not repeated for a week.
+    await rememberAsked(environment, knowledge.record, latest);
+    if (!agreed) {
+        note(environment, `Not updating. \`widgetic update\` does it whenever you want; this question comes back in ${UPDATE_CHECK_CONFIG.SNOOZE_DAYS} days, or for a newer version.`);
+        return;
+    }
+    await performUpdate(environment, { command, packageName, current, latest, quiet: false });
+}
+/**
+ * After the command: say that a newer version exists and ask, when this is the moment for it. `exitCode` is the
+ * command's own: 7 means the server refused this version as too old, which is always worth saying, so then npm is
+ * asked again (the saved answer may be a day old) and a "no" from last time does not silence it.
+ */
+export async function offerUpdate(environment, pending, exitCode) {
+    if (pending === undefined)
+        return;
+    try {
+        const current = cliVersion();
+        const refused = exitCode === EXIT_CODES.upgrade;
+        let knowledge = await pending;
+        if (refused && !knowledge.asked) {
+            knowledge = await lookUpLatestVersion(environment, {
+                force: true,
+                timeoutMilliseconds: UPDATE_CHECK_CONFIG.BACKGROUND_TIMEOUT_MILLISECONDS
+            });
+        }
+        const latest = knowledge.latest;
+        if (latest === undefined || !isNewerVersion(latest, current)) {
+            debug(environment, `no newer version than ${current} (newest known: ${latest ?? 'none'})`);
+            return;
+        }
+        if (!refused && isSnoozed(knowledge.record, latest, environment.now())) {
+            debug(environment, `${latest} was already offered less than ${UPDATE_CHECK_CONFIG.SNOOZE_DAYS} days ago`);
+            return;
+        }
+        await presentOffer(environment, knowledge, current, latest);
+    }
+    catch (error) {
+        // Whatever goes wrong here, the command has already done what it was asked to.
+        debug(environment, `the update offer failed: ${error.message}`);
+    }
+}

package/dist/update/perform.js

@@ -0,0 +1,33 @@
+import { note } from "../output.js";
+import { installVersion } from "./installation.js";
+/** Why an update did not happen, with the command to do it by hand: what to read when it did not work. */
+export function describeInstallFailure(result, input) {
+    const { command, packageName, latest } = input;
+    const byHand = `Update it by hand with: ${command.text}`;
+    if (result.reason === 'not-started') {
+        return `Could not run ${command.program} (is it installed and on your PATH?), so ${packageName} was not updated. ${byHand}`;
+    }
+    if (result.reason === 'unchanged') {
+        return (`${command.program} finished, but the ${packageName} installed here is still ${result.installedVersion ?? 'the same'}, ` +
+            `not ${latest}: it may have gone to another folder than the one this copy runs from. ${byHand}`);
+    }
+    return (`${command.program} stopped with exit code ${result.exitCode}, so ${packageName} was not updated. ${byHand}\n` +
+        'A permission error (EACCES) means the global folder belongs to another user: fix its ownership, or install Node with a version manager, rather than using sudo.');
+}
+/**
+ * Runs the command, checks the installed copy, and (unless `quiet`) prints what is being run and what came of it on
+ * stderr. The caller decides what a failure means for its exit code: here there is only the result.
+ */
+export async function performUpdate(environment, input) {
+    if (!input.quiet)
+        note(environment, `Running: ${input.command.text}`);
+    const result = await installVersion(environment, input.command, input.latest, {
+        showOutput: !input.quiet
+    });
+    if (!input.quiet) {
+        note(environment, result.ok
+            ? `Updated ${input.packageName} ${input.current} → ${input.latest}. The next command you run uses the new version.`
+            : describeInstallFailure(result, input));
+    }
+    return result;
+}

package/dist/update/registry.js

@@ -0,0 +1,68 @@
+import { isRecord } from "../http.js";
+import { isReleaseVersion } from "./version.js";
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+/** What went wrong before there was an answer, in a few words. */
+function describeFailure(error, timeoutMilliseconds) {
+    const name = error instanceof Error ? error.name : '';
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return `no answer within ${Math.round((timeoutMilliseconds / 1000) * 10) / 10}s`;
+    }
+    const cause = error instanceof Error ? error.cause : undefined;
+    return ((typeof cause?.code === 'string' && cause.code) ||
+        (typeof cause?.message === 'string' && cause.message) ||
+        (error instanceof Error ? error.message : String(error)));
+}
+export async function fetchLatestVersion(environment, query) {
+    const url = `${query.registryUrl.replace(/\/+$/, '')}/${query.packageName.replace('/', '%2f')}/latest`;
+    const host = hostOf(url);
+    let response;
+    try {
+        response = await environment.fetch(url, {
+            headers: { accept: 'application/json', 'user-agent': query.userAgent },
+            signal: AbortSignal.timeout(query.timeoutMilliseconds)
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: 'unreachable',
+            detail: `${host} did not answer: ${describeFailure(error, query.timeoutMilliseconds)}`
+        };
+    }
+    if (response.status === 404) {
+        return { ok: false, reason: 'not-published', detail: `${host} has no ${query.packageName} (yet)` };
+    }
+    if (!response.ok) {
+        return { ok: false, reason: 'unreachable', detail: `${host} answered ${response.status}` };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return { ok: false, reason: 'unexpected', detail: `${host} did not answer with JSON` };
+    }
+    if (!isRecord(body) || body.name !== query.packageName || typeof body.version !== 'string') {
+        return {
+            ok: false,
+            reason: 'unexpected',
+            detail: `${host} did not name a version of ${query.packageName}`
+        };
+    }
+    if (!isReleaseVersion(body.version)) {
+        return {
+            ok: false,
+            reason: 'unexpected',
+            // Quoted as JSON, so that a control character in what the network sent is shown as an escape, not obeyed.
+            detail: `${host} names ${JSON.stringify(body.version.slice(0, 40))} as the latest, which is not a release version`
+        };
+    }
+    return { ok: true, version: body.version };
+}

package/dist/update/version.js

@@ -0,0 +1,39 @@
+/**
+ * Versions as npm writes them, and which of two is later. Only what looking for an update needs: the newest release
+ * (`1.2.3`) is compared with the version that is running, which may be a pre-release (`1.3.0-beta.1`).
+ */
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseVersion(text) {
+    const match = VERSION.exec(text.trim());
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4]
+    };
+}
+/**
+ * `1.2.3` and nothing else: three numbers, no pre-release, no build. Only such a version is ever offered, and it is the
+ * only kind that is put in a command line: digits and dots cannot be anything but a version.
+ */
+export function isReleaseVersion(text) {
+    return /^\d+\.\d+\.\d+$/.test(text);
+}
+/**
+ * Whether `candidate` is a later version than `current`. A pre-release is earlier than its own release
+ * (`1.3.0-beta.1` is before `1.3.0`), so a person on a beta is offered the release; two pre-releases of the same
+ * numbers are not told apart, and a version that cannot be read is never "later".
+ */
+export function isNewerVersion(candidate, current) {
+    const later = parseVersion(candidate);
+    const earlier = parseVersion(current);
+    if (!later || !earlier)
+        return false;
+    for (const part of ['major', 'minor', 'patch']) {
+        if (later[part] !== earlier[part])
+            return later[part] > earlier[part];
+    }
+    return earlier.prerelease !== undefined && later.prerelease === undefined;
+}

package/dist/validate.js

@@ -0,0 +1,93 @@
+import { validationError } from "./errors.js";
+import { patternRequirement } from "./patterns.js";
+let ajvPromise;
+const compiled = new WeakMap();
+async function compilerFor() {
+    ajvPromise ??= import('ajv').then(({ Ajv }) => new Ajv({ strict: false, validateFormats: false, allErrors: true }));
+    return ajvPromise;
+}
+/** `/files/0/url` becomes `files[0].url`. */
+function dotted(pointer) {
+    return pointer
+        .split('/')
+        .filter((segment) => segment !== '')
+        .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'))
+        .reduce((path, segment) => /^\d+$/.test(segment) ? `${path}[${segment}]` : path === '' ? segment : `${path}.${segment}`, '');
+}
+function issueOf(error) {
+    const path = dotted(error.instancePath);
+    const join = (child) => (path === '' ? child : `${path}.${child}`);
+    switch (error.keyword) {
+        case 'required':
+            return {
+                path: join(String(error.params.missingProperty)),
+                message: 'is required'
+            };
+        case 'additionalProperties':
+            return {
+                path: join(String(error.params.additionalProperty)),
+                message: 'is not accepted here'
+            };
+        case 'enum':
+            return {
+                path,
+                message: `must be one of: ${(error.params.allowedValues ?? []).map(String).join(', ')}`
+            };
+        case 'pattern':
+            return { path, message: `must ${patternRequirement(error.params.pattern)}` };
+        case 'anyOf':
+        case 'oneOf':
+            return { path, message: 'does not match any of the shapes the contract allows' };
+        default:
+            return { path, message: error.message ?? 'is not valid' };
+    }
+}
+/** The things wrong with `value`, or an empty list. */
+export async function checkAgainst(schema, value) {
+    let validate = compiled.get(schema);
+    if (!validate) {
+        validate = (await compilerFor()).compile(schema);
+        compiled.set(schema, validate);
+    }
+    if (validate(value))
+        return [];
+    // The same problem is often reported twice (a missing field and the alternative that needed it): say each once.
+    const seen = new Set();
+    const issues = [];
+    for (const error of validate.errors ?? []) {
+        const issue = issueOf(error);
+        const key = `${issue.path}|${issue.message}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            issues.push(issue);
+        }
+    }
+    return issues;
+}
+const MOST_ISSUES_SHOWN = 10;
+/**
+ * A place in a document named the way the person typed it: `title` is `--title`, and a place inside a flag's value
+ * (`media_ids[0]`) is `--media-ids[0]`. A place that no flag fills (`files[0].url`) stays as the document spells it.
+ */
+export function namedByFlag(path, flagOf) {
+    const property = /^[^.[]+/.exec(path)?.[0];
+    if (property === undefined)
+        return path;
+    const flag = flagOf.get(property);
+    return flag === undefined ? path : `--${flag}${path.slice(property.length)}`;
+}
+/**
+ * Stops the command when the document does not fit its schema. `nameOf` turns a place in the document into what the
+ * person typed (`--title` for the property `title`), so the message points at a flag whenever there is one.
+ */
+export async function requireValid(schema, value, what, nameOf = (path) => path) {
+    const issues = await checkAgainst(schema, value);
+    if (issues.length === 0)
+        return;
+    const shown = issues
+        .slice(0, MOST_ISSUES_SHOWN)
+        .map((issue) => `  ${issue.path === '' ? what : nameOf(issue.path)} ${issue.message}`);
+    if (issues.length > MOST_ISSUES_SHOWN)
+        shown.push(`  … and ${issues.length - MOST_ISSUES_SHOWN} more`);
+    throw validationError(`${what} is not valid:\n${shown.join('\n')}`, issues.map((issue) => ({ path: issue.path, message: issue.message })), 'Nothing was sent. `widgetic schema` prints what the command takes.');
+}

package/dist/version.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+let cached;
+function readManifest() {
+    if (cached)
+        return cached;
+    const text = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(text);
+    if (typeof parsed.name !== 'string' || typeof parsed.version !== 'string') {
+        throw new Error('package.json of @widgetic/cli has no name or version');
+    }
+    cached = {
+        name: parsed.name,
+        version: parsed.version,
+        ...(parsed.engines ? { engines: parsed.engines } : {})
+    };
+    return cached;
+}
+export function cliPackageName() {
+    return readManifest().name;
+}
+export function cliVersion() {
+    return readManifest().version;
+}
+/**
+ * How the CLI names itself to the gateway: `@widgetic/cli/<version>`. The gateway's SDK version gate reads this from
+ * `X-SDK-Version` and from the `User-Agent`, counts it, and can answer 426 to a release it has retired.
+ */
+export function cliIdentity() {
+    const manifest = readManifest();
+    return `${manifest.name}/${manifest.version}`;
+}
+/**
+ * The two headers by which the gateway recognises this CLI: its SDK version gate reads `X-SDK-Version` (and the user
+ * agent) to count the release and, one day, to refuse one it has retired. Every request the CLI makes carries them.
+ */
+export function identityHeaders(environment) {
+    return {
+        'user-agent': `${cliIdentity()} (node/${environment.nodeVersion}; ${environment.platform})`,
+        'x-sdk-version': cliIdentity()
+    };
+}
+/** The oldest Node this package runs on, from `engines.node` (`>=22.12.0` is `22.12.0`); `undefined` when it says nothing usable. */
+export function minimumNodeVersion() {
+    const range = readManifest().engines?.node;
+    const match = typeof range === 'string' ? /^>=\s*(\d+(?:\.\d+){0,2})$/.exec(range.trim()) : null;
+    return match?.[1];
+}
+/** Whether `version` (`26.12.1`) is `minimum` (`22.12.0`) or later; a part that is missing counts as 0. */
+export function isAtLeast(version, minimum) {
+    const parse = (text) => text.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    const have = parse(version);
+    const need = parse(minimum);
+    for (let index = 0; index < Math.max(have.length, need.length); index += 1) {
+        const difference = (have[index] ?? 0) - (need[index] ?? 0);
+        if (difference !== 0)
+            return difference > 0;
+    }
+    return true;
+}

package/generated/contracts.json

@@ -0,0 +1 @@
+{"package":"@widgetic/api-contracts","version":"1.11.109","publishTag":"latest","source":{"commit":"21238b5bbb97b100ef2edb0d9d98d167467e8d18","branch":null,"dirty":false,"atOriginMain":true},"openApi":{"file":"openapi-public.json","sha256":"750e774e958a819377963d0a6f7a2feb2e7b70327b614053fdbe748e3e5e5865","paths":120,"operations":161,"servers":["https://api.widgetic.com/v1"]},"mcp":{"file":"mcp-tools.json","sha256":"9d6494d8d1d227e1752a170339d63853b52770812e9283cda2ca66981edd72c6","contractVersion":"1.12.0","serverName":"widgetic","tools":32}}