bdy 1.25.13-dev → 1.25.14-dev

package/distTs/src/discovery.js

@@ -6,6 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.discoverCommands = exports.describeCommand = void 0;
 const cliCommand_1 = __importDefault(require("./cliCommand"));
 const texts_1 = require("./texts");
+// An option defined identically on at least this many commands is described
+// once in shared_options and referenced by key from each command. --format
+// always stays in options: its choices are where json and jsonl get mixed up.
+const SHARED_OPTION_MIN_USES = 20;
 const sortedChildren = (command) => command
     .createHelp()
     .visibleCommands(command)
@@ -15,6 +19,14 @@ const sortedChildren = (command) => command
 const commandPath = (command) => command.parent
     ? `${commandPath(command.parent)} ${command.name()}`
     : command.name() || 'bdy';
+// Drops null, false, empty-string and empty-array fields: absent means "not set" and keeps
+// the catalog small. required_scopes is built outside this, since null there
+// means "undocumented".
+const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, field]) => field !== null &&
+    field !== undefined &&
+    field !== false &&
+    field !== '' &&
+    !(Array.isArray(field) && field.length === 0)));
 const optionInfo = (option) => {
     const value = option.flags.match(/[<[]([^>\]]+)[>\]]/)?.[1] ?? null;
     // These are static documentation, never resolved values from opts(), env or config.
@@ -27,59 +39,162 @@ const optionInfo = (option) => {
             /^[A-Za-z][A-Za-z0-9_-]*(?:\|[A-Za-z][A-Za-z0-9_-]*)+$/.test(value)
             ? value.split('|')
             : null);
-    return {
+    return compact({
         flags: option.flags,
         short: option.short ?? null,
         long: option.long ?? null,
         description: option.description,
         required: option.mandatory,
         value: value
-            ? {
+            ? compact({
                 name: value,
                 required: option.required,
                 variadic: !!option.variadic,
-            }
+            })
             : null,
         negated: option.negate,
         choices,
         default: option.defaultValue ?? null,
         documented_default: documentedDefault,
         env,
+    });
+};
+const globalOptions = (program) => program.createHelp().visibleOptions(program).map(optionInfo);
+// Options of a command as shown in its help, minus --help and the options
+// every command inherits from global_options.
+const localOptions = (command, globals) => command
+    .createHelp()
+    .visibleOptions(command)
+    .filter((option) => option.long !== '--help')
+    .map(optionInfo)
+    .filter((info) => !globals.has(JSON.stringify(info)));
+const allCommands = (command) => [
+    command,
+    ...sortedChildren(command).flatMap(allCommands),
+];
+// Stable keys for options repeated across the whole tree: the long name, plus
+// a counter for other variants of the same option with a different description.
+const buildSharedOptions = (program, globals) => {
+    const uses = new Map();
+    for (const command of allCommands(program).slice(1)) {
+        for (const info of localOptions(command, globals)) {
+            const key = JSON.stringify(info);
+            const entry = uses.get(key) ?? { info, count: 0 };
+            entry.count += 1;
+            uses.set(key, entry);
+        }
+    }
+    const frequent = [...uses.entries()]
+        .filter(([, { info, count }]) => count >= SHARED_OPTION_MIN_USES && info.long !== '--format')
+        .sort(([a, x], [b, y]) => y.count - x.count || (a < b ? -1 : 1));
+    const keys = new Map();
+    const taken = new Set();
+    for (const [json, { info }] of frequent) {
+        const base = (info.long ?? info.short ?? info.flags ?? '').replace(/^-+/, '');
+        let key = base;
+        for (let n = 2; taken.has(key); n += 1)
+            key = `${base}-${n}`;
+        taken.add(key);
+        keys.set(json, key);
+    }
+    return keys;
+};
+const splitOptions = (command, catalog) => {
+    const own = [];
+    const shared = [];
+    for (const info of localOptions(command, catalog.globals)) {
+        const key = catalog.shared?.get(JSON.stringify(info));
+        if (key)
+            shared.push(key);
+        else
+            own.push(info);
+    }
+    return { own, shared };
+};
+const requiredScopes = (command) => command instanceof cliCommand_1.default ? command.requiredScopes : null;
+const examplesOf = (command) => command instanceof cliCommand_1.default ? command.examples : [];
+const commandDetails = (command, catalog) => {
+    const { own, shared } = splitOptions(command, catalog);
+    return {
+        ...compact({
+            command: commandPath(command),
+            aliases: command.aliases(),
+            description: command.description(),
+            usage: `${commandPath(command)} ${command.usage()}`.trim(),
+            arguments: command.registeredArguments.map((argument) => compact({
+                name: argument.name(),
+                description: argument.description,
+                required: argument.required,
+                variadic: argument.variadic,
+                choices: argument.argChoices ?? null,
+                default: argument.defaultValue ?? null,
+            })),
+            options: own,
+            shared_options: shared,
+        }),
+        required_scopes: requiredScopes(command),
+        ...compact({ examples: examplesOf(command) }),
     };
 };
-const describeCommand = (command) => ({
-    command: commandPath(command),
-    aliases: command.aliases(),
-    description: command.description(),
-    usage: `${commandPath(command)} ${command.usage()}`.trim(),
-    arguments: command.registeredArguments.map((argument) => ({
-        name: argument.name(),
-        description: argument.description,
-        required: argument.required,
-        variadic: argument.variadic,
-        choices: argument.argChoices ?? null,
-        default: argument.defaultValue ?? null,
-    })),
-    options: command
-        .createHelp()
-        .visibleOptions(command)
-        .filter((option) => option.long !== '--help')
-        .map(optionInfo),
-    required_scopes: command instanceof cliCommand_1.default ? command.requiredScopes : null,
-    examples: command instanceof cliCommand_1.default ? command.examples : [],
-});
+/** Full details of one command, self-contained: no shared_options references. */
+const describeCommand = (command) => {
+    let root = command;
+    while (root.parent)
+        root = root.parent;
+    // a detached command has no root of its own: use the options every
+    // CliCommand gets
+    const globals = globalOptions(root === command ? new cliCommand_1.default('bdy') : root)
+        .map((info) => JSON.stringify(info));
+    return commandDetails(command, { globals: new Set(globals) });
+};
 exports.describeCommand = describeCommand;
-const describeTree = (command) => ({
-    ...(0, exports.describeCommand)(command),
-    subcommands: sortedChildren(command).map(describeTree),
+const describeTree = (command, catalog) => ({
+    ...commandDetails(command, catalog),
+    ...compact({
+        subcommands: sortedChildren(command).map((child) => describeTree(child, catalog)),
+    }),
 });
-const summarizeTree = (command) => [
-    {
-        command: commandPath(command),
-        description: command.description(),
-    },
-    ...sortedChildren(command).flatMap(summarizeTree),
-];
+// Index entry: enough to call a leaf command without a second lookup. Groups
+// carry only their name and description.
+const summarize = (command, catalog) => {
+    if (sortedChildren(command).length)
+        return compact({
+            command: commandPath(command),
+            aliases: command.aliases(),
+            description: command.description(),
+        });
+    const { own, shared } = splitOptions(command, catalog);
+    return {
+        ...compact({
+            command: commandPath(command),
+            aliases: command.aliases(),
+            description: command.description(),
+            usage: `${commandPath(command)} ${command.usage()}`.trim(),
+            arguments: command.registeredArguments.map((argument) => compact({
+                name: argument.name(),
+                required: argument.required,
+                variadic: argument.variadic,
+            })),
+            options: own.map((info) => info.flags),
+            shared_options: shared,
+        }),
+        required_scopes: requiredScopes(command),
+        ...compact({ examples: examplesOf(command).length || null }),
+    };
+};
+const referencedShared = (commands, shared) => {
+    const used = new Set();
+    const visit = (list) => {
+        for (const command of list) {
+            command.shared_options?.forEach((key) => used.add(key));
+            if (command.subcommands)
+                visit(command.subcommands);
+        }
+    };
+    visit(commands);
+    const byKey = new Map([...shared].map(([json, key]) => [key, json]));
+    return Object.fromEntries([...used].sort().map((key) => [key, JSON.parse(byKey.get(key))]));
+};
 const discoverCommands = (program, path, version, full = false) => {
     let selected = program;
     const selectedPath = [];
@@ -96,23 +211,27 @@ const discoverCommands = (program, path, version, full = false) => {
         selected = child;
         selectedPath.push(child.name());
     }
-    const commands = selected === program ? sortedChildren(program) : [selected];
-    const includeDetails = full || (selected !== program && sortedChildren(selected).length === 0);
+    const roots = selected === program ? sortedChildren(program) : [selected];
+    const global_options = globalOptions(program);
+    const globals = new Set(global_options.map((info) => JSON.stringify(info)));
+    const single = selected !== program && sortedChildren(selected).length === 0;
+    const header = { schema_version: 1, cli_version: version, global_options };
+    // A single selected command is returned self-contained, options inlined.
+    if (single)
+        return {
+            ...header,
+            commands: [commandDetails(selected, { globals })],
+            tips: texts_1.DISCOVERY_TIPS,
+        };
+    const shared = buildSharedOptions(program, globals);
+    const catalog = { globals, shared };
+    const commands = full
+        ? roots.map((command) => describeTree(command, catalog))
+        : roots.flatMap(allCommands).map((command) => summarize(command, catalog));
     return {
-        schema_version: 1,
-        cli_version: version,
-        // Root flags must precede the subcommand; keep them separate from local options.
-        ...(includeDetails
-            ? {
-                global_options: program
-                    .createHelp()
-                    .visibleOptions(program)
-                    .map(optionInfo),
-            }
-            : {}),
-        commands: includeDetails
-            ? commands.map(describeTree)
-            : commands.flatMap(summarizeTree),
+        ...header,
+        shared_options: referencedShared(commands, shared),
+        commands,
         tips: texts_1.DISCOVERY_TIPS,
     };
 };

package/distTs/src/input.js

@@ -588,20 +588,20 @@ class Input {
         }
         if (filters.pr) {
             if (!/^(?:pull\/)?[1-9]\d*$/.test(filters.pr))
-                throw new cliError_1.default('usage_error', (0, texts_1.ERR_PIPELINE_RUN_FIND_FILTER)('--pr'));
+                throw new cliError_1.default('usage_error', texts_1.ERR_PIPELINE_RUN_FIND_PR);
             filters.pr = 'pull/' + filters.pr.replace(/^pull\//, '');
         }
         if (filters.status) {
             filters.status = filters.status.toUpperCase();
             if (!Object.values(pipeline_1.PIPELINE_RUN_STATUS).includes(filters.status))
-                throw new cliError_1.default('usage_error', (0, texts_1.ERR_PIPELINE_RUN_FIND_FILTER)('--status'));
+                throw new cliError_1.default('usage_error', (0, texts_1.ERR_PIPELINE_RUN_FIND_STATUS)(Object.values(pipeline_1.PIPELINE_RUN_STATUS)));
         }
         if (filters.artifact?.includes(':')) {
             const separator = filters.artifact.indexOf(':');
             const version = filters.artifact.slice(separator + 1);
             const identifier = filters.artifact.slice(0, separator);
             if (!identifier.trim() || !version.trim())
-                throw new cliError_1.default('usage_error', (0, texts_1.ERR_PIPELINE_RUN_FIND_FILTER)('--artifact'));
+                throw new cliError_1.default('usage_error', texts_1.ERR_PIPELINE_RUN_FIND_ARTIFACT);
         }
         return { last, filters };
     }
@@ -1408,14 +1408,14 @@ class Input {
         // A nonexistent project is rejected by the API client
         // (getResourceByIdentifier); here only the environment itself can miss.
         if (!resolved.environment_id) {
-            output_1.default.exitError(texts_1.ERR_ENVIRONMENT_NOT_FOUND);
+            output_1.default.exitError(new cliError_1.default('not_found', texts_1.ERR_ENVIRONMENT_NOT_FOUND, texts_1.HINT_ENVIRONMENT_LIST));
         }
         if (strictProject && options.project) {
             const environment = await client.getEnvironment(workspace, resolved.environment_id);
             // a workspace environment carries no project, so this also fails the
             // workspace-fallback case
             if (environment.project?.name !== resolved.project_identifier) {
-                output_1.default.exitError(texts_1.ERR_ENVIRONMENT_NOT_FOUND);
+                output_1.default.exitError(new cliError_1.default('not_found', texts_1.ERR_ENVIRONMENT_NOT_FOUND, texts_1.HINT_ENVIRONMENT_LIST));
             }
         }
         return resolved.environment_id;
@@ -1436,7 +1436,7 @@ class Input {
             sandboxId = await client.findSandboxByIdentifier(workspace, identifier, project, environmentId);
         }
         if (!sandboxId) {
-            throw new cliError_1.default('not_found', texts_1.ERR_SANDBOX_NOT_FOUND);
+            throw new cliError_1.default('not_found', texts_1.ERR_SANDBOX_NOT_FOUND, texts_1.HINT_SANDBOX_LIST);
         }
         return sandboxId;
     }

package/distTs/src/output.js

@@ -59,7 +59,18 @@ class Output {
     static launchBrowser(url) {
         return require('open').default(url);
     }
-    static async openUrl(url) {
+    // Ends a command whose text result is a single success line: with
+    // --format json the payload takes that line's place on stdout.
+    static exitResult(json, data, msg) {
+        if (json) {
+            this.json(data);
+            this.exitNormal();
+        }
+        if (msg)
+            this.exitSuccess(msg);
+        this.exitNormal();
+    }
+    static async openUrl(url, json = false) {
         let parsed;
         try {
             parsed = new URL(url || '');
@@ -71,7 +82,10 @@ class Output {
             throw new cliError_1.default('not_found', texts_1.ERR_RESOURCE_BROWSER_URL_MISSING);
         }
         const browserUrl = parsed.toString();
-        this.data(browserUrl);
+        if (json)
+            this.json({ url: browserUrl });
+        else
+            this.data(browserUrl);
         try {
             await this.launchBrowser(browserUrl);
         }
@@ -405,8 +419,16 @@ class Output {
     static isTTY() {
         return this.isStdInTTY() && this.isStdOutTTY();
     }
-    static tunnel(tunnel) {
-        if (this.isTTY())
+    static tunnelJsonl(tunnel) {
+        this.killSpinner();
+        const OutputJsonlTunnel = require('./tunnel/output/noninteractive/tunnelJsonl').default;
+        const on = new OutputJsonlTunnel(getTerminal(), tunnel);
+        on.start();
+    }
+    static tunnel(tunnel, jsonl = false) {
+        if (jsonl)
+            this.tunnelJsonl(tunnel);
+        else if (this.isTTY())
             this.tunnelInteractive(tunnel);
         else
             this.tunnelNonInteractive(tunnel);
@@ -464,6 +486,31 @@ class Output {
         }
         return await this.confirm(message, quiet);
     }
+    // With --format json/jsonl stdout carries only the result, so prompts and
+    // the answers echoed without a TTY go to stderr instead.
+    static get promptsToStderr() {
+        return this.errorFormat !== 'text';
+    }
+    static promptContext(signal) {
+        return {
+            ...(signal ? { signal } : {}),
+            ...(this.promptsToStderr ? { output: process.stderr } : {}),
+        };
+    }
+    // Non-interactive stand-in for a prompt: shows the question and the answer
+    // taken without asking.
+    static promptEcho(message, answer) {
+        if (this.promptsToStderr) {
+            this.writeStderr(`? ${message}${answer ? ` ${answer}` : ''}`);
+            return;
+        }
+        this.cyan('? ', false);
+        this.normal(message, false);
+        if (answer)
+            this.cyan(` ${answer}`);
+        else
+            this.normal('');
+    }
     static async confirm(message = 'Are you sure?', quiet = false) {
         if (this.isStdInTTY()) {
             const prompts = require('@inquirer/prompts');
@@ -472,17 +519,21 @@ class Output {
                     message,
                     theme: this.getInquirerTheme(),
                     default: false,
-                }, quiet ? { output: process.stderr } : undefined);
+                }, quiet ? { output: process.stderr } : this.promptContext());
             }
             catch {
                 this.exitError(texts_1.ERR_CANCELLED);
             }
         }
-        if (!quiet) {
-            this.cyan('? ', false);
-            this.label(message, false);
-            this.cyan(` No`);
+        if (quiet)
+            return false;
+        if (this.promptsToStderr) {
+            this.promptEcho(message, 'No');
+            return false;
         }
+        this.cyan('? ', false);
+        this.label(message, false);
+        this.cyan(` No`);
         return false;
     }
     static async inputString(message, def, required, signal) {
@@ -495,7 +546,7 @@ class Output {
                     message,
                     default: def,
                     theme: this.getInquirerTheme(),
-                }, { signal });
+                }, this.promptContext(signal));
                 this.inlineOutput = true;
                 return value;
             }
@@ -506,14 +557,8 @@ class Output {
                 this.exitError(texts_1.ERR_CANCELLED);
             }
         }
-        this.cyan('? ', false);
-        this.normal(message, false);
-        if (def) {
-            this.cyan(` ${def}`);
-            return def;
-        }
-        this.normal('');
-        return '';
+        this.promptEcho(message, def);
+        return def || '';
     }
     static async inputMenuAdv(message, items) {
         const prompts = require('@inquirer/prompts');
@@ -524,21 +569,19 @@ class Output {
                     theme: this.getInquirerTheme(),
                     loop: false,
                     choices: items,
-                });
+                }, this.promptContext());
             }
             catch {
                 this.exitError(texts_1.ERR_CANCELLED);
             }
         }
         else {
-            this.cyan('? ', false);
-            this.normal(message, false);
             const item = items.find((item) => !prompts.Separator.isSeparator(item) && !item.disabled);
             if (item && item.name && item.value) {
-                this.cyan(` ${item.name}`);
+                this.promptEcho(message, item.name);
                 return item.value;
             }
-            this.normal('');
+            this.promptEcho(message);
             return '';
         }
     }
@@ -594,20 +637,18 @@ class Output {
                         });
                         return result;
                     },
-                });
+                }, this.promptContext());
             }
             catch {
                 this.exitError(texts_1.ERR_CANCELLED);
             }
         }
         else {
-            this.cyan('? ', false);
-            this.normal(message, false);
             if (items.length > 0) {
-                this.cyan(` ${items[0]}`);
+                this.promptEcho(message, items[0]);
                 return 0;
             }
-            this.normal('');
+            this.promptEcho(message);
             return -1;
         }
     }
@@ -620,20 +661,18 @@ class Output {
                     theme: this.getInquirerTheme(),
                     loop: false,
                     choices: items.map((item, index) => ({ value: index, name: item })),
-                });
+                }, this.promptContext());
             }
             catch {
                 this.exitError(texts_1.ERR_CANCELLED);
             }
         }
         else {
-            this.cyan('? ', false);
-            this.normal(message, false);
             if (items.length > 0) {
-                this.cyan(` ${items[0]}`);
+                this.promptEcho(message, items[0]);
                 return 0;
             }
-            this.normal('');
+            this.promptEcho(message);
             return -1;
         }
     }