@widgetic/cli 0.0.0-stage → 0.1.1

package/dist/http.js

@@ -0,0 +1,122 @@
+import { CliError, EXIT_CODES, exitCodeForStatus } from "./errors.js";
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Reads a whole answer. */
+export async function readAnswer(response) {
+    const text = await response.text();
+    const type = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() ?? '';
+    let body;
+    if (text !== '') {
+        if (type.includes('json')) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+        }
+        else {
+            body = text;
+        }
+    }
+    return { status: response.status, headers: response.headers, body };
+}
+/** `Retry-After` is a number of seconds or a date; either way, seconds from now (never negative). */
+export function parseRetryAfter(value, now) {
+    if (value === null || value.trim() === '')
+        return undefined;
+    if (/^\d+$/.test(value.trim()))
+        return Number(value.trim());
+    const date = Date.parse(value);
+    if (Number.isNaN(date))
+        return undefined;
+    return Math.max(0, Math.ceil((date - now.getTime()) / 1000));
+}
+function upgradeHint(details) {
+    const command = isRecord(details) ? details.upgradeCommand : undefined;
+    // The gateway names the package of the client it recognised; for this CLI that is `@widgetic/cli`.
+    return typeof command === 'string' ? `Update the CLI: ${command}` : undefined;
+}
+const NO_KEY_HINT = 'Run `widgetic auth login` with an API key, or set WIDGETIC_API_KEY.';
+/** The error an answer that was not a success stands for. */
+export function errorFromAnswer(answer, now, keySource) {
+    const { status, headers, body } = answer;
+    const envelope = isRecord(body) && isRecord(body.error) ? body.error : undefined;
+    const text = typeof body === 'string' ? body.trim() : '';
+    // The MCP endpoint answers an OAuth-style body to a key it does not accept: `{"error":"invalid_token","error_description":"…"}`.
+    const oauthCode = isRecord(body) && typeof body.error === 'string' ? body.error : undefined;
+    const oauthMessage = isRecord(body) && typeof body.error_description === 'string' ? body.error_description : undefined;
+    const code = typeof envelope?.code === 'string' ? envelope.code : (oauthCode ?? `HTTP_${status}`);
+    const message = (typeof envelope?.message === 'string' && envelope.message) ||
+        (isRecord(body) && typeof body.message === 'string' && body.message) ||
+        oauthMessage ||
+        (text !== '' && text.slice(0, 300)) ||
+        `The server answered ${status}.`;
+    const requestId = (typeof envelope?.correlationId === 'string' && envelope.correlationId) ||
+        headers.get('x-correlation-id') ||
+        undefined;
+    const retryAfter = (typeof envelope?.retryAfter === 'number' ? envelope.retryAfter : undefined) ??
+        parseRetryAfter(headers.get('retry-after'), now);
+    let details = envelope?.details;
+    if (typeof envelope?.param === 'string') {
+        const rest = isRecord(details) ? details : details === undefined ? {} : { detail: details };
+        details = { param: envelope.param, ...rest };
+    }
+    const suggested = typeof envelope?.suggestedAction === 'string' ? envelope.suggestedAction : undefined;
+    let hint = suggested;
+    if (status === 401) {
+        hint =
+            keySource === 'environment'
+                ? 'The key in WIDGETIC_API_KEY was not accepted: check it, or unset it to use the saved one.'
+                : NO_KEY_HINT;
+    }
+    else if (status === 426) {
+        hint = upgradeHint(details) ?? suggested;
+    }
+    else if (status === 429 && retryAfter !== undefined) {
+        hint = `Rate limited: try again in ${retryAfter}s.`;
+    }
+    return new CliError({
+        code,
+        message,
+        exitCode: exitCodeForStatus(status),
+        status,
+        requestId,
+        retryAfter,
+        details,
+        hint
+    });
+}
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+/** What went wrong before there was an answer: a wait that ran out, a host that cannot be reached. */
+export function networkFailure(error, url, timeoutMilliseconds) {
+    const name = error instanceof Error ? error.name : '';
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new CliError({
+            code: 'TIMEOUT',
+            message: `No answer from ${hostOf(url)} within ${Math.round(timeoutMilliseconds / 1000)}s.`,
+            exitCode: EXIT_CODES.unavailable,
+            hint: 'Try again, or wait longer with --timeout <seconds>.',
+            cause: error
+        });
+    }
+    const cause = error instanceof Error ? error.cause : undefined;
+    const reason = (typeof cause?.code === 'string' && cause.code) ||
+        (typeof cause?.message === 'string' && cause.message) ||
+        (error instanceof Error ? error.message : String(error));
+    return new CliError({
+        code: 'NETWORK_ERROR',
+        message: `Cannot reach ${hostOf(url)}: ${reason}`,
+        exitCode: EXIT_CODES.unavailable,
+        hint: 'Check the connection (and WIDGETIC_API_URL or WIDGETIC_MCP_URL if one is set), then try again.',
+        cause: error
+    });
+}

package/dist/input.js

@@ -0,0 +1,37 @@
+import { resolve } from 'node:path';
+import { readAll } from "./environment.js";
+import { usageError } from "./errors.js";
+/**
+ * A document given on the command line (`--data`, `--input`): the JSON itself, `@path` for a file that holds it, or
+ * `-` for what is on standard input. It has to be a JSON object: every body and every tool input of the contracts is one.
+ */
+export async function readDocument(environment, source, flag) {
+    let text;
+    if (source === '-') {
+        text = await readAll(environment.stdin);
+    }
+    else if (source.startsWith('@')) {
+        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 {
+        text = source;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw usageError(`--${flag} is not valid JSON: ${reason}`, 'Give the document itself, @path/to/file.json, or - to read it from standard input.');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw usageError(`--${flag} must be a JSON object ({ ... }).`);
+    }
+    return parsed;
+}

package/dist/main.js

@@ -0,0 +1,30 @@
+import { run } from "./cli.js";
+import { realEnvironment } from "./environment.js";
+import { offerUpdate, startUpdateCheck } from "./update/offer.js";
+/**
+ * One run of the program as the process does it: the command, and after it, when a newer version exists, the question
+ * whether to update (`src/update/offer.ts`). The look for that version starts first and goes on beside the command, so
+ * the command is not slower for it; the question comes last, so it cannot change what the command printed or the exit
+ * code it returns. `run` stays the command alone: it is what the tests of every command call.
+ */
+export async function runProcess(argv, environment) {
+    const pendingUpdateCheck = startUpdateCheck(environment, argv);
+    const exitCode = await run(argv, environment);
+    await offerUpdate(environment, pendingUpdateCheck, exitCode);
+    return exitCode;
+}
+/**
+ * The process entry (called by bin/widgetic.js): runs the program against the real environment and sets the exit code.
+ * `process.exitCode` is set rather than `process.exit()` called, so what was written to a pipe is flushed first.
+ */
+export async function main(argv = process.argv.slice(2)) {
+    // `widgetic ... | head` closes the pipe early: that is not an error of ours.
+    process.stdout.on('error', (error) => {
+        if (error.code === 'EPIPE')
+            process.exit(0);
+        throw error;
+    });
+    // Ctrl-C ends the run at once, the way a shell expects (128 + SIGINT).
+    process.once('SIGINT', () => process.exit(130));
+    process.exitCode = await runProcess(argv, realEnvironment());
+}

package/dist/manifest/load.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { MANIFEST_FORMAT } from "./types.js";
+/**
+ * Reads the manifests `npm run generate` wrote into `generated/` (one folder above `src/` and `dist/` alike), once
+ * each and only when a command needs them: `widgetic auth status` never reads a 500 KB description of the API.
+ */
+function readGenerated(file) {
+    const url = new URL(`../../generated/${file}`, import.meta.url);
+    let text;
+    try {
+        text = readFileSync(url, 'utf8');
+    }
+    catch {
+        throw new Error(`generated/${file} is missing: this build of @widgetic/cli is incomplete. Run \`npm run generate\` (or reinstall the package).`);
+    }
+    return JSON.parse(text);
+}
+function checkedFormat(manifest, file) {
+    if (manifest.format !== MANIFEST_FORMAT) {
+        throw new Error(`generated/${file} has format ${manifest.format}, and this program reads format ${MANIFEST_FORMAT}: run \`npm run generate\`.`);
+    }
+    return manifest;
+}
+let rest;
+let mcp;
+let contracts;
+export function loadRestManifest() {
+    rest ??= checkedFormat(readGenerated('rest-manifest.json'), 'rest-manifest.json');
+    return rest;
+}
+export function loadMcpManifest() {
+    mcp ??= checkedFormat(readGenerated('mcp-manifest.json'), 'mcp-manifest.json');
+    return mcp;
+}
+/** What the contracts the program was generated from say about themselves (`widgetic doctor` prints it). */
+export function loadContractsInfo() {
+    contracts ??= readGenerated('contracts.json');
+    return contracts;
+}

package/dist/manifest/types.js

@@ -0,0 +1,14 @@
+/**
+ * The shapes of the two command manifests.
+ *
+ * `scripts/generate.ts` writes them into `generated/` from the installed `@widgetic/api-contracts` (the public OpenAPI
+ * description and the MCP tool contract the gateway publishes), and the program reads them at run time to build its
+ * commands. Nothing in a manifest is typed by hand: a command exists because the contract has an operation or a tool,
+ * and a flag exists because the contract has a parameter or a property. The few rules that are ours (the names, the
+ * aliases, which command asks before it runs) are in `scripts/lib/` and pinned by tests.
+ *
+ * This file is imported by the generator and by the program, so a manifest cannot be written in one shape and read in
+ * another.
+ */
+/** The version of the manifest format. The program refuses a manifest of another version. */
+export const MANIFEST_FORMAT = 1;

package/dist/mcp/plan.js

@@ -0,0 +1,32 @@
+import { readDocument } from "../input.js";
+import { redactSecrets } from "../secrets.js";
+import { namedByFlag, requireValid } from "../validate.js";
+import { cliIdentity } from "../version.js";
+export async function planMcpCall(plan) {
+    const { environment, command, values, input } = plan;
+    const args = input === undefined ? {} : await readDocument(environment, input, 'input');
+    for (const flag of command.flags) {
+        if (values.has(flag.flag))
+            args[flag.property] = values.get(flag.flag);
+    }
+    // What the CLI does when it is not told: a build is a draft (`--publish` makes it public). Only where the person gave nothing, in a flag or in the document.
+    for (const flag of command.flags) {
+        if (flag.cliDefault !== undefined && !(flag.property in args))
+            args[flag.property] = flag.cliDefault;
+    }
+    const flagOf = new Map(command.flags.map((flag) => [flag.property, flag.flag]));
+    await requireValid(command.inputSchema, args, `The input of ${command.tool}`, (path) => namedByFlag(path, flagOf));
+    return { command, arguments: args };
+}
+/** What `--dry-run` prints: the call exactly as it would be made, with the key left out. */
+export function describeMcpPlan(plan, settings) {
+    return {
+        dryRun: true,
+        method: 'tools/call',
+        url: settings.mcpUrl,
+        headers: { authorization: 'Bearer [redacted]', 'x-sdk-version': cliIdentity() },
+        tool: plan.command.tool,
+        // No tool takes a secret today; one that does keeps it out of this print, as a REST document does.
+        arguments: redactSecrets(plan.arguments, plan.command.inputSchema)
+    };
+}

package/dist/mcp/register.js

@@ -0,0 +1,112 @@
+import { Option } from 'commander';
+import { resolveSettings, timeoutMilliseconds } from "../config.js";
+import { confirmOrStop } from "../confirm.js";
+import { noteContractDifference } from "../contract-note.js";
+import { requireApiKey } from "../credentials.js";
+import { addCommonOptions, addFlag, commandHelp, readCommon, readFlags } from "../options.js";
+import { printResult } from "../output.js";
+import { isWaitTool, WAIT_OVERLAY } from "../overlay.js";
+import { retryNotifier, withRetries } from "../retry.js";
+import { describeMcpPlan, planMcpCall } from "./plan.js";
+import { McpConnection, refusalOf } from "./session.js";
+import { waitForBuild } from "./wait.js";
+/**
+ * The `mcp` namespace: one command for every tool of the Widgetic MCP server, built from the tool contract the
+ * gateway publishes. A command is the tool name in kebab case; an argument that is a string, a number, a choice, a
+ * boolean or a list of strings is a flag, and `--input` takes the whole document (and the arguments that are objects).
+ */
+const SCOPE_HEADINGS = {
+    read: 'Read (look at what exists):',
+    write: 'Write (build and edit):',
+    publish: 'Publish (make something public):',
+    delete: 'Delete:'
+};
+/** What the question before a tool that asks says it does: a tool the CLI does not know (called with `mcp call`) could be anything. */
+function whatItDoes(command) {
+    if (command.destructive)
+        return 'deletes or overwrites something';
+    if (command.scopes.length === 0)
+        return 'is not a tool this CLI knows, so it cannot tell what it changes';
+    return 'makes something public or removes it';
+}
+/** What a tool's answer is, printed: the data of the tool; without data, its text. */
+function printOutcome(environment, outcome, json) {
+    if (outcome.structured !== undefined) {
+        printResult(environment, outcome.structured, json);
+        return;
+    }
+    // A tool that answers in words only: a program still gets JSON.
+    printResult(environment, json ? { text: outcome.text } : outcome.text, json);
+}
+/** Runs one tool command: plan and check, then (unless `--dry-run`) confirm, connect, call, optionally wait, print. */
+export async function runMcpCommand(run, command, node, bindings) {
+    const { environment, manifest } = run;
+    const common = readCommon(node);
+    const values = readFlags(node, bindings);
+    const options = node.opts();
+    const input = typeof options.input === 'string' ? options.input : undefined;
+    const waits = options.wait === true;
+    const settings = resolveSettings(environment, { profile: common.profile });
+    const plan = await planMcpCall({ environment, command, values, input });
+    if (common.dryRun) {
+        printResult(environment, describeMcpPlan(plan, settings), common.json);
+        return;
+    }
+    if (command.confirm) {
+        await confirmOrStop(environment, {
+            what: `${command.tool} ${whatItDoes(command)}`,
+            yes: common.yes,
+            json: common.json
+        });
+    }
+    const key = await requireApiKey(environment, settings);
+    const connection = new McpConnection(environment, settings, { apiKey: key.apiKey, source: key.source }, timeoutMilliseconds(common.timeout));
+    try {
+        // A call that cannot do anything twice is repeated after a lost answer; one that starts a build or edits is not.
+        const safeToRepeat = command.readOnly || command.idempotent;
+        let outcome = await withRetries(environment, { safeToRepeat }, async () => {
+            const answered = await connection.call(command.tool, plan.arguments);
+            if (answered.isError)
+                throw refusalOf(answered);
+            return answered;
+        }, retryNotifier(environment, common.json));
+        await noteContractDifference(environment, settings, {
+            server: connection.serverVersion,
+            expected: manifest.contractVersion,
+            json: common.json
+        });
+        if (waits)
+            outcome = await waitForBuild(environment, connection, outcome, common.json);
+        printOutcome(environment, outcome, common.json);
+    }
+    finally {
+        await connection.close();
+    }
+}
+/** Adds the command of one tool under `parent` and returns it. */
+export function registerMcpCommand(parent, command, run) {
+    const node = parent
+        .command(command.name)
+        .summary(command.title)
+        .description(commandHelp(command.title, command.description, `widgetic schema mcp ${command.name}`));
+    node.helpGroup(SCOPE_HEADINGS[command.scopeGroup]);
+    const bindings = command.flags.map((flag) => addFlag(node, flag, { mandatory: false, group: 'Arguments of the tool:' }));
+    addCommonOptions(node, { asks: command.confirm, document: 'input' });
+    if (isWaitTool(command.tool)) {
+        node.addOption(new Option('--wait', `Keep asking ${WAIT_OVERLAY.pollTool} until the build is finished, and print the finished widget (up to ${Math.round(WAIT_OVERLAY.defaultMaxSeconds / 60)} minutes).`).helpGroup('Common options:'));
+    }
+    node.action(async () => {
+        await runMcpCommand(run, command, node, bindings);
+    });
+    return node;
+}
+/** Adds one command for every tool of the manifest under `mcp`, listed by what they do to your account: read first, delete last. */
+export function registerMcpCommands(mcp, manifest, environment) {
+    const run = { environment, manifest };
+    for (const scopeGroup of Object.keys(SCOPE_HEADINGS)) {
+        for (const command of manifest.commands) {
+            if (command.scopeGroup === scopeGroup)
+                registerMcpCommand(mcp, command, run);
+        }
+    }
+}

package/dist/mcp/session.js

@@ -0,0 +1,185 @@
+import { CliError, EXIT_CODES, exitCodeForStatus } from "../errors.js";
+import { errorFromAnswer, isRecord, networkFailure, readAnswer } from "../http.js";
+import { cliVersion, identityHeaders } from "../version.js";
+/** Reads a `tools/call` result: the data, the text, whether it is a refusal. */
+export function outcomeOf(result) {
+    const record = isRecord(result) ? result : {};
+    const content = Array.isArray(record.content) ? record.content : [];
+    const text = content
+        .filter((block) => isRecord(block) && block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n\n');
+    const meta = isRecord(record._meta) ? record._meta : {};
+    return {
+        isError: record.isError === true,
+        structured: isRecord(record.structuredContent) ? record.structuredContent : undefined,
+        text,
+        authChallenge: 'mcp/www_authenticate' in meta
+    };
+}
+/** The error a refusal of a tool is: exit 3 when the key is not accepted, else exit 5 with the tool's own words. */
+export function refusalOf(outcome) {
+    if (outcome.authChallenge) {
+        return new CliError({
+            code: 'AUTH_REQUIRED',
+            message: outcome.text || 'The API key was not accepted.',
+            exitCode: EXIT_CODES.auth,
+            hint: 'Run `widgetic auth login` with an API key, or set WIDGETIC_API_KEY.'
+        });
+    }
+    return new CliError({
+        code: 'TOOL_ERROR',
+        message: outcome.text || 'The tool refused the call.',
+        exitCode: EXIT_CODES.rejected
+    });
+}
+const JSON_RPC = {
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    connectionClosed: -32000,
+    requestTimeout: -32001
+};
+function isMcpError(error) {
+    return (error instanceof Error &&
+        error.name === 'McpError' &&
+        typeof error.code === 'number');
+}
+function isHttpError(error) {
+    return error instanceof Error && error.name === 'StreamableHTTPError';
+}
+export class McpConnection {
+    /** The version the server reported when it was opened: the version of its tool contract. */
+    serverVersion;
+    client;
+    lastRefusal;
+    environment;
+    settings;
+    auth;
+    timeoutMilliseconds;
+    constructor(environment, settings, auth, timeoutMilliseconds) {
+        this.environment = environment;
+        this.settings = settings;
+        this.auth = auth;
+        this.timeoutMilliseconds = timeoutMilliseconds;
+    }
+    /** Calls a tool; throws a `CliError` for everything that is not an answer (a refusal of the tool is an answer: see `refusalOf`). */
+    async call(tool, args) {
+        this.lastRefusal = undefined;
+        try {
+            const client = await this.connected();
+            const result = await client.callTool({ name: tool, arguments: args }, undefined, {
+                timeout: this.timeoutMilliseconds
+            });
+            return outcomeOf(result);
+        }
+        catch (error) {
+            const failure = this.explain(error);
+            // A connection that failed is not trusted again: the next call opens its own.
+            await this.close();
+            throw failure;
+        }
+    }
+    /** The names of the tools the server offers (`tools/list`), to compare with the ones this CLI was built for. */
+    async listTools() {
+        this.lastRefusal = undefined;
+        try {
+            const client = await this.connected();
+            const names = [];
+            let cursor;
+            do {
+                const page = await client.listTools(cursor === undefined ? undefined : { cursor }, {
+                    timeout: this.timeoutMilliseconds
+                });
+                for (const tool of page.tools)
+                    names.push(tool.name);
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            return names;
+        }
+        catch (error) {
+            const failure = this.explain(error);
+            await this.close();
+            throw failure;
+        }
+    }
+    async close() {
+        const client = this.client;
+        this.client = undefined;
+        try {
+            await client?.close();
+        }
+        catch {
+            // Closing is a courtesy; the command's result does not depend on it.
+        }
+    }
+    async connected() {
+        if (this.client)
+            return this.client;
+        const [{ Client: SdkClient }, { StreamableHTTPClientTransport }] = await Promise.all([
+            import('@modelcontextprotocol/sdk/client/index.js'),
+            import('@modelcontextprotocol/sdk/client/streamableHttp.js')
+        ]);
+        const transport = new StreamableHTTPClientTransport(new URL(this.settings.mcpUrl), {
+            fetch: async (url, init) => {
+                const response = await this.environment.fetch(url, init);
+                // Only the answer to a message says why a call failed. The stream a client may open with GET is refused with a 405 by a server that keeps none, and that is not a failure.
+                if (!response.ok && init?.method === 'POST')
+                    this.lastRefusal = await readAnswer(response.clone());
+                return response;
+            },
+            requestInit: {
+                headers: { authorization: `Bearer ${this.auth.apiKey}`, ...identityHeaders(this.environment) }
+            }
+        });
+        const client = new SdkClient({ name: '@widgetic/cli', version: cliVersion() }, { capabilities: {} });
+        await client.connect(transport, { timeout: this.timeoutMilliseconds });
+        this.client = client;
+        this.serverVersion = client.getServerVersion()?.version;
+        return client;
+    }
+    /** What a failure of the SDK stands for, in the CLI's terms. */
+    explain(error) {
+        if (error instanceof CliError)
+            return error;
+        // The server refused at the HTTP layer (401, 403, 426, 429 …): its own envelope says what and why.
+        if (this.lastRefusal)
+            return errorFromAnswer(this.lastRefusal, this.environment.now(), this.auth.source);
+        if (isMcpError(error)) {
+            const message = error.message.replace(/^MCP error -?\d+:\s*/, '');
+            switch (error.code) {
+                case JSON_RPC.requestTimeout:
+                    return networkFailure(Object.assign(new Error(message), { name: 'TimeoutError' }), this.settings.mcpUrl, this.timeoutMilliseconds);
+                case JSON_RPC.connectionClosed:
+                    return networkFailure(error, this.settings.mcpUrl, this.timeoutMilliseconds);
+                case JSON_RPC.invalidParams:
+                case JSON_RPC.invalidRequest:
+                case JSON_RPC.methodNotFound:
+                    return new CliError({
+                        code: 'MCP_REJECTED',
+                        message,
+                        exitCode: EXIT_CODES.rejected,
+                        hint: 'The server did not accept the call. This CLI may be older than the server: `widgetic doctor` compares them.',
+                        cause: error
+                    });
+                default:
+                    return new CliError({
+                        code: `MCP_ERROR_${Math.abs(error.code)}`,
+                        message,
+                        exitCode: EXIT_CODES.failure,
+                        cause: error
+                    });
+            }
+        }
+        if (isHttpError(error) && typeof error.code === 'number' && error.code > 0) {
+            return new CliError({
+                code: `HTTP_${error.code}`,
+                message: error.message,
+                exitCode: exitCodeForStatus(error.code),
+                status: error.code,
+                cause: error
+            });
+        }
+        return networkFailure(error, this.settings.mcpUrl, this.timeoutMilliseconds);
+    }
+}

package/dist/mcp/wait.js

@@ -0,0 +1,68 @@
+import { CliError, EXIT_CODES } from "../errors.js";
+import { note } from "../output.js";
+import { WAIT_OVERLAY } from "../overlay.js";
+import { retryNotifier, withRetries } from "../retry.js";
+import { refusalOf } from "./session.js";
+/**
+ * `--wait`: a tool that starts a build answers at once with the widget's id and the phase it is in; the command then
+ * asks the poll tool again and again until the phase is one of the finished ones, and its result is the finished
+ * widget. What is waited for, and how often it is asked, is the overlay (`overlay.ts`), checked against the manifests.
+ */
+function phaseOf(outcome) {
+    const phase = outcome.structured?.[WAIT_OVERLAY.phaseProperty];
+    return typeof phase === 'string' ? phase : undefined;
+}
+export async function waitForBuild(environment, connection, started, json) {
+    const widgetId = started.structured?.[WAIT_OVERLAY.idProperty];
+    if (typeof widgetId !== 'string') {
+        throw new CliError({
+            code: 'WAIT_UNAVAILABLE',
+            message: `--wait: the answer names no widget (${WAIT_OVERLAY.idProperty}), so there is nothing to wait for.`,
+            exitCode: EXIT_CODES.failure,
+            details: started.structured
+        });
+    }
+    const readyPhases = WAIT_OVERLAY.readyPhases;
+    const failedPhases = WAIT_OVERLAY.failedPhases;
+    const clockStart = environment.now().getTime();
+    let waitedSeconds = 0;
+    let reported;
+    let outcome = started;
+    for (;;) {
+        const phase = phaseOf(outcome);
+        if (phase !== undefined && phase !== reported) {
+            reported = phase;
+            if (!json)
+                note(environment, `Widget ${widgetId}: ${phase}`);
+        }
+        if (phase !== undefined && readyPhases.includes(phase))
+            return outcome;
+        if (phase !== undefined && failedPhases.includes(phase)) {
+            throw new CliError({
+                code: 'BUILD_FAILED',
+                message: `The build of widget ${widgetId} ended in phase "${phase}".`,
+                exitCode: EXIT_CODES.rejected,
+                details: outcome.structured,
+                hint: `See the widget: widgetic mcp get-widget --${WAIT_OVERLAY.idProperty.replace(/_/g, '-')} ${widgetId}`
+            });
+        }
+        const elapsed = Math.max(waitedSeconds, (environment.now().getTime() - clockStart) / 1000);
+        if (elapsed >= WAIT_OVERLAY.defaultMaxSeconds) {
+            throw new CliError({
+                code: 'WAIT_TIMED_OUT',
+                message: `Widget ${widgetId} is still building (phase: ${phase ?? 'unknown'}) after ${Math.round(WAIT_OVERLAY.defaultMaxSeconds / 60)} minutes. It keeps going on the server.`,
+                exitCode: EXIT_CODES.failure,
+                details: outcome.structured,
+                hint: `Look again later: widgetic mcp get-widget --${WAIT_OVERLAY.idProperty.replace(/_/g, '-')} ${widgetId}`
+            });
+        }
+        await environment.sleep(WAIT_OVERLAY.pollIntervalSeconds * 1000);
+        waitedSeconds += WAIT_OVERLAY.pollIntervalSeconds;
+        outcome = await withRetries(environment, { safeToRepeat: true }, async () => {
+            const polled = await connection.call(WAIT_OVERLAY.pollTool, { [WAIT_OVERLAY.idProperty]: widgetId });
+            if (polled.isError)
+                throw refusalOf(polled);
+            return polled;
+        }, retryNotifier(environment, json));
+    }
+}