@gravity-rail/cli 4.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/lib.d.ts CHANGED
@@ -259,6 +259,26 @@ interface ArgDef {
259
259
  * to `b` alone and report success, having never touched `a`.
260
260
  */
261
261
  repeatable?: boolean;
262
+ /**
263
+ * The value is a non-negative integer id. CRUD list handlers reject any other
264
+ * value and forward it as a number, so `0` reaches the API as `0`.
265
+ */
266
+ integer?: boolean;
267
+ /**
268
+ * The value names a scope the call acts in, not a record: a workspace or an
269
+ * organization. The Manager's approval gate reads it from the tool
270
+ * manifest and asks the member before a call that addresses a workspace
271
+ * other than the session's, or any organization. `false` declares that a
272
+ * flag spelled like one (`--org-role`) does not. The manifest generator
273
+ * refuses a `workspace` / `org` spelling that declares neither.
274
+ */
275
+ addresses?: 'workspace' | 'organization' | false;
276
+ /**
277
+ * The value is a local path the command writes. A call that sets it is a
278
+ * write to the Manager's gate, even on a command that otherwise reads.
279
+ * `false` declares that a flag spelled like one (`--output-device`) is not.
280
+ */
281
+ writesPath?: boolean;
262
282
  default?: string | boolean;
263
283
  }
264
284
  type ParsedArgs = Record<string, string | boolean | string[] | undefined>;
@@ -278,19 +298,73 @@ interface CommandHandlerContext {
278
298
  workspace: string;
279
299
  data?: unknown;
280
300
  }
301
+ /**
302
+ * What a command can do to state.
303
+ *
304
+ * - `read` changes nothing.
305
+ * - `write` creates, updates, sends, starts or otherwise changes something.
306
+ * - `destroy` deletes, revokes or overwrites something the product cannot
307
+ * restore. It is a write too, and the Manager never runs one without asking.
308
+ */
309
+ type CommandEffect = 'read' | 'write' | 'destroy';
310
+ /**
311
+ * What a command does, in one word. The Manager shows it as the call's label,
312
+ * and the verb decides the command's effect (`VERB_EFFECT`), so a command
313
+ * cannot be labelled "delete" and still run as a read.
314
+ *
315
+ * The Python mirror is `ActivityVerb` in `lib/ai/call_activity.py`. The
316
+ * generated manifest carries each command's verb and effect, and the Python
317
+ * reader refuses a manifest whose verb and effect disagree with its own map.
318
+ */
319
+ type ActivityVerb = 'find' | 'read' | 'analyze' | 'export' | 'create' | 'update' | 'send' | 'start' | 'import' | 'connect' | 'download' | 'delete' | 'revoke';
320
+ /** The effect each verb has. Exhaustive: a new verb must say what it does. */
321
+ declare const VERB_EFFECT: Readonly<Record<ActivityVerb, CommandEffect>>;
322
+ /** The effect a command declares through its verb. */
323
+ declare function commandEffect(cmd: Pick<CommandDef, 'verb'>): CommandEffect;
324
+ /** Whether a command changes state, and so needs `--allow-write` to run. */
325
+ declare function commandWrites(cmd: Pick<CommandDef, 'verb'>): boolean;
281
326
  interface CommandDef<T = unknown> {
282
327
  path: string[];
328
+ /** Closed display subject for commands outside a registered domain. */
329
+ subject?: ActivitySubject;
283
330
  description: string;
331
+ /**
332
+ * Unlisted: the command still resolves and runs, but `--help` listings, the
333
+ * generated tool manifest and the generated skill docs omit it. Direct
334
+ * `gr <path> --help` on the command itself still works.
335
+ */
336
+ hidden?: boolean;
284
337
  args?: ArgDef[];
285
338
  /** Example usage lines shown in command-level help */
286
339
  examples?: string[];
287
340
  requiresWorkspace?: boolean;
288
341
  requiresAuth?: boolean;
289
- /** Whether this command mutates data. Requires --allow-write to execute. */
290
- mutates?: boolean;
342
+ /**
343
+ * What the command does. Required on every command so a missing declaration
344
+ * cannot read as a read.
345
+ *
346
+ * A verb whose effect is not `read` needs `--allow-write` to run. This is a
347
+ * safety declaration, not a UX hint: the Manager's approval gate runs a
348
+ * read-verb command in Auto mode with no prompt, and never runs a
349
+ * destroy-verb one unasked. Use a write verb for anything that creates,
350
+ * updates, rotates, sends, triggers, starts, or calls out with side effects
351
+ * (a POST that only computes a preview or runs a read-only query is a read).
352
+ * Use `delete` or `revoke` when what the command removes cannot be restored
353
+ * in the product. When unsure, pick the stronger effect: a wrong write costs
354
+ * a prompt, a wrong read skips consent.
355
+ */
356
+ verb: ActivityVerb;
357
+ /**
358
+ * The command prints a credential (password, client secret, API key, token,
359
+ * magic link, presigned URL that grants access) to stdout. Required on every
360
+ * command, like `verb`, so a missing declaration cannot read as "no".
361
+ * The Manager's gate never runs a `revealsSecret: true` command without
362
+ * consent, even when its verb is a read. When unsure, use true.
363
+ */
364
+ revealsSecret: boolean;
291
365
  /**
292
366
  * true: read a JSON body from --data, --file or stdin even though the command
293
- * does not mutate. false: the command reads a dedicated binary/CSV file argument.
367
+ * is a read. false: the command reads a dedicated binary/CSV file argument.
294
368
  */
295
369
  acceptsJsonInput?: boolean;
296
370
  /**
@@ -303,8 +377,15 @@ interface CommandDef<T = unknown> {
303
377
  columns?: TableColumn<T>[];
304
378
  handler: (hctx: CommandHandlerContext) => Promise<void>;
305
379
  }
380
+ /** Closed display vocabulary; mirrored by Python ActivitySubject. */
381
+ declare const ACTIVITY_SUBJECTS: readonly ["abilities", "account_details", "access", "activity", "agents", "agent_tasks", "models", "apps", "integrations", "assignments", "billing", "bundles", "calendars", "calendar_events", "chats", "command_help", "commands", "forms", "documentation", "actions", "experiments", "features", "files", "folders", "inboxes", "interventions", "roles", "members", "metrics", "notifications", "organizations", "phone_numbers", "personas", "prompts", "pronunciations", "qualifications", "queries", "recordings", "reports", "routines", "sites", "subscriptions", "supervisors", "support", "toolkits", "workflows", "workspaces", "workspace_settings", "member_records", "labels", "tasks", "messages", "fields", "domains", "webhooks", "api_keys"];
382
+ type ActivitySubject = (typeof ACTIVITY_SUBJECTS)[number];
306
383
  interface DomainDef {
307
384
  name: string;
385
+ /** Display metadata for Manager labels; optional for internal-only domains. */
386
+ subject?: ActivitySubject;
387
+ /** Relative command prefixes whose subjects differ from the domain. */
388
+ commandSubjects?: Readonly<Record<string, ActivitySubject>>;
308
389
  description: string;
309
390
  commands: CommandDef[];
310
391
  }
@@ -481,6 +562,8 @@ interface CrudConfig<T = unknown> {
481
562
  requiresWorkspace?: boolean;
482
563
  listArgs?: ArgDef[];
483
564
  extra?: CommandDef[];
565
+ /** Example lines shown in help for the list command */
566
+ listExamples?: string[];
484
567
  /** Example lines shown in help for the create command */
485
568
  createExamples?: string[];
486
569
  /** Example lines shown in help for the update command */
@@ -613,8 +696,10 @@ declare class CommandRegistry {
613
696
  private getCommandHelp;
614
697
  /** All registered domains (for docs generation and introspection). */
615
698
  getDomains(): readonly DomainDef[];
616
- /** All registered commands (for docs generation and introspection). */
699
+ /** Every registered command, hidden ones included (safety checks, introspection). */
617
700
  getAllCommands(): CommandDef[];
701
+ /** Commands a reader is shown: hidden ones omitted (docs and manifest generation). */
702
+ getListedCommands(): CommandDef[];
618
703
  private getTopLevelHelp;
619
704
  }
620
705
 
@@ -765,5 +850,5 @@ declare function organizationsListCommand(ctx: AuthenticatedContext, options?: {
765
850
 
766
851
  declare function whoamiCommand(ctx: AuthenticatedContext): Promise<void>;
767
852
 
768
- export { AuthRequiredError, CLIError, COL, CommandRegistry, LIST_PAGINATION_ARGS, PAGINATION_ARGS, PIPED_INPUT_FIRST_BYTE_WAIT_MS, WORKSPACE_EXPORT_ZIP, authBrowserCommand, authImportDevCommand, authListCommand, authSwitchCommand, chatCommand, commandAwaitsPipedInput, commandNeedsJsonBody, conciergeCommand, conciergeOutboundCommand, confirmAccountPhoneVerify, createAuthenticatedContext, createConciergeChat, createContext, createPublicAuthenticatedContext, createPublicContext, crudCommands, describeOutboundCallReceipt, detectOutputFormat, devImportLocalCommand, extractPaginationMeta, fetchAllCursorPages, fetchAllPages, flushStdout, formatPaginationWarning, getConciergeChat, getConciergeChatMessages, getStartedCommand, handleError, hint, importDevProfiles, isCursorPaginatedResponse, isDirectoryTrusted, isLikelySeedPhoneNumber, isListResult, isPagePaginatedResponse, isPaginatedResponse, isWorkspaceExportZip, listConciergeChats, listResult, loginCommand, logoutCommand, manageCommand, organizationsListCommand, originateConciergeCall, originateConciergeSms, outputData, outputSingle, parseArgs, parseGlobalOptions, parsePaginationArgs, profilesFromDevRealms, readCommandJsonInput, readJsonInput, registerPublicDomains, requireAuth, requireDirectoryTrust, requireNumber, requireString, resolveVoicePhoneNumberId, simpleCrudCommands, startAccountPhoneVerify, stderr, topLevelCommands, unwrapItems, waitForOutboundPhoneCallOutcome, whoamiCommand };
769
- export type { ArgDef, AuthenticatedContext, CommandContext, CommandDef, CommandHandlerContext, ConciergeChat, ConciergeMessage, DomainDef, GlobalOptions, GlobalOptionsResult, GlobalOptionsSpec, OutputFormat, OutputOptions, PaginationMeta, ParsedArgs, ParsedGlobalOptions, PublicGlobalOptions, TableColumn, WorkspaceExportZipInput };
853
+ export { AuthRequiredError, CLIError, COL, CommandRegistry, LIST_PAGINATION_ARGS, PAGINATION_ARGS, PIPED_INPUT_FIRST_BYTE_WAIT_MS, VERB_EFFECT, WORKSPACE_EXPORT_ZIP, authBrowserCommand, authImportDevCommand, authListCommand, authSwitchCommand, chatCommand, commandAwaitsPipedInput, commandEffect, commandNeedsJsonBody, commandWrites, conciergeCommand, conciergeOutboundCommand, confirmAccountPhoneVerify, createAuthenticatedContext, createConciergeChat, createContext, createPublicAuthenticatedContext, createPublicContext, crudCommands, describeOutboundCallReceipt, detectOutputFormat, devImportLocalCommand, extractPaginationMeta, fetchAllCursorPages, fetchAllPages, flushStdout, formatPaginationWarning, getConciergeChat, getConciergeChatMessages, getStartedCommand, handleError, hint, importDevProfiles, isCursorPaginatedResponse, isDirectoryTrusted, isLikelySeedPhoneNumber, isListResult, isPagePaginatedResponse, isPaginatedResponse, isWorkspaceExportZip, listConciergeChats, listResult, loginCommand, logoutCommand, manageCommand, organizationsListCommand, originateConciergeCall, originateConciergeSms, outputData, outputSingle, parseArgs, parseGlobalOptions, parsePaginationArgs, profilesFromDevRealms, readCommandJsonInput, readJsonInput, registerPublicDomains, requireAuth, requireDirectoryTrust, requireNumber, requireString, resolveVoicePhoneNumberId, simpleCrudCommands, startAccountPhoneVerify, stderr, topLevelCommands, unwrapItems, waitForOutboundPhoneCallOutcome, whoamiCommand };
854
+ export type { ActivityVerb, ArgDef, AuthenticatedContext, CommandContext, CommandDef, CommandEffect, CommandHandlerContext, ConciergeChat, ConciergeMessage, DomainDef, GlobalOptions, GlobalOptionsResult, GlobalOptionsSpec, OutputFormat, OutputOptions, PaginationMeta, ParsedArgs, ParsedGlobalOptions, PublicGlobalOptions, TableColumn, WorkspaceExportZipInput };