dexto 1.14.6 → 2.0.0-beta.1

package/dist/cli/cloud/output.d.ts

@@ -0,0 +1,34 @@
+import type { CloudRuntime } from './runtime.js';
+export interface Column<Row> {
+    readonly header: string;
+    readonly value: (row: Row) => string | number | boolean | null | undefined;
+}
+export interface Output {
+    /** Whether records and lists print as JSON. */
+    readonly json: boolean;
+    /**
+     * Whether content, such as a file, a command's output or a model's reply, prints as its JSON
+     * record: only with an explicit --json, so piped content stays intact.
+     */
+    readonly jsonContent: boolean;
+    /** A page of a list: a table, plus how to read the next page when there is one. */
+    list<Row>(page: ListPage<Row>, columns: readonly Column<Row>[]): void;
+    /** One resource: its fields, one per line. */
+    record(value: unknown): void;
+    /** A line for people; JSON output prints the value instead. */
+    result(value: unknown, text: string): void;
+    /** Progress and hints, on stderr so stdout stays parseable. */
+    note(text: string): void;
+}
+/** A list, paged or not: some `/v1` lists return everything at once. */
+export type ListPage<Row> = {
+    readonly data: readonly Row[];
+} | {
+    readonly data: readonly Row[];
+    readonly has_more: boolean;
+    readonly next_after: string | number | null;
+};
+/** `json` and `table` as asked; `auto` is tables at a terminal and JSON anywhere else. */
+export type OutputFormat = 'auto' | 'json' | 'table';
+export declare function createOutput(runtime: CloudRuntime, format: OutputFormat): Output;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/cloud/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/output.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,MAAM,CAAC,GAAG;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;CAC9E;AAED,MAAM,WAAW,MAAM;IACnB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,mFAAmF;IACnF,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,SAAS,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC;IACtE,8CAA8C;IAC9C,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,+DAA+D;IAC/D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3C,+DAA+D;IAC/D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wEAAwE;AACxE,MAAM,MAAM,QAAQ,CAAC,GAAG,IAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,CAAA;CAAE,GACjC;IACI,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AAER,0FAA0F;AAC1F,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAiChF"}

package/dist/cli/cloud/output.js

@@ -0,0 +1,77 @@
+// Prints API values: JSON for agents (--json, or stdout not a terminal), tables for people.
+import chalk from 'chalk';
+import { jsonResult } from '../output.js';
+export function createOutput(runtime, format) {
+    const json = format === 'json' || (format === 'auto' && !runtime.stdoutIsTerminal);
+    const color = runtime.color;
+    const printJson = (value) => {
+        runtime.writeOutput(jsonResult(value));
+    };
+    return {
+        json,
+        jsonContent: format === 'json',
+        list(page, columns) {
+            if (json)
+                return printJson(page);
+            if (page.data.length === 0) {
+                runtime.writeOutput(`${dim('None.', color)}\n`);
+                return;
+            }
+            runtime.writeOutput(renderTable(page.data, columns, color));
+            if ('next_after' in page && page.has_more && page.next_after !== null)
+                runtime.writeError(`${dim(`More results: add --after ${String(page.next_after)}`, color)}\n`);
+        },
+        note(text) {
+            runtime.writeError(`${dim(text, color)}\n`);
+        },
+        record(value) {
+            if (json)
+                return printJson(value);
+            runtime.writeOutput(renderRecord(value, color));
+        },
+        result(value, text) {
+            if (json)
+                return printJson(value);
+            runtime.writeOutput(`${text}\n`);
+        },
+    };
+}
+function renderTable(rows, columns, color) {
+    const cells = rows.map((row) => columns.map((column) => cell(column.value(row))));
+    const widths = columns.map((column, index) => Math.max(column.header.length, ...cells.map((row) => (row[index] ?? '').length)));
+    const line = (values) => values
+        .map((value, index) => index === values.length - 1 ? value : value.padEnd(widths[index] ?? 0))
+        .join('  ')
+        .trimEnd();
+    const header = line(columns.map((column) => column.header.toUpperCase()));
+    return `${color ? chalk.bold(header) : header}\n${cells.map(line).join('\n')}\n`;
+}
+/** Top-level fields aligned; nested values as compact JSON. */
+function renderRecord(value, color) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return `${JSON.stringify(value, null, 2)}\n`;
+    const entries = Object.entries(value);
+    const width = Math.max(...entries.map(([key]) => key.length));
+    return `${entries
+        .map(([key, field]) => `${dim(key.padEnd(width), color)}  ${recordField(field)}`)
+        .join('\n')}\n`;
+}
+function recordField(value) {
+    if (value === null)
+        return '-';
+    if (typeof value === 'string')
+        return value.includes('\n') ? JSON.stringify(value) : value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+const MAX_CELL = 60;
+function cell(value) {
+    if (value === null || value === undefined)
+        return '-';
+    const text = String(value).replace(/\s+/gu, ' ');
+    return text.length > MAX_CELL ? `${text.slice(0, MAX_CELL - 1)}…` : text;
+}
+function dim(text, color) {
+    return color ? chalk.dim(text) : text;
+}

package/dist/cli/cloud/run.d.ts

@@ -0,0 +1,26 @@
+import { type Command, type OptionSpec } from './command.js';
+import type { SignInFor } from './commands/account.js';
+import type { Connection, ConnectionOverrides } from './connection.js';
+import type { CloudRuntime } from './runtime.js';
+/** One area of commands in help, such as `projects` under `cloud`. */
+export interface Group {
+    readonly name: string;
+    readonly summary: string;
+}
+/** What the commands run against: injected so tests use a fake server and sign-in. */
+export interface CloudHost {
+    readonly commands: readonly Command[];
+    /** Help's areas by the words before them, such as `cloud`. */
+    readonly groups: Readonly<Record<string, readonly Group[]>>;
+    readonly runtime: CloudRuntime;
+    /** The connection for these overrides; null when signed out. */
+    readonly resolveConnection: (overrides: ConnectionOverrides) => Promise<Connection | null>;
+    /** The sign-in context login, logout, whoami and accounts run in. */
+    readonly signIn: SignInFor;
+    /** Signs the profile in again asking for `scope`; true once it did. */
+    readonly signInForScope: (overrides: ConnectionOverrides, scope: string) => Promise<boolean>;
+}
+export declare const GLOBAL_OPTIONS: Readonly<Record<string, OptionSpec>>;
+/** Runs one command line, such as `cloud secrets list --json`; returns its exit code. */
+export declare function runCloud(host: CloudHost, argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/cloud/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/run.ts"],"names":[],"mappings":"AAQA,OAAO,EAIH,KAAK,OAAO,EAEZ,KAAK,UAAU,EAElB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAOvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,sEAAsE;AACtE,MAAM,WAAW,KAAK;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,iBAAiB,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC3F,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,CAAC,SAAS,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChG;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAgC/D,CAAC;AASF,yFAAyF;AACzF,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAExF"}

package/dist/cli/cloud/run.js

@@ -0,0 +1,444 @@
+// Runs `dexto cloud …` and the other ported cloud commands: global options, help, the agent
+// contract's JSON output and exit codes, and signing in again for a permission a command lacked.
+import { CommandFailure, EXIT_CODE_MEANINGS, EXIT_CODES } from '../failure.js';
+import { parseArgs } from 'node:util';
+import { jsonError } from '../output.js';
+import { CloudApiError, createCloudClient } from '@dexto/cloud-client';
+import { MissingScopeFailure, signInCommand, UsageError, } from './command.js';
+import { listWorkspaceApps, runWorkspaceApp, } from './commands/workspace-apps.js';
+import { createOutput } from './output.js';
+export const GLOBAL_OPTIONS = {
+    'api-base-url': {
+        description: 'The API origin (default https://api.dexto.ai, or DEXTO_API_BASE_URL).',
+        type: 'string',
+        valueName: 'URL',
+    },
+    'api-key': {
+        description: 'Use this key instead of DEXTO_API_KEY or the saved sign-in.',
+        type: 'string',
+        valueName: 'KEY',
+    },
+    profile: {
+        description: 'The saved sign-in to use for this run (or DEXTO_PROFILE); see dexto accounts list.',
+        type: 'string',
+        valueName: 'NAME',
+    },
+    project: {
+        description: "The Cloud project to act in when you're signed in (or DEXTO_CLOUD_PROJECT).",
+        type: 'string',
+        valueName: 'ID',
+    },
+    help: { description: 'Show help.', short: 'h', type: 'boolean' },
+    json: {
+        description: "Print JSON, failures included (on stderr). The default when stdout isn't a terminal.",
+        type: 'boolean',
+    },
+    table: {
+        description: "Print tables for people even when stdout isn't a terminal.",
+        type: 'boolean',
+    },
+};
+const NO_OVERRIDES = {
+    apiBaseUrl: null,
+    apiKey: null,
+    cloudProject: null,
+    profile: null,
+};
+/** Runs one command line, such as `cloud secrets list --json`; returns its exit code. */
+export async function runCloud(host, argv) {
+    return await run(host, argv, true);
+}
+async function run(host, argv, mayGrant) {
+    const { runtime } = host;
+    let globals;
+    try {
+        globals = extractGlobals(argv);
+    }
+    catch (error) {
+        // The format isn't settled yet: JSON as asked, or when no one reads stdout.
+        return reportError({ overrides: NO_OVERRIDES, runtime }, argv.includes('--json') || !runtime.stdoutIsTerminal, groupHelp(host, argv.slice(0, 1)), error);
+    }
+    const { command, words, rest } = matchCommand(host.commands, globals.rest);
+    // `workspace` alone lists the apps; `workspace <app> …` is one of them, its operations from the
+    // server. The CLI's own `workspace` commands, such as `tools` and `drive put`, match above.
+    if (command === null && words[0] === 'workspace')
+        return await runWorkspace(host, globals, argv, mayGrant);
+    if (command === null) {
+        if (!host.commands.some((each) => startsWith(each.path, words)))
+            return reportError({ overrides: globals.overrides, runtime }, createOutput(runtime, globals.format).json, groupHelp(host, words.slice(0, 1)), new UsageError(`Unknown command: dexto ${words.join(' ')}`));
+        return printHelp(runtime, globals, groupHelp(host, words), groupHelpJson(host, words));
+    }
+    if (globals.help)
+        return printHelp(runtime, globals, commandHelp(command), commandHelpJson(command));
+    const output = createOutput(runtime, globals.format);
+    const signIn = { overrides: globals.overrides, runtime };
+    try {
+        const parsed = parseArgs({
+            allowPositionals: true,
+            args: [...rest],
+            options: Object.fromEntries(Object.entries(command.options ?? {}).map(([name, spec]) => [
+                name,
+                {
+                    type: spec.type,
+                    ...(spec.multiple === true ? { multiple: true } : {}),
+                    ...(spec.short === undefined ? {} : { short: spec.short }),
+                },
+            ])),
+            strict: true,
+        });
+        const required = (command.arguments ?? '').match(/<[^>]+>/gu)?.length ?? 0;
+        if (parsed.positionals.length < required)
+            throw new UsageError(`Missing arguments: ${command.arguments ?? ''}`);
+        return (await command.run(contextFor(host, globals, output), parsed)) ?? 0;
+    }
+    catch (thrown) {
+        const error = asMissingScope(signIn, thrown);
+        if (mayGrant &&
+            error instanceof MissingScopeFailure &&
+            runtime.prompt !== null &&
+            !output.json &&
+            (await askToGrant(host, globals.overrides, error)))
+            return await run(host, argv, false);
+        return reportError(signIn, output.json, commandHelp(command), error);
+    }
+}
+/** `workspace` or `workspace <app> [operation] [action] [--field value…]`. */
+async function runWorkspace(host, globals, argv, mayGrant) {
+    const output = createOutput(host.runtime, globals.format);
+    const context = contextFor(host, globals, output);
+    const args = globals.rest.slice(1);
+    try {
+        if (args.every((arg) => arg.startsWith('-'))) {
+            const apps = await listWorkspaceApps(context);
+            return printHelp(host.runtime, globals, workspaceHelp(host, apps), {
+                apps,
+                ...groupHelpJson(host, ['workspace']),
+            });
+        }
+        const appId = args[0] ?? '';
+        return await runWorkspaceApp(context, args, globals.help, host.commands
+            .filter((each) => each.path[0] === 'workspace' && each.path[1] === appId)
+            .map((each) => ({
+            name: each.path.slice(2).join(' '),
+            summary: each.summary,
+            usage: `dexto ${usage(each)}`,
+        })));
+    }
+    catch (thrown) {
+        const error = asMissingScope(context, thrown);
+        if (mayGrant &&
+            error instanceof MissingScopeFailure &&
+            host.runtime.prompt !== null &&
+            !output.json &&
+            (await askToGrant(host, globals.overrides, error)))
+            return await run(host, argv, false);
+        return reportError(context, output.json, workspaceHelp(host, null), error);
+    }
+}
+/** The workspace's apps, when listed, and the CLI's own workspace commands. */
+function workspaceHelp(host, apps) {
+    const commands = host.commands.filter((command) => command.path[0] === 'workspace');
+    const usages = commands.map((command) => usage(command));
+    const width = Math.max(...usages.map((line) => line.length));
+    return [
+        'Usage: dexto workspace <app> [operation] [--field value…] [--yes]',
+        '       dexto workspace <command>',
+        '',
+        'Use your Dexto workspace as yourself: the apps and tools your agents use over the Dexto MCP.',
+        '',
+        "Your workspace's apps (dexto workspace <app> lists what each does):",
+        ...(apps === null
+            ? ['  Run dexto workspace while signed in to list them.']
+            : apps.length === 0
+                ? ['  None yet.']
+                : [`  ${apps.map((app) => app.id).join(' · ')}`]),
+        '',
+        'Commands:',
+        ...commands.map((command, index) => `  ${(usages[index] ?? '').padEnd(width)}  ${command.summary}`),
+        '',
+        'Find what to run: dexto find "<what you want to do>"',
+        '',
+    ].join('\n');
+}
+/** At a terminal, offers to sign in again for the permission; true once that sign-in succeeded. */
+async function askToGrant(host, overrides, error) {
+    const answer = (await host.runtime.prompt?.(`${error.message} Sign in again to grant it? [y/N] `, {
+        secret: false,
+    })) ?? '';
+    if (!/^y(es)?$/iu.test(answer.trim()))
+        return false;
+    return await host.signInForScope(overrides, error.scope);
+}
+function contextFor(host, globals, output) {
+    const { overrides } = globals;
+    const connection = async () => {
+        const resolved = await host.resolveConnection(overrides);
+        if (resolved !== null)
+            return resolved;
+        throw new CommandFailure('needs_sign_in', 'Not signed in. Sign in, or set DEXTO_API_KEY to a developer key from your Cloud project.', signInCommand({ overrides, runtime: host.runtime }, null));
+    };
+    return {
+        client: async () => {
+            const resolved = await connection();
+            return createCloudClient({
+                apiBaseUrl: resolved.apiBaseUrl,
+                token: resolved.token,
+                // A key acts in its own project; only a person's token names one.
+                cloudProject: resolved.kind === 'oauth' ? resolved.cloudProject : null,
+                fetch: host.runtime.fetch,
+            });
+        },
+        connection,
+        invocation: globals.invocation,
+        output,
+        overrides,
+        runtime: host.runtime,
+    };
+}
+/** A `/v1` refusal that names the scope the sign-in lacks; any other error as it is. */
+function asMissingScope(context, error) {
+    if (!(error instanceof CloudApiError) || error.status !== 403)
+        return error;
+    const details = error.details;
+    const scope = typeof details === 'object' && details !== null && 'scope' in details
+        ? details.scope
+        : undefined;
+    if (typeof scope !== 'string')
+        return error;
+    return new MissingScopeFailure(context, scope, error.message);
+}
+/**
+ * Prints a failure and returns its exit code: JSON on stderr for agents, otherwise a message with
+ * the command's usage (for a usage mistake) or the command that fixes it.
+ */
+function reportError(context, json, help, error) {
+    const { runtime } = context;
+    const failure = describeFailure(context, error);
+    if (json) {
+        runtime.writeError(jsonError({
+            code: failure.code,
+            message: failure.message,
+            ...(failure.fix === null ? {} : { fix: failure.fix }),
+            ...(failure.apiCode === null ? {} : { api_code: failure.apiCode }),
+            ...(failure.details === null ? {} : { details: failure.details }),
+        }));
+    }
+    else if (failure.code === 'usage') {
+        runtime.writeError(`${failure.message}\n\n${help}`);
+    }
+    else {
+        runtime.writeError(`Error${failure.apiCode === null ? '' : ` (${failure.apiCode})`}: ${failure.message}\n`);
+        if (failure.details !== null)
+            runtime.writeError(`${JSON.stringify(failure.details, null, 2)}\n`);
+        if (failure.fix !== null)
+            runtime.writeError(`Run: ${failure.fix}\n`);
+    }
+    return EXIT_CODES[failure.code];
+}
+function describeFailure(context, error) {
+    const report = (code, message, fix, apiCode, details) => ({ apiCode, code, details: details ?? null, fix, message });
+    if (error instanceof UsageError || isParseArgsError(error))
+        return report('usage', error.message, null, null, null);
+    if (error instanceof CommandFailure)
+        return report(error.kind, error.message, error.fix, null, null);
+    if (error instanceof CloudApiError) {
+        if (error.status === 401)
+            return report('needs_sign_in', error.message, signInCommand(context, null), error.code, error.details);
+        return report(error.status === 403
+            ? 'needs_permission'
+            : error.status === 404
+                ? 'not_found'
+                : error.status === 400 || error.status === 413 || error.status === 422
+                    ? 'invalid_input'
+                    : 'failed', error.message, null, error.code, error.details);
+    }
+    if (error instanceof Error)
+        return report('failed', error.message, null, null, null);
+    return report('failed', 'The command failed.', null, null, null);
+}
+/** Takes the global options out wherever they appear, before the command's own parsing. */
+function extractGlobals(argv) {
+    const rest = [];
+    let apiBaseUrl = null;
+    let apiKey = null;
+    let cloudProject = null;
+    let profile = null;
+    let help = false;
+    let json = false;
+    let table = false;
+    const invocation = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? '';
+        if (token === '--') {
+            rest.push(...argv.slice(index));
+            invocation.push(...argv.slice(index));
+            break;
+        }
+        const [name, inline] = token.startsWith('--') ? splitOption(token) : [token, null];
+        if (name === '--api-key' ||
+            name === '--api-base-url' ||
+            name === '--profile' ||
+            name === '--project') {
+            const value = inline ?? argv[index + 1];
+            // Never take another option as the value, so `--project --api-key KEY` can't leave
+            // the key behind as a word that gets printed back.
+            if (value === undefined || (inline === null && value.startsWith('-')))
+                throw new UsageError(`Missing value for ${name}.`);
+            if (inline === null)
+                index += 1;
+            if (name === '--api-key')
+                apiKey = value;
+            else {
+                invocation.push(name, value);
+                if (name === '--project')
+                    cloudProject = value;
+                else if (name === '--profile')
+                    profile = value;
+                else
+                    apiBaseUrl = value;
+            }
+            continue;
+        }
+        if (token === '--json')
+            json = true;
+        else if (token === '--table')
+            table = true;
+        else if (token === '--help' || token === '-h')
+            help = true;
+        else
+            rest.push(token);
+        if (token !== '--help' && token !== '-h')
+            invocation.push(token);
+    }
+    if (json && table)
+        throw new UsageError('Pass --json or --table, not both.');
+    return {
+        format: json ? 'json' : table ? 'table' : 'auto',
+        help,
+        invocation,
+        overrides: { apiBaseUrl, apiKey, cloudProject, profile },
+        rest,
+    };
+}
+function splitOption(token) {
+    const equals = token.indexOf('=');
+    return equals === -1 ? [token, null] : [token.slice(0, equals), token.slice(equals + 1)];
+}
+/** The longest command whose path the leading words spell. */
+function matchCommand(commands, tokens) {
+    const words = [];
+    for (const token of tokens) {
+        if (token.startsWith('-'))
+            break;
+        const next = [...words, token];
+        if (!commands.some((command) => startsWith(command.path, next)))
+            break;
+        words.push(token);
+    }
+    for (let length = words.length; length > 0; length -= 1) {
+        const prefix = words.slice(0, length);
+        const command = commands.find((each) => each.path.length === length && startsWith(each.path, prefix));
+        if (command !== undefined)
+            return { command, rest: tokens.slice(length), words: prefix };
+    }
+    const rest = tokens.slice(words.length);
+    // A word after a group that names none of its commands, such as `cloud chat`, is unknown.
+    const unknown = rest[0] !== undefined && !rest[0].startsWith('-') ? [rest[0]] : [];
+    return {
+        command: null,
+        rest,
+        words: words.length === 0
+            ? tokens.filter((token) => !token.startsWith('-'))
+            : [...words, ...unknown],
+    };
+}
+function startsWith(path, prefix) {
+    return prefix.every((word, index) => path[index] === word);
+}
+/** Help as text for people, or as JSON where the output is JSON. */
+function printHelp(runtime, globals, text, json) {
+    if (createOutput(runtime, globals.format).json)
+        runtime.writeOutput(`${JSON.stringify(json, null, 2)}\n`);
+    else
+        runtime.writeOutput(text);
+    return 0;
+}
+/** A layer's own areas when it has them, otherwise its commands with their usage. */
+function groupHelp(host, words) {
+    const areas = host.groups[words.join(' ')];
+    if (areas !== undefined) {
+        const width = Math.max(...areas.map((group) => group.name.length));
+        return [
+            `Usage: dexto ${words.join(' ')} <command>`,
+            '',
+            'Commands:',
+            ...areas.map((group) => `  ${group.name.padEnd(width)}  ${group.summary}`),
+            '',
+            'Global options:',
+            ...optionLines(GLOBAL_OPTIONS),
+            '',
+            "Output is JSON when stdout isn't a terminal; a failure's JSON on stderr names the command",
+            'that fixes it. Exit codes: 0 done, 1 failed, 2 usage, 3 needs sign-in or permission,',
+            '4 needs --yes (pass it only once your person has agreed), 5 not found, 6 waiting on a',
+            'person (such as an approval).',
+            '',
+        ].join('\n');
+    }
+    const commands = host.commands.filter((command) => startsWith(command.path, words));
+    const usages = commands.map((command) => usage(command));
+    const width = Math.max(...usages.map((line) => line.length));
+    return [
+        `Usage: dexto ${words.join(' ')} <command>`,
+        '',
+        'Commands:',
+        ...commands.map((command, index) => `  ${(usages[index] ?? '').padEnd(width)}  ${command.summary}`),
+        '',
+    ].join('\n');
+}
+function groupHelpJson(host, words) {
+    return {
+        commands: host.commands
+            .filter((command) => startsWith(command.path, words))
+            .map((command) => ({ summary: command.summary, usage: `dexto ${usage(command)}` })),
+        exit_codes: EXIT_CODE_MEANINGS,
+        usage: `dexto ${words.join(' ')} <command>`,
+    };
+}
+function commandHelp(command) {
+    return [
+        `Usage: dexto ${usage(command)}${command.options === undefined ? '' : ' [options]'}`,
+        '',
+        command.summary,
+        '',
+        ...(command.options === undefined ? [] : ['Options:', ...optionLines(command.options), '']),
+        'Global options:',
+        ...optionLines(GLOBAL_OPTIONS),
+        '',
+    ].join('\n');
+}
+function commandHelpJson(command) {
+    return {
+        options: Object.entries({ ...command.options, ...GLOBAL_OPTIONS }).map(([name, spec]) => ({
+            description: spec.description,
+            name: `--${name}`,
+            type: spec.type,
+            ...(spec.multiple === true ? { multiple: true } : {}),
+        })),
+        summary: command.summary,
+        usage: `dexto ${usage(command)}`,
+    };
+}
+function usage(command) {
+    return [...command.path, ...(command.arguments === undefined ? [] : [command.arguments])].join(' ');
+}
+function optionLines(options) {
+    const labels = Object.entries(options).map(([name, spec]) => `${spec.short === undefined ? '    ' : `-${spec.short}, `}--${name}${spec.type === 'string' ? ` ${spec.valueName ?? 'VALUE'}` : ''}${spec.multiple === true ? ' ...' : ''}`);
+    const width = Math.max(...labels.map((label) => label.length));
+    return Object.values(options).map((spec, index) => `  ${(labels[index] ?? '').padEnd(width)}  ${spec.description}`);
+}
+function isParseArgsError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        error.code.startsWith('ERR_PARSE_ARGS_'));
+}

package/dist/cli/cloud/runtime.d.ts

@@ -0,0 +1,33 @@
+export interface CloudRuntime {
+    /** Whether to color what people read: a terminal that shows colors. */
+    readonly color: boolean;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+    readonly fetch: typeof globalThis.fetch;
+    /** Where other agents keep their chats, such as ~/.claude and ~/.codex. */
+    readonly homeDirectory: string;
+    /** Asks the person at the terminal; null when stdin is not a terminal. */
+    readonly prompt: ((question: string, options: {
+        secret: boolean;
+    }) => Promise<string>) | null;
+    /** All of stdin as text, for piped input. */
+    readonly readStdin: () => Promise<string>;
+    /** Runs a program, such as a project's packer, and returns its exit code and what it printed. */
+    readonly runProcess: (command: string, args: readonly string[], options: {
+        readonly cwd: string;
+    }) => Promise<ProcessResult>;
+    readonly signal: AbortSignal;
+    /** Waits, ending early with an error when the command is cancelled. */
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly stdoutIsTerminal: boolean;
+    /** Raw bytes to stdout, such as a downloaded file. */
+    readonly writeBytes: (chunk: Uint8Array) => Promise<void>;
+    readonly writeError: (text: string) => void;
+    readonly writeOutput: (text: string) => void;
+}
+export interface ProcessResult {
+    readonly exitCode: number;
+    /** Its stdout and stderr together, as a person would have seen them. */
+    readonly output: string;
+}
+export declare function nodeCloudRuntime(signal: AbortSignal): CloudRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/cli/cloud/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/runtime.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IACzB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;IAC9F,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAChC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CA2BlE"}