@gravity-rail/cli 0.17.0 → 0.18.1

package/dist/lib.d.ts

@@ -89,6 +89,15 @@ declare function listResult(data: unknown, supportsAll?: boolean): ListResult;
 type OutputFormat = 'json' | 'jsonl' | 'table';
 interface OutputOptions {
     outputFormat: OutputFormat;
+    /**
+     * jq filter applied to the serialised JSON before it reaches stdout.
+     *
+     * Setting this implies JSON output regardless of `outputFormat`: a filter
+     * over a rendered table is meaningless, and silently filtering nothing is
+     * worse than ignoring the flag. See `lib/jq.ts` for why the filter lives
+     * here rather than in a shell pipe.
+     */
+    jq?: string;
 }
 interface TableColumn<T> {
     header: string;
@@ -138,6 +147,7 @@ interface GlobalOptions {
     /** Override API base URL (also: GRAVITY_RAIL_API_URL env var). */
     apiUrl?: string;
     outputFormat?: string;
+    jq?: string;
     verbose?: boolean;
     allowWrite?: boolean;
     /** Named credential profile (`--profile` / GRAVITY_RAIL_PROFILE). */
@@ -148,6 +158,7 @@ interface PublicGlobalOptions {
     apiUrl?: string;
     frontendUrl?: string;
     outputFormat?: string;
+    jq?: string;
     verbose?: boolean;
     allowWrite?: boolean;
     /** Named credential profile (`--profile` / GRAVITY_RAIL_PROFILE). */
@@ -157,6 +168,8 @@ interface CommandContext {
     env: string;
     envConfig: EnvironmentConfig;
     outputFormat: OutputFormat;
+    /** `--jq` filter, applied to JSON output. See `lib/jq.ts`. */
+    jq?: string;
     verbose: boolean;
     allowWrite: boolean;
     credentialsManager: CredentialsManager;
@@ -251,6 +264,63 @@ declare function requireNumber(args: ParsedArgs, key: string): number;
 declare const PAGINATION_ARGS: ArgDef[];
 declare function parseArgs(defs: ArgDef[], argv: string[]): ParsedArgs;
 
+/**
+ * The global-option parser both `gr` binaries share.
+ *
+ * `packages/cli` is canonical. `packages/gr-cli` is a developer-only build that
+ * layers extra domains and a few dev conveniences on top and is meant to change
+ * *nothing* about behaviour. That contract was not expressible while each entry
+ * point carried its own copy of this parser, and the copies had already drifted:
+ *
+ * - `--api-url=x` and `-o=json` (inline `=` form) worked in the developer build
+ *   and threw "Unknown flag" in the canonical one.
+ * - `--jq` had to be implemented twice (PR #23017), which is what surfaced the
+ *   duplication in the first place.
+ *
+ * Anything genuinely build-specific is passed in via {@link GlobalOptionsSpec}
+ * rather than forked here. If a future difference cannot be expressed as one of
+ * those knobs, that is the signal it does not belong in only one binary.
+ */
+interface ParsedGlobalOptions {
+    env: string;
+    profile?: string;
+    apiUrl?: string;
+    outputFormat?: string;
+    jq?: string;
+    verbose: boolean;
+    allowWrite: boolean;
+}
+interface GlobalOptionsSpec {
+    /**
+     * Default when `--env` is absent.
+     *
+     * The public CLI defaults to `prod` because public consumers cannot reach
+     * dev or staging (#15819); the developer build defaults to `dev`. This is a
+     * legitimate difference, which is exactly why it is a parameter.
+     */
+    defaultEnv: string;
+    /**
+     * Flags the build recognises and consumes itself, beyond the shared set.
+     *
+     * Return `true` to mean "handled, keep scanning"; the handler owns any side
+     * effect, including exiting. Return `false` for a flag you do not claim, and
+     * the shared parser continues as though the hook were absent.
+     *
+     * `readValue()` ADVANCES the scan when it consumes the following token, so
+     * calling it and then returning `false` would swallow an argument this hook
+     * never claimed. Decide on `flag` first; only read a value once you are
+     * committed to returning `true`. The parser cannot enforce that for you —
+     * it is why the rule is stated here rather than left to be discovered.
+     */
+    extraFlag?: (flag: string, readValue: () => string | undefined) => boolean;
+}
+interface GlobalOptionsResult {
+    opts: ParsedGlobalOptions;
+    commandWords: string[];
+    rest: string[];
+}
+declare function parseGlobalOptions(argv: string[], spec: GlobalOptionsSpec): GlobalOptionsResult;
+
 declare class CLIError extends Error {
     exitCode: number;
     constructor(message: string, exitCode?: number);
@@ -578,4 +648,4 @@ declare function organizationsListCommand(ctx: AuthenticatedContext): Promise<vo
 
 declare function whoamiCommand(ctx: AuthenticatedContext): Promise<void>;
 
-export { type ArgDef, AuthRequiredError, type AuthenticatedContext, CLIError, COL, type CommandContext, type CommandDef, type CommandHandlerContext, CommandRegistry, type ConciergeChat, type ConciergeMessage, type DomainDef, type GlobalOptions, LIST_PAGINATION_ARGS, type OutputFormat, type OutputOptions, PAGINATION_ARGS, type PaginationMeta, type ParsedArgs, type PublicGlobalOptions, type TableColumn, authBrowserCommand, authImportDevCommand, authListCommand, authSwitchCommand, chatCommand, commandNeedsJsonBody, conciergeCommand, conciergeOutboundCommand, confirmAccountPhoneVerify, createAuthenticatedContext, createConciergeChat, createContext, createPublicAuthenticatedContext, createPublicContext, crudCommands, detectOutputFormat, devImportLocalCommand, extractPaginationMeta, fetchAllCursorPages, fetchAllPages, formatPaginationWarning, getConciergeChat, getConciergeChatMessages, getStartedCommand, handleError, importDevProfiles, isCursorPaginatedResponse, isDirectoryTrusted, isLikelySeedPhoneNumber, isListResult, isPagePaginatedResponse, isPaginatedResponse, listConciergeChats, listResult, loginCommand, logoutCommand, manageCommand, organizationsListCommand, originateConciergeCall, originateConciergeSms, outputData, outputSingle, parseArgs, parsePaginationArgs, profilesFromDevRealms, readJsonInput, registerPublicDomains, requireAuth, requireDirectoryTrust, requireNumber, requireString, resolveVoicePhoneNumberId, simpleCrudCommands, startAccountPhoneVerify, stderr, topLevelCommands, unwrapItems, waitForOutboundPhoneCallOutcome, whoamiCommand };
+export { type ArgDef, AuthRequiredError, type AuthenticatedContext, CLIError, COL, type CommandContext, type CommandDef, type CommandHandlerContext, CommandRegistry, type ConciergeChat, type ConciergeMessage, type DomainDef, type GlobalOptions, type GlobalOptionsResult, type GlobalOptionsSpec, LIST_PAGINATION_ARGS, type OutputFormat, type OutputOptions, PAGINATION_ARGS, type PaginationMeta, type ParsedArgs, type ParsedGlobalOptions, type PublicGlobalOptions, type TableColumn, authBrowserCommand, authImportDevCommand, authListCommand, authSwitchCommand, chatCommand, commandNeedsJsonBody, conciergeCommand, conciergeOutboundCommand, confirmAccountPhoneVerify, createAuthenticatedContext, createConciergeChat, createContext, createPublicAuthenticatedContext, createPublicContext, crudCommands, detectOutputFormat, devImportLocalCommand, extractPaginationMeta, fetchAllCursorPages, fetchAllPages, formatPaginationWarning, getConciergeChat, getConciergeChatMessages, getStartedCommand, handleError, importDevProfiles, isCursorPaginatedResponse, isDirectoryTrusted, isLikelySeedPhoneNumber, isListResult, isPagePaginatedResponse, isPaginatedResponse, listConciergeChats, listResult, loginCommand, logoutCommand, manageCommand, organizationsListCommand, originateConciergeCall, originateConciergeSms, outputData, outputSingle, parseArgs, parseGlobalOptions, parsePaginationArgs, profilesFromDevRealms, readJsonInput, registerPublicDomains, requireAuth, requireDirectoryTrust, requireNumber, requireString, resolveVoicePhoneNumberId, simpleCrudCommands, startAccountPhoneVerify, stderr, topLevelCommands, unwrapItems, waitForOutboundPhoneCallOutcome, whoamiCommand };