@tuuject/surowan-utils 0.0.0-canary.24.1.g5ba29720fe68

package/dist/client.js

@@ -0,0 +1,228 @@
+import { Buffer } from 'node:buffer';
+import { CliError, usageError } from "./errors.js";
+/**
+ * Validates an endpoint. Plaintext http is only accepted on loopback: the API
+ * key travels in a header and must not cross the network unencrypted. URL
+ * credentials are rejected so the key can never be smuggled through a URL.
+ */
+export function parseEndpoint(raw) {
+    const text = raw.trim();
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw usageError('invalid_endpoint', 'endpoint must be an absolute http(s) URL');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw usageError('invalid_endpoint', 'endpoint must use http or https');
+    }
+    if (url.username !== '' || url.password !== '') {
+        throw usageError('invalid_endpoint', 'endpoint must not contain URL credentials');
+    }
+    if (url.search !== '' || url.hash !== '') {
+        throw usageError('invalid_endpoint', 'endpoint must not contain a query string or fragment');
+    }
+    if (url.protocol === 'http:' && !isLoopbackHost(url.hostname)) {
+        throw usageError('insecure_endpoint', 'plaintext http is only allowed for loopback endpoints; use https');
+    }
+    if (!url.pathname.endsWith('/')) {
+        url.pathname = `${url.pathname}/`;
+    }
+    return url;
+}
+function isLoopbackHost(hostname) {
+    const host = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+    return host === 'localhost' || host === '::1' || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+/**
+ * Minimal JSON client for the Admin API. Requests never follow redirects and
+ * are never retried; the timeout aborts the in-flight request and the response
+ * body read that follows it.
+ */
+export class AdminClient {
+    #baseUrl;
+    #apiKey;
+    #defaultTimeoutMs;
+    constructor(options) {
+        this.#baseUrl = options.baseUrl;
+        this.#apiKey = options.apiKey;
+        this.#defaultTimeoutMs = options.defaultTimeoutMs;
+    }
+    async get(path, query) {
+        return await this.#request('GET', path, query, undefined);
+    }
+    async post(path, body) {
+        return await this.#request('POST', path, undefined, body);
+    }
+    /**
+     * Downloads a media body. The same redirect/timeout rules as JSON requests
+     * apply; the body is bounded by `maxBytes` so an oversized or stalled stream
+     * fails fast instead of filling memory or disk.
+     */
+    async getMedia(path, query, maxBytes) {
+        const url = this.#resolve(path, query);
+        const init = {
+            method: 'GET',
+            headers: {
+                authorization: `Bearer ${this.#apiKey}`,
+                accept: 'application/octet-stream',
+            },
+            redirect: 'error',
+            signal: AbortSignal.timeout(this.#defaultTimeoutMs),
+        };
+        try {
+            const response = await fetch(url, init);
+            if (!response.ok) {
+                throw await responseError(response);
+            }
+            const body = await readBodyBytes(response, maxBytes);
+            if (body.truncated) {
+                throw mediaTooLarge(maxBytes);
+            }
+            return {
+                bytes: body.bytes,
+                contentType: normalizeContentType(response.headers.get('content-type')),
+                variant: response.headers.get('x-plasticwan-media-variant'),
+            };
+        }
+        catch (error) {
+            throw translateFetchError(error, this.#defaultTimeoutMs);
+        }
+    }
+    #resolve(path, query) {
+        const url = new URL(path.replace(/^\/+/, ''), this.#baseUrl);
+        if (query !== undefined) {
+            for (const [key, value] of query) {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url;
+    }
+    async #request(method, path, query, body) {
+        const url = this.#resolve(path, query);
+        const headers = {
+            authorization: `Bearer ${this.#apiKey}`,
+            accept: 'application/json',
+        };
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+        const init = {
+            method,
+            headers,
+            redirect: 'error',
+            signal: AbortSignal.timeout(this.#defaultTimeoutMs),
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        try {
+            const response = await fetch(url, init);
+            // The body read belongs to the same try: a server that sends headers and
+            // then stalls must hit the timeout path, not `internal_error`.
+            return await readJsonResponse(response);
+        }
+        catch (error) {
+            throw translateFetchError(error, this.#defaultTimeoutMs);
+        }
+    }
+}
+function mediaTooLarge(maxBytes) {
+    return new CliError('media_file_too_large', `media content exceeded ${maxBytes} bytes`);
+}
+function translateFetchError(error, timeoutMs) {
+    if (error instanceof CliError) {
+        // A failed body read (invalid JSON, oversized body, ...) already carries a
+        // structured client error; it must keep its own code.
+        return error;
+    }
+    if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
+        return new CliError('timeout', `request timed out after ${timeoutMs}ms; it was not retried`);
+    }
+    const cause = error instanceof Error && error.cause instanceof Error ? error.cause.message : '';
+    const text = `${error instanceof Error ? error.message : String(error)} ${cause}`;
+    if (/redirect/i.test(text)) {
+        return new CliError('redirect_not_allowed', 'the server attempted a redirect; redirects are not followed');
+    }
+    return new CliError('network_error', 'the request failed before a response arrived; it was not retried');
+}
+async function readJsonResponse(response) {
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw responseErrorFromBody(response, bodyText);
+    }
+    if (bodyText.length === 0) {
+        throw new CliError('invalid_response', 'server returned an empty response');
+    }
+    const parsed = tryParseJson(bodyText);
+    if (parsed === undefined) {
+        throw new CliError('invalid_response', 'server response was not valid JSON');
+    }
+    return parsed;
+}
+async function responseError(response) {
+    return responseErrorFromBody(response, await response.text());
+}
+/** A JSON error body survives as the error code/message; anything else is http_error. */
+function responseErrorFromBody(response, bodyText) {
+    const parsed = tryParseJson(bodyText);
+    if (isRecord(parsed) && typeof parsed.error === 'string' && parsed.error.length > 0) {
+        const message = typeof parsed.message === 'string' && parsed.message.length > 0 ? parsed.message : parsed.error;
+        return new CliError(parsed.error, message);
+    }
+    return new CliError('http_error', `server responded with HTTP ${response.status}`);
+}
+function normalizeContentType(raw) {
+    if (raw === null) {
+        return null;
+    }
+    const type = (raw.split(';')[0] ?? '').trim().toLowerCase();
+    return type.length === 0 ? null : type;
+}
+async function readBodyBytes(response, maxBytes) {
+    const declared = response.headers.get('content-length');
+    if (declared !== null && /^\d+$/.test(declared) && Number(declared) > maxBytes) {
+        await response.body?.cancel().catch(() => undefined);
+        return { bytes: Buffer.alloc(0), truncated: true };
+    }
+    const stream = response.body;
+    if (stream === null) {
+        return { bytes: Buffer.alloc(0), truncated: false };
+    }
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value === undefined) {
+                continue;
+            }
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                return { bytes: Buffer.alloc(0), truncated: true };
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return { bytes: Buffer.concat(chunks), truncated: false };
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/commands.d.ts

@@ -0,0 +1,19 @@
+import type { CliCommand } from './args.ts';
+import { type AdminClient } from './client.ts';
+/**
+ * `--global-prompt` and `--group-prompt` accept at most 64Ki characters. The
+ * byte cap bounds the buffer while reading; the character cap is the contract.
+ */
+export declare const MAX_PROMPT_CHARS = 65536;
+export interface CliIo {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+}
+export interface CommandContext {
+    readonly json: boolean;
+    readonly io: CliIo;
+    readonly timeoutMs: number;
+    /** Redacts known secrets from any text the CLI prints or persists. */
+    readonly redact: (text: string) => string;
+}
+export declare function executeCommand(command: CliCommand, context: CommandContext, client: AdminClient): Promise<number>;

package/dist/commands.js

@@ -0,0 +1,403 @@
+import { Buffer } from 'node:buffer';
+import { readFile, stat } from 'node:fs/promises';
+import { isRecord } from "./client.js";
+import { CliError, usageError } from "./errors.js";
+import { runMedia } from "./media.js";
+/**
+ * `--global-prompt` and `--group-prompt` accept at most 64Ki characters. The
+ * byte cap bounds the buffer while reading; the character cap is the contract.
+ */
+export const MAX_PROMPT_CHARS = 65_536;
+const MAX_PROMPT_BYTES = MAX_PROMPT_CHARS * 4;
+export async function executeCommand(command, context, client) {
+    switch (command.kind) {
+        case 'list':
+            return await runList(command, context, client);
+        case 'get':
+            return await runGet(command, context, client);
+        case 'prompts':
+            return await runPrompts(command, context, client);
+        case 'preflight':
+            return await runPreflight(command, context, client);
+        case 'media':
+            return await runMedia(command, context, client);
+        case 'replay':
+            return await runReplay(command, context, client);
+        case 'models-list':
+            return await runModelsList(context, client);
+        case 'config-show':
+            return await runConfigShow(command, context, client);
+        case 'prompt-get':
+            return await runPromptGet(command, context, client);
+    }
+}
+async function runList(command, context, client) {
+    const query = new URLSearchParams();
+    if (command.limit !== undefined) {
+        query.set('limit', String(command.limit));
+    }
+    if (command.cursor !== undefined) {
+        query.set('cursor', command.cursor);
+    }
+    if (command.state !== undefined) {
+        query.set('state', command.state);
+    }
+    if (command.chat !== undefined) {
+        query.set('chat', command.chat);
+    }
+    if (command.search !== undefined) {
+        query.set('search', command.search);
+    }
+    if (command.at !== undefined) {
+        query.set('at', command.at);
+    }
+    if (command.from !== undefined) {
+        query.set('from', command.from);
+    }
+    if (command.to !== undefined) {
+        query.set('to', command.to);
+    }
+    const raw = await client.get('api/invocations', query);
+    if (!isRecord(raw) || !Array.isArray(raw.items)) {
+        throw new CliError('invalid_response', 'invocation list response has an unexpected shape');
+    }
+    const nextCursor = raw.next_cursor;
+    if (nextCursor !== null && typeof nextCursor !== 'string') {
+        throw new CliError('invalid_response', 'invocation list next_cursor must be a string or null');
+    }
+    context.io.stdout(context.json ? `${JSON.stringify(raw)}\n` : humanList(raw.items, nextCursor));
+    return 0;
+}
+async function runGet(command, context, client) {
+    const raw = await client.get(`api/invocations/${command.id}`);
+    if (!isRecord(raw) || typeof raw.id !== 'string') {
+        throw new CliError('invalid_response', 'invocation response has an unexpected shape');
+    }
+    writeDocument(raw, context);
+    return 0;
+}
+async function runPrompts(command, context, client) {
+    const raw = await client.get(`api/invocations/${command.id}/prompts`);
+    if (!isRecord(raw) ||
+        raw.source !== 'active' ||
+        typeof raw.source_invocation_id !== 'string' ||
+        typeof raw.global_prompt !== 'string' ||
+        typeof raw.group_prompt !== 'string' ||
+        raw.core_read_only !== true ||
+        !isNullableRecord(raw.template_values)) {
+        throw new CliError('invalid_response', 'active prompt response has an unexpected shape');
+    }
+    writeDocument(raw, context);
+    return 0;
+}
+async function runPreflight(command, context, client) {
+    const raw = await client.get(`api/invocations/${command.id}/replay-preflight`, preflightQuery(command));
+    if (!isPreflight(raw)) {
+        throw new CliError('invalid_response', 'replay preflight response has an unexpected shape');
+    }
+    writeDocument(raw, context);
+    return 0;
+}
+async function runReplay(command, context, client) {
+    // Prompt input is fully resolved (including stdin) before any request, so a
+    // stalled stdin never sends a preflight the old contract would not have sent.
+    // A sliced replay missing --confirm-paid is already refused while parsing
+    // arguments, so this path never reads stdin or reaches the preflight either.
+    const body = replayModelFields(command);
+    let hasPromptOverrides = false;
+    if (command.globalPromptSource !== undefined) {
+        body.global_prompt = await readPromptPart('global', command.globalPromptSource, context, false);
+        hasPromptOverrides = true;
+    }
+    if (command.groupPromptSource !== undefined) {
+        body.group_prompt = await readPromptPart('group', command.groupPromptSource, context, true);
+        hasPromptOverrides = true;
+    }
+    const preflight = await client.get(`api/invocations/${command.id}/replay-preflight`, preflightQuery(command));
+    if (!isPreflight(preflight)) {
+        throw new CliError('invalid_response', 'replay preflight response has an unexpected shape');
+    }
+    if (preflight.available !== true) {
+        // The preflight reason is the engine's own stable code, so the CLI reports
+        // exactly the failure a POST would have produced instead of a new one.
+        throw unavailableError(preflight);
+    }
+    // `before_send_id` selects a replay boundary; it is not a prompt override, so
+    // it must not require the prompt-overrides permission.
+    if (hasPromptOverrides && preflight.prompt_overrides_available !== true) {
+        throw new CliError('replay_prompt_parts_unavailable', 'this scene cannot replay with prompt overrides (prompt_overrides_available is false)');
+    }
+    if (command.beforeSendId !== undefined) {
+        body.before_send_id = command.beforeSendId;
+    }
+    const raw = await client.post(`api/invocations/${command.id}/replay`, body);
+    if (!isRecord(raw)) {
+        throw new CliError('invalid_response', 'replay response has an unexpected shape');
+    }
+    // Preserve the structured result even on failure; runCli reports the
+    // failure through the shared JSON stderr and exit-code path.
+    const failed = raw.error !== undefined && raw.error !== null;
+    writeDocument(raw, context);
+    if (failed) {
+        throw new CliError('replay_failed', `replay did not complete: ${describeError(raw.error)}`);
+    }
+    return 0;
+}
+async function runModelsList(context, client) {
+    const raw = await client.get('api/models');
+    if (!isRecord(raw) ||
+        raw.source !== 'active' ||
+        !Number.isSafeInteger(raw.generation) ||
+        !Array.isArray(raw.models) ||
+        !raw.models.every((model) => isRecord(model) &&
+            typeof model.provider === 'string' &&
+            model.provider.length > 0 &&
+            typeof model.model === 'string' &&
+            model.model.length > 0 &&
+            typeof model.name === 'string' &&
+            typeof model.reasoning === 'boolean' &&
+            typeof model.context_window === 'number' &&
+            model.context_window > 0 &&
+            typeof model.max_tokens === 'number' &&
+            model.max_tokens > 0 &&
+            Array.isArray(model.input) &&
+            model.input.includes('text') &&
+            model.input.every((input) => input === 'text' || input === 'image') &&
+            Array.isArray(model.thinking_levels) &&
+            model.thinking_levels.length > 0 &&
+            model.thinking_levels.every((level) => typeof level === 'string' && ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'].includes(level)))) {
+        throw new CliError('invalid_response', 'active model list response has an unexpected shape');
+    }
+    writeDocument(raw, context);
+    return 0;
+}
+async function runConfigShow(command, context, client) {
+    const query = new URLSearchParams({ source: command.source ?? 'active' });
+    const raw = await client.get('api/config/view', query);
+    if (!isRecord(raw) || typeof raw.source !== 'string' || !isRecord(raw.config)) {
+        throw new CliError('invalid_response', 'config view response has an unexpected shape');
+    }
+    writeDocument(raw, context);
+    return 0;
+}
+async function runPromptGet(command, context, client) {
+    const query = new URLSearchParams({ source: command.source ?? 'active' });
+    if (command.chat !== undefined) {
+        query.set('chat', command.chat);
+    }
+    const raw = await client.get(`api/prompts/${command.scope}`, query);
+    if (!isRecord(raw)) {
+        throw new CliError('invalid_response', 'prompt response has an unexpected shape');
+    }
+    if (raw.scope !== command.scope ||
+        typeof raw.prompt !== 'string' ||
+        raw.core_read_only !== true ||
+        !isNullableString(raw.chat_id) ||
+        typeof raw.source !== 'string') {
+        throw new CliError('invalid_response', `prompt ${command.scope} response has an unexpected shape`);
+    }
+    writeDocument(raw, context);
+    return 0;
+}
+function writeDocument(raw, context) {
+    context.io.stdout(context.json ? `${JSON.stringify(raw)}\n` : `${JSON.stringify(raw, null, 2)}\n`);
+}
+function isNullableString(value) {
+    return value === null || typeof value === 'string';
+}
+function isNullableRecord(value) {
+    return value === null || isRecord(value);
+}
+function isPreflight(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.available === 'boolean' &&
+        typeof value.prompt_overrides_available === 'boolean' &&
+        isNullableString(value.reason) &&
+        isNullableString(value.message));
+}
+function unavailableError(preflight) {
+    const reason = preflight.reason !== null && preflight.reason.length > 0 ? preflight.reason : undefined;
+    const message = preflight.message !== null && preflight.message.length > 0 ? preflight.message : undefined;
+    return new CliError(reason ?? 'replay_unavailable', message ?? reason ?? 'replay is not available');
+}
+function replayModelFields(selection) {
+    return {
+        ...(selection.provider === undefined ? {} : { provider: selection.provider }),
+        ...(selection.model === undefined ? {} : { model: selection.model }),
+        ...(selection.thinkingLevel === undefined ? {} : { thinking_level: selection.thinkingLevel }),
+    };
+}
+/** An absent selection keeps the old request URL byte-for-byte. */
+function preflightQuery(command) {
+    const query = new URLSearchParams(replayModelFields(command));
+    if (command.beforeSendId !== undefined) {
+        query.set('before_send_id', command.beforeSendId);
+    }
+    return query;
+}
+function humanList(items, nextCursor) {
+    if (items.length === 0) {
+        return 'no invocations\n';
+    }
+    const lines = items.flatMap((item) => humanListLines(item));
+    if (nextCursor !== null) {
+        lines.push(`next_cursor: ${nextCursor}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function humanListLines(item) {
+    return [humanListLine(item), ...humanMatchedLines(item)];
+}
+function humanListLine(item) {
+    if (!isRecord(item)) {
+        return '(malformed invocation)';
+    }
+    const chat = isRecord(item.chat) ? item.chat : undefined;
+    const title = typeof chat?.title === 'string' && chat.title.length > 0 ? chat.title : undefined;
+    const username = typeof chat?.username === 'string' && chat.username.length > 0 ? chat.username : undefined;
+    const chatId = chat !== undefined && (typeof chat.telegram_chat_id === 'string' || typeof chat.telegram_chat_id === 'number')
+        ? String(chat.telegram_chat_id)
+        : '?';
+    const thread = chat !== undefined && typeof chat.message_thread_id === 'number' && chat.message_thread_id !== 0
+        ? `#${chat.message_thread_id}`
+        : '';
+    const parts = [
+        typeof item.id === 'string' ? item.id : '?',
+        typeof item.state === 'string' ? item.state : '?',
+        typeof item.created_at === 'string' ? item.created_at : '?',
+        `${title ?? username ?? 'chat'}(${chatId}${thread})`,
+    ];
+    if (typeof item.total_tokens === 'number') {
+        parts.push(`tokens=${item.total_tokens}`);
+    }
+    if (typeof item.total_cost === 'number') {
+        parts.push(`cost=${item.total_cost}`);
+    }
+    return parts.join(' ');
+}
+/** Longest matched-message excerpt kept in the human list; the JSON output is untouched. */
+const MAX_MATCH_SUMMARY_CHARS = 160;
+/**
+ * `matched_messages` describes which messages made a filtered invocation match.
+ * It keeps the invocation's own `created_at` as the leading timestamp; a matched
+ * message's `at` is never presented as the invocation time.
+ */
+function humanMatchedLines(item) {
+    if (!isRecord(item) || !Array.isArray(item.matched_messages)) {
+        return [];
+    }
+    const lines = [];
+    for (const entry of item.matched_messages) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const source = entry.source === 'incoming' || entry.source === 'bot' ? entry.source : undefined;
+        if (source === undefined) {
+            continue;
+        }
+        const parts = ['  matched', source];
+        if (typeof entry.at === 'string' && entry.at.length > 0) {
+            parts.push(entry.at);
+        }
+        if (typeof entry.telegram_message_id === 'string') {
+            parts.push(`msg=${entry.telegram_message_id}`);
+        }
+        if (typeof entry.telegram_send_id === 'string') {
+            parts.push(`send=${entry.telegram_send_id}`);
+        }
+        const text = matchSummary(entry.text);
+        if (text.length > 0) {
+            parts.push(text);
+        }
+        lines.push(parts.join(' '));
+    }
+    return lines;
+}
+function matchSummary(value) {
+    if (typeof value !== 'string') {
+        return '';
+    }
+    const collapsed = value.replace(/\s+/g, ' ').trim();
+    return collapsed.length > MAX_MATCH_SUMMARY_CHARS ? `${collapsed.slice(0, MAX_MATCH_SUMMARY_CHARS)}…` : collapsed;
+}
+function describeError(value) {
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    try {
+        return JSON.stringify(value) ?? 'unknown error';
+    }
+    catch {
+        return 'unknown error';
+    }
+}
+async function readPromptPart(part, source, context, allowEmpty) {
+    const text = source === '-' ? await readStdinBounded(part, context.timeoutMs) : await readFileBounded(part, source);
+    if (!allowEmpty && text.trim().length === 0) {
+        throw usageError(`${part}_prompt_empty`, `${part} prompt must not be empty`);
+    }
+    if (text.length > MAX_PROMPT_CHARS) {
+        throw promptTooLarge(part);
+    }
+    return text;
+}
+async function readFileBounded(part, path) {
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch {
+        throw usageError(`${part}_prompt_read_failed`, `cannot read ${part} prompt file: ${path}`);
+    }
+    // A FIFO, device or socket passes stat() but can block a plain read forever;
+    // only a regular file (or a symlink to one) is a bounded prompt source.
+    // ponytail: path-based check; use open(O_NONBLOCK) + fstat if the containing
+    // directory is adversarial and a file can be swapped in after stat().
+    if (!info.isFile()) {
+        throw usageError(`${part}_prompt_read_failed`, `${part} prompt file must be a regular file: ${path}`);
+    }
+    if (info.size > MAX_PROMPT_BYTES) {
+        throw promptTooLarge(part);
+    }
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        throw usageError(`${part}_prompt_read_failed`, `cannot read ${part} prompt file: ${path}`);
+    }
+    return text;
+}
+async function readStdinBounded(part, timeoutMs) {
+    if (process.stdin.isTTY === true) {
+        throw usageError('stdin_required', 'stdin is a terminal; pipe the prompt or pass --global-prompt/--group-prompt <file>');
+    }
+    const timer = setTimeout(() => {
+        process.stdin.destroy(new CliError('timeout', `stdin timed out after ${timeoutMs}ms; no request was sent`));
+    }, timeoutMs);
+    const chunks = [];
+    let total = 0;
+    try {
+        for await (const chunk of process.stdin) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buffer.byteLength;
+            if (total > MAX_PROMPT_BYTES) {
+                process.stdin.destroy();
+                throw promptTooLarge(part);
+            }
+            chunks.push(buffer);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function promptTooLarge(part) {
+    return usageError(`${part}_prompt_too_large`, promptTooLargeMessage(part));
+}
+function promptTooLargeMessage(part) {
+    return `${part} prompt must be at most ${MAX_PROMPT_CHARS} characters`;
+}

package/dist/credentials.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Credentials for the Admin API, stored as one 0600 file under
+ * `~/.config/surowan-utils/`. Reading and writing share the same posture:
+ * the file must be a regular file that group/other cannot read or write, its
+ * bytes never reach an error message, and a replacement is renamed into place
+ * so a failure cannot damage the previous pair.
+ */
+export interface Credentials {
+    /** Normalized base URL, in the form `parseEndpoint` produces. */
+    readonly endpoint: string;
+    readonly apiKey: string;
+}
+/** A credentials file is tiny; anything larger is not one this tool wrote. */
+export declare const MAX_CREDENTIALS_BYTES: number;
+/**
+ * `~/.config/surowan-utils/credentials.json` on every platform, Windows
+ * included: one documented location beats an XDG/AppData guess that would hide
+ * the file from users who followed the guide.
+ */
+export declare function credentialsPath(homeDir?: string): string;
+/**
+ * A key is an opaque token: no `pwk_` prefix is required, and synthetic keys
+ * (including ones ending in a backslash) must round-trip unchanged. Only what
+ * would corrupt a header or a log line is refused.
+ */
+export declare function validateApiKey(value: string): string;
+/**
+ * Reads the stored credentials, or `undefined` when nothing is stored yet.
+ * Every other anomaly fails fast with a fixed `CliError`: a JSON parse error
+ * quotes the surrounding text, and that text is the key.
+ */
+export declare function readCredentials(path: string): Promise<Credentials | undefined>;
+/**
+ * Writes the complete pair over whatever was stored before. The bytes land in
+ * a freshly created 0600 file that is renamed into place, so a failed write
+ * leaves the old file byte-for-byte intact. An existing symlink or an
+ * over-permissive file or directory is refused rather than replaced. No lock
+ * is taken: two concurrent logins are last-writer-wins.
+ */
+export declare function writeCredentials(path: string, credentials: Credentials): Promise<void>;