Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | /** |
| 2 | * Command registrations: how a group gives each subcommand its identity (command path and |
| 3 | * `CommandMeta`) and how the command the parser selected records it. See |
| 4 | * `src/invocation/command-identity.ts` and `docs/adr/0001-command-identity-after-parse.md`. |
| 5 | * |
| 6 | * `effect/cli` runs a selected command's handler inside every provider of the groups above it, |
| 7 | * outermost first, and runs a group's own handler only when no subcommand was selected (pinned by |
| 8 | * `test/src/commands/registration.test.ts`). So each registration provides its identity around |
| 9 | * its whole dispatch, and `CommandInvocation.begin` wraps only handlers: a leaf's when its group |
| 10 | * registers it, a group's own one when the group registers its subcommands. |
| 11 | */ |
| 12 | import { Effect, Option } from 'effect'; |
| 13 | import { Command } from 'effect/cli'; |
| 14 | import type { CommandInputError, NotLoggedInError } from 'src/commands/errors'; |
| 15 | import { type CommandSurface, rejectUnsupportedSharedFlags } from 'src/commands/surface'; |
| 16 | import { assertLoggedIn } from 'src/effects/require-auth'; |
| 17 | import { |
| 18 | childIdentity, |
| 19 | CommandInvocation, |
| 20 | CommandRegistration, |
| 21 | } from 'src/invocation/command-identity'; |
| 22 | import type { ComposioUserContext } from 'src/services/user-context'; |
| 23 | |
| 24 | /** |
| 25 | * Records the running registration as the command this invocation runs, with the input |
| 26 | * `effect/cli` parsed for it (none for a group that only shows its help, so, like `--help`, it |
| 27 | * runs no invocation hook), then enforces what its `CommandMeta` requires: a shared flag it cannot |
| 28 | * honor, then a login. Both fail after the identity is recorded, so the failure is reported |
| 29 | * against the command the user ran, even when a group above it declared the requirement. |
| 30 | */ |
| 31 | const beginSelected = (input: Option.Option<unknown>) => |
| 32 | Effect.gen(function* () { |
| 33 | const identity = yield* CommandRegistration; |
| 34 | const invocation = yield* CommandInvocation; |
| 35 | yield* invocation.begin(identity, input); |
| 36 | yield* rejectUnsupportedSharedFlags(identity); |
| 37 | if (identity.meta.requiresLogin) { |
| 38 | yield* assertLoggedIn; |
| 39 | } |
| 40 | }); |
| 41 | |
| 42 | /** |
| 43 | * A command as a group registers it: its handler may now fail with `NotLoggedInError` or a |
| 44 | * rejected shared flag's `CommandInputError`. |
| 45 | */ |
| 46 | export type Registered<C> = |
| 47 | C extends Command.Command<infer Name, infer Input, infer ContextInput, infer E, infer R> |
| 48 | ? Command.Command< |
| 49 | Name, |
| 50 | Input, |
| 51 | ContextInput, |
| 52 | E | NotLoggedInError | CommandInputError, |
| 53 | R | ComposioUserContext | CommandSurface |
| 54 | > |
| 55 | : never; |
| 56 | |
| 57 | /** |
| 58 | * Registers `child` under the registration whose dispatch runs it. A group (a command with |
| 59 | * subcommands) begins its own handler in `withRegisteredSubcommands`. |
| 60 | */ |
| 61 | const registerSubcommand = <C extends Command.Command.Any>(child: C): Registered<C> => { |
| 62 | const command = child as unknown as Command.Command<string, unknown, unknown, unknown, unknown>; |
| 63 | const begun = |
| 64 | command.subcommands.length === 0 |
| 65 | ? Command.provideEffectDiscard(command, (input: unknown) => beginSelected(Option.some(input))) |
| 66 | : command; |
| 67 | return Command.provideEffect( |
| 68 | begun, |
| 69 | CommandRegistration, |
| 70 | Effect.gen(function* () { |
| 71 | const identity = childIdentity(yield* CommandRegistration, command); |
| 72 | const invocation = yield* CommandInvocation; |
| 73 | yield* invocation.enter(identity); |
| 74 | return identity; |
| 75 | }) |
| 76 | ) as unknown as Registered<C>; |
| 77 | }; |
| 78 | |
| 79 | /** What a group declares about its own handler, the one that runs when no subcommand is selected. */ |
| 80 | export interface GroupOptions { |
| 81 | /** |
| 82 | * Whether that handler is an action of its own (`composio dev --mode on`, `composio setup`) |
| 83 | * rather than the group's help. Off by default: a group made without a handler shows the help |
| 84 | * `effect/cli` prints for it, and the root shows its overview. Only an action runs the |
| 85 | * invocation hooks; help, like `--help`, runs none. `effect/cli` does not expose whether a |
| 86 | * command has a handler, so the group says so here. |
| 87 | */ |
| 88 | readonly ownAction?: boolean; |
| 89 | } |
| 90 | |
| 91 | /** |
| 92 | * `Command.withSubcommands` for the command tree: registers each subcommand under `self` with |
| 93 | * its own identity, and begins `self`'s own handler when no subcommand is selected: as the |
| 94 | * selected command with its input when it is an action (`GroupOptions.ownAction`), else as the |
| 95 | * group's help. Every group in the tree registers its subcommands with it. |
| 96 | */ |
| 97 | export const withRegisteredSubcommands = |
| 98 | <const Subcommands extends ReadonlyArray<Command.Command.Any>>( |
| 99 | subcommands: Subcommands, |
| 100 | options: GroupOptions = {} |
| 101 | ) => |
| 102 | <const Name extends string, Input, ContextInput, E, R>( |
| 103 | self: Command.Command<Name, Input, ContextInput, E, R> |
| 104 | ) => |
| 105 | Command.withSubcommands( |
| 106 | Command.provideEffectDiscard(self, (input: Input) => |
| 107 | beginSelected(options.ownAction === true ? Option.some(input) : Option.none()) |
| 108 | ), |
| 109 | subcommands.map(child => |
| 110 | registerSubcommand<Subcommands[number]>(child) |
| 111 | ) satisfies ReadonlyArray<Registered<Subcommands[number]>> |
| 112 | ); |