@gravity-rail/cli 0.1.0 → 0.3.0

package/dist/lib.d.ts

@@ -0,0 +1,439 @@
+import { GravityRailClient } from '@gravity-rail/sdk';
+import { E as EnvironmentConfig, C as CredentialsManager } from './auth-DBspA1Dh.js';
+
+/** Metadata extracted from a paginated API response */
+interface PaginationMeta {
+    /** Total number of items across all pages (page-based only) */
+    total?: number;
+    /** Current page number (page-based only) */
+    page?: number;
+    /** Total pages (page-based only) */
+    totalPages?: number;
+    /** Whether more pages exist (cursor-based only) */
+    hasMore?: boolean;
+    /** Cursor for next page (cursor-based only) */
+    nextCursor?: string;
+}
+/** Explicit pagination contract passed from commands to outputData */
+interface ListResult {
+    items: unknown[];
+    meta?: PaginationMeta;
+    supportsAll?: boolean;
+}
+/** Type guard: is the value a ListResult (explicit contract)? */
+declare function isListResult(data: unknown): data is ListResult;
+/** Check if a response looks like a page-based paginated envelope.
+ *  Matches both `{ items, total, totalPages, page }` (standard) and
+ *  `{ items, total, page, pageSize }` (legacy — e.g. InvitationListResponse,
+ *  InquiryListResponse). This is a pure type guard with no side effects;
+ *  totalPages computation for legacy shapes happens in extractPaginationMeta. */
+declare function isPagePaginatedResponse(data: unknown): data is {
+    items: unknown[];
+    total: number;
+    page: number;
+    totalPages?: number;
+    pageSize?: number;
+};
+/** Check if a response looks like a cursor-based paginated envelope */
+declare function isCursorPaginatedResponse(data: unknown): data is {
+    items: unknown[];
+    hasMore: boolean;
+    nextCursor?: string;
+};
+/** Check if a response is any paginated envelope ({ items: [...], ... }) */
+declare function isPaginatedResponse(data: unknown): boolean;
+/** Extract pagination metadata from a response, or return undefined for non-paginated responses.
+ *  For legacy shapes without totalPages, computes it from total/pageSize. */
+declare function extractPaginationMeta(data: unknown): PaginationMeta | undefined;
+/** Format a pagination warning for stderr. Returns undefined if no warning needed.
+ *  When `supportsAll` is false, the "Use --all" hint is omitted because the
+ *  command does not actually expose the --all flag. */
+declare function formatPaginationWarning(meta: PaginationMeta | undefined, supportsAll?: boolean): string | undefined;
+/** Unwrap items from a paginated response or return the data as-is if it's an array */
+declare function unwrapItems(data: unknown): unknown[];
+/** Default pagination args for list commands (page, page-size, all). No search. */
+declare const LIST_PAGINATION_ARGS: ArgDef[];
+/** Convert parsed CLI args to API pagination options */
+declare function parsePaginationArgs(args: ParsedArgs): {
+    page?: number;
+    pageSize?: number;
+    all?: boolean;
+};
+/**
+ * Fetch all pages from a page-based paginated endpoint.
+ * The fetcher receives { page, pageSize } and should return the raw API response.
+ * Throws CLIError if MAX_PAGES is reached without exhausting all pages.
+ */
+declare function fetchAllPages(fetcher: (opts: {
+    page: number;
+    pageSize: number;
+}) => Promise<unknown>): Promise<unknown[]>;
+/**
+ * Fetch all pages from a cursor-based paginated endpoint.
+ * The fetcher receives { cursor? } and should return the raw API response.
+ * Throws CLIError if MAX_PAGES is reached without exhausting all pages.
+ */
+declare function fetchAllCursorPages(fetcher: (opts: {
+    cursor?: string;
+}) => Promise<unknown>): Promise<unknown[]>;
+/**
+ * Wrap a raw API response into a ListResult with explicit pagination metadata.
+ * Works with both page-based and cursor-based responses, as well as plain arrays.
+ *
+ * @param data - Raw API response (paginated envelope or plain array)
+ * @param supportsAll - Whether the calling command exposes --all
+ */
+declare function listResult(data: unknown, supportsAll?: boolean): ListResult;
+
+type OutputFormat = 'json' | 'jsonl' | 'table';
+interface OutputOptions {
+    outputFormat: OutputFormat;
+}
+interface TableColumn<T> {
+    header: string;
+    getValue: (item: T) => string;
+    maxWidth?: number;
+}
+/** Detect default output format based on whether stdout is a TTY */
+declare function detectOutputFormat(explicit?: string): OutputFormat;
+/**
+ * Write a list of items to stdout in the requested format.
+ *
+ * Accepts:
+ * - A `ListResult` (explicit contract with items, meta, supportsAll) — preferred.
+ * - Raw arrays, paginated responses ({ items: [...] }), or any object — legacy.
+ *
+ * When a `ListResult` is passed, its explicit `meta` and `supportsAll` are used.
+ * When raw data is passed, pagination metadata is auto-detected with
+ * `supportsAll: false` as the safe default.
+ *
+ * The optional `paginationMeta` and `supportsAll` parameters are kept for
+ * backward compatibility but are ignored when a `ListResult` is passed.
+ */
+declare function outputData(data: unknown, opts: OutputOptions, columns?: TableColumn<any>[], paginationMeta?: PaginationMeta, supportsAll?: boolean): void;
+/** Write a single object to stdout in the requested format */
+declare function outputSingle<T>(data: T, opts: OutputOptions, columns?: TableColumn<T>[]): void;
+/** Common column factory helpers for domain files */
+declare const COL: {
+    id: () => TableColumn<any>;
+    uuid: () => TableColumn<any>;
+    name: () => TableColumn<any>;
+    status: () => TableColumn<any>;
+    created: () => TableColumn<any>;
+    updated: () => TableColumn<any>;
+    description: () => TableColumn<any>;
+    enabled: () => TableColumn<any>;
+};
+/** Write a status/progress message to stderr (never pollutes stdout) */
+declare function stderr(msg: string): void;
+
+interface GlobalOptions {
+    env: string;
+    realm?: string;
+    outputFormat?: string;
+    verbose?: boolean;
+    allowWrite?: boolean;
+}
+interface PublicGlobalOptions {
+    apiUrl?: string;
+    frontendUrl?: string;
+    outputFormat?: string;
+    verbose?: boolean;
+    allowWrite?: boolean;
+}
+interface CommandContext {
+    env: string;
+    envConfig: EnvironmentConfig;
+    outputFormat: OutputFormat;
+    verbose: boolean;
+    allowWrite: boolean;
+    credentialsManager: CredentialsManager;
+}
+interface AuthenticatedContext extends CommandContext {
+    accessToken: string;
+    apiClient: GravityRailClient;
+    realmWorkspace?: string;
+}
+/** Create a base command context (no auth required) */
+declare function createContext(opts: GlobalOptions): CommandContext;
+/** Create an authenticated command context. Tries realm, env var, then cached token. Never auto-triggers OAuth. */
+declare function createAuthenticatedContext(opts: GlobalOptions): Promise<AuthenticatedContext>;
+/**
+ * Narrow a handler context to `AuthenticatedContext`.
+ *
+ * Handler `ctx` is typed as `AuthenticatedContext | CommandContext` so that
+ * `requiresAuth: false` handlers can also share the type. At runtime, every
+ * handler that did not opt out of auth will receive an `AuthenticatedContext`,
+ * but TypeScript cannot verify this — call this helper before accessing
+ * `apiClient` / `accessToken`.
+ *
+ * Throws if called from a handler that did not declare `requiresAuth`.
+ */
+declare function requireAuth(ctx: AuthenticatedContext | CommandContext): AuthenticatedContext;
+/** Create a base command context for the public CLI (no --env flag, defaults to prod) */
+declare function createPublicContext(opts: PublicGlobalOptions): CommandContext;
+/** Create an authenticated context for the public CLI. Tries env var, then cached token. */
+declare function createPublicAuthenticatedContext(opts: PublicGlobalOptions): Promise<AuthenticatedContext>;
+
+interface ArgDef {
+    name: string;
+    alias?: string;
+    /** Additional long-form aliases (e.g. ['workspace-id', 'id'] for --wid) */
+    aliases?: string[];
+    description: string;
+    required?: boolean;
+    isFlag?: boolean;
+    default?: string | boolean;
+}
+type ParsedArgs = Record<string, string | boolean | undefined>;
+/**
+ * Context passed to a command handler.
+ *
+ * `ctx` is a discriminated union of `AuthenticatedContext` and `CommandContext`.
+ * Handlers registered without `requiresAuth: false` always receive an
+ * `AuthenticatedContext` at runtime, but the type does not express this — call
+ * `requireAuth(hctx.ctx)` before accessing `apiClient` / `accessToken` so that
+ * a handler missing `requiresAuth: false` cannot silently access undefined
+ * fields if it is later miswired.
+ */
+interface CommandHandlerContext {
+    ctx: AuthenticatedContext | CommandContext;
+    args: ParsedArgs;
+    workspace: string;
+    data?: unknown;
+}
+interface CommandDef<T = unknown> {
+    path: string[];
+    description: string;
+    args?: ArgDef[];
+    /** Example usage lines shown in command-level help */
+    examples?: string[];
+    requiresWorkspace?: boolean;
+    requiresAuth?: boolean;
+    /** Whether this command mutates data. Requires --allow-write to execute. */
+    mutates?: boolean;
+    columns?: TableColumn<T>[];
+    handler: (hctx: CommandHandlerContext) => Promise<void>;
+}
+interface DomainDef {
+    name: string;
+    description: string;
+    commands: CommandDef[];
+}
+/** Extract a required string arg, throwing if missing or not a string */
+declare function requireString(args: ParsedArgs, key: string): string;
+/** Extract a required numeric arg, throwing if missing */
+declare function requireNumber(args: ParsedArgs, key: string): number;
+
+/** Standard pagination args used by admin list commands (includes search).
+ *  @deprecated Use LIST_PAGINATION_ARGS (page/page-size/all only) plus domain-specific filter args instead. */
+declare const PAGINATION_ARGS: ArgDef[];
+declare function parseArgs(defs: ArgDef[], argv: string[]): ParsedArgs;
+
+declare class CLIError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+declare class AuthRequiredError extends CLIError {
+    constructor(message?: string);
+}
+declare function handleError(err: unknown): never;
+
+/** Read JSON input from --data string, --file path, or stdin (if piped) */
+declare function readJsonInput(args: ParsedArgs): Promise<unknown | undefined>;
+
+/**
+ * @deprecated Use `SimpleCrudConfig` with `simpleCrudCommands()` for new code.
+ *
+ * This interface uses string method names that are resolved at runtime via
+ * dynamic dispatch, which prevents TypeScript from validating call signatures.
+ * It is safe for simple top-level CRUD resources but must NOT be used for
+ * nested resources that require parent IDs.
+ */
+interface CrudConfig<T = unknown> {
+    prefix: string[];
+    entityName: string;
+    listMethod?: string;
+    getMethod?: string;
+    createMethod?: string;
+    updateMethod?: string;
+    deleteMethod?: string;
+    archiveMethod?: string;
+    unarchiveMethod?: string;
+    /** When true, adds a --cascade flag to the delete command. Only enable for entities whose backend endpoint accepts a cascade parameter. */
+    supportsCascade?: boolean;
+    columns?: TableColumn<T>[];
+    requiresWorkspace?: boolean;
+    listArgs?: ArgDef[];
+    extra?: CommandDef[];
+    /** Example lines shown in help for the create command */
+    createExamples?: string[];
+    /**
+     * Controls how the CRUD list handler interacts with pagination.
+     *
+     * - `'full'`  — The client method accepts an options object with page/pageSize.
+     *               Pagination args (--page, --page-size, --all) are injected and
+     *               forwarded to the API method via `callApiWithOptions`.
+     * - `'client-only'` — Pagination args are injected for --all support (client-side
+     *               page-walking), but options are NOT forwarded to the API method.
+     *               Use for raw-array endpoints that don't accept page/pageSize.
+     * - `false`   — No pagination args are injected. The list method is called with
+     *               `callApi` (workspace-only) or `callApiWithOptions` for domain
+     *               listArgs only. Use for legacy/positional signatures where passing
+     *               an options object would be misinterpreted.
+     *
+     * Default: `false` (safe — never forwards pagination options unless opted in).
+     */
+    paginationSupport?: 'full' | 'client-only' | false;
+}
+/**
+ * @deprecated Use `simpleCrudCommands()` for new code — it provides compile-time
+ * safety via typed callables instead of string method names.
+ *
+ * Existing usages are safe for simple top-level CRUD resources. Do NOT use this
+ * for nested resources that require parent IDs (workflowId, memberId, toolkitId, etc.).
+ */
+declare function crudCommands<T>(config: CrudConfig<T>): CommandDef[];
+/**
+ * Typed CRUD config for simple, top-level resources.
+ *
+ * Unlike the stringly-typed `CrudConfig`, operations are typed functions that
+ * receive the real `GravityRailClient`. TypeScript validates the call at the definition
+ * site, eliminating the string-dispatch + positional-argument blind spot.
+ *
+ * Use this for resources that fit the simple CRUD contract:
+ * - optional workspace scope
+ * - single resource ID (no parent IDs)
+ * - optional list-options object
+ *
+ * For nested resources that need parent IDs, use explicit handlers.
+ *
+ * @example
+ * ```ts
+ * simpleCrudCommands({
+ *    prefix: ['tasks'],
+ *    entityName: 'task',
+ *    list: (client, wid) => client.getTasks(wid),
+ *    get: (client, wid, id) => client.getTask(wid, id),
+ *    create: (client, wid, data) => client.createTask(wid, data),
+ *    update: (client, wid, id, data) => client.updateTask(wid, id, data),
+ *    delete: (client, wid, id) => client.deleteTask(wid, id),
+ * })
+ * ```
+ */
+interface SimpleCrudConfig<T = unknown> {
+    prefix: string[];
+    entityName: string;
+    columns?: TableColumn<T>[];
+    requiresWorkspace?: boolean;
+    listArgs?: ArgDef[];
+    extra?: CommandDef[];
+    createExamples?: string[];
+    paginationSupport?: 'full' | 'client-only' | false;
+    list?: (client: GravityRailClient, workspace: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    get?: (client: GravityRailClient, workspace: string, id: string) => Promise<unknown>;
+    create?: (client: GravityRailClient, workspace: string, data: unknown) => Promise<unknown>;
+    update?: (client: GravityRailClient, workspace: string, id: string, data: unknown) => Promise<unknown>;
+    delete?: (client: GravityRailClient, workspace: string, id: string) => Promise<unknown>;
+    archive?: (client: GravityRailClient, workspace: string, id: string) => Promise<unknown>;
+    unarchive?: (client: GravityRailClient, workspace: string, id: string) => Promise<unknown>;
+    /** When true, adds a --cascade flag to the delete command. */
+    supportsCascade?: boolean;
+    deleteFn?: (client: GravityRailClient, workspace: string, id: string, cascade: boolean) => Promise<unknown>;
+}
+/**
+ * Generate CRUD commands from typed callable functions.
+ *
+ * This is the recommended path for new simple CRUD domains. It provides
+ * compile-time safety by accepting typed callables instead of string method names.
+ */
+declare function simpleCrudCommands<T>(config: SimpleCrudConfig<T>): CommandDef[];
+
+declare class CommandRegistry {
+    private commands;
+    private domains;
+    register(domain: DomainDef): void;
+    registerCommand(cmd: CommandDef): void;
+    /** Resolve command words to a CommandDef using longest-match.
+     *  Supports {param} path segments that match any word and extract as pathParams. */
+    resolve(words: string[]): {
+        cmd: CommandDef;
+        rest: string[];
+        pathParams: Record<string, string>;
+    } | undefined;
+    /** Generate help text. If prefix given, show commands under that prefix. */
+    getHelp(prefix?: string[]): string;
+    private getCommandHelp;
+    private getTopLevelHelp;
+}
+
+/**
+ * Register the full set of public CLI domains on a registry.
+ *
+ * This file intentionally does NOT import any admin or infrastructure domains
+ * (deploy, rollback, railgun, admin/*). Those live in `@gravity-rail/gr-cli`
+ * and are layered on top via its own `registerAllDomains`.
+ */
+declare function registerPublicDomains(registry: CommandRegistry): void;
+
+/**
+ * Concierge API client — direct HTTP calls to the global concierge endpoints.
+ *
+ * The concierge is account-level (no workspace), so these bypass the ApiClient
+ * which is workspace-oriented.
+ */
+
+interface ConciergeChat {
+    id: number;
+    uuid: string;
+    chatType: string;
+    title: string | null;
+    threadId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ConciergeMessage {
+    id: string;
+    role: string;
+    content: string;
+    createdAt: string | null;
+    toolCalls: any[] | null;
+    toolCallId: string | null;
+}
+declare function listConciergeChats(ctx: AuthenticatedContext): Promise<ConciergeChat[]>;
+declare function createConciergeChat(ctx: AuthenticatedContext, title?: string): Promise<ConciergeChat>;
+declare function getConciergeChat(ctx: AuthenticatedContext, chatId: number): Promise<ConciergeChat>;
+declare function getConciergeChatMessages(ctx: AuthenticatedContext, chatId: number): Promise<ConciergeMessage[]>;
+
+/**
+ * Open an authenticated browser session using the CLI's existing credentials.
+ *
+ * Flow:
+ * 1. Get the current account's email from the CLI session
+ * 2. Request a magic link via the API (token returned directly since caller is authenticated)
+ * 3. Open the magic link URL in the default browser (or print it with --no-open)
+ */
+declare function authBrowserCommand(ctx: AuthenticatedContext, args: Record<string, unknown>): Promise<void>;
+
+/**
+ * Concierge chat command — interactive chat with the global concierge agent.
+ *
+ * Supports the same modes as workspace manager chat (text, realtime, voice)
+ * but without requiring a workspace.
+ */
+
+declare function conciergeCommand(hctx: CommandHandlerContext): Promise<void>;
+
+declare function devImportLocalCommand(ctx: AuthenticatedContext, workspace: string): Promise<void>;
+
+declare function loginCommand(ctx: CommandContext): Promise<void>;
+declare function logoutCommand(ctx: CommandContext): Promise<void>;
+
+declare function manageCommand(hctx: CommandHandlerContext): Promise<void>;
+declare function chatCommand(hctx: CommandHandlerContext): Promise<void>;
+
+declare function organizationsListCommand(ctx: AuthenticatedContext): Promise<void>;
+
+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, chatCommand, conciergeCommand, createAuthenticatedContext, createConciergeChat, createContext, createPublicAuthenticatedContext, createPublicContext, crudCommands, detectOutputFormat, devImportLocalCommand, extractPaginationMeta, fetchAllCursorPages, fetchAllPages, formatPaginationWarning, getConciergeChat, getConciergeChatMessages, handleError, isCursorPaginatedResponse, isListResult, isPagePaginatedResponse, isPaginatedResponse, listConciergeChats, listResult, loginCommand, logoutCommand, manageCommand, organizationsListCommand, outputData, outputSingle, parseArgs, parsePaginationArgs, readJsonInput, registerPublicDomains, requireAuth, requireNumber, requireString, simpleCrudCommands, stderr, unwrapItems, whoamiCommand };