dedalus-cli 0.0.0-stage → 0.7.0

package/dist/esm/cli/runtime.js

@@ -0,0 +1,1345 @@
+// File generated from our OpenAPI spec by Scalar. See README.md for details.
+import { accessSync, constants as fsConstants, createReadStream, readFileSync } from 'node:fs';
+import { stdin as processStdin, stdout as processStdout } from 'node:process';
+import as from 'ansis';
+import { Command } from 'commander';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { listRow } from './list.js';
+import { encodeToon } from './toon.js';
+import { takeWarnings } from './credentials.js';
+import { UsageError, runLogin, runLogout, storedCredentials } from './login.js';
+import { createDiagnostics, diagnosticScope } from '../feedback/diagnostics.js';
+import { routeBrowserCredential } from '../custom/browser-routing.js';
+const LOGIN_COMMAND = 'dedalus login';
+// The sign-in command for the environment a request targeted.
+const loginCommandFor = (environment) => {
+    if (environment === undefined)
+        return LOGIN_COMMAND;
+    const word = /^[A-Za-z0-9._-]+$/u.test(environment) ? environment : shellQuote(environment);
+    return LOGIN_COMMAND + ' --environment ' + word;
+};
+// Quotes one word for a POSIX shell so it reaches the command exactly as written.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: dropping control characters is the point.
+const shellQuote = (value) => "'" + value.replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/gu, '').replace(/'/gu, "'\\''") + "'";
+export const createProgram = ({ SDK, binaryName, version, description, defaultFormat, defaultErrorFormat, clientOptions, commands, groups, completions, environments = [], defaultEnvironment, environmentEnv, baseUrlEnv, auth, }) => {
+    const selection = { environments, defaultEnvironment, environmentEnv, baseUrlEnv };
+    const program = usageExitCode(new Command());
+    program
+        .enablePositionalOptions()
+        .name(binaryName)
+        .description(description)
+        .version(version, '-v, --version')
+        .showHelpAfterError()
+        .option('--base-url <url>', 'Override the base URL for API requests')
+        .option('--timeout <ms>', 'Request timeout in milliseconds')
+        .option('--max-retries <count>', 'Number of retries for retryable failures')
+        .option('--format <format>', 'Output format: auto, json, jsonl, pretty, raw, toon, yaml', defaultFormat)
+        .option('--format-error <format>', 'Error output format: auto, json, jsonl, pretty, raw, toon, yaml', defaultErrorFormat)
+        .option('--transform <path>', 'Dot-path transform for data output')
+        .option('--transform-error <path>', 'Dot-path transform for error output')
+        .option('-r, --raw-output', 'Print transformed string values without JSON quotes')
+        .option('--debug', 'Enable SDK debug logging');
+    // Registered only for an API that declares more than one environment, because that is when the
+    // embedded SDK accepts an `environment` option at all. No Commander default is set: the SDK
+    // applies its own default, and a value here would look explicitly passed and trip the
+    // mutual-exclusion check below against a `--base-url` the user did pass on purpose.
+    if (environments.length > 0) {
+        program.option('--environment <name>', environmentFlagDescription(selection));
+    }
+    // Register configured client options (auth credentials, org headers, etc.) as global flags.
+    // Mirrored on each subcommand below so users can supply them either before or after the verb.
+    for (const option of clientOptions) {
+        program.option('--' + option.name + ' <value>', clientOptionDescription(option));
+    }
+    for (const definition of commands)
+        addGeneratedCommand(program, SDK, clientOptions, definition, groups, selection, auth);
+    if (environments.length > 0)
+        addEnvironmentsCommand(program, selection, defaultFormat);
+    if (completions)
+        addCompletionCommand(program, binaryName, completions);
+    if (auth)
+        addAuthCommands(program, auth, selection);
+    return program;
+};
+// Routes Commander's own exits through the documented status.
+//
+// Commander defaults every parse failure — unknown flag, missing option-argument, unknown
+// command — to exit 1, which is the status reserved here for an unclassified API failure, so a
+// caller branching on the status could not tell a typo from a request that actually ran and
+// failed. Only a zero exit (--help, --version) is passed through unchanged; everything else
+// Commander exits on is a usage error by definition.
+//
+// This has to be applied to every command object: `addCommand` does not copy the callback the
+// way `.command()` does, so setting it on the program alone would leave the subcommands — where
+// flags are actually parsed — still exiting 1.
+const usageExitCode = (command) => command.exitOverride((error) => process.exit(error.exitCode === 0 ? 0 : 2));
+// Prints the completion script for one shell. The scripts are generated from the same command
+// table this program is built from, so they always describe the commands and flags below; nothing
+// is derived from the live Commander tree, and no shell code is assembled at runtime.
+const addCompletionCommand = (program, binaryName, completions) => {
+    const shells = Object.keys(completions);
+    program
+        .command('completion')
+        .description('Print a shell completion script (' + shells.join(', ') + ')')
+        .argument('<shell>', 'Shell to print a completion script for: ' + shells.join(', '))
+        .addHelpText('after', completionHelpExamples(binaryName, shells))
+        .action((shell) => {
+        // Own-property lookup only: a bare `completions[shell]` would resolve inherited keys like
+        // "constructor" or "__proto__" to something that is not a completion script.
+        const script = Object.prototype.hasOwnProperty.call(completions, shell)
+            ? completions[shell]
+            : undefined;
+        if (script === undefined) {
+            process.stderr.write("Unsupported shell '" + shell + "'. Supported shells: " + shells.join(', ') + '\n');
+            process.exitCode = 2;
+            return;
+        }
+        processStdout.write(script);
+    });
+};
+// Shows how to load each script, since every shell wires completions up differently.
+const completionHelpExamples = (binaryName, shells) => {
+    const examples = {
+        bash: '  eval "$(' + binaryName + ' completion bash)"  # or write it to /etc/bash_completion.d',
+        zsh: '  eval "$(' + binaryName + ' completion zsh)"  # or write it to a directory on $fpath',
+        fish: '  ' + binaryName + ' completion fish | source  # or write it to ~/.config/fish/completions',
+    };
+    const lines = shells.map((shell) => examples[shell]).filter((line) => line !== undefined);
+    return lines.length > 0 ? '\nAdd one of these to your shell startup file:\n' + lines.join('\n') : '';
+};
+// Help text for `--environment`, naming the environments the embedded SDK accepts and the one it
+// falls back to.
+//
+// Kept in step with `environmentFlagDescription` in the generator's `helpers/environments.ts`, which
+// renders the same sentence into the man pages, the README, and the completion scripts. It is built
+// here rather than passed in because this runtime is one fixed file for every generated CLI: only
+// the data handed to `createProgram` varies.
+const environmentFlagDescription = ({ environments, defaultEnvironment, environmentEnv, }) => {
+    const names = environments.map((environment) => environmentLabel(environment.name)).join(', ');
+    return ('Named environment to target: ' +
+        names +
+        (environmentEnv ? ' (can also be set with ' + environmentEnv + ' env var)' : '') +
+        (defaultEnvironment ? ' (default: ' + environmentLabel(defaultEnvironment) + ')' : ''));
+};
+// Reduces a configured environment name to text that is safe on one line of the help column.
+//
+// Commander wraps a flag description into a column, so a newline in a name would tear the option
+// list apart, and a control character would be written to the terminal as an escape sequence when
+// help is printed. Only the description is reduced: `--environment` still matches against the name
+// itself, and the `environments` command prints it unchanged.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: dropping control characters is the point.
+// Whitespace collapses first, so a line break becomes the space it reads as; dropping control
+// characters first would swallow it and run the words either side of it together.
+const environmentLabel = (name) => name
+    .replace(/\s+/gu, ' ')
+    .replace(/[\u0000-\u001F\u007F-\u009F]/gu, '')
+    .trim();
+// Lists the configured environments, so what `--environment` accepts is discoverable from the CLI
+// itself rather than only from its docs.
+//
+// It prints through the same writer every generated command uses and takes its own `--format`, so a
+// script can read the URLs straight out of it (`--format json`) instead of parsing the table a human
+// reads.
+//
+// "Default" is the environment a command without `--environment` uses, so an exported
+// environment variable naming a configured one moves the mark there: every such command now goes
+// to it. An unknown name leaves the configured default marked, since every other command refuses
+// that value and this list is where a user looks up what it should have been.
+const addEnvironmentsCommand = (program, { environments, defaultEnvironment, environmentEnv }, defaultFormat) => {
+    // Read when the command runs, not when it is registered, like every other environment variable.
+    const listRows = () => {
+        const ambient = ambientEnvironment(environmentEnv);
+        const effective = environments.some((environment) => environment.name === ambient)
+            ? ambient
+            : defaultEnvironment;
+        return environments.map((environment) => ({
+            name: environment.name,
+            url: environment.url,
+            default: environment.name === effective,
+        }));
+    };
+    program
+        .command('environments')
+        .description('List the named environments --environment can select')
+        .option('--format <format>', 'Output format: auto, json, jsonl, pretty, raw, toon, yaml')
+        .action(async (options) => {
+        // A machine format asked for by name is answered with the rows; anything else is a person
+        // reading, so the list is drawn the way the sign-in picker draws its own. `auto` lands here
+        // rather than on JSON because this command exists to be read, not parsed — a script names
+        // the format it wants, and `--format json` is what the README and the man page tell it to.
+        const rows = listRows();
+        const requested = options.format ?? program.opts().format;
+        if (requested === undefined || requested === 'auto' || requested === 'pretty') {
+            writeEnvironmentList(rows);
+            return;
+        }
+        await writeOutput(rows, { format: normalizeFormat(requested, defaultFormat), title: 'environments' });
+    });
+};
+// Draws the environments as the list a person reads: the default marked and coloured, each URL
+// dimmed behind its name, through the same renderer the sign-in picker uses for its rows.
+//
+// Escapes only when stdout is a terminal, so a redirected list is the same text without them —
+// and the names are printed as configured, since this is the one place they are the value to type
+// rather than prose about it.
+const writeEnvironmentList = (rows) => {
+    const columns = Number(processStdout.columns) || 80;
+    const color = Boolean(processStdout.isTTY);
+    const width = Math.max(0, ...rows.map((row) => row.name.length));
+    for (const row of rows) {
+        const label = row.name.padEnd(width, ' ');
+        const detail = row.url + (row.default ? '  (default)' : '');
+        processStdout.write(listRow(label, detail, { columns, selected: row.default, color }) + '\n');
+    }
+};
+// The environment the selecting variable names, or undefined when it is unset or not offered.
+// Blank is unset, as the embedded SDK treats its own variables: an `export NAME=` left in a shell
+// profile must not select an environment called "". Shared by `resolveEnvironment` and the
+// `environments` list, so the two cannot disagree about which environment the variable picks.
+const ambientEnvironment = (environmentEnv) => environmentEnv ? process.env[environmentEnv]?.trim() || undefined : undefined;
+// Resolves the environment a command targets: `--environment`, else the environment variable that
+// stands in for it, checked against the configured list.
+//
+// Every failure is a usage error: no request is built for any of them, and none is one the embedded
+// SDK can report in command-line terms. An unknown name reaches the client as a key it cannot index,
+// leaving it with no base URL at all, and a URL paired with an environment is rejected there with a
+// message naming `baseURL: null` — a library construct a command line has no spelling for, which is
+// the same reason `buildClient` restates the credential guard.
+//
+// `login` and `logout` resolve through here too, because the environment decides which stored
+// credential a request carries: the two must agree on it or a sign-in lands where no request looks.
+const resolveEnvironment = (options, command, { environments, environmentEnv, baseUrlEnv }) => {
+    // Answered before the option bag is read at all: with no environments configured the CLI never
+    // registers `--environment`, so an `environment` key here belongs to something else — a client
+    // option of that name, whose value would otherwise be rejected as an environment (and, for a
+    // credential, echoed into the error).
+    if (environments.length === 0)
+        return undefined;
+    const flagged = options.environment;
+    // A URL typed on this command line outranks an environment exported for the whole shell, the
+    // precedence every other option follows — so the variable is not even read, and a stale value in
+    // it cannot fail a command that named its URL. Trimmed, as the request path trims it: a blank
+    // `--base-url` is no flag at all, so it cannot outrank anything.
+    if (flagged === undefined && options.baseUrl?.trim())
+        return undefined;
+    const ambient = ambientEnvironment(environmentEnv);
+    const selected = flagged ?? ambient;
+    if (selected === undefined)
+        return undefined;
+    const names = environments.map((environment) => environment.name);
+    if (!names.includes(selected)) {
+        command.error("error: unknown environment '" +
+            environmentLabel(selected) +
+            "'" +
+            (flagged === undefined ? ' in ' + environmentEnv : '') +
+            '. Available environments: ' +
+            names.map(environmentLabel).join(', '), { exitCode: 2 });
+    }
+    if (flagged !== undefined) {
+        // Each names a base URL on its own, so honoring either would silently discard the other.
+        // Trimmed like every other reading of the flag: a blank `--base-url` names no URL, so it
+        // conflicts with nothing, and the variable form below already treats it that way.
+        if (options.baseUrl?.trim()) {
+            command.error('error: --environment cannot be combined with --base-url, which already names the URL to call', { exitCode: 2 });
+        }
+        return selected;
+    }
+    // Two exported variables, each naming where requests go, with nothing to say which was meant.
+    // The embedded SDK refuses a base URL beside an environment for the same reason, so this is not
+    // settled by picking one: a production URL exported last week must not quietly beat a staging
+    // environment exported today, or the other way round.
+    if (baseUrlEnv && process.env[baseUrlEnv]?.trim()) {
+        command.error('error: ' +
+            environmentEnv +
+            ' and ' +
+            baseUrlEnv +
+            ' are both set, and each names where requests go. Unset one, or pass --environment or --base-url to choose.', { exitCode: 2 });
+    }
+    return selected;
+};
+// `login`/`logout` sit at the top level unless the API already claims one of those names, in
+// which case they fall back under an `auth` parent. That parent is created here rather than
+// from the command table, so it needs its own description or `--help` lists a bare `auth`,
+// which is the very thing the group table exists to prevent. Both paths are described so
+// whichever one creates the group first carries it.
+const authGroups = (auth) => [
+    { commandPath: auth.loginPath.slice(0, -1), description: 'Sign in and out' },
+    { commandPath: auth.logoutPath.slice(0, -1), description: 'Sign in and out' },
+];
+const addAuthCommands = (program, auth, selection) => {
+    const flows = auth.methods.map((method) => method.name).join(', ');
+    const login = usageExitCode(new Command(auth.loginPath.at(-1) ?? 'login'))
+        .description('Sign in and save credentials for later commands')
+        .showHelpAfterError()
+        .option('--base-url <url>', 'Sign in against this base URL instead of the default')
+        .option('--flow <name>', 'Sign-in flow to use: ' + flows)
+        .addHelpText('after', authFlowHelp(auth))
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        const environment = resolveEnvironment(options, command, selection);
+        await runAuthCommand(() => runLogin(auth, credentialBaseUrl(auth, options.baseUrl, environment), options.flow, loginCommandFor(environment)));
+    });
+    addEnvironmentOption(login, selection);
+    ensureCommandPath(program, auth.loginPath.slice(0, -1), authGroups(auth)).addCommand(login);
+    const logout = usageExitCode(new Command(auth.logoutPath.at(-1) ?? 'logout'))
+        .description('Forget saved credentials, and revoke them if the provider supports it')
+        .showHelpAfterError()
+        .option('--base-url <url>', 'Forget the credentials saved for this base URL (not with --all)')
+        .option('--all', 'Forget every saved credential, for every base URL')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        if (options.all === true) {
+            if (options.baseUrl?.trim()) {
+                command.error('error: --base-url cannot be combined with --all, which forgets the credentials of every base URL', { exitCode: 2 });
+            }
+            if (selection.environments.length > 0 && options.environment !== undefined) {
+                command.error('error: --environment cannot be combined with --all, which forgets the credentials of every environment', { exitCode: 2 });
+            }
+            await runAuthCommand(() => runLogout(auth, '', true));
+            return;
+        }
+        const environment = resolveEnvironment(options, command, selection);
+        await runAuthCommand(() => runLogout(auth, credentialBaseUrl(auth, options.baseUrl, environment), false));
+    });
+    addEnvironmentOption(logout, selection);
+    ensureCommandPath(program, auth.logoutPath.slice(0, -1), authGroups(auth)).addCommand(logout);
+};
+// Lets `login` and `logout` take `--environment` after the verb, as every request command does.
+const addEnvironmentOption = (command, selection) => {
+    if (selection.environments.length > 0)
+        command.option('--environment <name>', environmentFlagDescription(selection));
+};
+const runAuthCommand = async (run) => {
+    try {
+        processStdout.write((await run()) + '\n');
+    }
+    catch (error) {
+        process.stderr.write((error instanceof Error ? error.message : String(error)) + '\n');
+        process.exitCode = error instanceof UsageError ? 2 : 10;
+    }
+    finally {
+        for (const warning of takeWarnings())
+            process.stderr.write(warning + '\n');
+    }
+};
+// The base URL a stored credential is filed under for this invocation. One resolver for `login`,
+// `logout` and the request path, so a sign-in lands exactly where a later request looks.
+const credentialBaseUrl = (auth, flag, environment) => flag?.trim() ||
+    auth.environments?.find((entry) => entry.name === environment)?.url ||
+    process.env[auth.baseUrlEnv]?.trim() ||
+    auth.defaultBaseUrl;
+// Lists the flows by name so `--flow` can be used without first running the picker.
+const authFlowHelp = (auth) => '\nSign-in flows:\n' + auth.methods.map((method) => '  ' + method.name + '  ' + method.label).join('\n');
+const clientOptionDescription = (option) => {
+    const parts = [];
+    if (option.description)
+        parts.push(option.description);
+    if (option.env)
+        parts.push('(can also be set with ' + option.env + ' env var)');
+    // Stated last, matching resolution order: the flag wins, then the env var, then this value.
+    if (option.defaultValue !== undefined)
+        parts.push('(defaults to ' + option.defaultValue + ')');
+    return parts.join(' ');
+};
+// Constructs the embedded client, restating its credential guard in command-line terms.
+//
+// The SDK's own guard is worded for a library caller — "instantiate the X client with an apiKey
+// option, like new X({ apiKey: ... })" — which names something a CLI user cannot do. That wording
+// is fixed upstream to match the reference SDKs byte for byte, so it is restated here rather than
+// changed there. The environment variable is the anchor for the match: it is the one token of the
+// message this runtime also knows, so an unrelated constructor failure is rethrown untouched
+// instead of being reported as a missing credential.
+const buildClient = (SDK, options, clientOptions, environment) => {
+    try {
+        return new SDK(options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const missing = clientOptions.find((option) => option.env !== undefined && message.includes(option.env));
+        if (!missing)
+            throw error;
+        throw new Error('Missing credential: run `' +
+            loginCommandFor(environment) +
+            '`, pass --' +
+            missing.name +
+            ' <value>' +
+            (missing.env ? ' or set the ' + missing.env + ' environment variable' : '') +
+            '.');
+    }
+};
+const addGeneratedCommand = (program, SDK, clientOptions, definition, groups, selection, auth) => {
+    const parent = ensureCommandPath(program, definition.commandPath.slice(0, -1), groups);
+    const commandName = definition.commandPath.at(-1) ?? definition.methodName;
+    const command = usageExitCode(new Command(commandName))
+        .description(definition.summary ?? definition.description ?? '')
+        .showHelpAfterError()
+        .option('--base-url <url>', 'Override the base URL for API requests')
+        .option('--timeout <ms>', 'Request timeout in milliseconds')
+        .option('--max-retries <count>', 'Number of retries for retryable failures')
+        .option('--format <format>', 'Output format: auto, json, jsonl, pretty, raw, toon, yaml')
+        .option('--format-error <format>', 'Error output format: auto, json, jsonl, pretty, raw, toon, yaml')
+        .option('--transform <path>', 'Dot-path transform for data output')
+        .option('--transform-error <path>', 'Dot-path transform for error output')
+        .option('-r, --raw-output', 'Print transformed string values without JSON quotes')
+        .option('--debug', 'Enable SDK debug logging');
+    // Mirrored on the subcommand for the same reason the client options below are: so it can be
+    // passed before or after the verb. Registered only when the API declares more than one
+    // environment, matching the program-level registration.
+    if (selection.environments.length > 0) {
+        command.option('--environment <name>', environmentFlagDescription(selection));
+    }
+    // Mirror configured client-option flags on the subcommand so they can appear before or after the verb.
+    for (const option of clientOptions) {
+        command.option('--' + option.name + ' <value>', clientOptionDescription(option));
+    }
+    if (definition.iterable)
+        command.option('--max-items <count>', 'Maximum number of streamed items to print; use -1 for unlimited');
+    // Positionals are registered as optional Commander arguments because each one is also
+    // accepted as an equivalent flag (e.g. `workers retrieve wkr_1` or `workers retrieve --id
+    // wkr_1`); requiredness is enforced at call time once both spellings have been merged.
+    for (const positional of definition.positional) {
+        command.argument('[' + positional.name + ']', positional.description ?? '');
+    }
+    for (const flag of definition.flags) {
+        // A file flag takes a filesystem path, so it says so: the placeholder is the only hint in
+        // `--help` that the value is opened rather than sent verbatim.
+        const isPath = flag.valueKind === 'file' || flag.itemKind === 'file';
+        const value = flag.valueKind === 'boolean' ? '' : isPath ? ' <path>' : ' <value>';
+        if (flag.name === 'send') {
+            command.option('--' + flag.name + value, flag.description ?? '', (value, previous) => [...(previous ?? []), value]);
+            continue;
+        }
+        // Array params are repeatable single-value switches (`--status a --status b`); the custom
+        // option-argument accumulates each occurrence so Commander does not overwrite the prior value.
+        if (flag.repeatable) {
+            command.option('--' + flag.name + value, flag.description ?? '', (value, previous) => [...(previous ?? []), value]);
+            continue;
+        }
+        command.option('--' + flag.name + value, flag.description ?? '');
+    }
+    // Flag spelling for path params (`--id wkr_1`). `flagName` is absent when the name is already
+    // taken — by a global flag, a client option, a generated flag, or Commander's own `--help`, which
+    // lives in `_helpOption` where no scan of `command.options` could see it — and the param is then
+    // accepted positionally only. The decision is made once, by the emitter, so the man pages and the
+    // completion scripts advertise exactly the spellings registered here.
+    for (const positional of definition.positional) {
+        if (!positional.flagName)
+            continue;
+        command.option('--' + positional.flagName + ' <value>', positional.description ?? '');
+    }
+    command.action(async (...args) => {
+        const command = args.at(-1);
+        if (!(command instanceof Command))
+            throw new Error('Expected Commander command context');
+        const positionalValues = args.slice(0, -1);
+        await runGeneratedCommand(SDK, clientOptions, definition, command, positionalValues, selection, auth);
+    });
+    parent.addCommand(command);
+};
+const ensureCommandPath = (program, path, groups) => {
+    let parent = program;
+    const walked = [];
+    for (const part of path) {
+        walked.push(part);
+        const existing = parent.commands.find((command) => command.name() === part);
+        if (existing) {
+            parent = existing;
+            continue;
+        }
+        const next = usageExitCode(new Command(part)).showHelpAfterError();
+        // A group is created as the parent of its first command, so this is the only moment it can be
+        // described: Commander never revisits it, and an undescribed group is a bare name in --help.
+        const description = groupDescription(groups, walked);
+        if (description)
+            next.description(description);
+        parent.addCommand(next);
+        parent = next;
+    }
+    return parent;
+};
+// Matched on the full walked path rather than the last segment, so a nested group is described by
+// the resource it was actually built from and two resources sharing a leaf name cannot collide.
+const groupDescription = (groups, path) => groups?.find((group) => group.commandPath.length === path.length &&
+    group.commandPath.every((part, index) => part === path[index]))?.description;
+const runGeneratedCommand = async (SDK, clientOptions, definition, command, positionalValues, selection, auth) => {
+    const rootOptions = command.optsWithGlobals();
+    const commandOptions = command.opts();
+    // Resolved before the request is set up, not inside the try below: a rejected `--environment`
+    // is a usage error reported by Commander, and running it through the catch that classifies API
+    // failures would re-report it as one.
+    const environment = resolveEnvironment(rootOptions, command, selection);
+    const maxItems = definition.iterable ? normalizeMaxItems(commandOptions.maxItems) : undefined;
+    const outputOptions = {
+        format: normalizeFormat(commandOptions.format ?? rootOptions.format, 'auto'),
+        title: definition.commandPath.join(' '),
+        ...((commandOptions.transform ?? rootOptions.transform)
+            ? { transform: commandOptions.transform ?? rootOptions.transform }
+            : {}),
+        ...(commandOptions.rawOutput || rootOptions.rawOutput ? { rawOutput: true } : {}),
+        ...(maxItems !== undefined ? { maxItems } : {}),
+    };
+    const errorOptions = {
+        format: normalizeFormat(commandOptions.formatError ?? rootOptions.formatError, 'auto'),
+        ...((commandOptions.transformError ?? rootOptions.transformError)
+            ? { transform: commandOptions.transformError ?? rootOptions.transformError }
+            : {}),
+        ...(commandOptions.rawOutput || rootOptions.rawOutput ? { rawOutput: true } : {}),
+    };
+    let diagnostics;
+    try {
+        const clientConfig = await sdkClientOptions(rootOptions, command, clientOptions, auth, definition.authClientKeyRequirements, environment);
+        const call = await callArguments(definition, command.opts(), positionalValues);
+        const organization = call.params['X-Dedalus-Org-Id'];
+        const scopeOptions = organization === undefined ? clientConfig : { ...clientConfig, dedalusOrgID: organization };
+        diagnostics = createDiagnostics('dedalus ' + definition.commandPath.join(' '), diagnosticScope(scopeOptions));
+        const client = buildClient(SDK, { ...clientConfig, fetch: diagnostics.fetch }, clientOptions, environment);
+        const method = sdkMethod(client, definition);
+        // Required positionals are validated here (not by Commander) because each one may also be
+        // supplied through its flag spelling or stdin; `call.params` has all sources merged.
+        for (const param of definition.positional) {
+            if (param.required && call.params[param.paramKey] === undefined) {
+                command.error("error: missing required argument '" + param.name + "'", { exitCode: 2 });
+            }
+        }
+        const result = method(...call.args);
+        if (definition.transport === 'websocket') {
+            await handleWebSocket(result, call.params, outputOptions);
+            return;
+        }
+        if (definition.iterable && !definition.streaming) {
+            await writePaginated(result, outputOptions);
+            return;
+        }
+        const resolved = await result;
+        if (definition.streaming) {
+            await writeIterable(resolved, outputOptions);
+            return;
+        }
+        await writeOutput(resolved, outputOptions);
+    }
+    catch (error) {
+        diagnostics?.record({ kind: 'command_failure' });
+        await writeError(error, errorOptions, clientOptions, SDK, environment);
+        process.exitCode = errorExitCode(error, SDK);
+    }
+    finally {
+        diagnostics?.record({ kind: 'command_complete' });
+    }
+};
+// Generated commands pass operation-specific requirements. Custom commands use the API-wide requirements.
+export const sdkClientOptions = async (options, command, clientOptions, auth, requirements = auth?.requirements ?? [], environment = undefined) => {
+    // Forward configured client-option flags (auth keys, org headers, etc.) to the embedded SDK
+    // using the SDK-facing camelCased key. Only forward values that were explicitly set so the
+    // SDK's own env-var fallback keeps working when no CLI flag was passed.
+    const rootOptions = options;
+    const commandOptions = command.opts();
+    const forwarded = {};
+    for (const option of clientOptions) {
+        const commandValue = commandOptions[option.optionKey];
+        const value = commandValue === undefined ? rootOptions[option.optionKey] : commandValue;
+        if (value === undefined)
+            continue;
+        // A credential is exactly the kind of value that belongs in a file rather than in shell
+        // history, so a client option reads `@path` like any other flag. It never reaches the
+        // structured decoding below it: an SDK client option is always a scalar.
+        forwarded[option.sdkKey] = typeof value === 'string' ? clientOptionValue(value, option) : value;
+    }
+    await applyStoredCredentials(forwarded, clientOptions, requirements, auth, options.baseUrl, environment);
+    const organization = commandOptions['xDedalusOrgId'] ?? rootOptions['xDedalusOrgId'] ??
+        forwarded['dedalusOrgID'] ?? process.env['DEDALUS_ORG_ID'];
+    if (organization !== undefined)
+        forwarded['dedalusOrgID'] = organization;
+    return routeBrowserCredential({
+        ...(options.baseUrl?.trim() ? { baseURL: options.baseUrl.trim() } : {}),
+        ...(environment !== undefined ? { environment, baseURL: null } : {}),
+        ...(options.timeout ? { timeout: Number(options.timeout) } : {}),
+        ...(options.maxRetries ? { maxRetries: Number(options.maxRetries) } : {}),
+        ...(options.debug ? { logLevel: 'debug' } : {}),
+        ...forwarded,
+        defaultHeaders: {
+            'X-Request-ID': null,
+            ...(organization ? { 'X-Dedalus-Org-Id': organization } : {}),
+            'X-Scalar-Lang': 'cli',
+            'X-Scalar-Runtime': 'cli',
+            'X-Scalar-CLI-Command': command.name(),
+            'X-Dedalus-CLI-Command': commandPath(command),
+            'User-Agent': 'Dedalus/CLI ' + rootCommand(command).version(),
+        },
+    });
+};
+const applyStoredCredentials = async (forwarded, clientOptions, authClientKeyRequirements, auth, baseUrl, environment) => {
+    if (!auth)
+        return;
+    if (authClientKeyRequirements.length === 0)
+        return;
+    const hasExplicitValue = (option) => forwarded[option.sdkKey] !== undefined || Boolean(option.env && (process.env[option.env] ?? '').trim());
+    const explicit = authClientKeyRequirements.find((keys) => keys.every((key) => {
+        const option = clientOptions.find((candidate) => candidate.clientKey === key);
+        return option !== undefined && hasExplicitValue(option);
+    }));
+    if (explicit)
+        return;
+    const stored = await storedCredentials(auth, credentialBaseUrl(auth, baseUrl, environment));
+    const isSatisfiable = (keys) => keys.every((key) => {
+        const option = clientOptions.find((candidate) => candidate.clientKey === key);
+        if (!option)
+            return false;
+        return hasExplicitValue(option) || (typeof stored[key] === 'string' && stored[key] !== '');
+    });
+    const selected = authClientKeyRequirements.find((keys) => isSatisfiable(keys)) ?? authClientKeyRequirements[0] ?? [];
+    const pending = clientOptions.filter((option) => option.auth && selected.includes(option.clientKey) && !hasExplicitValue(option));
+    for (const option of pending) {
+        // Own-property lookup only: the store is a JSON file, so a key like "constructor"
+        // would otherwise resolve to something off Object.prototype rather than a credential.
+        if (!Object.prototype.hasOwnProperty.call(stored, option.clientKey))
+            continue;
+        const value = stored[option.clientKey];
+        if (typeof value === 'string' && value)
+            forwarded[option.sdkKey] = value;
+    }
+};
+const commandPath = (command) => {
+    const parts = [];
+    for (let current = command; current; current = current.parent)
+        parts.unshift(current.name());
+    return parts.join(' ');
+};
+const rootCommand = (command) => {
+    let root = command;
+    while (root.parent)
+        root = root.parent;
+    return root;
+};
+const sdkMethod = (client, definition) => {
+    let target = client;
+    for (const resource of definition.resourcePath) {
+        target = target[resource];
+    }
+    const method = target[definition.methodName];
+    if (typeof method !== 'function') {
+        throw new Error('Generated CLI could not find SDK method ' +
+            [...definition.resourcePath, definition.methodName].join('.'));
+    }
+    return method.bind(target);
+};
+const callArguments = async (definition, options, positionalValues) => {
+    const positionalParams = {};
+    definition.positional.forEach((param, index) => {
+        // `optionKey` is only this positional's when it was given a flag spelling. Without one the key
+        // belongs to whatever took the name — a `--environment` selector, say — and reading it would
+        // fill the path param with that flag's value and satisfy the required-argument check below.
+        const value = positionalValues[index] ?? (param.flagName === undefined ? undefined : options[param.optionKey]);
+        if (value !== undefined)
+            positionalParams[param.paramKey] = coerceValue(value, param.valueKind, undefined, param.name);
+    });
+    const flagParams = {};
+    for (const flag of definition.flags) {
+        if (flag.objectPath)
+            continue;
+        const value = options[flag.optionKey];
+        if (value !== undefined)
+            flagParams[flag.paramKey] = coerceValue(value, flag.valueKind, flag.itemKind, '--' + flag.name);
+    }
+    // Dotted leaf flags (e.g. `--address.city`) are applied after the JSON-blob flag for the same
+    // param so an explicit leaf value always overrides the corresponding blob field.
+    for (const flag of definition.flags) {
+        if (!flag.objectPath || flag.objectPath.length === 0)
+            continue;
+        const value = options[flag.optionKey];
+        if (value === undefined)
+            continue;
+        flagParams[flag.paramKey] = setNestedValue(flagParams[flag.paramKey], flag.objectPath, coerceValue(value, flag.valueKind, flag.itemKind, '--' + flag.name));
+    }
+    const stdin = await readStdinValue();
+    const params = mergeObjects(stdin, { ...flagParams, ...positionalParams });
+    const positionalArgs = definition.positional.map((param) => params[param.paramKey]);
+    // A positional path param is handed to the SDK method as a leading argument, and the method
+    // never destructures it back out of `params` — only the path params it did *not* take
+    // positionally are pulled out there. Leaving it in `params` makes it fall through the
+    // method's `...query` / `...body` rest and reach the wire a second time, as
+    // `/version/1.0.0?semver=1.0.0` or as a `namespace` field in a body that has no such field.
+    //
+    // Dropping it cannot remove a field the call needs: a positional whose name collides with a
+    // params field is already disambiguated when the command table is built (a body `slug` beside
+    // a path one leaves the positional as `slug2`), so the two never share a key.
+    const omitted = definition.positional.map((param) => param.paramKey);
+    if (definition.transport === 'websocket')
+        omitted.push('send');
+    const sdkParams = omitParams(params, omitted);
+    if (definition.callShape === 'options')
+        return { args: [...positionalArgs, undefined], params };
+    if (definition.callShape === 'body')
+        return { args: [...positionalArgs, bodyValue(sdkParams, definition), undefined], params };
+    return { args: [...positionalArgs, paramsValue(sdkParams, definition), undefined], params };
+};
+const paramsValue = (params, definition) => {
+    if (definition.bodyParamKey === undefined)
+        return params;
+    const body = params[definition.bodyParamKey];
+    if (body === undefined)
+        return params;
+    // Scoped union bodies with headers are typed as the params root. A `--body` JSON blob therefore
+    // needs to sit beside header/query flags, or be passed as the root when it cannot be merged.
+    if (!isPlainObject(body))
+        return body;
+    return mergeObjects(body, omitParams(params, [definition.bodyParamKey]));
+};
+const bodyValue = (params, definition) => {
+    // A non-flattenable body is forwarded as a single value: the SDK method takes that param
+    // directly, so return it bare. Its dotted leaf flags (`--payload.city`) share this key and have
+    // already been merged into the param value, so counting body flags would wrongly treat one
+    // logical body as many and re-wrap it under the param key. `params.body` covers a bare value
+    // piped via stdin.
+    if (definition.bodyParamKey !== undefined) {
+        if (params[definition.bodyParamKey] !== undefined)
+            return params[definition.bodyParamKey];
+        if (params.body !== undefined)
+            return params.body;
+    }
+    // A flattenable body is reassembled from its per-property flags into a single object. Leaf flags
+    // share their parent property key, so keying by paramKey collapses them back onto that property.
+    const bodyFlags = definition.flags.filter((flag) => flag.location === 'body' && flag.paramKey !== 'send');
+    const body = {};
+    for (const flag of bodyFlags) {
+        if (params[flag.paramKey] !== undefined)
+            body[flag.paramKey] = params[flag.paramKey];
+    }
+    return Object.keys(body).length > 0 ? body : params;
+};
+const readStdinValue = async () => {
+    if (processStdin.isTTY)
+        return {};
+    const source = await readStdinSource();
+    if (!source)
+        return {};
+    const parsed = parseStructuredValue(source);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+        return parsed;
+    return { body: parsed };
+};
+const readStdinSource = async () => {
+    const chunks = [];
+    const done = new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            processStdin.off('data', onData);
+            processStdin.off('end', onEnd);
+            processStdin.off('error', onError);
+            processStdin.pause();
+        };
+        const onData = (chunk) => {
+            clearTimeout(timer);
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(Buffer.concat(chunks).toString('utf8').trim());
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve('');
+        }, 25);
+        processStdin.on('data', onData);
+        processStdin.on('end', onEnd);
+        processStdin.on('error', onError);
+    });
+    processStdin.resume();
+    return done;
+};
+// An empty argument is an empty STRING, not YAML's empty document. `--tag ''` asks for one
+// empty tag; parsing it as YAML answers `null`, which the request builder then refuses
+// ("Received null for "tags[]""). Only the empty case is special-cased: `--tag null` still
+// means null, and every other value keeps the JSON-then-YAML reading.
+const parseStructuredValue = (source) => {
+    if (source === '')
+        return source;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return parseYaml(source);
+    }
+};
+const setNestedValue = (target, path, value) => {
+    const root = isPlainObject(target) ? { ...target } : {};
+    let cursor = root;
+    for (const segment of path.slice(0, -1)) {
+        const existing = cursor[segment];
+        const next = isPlainObject(existing) ? { ...existing } : {};
+        cursor[segment] = next;
+        cursor = next;
+    }
+    const leaf = path.at(-1);
+    if (leaf !== undefined)
+        cursor[leaf] = value;
+    return root;
+};
+const isPlainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const mergeObjects = (base, overlay) => ({
+    ...base,
+    ...Object.fromEntries(Object.entries(overlay).filter(([, value]) => value !== undefined)),
+});
+const omitParams = (params, names) => {
+    const out = { ...params };
+    for (const name of names)
+        delete out[name];
+    return out;
+};
+// A file argument is spelled `@path`, the spelling curl and the reference CLIs already use, so a
+// command written against one of those keeps working here. A command line carries a path but never
+// the bytes behind it, and without this the path itself went on the wire as the value.
+const FILE_ARG_PREFIX = '@';
+// `@file://x` sends the bytes as text and `@data://x` sends them base64-encoded; a bare `@x` lets the
+// file decide, which is what a caller who has not thought about encoding means.
+const FILE_ARG_TEXT_SCHEME = 'file://';
+const FILE_ARG_DATA_SCHEME = 'data://';
+// `\@value` is how a value that genuinely begins with `@` (an npm scope, a handle) is spelled.
+const ESCAPED_FILE_ARG_PREFIX = '\\@';
+// The part after `@`, or `undefined` when the value is not a file argument at all.
+const fileArgRest = (value) => value.startsWith(FILE_ARG_PREFIX) ? value.slice(FILE_ARG_PREFIX.length) : undefined;
+// Drops the escape from `\@literal`, which is the only thing a leading backslash means here.
+const unescapeFileArg = (value) => value.startsWith(ESCAPED_FILE_ARG_PREFIX) ? value.slice(1) : value;
+// Resolves one scalar value: a file argument becomes the file's contents, `\@` becomes a literal `@`,
+// and anything else is passed through untouched.
+const flagValue = (value, label) => {
+    const rest = fileArgRest(value);
+    if (rest === undefined) {
+        const unescaped = unescapeFileArg(value);
+        return { text: unescaped, origin: unescaped === value ? 'literal' : 'escaped' };
+    }
+    if (rest.startsWith(FILE_ARG_TEXT_SCHEME)) {
+        return {
+            text: readFileArg(rest.slice(FILE_ARG_TEXT_SCHEME.length), label, true).toString('utf8'),
+            origin: 'file',
+        };
+    }
+    if (rest.startsWith(FILE_ARG_DATA_SCHEME)) {
+        return {
+            text: readFileArg(rest.slice(FILE_ARG_DATA_SCHEME.length), label, true).toString('base64'),
+            origin: 'encoded',
+        };
+    }
+    const bytes = readFileArg(rest, label, false);
+    // Bytes that are not text cannot travel as a JSON string, so they are base64-encoded. A caller who
+    // wants one encoding regardless of what the file holds spells it with `@file://` or `@data://`.
+    return looksBinary(bytes)
+        ? { text: bytes.toString('base64'), origin: 'encoded' }
+        : { text: bytes.toString('utf8'), origin: 'file' };
+};
+// A `file://` or `data://` value is a URL and is percent-decoded as one; a bare `@path` is not a URL
+// and is opened exactly as typed, or a file genuinely named `100%20pct.txt` would be looked up as
+// `100 pct.txt`.
+const readFileArg = (source, label, url) => {
+    const path = url ? fileUrlToPath(source) : source;
+    try {
+        return readFileSync(path);
+    }
+    catch (error) {
+        throw new Error(fileArgFailure(label, path, error));
+    }
+};
+// A missing file names the flag, the path, and the escape, because the likeliest reason `@abe` names
+// nothing on disk is that it was meant as a literal value.
+const fileArgFailure = (label, path, error) => label +
+    ': could not read ' +
+    path +
+    ' (' +
+    (error instanceof Error ? error.message : String(error)) +
+    '). Write \\@ to send a literal value beginning with @.';
+// Bytes are text when they round-trip through UTF-8. A NUL byte is checked separately because it is
+// legal UTF-8, so it round-trips, yet no text field is meant to carry one.
+const looksBinary = (bytes) => bytes.includes(0) || !Buffer.from(bytes.toString('utf8'), 'utf8').equals(bytes);
+// `file://./x` and `file:///abs/x` are both spelled by hand often enough to accept: the first is not
+// a legal file URL, so `new URL()` is not used and the remainder is treated as a path. The slash
+// before a drive letter (`file:///C:/x`) is the Windows spelling of an absolute path and is dropped,
+// since `/C:/x` names nothing.
+const fileUrlToPath = (rest) => {
+    const decoded = decodeFileUrl(rest);
+    return /^\/[A-Za-z]:/u.test(decoded) ? decoded.slice(1) : decoded;
+};
+// Percent-decoding applies only when the value decodes cleanly. A literal `%` in a file name is
+// likelier than a hand-encoded one, and letting `decodeURIComponent` throw would surface a bare
+// "URI error" naming neither the flag nor the path.
+const decodeFileUrl = (rest) => {
+    try {
+        return decodeURIComponent(rest);
+    }
+    catch {
+        return rest;
+    }
+};
+// The path a file-kinded flag names, with or without the `@`. An upload value is a path by
+// definition, so the prefix is optional there and both spellings open the same file.
+const uploadPath = (value) => {
+    const rest = fileArgRest(value);
+    if (rest === undefined)
+        return unescapeFileArg(value);
+    if (rest.startsWith(FILE_ARG_TEXT_SCHEME))
+        return fileUrlToPath(rest.slice(FILE_ARG_TEXT_SCHEME.length));
+    if (rest.startsWith(FILE_ARG_DATA_SCHEME))
+        return fileUrlToPath(rest.slice(FILE_ARG_DATA_SCHEME.length));
+    return rest;
+};
+// `createReadStream` defers a missing file to an asynchronous `error` event, which surfaces as an
+// unhandled rejection rather than a usage error, so the path is checked before the stream is opened.
+const uploadStream = (value, label) => {
+    const path = uploadPath(value);
+    try {
+        accessSync(path, fsConstants.R_OK);
+    }
+    catch (error) {
+        throw new Error(fileArgFailure(label, path, error));
+    }
+    return createReadStream(path);
+};
+// `@` works inside a JSON or YAML blob too (`--metadata '{"notes": "@notes.txt"}'`), so a nested
+// field names a file the same way a flag does. Only a blob typed on the command line is walked; see
+// `FlagValueOrigin` for why a blob read out of a file is not.
+const expandFileArgs = (value, label) => {
+    if (typeof value === 'string')
+        return flagValue(value, label).text;
+    if (Array.isArray(value))
+        return value.map((item) => expandFileArgs(item, label));
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, expandFileArgs(item, label)]));
+    }
+    return value;
+};
+// `itemKind` types one occurrence of a repeatable array flag; a definition without one (an injected
+// field with no item schema) falls back to parsing each occurrence as structured text. `label` names
+// the flag a file-argument failure came from, since a path names no flag on its own.
+// A failing client option cannot name the path it tried to open when the option carries a
+// credential: the likeliest reason `@sk-live-...` names no file is that it *is* the key, and the
+// message reaches stderr and every CI log capturing it.
+const clientOptionValue = (value, option) => {
+    try {
+        return flagValue(value, '--' + option.name).text;
+    }
+    catch (error) {
+        if (!option.auth)
+            throw error;
+        throw new Error('--' +
+            option.name +
+            ': could not read the file it names. Write \\@ to send a literal value beginning with @.');
+    }
+};
+const coerceValue = (value, kind, itemKind, label = 'value') => {
+    if (Array.isArray(value)) {
+        const elementKind = kind === 'array' ? (itemKind ?? 'unknown') : kind;
+        return value.map((item) => coerceValue(item, elementKind, undefined, label));
+    }
+    if (typeof value !== 'string')
+        return value;
+    // A file field takes bytes, and a path is the only thing a command line can carry. The stream is
+    // what the SDK's multipart encoder detects (it is async iterable) and it names the part from the
+    // stream's `path`, so the upload keeps its file name.
+    if (kind === 'file')
+        return uploadStream(value, label);
+    const source = flagValue(value, label);
+    if (kind === 'boolean')
+        return source.text === 'true' || source.text === '1';
+    if (kind === 'number' || kind === 'integer')
+        return Number(source.text);
+    if (kind === 'object' || kind === 'array' || kind === 'unknown') {
+        // Base64 is the value itself, and an escaped literal was declared to be text: parsing
+        // either would read it as YAML, and `@remote` is not even legal YAML.
+        if (source.origin === 'encoded' || source.origin === 'escaped')
+            return source.text;
+        const parsed = parseStructuredValue(source.text);
+        return source.origin === 'literal' ? expandFileArgs(parsed, label) : parsed;
+    }
+    return source.text;
+};
+// Iterator commands print one item at a time so pipes can consume long-running streams immediately.
+// One streamed item, framed so consecutive items stay separable.
+//
+// Every other format self-frames per item: `jsonl` is one record per line, `json` wraps each in
+// braces. A TOON object is several bare `key: value` lines, so two events written back to back
+// would run together with nothing marking the boundary — recoverable only by guessing that a
+// repeated key starts a new record, which fails the moment a field is optional. Encoding the item
+// as a one-element list gives each record its own `[1]` header at column 0, keeps the count
+// marker honest about what follows, and leaves every other format untouched.
+const streamItemText = (value, options) => {
+    if (options.format !== 'toon')
+        return serializeOutput(value, options);
+    if (options.rawOutput && typeof value === 'string')
+        return value;
+    return serializeOutput([value], options);
+};
+const writeIterable = async (value, options) => {
+    if (!isAsyncIterable(value)) {
+        await writeOutput(value, options);
+        return;
+    }
+    if (options.maxItems === 0) {
+        options.onLimit?.();
+        return;
+    }
+    let written = 0;
+    for await (const item of value) {
+        if (options.failOnWebSocketError)
+            throwWebSocketEventError(item);
+        processStdout.write(streamItemText(transformValue(item, options.transform), options) + '\n');
+        if (!countsTowardLimit(item, options))
+            continue;
+        written += 1;
+        if (options.maxItems !== undefined && options.maxItems > -1 && written >= options.maxItems) {
+            options.onLimit?.();
+            break;
+        }
+    }
+};
+// Paginated list commands auto-page across cursors: the SDK PagePromise iterates items across
+// pages. `raw` is the explicit escape hatch for the unmodified single-response envelope, so it
+// stays a single request with no auto-paging. For every other format we hand the page iterator
+// to writeOutput, which already makes the right split: `jsonl` streams each item as it arrives,
+// while `json`/`auto`/`pretty`/`yaml` collect the fully auto-paged items into one value (honoring
+// --max-items either way). Routing through writeIterable here instead would stream items for
+// every format, emitting newline-delimited objects under `--format json` (invalid as a single
+// JSON document) and nothing at all for an empty result.
+const writePaginated = async (result, options) => {
+    if (options.format === 'raw') {
+        const page = await result;
+        const envelope = page && typeof page === 'object' && 'body' in page ? page.body : undefined;
+        await writeOutput(envelope ?? page, options);
+        return;
+    }
+    if (isAsyncIterable(result)) {
+        await writeOutput(result, options);
+        return;
+    }
+    await writeOutput(await result, options);
+};
+const countsTowardLimit = (item, options) => {
+    if (!options.failOnWebSocketError)
+        return true;
+    if (!item || typeof item !== 'object')
+        return false;
+    const type = item.type;
+    return type === 'message' || type === 'raw';
+};
+// WebSocket SDKs expose lifecycle events as iterator values; error events should fail CLI commands.
+const handleWebSocket = async (socket, params, options) => {
+    const closer = () => {
+        closeSocket(socket, 'interrupted');
+    };
+    process.once('SIGINT', closer);
+    try {
+        const output = writeIterable(socket, {
+            ...options,
+            failOnWebSocketError: true,
+            onLimit: () => closeSocket(socket, 'max-items reached'),
+        });
+        await Promise.resolve();
+        const sendValue = params.send;
+        if (sendValue !== undefined)
+            sendSocketValue(socket, sendValue);
+        if (!processStdin.isTTY) {
+            const stdin = await readStdinValue();
+            if (Object.keys(stdin).length > 0)
+                sendSocketValue(socket, stdin.body ?? stdin);
+        }
+        await output;
+    }
+    finally {
+        process.off('SIGINT', closer);
+    }
+};
+const closeSocket = (socket, reason) => {
+    const close = socket.close;
+    if (typeof close === 'function')
+        close.call(socket, { code: 1000, reason });
+};
+const sendSocketValue = (socket, value) => {
+    const send = socket.send;
+    if (typeof send !== 'function')
+        throw new Error('Generated CLI could not send on SDK WebSocket client');
+    if (Array.isArray(value)) {
+        for (const item of value)
+            send.call(socket, item);
+        return;
+    }
+    send.call(socket, value);
+};
+export const writeOutput = async (value, options) => {
+    if (isAsyncIterable(value)) {
+        if (options.format === 'jsonl') {
+            await writeIterable(value, options);
+            return;
+        }
+        await writeOutput(await collectIterable(value, options.maxItems), options);
+        return;
+    }
+    processStdout.write(serializeOutput(transformValue(value, options.transform), options) + '\n');
+};
+const collectIterable = async (value, maxItems) => {
+    const items = [];
+    for await (const item of value) {
+        if (maxItems === 0)
+            break;
+        items.push(item);
+        if (maxItems !== undefined && maxItems > -1 && items.length >= maxItems)
+            break;
+    }
+    return items;
+};
+// `auto` renders like `json` (2-space pretty-printed): `pretty` is reserved for the distinct
+// human-readable card view, matching common CLI defaults.
+const serializeOutput = (value, options) => {
+    const normalized = options.format === 'auto' ? 'json' : options.format;
+    if (options.rawOutput && typeof value === 'string')
+        return value;
+    const safeValue = value === undefined ? null : value;
+    if (normalized === 'raw')
+        return typeof safeValue === 'string' ? safeValue : JSON.stringify(safeValue);
+    if (normalized === 'yaml')
+        return stringifyYaml(JSON.parse(JSON.stringify(safeValue))).trimEnd();
+    if (normalized === 'jsonl')
+        return JSON.stringify(safeValue);
+    if (normalized === 'pretty')
+        return prettyCard(safeValue, options);
+    // TOON keeps the JSON data model but drops repeated syntax, so a list response costs an agent
+    // markedly fewer context tokens than the same data as JSON.
+    if (normalized === 'toon')
+        return encodeToon(JSON.parse(JSON.stringify(safeValue)));
+    return JSON.stringify(safeValue, null, 2);
+};
+// Human-readable `pretty` view: a bordered key/value card titled with the command path,
+// rendering booleans as yes/no and array entries as numbered items.
+const prettyCard = (value, options) => {
+    const lines = prettyLines(value, '');
+    const width = Math.max(0, ...lines.map((line) => line.length));
+    const body = lines.length > 0 ? lines : [''];
+    return [
+        ...(options.title ? ['  ' + options.title] : []),
+        '\u256d' + '\u2500'.repeat(width + 2) + '\u256e',
+        ...body.map((line) => '\u2502 ' + line.padEnd(width, ' ') + ' \u2502'),
+        '\u2570' + '\u2500'.repeat(width + 2) + '\u256f',
+    ].join('\n');
+};
+const prettyLines = (value, indent) => {
+    if (Array.isArray(value)) {
+        return value.flatMap((item, index) => {
+            const label = indent + (index + 1) + '.';
+            if (item && typeof item === 'object')
+                return [label, ...prettyLines(item, indent + '  ')];
+            return [label + ' ' + prettyScalar(item)];
+        });
+    }
+    if (value && typeof value === 'object') {
+        return Object.entries(value).flatMap(([key, entry]) => {
+            if (entry && typeof entry === 'object')
+                return [indent + key + ':', ...prettyLines(entry, indent + '  ')];
+            return [indent + key + ': ' + prettyScalar(entry)];
+        });
+    }
+    return [indent + prettyScalar(value)];
+};
+const prettyScalar = (value) => {
+    if (value === true)
+        return 'yes';
+    if (value === false)
+        return 'no';
+    if (value === null || value === undefined)
+        return '';
+    return String(value);
+};
+export const writeError = async (error, options, clientOptions, SDK, environment = undefined) => {
+    const body = transformValue(errorBody(error, clientOptions, SDK, environment), options.transform);
+    if (options.rawOutput && typeof body === 'string') {
+        process.stderr.write(body + '\n');
+        return;
+    }
+    if (options.format === 'raw') {
+        // The hint is appended rather than dropped: before failures were classified, the auth hint
+        // *was* the message, so printing the message alone would lose advice `raw` used to show.
+        const hint = errorHintText(body);
+        process.stderr.write(String(errorMessage(body)) + (hint ? ' ' + hint : '') + '\n');
+        return;
+    }
+    const output = options.format === 'auto' ? 'pretty' : options.format;
+    const safeBody = body === undefined ? null : body;
+    const serialized = serializeErrorBody(safeBody, output);
+    process.stderr.write((output === 'pretty' ? as.red(serialized) : serialized) + '\n');
+};
+const serializeErrorBody = (body, format) => {
+    if (format === 'yaml')
+        return stringifyYaml(body).trimEnd();
+    if (format === 'toon')
+        return encodeToon(JSON.parse(JSON.stringify(body)));
+    return JSON.stringify(body, null, format === 'jsonl' ? 0 : 2);
+};
+const errorMessage = (value) => value && typeof value === 'object' && 'message' in value ? value.message : value;
+/** The `hint` on an error body, when the body is one and carries a non-empty hint. */
+const errorHintText = (value) => {
+    if (!value || typeof value !== 'object')
+        return '';
+    const hint = value.hint;
+    return typeof hint === 'string' ? hint : '';
+};
+const errorBody = (error, clientOptions, SDK, environment) => {
+    if (error && typeof error === 'object') {
+        const record = error;
+        const hint = errorHint(record, clientOptions, environment);
+        return {
+            name: record.name,
+            // Stable class identifier so a caller can branch on the kind of failure without parsing prose.
+            code: errorCode(record, SDK),
+            // The upstream message is passed through untouched; advice goes in `hint` beside it, so a
+            // caller logging the message never loses what the API actually said.
+            message: record.message ?? String(error),
+            status: record.status,
+            requestId: record.requestID ?? record.requestId,
+            ...(hint !== undefined ? { hint } : {}),
+            body: record.body ?? record.error,
+        };
+    }
+    return { code: 'error', message: String(error) };
+};
+// Stable error class for the failure, derived from the HTTP status, or from the SDK error class
+// for transport failures that never reached a response. Drives both the `code` field and the
+// process exit status.
+const errorCode = (record, SDK) => {
+    const status = typeof record.status === 'number' ? record.status : undefined;
+    if (status === 401 || status === 403)
+        return 'auth-failed';
+    if (status === 404)
+        return 'not-found';
+    if (status === 429)
+        return 'rate-limited';
+    if (status !== undefined && status >= 400 && status < 500)
+        return 'client-error';
+    if (status !== undefined && status >= 500)
+        return 'server-error';
+    if (isConnectionError(record, SDK))
+        return 'connection-error';
+    return 'error';
+};
+// Identifies a transport failure — one that never reached a response, so there is no status to
+// classify it by.
+//
+// Matched by identity against the error class the SDK exposes as a static, never by class name:
+// release binaries are built with `bun build --compile --minify`, which renames classes, so
+// `constructor.name` there is a mangled single letter and `.name` is the inherited "Error". The
+// name check stays only as a fallback for a host object that is not an SDK error at all (an
+// undici `ConnectTimeoutError` surfacing through a custom fetch, say).
+// Transport failure codes Node and undici set on the error, none of which are CamelCase.
+const CONNECTION_ERROR_CODE = /^(ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|EPIPE|UND_ERR)/u;
+const isConnectionError = (record, SDK) => {
+    const connectionError = SDK.APIConnectionError;
+    if (typeof connectionError === 'function' &&
+        record instanceof connectionError)
+        return true;
+    const name = typeof record.name === 'string' ? record.name : '';
+    const code = typeof record.code === 'string' ? record.code : '';
+    // Class names are CamelCase (`ConnectTimeoutError`) but Node/undici transport codes are
+    // SCREAMING_SNAKE_CASE (`ECONNREFUSED`, `UND_ERR_CONNECT_TIMEOUT`), so the two need different
+    // tests: a substring match on the code would never fire, leaving a host that cannot be reached
+    // through a custom fetch falling through to the unclassified status.
+    if (name.includes('Connection') || name.includes('Timeout'))
+        return true;
+    return CONNECTION_ERROR_CODE.test(code);
+};
+// One exit status per error class so a caller can decide what to do next — fix credentials, back
+// off, retry, give up — from the status alone.
+const ERROR_EXIT_CODES = {
+    error: 1,
+    'auth-failed': 10,
+    'not-found': 11,
+    'rate-limited': 12,
+    'client-error': 13,
+    'server-error': 14,
+    'connection-error': 15,
+};
+export const errorExitCode = (error, SDK) => {
+    if (!error || typeof error !== 'object')
+        return 1;
+    return ERROR_EXIT_CODES[errorCode(error, SDK)] ?? 1;
+};
+// Actionable next step for the classes where one exists, surfaced beside the upstream message.
+const errorHint = (error, clientOptions, environment) => {
+    const status = error.status;
+    if (status === 401)
+        return authHint(clientOptions, environment);
+    // 403 is a permission failure, not a credential one: the request authenticated fine, so
+    // telling the caller to set the auth env var would send it round the same loop again.
+    if (status === 403)
+        return 'Access denied. The credential is valid but lacks permission for this resource.';
+    if (status === 404)
+        return 'Resource not found. Check the identifier and path arguments.';
+    if (status === 429)
+        return 'Rate limited. Wait and retry, or reduce request frequency.';
+    return undefined;
+};
+// Undefined when the SDK declares no authentication: there would be no variable to name, and a
+// generic "set the required environment variable" would point at something that does not exist.
+const authHint = (clientOptions, environment) => {
+    const authOptions = clientOptions.filter((option) => option.auth);
+    if (authOptions.length === 0)
+        return undefined;
+    const env = authOptions
+        .map((option) => option.env)
+        .filter((value) => !!value)
+        .join(', ');
+    return ('Authentication failed. Run `' +
+        loginCommandFor(environment) +
+        '`' +
+        (env ? ', or set ' + env : '') +
+        ', and try again.');
+};
+// Keep transforms small and dependency-free; the CLI supports the common dot-path extraction case.
+const transformValue = (value, transform) => {
+    if (!transform)
+        return value;
+    return transform
+        .split('.')
+        .filter(Boolean)
+        .reduce((current, segment) => {
+        if (current === undefined || current === null)
+            return undefined;
+        if (Array.isArray(current) && /^\\d+$/u.test(segment))
+            return current[Number(segment)];
+        if (typeof current === 'object')
+            return current[segment];
+        return undefined;
+    }, value);
+};
+const throwWebSocketEventError = (value) => {
+    if (!value || typeof value !== 'object')
+        return;
+    const record = value;
+    if (record.type !== 'error')
+        return;
+    const error = record.error;
+    if (error instanceof Error)
+        throw error;
+    throw new Error(typeof error === 'string' ? error : JSON.stringify(error ?? record));
+};
+const normalizeFormat = (value, fallback) => {
+    if (value === 'auto' ||
+        value === 'json' ||
+        value === 'jsonl' ||
+        value === 'pretty' ||
+        value === 'raw' ||
+        value === 'toon' ||
+        value === 'yaml') {
+        return value;
+    }
+    return fallback;
+};
+const normalizeMaxItems = (value) => {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    return Math.trunc(parsed);
+};
+const isAsyncIterable = (value) => !!value && typeof value[Symbol.asyncIterator] === 'function';
+// Custom commands share generated credential, output, and error conventions.
+export { normalizeFormat, usageExitCode };
+//# sourceMappingURL=runtime.js.map