@roarkanalytics/cli 0.1.0

package/runtime/program.js

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = exports.createProgram = exports.resolveOutput = exports.assertBaseUrlIsTrusted = void 0;
+const commander_1 = require("commander");
+const sdk_1 = __importDefault(require("@roarkanalytics/sdk"));
+const api_1 = require("./commands/api");
+const auth_1 = require("./commands/auth");
+const config_1 = require("./commands/config");
+const completion_1 = require("./commands/completion");
+const confirm_1 = require("./confirm");
+const config_2 = require("./config");
+const errors_1 = require("./errors");
+const input_1 = require("./input");
+const output_1 = require("./output");
+/** Verbs whose effect a user cannot undo, so they get a confirmation prompt. */
+const DESTRUCTIVE_VERBS = new Set(['delete']);
+const isDestructive = (command) => DESTRUCTIVE_VERBS.has(command.commandPath.at(-1) ?? '');
+/**
+ * Global flags are declared on every leaf as well as the root so they can be
+ * written on either side of the verb. Commander does not inherit options down
+ * the tree, and `roark call list --json` is what a user will type.
+ *
+ * The execution flags are added per command rather than everywhere: a `--data`
+ * on a GET with no body, or a `--yes` on a command that never prompts, is help
+ * text that describes something the command will not do.
+ */
+const addGlobalOptions = (command, extra) => {
+    command
+        .option('--base-url <url>', 'API base URL')
+        .option('--token <token>', 'bearer token (prefer ROARK_API_BEARER_TOKEN or `auth login`)')
+        .option('--timeout <ms>', 'request timeout in milliseconds')
+        .option('--max-retries <count>', 'retries for retryable failures')
+        .addOption(new commander_1.Option('--format <format>', 'output format').choices(output_1.OUTPUT_FORMATS).default('auto'))
+        .option('--json', 'shorthand for --format json')
+        .option('--no-color', 'disable colour')
+        .option('-q, --quiet', 'suppress non-essential output')
+        .option('--allow-project-base-url', `send your credential to a base URL set by a ${config_2.PROJECT_FILE}`);
+    if (extra.body) {
+        command.option('--data <json>', 'request body as JSON, or @file to read one (@- for stdin)');
+    }
+    if (extra.confirmation) {
+        command
+            .option('-y, --yes', 'skip confirmation prompts')
+            .option('--no-input', 'never prompt; fail instead');
+    }
+    return command;
+};
+/**
+ * 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.
+ */
+const assertBaseUrlIsTrusted = (options, resolved) => {
+    if (options.allowProjectBaseUrl === true || (0, config_2.allowProjectBaseUrlFromEnvironment)())
+        return;
+    const redirect = (0, config_2.unsafeBaseUrlRedirect)(resolved);
+    if (redirect === undefined)
+        return;
+    const origin = redirect.credentialFrom === 'environment' ? 'ROARK_API_BEARER_TOKEN' : (0, config_2.userConfigPath)();
+    throw new errors_1.UsageError([
+        `Refusing to send your credential to ${redirect.baseURL}.`,
+        '',
+        `${redirect.projectFile} sets baseURL, and a ${config_2.PROJECT_FILE} is not necessarily yours: it`,
+        `arrives with a clone. The credential that would be sent came from ${origin}.`,
+        '',
+        'Pass --allow-project-base-url if you trust that file, or --token to send a',
+        'different credential.',
+    ].join('\n'));
+};
+exports.assertBaseUrlIsTrusted = assertBaseUrlIsTrusted;
+const clientFor = (options, requiresAuth = true) => {
+    const overrides = {
+        ...(options.token === undefined ? {} : { bearerToken: options.token }),
+        ...(options.baseUrl === undefined ? {} : { baseURL: options.baseUrl }),
+        ...(options.timeout === undefined ? {} : { timeout: Number(options.timeout) }),
+        ...(options.maxRetries === undefined ? {} : { maxRetries: Number(options.maxRetries) }),
+    };
+    const resolved = (0, config_2.resolveConfig)(overrides);
+    (0, exports.assertBaseUrlIsTrusted)(options, resolved);
+    const config = resolved.config;
+    if (config.bearerToken === undefined && requiresAuth) {
+        throw new errors_1.AuthRequiredError('No credential found. Run `roark auth login`, set ROARK_API_BEARER_TOKEN, or pass --token.');
+    }
+    return new sdk_1.default({
+        // The SDK constructor rejects an absent token, so a public endpoint is given
+        // an empty one rather than being made to demand a credential it never sends.
+        bearerToken: config.bearerToken ?? '',
+        ...(config.baseURL === undefined ? {} : { baseURL: config.baseURL }),
+        ...(config.timeout === undefined ? {} : { timeout: config.timeout }),
+        ...(config.maxRetries === undefined ? {} : { maxRetries: config.maxRetries }),
+    });
+};
+const resolveOutput = (options) => ({
+    format: options.json ? 'json' : options.format ?? 'auto',
+    // `--no-color` sets color to false; otherwise defer to the environment.
+    color: options.color === false ? false : (0, output_1.supportsColor)(),
+});
+exports.resolveOutput = resolveOutput;
+const flagSpec = (flag) => {
+    if (flag.valueKind === 'boolean')
+        return `--${flag.name}`;
+    return `--${flag.name} <value>`;
+};
+const flagDescription = (flag) => {
+    const parts = [];
+    if (flag.description)
+        parts.push(flag.description.replace(/\s+/g, ' ').trim());
+    if (flag.enumValues && flag.enumValues.length > 0) {
+        parts.push(`(one of: ${flag.enumValues.join(', ')})`);
+    }
+    if (flag.repeatable)
+        parts.push('(repeatable)');
+    if (flag.required)
+        parts.push('(required)');
+    return parts.join(' ');
+};
+/** Explains a union body, which has no flags to document. */
+const variantHelp = (command, binaryName) => {
+    if (!command.bodyOpaque)
+        return '';
+    const name = command.commandPath.join(' ');
+    const lines = [
+        '',
+        'This endpoint takes one of several request shapes, so it is supplied as JSON:',
+        '',
+        `  ${binaryName} ${name} --data '{ ... }'`,
+        `  ${binaryName} ${name} --data @request.json`,
+        `  cat request.json | ${binaryName} ${name}`,
+        '',
+    ];
+    if (command.bodyVariants.length > 0) {
+        lines.push('Accepted shapes:');
+        for (const variant of command.bodyVariants) {
+            const required = variant.required.length > 0 ? variant.required.join(', ') : 'no required fields';
+            lines.push(`  ${variant.name} - requires ${required}`);
+        }
+    }
+    return lines.join('\n');
+};
+/** Finds or creates the parent command for a path, so groups are built once. */
+const ensureGroup = (root, path, groups) => {
+    let parent = root;
+    const walked = [];
+    for (const segment of path) {
+        walked.push(segment);
+        const existing = parent.commands.find((child) => child.name() === segment);
+        if (existing) {
+            parent = existing;
+            continue;
+        }
+        const key = walked.join(' ');
+        const group = new commander_1.Command(segment)
+            .description(Object.prototype.hasOwnProperty.call(groups, key) ? groups[key] : `Commands for ${key}`)
+            .showHelpAfterError();
+        // A group with no action prints its own help rather than exiting silently.
+        group.action(() => {
+            group.outputHelp();
+            process.exitCode = errors_1.EXIT.usage;
+        });
+        parent.addCommand(group);
+        parent = group;
+    }
+    return parent;
+};
+const addApiCommand = (root, options, definition) => {
+    const parent = ensureGroup(root, definition.commandPath.slice(0, -1), options.groups);
+    const name = definition.commandPath.at(-1);
+    const command = new commander_1.Command(name)
+        .description(definition.summary ?? definition.description ?? '')
+        .showHelpAfterError();
+    if (definition.description && definition.description !== definition.summary) {
+        command.addHelpText('after', `\n${definition.description.replace(/\s+/g, ' ').trim()}`);
+    }
+    command.addHelpText('after', variantHelp(definition, options.binaryName));
+    command.addHelpText('after', `\n${definition.httpMethod.toUpperCase()} ${definition.httpPath}`);
+    for (const positional of definition.positionals) {
+        command.argument(`<${positional.name}>`, positional.description ?? '');
+    }
+    for (const flag of definition.flags) {
+        const option = new commander_1.Option(flagSpec(flag), flagDescription(flag));
+        if (flag.repeatable) {
+            option.argParser((value, previous) => [...(previous ?? []), value]);
+        }
+        command.addOption(option);
+    }
+    addGlobalOptions(command, {
+        body: definition.acceptsBody,
+        confirmation: isDestructive(definition),
+    });
+    command.action(async (...actionArgs) => {
+        // Commander passes positionals, then the options object, then the Command.
+        const positionals = actionArgs.slice(0, definition.positionals.length);
+        const options_ = actionArgs[definition.positionals.length];
+        await runApiCommand(definition, positionals, options_, options);
+    });
+    parent.addCommand(command);
+};
+const runApiCommand = async (definition, positionals, options, program) => {
+    const output = (0, exports.resolveOutput)(options);
+    if (isDestructive(definition)) {
+        await (0, confirm_1.confirm)(`Permanently delete ${positionals.join(' ') || definition.commandPath.join(' ')}?`, {
+            assumeYes: options.yes === true,
+            noInput: options.input === false,
+        });
+    }
+    // stdin is only consulted when the command can actually take a body and no
+    // explicit --data was given, so piping into a read command is never silently
+    // swallowed.
+    const explicitData = options.data === undefined ? undefined : (0, input_1.readData)(options.data);
+    const piped = definition.acceptsBody && explicitData === undefined && (0, input_1.stdinIsPiped)() ?
+        (() => {
+            const raw = (0, input_1.readStdin)().trim();
+            return raw.length === 0 ? undefined : JSON.parse(raw);
+        })()
+        : undefined;
+    const args = (0, input_1.buildArgs)({
+        command: definition,
+        positionals,
+        options,
+        ...(explicitData === undefined ? {} : { data: explicitData }),
+        ...(piped === undefined ? {} : { stdin: piped }),
+    });
+    const client = clientFor(options, definition.requiresAuth);
+    const resource = client[definition.clientProperty];
+    const method = resource?.[definition.methodName];
+    if (typeof method !== 'function') {
+        // Only reachable if the table and the installed SDK disagree, which means
+        // the two packages were published out of step.
+        throw new Error(`${program.binaryName}: ${definition.clientProperty}.${definition.methodName} is missing from @roarkanalytics/sdk`);
+    }
+    const result = await method.apply(resource, args);
+    if (options.quiet === true)
+        return;
+    (0, output_1.write)((0, output_1.render)(result, output));
+};
+const createProgram = (options) => {
+    const root = new commander_1.Command()
+        .name(options.binaryName)
+        .description(options.description)
+        .version(options.version, '-v, --version')
+        .showHelpAfterError()
+        .enablePositionalOptions();
+    addGlobalOptions(root, { body: false, confirmation: false });
+    for (const definition of options.commands)
+        addApiCommand(root, options, definition);
+    (0, auth_1.registerAuthCommands)(root, options.binaryName);
+    (0, config_1.registerConfigCommands)(root, options.binaryName);
+    (0, api_1.registerApiCommand)(root, options.binaryName, clientFor, exports.resolveOutput);
+    (0, completion_1.registerCompletionCommand)(root, options.binaryName, options.completions);
+    root.addHelpText('after', [
+        '',
+        'Environment:',
+        '  ROARK_API_BEARER_TOKEN   bearer token used when --token is not given',
+        '  ROARK_BASE_URL           API base URL',
+        `  ROARK_ALLOW_PROJECT_BASE_URL   trust a base URL set by a ${config_2.PROJECT_FILE}`,
+        '  NO_COLOR                 disable colour',
+        '',
+        `Run \`${options.binaryName} <command> --help\` for the flags of a single command.`,
+    ].join('\n'));
+    return root;
+};
+exports.createProgram = createProgram;
+/**
+ * `exitOverride` is per command, not inherited. Without walking the tree, a
+ * subcommand's parse error calls `process.exit` itself and never reaches the
+ * handler below, so `roark call retrieve` exited 1 instead of 2.
+ */
+const overrideExitEverywhere = (command) => {
+    command.exitOverride();
+    for (const child of command.commands)
+        overrideExitEverywhere(child);
+};
+const run = async (options, argv) => {
+    const program = (0, exports.createProgram)(options);
+    overrideExitEverywhere(program);
+    try {
+        await program.parseAsync(argv);
+        return process.exitCode === undefined ? errors_1.EXIT.ok : Number(process.exitCode);
+    }
+    catch (error) {
+        // Commander throws for --help and --version too; those are successful exits.
+        const code = error.code;
+        if (code === 'commander.helpDisplayed' || code === 'commander.help')
+            return errors_1.EXIT.ok;
+        if (code === 'commander.version')
+            return errors_1.EXIT.ok;
+        if (typeof code === 'string' && code.startsWith('commander.')) {
+            const message = error.message;
+            if (message)
+                (0, output_1.write)((0, output_1.paint)(`error: ${message}`, 'red', (0, output_1.supportsColor)(process.stderr)), process.stderr);
+            return errors_1.EXIT.usage;
+        }
+        (0, errors_1.reportError)(error, { ...(0, exports.resolveOutput)({}), binaryName: options.binaryName });
+        return (0, errors_1.exitCodeFor)(error);
+    }
+};
+exports.run = run;

package/runtime/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The contract between the generated command table and this runtime.
+ *
+ * `src/commands.ts` is generated from the OpenAPI spec by app-agent-codegen and
+ * contains nothing but data in these shapes. Everything in `src/runtime/` is
+ * hand-maintained and holds no per-endpoint knowledge, so adding an endpoint is
+ * a data change and never a code change.
+ */
+export type CliValueKind = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+export interface CliPositional {
+    /** As shown in usage, e.g. `call-id`. */
+    name: string;
+    /** Wire name of the path parameter, e.g. `callId`. */
+    paramKey: string;
+    description?: string;
+}
+export interface CliFlag {
+    /** As typed, without the leading dashes. Dotted for a nested leaf. */
+    name: string;
+    /** Where the value lands in the params object, e.g. `['metadata', 'source']`. */
+    path: string[];
+    location: 'query' | 'body' | 'path';
+    required: boolean;
+    description?: string;
+    valueKind: CliValueKind;
+    enumValues?: string[];
+    /** `--tag a --tag b` accumulates into an array. */
+    repeatable?: boolean;
+}
+export interface CliBodyVariant {
+    name: string;
+    required: string[];
+}
+export interface CliCommand {
+    commandPath: string[];
+    clientProperty: string;
+    methodName: string;
+    httpMethod: string;
+    httpPath: string;
+    summary?: string;
+    description?: string;
+    /** All path params in path order. The last is the SDK's positional argument. */
+    positionals: CliPositional[];
+    flags: CliFlag[];
+    hasParams: boolean;
+    paramsAllOptional: boolean;
+    /** The body is a union: reachable only through `--data` or stdin. */
+    bodyOpaque: boolean;
+    bodyVariants: CliBodyVariant[];
+    acceptsBody: boolean;
+    /** False where the operation declares `security: []`, e.g. the health check. */
+    requiresAuth: boolean;
+}

package/runtime/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * The contract between the generated command table and this runtime.
+ *
+ * `src/commands.ts` is generated from the OpenAPI spec by app-agent-codegen and
+ * contains nothing but data in these shapes. Everything in `src/runtime/` is
+ * hand-maintained and holds no per-endpoint knowledge, so adding an endpoint is
+ * a data change and never a code change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "2.31.0";

package/version.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.version = void 0;
+// Bumped by hand, together with `version` in package.json. This package is not
+// in release-please-config.json's `extra-files`: the CLI ships from
+// publish-cli.yml rather than the vendor's release train, so no tooling rewrites
+// this line.
+exports.version = '2.31.0';