@widgetic/cli 0.0.0-stage → 0.1.2

package/dist/commands/auth.js

@@ -0,0 +1,269 @@
+import { resolveSettings, timeoutMilliseconds } from "../config.js";
+import { API_KEY_SHAPE } from "../constants.js";
+import { CredentialStore, maskKey, noApiKey, resolveApiKey } from "../credentials.js";
+import { readAll } from "../environment.js";
+import { CliError, EXIT_CODES, usageError } from "../errors.js";
+import { addBasicOptions, readCommon } from "../options.js";
+import { note, printResult, writeStdout } from "../output.js";
+import { retryNotifier } from "../retry.js";
+import { verifyApiKey } from "./verify.js";
+/**
+ * `widgetic auth login | logout | status`: the one place the CLI's key is saved, forgotten and looked at. A key is read
+ * from a hidden prompt on a terminal or from standard input (`--with-key`), never from an argument (an argument is in
+ * the shell history and in `ps`), checked with the server before it is saved, and written to a private file. The
+ * environment variable `WIDGETIC_API_KEY` needs none of this and always wins over a saved key.
+ */
+const ENVIRONMENT_KEY_NOTE = 'note: WIDGETIC_API_KEY is set in this environment, and the CLI uses it before any saved key.';
+/** A key is one printable word: anything else would be refused by the server and could not be put in a header. */
+function looksLikeAWord(key) {
+    return /^[\x21-\x7e]+$/.test(key);
+}
+async function readKey(environment, input) {
+    if (input.withKey) {
+        const text = await readAll(environment.stdin);
+        const key = (text.split(/\r?\n/)[0] ?? '').trim();
+        if (key === '') {
+            throw usageError('--with-key: standard input holds no key.', 'Pipe it in: echo "$WIDGETIC_API_KEY" | widgetic auth login --with-key');
+        }
+        return key;
+    }
+    if (input.json) {
+        throw usageError('--json never asks anything, so the key cannot be typed.', 'Pipe it in: echo "$WIDGETIC_API_KEY" | widgetic auth login --with-key --json');
+    }
+    if (environment.promptSecret === undefined) {
+        throw usageError('There is no terminal to ask for the key on.', 'Pipe it in with --with-key, or set WIDGETIC_API_KEY and skip logging in.');
+    }
+    const typed = (await environment.promptSecret('API key (it is not shown): ')).trim();
+    if (typed === '')
+        throw usageError('No key was typed.');
+    return typed;
+}
+/** What a failed save means to the person: where it was meant to go, and the way around it. */
+function notSaved(path, error) {
+    return new CliError({
+        code: 'CREDENTIALS_NOT_SAVED',
+        message: `The key could not be saved in ${path}: ${error instanceof Error ? error.message : String(error)}`,
+        exitCode: EXIT_CODES.failure,
+        hint: 'Set WIDGETIC_API_KEY instead, or choose another folder with WIDGETIC_CONFIG_DIR.',
+        cause: error
+    });
+}
+function describeCheck(check) {
+    const scopes = check.scopes.length === 0 ? 'no scopes listed' : `scopes: ${check.scopes.join(', ')}`;
+    return `${check.tokenType ?? 'key'}; ${scopes}`;
+}
+async function runLogin(environment, node) {
+    const common = readCommon(node);
+    const options = node.opts();
+    const settings = resolveSettings(environment, { profile: common.profile });
+    const key = await readKey(environment, { withKey: options.withKey === true, json: common.json });
+    if (!looksLikeAWord(key)) {
+        throw usageError('That is not an API key: it holds spaces or characters a key never has.');
+    }
+    if (!common.json && !API_KEY_SHAPE.test(key)) {
+        note(environment, 'note: that does not look like a Widgetic API key (they start with wgt_usr_, wgt_prt_ or wdg_org_); checking it anyway.');
+    }
+    // `--no-verify` is `verify: false`; without it the server is asked, and a key it refuses is never saved.
+    const check = options.verify === false
+        ? undefined
+        : await verifyApiKey(environment, settings, key, {
+            timeoutMilliseconds: timeoutMilliseconds(common.timeout),
+            onRetry: retryNotifier(environment, common.json)
+        });
+    const store = new CredentialStore(environment, settings.configDir);
+    try {
+        await store.save(settings.profile, key);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw notSaved(store.path, error);
+    }
+    if (common.json) {
+        printResult(environment, {
+            profile: settings.profile,
+            saved: true,
+            key: maskKey(key),
+            file: store.path,
+            verified: check !== undefined,
+            ...(check
+                ? {
+                    tokenType: check.tokenType,
+                    scopes: check.scopes,
+                    userId: check.userId,
+                    expiresAt: check.expiresAt
+                }
+                : {})
+        }, true);
+        return;
+    }
+    const lines = [`Saved the key ${maskKey(key)} for the profile "${settings.profile}".`];
+    if (check)
+        lines.push(`  The server accepted it (${describeCheck(check)}).`);
+    else
+        lines.push('  It was not checked with the server (--no-verify).');
+    lines.push(`  File: ${store.path} (only you can read it).`);
+    writeStdout(environment, lines.join('\n'));
+    if (environment.env.WIDGETIC_API_KEY?.trim())
+        note(environment, ENVIRONMENT_KEY_NOTE);
+}
+async function runLogout(environment, node) {
+    const common = readCommon(node);
+    const settings = resolveSettings(environment, { profile: common.profile });
+    const store = new CredentialStore(environment, settings.configDir);
+    const everything = node.opts().all === true;
+    const names = everything ? Object.keys((await store.read()).profiles) : [settings.profile];
+    const removed = [];
+    for (const name of names) {
+        if (await store.remove(name))
+            removed.push(name);
+    }
+    if (common.json) {
+        printResult(environment, { removed }, true);
+        return;
+    }
+    if (removed.length === 0) {
+        writeStdout(environment, everything
+            ? 'There were no saved keys.'
+            : `There was no saved key for the profile "${settings.profile}".`);
+    }
+    else {
+        writeStdout(environment, removed.length === 1 && !everything
+            ? `Removed the saved key of the profile "${settings.profile}".`
+            : `Removed the saved keys of: ${removed.join(', ')}.`);
+    }
+    if (environment.env.WIDGETIC_API_KEY?.trim()) {
+        note(environment, 'note: WIDGETIC_API_KEY is still set in this environment, and the CLI keeps using it.');
+    }
+}
+async function verdictOn(environment, settings, found, timeout, json) {
+    try {
+        const check = await verifyApiKey(environment, settings, found.apiKey, {
+            timeoutMilliseconds: timeoutMilliseconds(timeout),
+            keySource: found.source,
+            onRetry: retryNotifier(environment, json)
+        });
+        return {
+            verdict: {
+                accepted: true,
+                checked: true,
+                tokenType: check.tokenType,
+                scopes: check.scopes,
+                userId: check.userId,
+                expiresAt: check.expiresAt
+            },
+            check,
+            failure: undefined
+        };
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        const refused = error.exitCode === EXIT_CODES.auth;
+        return {
+            verdict: {
+                accepted: false,
+                // A refusal is an answer; a server that could not be reached has not said anything.
+                checked: refused,
+                ...(error.status === undefined ? {} : { status: error.status }),
+                code: error.code,
+                message: error.message
+            },
+            check: undefined,
+            failure: error
+        };
+    }
+}
+async function runStatus(environment, node) {
+    const common = readCommon(node);
+    const settings = resolveSettings(environment, { profile: common.profile });
+    const store = new CredentialStore(environment, settings.configDir);
+    const found = await resolveApiKey(environment, store, settings.profile);
+    // The saved profiles are listed even when the key in use is the environment's; a damaged file is that key's business only.
+    let profiles = [];
+    let savedAt;
+    try {
+        const file = await store.read();
+        profiles = Object.keys(file.profiles).sort();
+        savedAt = file.profiles[settings.profile]?.savedAt;
+    }
+    catch (error) {
+        if (found?.source !== 'environment')
+            throw error;
+    }
+    let verdict;
+    let check;
+    let failure;
+    if (found) {
+        ({ verdict, check, failure } = await verdictOn(environment, settings, found, common.timeout, common.json));
+    }
+    else {
+        failure = noApiKey(settings);
+    }
+    const report = {
+        profile: settings.profile,
+        authenticated: verdict?.accepted === true,
+        source: found?.source ?? null,
+        key: found ? maskKey(found.apiKey) : null,
+        ...(found?.source === 'file' && savedAt ? { savedAt } : {}),
+        file: store.path,
+        profiles,
+        server: verdict ?? null
+    };
+    if (common.json) {
+        printResult(environment, report, true);
+    }
+    else {
+        const lines = [`Profile:  ${settings.profile}`];
+        if (!found) {
+            lines.push('Key:      none');
+        }
+        else if (found.source === 'environment') {
+            lines.push(`Key:      ${maskKey(found.apiKey)}, from WIDGETIC_API_KEY`);
+        }
+        else {
+            lines.push(`Key:      ${maskKey(found.apiKey)}, saved in ${store.path}${savedAt ? ` on ${savedAt}` : ''}`);
+        }
+        if (verdict?.accepted && check) {
+            lines.push(`Server:   accepted (${describeCheck(check)}) at ${settings.apiUrl}`);
+        }
+        else if (verdict) {
+            lines.push(verdict.checked
+                ? `Server:   did not accept it${verdict.status ? ` (HTTP ${verdict.status})` : ''}`
+                : `Server:   not reached (${verdict.message ?? 'no answer'})`);
+        }
+        if (profiles.length > 0)
+            lines.push(`Saved profiles: ${profiles.join(', ')}`);
+        writeStdout(environment, lines.join('\n'));
+    }
+    if (failure)
+        throw failure;
+}
+/** Adds `auth` and its three commands under the root. */
+export function registerAuthCommands(root, environment) {
+    const auth = root.command('auth').description('Save, forget and check the API key the CLI uses.');
+    const login = auth
+        .command('login')
+        .description('Check an API key with the server and save it for this profile.\n\nThe key is asked for on the terminal without showing it, or read from standard input with --with-key. It is never taken from an argument. Setting WIDGETIC_API_KEY instead needs no login.')
+        .option('--with-key', 'Read the key from standard input instead of asking for it.')
+        .option('--no-verify', 'Save the key without asking the server whether it works.');
+    addBasicOptions(login, { server: true });
+    login.action(async () => {
+        await runLogin(environment, login);
+    });
+    const logout = auth
+        .command('logout')
+        .description('Forget the saved key of this profile (or of every profile with --all).')
+        .option('--all', 'Forget the saved keys of every profile.');
+    addBasicOptions(logout, { server: true });
+    logout.action(async () => {
+        await runLogout(environment, logout);
+    });
+    const status = auth
+        .command('status')
+        .description('Show which key a command would use, where it comes from, and whether the server accepts it.\n\nExit code 0 when it is accepted, 3 when there is no key or the server refuses it, 6 when the server cannot be reached.');
+    addBasicOptions(status, { server: true });
+    status.action(async () => {
+        await runStatus(environment, status);
+    });
+}

package/dist/commands/call.js

@@ -0,0 +1,97 @@
+import { usageError } from "../errors.js";
+import { registerMcpCommand } from "../mcp/register.js";
+import { findMcpCommand, findRestCommand, unknownOperation } from "./schema.js";
+/**
+ * `widgetic api call <operationId>` and `widgetic mcp call <tool>`: the way in by the contract's own name.
+ *
+ * An operationId (`createUserApiKey`) is what the OpenAPI description, the SDK methods and the documentation call an
+ * operation; a tool name (`create_widget`) is what the MCP server calls a tool. Both run the very command that is
+ * generated for it, with the flags of that command, so there is one behaviour and one place to read it:
+ *
+ *     widgetic api call getWidget --id 42 --json      is   widgetic api widgets get-widget --id 42 --json
+ *
+ * The one thing `mcp call` adds is a way to call a tool this CLI has no command for: a server that is newer than the
+ * CLI offers tools the CLI was not built with, and `mcp call new_tool --input '{…}'` reaches one without an update.
+ * Such a call is sent as it is (the server checks the arguments) and asks before it runs, because the CLI cannot tell
+ * what the tool does.
+ */
+const argumentsOf = (schemaCommand) => `The flags and values of the command it runs (\`${schemaCommand}\` lists them).`;
+/**
+ * A flag where the name belongs (`call --json getWidget`). The flags are the ones of the command that runs, so they
+ * come after its name, and the message says so instead of calling the flag an unknown operation.
+ */
+function nameFirst(word, form) {
+    if (!word.startsWith('-'))
+        return;
+    throw usageError(`Name what to run before its flags: "${word}" is a flag, and the flags are the ones of the command that runs.`, `Write \`widgetic ${form} ${word}\`.`);
+}
+/** Adds `call` under `api`. The groups and commands must already be registered: the command to run is found among them. */
+export function registerApiCall(api, manifest) {
+    api
+        .command('call')
+        .summary('Run an operation by its operationId')
+        .description('Run one operation by the operationId the contract gives it (createUserApiKey), with the flags of its own command.\n\nIt is the same as `widgetic api <group> <command>`, found by the name the OpenAPI description, the SDK and the documentation use. The operationId comes first; everything after it is the flags of that command.\n\nThe operations that `--help` does not list (those of the public embed runtime) are reached this way too.')
+        .argument('<operationId>', 'The operationId of the operation (createUserApiKey)')
+        .argument('[arguments...]', argumentsOf('widgetic schema api <operationId>'))
+        .allowUnknownOption()
+        .passThroughOptions()
+        .action(async (operationId, rest) => {
+        nameFirst(operationId, 'api call <operationId>');
+        const match = findRestCommand(manifest, [operationId]);
+        if (!match)
+            throw unknownOperation(manifest, [operationId]);
+        const node = api.commands
+            .find((group) => group.name() === match.group.name)
+            ?.commands.find((command) => command.name() === match.command.name);
+        if (!node)
+            throw new Error(`The command of ${operationId} was not registered.`);
+        await node.parseAsync(rest, { from: 'user' });
+    });
+}
+/** What the CLI knows of a tool it has no command for: nothing, which is said in its help and in the question it asks. */
+function unknownTool(tool) {
+    return {
+        name: tool,
+        tool,
+        title: `Call the tool ${tool}`,
+        description: `${tool} is not a tool this CLI was built with, so its arguments are sent exactly as --input gives them and the server checks them. The CLI cannot tell what it changes, so it asks before it runs.`,
+        scopes: [],
+        scopeGroup: 'write',
+        readOnly: false,
+        destructive: false,
+        idempotent: false,
+        confirm: true,
+        inputSchema: { type: 'object' },
+        flags: [],
+        inputOnly: []
+    };
+}
+/** The names a tool can have: what the server accepts in `tools/call`. */
+const TOOL_NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
+/** Adds `call` under `mcp`. The tools must already be registered. */
+export function registerMcpCall(mcp, manifest, run) {
+    mcp
+        .command('call')
+        .summary('Call a tool by its name')
+        .description('Call one tool by the name the server gives it (create_widget), with the flags of its own command.\n\nIt is the same as `widgetic mcp <tool>`. A tool that this CLI has no command for (the server is newer than the CLI) is called with --input only, and asks before it runs, since nothing is known about what it does.')
+        .argument('<tool>', 'The tool, as a command (create-widget) or as the server names it (create_widget)')
+        .argument('[arguments...]', argumentsOf('widgetic schema mcp <tool>'))
+        .allowUnknownOption()
+        .passThroughOptions()
+        .action(async (tool, rest) => {
+        nameFirst(tool, 'mcp call <tool>');
+        const known = findMcpCommand(manifest.commands, tool);
+        if (known) {
+            const node = mcp.commands.find((command) => command.name() === known.name);
+            if (!node)
+                throw new Error(`The command of ${known.tool} was not registered.`);
+            await node.parseAsync(rest, { from: 'user' });
+            return;
+        }
+        if (tool === 'call' || tool === 'help' || !TOOL_NAME.test(tool)) {
+            throw usageError(`"${tool}" is not the name of a tool.`, 'Run `widgetic mcp --help` to see the tools.');
+        }
+        const node = registerMcpCommand(mcp, unknownTool(tool), run);
+        await node.parseAsync(rest, { from: 'user' });
+    });
+}

package/dist/commands/completion.js

@@ -0,0 +1,150 @@
+import { usageError } from "../errors.js";
+import { writeStdout } from "../output.js";
+/**
+ * Tab completion for bash, zsh and fish.
+ *
+ * The scripts are three lines each and know nothing about the commands: they hand the text typed so far to the hidden
+ * `widgetic __complete --line "<text>"`, which builds the program the way `run` would for those words and answers with
+ * the subcommands, flags and choices that fit. So completion is always the commands this build has (generated from the
+ * contracts), and nothing is kept in step by hand. A completion that fails prints nothing: a shell prompt must never
+ * show a stack.
+ */
+export const SHELLS = ['bash', 'zsh', 'fish'];
+const SCRIPTS = {
+    bash: `# widgetic completion for bash. Add this line to ~/.bashrc:
+#   eval "$(widgetic completion bash)"
+_widgetic_complete() {
+  local IFS=$'\\n'
+  COMPREPLY=($(widgetic __complete --line "\${COMP_LINE:0:COMP_POINT}" 2>/dev/null))
+}
+complete -o default -F _widgetic_complete widgetic
+`,
+    zsh: `#compdef widgetic
+# widgetic completion for zsh. Add this line to ~/.zshrc, after compinit:
+#   eval "$(widgetic completion zsh)"
+_widgetic() {
+  local -a candidates
+  candidates=( \${(f)"$(widgetic __complete --line "$LBUFFER" 2>/dev/null)"} )
+  if (( \${#candidates} )); then
+    compadd -a candidates
+  else
+    _files
+  fi
+}
+compdef _widgetic widgetic
+`,
+    fish: `# widgetic completion for fish. Save it as ~/.config/fish/completions/widgetic.fish:
+#   widgetic completion fish > ~/.config/fish/completions/widgetic.fish
+complete -c widgetic -f -a '(widgetic __complete --line (commandline -cp) 2>/dev/null)'
+`
+};
+/** The script that completes `widgetic` in this shell. */
+export function completionScript(shell) {
+    return SCRIPTS[shell];
+}
+/**
+ * The words of a command line as the shell would split them (quotes and backslashes honoured), and the word being
+ * typed: the last one when the text does not end in a space, else an empty one (the next word is about to start).
+ */
+export function splitLine(line) {
+    const words = [];
+    let word = '';
+    let inWord = false;
+    let quote;
+    for (let index = 0; index < line.length; index += 1) {
+        const character = line[index];
+        if (quote !== undefined) {
+            if (character === quote)
+                quote = undefined;
+            else
+                word += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            inWord = true;
+        }
+        else if (character === '\\' && index + 1 < line.length) {
+            index += 1;
+            word += line[index];
+            inWord = true;
+        }
+        else if (/\s/.test(character)) {
+            if (inWord) {
+                words.push(word);
+                word = '';
+                inWord = false;
+            }
+        }
+        else {
+            word += character;
+            inWord = true;
+        }
+    }
+    return inWord ? { words, current: word } : { words, current: '' };
+}
+/** What can follow `words` after the program name, given the start of the next word. */
+export function completionsFor(build, words, current) {
+    const program = build(words);
+    let command = program;
+    // The option typed last that takes a value, so that value (not a subcommand) is what is being completed.
+    let waitingFor;
+    for (const word of words) {
+        if (waitingFor !== undefined) {
+            waitingFor = undefined;
+            continue;
+        }
+        if (word.startsWith('-')) {
+            const name = word.includes('=') ? word.slice(0, word.indexOf('=')) : word;
+            const option = command.options.find((candidate) => candidate.long === name || candidate.short === name);
+            if (option && !word.includes('=') && (option.required || option.optional))
+                waitingFor = option;
+            continue;
+        }
+        const next = command.commands.find((candidate) => candidate.name() === word || candidate.aliases().includes(word));
+        if (next)
+            command = next;
+    }
+    const starting = (candidates) => [...new Set(candidates)].filter((candidate) => candidate.startsWith(current)).sort();
+    if (waitingFor !== undefined)
+        return starting(waitingFor.argChoices ?? []);
+    const help = command.createHelp();
+    if (current.startsWith('-')) {
+        return starting(help
+            .visibleOptions(command)
+            .map((option) => option.long ?? option.short)
+            .filter((name) => name !== undefined));
+    }
+    return starting(help.visibleCommands(command).flatMap((candidate) => [candidate.name(), ...candidate.aliases()]));
+}
+/** Adds `completion <shell>` and the hidden `__complete` under the root. */
+export function registerCompletionCommands(root, environment, build) {
+    root
+        .command('completion')
+        // The line the list of commands of `widgetic --help` shows; the shell lines are the help of `completion` itself.
+        .summary('Print the script that completes commands and flags with the Tab key.')
+        .description('Print the script that completes widgetic commands and flags with the Tab key.\n\nbash: eval "$(widgetic completion bash)" in ~/.bashrc\nzsh:  eval "$(widgetic completion zsh)" in ~/.zshrc, after compinit\nfish: widgetic completion fish > ~/.config/fish/completions/widgetic.fish')
+        .argument('<shell>', `One of: ${SHELLS.join(', ')}`)
+        .action((shell) => {
+        if (!SHELLS.includes(shell)) {
+            throw usageError(`There is no completion for "${shell}".`, `Use one of: ${SHELLS.join(', ')}.`);
+        }
+        writeStdout(environment, completionScript(shell).trimEnd());
+    });
+    root
+        .command('__complete', { hidden: true })
+        .description('Answers the completion scripts: the words that can follow the text typed so far.')
+        .requiredOption('--line <text>', 'The text typed so far, up to the cursor')
+        .action((options) => {
+        try {
+            const { words, current } = splitLine(options.line);
+            // The first word is the program as typed (`widgetic`, `./bin/widgetic.js`); what follows is the command line.
+            const candidates = completionsFor(build, words.slice(1), current);
+            if (candidates.length > 0)
+                writeStdout(environment, candidates.join('\n'));
+        }
+        catch {
+            // A prompt shows nothing rather than a failure.
+        }
+    });
+}