@roarkanalytics/cli 0.1.0

package/runtime/errors.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * 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".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportError = exports.exitCodeFor = exports.AuthRequiredError = exports.UsageError = exports.EXIT = void 0;
+const sdk_1 = require("@roarkanalytics/sdk");
+const output_1 = require("./output");
+exports.EXIT = {
+    ok: 0,
+    /** The request was made and the API rejected it. */
+    apiError: 1,
+    /** The command line was wrong: unknown flag, missing argument, bad value. */
+    usage: 2,
+    /** No credential, or the credential was refused. */
+    auth: 3,
+    /** The addressed resource does not exist. */
+    notFound: 4,
+    /** The request never completed: DNS, TLS, timeout, or an aborted run. */
+    connection: 5,
+};
+/** Thrown for anything wrong with the command line itself. */
+class UsageError extends Error {
+    name = 'UsageError';
+}
+exports.UsageError = UsageError;
+/**
+ * No credential was found at all. Distinct from a rejected one, but a script
+ * handles both the same way, so both exit 3.
+ */
+class AuthRequiredError extends Error {
+    name = 'AuthRequiredError';
+}
+exports.AuthRequiredError = AuthRequiredError;
+const exitCodeFor = (error) => {
+    if (error instanceof AuthRequiredError)
+        return exports.EXIT.auth;
+    if (error instanceof UsageError)
+        return exports.EXIT.usage;
+    if (error instanceof sdk_1.AuthenticationError || error instanceof sdk_1.PermissionDeniedError) {
+        return exports.EXIT.auth;
+    }
+    if (error instanceof sdk_1.NotFoundError)
+        return exports.EXIT.notFound;
+    if (error instanceof sdk_1.APIConnectionError ||
+        error instanceof sdk_1.APIConnectionTimeoutError ||
+        error instanceof sdk_1.APIUserAbortError) {
+        return exports.EXIT.connection;
+    }
+    if (error instanceof sdk_1.APIError)
+        return exports.EXIT.apiError;
+    return exports.EXIT.apiError;
+};
+exports.exitCodeFor = exitCodeFor;
+/**
+ * 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.
+ */
+const reportError = (error, options) => {
+    const stderr = process.stderr;
+    const label = (0, output_1.paint)('error:', 'red', options.color);
+    if (error instanceof UsageError || error instanceof AuthRequiredError) {
+        (0, output_1.write)(`${label} ${error.message}`, stderr);
+        return;
+    }
+    if (error instanceof sdk_1.APIError) {
+        const status = error.status === undefined ? 'request failed' : `HTTP ${error.status}`;
+        const body = error.error;
+        const hasBody = body !== undefined && body !== null;
+        // The SDK's `message` already embeds the raw response body, so printing both
+        // shows the same JSON twice: once unformatted, once formatted.
+        (0, output_1.write)(hasBody ? `${label} ${status}` : `${label} ${status}: ${error.message}`, stderr);
+        if (hasBody) {
+            (0, output_1.write)((0, output_1.render)(body, { format: options.format, color: options.color, stream: stderr }), stderr);
+        }
+        if (error instanceof sdk_1.AuthenticationError) {
+            (0, output_1.write)((0, output_1.paint)(`\nRun \`${options.binaryName} auth login\` or set ROARK_API_BEARER_TOKEN.`, 'dim', options.color), stderr);
+        }
+        return;
+    }
+    if (error instanceof Error) {
+        (0, output_1.write)(`${label} ${error.message}`, stderr);
+        return;
+    }
+    (0, output_1.write)(`${label} ${String(error)}`, stderr);
+};
+exports.reportError = reportError;

package/runtime/input.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Turning a command line into SDK arguments.
+ *
+ * Three inputs can supply the request body, in increasing precedence: piped
+ * stdin, `--data`, then individual flags. That ordering is what makes
+ * `cat call.json | roark call create --agent-id other` a useful edit of a saved
+ * payload rather than an ambiguous merge.
+ */
+import type { CliCommand, CliFlag } from './types';
+export type Params = Record<string, unknown>;
+/** `--data @payload.json` reads a file; anything else is the JSON itself. */
+export declare const readData: (value: string) => unknown;
+export declare const readStdin: () => string;
+/**
+ * Only consume stdin when there is actually something to read from.
+ *
+ * "Not a TTY" is not the same question. A descriptor can be closed, or opened
+ * non-blocking, or be `/dev/null`, and none of those are a TTY: reading them
+ * either fails outright or returns nothing. Under a CI runner it is the first,
+ * so `roark agent update <id> --name x` - a command with no pipe in sight -
+ * failed with "Could not read stdin".
+ *
+ * A pipe (`echo … | roark`) is a FIFO and a redirect (`roark < body.json`) is a
+ * regular file. Those two are what this is for, so those two are what it asks
+ * about, and anything it cannot stat is not a pipe.
+ */
+export declare const stdinIsPiped: (fd?: number) => boolean;
+export declare const coerceFlag: (raw: string | string[] | boolean, flag: CliFlag) => unknown;
+/** Writes `['metadata','source']` into `{ metadata: { source } }`. */
+export declare const setPath: (target: Params, path: string[], value: unknown) => void;
+export interface BuildArgsInput {
+    command: CliCommand;
+    /** Positional values in the order the command declares them. */
+    positionals: string[];
+    /** Commander's parsed options, keyed by the flag's camelCase option name. */
+    options: Record<string, unknown>;
+    /** Already-parsed `--data` payload, if any. */
+    data?: unknown;
+    /** Already-read stdin payload, if any. */
+    stdin?: unknown;
+}
+/** Commander stores `--outbound-dial-type` under `outboundDialType`. */
+export declare const optionKey: (flagName: string) => string;
+/**
+ * Assembles the argument list for the SDK method.
+ *
+ * The SDK takes the *last* path parameter positionally and folds any earlier
+ * ones into the params object under their wire names, so the CLI's uniform
+ * "every path param is a positional" is undone here rather than pushed onto the
+ * user. See `customerFlowEdgeCase.update(edgeCaseID, { flowId, ...body })`.
+ */
+export declare const buildArgs: (input: BuildArgsInput) => unknown[];

package/runtime/input.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Turning a command line into SDK arguments.
+ *
+ * Three inputs can supply the request body, in increasing precedence: piped
+ * stdin, `--data`, then individual flags. That ordering is what makes
+ * `cat call.json | roark call create --agent-id other` a useful edit of a saved
+ * payload rather than an ambiguous merge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildArgs = exports.optionKey = exports.setPath = exports.coerceFlag = exports.stdinIsPiped = exports.readStdin = exports.readData = void 0;
+const node_fs_1 = require("node:fs");
+const errors_1 = require("./errors");
+const parseJson = (raw, source) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new errors_1.UsageError(`${source} is not valid JSON: ${cause.message}`);
+    }
+};
+/** `--data @payload.json` reads a file; anything else is the JSON itself. */
+const readData = (value) => {
+    if (value.startsWith('@')) {
+        const path = value.slice(1);
+        if (path === '-')
+            return parseJson((0, exports.readStdin)(), 'stdin');
+        try {
+            return parseJson((0, node_fs_1.readFileSync)(path, 'utf8'), path);
+        }
+        catch (cause) {
+            if (cause instanceof errors_1.UsageError)
+                throw cause;
+            throw new errors_1.UsageError(`Could not read ${path}: ${cause.message}`);
+        }
+    }
+    return parseJson(value, '--data');
+};
+exports.readData = readData;
+const readStdin = () => {
+    try {
+        return (0, node_fs_1.readFileSync)(0, 'utf8');
+    }
+    catch (cause) {
+        throw new errors_1.UsageError(`Could not read stdin: ${cause.message}`);
+    }
+};
+exports.readStdin = readStdin;
+/**
+ * Only consume stdin when there is actually something to read from.
+ *
+ * "Not a TTY" is not the same question. A descriptor can be closed, or opened
+ * non-blocking, or be `/dev/null`, and none of those are a TTY: reading them
+ * either fails outright or returns nothing. Under a CI runner it is the first,
+ * so `roark agent update <id> --name x` - a command with no pipe in sight -
+ * failed with "Could not read stdin".
+ *
+ * A pipe (`echo … | roark`) is a FIFO and a redirect (`roark < body.json`) is a
+ * regular file. Those two are what this is for, so those two are what it asks
+ * about, and anything it cannot stat is not a pipe.
+ */
+const stdinIsPiped = (fd = 0) => {
+    if (fd === 0 && process.stdin.isTTY === true)
+        return false;
+    try {
+        const stats = (0, node_fs_1.fstatSync)(fd);
+        return stats.isFIFO() || stats.isFile();
+    }
+    catch {
+        return false;
+    }
+};
+exports.stdinIsPiped = stdinIsPiped;
+const coerceScalar = (raw, kind, flag) => {
+    switch (kind) {
+        case 'integer':
+        case 'number': {
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed))
+                throw new errors_1.UsageError(`--${flag} expects a number, got '${raw}'`);
+            if (kind === 'integer' && !Number.isInteger(parsed)) {
+                throw new errors_1.UsageError(`--${flag} expects a whole number, got '${raw}'`);
+            }
+            return parsed;
+        }
+        case 'boolean':
+            if (raw === 'true' || raw === '')
+                return true;
+            if (raw === 'false')
+                return false;
+            throw new errors_1.UsageError(`--${flag} expects true or false, got '${raw}'`);
+        case 'object':
+            return parseJson(raw, `--${flag}`);
+        case 'array':
+            // A single `--tag a,b` is a convenience over repeating the flag; JSON is
+            // there for arrays of anything that is not a bare string.
+            return raw.trimStart().startsWith('[') ? parseJson(raw, `--${flag}`) : raw.split(',');
+        default:
+            return raw;
+    }
+};
+const coerceFlag = (raw, flag) => {
+    if (typeof raw === 'boolean')
+        return raw;
+    if (Array.isArray(raw)) {
+        const values = raw.map((entry) => coerceScalar(entry, 'string', flag.name));
+        assertEnum(values, flag);
+        return values;
+    }
+    const value = coerceScalar(raw, flag.valueKind, flag.name);
+    assertEnum(Array.isArray(value) ? value : [value], flag);
+    return value;
+};
+exports.coerceFlag = coerceFlag;
+/**
+ * Checked here rather than left to the API so a typo costs no round trip and the
+ * message can list what was actually allowed.
+ */
+const assertEnum = (values, flag) => {
+    if (!flag.enumValues || flag.enumValues.length === 0)
+        return;
+    for (const value of values) {
+        if (typeof value !== 'string')
+            continue;
+        if (!flag.enumValues.includes(value)) {
+            throw new errors_1.UsageError(`--${flag.name} expects one of ${flag.enumValues.join(', ')}, got '${value}'`);
+        }
+    }
+};
+/** Writes `['metadata','source']` into `{ metadata: { source } }`. */
+const setPath = (target, path, value) => {
+    let cursor = target;
+    for (let index = 0; index < path.length - 1; index += 1) {
+        const key = path[index];
+        const existing = cursor[key];
+        if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {
+            cursor[key] = {};
+        }
+        cursor = cursor[key];
+    }
+    cursor[path.at(-1)] = value;
+};
+exports.setPath = setPath;
+/** Commander stores `--outbound-dial-type` under `outboundDialType`. */
+const optionKey = (flagName) => flagName
+    .split(/[.-]/)
+    .map((part, index) => (index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+    .join('');
+exports.optionKey = optionKey;
+const asObject = (value, source) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new errors_1.UsageError(`${source} must be a JSON object`);
+    }
+    return { ...value };
+};
+/**
+ * Assembles the argument list for the SDK method.
+ *
+ * The SDK takes the *last* path parameter positionally and folds any earlier
+ * ones into the params object under their wire names, so the CLI's uniform
+ * "every path param is a positional" is undone here rather than pushed onto the
+ * user. See `customerFlowEdgeCase.update(edgeCaseID, { flowId, ...body })`.
+ */
+const buildArgs = (input) => {
+    const { command, positionals, options } = input;
+    if (positionals.length !== command.positionals.length) {
+        const expected = command.positionals.map((entry) => `<${entry.name}>`).join(' ');
+        throw new errors_1.UsageError(`expected ${command.positionals.length} argument(s): ${expected}`);
+    }
+    const params = {
+        ...(input.stdin === undefined ? {} : asObject(input.stdin, 'stdin')),
+        ...(input.data === undefined ? {} : asObject(input.data, '--data')),
+    };
+    // Path params other than the last one travel inside the params object.
+    command.positionals.slice(0, -1).forEach((entry, index) => {
+        params[entry.paramKey] = positionals[index];
+    });
+    for (const flag of command.flags) {
+        const raw = options[(0, exports.optionKey)(flag.name)];
+        if (raw === undefined)
+            continue;
+        (0, exports.setPath)(params, flag.path, (0, exports.coerceFlag)(raw, flag));
+    }
+    for (const flag of command.flags) {
+        if (!flag.required)
+            continue;
+        if (readPath(params, flag.path) === undefined) {
+            throw new errors_1.UsageError(`--${flag.name} is required`);
+        }
+    }
+    const args = [];
+    if (command.positionals.length > 0)
+        args.push(positionals.at(-1));
+    const hasParams = Object.keys(params).length > 0;
+    if (command.hasParams && (hasParams || !command.paramsAllOptional))
+        args.push(params);
+    else if (hasParams && !command.hasParams) {
+        throw new errors_1.UsageError(`${command.commandPath.join(' ')} takes no parameters`);
+    }
+    return args;
+};
+exports.buildArgs = buildArgs;
+const readPath = (target, path) => {
+    let cursor = target;
+    for (const key of path) {
+        if (typeof cursor !== 'object' || cursor === null)
+            return undefined;
+        cursor = cursor[key];
+    }
+    return cursor;
+};

package/runtime/output.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Output formatting and colour.
+ *
+ * The rule throughout is clig.dev's: a TTY gets something a human reads, a pipe
+ * gets something a program parses. Nothing here decides that per command, so
+ * `roark call list | jq` and `roark call list` differ only in presentation.
+ */
+export type OutputFormat = 'auto' | 'json' | 'jsonl' | 'plain';
+export declare const OUTPUT_FORMATS: OutputFormat[];
+export declare const isTty: (stream?: NodeJS.WriteStream) => boolean;
+/**
+ * Colour is off unless we are certain it will be read by a terminal. `NO_COLOR`
+ * is honoured with any value, per the no-color.org convention.
+ */
+export declare const supportsColor: (stream?: NodeJS.WriteStream) => boolean;
+declare const CODES: {
+    readonly reset: "\u001B[0m";
+    readonly dim: "\u001B[2m";
+    readonly bold: "\u001B[1m";
+    readonly red: "\u001B[31m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly blue: "\u001B[34m";
+    readonly cyan: "\u001B[36m";
+};
+export type Style = keyof Omit<typeof CODES, 'reset'>;
+export declare const paint: (text: string, style: Style, enabled: boolean) => string;
+/**
+ * `auto` is JSON either way. What the TTY changes is presentation - indentation
+ * and colour - not the format, so a command's output stays parseable no matter
+ * where it runs and a script never has to pass a flag to get stable output.
+ */
+export declare const resolveFormat: (requested: OutputFormat) => Exclude<OutputFormat, "auto">;
+export interface RenderOptions {
+    format: OutputFormat;
+    color: boolean;
+    stream?: NodeJS.WriteStream;
+}
+export declare const render: (value: unknown, options: RenderOptions) => string;
+export declare const write: (text: string, stream?: NodeJS.WriteStream) => void;
+export {};

package/runtime/output.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Output formatting and colour.
+ *
+ * The rule throughout is clig.dev's: a TTY gets something a human reads, a pipe
+ * gets something a program parses. Nothing here decides that per command, so
+ * `roark call list | jq` and `roark call list` differ only in presentation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.write = exports.render = exports.resolveFormat = exports.paint = exports.supportsColor = exports.isTty = exports.OUTPUT_FORMATS = void 0;
+exports.OUTPUT_FORMATS = ['auto', 'json', 'jsonl', 'plain'];
+const isTty = (stream = process.stdout) => stream.isTTY === true;
+exports.isTty = isTty;
+/**
+ * Colour is off unless we are certain it will be read by a terminal. `NO_COLOR`
+ * is honoured with any value, per the no-color.org convention.
+ */
+const supportsColor = (stream = process.stdout) => {
+    if (process.env['NO_COLOR'] !== undefined)
+        return false;
+    if (process.env['TERM'] === 'dumb')
+        return false;
+    return (0, exports.isTty)(stream);
+};
+exports.supportsColor = supportsColor;
+const CODES = {
+    reset: '\u001b[0m',
+    dim: '\u001b[2m',
+    bold: '\u001b[1m',
+    red: '\u001b[31m',
+    green: '\u001b[32m',
+    yellow: '\u001b[33m',
+    blue: '\u001b[34m',
+    cyan: '\u001b[36m',
+};
+const paint = (text, style, enabled) => enabled ? `${CODES[style]}${text}${CODES.reset}` : text;
+exports.paint = paint;
+/** JSON with the structure picked out by colour: keys, strings, numbers, literals. */
+const colorizeJson = (json) => json.replace(/("(\\.|[^"\\])*"\s*:)|("(\\.|[^"\\])*")|(\b(?:true|false|null)\b)|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g, (match, key, _k2, str, _s2, literal) => {
+    if (key !== undefined)
+        return `${CODES.blue}${key}${CODES.reset}`;
+    if (str !== undefined)
+        return `${CODES.green}${str}${CODES.reset}`;
+    if (literal !== undefined)
+        return `${CODES.yellow}${literal}${CODES.reset}`;
+    return `${CODES.cyan}${match}${CODES.reset}`;
+});
+/**
+ * `plain` prints scalars bare so `$(roark ... --format plain)` is directly
+ * usable in a shell; anything with structure still has to be JSON.
+ */
+const plain = (value) => {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(plain).join('\n');
+    return JSON.stringify(value);
+};
+/**
+ * `auto` is JSON either way. What the TTY changes is presentation - indentation
+ * and colour - not the format, so a command's output stays parseable no matter
+ * where it runs and a script never has to pass a flag to get stable output.
+ */
+const resolveFormat = (requested) => requested === 'auto' ? 'json' : requested;
+exports.resolveFormat = resolveFormat;
+const render = (value, options) => {
+    const format = (0, exports.resolveFormat)(options.format);
+    if (format === 'plain')
+        return plain(value);
+    if (format === 'jsonl') {
+        const rows = Array.isArray(value) ? value : [value];
+        return rows.map((row) => JSON.stringify(row)).join('\n');
+    }
+    // `json` is pretty-printed when a human will read it and compact when a
+    // program will: indentation is noise to `jq` and structure to a person.
+    const humanReadable = options.color || (0, exports.isTty)(options.stream);
+    const json = humanReadable ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+    return options.color ? colorizeJson(json) : json;
+};
+exports.render = render;
+const write = (text, stream = process.stdout) => {
+    if (text.length === 0)
+        return;
+    stream.write(text.endsWith('\n') ? text : `${text}\n`);
+};
+exports.write = write;

package/runtime/program.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Builds the whole command tree from the generated table.
+ *
+ * Nothing here names an endpoint. Every command, positional and flag comes from
+ * `commands.ts`, so a new API operation reaches the CLI as a data change.
+ */
+import { Command } from 'commander';
+import { type ResolvedConfig } from './config';
+import { type OutputFormat } from './output';
+import type { CliCommand } from './types';
+export interface ProgramOptions {
+    binaryName: string;
+    version: string;
+    description: string;
+    commands: readonly CliCommand[];
+    /** Help text for the command groups, keyed by space-joined path. */
+    groups: Readonly<Record<string, string>>;
+    completions: Readonly<Record<string, string>>;
+}
+interface GlobalOptions {
+    baseUrl?: string;
+    timeout?: string;
+    maxRetries?: string;
+    token?: string;
+    format?: OutputFormat;
+    json?: boolean;
+    color?: boolean;
+    yes?: boolean;
+    input?: boolean;
+    quiet?: boolean;
+    data?: string;
+    allowProjectBaseUrl?: boolean;
+}
+/**
+ * Refuses the one combination that would post a secret to a host the caller did
+ * not choose. Nothing is sent first: this throws before the client exists.
+ */
+export declare const assertBaseUrlIsTrusted: (options: GlobalOptions, resolved: ResolvedConfig) => void;
+export declare const resolveOutput: (options: GlobalOptions) => {
+    format: OutputFormat;
+    color: boolean;
+};
+export declare const createProgram: (options: ProgramOptions) => Command;
+export declare const run: (options: ProgramOptions, argv: readonly string[]) => Promise<number>;
+export {};