@roarkanalytics/cli 0.1.0

package/runtime/commands/auth.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * `roark auth login | logout | status`
+ *
+ * The token is never accepted as a flag value: flags land in shell history and
+ * in the process table, where a bearer token has no business being. It is read
+ * from a prompt with echo off, or from stdin so CI can pipe it in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAuthCommands = void 0;
+const commander_1 = require("commander");
+const node_readline_1 = require("node:readline");
+const errors_1 = require("../errors");
+const config_1 = require("../config");
+const output_1 = require("../output");
+const confirm_1 = require("../confirm");
+/** Reads a secret without echoing it, so it is not left on screen or in a scrollback. */
+const promptSecret = async (prompt) => {
+    const input = process.stdin;
+    const output = process.stderr;
+    const rl = (0, node_readline_1.createInterface)({ input, output, terminal: true });
+    const onData = (chunk) => {
+        // Redraw the prompt without the typed characters.
+        const text = chunk.toString();
+        if (text.includes('\n') || text.includes('\r'))
+            return;
+        output.write(`${prompt}`);
+    };
+    output.write(prompt);
+    input.on('data', onData);
+    try {
+        return await new Promise((resolve) => {
+            rl.question('', (answer) => resolve(answer));
+        });
+    }
+    finally {
+        input.off('data', onData);
+        rl.close();
+        output.write('\n');
+    }
+};
+const readToken = async () => {
+    if (!(0, confirm_1.isInteractive)()) {
+        const piped = await new Promise((resolve, reject) => {
+            let buffer = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (chunk) => (buffer += chunk));
+            process.stdin.on('end', () => resolve(buffer));
+            process.stdin.on('error', reject);
+        });
+        const token = piped.trim();
+        if (token.length === 0) {
+            throw new errors_1.UsageError('No token on stdin. Pipe one in, or run this in a terminal.');
+        }
+        return token;
+    }
+    const token = (await promptSecret('Bearer token: ')).trim();
+    if (token.length === 0)
+        throw new errors_1.UsageError('No token entered.');
+    return token;
+};
+const registerAuthCommands = (root, binaryName) => {
+    const auth = new commander_1.Command('auth').description('Manage the stored credential').showHelpAfterError();
+    auth.action(() => auth.outputHelp());
+    auth
+        .command('login')
+        .description('Store a bearer token for future commands')
+        .addHelpText('after', [
+        '',
+        'The token is read from a hidden prompt, or from stdin when not a terminal:',
+        '',
+        `  ${binaryName} auth login`,
+        `  echo "$ROARK_API_BEARER_TOKEN" | ${binaryName} auth login`,
+    ].join('\n'))
+        .action(async () => {
+        const token = await readToken();
+        const path = (0, config_1.writeUserConfig)({ ...(0, config_1.readUserConfig)(), bearerToken: token });
+        const color = (0, output_1.supportsColor)(process.stderr);
+        (0, output_1.write)(`${(0, output_1.paint)('Saved', 'green', color)} ${(0, config_1.maskToken)(token)} to ${path}`, process.stderr);
+    });
+    auth
+        .command('logout')
+        .description('Delete the stored credential')
+        .action(() => {
+        const removed = (0, config_1.clearUserConfig)();
+        (0, output_1.write)(removed ? `Removed ${(0, config_1.userConfigPath)()}` : `Nothing to remove at ${(0, config_1.userConfigPath)()}`, process.stderr);
+    });
+    auth
+        .command('status')
+        .description('Show which credential would be used, and where it came from')
+        .action(() => {
+        const color = (0, output_1.supportsColor)(process.stderr);
+        const fromEnv = process.env['ROARK_API_BEARER_TOKEN'];
+        const stored = (0, config_1.readUserConfig)().bearerToken;
+        if (fromEnv) {
+            (0, output_1.write)(`${(0, output_1.paint)('Authenticated', 'green', color)} via ROARK_API_BEARER_TOKEN (${(0, config_1.maskToken)(fromEnv)})`, process.stderr);
+            if (stored) {
+                (0, output_1.write)((0, output_1.paint)(`A token is also stored in ${(0, config_1.userConfigPath)()}; the environment variable wins.`, 'dim', color), process.stderr);
+            }
+            return;
+        }
+        if (stored) {
+            (0, output_1.write)(`${(0, output_1.paint)('Authenticated', 'green', color)} via ${(0, config_1.userConfigPath)()} (${(0, config_1.maskToken)(stored)})`, process.stderr);
+            return;
+        }
+        (0, output_1.write)(`${(0, output_1.paint)('Not authenticated.', 'yellow', color)} Run \`${binaryName} auth login\`.`, process.stderr);
+        process.exitCode = 3;
+    });
+    root.addCommand(auth);
+};
+exports.registerAuthCommands = registerAuthCommands;

package/runtime/commands/completion.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `roark completion <shell>`
+ *
+ * The scripts are generated from the same command table the program is built
+ * from, so they cannot describe a command that does not exist. Nothing is
+ * assembled at runtime and nothing is read from the live Commander tree.
+ */
+import { Command } from 'commander';
+export declare const registerCompletionCommand: (root: Command, binaryName: string, completions: Readonly<Record<string, string>>) => void;

package/runtime/commands/completion.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * `roark completion <shell>`
+ *
+ * The scripts are generated from the same command table the program is built
+ * from, so they cannot describe a command that does not exist. Nothing is
+ * assembled at runtime and nothing is read from the live Commander tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCompletionCommand = void 0;
+const commander_1 = require("commander");
+const errors_1 = require("../errors");
+const output_1 = require("../output");
+const LOADING_INSTRUCTIONS = {
+    bash: (binary) => `  eval "$(${binary} completion bash)"   # or install into /etc/bash_completion.d`,
+    zsh: (binary) => `  eval "$(${binary} completion zsh)"    # or write to a directory on $fpath`,
+    fish: (binary) => `  ${binary} completion fish | source     # or write to ~/.config/fish/completions`,
+    powershell: (binary) => `  ${binary} completion powershell | Out-String | Invoke-Expression   # or add to $PROFILE`,
+};
+const registerCompletionCommand = (root, binaryName, completions) => {
+    const shells = Object.keys(completions);
+    if (shells.length === 0)
+        return;
+    const help = shells
+        .map((shell) => LOADING_INSTRUCTIONS[shell]?.(binaryName))
+        .filter((line) => line !== undefined);
+    root.addCommand(new commander_1.Command('completion')
+        .description(`Print a shell completion script (${shells.join(', ')})`)
+        .argument('<shell>', `one of: ${shells.join(', ')}`)
+        .addHelpText('after', help.length > 0 ? `\nAdd one of these to your shell startup file:\n${help.join('\n')}` : '')
+        .action((shell) => {
+        // Own-property lookup only: `completions['constructor']` would otherwise
+        // resolve to something that is not a completion script.
+        const script = Object.prototype.hasOwnProperty.call(completions, shell) ? completions[shell] : undefined;
+        if (script === undefined) {
+            throw new errors_1.UsageError(`Unsupported shell '${shell}'. Supported: ${shells.join(', ')}`);
+        }
+        (0, output_1.write)(script);
+    })
+        .showHelpAfterError());
+};
+exports.registerCompletionCommand = registerCompletionCommand;

package/runtime/commands/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `roark config get | set | list | path`
+ *
+ * Only the non-secret settings are settable here. The token has its own command
+ * because it needs a hidden prompt, and `config set bearer-token <value>` would
+ * put it straight into shell history.
+ *
+ * The API has a `config` resource of its own - config as code - so `config` at
+ * the root may already exist by the time this runs, carrying the generated
+ * `diff` and `apply`. The two sets of subcommands do not overlap, so they share
+ * one command rather than either side being renamed; Commander refuses a second
+ * `config` at the root outright.
+ */
+import { Command } from 'commander';
+export declare const registerConfigCommands: (root: Command, binaryName: string) => void;

package/runtime/commands/config.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * `roark config get | set | list | path`
+ *
+ * Only the non-secret settings are settable here. The token has its own command
+ * because it needs a hidden prompt, and `config set bearer-token <value>` would
+ * put it straight into shell history.
+ *
+ * The API has a `config` resource of its own - config as code - so `config` at
+ * the root may already exist by the time this runs, carrying the generated
+ * `diff` and `apply`. The two sets of subcommands do not overlap, so they share
+ * one command rather than either side being renamed; Commander refuses a second
+ * `config` at the root outright.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerConfigCommands = void 0;
+const commander_1 = require("commander");
+const errors_1 = require("../errors");
+const config_1 = require("../config");
+const output_1 = require("../output");
+/** Settable keys, as typed, mapped onto the config field they write. */
+const KEYS = {
+    'base-url': 'baseURL',
+    timeout: 'timeout',
+    'max-retries': 'maxRetries',
+};
+const numericKeys = new Set(['timeout', 'maxRetries']);
+const keyFor = (name) => {
+    const key = KEYS[name];
+    if (!key) {
+        throw new errors_1.UsageError(`Unknown config key '${name}'. Known keys: ${Object.keys(KEYS).join(', ')}`);
+    }
+    return key;
+};
+/** The generated `config` group if it is already there, otherwise a new one. */
+const configCommand = (root) => {
+    const description = 'Read and write CLI settings, and apply config as code';
+    const existing = root.commands.find((child) => child.name() === 'config');
+    if (existing)
+        return existing.description(description);
+    const created = new commander_1.Command('config').description(description).showHelpAfterError();
+    created.action(() => created.outputHelp());
+    root.addCommand(created);
+    return created;
+};
+const registerConfigCommands = (root, binaryName) => {
+    const config = configCommand(root);
+    config
+        .command('list')
+        .description('Show the effective settings and where each file lives')
+        .option('--json', 'output as JSON')
+        .action((options) => {
+        const effective = (0, config_1.loadConfig)();
+        const shown = {
+            ...effective,
+            ...(effective.bearerToken === undefined ? {} : { bearerToken: (0, config_1.maskToken)(effective.bearerToken) }),
+        };
+        if (options.json === true) {
+            (0, output_1.write)((0, output_1.render)(shown, { format: 'json', color: (0, output_1.supportsColor)() }));
+            return;
+        }
+        for (const [name, key] of Object.entries(KEYS)) {
+            (0, output_1.write)(`${name} = ${shown[key] ?? '(unset)'}`);
+        }
+        (0, output_1.write)(`token = ${shown.bearerToken ?? '(unset)'}`);
+        (0, output_1.write)('');
+        (0, output_1.write)(`user config    ${(0, config_1.userConfigPath)()}`);
+        (0, output_1.write)(`project config ${(0, config_1.projectConfigPath)() ?? '(none)'}`);
+    });
+    config
+        .command('get')
+        .description('Print one effective setting')
+        .argument('<key>', `one of: ${Object.keys(KEYS).join(', ')}`)
+        .action((name) => {
+        const value = (0, config_1.loadConfig)()[keyFor(name)];
+        if (value === undefined)
+            process.exitCode = 1;
+        else
+            (0, output_1.write)(String(value));
+    });
+    config
+        .command('set')
+        .description('Write one setting to the user config file')
+        .argument('<key>', `one of: ${Object.keys(KEYS).join(', ')}`)
+        .argument('<value>')
+        .action((name, value) => {
+        const key = keyFor(name);
+        let parsed = value;
+        if (numericKeys.has(key)) {
+            parsed = Number(value);
+            if (!Number.isFinite(parsed))
+                throw new errors_1.UsageError(`${name} expects a number, got '${value}'`);
+        }
+        const path = (0, config_1.writeUserConfig)({ ...(0, config_1.readUserConfig)(), [key]: parsed });
+        (0, output_1.write)(`Set ${name} in ${path}`, process.stderr);
+    });
+    config
+        .command('unset')
+        .description('Remove one setting from the user config file')
+        .argument('<key>', `one of: ${Object.keys(KEYS).join(', ')}`)
+        .action((name) => {
+        const key = keyFor(name);
+        const current = (0, config_1.readUserConfig)();
+        delete current[key];
+        const path = (0, config_1.writeUserConfig)(current);
+        (0, output_1.write)(`Unset ${name} in ${path}`, process.stderr);
+    });
+    config
+        .command('path')
+        .description('Print the config file paths')
+        .action(() => {
+        (0, output_1.write)((0, config_1.userConfigPath)());
+        const project = (0, config_1.projectConfigPath)();
+        if (project)
+            (0, output_1.write)(project);
+    });
+    config.addHelpText('after', [
+        '',
+        'Precedence, highest first: flag, environment, project .roark.json, user config.',
+        '',
+        `  ${binaryName} config set base-url https://api.roark.ai`,
+        `  ${binaryName} auth login    # the token is stored separately`,
+    ].join('\n'));
+};
+exports.registerConfigCommands = registerConfigCommands;

package/runtime/config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Configuration resolution.
+ *
+ * Precedence, highest first (clig.dev): flag, environment, project config, user
+ * config. A project file lets a repo pin a base URL without every contributor
+ * exporting it; the user file is where `auth login` writes the token.
+ *
+ * A project file is untrusted input. It is found by walking up from the cwd, so
+ * it arrives with a `git clone` rather than being something the person running
+ * the command wrote, which is why `resolveConfig` records where every value came
+ * from: sending a credential to a host that a checked-in file chose is a
+ * decision the caller has to make deliberately. See `unsafeBaseUrlRedirect`.
+ */
+export interface CliConfig {
+    bearerToken?: string;
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+export declare const PROJECT_FILE = ".roark.json";
+export declare const userConfigPath: () => string;
+/** Walks up from the cwd, so a command run in a subdirectory still sees the repo's config. */
+export declare const projectConfigPath: (from?: string) => string | undefined;
+/** Which layer a value came from, lowest precedence first. */
+export type ConfigSource = 'user' | 'project' | 'environment' | 'flag';
+export interface ResolvedConfig {
+    config: CliConfig;
+    /** The layer that supplied each key that ended up set. */
+    sources: Partial<Record<keyof CliConfig, ConfigSource>>;
+    /** The project file that took part in the merge, if one was found. */
+    projectFile?: string;
+}
+export declare const resolveConfig: (overrides?: CliConfig, cwd?: string) => ResolvedConfig;
+export declare const loadConfig: (overrides?: CliConfig) => CliConfig;
+export interface BaseUrlRedirect {
+    baseURL: string;
+    projectFile: string;
+    credentialFrom: ConfigSource;
+}
+/**
+ * The one combination that leaks a secret: a project file chose the host, and
+ * the credential heading for it is one the caller did not choose per-invocation.
+ *
+ * `git clone` a repository with a `.roark.json` naming someone else's base URL,
+ * run any command anywhere inside it, and the token `auth login` stored would be
+ * posted to that host - the SDK attaches `Authorization` to whatever base URL it
+ * is given, and never scopes a credential to a host. Same shape as a malicious
+ * `.npmrc` pointing `registry` at an attacker.
+ *
+ * A token that came from the same project file is not a leak: the file supplied
+ * both halves and nothing of the caller's travels. Neither is one passed as
+ * `--token` for this run, which is an explicit act naming both.
+ */
+export declare const unsafeBaseUrlRedirect: (resolved: ResolvedConfig) => BaseUrlRedirect | undefined;
+/** `ROARK_ALLOW_PROJECT_BASE_URL`, for scripts that cannot pass the flag. */
+export declare const allowProjectBaseUrlFromEnvironment: () => boolean;
+/**
+ * Written 0600: it holds a bearer token, and the default 0644 would expose it to
+ * every account on a shared machine.
+ */
+export declare const writeUserConfig: (config: CliConfig) => string;
+export declare const readUserConfig: () => CliConfig;
+export declare const clearUserConfig: () => boolean;
+/** `roark-...-abcd` -> `roar...abcd`: enough to identify, not enough to use. */
+export declare const maskToken: (token: string) => string;

package/runtime/config.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Configuration resolution.
+ *
+ * Precedence, highest first (clig.dev): flag, environment, project config, user
+ * config. A project file lets a repo pin a base URL without every contributor
+ * exporting it; the user file is where `auth login` writes the token.
+ *
+ * A project file is untrusted input. It is found by walking up from the cwd, so
+ * it arrives with a `git clone` rather than being something the person running
+ * the command wrote, which is why `resolveConfig` records where every value came
+ * from: sending a credential to a host that a checked-in file chose is a
+ * decision the caller has to make deliberately. See `unsafeBaseUrlRedirect`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskToken = exports.clearUserConfig = exports.readUserConfig = exports.writeUserConfig = exports.allowProjectBaseUrlFromEnvironment = exports.unsafeBaseUrlRedirect = exports.loadConfig = exports.resolveConfig = exports.projectConfigPath = exports.userConfigPath = exports.PROJECT_FILE = void 0;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.PROJECT_FILE = '.roark.json';
+const userConfigPath = () => {
+    const xdg = process.env['XDG_CONFIG_HOME'];
+    const base = xdg && xdg.length > 0 ? xdg : (0, node_path_1.join)((0, node_os_1.homedir)(), '.config');
+    return (0, node_path_1.join)(base, 'roark', 'config.json');
+};
+exports.userConfigPath = userConfigPath;
+/** Walks up from the cwd, so a command run in a subdirectory still sees the repo's config. */
+const projectConfigPath = (from = process.cwd()) => {
+    let directory = (0, node_path_1.resolve)(from);
+    for (;;) {
+        const candidate = (0, node_path_1.join)(directory, exports.PROJECT_FILE);
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+        const parent = (0, node_path_1.dirname)(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+};
+exports.projectConfigPath = projectConfigPath;
+const readFile = (path) => {
+    if (!path || !(0, node_fs_1.existsSync)(path))
+        return {};
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        return parsed;
+    }
+    catch (cause) {
+        // A corrupt config should say so rather than silently behaving as if the
+        // file were empty, which looks like "my token stopped working".
+        throw new Error(`Could not parse ${path}: ${cause.message}`);
+    }
+};
+const number = (value) => {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+const fromEnvironment = () => ({
+    ...(process.env['ROARK_API_BEARER_TOKEN'] ? { bearerToken: process.env['ROARK_API_BEARER_TOKEN'] } : {}),
+    ...(process.env['ROARK_BASE_URL'] ? { baseURL: process.env['ROARK_BASE_URL'] } : {}),
+    ...(number(process.env['ROARK_TIMEOUT']) !== undefined ?
+        { timeout: number(process.env['ROARK_TIMEOUT']) }
+        : {}),
+    ...(number(process.env['ROARK_MAX_RETRIES']) !== undefined ?
+        { maxRetries: number(process.env['ROARK_MAX_RETRIES']) }
+        : {}),
+});
+/** Later arguments win, and an absent key never overwrites a present one. */
+const merge = (...layers) => {
+    const result = {};
+    for (const layer of layers) {
+        for (const [key, value] of Object.entries(layer)) {
+            if (value !== undefined)
+                result[key] = value;
+        }
+    }
+    return result;
+};
+const resolveConfig = (overrides = {}, cwd) => {
+    const projectFile = (0, exports.projectConfigPath)(cwd);
+    const layers = [
+        ['user', readFile((0, exports.userConfigPath)())],
+        ['project', readFile(projectFile)],
+        ['environment', fromEnvironment()],
+        ['flag', overrides],
+    ];
+    const config = {};
+    const sources = {};
+    for (const [source, layer] of layers) {
+        for (const [key, value] of Object.entries(layer)) {
+            if (value === undefined)
+                continue;
+            config[key] = value;
+            sources[key] = source;
+        }
+    }
+    return { config, sources, ...(projectFile === undefined ? {} : { projectFile }) };
+};
+exports.resolveConfig = resolveConfig;
+const loadConfig = (overrides = {}) => (0, exports.resolveConfig)(overrides).config;
+exports.loadConfig = loadConfig;
+/**
+ * The one combination that leaks a secret: a project file chose the host, and
+ * the credential heading for it is one the caller did not choose per-invocation.
+ *
+ * `git clone` a repository with a `.roark.json` naming someone else's base URL,
+ * run any command anywhere inside it, and the token `auth login` stored would be
+ * posted to that host - the SDK attaches `Authorization` to whatever base URL it
+ * is given, and never scopes a credential to a host. Same shape as a malicious
+ * `.npmrc` pointing `registry` at an attacker.
+ *
+ * A token that came from the same project file is not a leak: the file supplied
+ * both halves and nothing of the caller's travels. Neither is one passed as
+ * `--token` for this run, which is an explicit act naming both.
+ */
+const unsafeBaseUrlRedirect = (resolved) => {
+    const { baseURL, bearerToken } = resolved.config;
+    if (resolved.sources.baseURL !== 'project' || baseURL === undefined)
+        return undefined;
+    if (bearerToken === undefined)
+        return undefined;
+    const credentialFrom = resolved.sources.bearerToken;
+    if (credentialFrom === undefined || credentialFrom === 'project' || credentialFrom === 'flag') {
+        return undefined;
+    }
+    // `sources.baseURL === 'project'` cannot be set without a project file.
+    return { baseURL, projectFile: resolved.projectFile, credentialFrom };
+};
+exports.unsafeBaseUrlRedirect = unsafeBaseUrlRedirect;
+/** `ROARK_ALLOW_PROJECT_BASE_URL`, for scripts that cannot pass the flag. */
+const allowProjectBaseUrlFromEnvironment = () => {
+    const value = process.env['ROARK_ALLOW_PROJECT_BASE_URL'];
+    return value !== undefined && value !== '' && value !== '0' && value.toLowerCase() !== 'false';
+};
+exports.allowProjectBaseUrlFromEnvironment = allowProjectBaseUrlFromEnvironment;
+/**
+ * Written 0600: it holds a bearer token, and the default 0644 would expose it to
+ * every account on a shared machine.
+ */
+const writeUserConfig = (config) => {
+    const path = (0, exports.userConfigPath)();
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    return path;
+};
+exports.writeUserConfig = writeUserConfig;
+const readUserConfig = () => readFile((0, exports.userConfigPath)());
+exports.readUserConfig = readUserConfig;
+const clearUserConfig = () => {
+    const path = (0, exports.userConfigPath)();
+    if (!(0, node_fs_1.existsSync)(path))
+        return false;
+    (0, node_fs_1.rmSync)(path);
+    return true;
+};
+exports.clearUserConfig = clearUserConfig;
+/** `roark-...-abcd` -> `roar...abcd`: enough to identify, not enough to use. */
+const maskToken = (token) => token.length <= 8 ? '****' : `${token.slice(0, 4)}...${token.slice(-4)}`;
+exports.maskToken = maskToken;

package/runtime/confirm.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Confirmation for destructive commands.
+ *
+ * Prompting is only safe when there is a human to answer: in a script stdin is
+ * not a TTY, and a prompt would either hang or silently consume piped data. So
+ * a non-interactive run requires `--yes` up front rather than being waved
+ * through, which is the direction that fails safe.
+ */
+export declare const isInteractive: () => boolean;
+export interface ConfirmOptions {
+    /** `--yes`: the user has already agreed. */
+    assumeYes: boolean;
+    /** `--no-input`: never prompt, fail instead. */
+    noInput: boolean;
+}
+export declare const confirm: (prompt: string, options: ConfirmOptions) => Promise<void>;

package/runtime/confirm.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Confirmation for destructive commands.
+ *
+ * Prompting is only safe when there is a human to answer: in a script stdin is
+ * not a TTY, and a prompt would either hang or silently consume piped data. So
+ * a non-interactive run requires `--yes` up front rather than being waved
+ * through, which is the direction that fails safe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirm = exports.isInteractive = void 0;
+const node_readline_1 = require("node:readline");
+const errors_1 = require("./errors");
+const isInteractive = () => process.stdin.isTTY === true && process.stdout.isTTY === true;
+exports.isInteractive = isInteractive;
+const confirm = async (prompt, options) => {
+    if (options.assumeYes)
+        return;
+    if (options.noInput || !(0, exports.isInteractive)()) {
+        throw new errors_1.UsageError(`${prompt} Refusing to continue without --yes.`);
+    }
+    const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolveAnswer) => {
+            rl.question(`${prompt} [y/N] `, resolveAnswer);
+        });
+        if (!/^y(es)?$/i.test(answer.trim()))
+            throw new errors_1.UsageError('Cancelled.');
+    }
+    finally {
+        rl.close();
+    }
+};
+exports.confirm = confirm;

package/runtime/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Error rendering and exit codes.
+ *
+ * Exit codes are the only thing a script can branch on, so they distinguish the
+ * cases a caller would actually handle differently: a bad invocation, a missing
+ * credential, and a missing resource are not all "1".
+ */
+import { type OutputFormat } from './output';
+export declare const EXIT: {
+    readonly ok: 0;
+    /** The request was made and the API rejected it. */
+    readonly apiError: 1;
+    /** The command line was wrong: unknown flag, missing argument, bad value. */
+    readonly usage: 2;
+    /** No credential, or the credential was refused. */
+    readonly auth: 3;
+    /** The addressed resource does not exist. */
+    readonly notFound: 4;
+    /** The request never completed: DNS, TLS, timeout, or an aborted run. */
+    readonly connection: 5;
+};
+/** Thrown for anything wrong with the command line itself. */
+export declare class UsageError extends Error {
+    readonly name = "UsageError";
+}
+/**
+ * No credential was found at all. Distinct from a rejected one, but a script
+ * handles both the same way, so both exit 3.
+ */
+export declare class AuthRequiredError extends Error {
+    readonly name = "AuthRequiredError";
+}
+export declare const exitCodeFor: (error: unknown) => number;
+interface ReportOptions {
+    format: OutputFormat;
+    color: boolean;
+    /** Shown under an auth failure so the fix is one copyable line away. */
+    binaryName: string;
+}
+/**
+ * Errors go to stderr so that `roark ... > out.json` leaves `out.json` holding
+ * only real output, and a failed run leaves it empty rather than half-written.
+ */
+export declare const reportError: (error: unknown, options: ReportOptions) => void;
+export {};