dexto 1.14.4 → 2.0.0-beta.0

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 { parseArgs } from 'node:util';
+import { CloudApiError, createCloudClient } from '@dexto/cloud-client';
+import { CommandFailure, EXIT_CODE_MEANINGS, EXIT_CODES, 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(`${JSON.stringify({
+            error: {
+                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 }),
+            },
+        }, null, 2)}\n`);
+    }
+    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"}

package/dist/cli/cloud/runtime.js

@@ -0,0 +1,86 @@
+// The process the cloud commands run in, injected so tests drive the public command boundary.
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import chalk from 'chalk';
+export function nodeCloudRuntime(signal) {
+    return {
+        color: process.stdout.isTTY === true && chalk.level > 0,
+        environment: process.env,
+        fetch: globalThis.fetch.bind(globalThis),
+        homeDirectory: homedir(),
+        prompt: process.stdin.isTTY === true ? promptAtTerminal : null,
+        readStdin: async () => {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(Buffer.from(chunk));
+            return Buffer.concat(chunks).toString('utf8');
+        },
+        runProcess: (command, args, options) => runProcess(command, args, options.cwd, signal),
+        signal,
+        sleep: (ms) => delay(ms, undefined, { signal }),
+        stdoutIsTerminal: process.stdout.isTTY === true,
+        writeBytes: (chunk) => new Promise((resolve, reject) => process.stdout.write(chunk, (error) => (error ? reject(error) : resolve()))),
+        writeError: (text) => {
+            process.stderr.write(text);
+        },
+        writeOutput: (text) => {
+            process.stdout.write(text);
+        },
+    };
+}
+function runProcess(command, args, cwd, signal) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, signal, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        child.stdout.on('data', (chunk) => (output += chunk.toString('utf8')));
+        child.stderr.on('data', (chunk) => (output += chunk.toString('utf8')));
+        child.once('error', reject);
+        child.once('close', (code) => resolve({ exitCode: code ?? 1, output }));
+    });
+}
+async function promptAtTerminal(question, options) {
+    if (options.secret)
+        return await readHidden(question);
+    const readline = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await readline.question(question);
+    }
+    finally {
+        readline.close();
+    }
+}
+/** Reads a line without echoing it, for API keys and secret values. */
+function readHidden(question) {
+    return new Promise((resolve, reject) => {
+        const input = process.stdin;
+        let value = '';
+        const finish = (error) => {
+            input.off('data', onData);
+            input.setRawMode(false);
+            input.pause();
+            process.stderr.write('\n');
+            if (error === null)
+                resolve(value);
+            else
+                reject(error);
+        };
+        const onData = (chunk) => {
+            for (const character of chunk.toString('utf8')) {
+                if (character === '\r' || character === '\n')
+                    return finish(null);
+                if (character === '\u0003')
+                    return finish(new Error('Cancelled.'));
+                if (character === '\u007f' || character === '\b')
+                    value = value.slice(0, -1);
+                else
+                    value += character;
+            }
+        };
+        process.stderr.write(question);
+        input.setRawMode(true);
+        input.resume();
+        input.on('data', onData);
+    });
+}

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

@@ -0,0 +1,9 @@
+export interface TarFile {
+    readonly bytes: Uint8Array;
+    readonly executable: boolean;
+    /** Relative, with `/` between segments. */
+    readonly path: string;
+}
+/** The archive of these files in order, closed by its two empty blocks. */
+export declare function tarArchive(files: readonly TarFile[]): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=tar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tar.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/tar.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,OAAO;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,CA6B7E"}

package/dist/cli/cloud/tar.js

@@ -0,0 +1,69 @@
+// Writes a POSIX ustar archive as Dexto's Skill bundle import reads one: files, PAX for long paths.
+const BLOCK_BYTES = 512;
+const encoder = new globalThis.TextEncoder();
+/** The archive of these files in order, closed by its two empty blocks. */
+export function tarArchive(files) {
+    const blocks = [];
+    for (const [index, file] of files.entries()) {
+        // A path past the 100-byte name field rides in a PAX header for the entry after it.
+        const pax = paxPathBody(file.path);
+        if (pax !== null)
+            blocks.push(tarHeader({
+                mode: 0o644,
+                name: `PaxHeaders/${index}`,
+                size: pax.length,
+                type: 'x',
+            }), pax, padding(pax.length));
+        blocks.push(tarHeader({
+            mode: file.executable ? 0o755 : 0o644,
+            name: pax === null ? file.path : `file-${index}`,
+            size: file.bytes.length,
+            type: '0',
+        }), file.bytes, padding(file.bytes.length));
+    }
+    blocks.push(new Uint8Array(BLOCK_BYTES * 2));
+    return Buffer.concat(blocks);
+}
+function tarHeader(input) {
+    const header = new Uint8Array(BLOCK_BYTES);
+    writeText(header, 0, 100, input.name);
+    writeOctal(header, 100, 8, input.mode);
+    writeOctal(header, 108, 8, 0);
+    writeOctal(header, 116, 8, 0);
+    writeOctal(header, 124, 12, input.size);
+    writeOctal(header, 136, 12, 0);
+    // The checksum counts its own field as spaces.
+    header.fill(0x20, 148, 156);
+    writeText(header, 156, 1, input.type);
+    writeText(header, 257, 6, 'ustar');
+    writeText(header, 263, 2, '00');
+    const checksum = header.reduce((total, byte) => total + byte, 0);
+    writeText(header, 148, 6, checksum.toString(8).padStart(6, '0'));
+    header[154] = 0;
+    header[155] = 0x20;
+    return header;
+}
+function writeText(target, offset, length, value) {
+    const bytes = encoder.encode(value);
+    if (bytes.length > length)
+        throw new Error(`Tar header value is too long: ${value}`);
+    target.set(bytes, offset);
+}
+function writeOctal(target, offset, length, value) {
+    writeText(target, offset, length, `${value.toString(8).padStart(length - 1, '0')}\0`);
+}
+/** `<length> path=<path>\n`, whose length counts its own digits; null when the name field fits. */
+function paxPathBody(path) {
+    if (encoder.encode(path).length <= 100)
+        return null;
+    let length = encoder.encode(` path=${path}\n`).length + 1;
+    for (;;) {
+        const record = encoder.encode(`${length} path=${path}\n`);
+        if (record.length === length)
+            return record;
+        length = record.length;
+    }
+}
+function padding(size) {
+    return new Uint8Array(Math.ceil(size / BLOCK_BYTES) * BLOCK_BYTES - size);
+}

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

@@ -0,0 +1,13 @@
+import { type CommandContext } from './command.js';
+/** Where the bytes go: a short-lived URL, its method and the headers it expects. */
+export interface TransferTarget {
+    readonly headers: Readonly<Record<string, string>>;
+    readonly method: string;
+    readonly url: string;
+}
+/**
+ * Streams `body` to the target with its length, and returns the JSON reply (null when there is
+ * none). A refusal fails with the server's own message.
+ */
+export declare function sendBytes(context: CommandContext, target: TransferTarget, body: globalThis.Blob): Promise<unknown>;
+//# sourceMappingURL=transfer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/transfer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAEjF,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC3B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,UAAU,CAAC,IAAI,GACtB,OAAO,CAAC,OAAO,CAAC,CAelB"}