@standchat/cli 0.0.0-stage → 0.1.1

package/dist/export-validation.js

@@ -0,0 +1,164 @@
+import { createReadStream } from 'node:fs';
+import { Transform, Writable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { parser } from 'stream-json/parser.js';
+import { CliError } from './errors.js';
+const ROOT_TYPES = new Map([
+    ['exportedAt', 'startString'], ['filters', 'startObject'],
+    ['conversations', 'startArray'], ['totalElements', 'startNumber'],
+    ['exportedElements', 'startNumber'], ['exportLimit', 'startNumber'],
+    ['failedSessionIds', 'startArray'],
+]);
+const VALUE_STARTS = new Set(['startObject', 'startArray', 'startString', 'startNumber', 'nullValue', 'trueValue', 'falseValue']);
+const COUNT_FIELDS = new Set(['totalElements', 'exportedElements', 'exportLimit']);
+const invalid = () => new CliError('EXPORT_INVALID', 'Export is not a complete valid history document. No file was published.', 5);
+/** Validate syntax with stream-json; retain only bounded top-level metadata.
+ * Never assemble a conversation, string value, failed-ID list, or full file.
+ */
+export async function validateHistoryExport(path, signal) {
+    let depth = 0;
+    let started = false;
+    let ended = false;
+    let collectingKey = false;
+    let key = '';
+    let field = '';
+    let expectsValue = false;
+    let number = '';
+    let countingNumber = false;
+    let conversations = 0;
+    let failed = 0;
+    const seen = new Set();
+    const counts = new Map();
+    function consume(token) {
+        const name = token.name;
+        if (!started) {
+            if (name !== 'startObject')
+                throw invalid();
+            started = true;
+            depth = 1;
+            return;
+        }
+        if (ended)
+            throw invalid();
+        if (depth === 1 && name === 'startKey') {
+            collectingKey = true;
+            key = '';
+            return;
+        }
+        if (collectingKey) {
+            if (name === 'stringChunk') {
+                key += token.value;
+                // Only the small documented top-level field names are retained.
+                if (key.length > 128)
+                    throw invalid();
+            }
+            else if (name === 'endKey') {
+                collectingKey = false;
+                field = key;
+                expectsValue = true;
+                if (ROOT_TYPES.has(field)) {
+                    if (seen.has(field))
+                        throw invalid();
+                    seen.add(field);
+                }
+            }
+            return;
+        }
+        if (depth === 1 && expectsValue && VALUE_STARTS.has(name)) {
+            const expected = ROOT_TYPES.get(field);
+            if (expected && name !== expected)
+                throw invalid();
+            expectsValue = false;
+            if (COUNT_FIELDS.has(field)) {
+                countingNumber = true;
+                number = '';
+            }
+        }
+        if (countingNumber) {
+            if (name === 'numberChunk') {
+                number += token.value;
+                if (number.length > 64)
+                    throw invalid();
+            }
+            else if (name === 'endNumber') {
+                const value = Number(number);
+                if (!Number.isSafeInteger(value) || value < 0)
+                    throw invalid();
+                counts.set(field, value);
+                countingNumber = false;
+            }
+        }
+        // Count only direct array elements. Arbitrary nested conversation data is
+        // consumed as tokens and is never buffered by this validation layer.
+        if (depth === 2 && VALUE_STARTS.has(name)) {
+            if (field === 'conversations') {
+                if (name !== 'startObject')
+                    throw invalid();
+                conversations++;
+            }
+            else if (field === 'failedSessionIds') {
+                if (name !== 'startString')
+                    throw invalid();
+                failed++;
+            }
+        }
+        if (name === 'startObject' || name === 'startArray') {
+            if (++depth > 128)
+                throw invalid();
+        }
+        else if (name === 'endObject' || name === 'endArray') {
+            depth--;
+            if (depth === 0)
+                ended = true;
+        }
+    }
+    // Node's normal string decoder replaces malformed UTF-8. Validate it with
+    // the built-in fatal decoder before handing the original bytes to the parser.
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    const utf8 = new Transform({
+        transform(chunk, _encoding, callback) {
+            try {
+                decoder.decode(chunk, { stream: true });
+                callback(null, chunk);
+            }
+            catch {
+                callback(invalid());
+            }
+        },
+        flush(callback) { try {
+            decoder.decode();
+            callback();
+        }
+        catch {
+            callback(invalid());
+        } },
+    });
+    const sink = new Writable({ objectMode: true, write(token, _encoding, callback) {
+            try {
+                consume(token);
+                callback();
+            }
+            catch (error) {
+                callback(error);
+            }
+        } });
+    try {
+        await pipeline(createReadStream(path, { highWaterMark: 64 * 1024 }), utf8, parser.asStream({ packValues: false }), sink, { signal });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw new CliError('CANCELLED', 'Export cancelled. No file was published.', 130);
+        if (error instanceof CliError)
+            throw error;
+        // Parser diagnostics can contain customer content; never surface them.
+        throw invalid();
+    }
+    if (!ended || depth !== 0 || [...ROOT_TYPES.keys()].some(name => !seen.has(name)))
+        throw invalid();
+    const total = counts.get('totalElements');
+    const exported = counts.get('exportedElements');
+    if (failed !== 0 || conversations !== exported || total !== exported || counts.get('exportLimit') !== total) {
+        throw new CliError('EXPORT_INCOMPLETE', `Export incomplete: ${conversations} conversations received, ${exported} reported exported, ${total} expected, ${failed} failed. No file was published.`, 1);
+    }
+    return { complete: true, totalElements: total, exportedElements: exported, failedElements: 0 };
+}

package/dist/index.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { CLI_VERSION } from './version.js';
+import { AuthSession, ALLOWED_SCOPES, DEFAULT_SCOPES, SETUP_SCOPES, deviceLogin, scopesForLogin } from './auth.js';
+import { ConfigStore, CredentialVault, profileName } from './config.js';
+import { COMMANDS, executeCommand, findCommand, integerFlag, readInput, readSchema, requestBody, stringFlag } from './commands.js';
+import { CliError, isObject, terminalJson, terminalText, usage } from './errors.js';
+import { multipartBody } from './multipart.js';
+import { publicOperation } from './contract.js';
+import { setupStatus } from './setup.js';
+import { ApiClient, apiUrl, safeUrl, sleep } from './transport.js';
+const GLOBAL_OPTIONS = ['profile', 'json', 'no-input', 'yes', 'help', 'timeout', 'retries'];
+const STRING_OPTIONS = ['profile', 'timeout', 'retries', 'api-url', 'issuer', 'scopes', 'credential-store', 'body-file', 'domain', 'name', 'enabled', 'language', 'query', 'page', 'size', 'type', 'scope', 'site', 'contact', 'label', 'closed-from', 'closed-to', 'sort-by', 'sort-dir', 'max-pages', 'interval', 'count', 'email', 'output', 'max-bytes', 'app-url'];
+const BOOLEAN_OPTIONS = ['json', 'no-input', 'yes', 'help', 'all', 'watch', 'token-stdin', 'local-only', 'check', 'version', 'setup'];
+const HELP = `Stand Chat CLI (beta)\n\nUsage: stand <resource> <command> [arguments] [options]\n\n` +
+    COMMANDS.map(command => `  ${`${command.command}${command.args.map(arg => ` <${arg}>`).join(' ')}`.padEnd(34)} ${command.description}`).join('\n') +
+    `\n\n  auth login                        Sign in using a browser and device code; read-only scopes by default.\n` +
+    `  auth login --setup                Request site, Stand-in and knowledge setup permissions together; onboarding stays in the browser.\n` +
+    `  auth import --token-stdin          Import a token from stdin for this API profile.\n` +
+    `  auth status [--check]              Show credential metadata; --check verifies API access.\n` +
+    `  auth logout [--local-only]         Revoke the refresh token and remove the local credential.\n` +
+    `  config set --api-url URL --issuer URL\n` +
+    `  config list                       List API profiles (never credentials).\n` +
+    `  api METHOD /v1/path                Send a request to the configured API.\n` +
+    `  schema [operationId]              Print the bundled OpenAPI contract or one operation.\n` +
+    `  commands                          Print machine-readable command metadata.\n` +
+    `  setup status [--app-url URL]       Check browser onboarding readiness without changing your account.\n\n` +
+    `Global options: --profile NAME, --json, --no-input, --yes, --timeout SECONDS, --retries 0..3\n` +
+    `Timeout: 30 seconds by default (maximum 120); history export uses 600 seconds (maximum 3600), including validation.\n` +
+    `Input: --body-file FILE or --body-file - reads JSON; --form-string name=value and --form-file name=PATH send published multipart fields. No token argument is accepted.\n` +
+    `Automation: output is JSON when stdout is not a terminal; diagnostics/errors go to stderr.\n` +
+    `Safety: write confirmations require --yes without a TTY. Writes are never automatically retried.\n` +
+    `See stand commands --json for flags, required scopes, and confirmation requirements.\n`;
+function checkOptions(flags, allowed) {
+    const unknown = Object.keys(flags).find(key => !GLOBAL_OPTIONS.includes(key) && !allowed.includes(key));
+    if (unknown)
+        usage(`--${unknown} is not supported by this command.`);
+}
+function output(value, json) {
+    if (json) {
+        process.stdout.write(`${terminalJson(value)}\n`);
+        return;
+    }
+    const rows = Array.isArray(value) ? value
+        : isObject(value) && Array.isArray(value.sites) ? value.sites
+            : isObject(value) && Array.isArray(value.sessions) ? value.sessions
+                : undefined;
+    if (rows && rows.every(row => isObject(row))) {
+        if (!rows.length) {
+            process.stdout.write('No results.\n');
+            return;
+        }
+        const preferred = ['siteId', 'sessionId', 'domain', 'name', 'enabled', 'status', 'createdAt', 'closedAt', 'messageCount'];
+        const columns = preferred.filter(key => rows.some(row => isObject(row) && row[key] !== undefined)).slice(0, 6);
+        if (columns.length) {
+            const cells = rows.map(row => columns.map(column => terminalText(String(row[column] ?? '')).slice(0, 70)));
+            const widths = columns.map((column, index) => Math.max(column.length, ...cells.map(row => row[index].length)));
+            process.stdout.write(`${columns.map((column, i) => column.padEnd(widths[i])).join('  ')}\n`);
+            for (const row of cells)
+                process.stdout.write(`${row.map((cell, i) => cell.padEnd(widths[i])).join('  ')}\n`);
+            if (isObject(value) && value.complete === false)
+                process.stderr.write('More pages are available; continue with --page nextPage or increase --max-pages.\n');
+            return;
+        }
+    }
+    // Escape C1 and bidi controls as well as JSON control characters in nested content.
+    process.stdout.write(`${terminalJson(value, true)}\n`);
+}
+const LEGACY_EMBED_WARNING = 'Legacy embedOptions merges option keys but replaces all behavior rules and custom JavaScript and resets advancedBehaviorEnabled and allowStandAdminBehavior to false, even for {}. A valid behaviorConfig in the same request is applied afterward, subject to current owner consent. Review the complete replacement before continuing.';
+function legacyEmbedWarning(body) {
+    return body && isObject(body.embedOptions) ? LEGACY_EMBED_WARNING : undefined;
+}
+async function confirm(label, flags, signal, warning) {
+    if (flags.yes) {
+        if (warning)
+            process.stderr.write(Boolean(flags.json) || !process.stdout.isTTY
+                ? `${JSON.stringify({ warning: { code: 'LEGACY_EMBED_OPTIONS_CONVERSION', message: warning } })}\n`
+                : `Warning: ${warning}\n`);
+        return;
+    }
+    if (warning)
+        label = `${label}. ${warning}`;
+    if (flags['no-input'] || !process.stdin.isTTY || !process.stderr.isTTY || flags['body-file'] === '-') {
+        throw new CliError('CONFIRMATION_REQUIRED', `${label} requires --yes. No request was sent.`, 2);
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stderr });
+    const cancellation = new AbortController();
+    const cancel = () => cancellation.abort();
+    prompt.on('SIGINT', cancel);
+    prompt.on('close', cancel);
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted)
+        cancel();
+    try {
+        const answer = await prompt.question(`${terminalText(label)}? Type yes to continue: `, { signal: cancellation.signal });
+        if (answer !== 'yes')
+            throw new CliError('CANCELLED', 'Operation cancelled. No request was sent.', 130);
+    }
+    catch (error) {
+        if (cancellation.signal.aborted)
+            throw new CliError('CANCELLED', 'Operation cancelled. No request was sent.', 130);
+        throw error;
+    }
+    finally {
+        signal?.removeEventListener('abort', cancel);
+        prompt.removeListener('SIGINT', cancel);
+        prompt.removeListener('close', cancel);
+        prompt.close();
+    }
+}
+function storeFlag(flags) {
+    const value = stringFlag(flags, 'credential-store');
+    if (value !== undefined && value !== 'file' && value !== 'keychain')
+        usage('--credential-store must be keychain or file.');
+    return value;
+}
+export async function main(args = process.argv.slice(2), env = process.env, signal) {
+    let positionals;
+    let flags;
+    try {
+        const parsed = parseArgs({ args, allowPositionals: true, strict: true, options: {
+                ...Object.fromEntries(STRING_OPTIONS.map(key => [key, { type: 'string' }])),
+                ...Object.fromEntries(BOOLEAN_OPTIONS.map(key => [key, { type: 'boolean' }])),
+                'query-param': { type: 'string', multiple: true },
+                'form-string': { type: 'string', multiple: true },
+                'form-file': { type: 'string', multiple: true },
+            } });
+        positionals = parsed.positionals;
+        flags = parsed.values;
+    }
+    catch {
+        return usage('Unknown option or missing option value. Run stand --help. Token arguments are never accepted.');
+    }
+    const json = Boolean(flags.json) || !process.stdout.isTTY;
+    if (flags.version) {
+        output({ name: '@standchat/cli', version: CLI_VERSION, apiVersion: 'v1' }, json);
+        return;
+    }
+    if (flags.help || positionals[0] === 'help' || positionals.length === 0) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (positionals[0] === 'commands') {
+        checkOptions(flags, []);
+        if (positionals.length !== 1)
+            usage('Usage: stand commands.');
+        output({ version: 1, commands: COMMANDS, authCommands: [
+                { command: 'auth login', options: ['scopes', 'setup', 'credential-store'], browserApproval: true, progressEvent: 'device_authorization' },
+                { command: 'auth import', options: ['token-stdin', 'credential-store'] },
+                { command: 'auth status', options: ['check'] },
+                { command: 'auth logout', options: ['local-only'] },
+            ], apiCommand: { command: 'api METHOD /v1/path', options: ['body-file', 'query-param', 'form-string', 'form-file'], requestFormats: ['application/json', 'multipart/form-data'], multipartFieldsFrom: 'stand schema OPERATION_ID', writesRequireConfirmation: true }, globalOptions: GLOBAL_OPTIONS, loginScopes: { default: DEFAULT_SCOPES, setup: SETUP_SCOPES, supported: ALLOWED_SCOPES },
+            setupCommand: { command: 'setup status', options: ['app-url'], scopes: ['profile:read', 'org:read'], writes: false },
+            exits: { success: 0, api: 1, usage: 2, notFound: 3, authenticationOrPermission: 4, network: 5, cancelled: 130 } }, true);
+        return;
+    }
+    if (positionals[0] === 'schema') {
+        checkOptions(flags, []);
+        if (positionals.length > 2)
+            usage('Usage: stand schema [operationId].');
+        output(await readSchema(positionals[1]), true);
+        return;
+    }
+    const name = profileName(stringFlag(flags, 'profile') ?? env.STAND_PROFILE ?? 'default');
+    const config = new ConfigStore(env.STAND_CONFIG_HOME);
+    if (positionals[0] === 'config') {
+        if (positionals[1] === 'list' && positionals.length === 2) {
+            checkOptions(flags, []);
+            const saved = await config.read();
+            output({ selectedProfile: name, profiles: saved.profiles, defaults: { apiUrl: 'https://api.stand.chat', issuer: 'https://auth.stand.chat/realms/stand' } }, json);
+            return;
+        }
+        if (positionals[1] !== 'set' || positionals.length !== 2)
+            usage('Usage: stand config set --profile NAME --api-url URL --issuer URL.');
+        checkOptions(flags, ['api-url', 'issuer', 'credential-store']);
+        const profile = await config.update(name, current => {
+            const api = stringFlag(flags, 'api-url') ?? current?.apiUrl;
+            const issuer = stringFlag(flags, 'issuer') ?? current?.issuer;
+            if (!api || !issuer)
+                usage('New profiles require --api-url and --issuer.');
+            return { apiUrl: safeUrl(api).origin, issuer: safeUrl(issuer, 'issuer').href.replace(/\/$/, ''), credentialStore: storeFlag(flags) ?? current?.credentialStore };
+        }, signal);
+        output({ profile: name, ...profile }, json);
+        return;
+    }
+    // Capture saved endpoints once. A runtime override changes this invocation,
+    // while a later credential-store publication must preserve the saved target.
+    const savedProfile = await config.profile(name, {});
+    const profile = { ...savedProfile,
+        apiUrl: safeUrl(env.STAND_API_URL ?? savedProfile.apiUrl).origin,
+        issuer: safeUrl(env.STAND_ISSUER ?? savedProfile.issuer, 'issuer').href.replace(/\/$/, ''),
+    };
+    const publishCredentialStore = () => config.update(name, current => {
+        const latest = current ?? savedProfile;
+        if (latest.apiUrl !== savedProfile.apiUrl || latest.issuer !== savedProfile.issuer
+            || (latest.credentialStore !== savedProfile.credentialStore && latest.credentialStore !== profile.credentialStore)) {
+            throw new CliError('CONFIG_CHANGED', 'Credentials were saved for the selected connection, but its saved profile changed during sign-in/import. The newer configuration was preserved. Run stand config list, then sign in or import again for the intended connection. Logout still includes the saved credential location.', 4);
+        }
+        return { ...latest, credentialStore: profile.credentialStore };
+    }, signal);
+    if (positionals[0] === 'auth' && ['login', 'import'].includes(positionals[1]))
+        profile.credentialStore = storeFlag(flags) ?? profile.credentialStore;
+    const vault = new CredentialVault(config.root, name, profile);
+    const auth = new AuthSession(profile, vault, env, signal);
+    const client = new ApiClient(profile.apiUrl, () => auth.accessToken(), scope => auth.loginHint(scope));
+    const exporting = positionals[0] === 'history' && positionals[1] === 'export';
+    const options = { timeoutMs: integerFlag(flags, 'timeout', exporting ? 600 : 30, 1, exporting ? 3600 : 120) * 1000, retries: integerFlag(flags, 'retries', 2, 0, 3), signal };
+    if (positionals[0] === 'auth') {
+        if (positionals.length !== 2)
+            usage('Usage: stand auth login|import|status|logout.');
+        switch (positionals[1]) {
+            case 'login': {
+                checkOptions(flags, ['scopes', 'setup', 'credential-store']);
+                if (flags.setup && flags.scopes !== undefined)
+                    usage('--setup and --scopes are mutually exclusive. Choose the setup preset or an explicit permission list.');
+                if (flags['no-input'])
+                    usage('Device login requires browser interaction. First run stand auth login interactively and approve it in the browser; later commands can use that saved session without input.');
+                await vault.preflight();
+                const explicitScopes = flags.setup ? SETUP_SCOPES.join(' ') : stringFlag(flags, 'scopes');
+                const saved = await deviceLogin(profile, await scopesForLogin(vault, explicitScopes), {
+                    display: info => process.stderr.write(json
+                        ? `${JSON.stringify({ event: 'device_authorization', ...info })}\n`
+                        : `Open ${info.verificationUri}\nEnter code: ${info.userCode}\nWaiting for approval (expires in ${info.expiresIn} seconds). Press Ctrl-C to cancel.\n`),
+                }, signal);
+                await vault.locked(() => vault.save(saved), signal);
+                // Environment URL overrides apply to this invocation, never to saved endpoints.
+                await publishCredentialStore();
+                output({ profile: name, apiUrl: profile.apiUrl, credentialStored: true, expiresAt: new Date(saved.expiresAt).toISOString(), scopes: saved.scopes }, json);
+                return;
+            }
+            case 'import': {
+                checkOptions(flags, ['token-stdin', 'credential-store']);
+                if (!flags['token-stdin'] || process.stdin.isTTY)
+                    usage('Import requires --token-stdin and a pipe. No token argument or echoed terminal input is accepted.');
+                const token = (await readInput(process.stdin, 64 * 1024, signal)).trim();
+                if (!token || /\s/.test(token))
+                    usage('stdin must contain one nonempty access token.');
+                await vault.locked(() => vault.save({ version: 1, apiUrl: profile.apiUrl, issuer: profile.issuer, clientId: 'stand-cli', accessToken: token }), signal);
+                // Environment URL overrides apply to this invocation, never to saved endpoints.
+                await publishCredentialStore();
+                output({ profile: name, apiUrl: profile.apiUrl, credentialStored: true, source: 'import', verified: false }, json);
+                return;
+            }
+            case 'status': {
+                checkOptions(flags, ['check']);
+                const provided = auth.environmentToken();
+                const verified = flags.check ? await client.request('/v1/reps/me', options) : undefined;
+                const saved = provided ? undefined : await vault.load();
+                if (signal?.aborted)
+                    throw new CliError('CANCELLED', 'Operation cancelled.', 130);
+                output({ profile: name, apiUrl: profile.apiUrl, issuer: profile.issuer, credentialPresent: Boolean(provided || saved),
+                    source: provided ? 'environment' : profile.credentialStore ?? 'keychain',
+                    expiresAt: saved?.expiresAt === undefined ? null : new Date(saved.expiresAt).toISOString(),
+                    scopes: saved?.scopes ?? null, verified: Boolean(flags.check), ...(verified === undefined ? {} : { user: verified }) }, json);
+                return;
+            }
+            case 'logout':
+                checkOptions(flags, ['local-only']);
+                output({ profile: name, ...await auth.logout(Boolean(flags['local-only'])), environmentTokenRemoved: false }, json);
+                return;
+            default: return usage('Usage: stand auth login|import|status|logout.');
+        }
+    }
+    if (positionals[0] === 'setup') {
+        checkOptions(flags, ['app-url']);
+        if (positionals.length !== 2 || positionals[1] !== 'status')
+            usage('Usage: stand setup status [--app-url URL].');
+        output(await setupStatus(client, profile, options, stringFlag(flags, 'app-url')), json);
+        return;
+    }
+    if (positionals[0] === 'api') {
+        checkOptions(flags, ['body-file', 'query-param', 'form-string', 'form-file']);
+        if (positionals.length !== 3)
+            usage('Usage: stand api METHOD /v1/path [--body-file FILE] [--query-param key=value].');
+        const method = positionals[1].toUpperCase();
+        if (!['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method))
+            usage('Unsupported HTTP method.');
+        const url = apiUrl(profile.apiUrl, positionals[2]);
+        if (!publicOperation(url.pathname, method))
+            usage('This operation is not in the public API contract. Run stand schema.');
+        for (const pair of flags['query-param'] ?? []) {
+            const separator = pair.indexOf('=');
+            if (separator <= 0)
+                usage('--query-param must be key=value.');
+            url.searchParams.append(pair.slice(0, separator), pair.slice(separator + 1));
+        }
+        if ([...url.searchParams.keys()].some(key => /^(?:token|access_token|authorization|refresh_token)$/i.test(key)))
+            usage('Credentials must not be placed in API URLs.');
+        const hasForm = flags['form-string'] !== undefined || flags['form-file'] !== undefined;
+        if (hasForm && flags['body-file'] !== undefined)
+            usage('Multipart form flags and --body-file are mutually exclusive.');
+        if (['GET', 'HEAD'].includes(method) && (flags['body-file'] || hasForm))
+            usage('GET and HEAD do not accept a body.');
+        const siteUpdate = method === 'PUT' && /^\/v1\/sites\/[^/]+\/?$/.test(url.pathname);
+        // Decode the exact Site payload before approval and reuse it for dispatch;
+        // editing a body file while the prompt is open cannot change the approved write.
+        const preparedBody = siteUpdate && !hasForm ? await requestBody(flags, process.stdin, signal) : undefined;
+        if (!['GET', 'HEAD'].includes(method))
+            await confirm(`${method} ${url.pathname}`, flags, signal, legacyEmbedWarning(preparedBody));
+        const multipart = hasForm ? await multipartBody(url.pathname, method, flags['form-string'] ?? [], flags['form-file'] ?? [], signal) : undefined;
+        const body = hasForm ? undefined : siteUpdate ? preparedBody : await requestBody(flags, process.stdin, signal);
+        output(await client.request(`${url.pathname}${url.search}`, { ...options, method, body, multipart }), json);
+        return;
+    }
+    const match = findCommand(positionals);
+    if (!match)
+        usage('Unknown command. Run stand --help or stand commands --json.');
+    checkOptions(flags, match.definition.options);
+    const preparedBody = match.definition.command === 'sites update' ? await requestBody(flags, process.stdin, signal) : undefined;
+    if (match.definition.confirmation)
+        await confirm(`${match.definition.command} ${match.args.join(' ')}`.trim(), flags, signal, legacyEmbedWarning(preparedBody));
+    if ((flags.interval !== undefined || flags.count !== undefined) && !flags.watch)
+        usage('--interval and --count require --watch.');
+    const count = flags.watch ? integerFlag(flags, 'count', Number.MAX_SAFE_INTEGER, 1, 1_000_000) : 1;
+    const interval = integerFlag(flags, 'interval', 5, 2, 3600) * 1000;
+    for (let iteration = 0; iteration < count; iteration++) {
+        if (iteration > 0)
+            await sleep(interval, signal);
+        const result = await executeCommand(client, match.definition, match.args, flags, process.stdin, options, preparedBody);
+        output(result, json);
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.on('SIGINT', cancel);
+    process.on('SIGTERM', cancel);
+    process.on('SIGHUP', cancel);
+    process.stdout.on('error', error => {
+        if (isObject(error) && error.code === 'EPIPE') {
+            process.exit(0);
+        }
+    });
+    main(undefined, process.env, controller.signal).catch(error => {
+        const failure = error instanceof CliError ? error : new CliError('LOCAL_ERROR', 'The command failed locally. Check file permissions and configuration.');
+        if (process.argv.includes('--json') || !process.stderr.isTTY) {
+            process.stderr.write(`${terminalJson({ error: { code: failure.code, message: failure.message, ...(failure.status === undefined ? {} : { status: failure.status }), ...(failure.retryAfter ? { retryAfter: failure.retryAfter } : {}), ...(failure.reconciliation ? { reconciliation: failure.reconciliation } : {}) } })}\n`);
+        }
+        else {
+            process.stderr.write(`${terminalText(failure.code)}: ${terminalText(failure.message)}\n`);
+            if (failure.reconciliation)
+                process.stderr.write(`Reconciliation: ${terminalJson(failure.reconciliation)}\n`);
+        }
+        process.exitCode = failure.exitCode;
+    }).finally(() => { process.removeListener('SIGINT', cancel); process.removeListener('SIGTERM', cancel); process.removeListener('SIGHUP', cancel); });
+}

package/dist/multipart.js

@@ -0,0 +1,115 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { CliError, isObject, usage } from './errors.js';
+import { publicOperation } from './contract.js';
+const MAX_TEXT_BYTES = 1024 * 1024;
+const MAX_FORM_BYTES = 11 * 1024 * 1024; // Leave room inside the server's 12 MiB multipart envelope.
+const IMAGE_UPLOAD_LIMITS = {
+    uploadRepAvatar: 5, uploadDraftAvatar: 5, uploadStandinAvatar: 5,
+    uploadMyIcon: 5, uploadMyLogo: 5, uploadIcon: 5, uploadLogo: 5,
+    uploadStandinPinIcon: 10, uploadStandinPinLogo: 10,
+};
+const MIME = {
+    '.pdf': 'application/pdf', '.txt': 'text/plain', '.md': 'text/markdown', '.markdown': 'text/markdown', '.csv': 'text/csv',
+    '.html': 'text/html', '.json': 'application/json', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif',
+};
+const cancelled = (signal) => { if (signal?.aborted)
+    throw new CliError('CANCELLED', 'Upload preparation cancelled. No request was sent.', 130); };
+/** Construct only a published multipart operation; never interpret @values or URLs as files. */
+export async function multipartBody(path, method, strings, files, signal) {
+    const operation = publicOperation(path, method);
+    const requestBody = isObject(operation?.requestBody) ? operation.requestBody : undefined;
+    const content = isObject(requestBody?.content) ? requestBody.content : undefined;
+    const media = isObject(content?.['multipart/form-data']) ? content['multipart/form-data'] : undefined;
+    const schema = isObject(media?.schema) ? media.schema : undefined;
+    const properties = isObject(schema?.properties) ? schema.properties : undefined;
+    if (!operation || !schema || !properties || !['POST', 'PUT', 'PATCH'].includes(method))
+        usage('This public operation does not accept multipart form data. Use stand schema to inspect its request.');
+    const entries = [...strings.map(value => ({ value, file: false })), ...files.map(value => ({ value, file: true }))];
+    if (entries.length > 20)
+        usage('Multipart uploads accept at most 20 parts.');
+    const seen = new Set();
+    const parsed = entries.map(({ value, file }) => {
+        const separator = value.indexOf('=');
+        const name = value.slice(0, separator);
+        if (separator < 1 || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name) || /^(?:token|access_token|authorization|refresh_token)$/i.test(name))
+            usage('Form parts must use a published field name followed by = and its literal value or file path. Credentials are not form fields.');
+        if (seen.has(name))
+            usage(`Duplicate form field: ${name}.`);
+        seen.add(name);
+        const property = properties[name];
+        if (!isObject(property) || property.type !== 'string' || (property.format === 'binary') !== file)
+            usage(`Form field ${name} is not a published ${file ? 'file' : 'text'} field for this operation.`);
+        const input = value.slice(separator + 1);
+        if (file && !input)
+            usage(`Form field ${name} requires a local file path.`);
+        if (!file && (Buffer.byteLength(input, 'utf8') > MAX_TEXT_BYTES
+            || (typeof property.maxLength === 'number' && input.length > property.maxLength)
+            || (Array.isArray(property.enum) && !property.enum.includes(input))))
+            usage(`Form field ${name} exceeds its limit or is not an allowed value. Inspect stand schema.`);
+        return { name, input, file };
+    });
+    if (Array.isArray(schema.required) && schema.required.some(name => typeof name === 'string' && !seen.has(name)))
+        usage(`Missing required multipart fields: ${schema.required.filter(name => typeof name === 'string' && !seen.has(name)).join(', ')}.`);
+    const form = new FormData();
+    let total = 0;
+    for (const part of parsed) {
+        cancelled(signal);
+        if (!part.file) {
+            total += Buffer.byteLength(part.input, 'utf8');
+            if (total > MAX_FORM_BYTES)
+                usage('Multipart fields and files exceed the 11 MiB CLI payload bound.');
+            form.append(part.name, part.input);
+            continue;
+        }
+        const filename = basename(part.input);
+        if (!filename || Buffer.byteLength(filename) > 255 || /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/.test(filename))
+            usage('Upload filename must be at most 255 bytes and contain no control or bidirectional formatting characters.');
+        const contentType = MIME[extname(filename).toLowerCase()] ?? 'application/octet-stream';
+        const feedback = operation.operationId === 'submitFeedback';
+        const imageLimit = typeof operation.operationId === 'string' ? IMAGE_UPLOAD_LIMITS[operation.operationId] : undefined;
+        if (operation.operationId === 'uploadKnowledgeBaseSource' && !['.pdf', '.md', '.markdown', '.txt', '.docx'].includes(extname(filename).toLowerCase()))
+            usage('Knowledge uploads support PDF, Markdown, text and Word .docx files.');
+        if (feedback && !contentType.startsWith('image/'))
+            usage('Feedback attachments must use a .png, .jpg, .jpeg, .webp or .gif image filename.');
+        if (imageLimit && !contentType.startsWith('image/'))
+            usage('Image uploads must use a .png, .jpg, .jpeg, .webp or .gif filename.');
+        const limit = (feedback ? 4 : imageLimit ?? 10) * 1024 * 1024;
+        let handle;
+        try {
+            handle = await open(part.input, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        }
+        catch {
+            throw new CliError('UPLOAD_FILE', 'Cannot open the upload. Use a readable local regular file, not a symlink or URL. No request was sent.', 2);
+        }
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.size < 1 || stat.size > limit || total + stat.size > MAX_FORM_BYTES)
+                usage(`Upload must be a nonempty regular file of at most ${limit / 1024 / 1024} MiB; total multipart payload must stay within 11 MiB.`);
+            const chunks = [];
+            let size = 0;
+            while (true) {
+                cancelled(signal);
+                const buffer = Buffer.alloc(Math.min(64 * 1024, limit - size + 1));
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+                if (!bytesRead)
+                    break;
+                size += bytesRead;
+                if (size > limit || total + size > MAX_FORM_BYTES)
+                    usage('Upload grew beyond its file or aggregate limit. No request was sent.');
+                chunks.push(buffer.subarray(0, bytesRead));
+            }
+            if (size !== stat.size)
+                usage('Upload changed while it was being read. Retry only after the file is stable.');
+            total += size;
+            form.append(part.name, new Blob(chunks, { type: contentType }), filename);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    cancelled(signal);
+    return form;
+}