Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 112 lines 4.89 KB
Raw
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 );