@devries-cameron20 / composio-1 / commits / 8b02915d7
Fork 0

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

refactor(cli): derive the command path from the parsed command tree (#5134)

This PR: - builds on top of https://github.com/ComposioHQ/composio/pull/5132 - records which command runs after `effect/cli` parsed argv: every group registers its subcommands with `withRegisteredSubcommands` (`src/commands/registration.ts`), which provides each registration's identity (command path + `CommandMeta`) around its dispatch; only the selected handler calls `CommandInvocation.begin` (`src/invocation/command-identity.ts`), which reports the invoked event - `--help` / `--version` (`Help` / `Version` action wrappers) and parse failures (`CliError.ShowHelp.commandPath`, canonical names only, `failure_reason_code: "parse_error"`) begin the command `effect/cli` names - `requireLogin` now declares `requiresLogin` in `CommandMeta`, checked right after `begin`, so `NotLoggedInError` from a group-gated command (`tools`, `connections`, `dev toolkits`, …) is reported against the command the user ran; call sites are unchanged - deletes `KNOWN_COMMAND_TOKENS`, the `is*Command` family matchers and the execute value-flag list from `src/analytics/events.ts`; families are declared on root registrations (`dev` commands stay generic); execute's tool slug, search's query, link's toolkit and proxy's endpoint come from the parsed input; `run`'s run id is minted at `begin` (`CliRunId` and the pre-parse bootstrap are gone) - adds a contract test pinning effect/cli 4.0.5 handler composition (`test/src/commands/registration.test.ts`: nested providers, aliases, bare groups with and without a handler, root shortcuts, reused registrations, group-level login and guards, parse failures, `--help`/`--version`), and a characterization test over all 154 command paths against the frozen before table (`test/src/invocation/command-identity.before.ts`) - ships ADR 0001 (`docs/adr/0001-command-identity-after-parse.md`, version wording fixed to 4.0.5), linked from `AGENTS.md` ## Context Command paths whose recording changed (all were misattributed before; every other path and family is byte-identical): - `signup`, `agent`, `agent signup|login|whoami|claim|inbox`, `connections`, `connections list|remove`, `config`, `config experimental`, `debug`, `debug generate-graph|api-info|who-is-my-master`: were `composio` - `dev init`: was `dev` - `setup skill`: was `setup` with `CLI_SETUP_*`; now `setup skill` with `CLI_COMMAND_*` - `help` and every `help <command>` (77 paths): were `composio` Other telemetry differences: `--help` and parse-failure events of execute/search/link/proxy carry no slug/query/toolkit/endpoint (nothing was parsed); the generic `CLI_COMMAND_FAILED` gains `failure_reason_code` when there is one. Known gap, fixed in a follow-up PR: the `dev logs`, `dev projects` and `dev auth-configs` groups reject shared flags with a group-level guard that runs before the subcommand is reached, so such a rejection is recorded against the group (`dev logs`, not `dev logs tools`). Manual check (`COMPOSIO_CLI_TELEMETRY_DEBUG=1`, isolated `COMPOSIO_CACHE_DIR`, logged out, PostHog pointed at a dead local endpoint): | Invocation | Exit | Events | `command_path` | Notes | | --- | --- | --- | --- | --- | | `signup --help` | 0 | `CLI_COMMAND_INVOKED`/`SUCCEEDED` | `signup` (was `composio`) | | | `connections list` | 1 | `CLI_COMMAND_INVOKED`/`FAILED` | `connections list` (was `composio`) | `NotLoggedInError` | | `dev triggers list` | 1 | `CLI_COMMAND_INVOKED`/`FAILED` | `dev triggers list` | missing toolkit, `parse_error` | | `link gmail` | 1 | `CLI_LINK_INVOKED`/`FAILED` | `link` | `toolkit: gmail`, `NotLoggedInError` | | `dve` | 1 | `CLI_COMMAND_INVOKED`/`FAILED` | `composio` | `parse_error`, no `dve` in properties | | `--version` | 0 | `CLI_COMMAND_INVOKED`/`SUCCEEDED` | `composio` | | | `execute GMAIL_SEND_EMAIL` | 1 | `CLI_EXECUTE_INVOKED`/`FAILED` | `execute` | `tool_slug` from parsed input | | `dev connected-accounts link gmail` | 1 | `CLI_COMMAND_INVOKED`/`FAILED` | `dev connected-accounts link` | generic family, as before | Verification: `pnpm typecheck`, `pnpm --filter @composio/cli run lint:effect`, `pnpm --filter @composio/cli test` (220 files, 2817 passed, 1 skipped), `./node_modules/.bin/oxlint ts/packages/cli` (no errors). ## Telemetry property changes Both accepted: - `--help` and parse-failure events no longer carry execute's tool slug, search's query, link's toolkit or proxy's endpoint: these come from the parsed input now, and nothing is parsed in those cases. - Generic failed events (`CLI_COMMAND_FAILED`) gain `failure_reason_code` when there is one. --------- Co-authored-by: Vinayak Agarwal <vinayak@composio.dev> Co-authored-by: manobhisriram <manobhisriram@gmail.com>

Alberto Schiabel committed Oct 28, 2026 at 17:40 UTC 8b02915d793a1ca054f5d4595ec855029e827675
41 files changed +1435 -396
ts/packages/cli/AGENTS.md
+6 -3
@@ -31,6 +31,8 @@ Signals belong to the runner, the one place that installs SIGINT, SIGTERM and SI
31
32 Errors are captured via the custom `effect-errors/` module (source-mapped stack traces, Effect span timelines, formatted output).
33
34 +The invocation learns which command it runs after `effect/cli` parsed argv, never from argv itself ([ADR 0001](docs/adr/0001-command-identity-after-parse.md)). A command's identity (`src/invocation/command-identity.ts`) is its command registration: the command path from the root plus the `CommandMeta` it declares (one `Command.annotate` key, set with `withCommandMeta`: the lifecycle `telemetryFamily`, and `requiresLogin`, which `requireLogin` sets and subcommands inherit). Every group registers its subcommands with `withRegisteredSubcommands` (`src/commands/registration.ts`), which provides each registration's identity around its dispatch; only the selected command's handler calls `CommandInvocation.begin`, which reports the invoked event, then checks a required login. `--help` and `--version` (the `Help` and `Version` actions in `root-help.ts`) and a parse failure (`CliError.ShowHelp.commandPath`, canonical names only, `failure_reason_code: "parse_error"`) begin the command `effect/cli` names. `test/src/commands/registration.test.ts` pins the handler composition order this relies on. Telemetry families are declared on root registrations in `src/commands/index.ts`; `dev` commands report the generic family.
35 +
36 ### Commands — `src/commands/`
37
38 Each command uses `effect/cli`'s `Command.make()` pattern. Current top-level commands:
@@ -75,7 +77,7 @@ src/commands/
77 $default.cmd.ts root command: shared flags and description
78 errors.ts CommandInputError, the one usage error every command raises
79 surface.ts CommandSurface: the tree a command runs in, the dev group's shared flags, the acting user
78 - <group>/<group>.cmd.ts group entry: Command.make(name) + withSubcommands, nothing else
80 + <group>/<group>.cmd.ts group entry: Command.make(name) + withRegisteredSubcommands, nothing else
81 <group>/<name>/<group>.<name>.cmd.ts flags, arguments, description, examples, Command.make
82 <group>/<name>/<group>.<name>.handler.ts (params) => Effect; imports nothing from effect/cli
83 <group>/<name>/<group>.<name>.format.ts human renderer (stderr) and machine renderer (stdout)
@@ -91,7 +93,8 @@ Rules:
93 - A command that exists in both the root tree and the `dev` tree is defined once. The group supplies what differs between the two surfaces through `Command.withSharedFlags` and `Command.provide`, not through a second `Command.make` with a copied description. `--user-id` and `--project-name` are shared flags of the `dev` group (`dev.cmd.ts`), accepted before or after the subcommand name and documented once on every `dev` page; a handler reads them, and the tree it runs in, from `CommandSurface` (`surface.ts`) and never declares either flag itself, since `withSharedFlags` rejects a duplicate on a direct subcommand. A `dev` command that cannot honor one of them yet (it cannot target another project, or it does not act for a user) pipes `rejectsSharedFlags` (`surface.ts`), and the `dev` group's own `--mode` toggle calls `rejectSharedFlags`, so the flag fails with a `CommandInputError` instead of being ignored. `execute` and `playground-execute` keep two registrations because their names differ; they share one handler.
94 - A handler that acts as a user gets it, and the project it was resolved against, from `actingUser` (fails with `MissingActingUserError`, an expected failure whose message fits the tree) or `actingUserOption` (for a command that also runs without one) in `surface.ts`; both name a fallback test user on stderr. A handler never reads `--user-id` or a test user id to resolve one itself, never prints that notice, and lets `MissingActingUserError` through instead of wrapping it in its own error (its tag is the `error_name` telemetry reports). An empty consumer user id counts as none. A `--user-id` that only filters results (`dev logs`, `dev triggers listen`, `dev connected-accounts list`) stays a raw flag.
95 - Logic shared across groups belongs in `src/effects/` or `src/services/`, never in another command's directory.
94 -- A command that needs a logged-in user pipes `requireLogin` (`src/effects/require-auth.ts`) on itself or on its group entry, after `Command.withSubcommands`. Handlers never check `apiKey` or print a login hint; a missing login fails with `NotLoggedInError` and exits 1. Project context comes from `resolveCommandProject`, which fails with `ProjectResolutionError`; never flatten it into a plain `Error`.
96 +- A group registers its subcommands with `withRegisteredSubcommands` (`src/commands/registration.ts`), never `Command.withSubcommands`, so each subcommand gets its command identity.
97 +- A command that needs a logged-in user pipes `requireLogin` (`src/effects/require-auth.ts`) on itself or on its group entry; it declares `requiresLogin` in `CommandMeta`, which the selected command checks right after recording its identity. Handlers never check `apiKey` or print a login hint; a missing login fails with `NotLoggedInError` and exits 1. Project context comes from `resolveCommandProject`, which fails with `ProjectResolutionError`; never flatten it into a plain `Error`.
98 - A group entry is recognised by its place in the tree: `<dir>/<dir>.cmd.ts` or `<dir>/root-<dir>.cmd.ts` with other `.cmd.ts` files below `<dir>/`. The same name with nothing below it (`logout/logout.cmd.ts`) is a top-level command. Every command needs a test; a group entry does not, though one with a default action (`generate`) still gets one.
99
100 Legacy shape still present while commands migrate: `<group>/commands/<group>.<name>.cmd.ts` holding flags, handler, helpers, and errors in one file, and top-level `<name>.cmd.ts` doing the same. Migrate a command to the directory shape when you touch it for more than a one-line fix, one command per PR.
@@ -125,7 +128,7 @@ test/src/commands/<group>/<shared-module>.test.ts group helper
128 | `BackendMismatchWarning` | Warns before a command when an env var sends the stored key to a backend other than its issuer |
129 | `UpdateNotice` | Prints the cached "update available" hint before a command, except `upgrade` |
130 | `PluginHint` | Prints the Composio agent plugin hint under Claude Code or Codex, at most once a day |
128 -| `CommandLifecycleTelemetry` | Tracks the running command's invoked, succeeded, and failed events |
131 +| `CommandLifecycleTelemetry` | Tracks the running command's invoked (once it began), succeeded, and failed events |
132
133 Every Composio API request goes through an Effect client from `@composio/client/effect`, obtained from `ComposioClientSingleton` (`src/services/composio-clients.ts`). Clients are built with `make`, which never reads the ambient environment: the user key and base URL come from the CLI's own configuration. Each client is built with the CLI's `identity` (`cliClientIdentity()` in `client-provenance.ts`, from which the client sends the provenance headers and which makes it refuse them in `defaultHeaders` and per-call `headers`), `auth` (`Auth.user` with the user key, `Auth.project` when a caller passes `projectApiKey`, `Auth.none()` before login), `scope` (the org and project, when both are known), `x-cli-session-id` as the one default header (read once per process), and a counting `fetch` (`composio-client-metrics.ts`) provided as the transport's `FetchHttpClient.Fetch`. Explicitly configured HTTP base URLs remain supported without an additional environment flag. The client's deprecation notices, which CLI users cannot act on, are dropped by the root logger (`withoutClientNotices`, `src/effects/without-client-notices.ts`, through the client's `isDeprecationNotice`). `composio-clients.ts` holds client construction, the two repositories, and the `collectAll` and `sortBySlug` helpers the catalog fetches share. The repository's auth-config, connected-account, trigger-instance, search, and single-item methods live in `src/services/composio-resource-operations.ts`; the account helpers (`listOrganizations`, `getSessionInfo*`, `resolveConsumerProject`, `createProjectApiKey`, `getLatestToolVersion`, …) in `src/services/composio-account.ts`; toolkit version validation and its errors (`InvalidToolkitsError`, `InvalidToolkitVersionsError`) in `src/services/toolkit-version-validation.ts`; the shared error types (`ClientError`, `HttpDecodingError`, `ComposioClientConfigurationError`) in `src/services/composio-errors.ts`; and the shared `decode` helper and `validated` request option in `src/services/composio-request.ts`. There is no CLI error wrapper around a request: the client's tagged errors (`@composio/client/NotFoundError`, `APIConnectionError`, `DecodeError`, …) flow to callers, which recover with `Effect.catchTag` or the client's `isAPIError` guard. Commands that report an API failure with a hint and exit 1 share one handler, `handleClientApiError` (`src/effects/handle-http-error.ts`), applied with `Effect.catchTag(CLIENT_API_ERROR_TAGS, …)`; it never succeeds, so the command reads the request's result straight through; the tag list lives in `src/services/composio-errors.ts`. Endpoints the client does not type use the raw `client.get`/`client.post`; `src/services/tool-permissions.ts` reaches them through its own `requestJson`, which raises `services/ToolPermissionsRequestError` because its callers fail closed on that tag. Do not add a raw `fetch` to the Composio backend from `src/commands`, `src/effects`, or `src/services` — the one sanctioned exception is the bundled companion runtime (`run-helpers-runtime.ts`), which runs in the user's spawned process outside the Effect runtime. (`src/services/agents.ts` also calls `fetch`, against the agents service at agents.composio.dev rather than the Composio backend.) The Composio Dashboard (`ComposioUserContext.data.webURL`) is the one first-party host the CLI calls without `@composio/client`: `src/services/dashboard-tool-execution.ts` sends consumer `composio execute` calls (tool and meta-tool executions) to it over `HttpClient` from `effect/http`, once, with no retry, no redirect following and one 15-minute deadline, only to an `https:` base URL (or loopback `http:`) that carries no credentials, query or fragment, and fails a relayed backend failure with the client's own status error (`@composio/client/PermissionDeniedError`, …) so the classification below still applies. While telemetry is enabled, those requests (and only those) also carry the stored analytics install ID as `x-cli-install-id`, read through `readInstallIdWhenTelemetryEnabled` in `src/analytics/dispatch.ts`, which never creates an ID and never fails; do not add the header to backend requests or to `cliRequestHeaders()`. Everything else on the execute path (connection lookups, the permission gate, file uploads) and `dev playground-execute` stay on the backend client. Do not route other commands through the Dashboard, and do not add a second raw-HTTP host, without updating this paragraph. oxlint rejects value imports of the `@composio/client` root and `@composio/client/pagination` from CLI `src/`; type-only imports are allowed. The CLI's clients send every request once. A call that is safe to repeat — a read, or a call whose repeat changes nothing on the server — passes the `idempotent` request option (`src/services/composio-request.ts`) and is retried by the client after a connection failure, a timeout, or a 408, 409, 429 or 5xx response; combine it with `validated` as `{ ...idempotent, ...validated }`. Creates, updates, deletes, links, sessions, tool executions and proxied calls never pass it, because a request that failed in flight may already have acted. It also rejects importing `make` or the client layers from `@composio/client/effect` anywhere but `composio-clients.ts`, and `getFor` takes an org and a project together or neither, because the two headers are only sent as a pair. Every `getFor` builds a new client, so never key a memo on a client instance: `clientScopeKey(client)` gives its auth mode, a SHA-256 fingerprint of its credential (never the key), org, and project (`listActiveConnectedAccounts` keys on it and the user id). While a client has `auth` and `scope`, a per-call `x-api-key`, `x-user-api-key`, `x-org-api-key`, `x-org-id` or `x-project-id` header fails the call before it is sent; an org or project known alone goes on an unscoped client's request, as `orgScopedOptions` and `getLatestToolVersion` do. Client errors are classified for display by `src/utils/api-error-extraction.ts`.
134
ts/packages/cli/CHANGELOG.md
+10
@@ -84,6 +84,16 @@
84 `""`. `composio run` starts the script without the consumer user's context,
85 as it does when there is no consumer user.
86
87 +- CLI telemetry now records the command `effect/cli` parsed instead of guessing
88 + it from argv. `composio signup`, `agent …`, `connections …`, `config …`,
89 + `debug …` and `help …` were recorded as `composio`, `composio dev init` as
90 + `dev`, and `composio setup skill` as `setup` with the `CLI_SETUP_*` events;
91 + each is now recorded under its own command path with the generic
92 + `CLI_COMMAND_*` events. A rejected invocation (unknown command or flag,
93 + missing argument) is recorded with the command path the parser reached and
94 + `failure_reason_code: "parse_error"`. Every other command path and event
95 + family is unchanged.
96 +
97 - CLI telemetry now records a command that prints its own
98 failure and exits 1 (a failed API request, an alias conflict on
99 `composio link`, a `--fail-fast` listener stop) as failed instead of
ts/packages/cli/docs/adr/0001-command-identity-after-parse.md new
+36
@@ -0,0 +1,36 @@
1 +---
2 +status: accepted
3 +---
4 +
5 +# Command identity is recorded after parse
6 +
7 +The CLI needs to know which command an invocation runs, for telemetry, hooks, and login checks. We learn it at runtime, after effect/cli parses argv, instead of guessing it from argv up front. Each command registration passes its children an immutable command path and inherited command metadata; only the selected handler records the identity. Parse failures take the command path from `CliError.ShowHelp.commandPath`; `--help` and `--version` take it from the Help and Version action wrappers.
8 +
9 +Identity describes the command registration, not the `Command` value. `link` is one value registered twice (`link` and `dev connected-accounts link`), so the same value has two command paths and must report the one the user ran.
10 +
11 +## Considered Options
12 +
13 +- **Runtime identity after parse (chosen).** effect/cli already resolved the command; we read its answer.
14 +- **Static resolution of argv before parse.** `Command.Any` does not expose its flags, so this means reimplementing the parser: value flags, boolean literals, `--no-x`, shared and global flags, `--`. It keeps hand-kept value-flag tables that drift from the commands, and it knows less about a parse failure than `ShowHelp` does.
15 +- **Hybrid (static first, runtime to confirm).** Two implementations of one question, and events from the same invocation can be attributed to different command paths.
16 +- **Observer `GlobalFlag` action.** Runs only when its flag is present on argv, so it cannot see most invocations.
17 +
18 +Industry practice agrees: gh, the Stripe CLI, cobra and commander based CLIs, Turborepo, and Vercel record the command after parse. oclif is the outlier; its `init` hook runs before command lookup.
19 +
20 +- gh: https://github.com/cli/cli/blob/trunk/pkg/cmdutil/telemetry.go
21 +- Stripe CLI: https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/root.go
22 +- cobra (`PersistentPreRun` never runs for unknown commands): https://github.com/spf13/cobra/blob/main/command.go
23 +- commander (`preAction` runs after a valid parse): https://github.com/tj/commander.js/blob/master/lib/command.js
24 +
25 +## Consequences
26 +
27 +- Telemetry path and family come from identity, so the argv token tables and family matchers in `src/analytics/events.ts` go away. Only paths that were misattributed change.
28 +- Parse failures still emit the invoked and failed pair, so current dashboards keep working. The path comes from `ShowHelp`, uses canonical command names, never raw user tokens, and the reason is `parse_error`. A separate rejected event (as the Stripe CLI does) was considered and deferred; adopting it means migrating funnels on purpose.
29 +- The design depends on the order in which effect/cli (`effect` 4.0.5, the version the workspace locks) composes handlers in `withSubcommands`, which is undocumented. A contract test (`test/src/commands/registration.test.ts`) pins it (nested providers, guards, bare groups, reused registrations, root shortcuts), so an `effect` upgrade that changes it fails there first.
30 +- Group-level guards such as `requireLogin` can run before the selected handler, so they would fire without an identity. They become command metadata, enforced right after identity is recorded.
31 +- Invocation hooks (update notice, plugin hint) still run before parsing, so `--help`, `--version`, and typos can still show them.
32 +
33 +## Revisit when
34 +
35 +- effect/cli ships a public hook for the selected command, such as an upstream `runWith({ onSelected })`.
36 +- `CliOutput.Presenter` (https://github.com/Effect-TS/effect/pull/6743, merged but unreleased) ships; it can replace the Help, Version, and `ShowHelp` adapters for help, version, and parse-failure identity.
ts/packages/cli/src/analytics/dispatch.ts
+4 -3
@@ -25,7 +25,8 @@ import { NodeOs } from 'src/services/node-os';
25 import { detectPluginHost, rawHostEnvironment } from 'src/services/agent-host-env';
26 import { TerminalUI } from 'src/services/terminal-ui';
27 import { isTelemetryDebugEnabled, TELEMETRY_DEBUG_FLAG } from 'src/services/runtime-flags';
28 -import { cliInvocationContext, CliRunId } from 'src/services/runtime-cli-context';
28 +import { cliInvocationContext } from 'src/services/runtime-cli-context';
29 +import { invocationRunId } from 'src/invocation/command-identity';
30 import type { AnalyticsEnvelope, TrackEvent } from './types';
31
32 const INTERNAL_ANALYTICS_WORKER_FLAG = '__analytics-worker';
@@ -583,11 +584,11 @@ type CliInvocationContext = {
584 };
585
586 // The COMPOSIO_CLI_PARENT_RUN_ID handshake only exists in processes `composio run` spawned. The
586 -// root run process holds its freshly minted id in the CliRunId service instead, so failures it
587 +// root run process minted its id when the command began (`invocationRunId`), so failures it
588 // reports carry the same run id its children stamp from the environment.
589 const getCliInvocationContext: Effect.Effect<CliInvocationContext> = Effect.gen(function* () {
590 const { invocationOrigin, parentRunId } = yield* cliInvocationContext;
590 - const mintedRunId = Option.flatten(yield* Effect.serviceOption(CliRunId));
591 + const mintedRunId = yield* invocationRunId;
592 return {
593 origin: invocationOrigin,
594 parentRunId: parentRunId ?? Option.getOrUndefined(mintedRunId),
ts/packages/cli/src/analytics/events.ts
+93 -169
@@ -1,5 +1,8 @@
1 import { cliAnalyticsProvenance } from 'src/services/client-provenance';
2 -import type { CliCommandTelemetryContext, TrackEvent } from './types';
2 +import { Option, Schema } from 'effect';
3 +import { CliError } from 'effect/cli';
4 +import type { CliCommandTelemetryContext, TelemetryFamily, TrackEvent } from './types';
5 +import { type CommandIdentity, commandPathOf } from 'src/invocation/command-identity';
6 import { APP_VERSION } from 'src/constants';
7 import { inferSkillReleaseChannel } from 'src/effects/install-skill';
8 import type { AgentHost } from 'src/services/agent-host';
@@ -8,7 +11,6 @@ import { ChildProcessExited, ChildProcessSignaled } from 'src/effects/child-proc
11 import { SetupCommandError } from 'src/services/setup-command-error';
12 import { ToolInputValidationError } from 'src/services/tool-input-validation';
13 import { guessToolkitFromToolSlug } from 'src/utils/toolkit-from-tool-slug';
11 -import { rootCommandIndex } from 'src/utils/cli-args';
14
15 export const CLI_ANALYTICS_EVENTS = {
16 CLI_COMMAND_INVOKED: 'CLI_COMMAND_INVOKED',
@@ -151,46 +153,6 @@ const buildEvent = (
153 },
154 });
155
154 -const KNOWN_COMMAND_TOKENS = new Set([
155 - 'version',
156 - 'upgrade',
157 - 'whoami',
158 - 'login',
159 - 'logout',
160 - 'run',
161 - 'install',
162 - 'setup',
163 - 'dev',
164 - 'generate',
165 - 'tools',
166 - 'toolkits',
167 - 'toolkit',
168 - 'search',
169 - 'execute',
170 - 'playground-execute',
171 - 'link',
172 - 'proxy',
173 - 'artifacts',
174 - 'cwd',
175 - 'connected-accounts',
176 - 'auth-configs',
177 - 'triggers',
178 - 'logs',
179 - 'orgs',
180 - 'projects',
181 - 'info',
182 - 'list',
183 - 'create',
184 - 'delete',
185 - 'enable',
186 - 'disable',
187 - 'status',
188 - 'listen',
189 - 'switch',
190 - 'py',
191 - 'ts',
192 -]);
193 -
156 const TOOL_NOT_FOUND_PATTERN = /\btool\b.*\bnot found\b/i;
157 const TOOL_VALIDATION_PATTERN = /\b(?:validation|invalid parameter|invalid argument)\b/i;
158 const TOOL_NOT_FOUND_CODES: ReadonlySet<number> = new Set([
@@ -209,19 +171,6 @@ const TOOL_VALIDATION_CODES: ReadonlySet<number> = new Set([
171 3702, // ComposioTools_ValidationError
172 ]);
173
212 -const extractCommandPath = (argv: ReadonlyArray<string>): string => {
213 - const commandTokens: string[] = [];
214 - const args = argv.slice(2);
215 - for (const token of args.slice(rootCommandIndex(args))) {
216 - if (!token || token.startsWith('-') || !KNOWN_COMMAND_TOKENS.has(token)) {
217 - break;
218 - }
219 - commandTokens.push(token);
220 - }
221 -
222 - return commandTokens.length > 0 ? commandTokens.join(' ') : 'composio';
223 -};
224 -
174 const extractFlagNames = (argv: ReadonlyArray<string>): ReadonlyArray<string> =>
175 [
176 ...new Set(
@@ -262,6 +211,11 @@ const errorNameOf = (error: unknown): string =>
211 error instanceof Error && error.name ? error.name : 'UnknownError';
212
213 const failureReasonProperties = (error: unknown) => {
214 + // `effect/cli` rejected argv: no command ran, and the event's command path is the one the
215 + // parser reached (`CliError.ShowHelp.commandPath`). A bare group's help carries no errors.
216 + if (error instanceof CliError.ShowHelp && error.errors.length > 0) {
217 + return { failure_reason_code: 'parse_error' };
218 + }
219 if (error instanceof SetupCommandError) return { failure_reason_code: error.reasonCode };
220 if (error instanceof ChildProcessExited || error instanceof ChildProcessSignaled) {
221 return { failure_reason_code: 'child_exit' };
@@ -294,47 +248,8 @@ const getFlagValue = (argv: ReadonlyArray<string>, ...flags: string[]): string |
248 return undefined;
249 };
250
297 -const getTrailingPositionals = (context: CliCommandTelemetryContext): ReadonlyArray<string> => {
298 - const commandTokenCount =
299 - context.commandPath === 'composio' ? 0 : context.commandPath.split(' ').length;
300 - const rootArgs = context.argv.slice(2);
301 - const args = rootArgs.slice(rootCommandIndex(rootArgs) + commandTokenCount);
302 - const positionals: string[] = [];
303 -
304 - for (let index = 0; index < args.length; index += 1) {
305 - const token = args[index];
306 - if (!token) continue;
307 -
308 - if (token === '--') {
309 - break;
310 - }
311 -
312 - if (token.startsWith('-')) {
313 - const expectsValue = [
314 - '--data',
315 - '-d',
316 - '--toolkits',
317 - '--limit',
318 - '--user-id',
319 - '--project-name',
320 - '--auth-config',
321 - '--file',
322 - '-f',
323 - ].includes(token);
324 - if (expectsValue) {
325 - index += 1;
326 - }
327 - continue;
328 - }
329 -
330 - positionals.push(token);
331 - }
332 -
333 - return positionals;
334 -};
335 -
251 const getExecuteCommandProperties = (context: CliCommandTelemetryContext) => {
337 - const slug = getTrailingPositionals(context)[0];
252 + const slug = context.argument;
253 return {
254 source: 'cli',
255 invocation_origin: context.invocationOrigin,
@@ -360,7 +275,7 @@ const getExecuteCommandProperties = (context: CliCommandTelemetryContext) => {
275
276 // Search queries are user-authored free text, so only their shape is recorded.
277 const getSearchCommandProperties = (context: CliCommandTelemetryContext) => {
363 - const query = getTrailingPositionals(context)[0] ?? '';
278 + const query = context.argument ?? '';
279 return {
280 source: 'cli',
281 invocation_origin: context.invocationOrigin,
@@ -377,7 +292,6 @@ const getSearchCommandProperties = (context: CliCommandTelemetryContext) => {
292 };
293
294 const getLinkCommandProperties = (context: CliCommandTelemetryContext) => {
380 - const firstPositional = getTrailingPositionals(context)[0];
295 return {
296 source: 'cli',
297 invocation_origin: context.invocationOrigin,
@@ -386,7 +300,7 @@ const getLinkCommandProperties = (context: CliCommandTelemetryContext) => {
300 cli_version: context.cliVersion,
301 command_path: context.commandPath,
302 duration_ms: Date.now() - context.startedAt,
389 - toolkit: getFlagValue(context.argv, '--toolkit') ?? firstPositional,
303 + toolkit: context.argument,
304 no_browser: isFlagPresent(context.argv, '--no-browser'),
305 no_wait: isFlagPresent(context.argv, '--no-wait'),
306 has_auth_config: isFlagPresent(context.argv, '--auth-config'),
@@ -458,7 +372,7 @@ const getProxyCommandProperties = (context: CliCommandTelemetryContext) => ({
372 cli_version: context.cliVersion,
373 command_path: context.commandPath,
374 duration_ms: Date.now() - context.startedAt,
461 - has_endpoint: typeof getTrailingPositionals(context)[0] === 'string',
375 + has_endpoint: typeof context.argument === 'string',
376 toolkit: getFlagValue(context.argv, '--toolkit', '-t'),
377 method: getFlagValue(context.argv, '--method', '-X') ?? 'GET',
378 has_data: isFlagPresent(context.argv, '--data', '-d'),
@@ -467,64 +381,78 @@ const getProxyCommandProperties = (context: CliCommandTelemetryContext) => ({
381 skip_connection_check: isFlagPresent(context.argv, '--skip-connection-check'),
382 });
383
470 -const isExecuteCommand = (commandPath: string): boolean =>
471 - commandPath === 'execute' || commandPath === 'dev playground-execute';
472 -
473 -const isSearchCommand = (commandPath: string): boolean =>
474 - commandPath === 'search' || commandPath === 'dev toolkits search';
475 -
476 -const isLinkCommand = (commandPath: string): boolean =>
477 - commandPath === 'link' || commandPath === 'dev connected-accounts link';
478 -
479 -const isLoginCommand = (commandPath: string): boolean => commandPath === 'login';
480 -
481 -const isLogoutCommand = (commandPath: string): boolean => commandPath === 'logout';
482 -
483 -const isProxyCommand = (commandPath: string): boolean => commandPath === 'proxy';
484 -
485 -const isRunCommand = (commandPath: string): boolean => commandPath === 'run';
486 -
487 -const isInstallCommand = (commandPath: string): boolean => commandPath === 'install';
488 -
489 -const isSetupCommand = (commandPath: string): boolean => commandPath === 'setup';
490 -
491 -const isGenericOnlyCommand = (commandPath: string): boolean =>
492 - commandPath === 'composio' || commandPath.startsWith('dev');
384 +const firstOf = (values: ReadonlyArray<string>) => values[0];
385
386 /**
495 - * Tool slug positional of an execute-family invocation, so the CLI bootstrap
496 - * can resolve the toolkit slug once and stamp it on the telemetry context for
497 - * the synchronous lifecycle event builders.
387 + * How each family that describes an input argument finds it in the input `effect/cli` parsed for
388 + * the command (see `CliCommandTelemetryContext.argument`).
389 */
499 -export const getExecuteCommandToolSlug = (
500 - context: CliCommandTelemetryContext
390 +const FAMILY_ARGUMENTS: Partial<
391 + Record<TelemetryFamily, (input: unknown) => Option.Option<string>>
392 +> = {
393 + execute: input =>
394 + Option.map(
395 + Schema.decodeUnknownOption(Schema.Struct({ slug: Schema.String }))(input),
396 + ({ slug }) => slug
397 + ),
398 + search: input =>
399 + Option.flatMap(
400 + Schema.decodeUnknownOption(Schema.Struct({ query: Schema.Array(Schema.String) }))(input),
401 + ({ query }) => Option.fromNullishOr(firstOf(query))
402 + ),
403 + link: input =>
404 + Option.flatMap(
405 + Schema.decodeUnknownOption(Schema.Struct({ toolkit: Schema.Option(Schema.String) }))(input),
406 + ({ toolkit }) => toolkit
407 + ),
408 + proxy: input =>
409 + Option.map(
410 + Schema.decodeUnknownOption(Schema.Struct({ endpoint: Schema.String }))(input),
411 + ({ endpoint }) => endpoint
412 + ),
413 +};
414 +
415 +const familyArgument = (
416 + family: TelemetryFamily,
417 + input: Option.Option<unknown>
418 ): string | undefined =>
502 - isExecuteCommand(context.commandPath) ? getTrailingPositionals(context)[0] : undefined;
419 + Option.getOrUndefined(
420 + Option.flatMap(input, parsed =>
421 + Option.flatMap(Option.fromNullishOr(FAMILY_ARGUMENTS[family]), argument => argument(parsed))
422 + )
423 + );
424
425 /**
505 - * Builds the telemetry context of the running command.
426 + * Builds the telemetry context of the command `identity` names, with the input `effect/cli`
427 + * parsed for it (none for help, version, and parse failures).
428 *
429 * `invocation` is read from config by the caller and stamped here so every synchronous event
430 * builder below takes the origin as an input rather than consulting process-wide state.
431 */
510 -export const createCliCommandTelemetryContext = (
511 - argv: ReadonlyArray<string>,
512 - cliVersion: string,
513 - terminal: { readonly stdoutIsTTY: boolean; readonly stderrIsTTY: boolean },
514 - invocation: CliInvocationContext
515 -): CliCommandTelemetryContext => {
516 - const commandPath = extractCommandPath(argv);
432 +export const createCliCommandTelemetryContext = (params: {
433 + readonly argv: ReadonlyArray<string>;
434 + readonly cliVersion: string;
435 + readonly terminal: { readonly stdoutIsTTY: boolean; readonly stderrIsTTY: boolean };
436 + readonly invocation: CliInvocationContext;
437 + readonly identity: CommandIdentity;
438 + readonly input: Option.Option<unknown>;
439 + readonly startedAt: number;
440 +}): CliCommandTelemetryContext => {
441 + const { argv, invocation, terminal, identity } = params;
442 + const family = identity.meta.telemetryFamily;
443 return {
444 argv,
519 - cliVersion,
445 + cliVersion: params.cliVersion,
446 invocationOrigin: invocation.invocationOrigin,
447 parentRunId: invocation.parentRunId,
522 - commandPath,
448 + commandPath: commandPathOf(identity),
449 + family,
450 + argument: familyArgument(family, params.input),
451 flagNames: extractFlagNames(argv),
452 stdoutIsTTY: terminal.stdoutIsTTY,
453 stderrIsTTY: terminal.stderrIsTTY,
526 - startedAt: Date.now(),
527 - runId: commandPath === 'run' ? (invocation.parentRunId ?? crypto.randomUUID()) : undefined,
454 + startedAt: params.startedAt,
455 + runId: family === 'run' ? (invocation.parentRunId ?? crypto.randomUUID()) : undefined,
456 };
457 };
458
@@ -562,90 +490,86 @@ const getCliCommandFailedEvent = (
490 duration_ms: Date.now() - context.startedAt,
491 flag_names: context.flagNames,
492 error_name: errorNameOf(error),
493 + ...failureReasonProperties(error),
494 });
495
496 type SpecialLifecycleFamily = {
568 - readonly match: (commandPath: string) => boolean;
497 readonly invokedEventName: CliAnalyticsEventName;
498 readonly succeededEventName: CliAnalyticsEventName;
499 readonly failedEventName: CliAnalyticsEventName;
500 readonly getProperties: (context: CliCommandTelemetryContext) => Record<string, unknown>;
501 };
502
575 -const SPECIAL_LIFECYCLE_FAMILIES: ReadonlyArray<SpecialLifecycleFamily> = [
576 - {
577 - match: isExecuteCommand,
503 +const SPECIAL_LIFECYCLE_FAMILIES: Record<
504 + Exclude<TelemetryFamily, 'command'>,
505 + SpecialLifecycleFamily
506 +> = {
507 + execute: {
508 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_INVOKED,
509 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_SUCCEEDED,
510 failedEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_FAILED,
511 getProperties: getExecuteCommandProperties,
512 },
583 - {
584 - match: isSearchCommand,
513 + search: {
514 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_INVOKED,
515 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_SUCCEEDED,
516 failedEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_FAILED,
517 getProperties: getSearchCommandProperties,
518 },
590 - {
591 - match: isLinkCommand,
519 + link: {
520 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_INVOKED,
521 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_SUCCEEDED,
522 failedEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_FAILED,
523 getProperties: getLinkCommandProperties,
524 },
597 - {
598 - match: isLoginCommand,
525 + login: {
526 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_INVOKED,
527 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_SUCCEEDED,
528 failedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_FAILED,
529 getProperties: getLoginCommandProperties,
530 },
604 - {
605 - match: isLogoutCommand,
531 + logout: {
532 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_INVOKED,
533 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_SUCCEEDED,
534 failedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_FAILED,
535 getProperties: getLogoutCommandProperties,
536 },
611 - {
612 - match: isProxyCommand,
537 + proxy: {
538 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_INVOKED,
539 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_SUCCEEDED,
540 failedEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_FAILED,
541 getProperties: getProxyCommandProperties,
542 },
618 - {
619 - match: isRunCommand,
543 + run: {
544 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_INVOKED,
545 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_SUCCEEDED,
546 failedEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_FAILED,
547 getProperties: getRunCommandProperties,
548 },
625 - {
626 - match: isInstallCommand,
549 + install: {
550 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_INVOKED,
551 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_SUCCEEDED,
552 failedEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_FAILED,
553 getProperties: getInstallCommandProperties,
554 },
632 - {
633 - match: isSetupCommand,
555 + setup: {
556 invokedEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_INVOKED,
557 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_SUCCEEDED,
558 failedEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_FAILED,
559 getProperties: getSetupCommandProperties,
560 },
639 -];
561 +};
562
641 -const getSpecialLifecycleFamily = (commandPath: string): SpecialLifecycleFamily | undefined =>
642 - SPECIAL_LIFECYCLE_FAMILIES.find(family => family.match(commandPath));
563 +const getSpecialLifecycleFamily = (
564 + context: CliCommandTelemetryContext
565 +): SpecialLifecycleFamily | undefined =>
566 + context.family === 'command' ? undefined : SPECIAL_LIFECYCLE_FAMILIES[context.family];
567
568 export const getPrimaryLifecycleInvokedEvent = (
569 context: CliCommandTelemetryContext
570 ): TrackEvent => {
647 - const family = getSpecialLifecycleFamily(context.commandPath);
648 - if (!family || isGenericOnlyCommand(context.commandPath)) {
571 + const family = getSpecialLifecycleFamily(context);
572 + if (!family) {
573 return getCliCommandInvokedEvent(context);
574 }
575 return buildEvent(family.invokedEventName, family.getProperties(context));
@@ -654,8 +578,8 @@ export const getPrimaryLifecycleInvokedEvent = (
578 export const getPrimaryLifecycleSucceededEvent = (
579 context: CliCommandTelemetryContext
580 ): TrackEvent => {
657 - const family = getSpecialLifecycleFamily(context.commandPath);
658 - if (!family || isGenericOnlyCommand(context.commandPath)) {
581 + const family = getSpecialLifecycleFamily(context);
582 + if (!family) {
583 return getCliCommandSucceededEvent(context);
584 }
585 return buildEvent(family.succeededEventName, family.getProperties(context));
@@ -665,8 +589,8 @@ export const getPrimaryLifecycleFailedEvent = (
589 context: CliCommandTelemetryContext,
590 error: unknown
591 ): TrackEvent => {
668 - const family = getSpecialLifecycleFamily(context.commandPath);
669 - if (!family || isGenericOnlyCommand(context.commandPath)) {
592 + const family = getSpecialLifecycleFamily(context);
593 + if (!family) {
594 return getCliCommandFailedEvent(context, error);
595 }
596 return buildEvent(family.failedEventName, {
ts/packages/cli/src/analytics/types.ts
+23
@@ -12,6 +12,22 @@ export type AnalyticsEnvelope = {
12 readonly installId: string;
13 };
14
15 +/**
16 + * The family of lifecycle events a command reports: `command` is the generic `CLI_COMMAND_*`
17 + * family, every other one has its own events (`CLI_EXECUTE_*`, `CLI_LINK_*`, …).
18 + */
19 +export type TelemetryFamily =
20 + | 'command'
21 + | 'execute'
22 + | 'search'
23 + | 'link'
24 + | 'login'
25 + | 'logout'
26 + | 'proxy'
27 + | 'run'
28 + | 'install'
29 + | 'setup';
30 +
31 export type CliCommandTelemetryContext = {
32 readonly argv: ReadonlyArray<string>;
33 readonly cliVersion: string;
@@ -20,6 +36,13 @@ export type CliCommandTelemetryContext = {
36 /** Run id of the `composio run` that spawned this process, when there is one. */
37 readonly parentRunId: string | undefined;
38 readonly commandPath: string;
39 + readonly family: TelemetryFamily;
40 + /**
41 + * The input argument the family's events describe, from the input `effect/cli` parsed: the tool
42 + * slug of `execute`, the first query of `search`, the toolkit of `link`, the endpoint of
43 + * `proxy`. Unset for other families and when nothing was parsed (help, version, parse errors).
44 + */
45 + readonly argument?: string;
46 readonly flagNames: ReadonlyArray<string>;
47 readonly stdoutIsTTY: boolean;
48 readonly stderrIsTTY: boolean;
ts/packages/cli/src/cli-config.ts
+5 -4
@@ -1,7 +1,8 @@
1 -import { Help } from 'src/commands/root-help';
2 -import { GlobalFlag, type CliConfig } from 'effect/cli';
1 +import { Help, Version } from 'src/commands/root-help';
2 +import type { CliConfig } from 'effect/cli';
3
4 -// Help and version use the framework parser. The help formatter keeps version output bare.
4 +// Help and version use the framework parser, wrapped to record the command they answer for. The
5 +// help formatter keeps version output bare.
6 export const ComposioCliConfig = {
6 - builtIns: [Help, GlobalFlag.Version],
7 + builtIns: [Help, Version],
8 } satisfies Partial<CliConfig.CliConfig.Service>;
ts/packages/cli/src/commands/agent/agent.cmd.ts
+2 -1
@@ -4,10 +4,11 @@ import { agentCmd$Inbox } from './inbox/agent.inbox.cmd';
4 import { agentCmd$Login } from './login/agent.login.cmd';
5 import { agentCmd$Signup } from './signup/agent.signup.cmd';
6 import { agentCmd$Whoami } from './whoami/agent.whoami.cmd';
7 +import { withRegisteredSubcommands } from 'src/commands/registration';
8
9 export const agentCmd = Command.make('agent').pipe(
10 Command.withDescription('Manage Composio agent identity, inbox, and handoff.'),
10 - Command.withSubcommands([
11 + withRegisteredSubcommands([
12 agentCmd$Signup,
13 agentCmd$Login,
14 agentCmd$Whoami,
ts/packages/cli/src/commands/artifacts/artifacts.cmd.ts
+2 -1
@@ -1,7 +1,8 @@
1 import { Command } from 'effect/cli';
2 import { artifactsCmd$Cwd } from './cwd/artifacts.cwd.cmd';
3 +import { withRegisteredSubcommands } from 'src/commands/registration';
4
5 export const artifactsCmd = Command.make('artifacts').pipe(
6 Command.withDescription('Inspect session artifact directories.'),
6 - Command.withSubcommands([artifactsCmd$Cwd])
7 + withRegisteredSubcommands([artifactsCmd$Cwd])
8 );
ts/packages/cli/src/commands/auth-configs/auth-configs.cmd.ts
+2 -1
@@ -3,6 +3,7 @@ import { Command } from 'effect/cli';
3 import { authConfigsCmd$List } from './list/auth-configs.list.cmd';
4 import { authConfigsCmd$Info } from './info/auth-configs.info.cmd';
5 import { authConfigsCmd$Create } from './create/auth-configs.create.cmd';
6 +import { withRegisteredSubcommands } from 'src/commands/registration';
7
8 /**
9 * CLI entry point for auth config management commands.
@@ -14,6 +15,6 @@ import { authConfigsCmd$Create } from './create/auth-configs.create.cmd';
15 */
16 export const authConfigsCmd = Command.make('auth-configs').pipe(
17 Command.withDescription('View and manage Composio auth configs.'),
17 - Command.withSubcommands([authConfigsCmd$List, authConfigsCmd$Info, authConfigsCmd$Create]),
18 + withRegisteredSubcommands([authConfigsCmd$List, authConfigsCmd$Info, authConfigsCmd$Create]),
19 requireLogin
20 );
ts/packages/cli/src/commands/background-update-check.ts
+4 -2
@@ -3,6 +3,7 @@ import { Command } from 'effect/cli';
3 import { versionCmd } from './version.cmd';
4 import { upgradeCmd } from './upgrade/upgrade.cmd';
5 import { checkForUpdateInBackground } from 'src/services/update-check';
6 +import { withRegisteredSubcommands } from 'src/commands/registration';
7
8 const isExplicitVersionCheck = (commandName: string, input: unknown): boolean =>
9 commandName === versionCmd.name && Predicate.hasProperty(input, 'check') && input.check === true;
@@ -17,7 +18,8 @@ const resolvesReleasesItself = (commandName: string, input: unknown): boolean =>
18 *
19 * `effect/cli` keeps the selected subcommand private to the parent's dispatcher, so the
20 * hook is attached per subcommand (each sees its own parsed input) plus the root itself for the
20 - * no-subcommand path, before the tree is assembled with `Command.withSubcommands`.
21 + * no-subcommand path, before the tree is assembled with `withRegisteredSubcommands`, which also
22 + * registers each subcommand under the root.
23 */
24 export const withBackgroundUpdateCheck = <
25 const Name extends string,
@@ -42,6 +44,6 @@ export const withBackgroundUpdateCheck = <
44
45 return root.pipe(
46 Command.provideEffectDiscard(startInBackground),
45 - Command.withSubcommands(guarded)
47 + withRegisteredSubcommands(guarded)
48 );
49 };
ts/packages/cli/src/commands/config/config.cmd.ts
+2 -1
@@ -1,7 +1,8 @@
1 import { Command } from 'effect/cli';
2 import { configExperimentalCmd } from './config.experimental.cmd';
3 +import { withRegisteredSubcommands } from 'src/commands/registration';
4
5 export const configCmd = Command.make('config').pipe(
6 Command.withDescription('View and manage CLI configuration.'),
6 - Command.withSubcommands([configExperimentalCmd])
7 + withRegisteredSubcommands([configExperimentalCmd])
8 );
ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts
+2 -1
@@ -5,6 +5,7 @@ import { connectedAccountsCmd$List } from './list/connected-accounts.list.cmd';
5 import { connectedAccountsCmd$Info } from './info/connected-accounts.info.cmd';
6 import { connectedAccountsCmd$Whoami } from './whoami/connected-accounts.whoami.cmd';
7 import { connectedAccountsCmd$Link } from './link/connected-accounts.link.cmd';
8 +import { withRegisteredSubcommands } from 'src/commands/registration';
9
10 /**
11 * CLI entry point for connected account management commands.
@@ -16,7 +17,7 @@ import { connectedAccountsCmd$Link } from './link/connected-accounts.link.cmd';
17 */
18 export const connectedAccountsCmd = Command.make('connected-accounts').pipe(
19 Command.withDescription('View and manage Composio connected accounts.'),
19 - Command.withSubcommands([
20 + withRegisteredSubcommands([
21 connectedAccountsCmd$Link,
22 connectedAccountsCmd$List,
23 connectedAccountsCmd$Info.pipe(rejectsSharedFlags('dev connected-accounts info')),
ts/packages/cli/src/commands/connections/connections.cmd.ts
+2 -1
@@ -2,9 +2,10 @@ import { requireLogin } from 'src/effects/require-auth';
2 import { Command } from 'effect/cli';
3 import { connectionsCmd$List } from './list/connections.list.cmd';
4 import { connectionsCmd$Remove } from './remove/connections.remove.cmd';
5 +import { withRegisteredSubcommands } from 'src/commands/registration';
6
7 export const rootConnectionsCmd = Command.make('connections').pipe(
8 Command.withDescription('Inspect and remove connected toolkit accounts.'),
8 - Command.withSubcommands([connectionsCmd$List, connectionsCmd$Remove]),
9 + withRegisteredSubcommands([connectionsCmd$List, connectionsCmd$Remove]),
10 requireLogin
11 );
ts/packages/cli/src/commands/debug/debug.cmd.ts
+2 -1
@@ -2,9 +2,10 @@ import { Command } from 'effect/cli';
2 import { debugCmd$ApiInfo } from './api-info/debug.api-info.cmd';
3 import { debugCmd$GenerateGraph } from './generate-graph/debug.generate-graph.cmd';
4 import { debugCmd$WhoIsMyMaster } from './who-is-my-master/debug.who-is-my-master.cmd';
5 +import { withRegisteredSubcommands } from 'src/commands/registration';
6
7 export const debugCmd = Command.make('debug').pipe(
8 Command.unlisted,
9 Command.withDescription('Internal CLI diagnostics.'),
9 - Command.withSubcommands([debugCmd$GenerateGraph, debugCmd$ApiInfo, debugCmd$WhoIsMyMaster])
10 + withRegisteredSubcommands([debugCmd$GenerateGraph, debugCmd$ApiInfo, debugCmd$WhoIsMyMaster])
11 );
ts/packages/cli/src/commands/dev.cmd.ts
+2 -1
@@ -16,6 +16,7 @@ import { Stdin } from 'src/services/stdin';
16 import { TerminalUI } from 'src/services/terminal-ui';
17 import type { CommandVisibility } from './feature-tags';
18 import { CommandSurface, rejectSharedFlags, rejectsSharedFlags } from './surface';
19 +import { withRegisteredSubcommands } from 'src/commands/registration';
20
21 const devMode = Flag.Literals('mode', ['on', 'off'] as const).pipe(
22 Flag.withDescription('Set developer mode on or off.'),
@@ -180,7 +181,7 @@ export const buildDevCommand = (visibility: CommandVisibility) =>
181 Effect.andThen(developerModeHandler(input))
182 )
183 ).pipe(
183 - Command.withSubcommands([...devSubcommands]),
184 + withRegisteredSubcommands([...devSubcommands]),
185 Command.withSharedFlags({ userId, projectName }),
186 Command.provide(({ userId, projectName }) => CommandSurface.dev({ userId, projectName }))
187 )
ts/packages/cli/src/commands/generate/generate.cmd.ts
+2 -1
@@ -2,6 +2,7 @@ import { Command, Flag } from 'effect/cli';
2 import { runGenerate } from './generate.handler';
3 import { generateCmd$Py } from './py/generate.py.cmd';
4 import { generateCmd$Ts } from './ts/generate.ts.cmd';
5 +import { withRegisteredSubcommands } from 'src/commands/registration';
6
7 const outputDir = Flag.optional(Flag.Directory('output-dir')).pipe(
8 Flag.withAlias('o'),
@@ -44,5 +45,5 @@ export const generateCmd = Command.make(
45 Command.withDescription(
46 'Generate type stubs for toolkits, tools, and triggers, auto-detecting project language (TypeScript | Python)'
47 ),
47 - Command.withSubcommands([generateCmd$Py, generateCmd$Ts])
48 + withRegisteredSubcommands([generateCmd$Py, generateCmd$Ts])
49 );
ts/packages/cli/src/commands/index.ts
+27 -23
@@ -1,5 +1,7 @@
1 -import { Array as Arr, Console, Effect, Layer } from 'effect';
2 -import { CliOutput, Command } from 'effect/cli';
1 +import { Array as Arr, Console, Effect } from 'effect';
2 +import { CliError, CliOutput, Command } from 'effect/cli';
3 +import type { TelemetryFamily } from 'src/analytics/types';
4 +import { beginAtCommandPath, withCommandMeta } from 'src/invocation/command-identity';
5 import { $defaultCmd, withRootLogLevel } from './$default.cmd';
6 import { getVersion } from 'src/effects/version';
7 import { versionCmd } from './version.cmd';
@@ -34,7 +36,6 @@ import { configCmd } from './config/config.cmd';
36 import { rootConnectionsCmd } from './connections/connections.cmd';
37 import { agentCmd } from './agent/agent.cmd';
38 import { cliDebugFlagsLayer, CLI_DEBUG_GLOBAL_FLAGS } from 'src/services/runtime-flags';
37 -import { cliRunIdLayer } from 'src/services/runtime-cli-context';
39 import { ComposioCliUserConfig } from 'src/services/cli-user-config';
40 import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
41 import { experimental, type CommandVisibility, tagged, visibleValues } from './feature-tags';
@@ -44,26 +45,31 @@ import { normalizeListenStreamFlag, normalizeRunScriptArgs } from './argv-compat
45 import { configureCliAnalyticsReleaseVersion } from 'src/analytics/events';
46 import { CommandSurface } from './surface';
47
48 +// Lifecycle telemetry families are declared on root registrations only: every `dev` command,
49 +// including `dev connected-accounts link` (the same `Command` value as the root `link`), reports the
50 +// generic `CLI_COMMAND_*` events.
51 +const family = (telemetryFamily: TelemetryFamily) => withCommandMeta({ telemetryFamily });
52 +
53 const ROOT_COMMANDS = [
54 tagged(debugCmd),
55 tagged(versionCmd),
56 tagged(upgradeCmd),
57 tagged(whoamiCmd),
52 - tagged(loginCmd),
58 + tagged(loginCmd.pipe(family('login'))),
59 tagged(signupCmd),
54 - tagged(setupCmd),
60 + tagged(setupCmd.pipe(family('setup'))),
61 tagged(agentCmd),
62 experimental(CLI_EXPERIMENTAL_FEATURES.LISTEN, listenCmd),
57 - tagged(logoutCmd),
58 - tagged(runCmd),
59 - tagged(proxyCmd),
63 + tagged(logoutCmd.pipe(family('logout'))),
64 + tagged(runCmd.pipe(family('run'))),
65 + tagged(proxyCmd.pipe(family('proxy'))),
66 tagged(artifactsCmd),
61 - tagged(installCmd),
67 + tagged(installCmd.pipe(family('install'))),
68 tagged(rootToolsCmd),
69 tagged(rootTriggersCmd),
64 - tagged(toolsCmd$Search),
65 - tagged(connectedAccountsCmd$Link),
66 - tagged(rootToolsCmd$Execute),
70 + tagged(toolsCmd$Search.pipe(family('search'))),
71 + tagged(connectedAccountsCmd$Link.pipe(family('link'))),
72 + tagged(rootToolsCmd$Execute.pipe(family('execute'))),
73 tagged(rootConnectionsCmd),
74 tagged(generateCmd),
75 tagged(orgsCmd),
@@ -92,15 +98,6 @@ export const buildRootCommand = (visibility: CommandVisibility) => {
98 );
99 };
100
95 -/**
96 - * Values the CLI bootstrap resolved before the root command runs and that the command tree needs
97 - * as an input. Optional for callers that drive the root command directly in tests.
98 - */
99 -export type RootCommandBootstrap = {
100 - /** Run id minted for a `composio run` invocation, shared with its telemetry events. */
101 - readonly runId?: string;
102 -};
103 -
101 export const runWithConfig = Effect.gen(function* () {
102 const cliUserConfig = yield* ComposioCliUserConfig;
103 const visibility: CommandVisibility = {
@@ -115,6 +112,13 @@ export const runWithConfig = Effect.gen(function* () {
112 // prefix — see `cli-main.ts` module docs for the full contract at this boundary.
113 const run = (args: ReadonlyArray<string>) => {
114 return Command.runWith(rootCommand, { version })(args).pipe(
115 + // A parse failure selects no command: begin the one `effect/cli` names (canonical names,
116 + // never the user's tokens). After a command began, this changes nothing.
117 + Effect.tapError(error =>
118 + error instanceof CliError.ShowHelp
119 + ? beginAtCommandPath(rootCommand, error.commandPath)
120 + : Effect.void
121 + ),
122 Effect.provideService(RootHelpContext, { command: rootCommand, version }),
123 Effect.provideService(CliOutput.Formatter, helpFormatter())
124 );
@@ -142,11 +146,11 @@ export const runWithConfig = Effect.gen(function* () {
146 ? run(args)
147 : runWithDecorationOnStderr(args);
148
145 - return (argv: ReadonlyArray<string>, bootstrap: RootCommandBootstrap = {}) => {
149 + return (argv: ReadonlyArray<string>) => {
150 const parsedArgv = normalizeRunScriptArgs(normalizeListenStreamFlag(argv));
151 return runCli(parsedArgv.slice(2)).pipe(
152 Effect.provideService(ExecuteInvocationArgs, parsedArgv.slice(2)),
149 - Effect.provide(Layer.merge(cliDebugFlagsLayer(), cliRunIdLayer(bootstrap.runId)))
153 + Effect.provide(cliDebugFlagsLayer())
154 );
155 };
156 });
ts/packages/cli/src/commands/logs/logs.cmd.ts
+2 -1
@@ -2,6 +2,7 @@ import { Command } from 'effect/cli';
2 import { requireLogin } from 'src/effects/require-auth';
3 import { logsCmd$Tools } from './tools/logs.tools.cmd';
4 import { logsCmd$Triggers } from './triggers/logs.triggers.cmd';
5 +import { withRegisteredSubcommands } from 'src/commands/registration';
6
7 /**
8 * CLI entry point for logs commands.
@@ -13,6 +14,6 @@ import { logsCmd$Triggers } from './triggers/logs.triggers.cmd';
14 */
15 export const logsCmd = Command.make('logs').pipe(
16 Command.withDescription('Inspect trigger and tool execution logs.'),
16 - Command.withSubcommands([logsCmd$Triggers, logsCmd$Tools]),
17 + withRegisteredSubcommands([logsCmd$Triggers, logsCmd$Tools]),
18 requireLogin
19 );
ts/packages/cli/src/commands/orgs/orgs.cmd.ts
+2 -1
@@ -2,12 +2,13 @@ import { requireLogin } from 'src/effects/require-auth';
2 import { Command } from 'effect/cli';
3 import { orgsCmd$List } from './list/orgs.list.cmd';
4 import { orgsCmd$Switch } from './switch/orgs.switch.cmd';
5 +import { withRegisteredSubcommands } from 'src/commands/registration';
6
7 /**
8 * CLI entry point for organization context commands.
9 */
10 export const orgsCmd = Command.make('orgs').pipe(
11 Command.withDescription('Manage default global organization/project context.'),
11 - Command.withSubcommands([orgsCmd$List, orgsCmd$Switch]),
12 + withRegisteredSubcommands([orgsCmd$List, orgsCmd$Switch]),
13 requireLogin
14 );
ts/packages/cli/src/commands/projects/projects.cmd.ts
+2 -1
@@ -1,11 +1,12 @@
1 import { Command } from 'effect/cli';
2 import { projectsCmd$List } from './list/projects.list.cmd';
3 import { projectsCmd$Switch } from './switch/projects.switch.cmd';
4 +import { withRegisteredSubcommands } from 'src/commands/registration';
5
6 /**
7 * CLI entry point for project context commands.
8 */
9 export const projectsCmd = Command.make('projects').pipe(
10 Command.withDescription('Inspect developer projects and project context helpers.'),
10 - Command.withSubcommands([projectsCmd$List, projectsCmd$Switch])
11 + withRegisteredSubcommands([projectsCmd$List, projectsCmd$Switch])
12 );
ts/packages/cli/src/commands/registration.ts new
+82
@@ -0,0 +1,82 @@
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 { NotLoggedInError } from 'src/commands/errors';
15 +import { assertLoggedIn } from 'src/effects/require-auth';
16 +import {
17 + childIdentity,
18 + CommandInvocation,
19 + CommandRegistration,
20 +} from 'src/invocation/command-identity';
21 +import type { ComposioUserContext } from 'src/services/user-context';
22 +
23 +/**
24 + * Records the running registration as the command this invocation runs, then enforces what its
25 + * `CommandMeta` requires: a login fails after the identity is recorded, so `NotLoggedInError`
26 + * is reported against the command the user ran.
27 + */
28 +const beginSelected = (input: unknown) =>
29 + Effect.gen(function* () {
30 + const identity = yield* CommandRegistration;
31 + const invocation = yield* CommandInvocation;
32 + yield* invocation.begin(identity, Option.some(input));
33 + if (identity.meta.requiresLogin) {
34 + yield* assertLoggedIn;
35 + }
36 + });
37 +
38 +/** A command as a group registers it: its handler may now fail with `NotLoggedInError`. */
39 +export type Registered<C> =
40 + C extends Command.Command<infer Name, infer Input, infer ContextInput, infer E, infer R>
41 + ? Command.Command<Name, Input, ContextInput, E | NotLoggedInError, R | ComposioUserContext>
42 + : never;
43 +
44 +/**
45 + * Registers `child` under the registration whose dispatch runs it. A group (a command with
46 + * subcommands) begins its own handler in `withRegisteredSubcommands`.
47 + */
48 +const registerSubcommand = <C extends Command.Command.Any>(child: C): Registered<C> => {
49 + const command = child as unknown as Command.Command<string, unknown, unknown, unknown, unknown>;
50 + const begun =
51 + command.subcommands.length === 0
52 + ? Command.provideEffectDiscard(command, beginSelected)
53 + : command;
54 + return Command.provideEffect(
55 + begun,
56 + CommandRegistration,
57 + Effect.gen(function* () {
58 + const identity = childIdentity(yield* CommandRegistration, command);
59 + const invocation = yield* CommandInvocation;
60 + yield* invocation.enter(identity);
61 + return identity;
62 + })
63 + ) as unknown as Registered<C>;
64 +};
65 +
66 +/**
67 + * `Command.withSubcommands` for the command tree: registers each subcommand under `self` with
68 + * its own identity, and begins `self`'s own handler (a group's default action, or the help
69 + * `effect/cli` shows for a bare group) when no subcommand is selected. Every group in the tree
70 + * registers its subcommands with it.
71 + */
72 +export const withRegisteredSubcommands =
73 + <const Subcommands extends ReadonlyArray<Command.Command.Any>>(subcommands: Subcommands) =>
74 + <const Name extends string, Input, ContextInput, E, R>(
75 + self: Command.Command<Name, Input, ContextInput, E, R>
76 + ) =>
77 + Command.withSubcommands(
78 + Command.provideEffectDiscard(self, beginSelected),
79 + subcommands.map(child =>
80 + registerSubcommand<Subcommands[number]>(child)
81 + ) satisfies ReadonlyArray<Registered<Subcommands[number]>>
82 + );
ts/packages/cli/src/commands/root-help.ts
+36 -10
@@ -1,5 +1,9 @@
1 import { Console, Context, Effect } from 'effect';
2 import { CliConfig, CliOutput, Command, GlobalFlag } from 'effect/cli';
3 +import type { NotLoggedInError } from 'src/commands/errors';
4 +import { beginAtCommandPath } from 'src/invocation/command-identity';
5 +import type { ComposioUserContext } from 'src/services/user-context';
6 +import { withRegisteredSubcommands } from 'src/commands/registration';
7
8 export const RootHelpMarker = Context.Reference<boolean>('commands/RootHelpMarker', {
9 defaultValue: () => false,
@@ -53,10 +57,16 @@ export const buildHelpCommand = (commands: ReadonlyArray<Command.Command.Any>) =
57 path: ReadonlyArray<string>,
58 subcommands: ReadonlyArray<Command.Command.Any>,
59 description: string | undefined
56 - ): Command.Command<string, Record<never, never>, Record<never, never>, never, RootHelpContext> =>
60 + ): Command.Command<
61 + string,
62 + Record<never, never>,
63 + Record<never, never>,
64 + NotLoggedInError,
65 + RootHelpContext | ComposioUserContext
66 + > =>
67 Command.make(name, {}, () => showCommandHelp(path)).pipe(
68 Command.withDescription(description ?? 'Show command help.'),
59 - Command.withSubcommands(
69 + withRegisteredSubcommands(
70 subcommands.map(child => {
71 const help = makeHelpCommand(
72 child.name,
@@ -72,15 +82,31 @@ export const buildHelpCommand = (commands: ReadonlyArray<Command.Command.Any>) =
82 return makeHelpCommand('help', [], commands, 'Show help for a command.');
83 };
84
75 -/** A help flag on the help alias describes the requested command. */
85 +/**
86 + * `--help`: begins the command whose help it shows (no handler runs, so nothing else records
87 + * it). A help flag on the help alias describes the requested command.
88 + */
89 export const Help = GlobalFlag.Action({
90 flag: GlobalFlag.Help.flag,
91 run: (value, context) =>
79 - GlobalFlag.Help.run(value, {
80 - ...context,
81 - commandPath:
82 - context.commandPath[1] === 'help'
83 - ? [context.commandPath[0], ...context.commandPath.slice(2)]
84 - : context.commandPath,
85 - }),
92 + beginAtCommandPath(context.command, context.commandPath).pipe(
93 + Effect.andThen(
94 + GlobalFlag.Help.run(value, {
95 + ...context,
96 + commandPath:
97 + context.commandPath[1] === 'help'
98 + ? [context.commandPath[0], ...context.commandPath.slice(2)]
99 + : context.commandPath,
100 + })
101 + )
102 + ),
103 +});
104 +
105 +/** `--version`: begins the command it was given on (no handler runs), then prints the version. */
106 +export const Version = GlobalFlag.Action({
107 + flag: GlobalFlag.Version.flag,
108 + run: (value, context) =>
109 + beginAtCommandPath(context.command, context.commandPath).pipe(
110 + Effect.andThen(GlobalFlag.Version.run(value, context))
111 + ),
112 });
ts/packages/cli/src/commands/run.cmd.ts
+3 -2
@@ -28,7 +28,8 @@ import {
28 isTelemetryDebugEnabled,
29 isToolDebugEnabled,
30 } from 'src/services/runtime-flags';
31 -import { cliInvocationContext, CliRunId } from 'src/services/runtime-cli-context';
31 +import { cliInvocationContext } from 'src/services/runtime-cli-context';
32 +import { invocationRunId } from 'src/invocation/command-identity';
33 import {
34 repairMissingInstalledRunCompanionModules,
35 resolveRunCompanionModulePath,
@@ -482,7 +483,7 @@ export const runCmd = Command.make('run', {
483 const path = yield* Path.Path;
484 const invocation = yield* cliInvocationContext;
485 const runId = Option.getOrElse(
485 - yield* CliRunId,
486 + yield* invocationRunId,
487 () => invocation.parentRunId ?? crypto.randomUUID()
488 );
489 const perfDebug = yield* isPerfDebugEnabled;
ts/packages/cli/src/commands/setup.cmd.ts
+2 -1
@@ -25,6 +25,7 @@ import { SetupCommandError, type SetupFailureReasonCode } from 'src/services/set
25 import { TerminalUI } from 'src/services/terminal-ui';
26 import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
27 import { cliInvocationContext } from 'src/services/runtime-cli-context';
28 +import { withRegisteredSubcommands } from 'src/commands/registration';
29
30 const target = Flag.Literals('target', SETUP_TARGETS).pipe(
31 Flag.withDefault('auto'),
@@ -351,5 +352,5 @@ export const setupCmd = setupBaseCmd.pipe(
352 command: 'composio setup --target all',
353 },
354 ]),
354 - Command.withSubcommands([setupSkillCmd])
355 + withRegisteredSubcommands([setupSkillCmd])
356 );
ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts
+2 -1
@@ -5,6 +5,7 @@ import { toolkitsCmd$List } from './list/toolkits.list.cmd';
5 import { toolkitsCmd$Info } from './info/toolkits.info.cmd';
6 import { toolkitsCmd$Search } from './search/toolkits.search.cmd';
7 import { toolkitsCmd$Version } from './version/toolkits.version.cmd';
8 +import { withRegisteredSubcommands } from 'src/commands/registration';
9
10 /**
11 * CLI entry point for toolkit discovery commands.
@@ -16,7 +17,7 @@ import { toolkitsCmd$Version } from './version/toolkits.version.cmd';
17 */
18 export const toolkitsCmd = Command.make('toolkits').pipe(
19 Command.withDescription('Discover and inspect Composio toolkits.'),
19 - Command.withSubcommands([
20 + withRegisteredSubcommands([
21 toolkitsCmd$List,
22 toolkitsCmd$Info,
23 toolkitsCmd$Search.pipe(rejectsSharedFlags('dev toolkits search')),
ts/packages/cli/src/commands/tools/tools.cmd.ts
+2 -1
@@ -2,6 +2,7 @@ import { requireLogin } from 'src/effects/require-auth';
2 import { Command } from 'effect/cli';
3 import { toolsCmd$List } from './list/tools.list.cmd';
4 import { toolsCmd$Info } from './info/tools.info.cmd';
5 +import { withRegisteredSubcommands } from 'src/commands/registration';
6
7 export const rootToolsCmd = Command.make('tools').pipe(
8 Command.withDescription('Browse and inspect tools before executing them.'),
@@ -13,6 +14,6 @@ export const rootToolsCmd = Command.make('tools').pipe(
14 command: 'composio tools info GMAIL_SEND_EMAIL',
15 },
16 ]),
16 - Command.withSubcommands([toolsCmd$List, toolsCmd$Info]),
17 + withRegisteredSubcommands([toolsCmd$List, toolsCmd$Info]),
18 requireLogin
19 );
ts/packages/cli/src/commands/triggers/root-triggers.cmd.ts
+2 -1
@@ -2,9 +2,10 @@ import { requireLogin } from 'src/effects/require-auth';
2 import { Command } from 'effect/cli';
3 import { triggersCmd$Info } from './info/triggers.info.cmd';
4 import { triggersCmd$List } from './list/triggers.list.cmd';
5 +import { withRegisteredSubcommands } from 'src/commands/registration';
6
7 export const rootTriggersCmd = Command.make('triggers').pipe(
8 Command.withDescription('Browse and inspect trigger types before creating subscriptions.'),
8 - Command.withSubcommands([triggersCmd$List, triggersCmd$Info]),
9 + withRegisteredSubcommands([triggersCmd$List, triggersCmd$Info]),
10 requireLogin
11 );
ts/packages/cli/src/commands/triggers/triggers.cmd.ts
+2 -1
@@ -8,6 +8,7 @@ import { triggersCmd$Create } from './create/triggers.create.cmd';
8 import { triggersCmd$Enable } from './enable/triggers.enable.cmd';
9 import { triggersCmd$Disable } from './disable/triggers.disable.cmd';
10 import { triggersCmd$Listen } from './commands/triggers.listen.cmd';
11 +import { withRegisteredSubcommands } from 'src/commands/registration';
12
13 /**
14 * CLI entry point for realtime trigger commands.
@@ -19,7 +20,7 @@ import { triggersCmd$Listen } from './commands/triggers.listen.cmd';
20 */
21 export const triggersCmd = Command.make('triggers').pipe(
22 Command.withDescription('Inspect and subscribe to trigger events.'),
22 - Command.withSubcommands([
23 + withRegisteredSubcommands([
24 triggersCmd$Listen,
25 triggersCmd$List.pipe(rejectsSharedFlags('dev triggers list')),
26 triggersCmd$Info.pipe(rejectsSharedFlags('dev triggers info')),
ts/packages/cli/src/effects/require-auth.ts
+6 -6
@@ -1,6 +1,6 @@
1 import { Effect } from 'effect';
2 -import { Command } from 'effect/cli';
2 import { notLoggedIn } from 'src/commands/errors';
3 +import { withCommandMeta } from 'src/invocation/command-identity';
4 import { ComposioUserContext } from 'src/services/user-context';
5
6 /** Fails with `NotLoggedInError` when `~/.composio` holds no API key. */
@@ -13,9 +13,9 @@ export const assertLoggedIn = Effect.gen(function* () {
13
14 /**
15 * Makes a command, or a group entry and every subcommand under it, require a logged-in user.
16 - * Pipe it after `Command.withSubcommands`, since it wraps the handler that exists when it is
17 - * applied. The handler then never checks `apiKey` or prints a login hint.
16 + * It declares `requiresLogin` in the command's `CommandMeta`; the registration that runs the
17 + * command checks the login right after recording the command's identity
18 + * (`src/commands/registration.ts`), so `NotLoggedInError` names the command the user ran. The
19 + * handler then never checks `apiKey` or prints a login hint.
20 */
19 -export const requireLogin = <const Name extends string, Input, ContextInput, E, R>(
20 - self: Command.Command<Name, Input, ContextInput, E, R>
21 -) => Command.provideEffectDiscard(self, assertLoggedIn);
21 +export const requireLogin = withCommandMeta({ requiresLogin: true });
ts/packages/cli/src/invocation/command-identity.ts new
+177
@@ -0,0 +1,177 @@
1 +/**
2 + * Which command an invocation runs, learned after `effect/cli` parsed argv (see
3 + * `docs/adr/0001-command-identity-after-parse.md`).
4 + *
5 + * A command's identity is its command registration: the command path from the root plus the
6 + * `CommandMeta` it declares and inherits. `withRegisteredSubcommands`
7 + * (`src/commands/registration.ts`) gives every registration its identity while the parser's
8 + * selection is dispatched, and only the selected command calls `CommandInvocation.begin`. `--help`,
9 + * `--version`, and parse failures have no selected handler; they resolve the identity from the
10 + * command path `effect/cli` hands them (`identityAt`).
11 + */
12 +import { Array as Arr, Context, Effect, Option } from 'effect';
13 +import { Command } from 'effect/cli';
14 +import type { TelemetryFamily } from 'src/analytics/types';
15 +
16 +/**
17 + * What a command declares about itself, under one annotation key (`Command.annotate`, or
18 + * `withCommandMeta` in `src/commands/registration.ts`). Every field is optional; what an
19 + * absent field means is set once, in `resolveCommandMeta`.
20 + */
21 +export interface CommandMetaShape {
22 + /**
23 + * The family of lifecycle events the command reports (`CLI_EXECUTE_*`, `CLI_LINK_*`, …).
24 + * Not inherited: a subcommand reports its own family, the generic `command` by default.
25 + */
26 + readonly telemetryFamily?: TelemetryFamily;
27 + /**
28 + * Whether the command needs a logged-in user (`requireLogin`). Inherited: a group's
29 + * subcommands need one too.
30 + */
31 + readonly requiresLogin?: boolean;
32 +}
33 +
34 +export const CommandMeta = Context.Reference<CommandMetaShape>('commands/CommandMeta', {
35 + defaultValue: () => ({}),
36 +});
37 +
38 +/** `CommandMetaShape` with every field decided for one registration. */
39 +export interface ResolvedCommandMeta {
40 + readonly telemetryFamily: TelemetryFamily;
41 + readonly requiresLogin: boolean;
42 +}
43 +
44 +/** Resolves what a command declares (`own`) under a parent registration's resolved meta. */
45 +export const resolveCommandMeta = (
46 + parent: ResolvedCommandMeta | undefined,
47 + own: CommandMetaShape
48 +): ResolvedCommandMeta => ({
49 + telemetryFamily: own.telemetryFamily ?? 'command',
50 + requiresLogin: own.requiresLogin ?? parent?.requiresLogin ?? false,
51 +});
52 +
53 +/** The meta `command` declares on itself. */
54 +export const commandMetaOf = (command: Command.Command.Any): CommandMetaShape =>
55 + Context.get(command.annotations, CommandMeta);
56 +
57 +/** Adds `meta` to what `self` already declares in its `CommandMeta` annotation. */
58 +export const withCommandMeta =
59 + (meta: CommandMetaShape) =>
60 + <const Name extends string, Input, ContextInput, E, R>(
61 + self: Command.Command<Name, Input, ContextInput, E, R>
62 + ): Command.Command<Name, Input, ContextInput, E, R> =>
63 + Command.annotate(self, CommandMeta, { ...commandMetaOf(self), ...meta });
64 +
65 +/** One command registration: where a command sits in the tree and what applies to it there. */
66 +export interface CommandIdentity {
67 + /** Canonical command names below `composio`; empty for the root command. */
68 + readonly path: ReadonlyArray<string>;
69 + readonly meta: ResolvedCommandMeta;
70 +}
71 +
72 +/** The root command's identity; the root declares no `CommandMeta`. */
73 +export const ROOT_IDENTITY: CommandIdentity = {
74 + path: [],
75 + meta: resolveCommandMeta(undefined, {}),
76 +};
77 +
78 +/** The identity of `child` registered under `parent`. */
79 +export const childIdentity = (
80 + parent: CommandIdentity,
81 + child: Command.Command.Any
82 +): CommandIdentity => ({
83 + path: [...parent.path, child.name],
84 + meta: resolveCommandMeta(parent.meta, commandMetaOf(child)),
85 +});
86 +
87 +/** The command path as telemetry records it: the names joined by spaces, `composio` for the root. */
88 +export const commandPathOf = (identity: CommandIdentity): string =>
89 + identity.path.length === 0 ? 'composio' : identity.path.join(' ');
90 +
91 +const subcommandNamed = (command: Command.Command.Any, name: string) =>
92 + Arr.findFirst(
93 + command.subcommands.flatMap(group => group.commands),
94 + child => child.name === name
95 + );
96 +
97 +/**
98 + * The identity of the registration `effect/cli` names by `commandPath` (canonical names, the root
99 + * command's name first, as in `CliError.ShowHelp` and `GlobalFlag.HandlerContext`), found by
100 + * walking `root`'s public subcommands. Stops at the deepest name the tree knows.
101 + */
102 +export const identityAt = (
103 + root: Command.Command.Any,
104 + commandPath: ReadonlyArray<string>
105 +): CommandIdentity => {
106 + const walk = (
107 + node: Command.Command.Any,
108 + identity: CommandIdentity,
109 + names: ReadonlyArray<string>
110 + ): CommandIdentity =>
111 + Arr.matchLeft(names, {
112 + onEmpty: () => identity,
113 + onNonEmpty: (name, rest) =>
114 + Option.match(subcommandNamed(node, name), {
115 + onNone: () => identity,
116 + onSome: child => walk(child, childIdentity(identity, child), rest),
117 + }),
118 + });
119 + return walk(root, ROOT_IDENTITY, commandPath.slice(1));
120 +};
121 +
122 +/**
123 + * The identity of the registration whose dispatch is running: provided by every registration to
124 + * everything below it (`src/commands/registration.ts`), the root's outside any.
125 + */
126 +export const CommandRegistration = Context.Reference<CommandIdentity>(
127 + 'commands/CommandRegistration',
128 + { defaultValue: () => ROOT_IDENTITY }
129 +);
130 +
131 +/**
132 + * The invocation's record of the command it runs. `runInvocation` provides it for one
133 + * invocation; outside one (a test that drives a command directly) it records nothing.
134 + */
135 +export interface CommandInvocationShape {
136 + /**
137 + * Records `identity` as the command this invocation runs, with the input `effect/cli` parsed
138 + * for it (none for help, version, and parse failures), and reports that it started. Only the
139 + * first call counts. Never fails.
140 + */
141 + readonly begin: (identity: CommandIdentity, input: Option.Option<unknown>) => Effect.Effect<void>;
142 + /**
143 + * Notes that the dispatch of the registration `identity` started. Before `begin`, the deepest
144 + * registration entered is what a failure is reported against: a group-level check that fails
145 + * before the parser's selection is reached.
146 + */
147 + readonly enter: (identity: CommandIdentity) => Effect.Effect<void>;
148 + /** The run id `begin` minted for `composio run`, shared with its telemetry events. */
149 + readonly runId: Effect.Effect<Option.Option<string>>;
150 +}
151 +
152 +export const CommandInvocation = Context.Reference<CommandInvocationShape>(
153 + 'invocation/CommandInvocation',
154 + {
155 + defaultValue: () => ({
156 + begin: () => Effect.void,
157 + enter: () => Effect.void,
158 + runId: Effect.succeedNone,
159 + }),
160 + }
161 +);
162 +
163 +/** Begins the command `commandPath` names, for an invocation `effect/cli` answers without one. */
164 +export const beginAtCommandPath = (
165 + root: Command.Command.Any,
166 + commandPath: ReadonlyArray<string>
167 +): Effect.Effect<void> =>
168 + Effect.gen(function* () {
169 + const invocation = yield* CommandInvocation;
170 + yield* invocation.begin(identityAt(root, commandPath), Option.none());
171 + });
172 +
173 +/** The run id of the running `composio run`, if this invocation is one. */
174 +export const invocationRunId: Effect.Effect<Option.Option<string>> = Effect.gen(function* () {
175 + const invocation = yield* CommandInvocation;
176 + return yield* invocation.runId;
177 +});
ts/packages/cli/src/invocation/invocation.ts
+82 -27
@@ -10,29 +10,37 @@
10 * its own cause, so a caller can still match its typed error; `forRunner` turns it into what the
11 * runner needs to print nothing more and exit with the right code.
12 */
13 -import { Cause, Effect, Exit, Option, Runtime, type Layer } from 'effect';
13 +import { Cause, Effect, Exit, Option, Ref, Runtime, type Layer } from 'effect';
14 import { CliError } from 'effect/cli';
15 import { captureErrors, prettyPrintFromCapturedErrors } from 'effect-errors/index';
16 import {
17 configureCliAnalyticsReleaseVersion,
18 createCliCommandTelemetryContext,
19 - getExecuteCommandToolSlug,
19 } from 'src/analytics/events';
21 -import { runWithConfig, type RootCommandBootstrap } from 'src/commands';
20 +import type { CliCommandTelemetryContext } from 'src/analytics/types';
21 +import { runWithConfig } from 'src/commands';
22 import * as constants from 'src/constants';
23 import { isExpectedFailure } from 'src/effects/expected-failure';
24 import { isRejectedUserApiKey, rejectedUserApiKeyHint } from 'src/effects/rejected-user-api-key';
25 import { ReportedFailure } from 'src/effects/report-failure';
26 import { toolkitFromToolSlug } from 'src/effects/toolkit-from-tool-slug';
27 import { getVersion } from 'src/effects/version';
28 +import {
29 + type CommandIdentity,
30 + CommandInvocation,
31 + type CommandInvocationShape,
32 + ROOT_IDENTITY,
33 +} from 'src/invocation/command-identity';
34 import { BackendMismatchWarning } from 'src/services/backend-mismatch-warning';
35 import { CommandLifecycleTelemetry } from 'src/services/command-lifecycle-telemetry';
36 +import type { ComposioToolkitsRepository } from 'src/services/composio-clients';
37 import { mapOnlyComposioOverrideError } from 'src/services/composio-error-overrides';
38 import type { HookInvocation } from 'src/services/invocation-hook';
39 import { PluginHint } from 'src/services/plugin-hint';
40 import { cliInvocationContext } from 'src/services/runtime-cli-context';
41 import type { ShutdownSignal } from 'src/services/shutdown-signal';
42 import { TerminalUI } from 'src/services/terminal-ui';
43 +import type { ToolkitSlugCatalog } from 'src/services/toolkit-slug-catalog';
44 import { UpdateNotice } from 'src/services/update-check';
45 import { extractMessage } from 'src/utils/api-error-extraction';
46 import type { InvocationLive } from './live';
@@ -46,46 +54,93 @@ export type InvocationServices = Layer.Success<typeof InvocationLive> | Shutdown
54 // `any` is otherwise infectious through the rest of this pipeline, so it is pinned here to the
55 // services an invocation is given — this changes nothing at runtime, it only restores the
56 // precise static type that inference failed to produce on its own.
49 -const runWithArgs = (argv: ReadonlyArray<string>, bootstrap: RootCommandBootstrap) =>
50 - Effect.flatMap(runWithConfig, run => run(argv, bootstrap)) as Effect.Effect<
57 +const runWithArgs = (argv: ReadonlyArray<string>) =>
58 + Effect.flatMap(runWithConfig, run => run(argv)) as Effect.Effect<
59 void,
60 unknown,
61 InvocationServices
62 >;
63
64 +/**
65 + * Runs the command `effect/cli` selects for `argv` under its lifecycle telemetry. The command's
66 + * identity is known only once the parser selected it: the selected registration calls
67 + * `CommandInvocation.begin` (`src/commands/registration.ts`), and so do `--help`, `--version`,
68 + * and a parse failure, for the command path `effect/cli` gives them. `begin` reports the invoked
69 + * event; the outcome is reported for the same command. A failure before any `begin` (a group-level
70 + * check) is reported against the deepest registration whose dispatch started.
71 + */
72 const runWithTelemetry = (argv: ReadonlyArray<string>) =>
73 Effect.gen(function* () {
74 const ui = yield* TerminalUI;
75 const terminal = yield* ui.capabilities;
60 -
76 const version = yield* getVersion;
77 configureCliAnalyticsReleaseVersion(version);
63 - const baseTelemetryContext = createCliCommandTelemetryContext(
64 - argv,
65 - version,
66 - terminal,
67 - yield* cliInvocationContext
68 - );
69 - const executeToolSlug = getExecuteCommandToolSlug(baseTelemetryContext);
70 - const commandTelemetryContext =
71 - executeToolSlug === undefined
72 - ? baseTelemetryContext
73 - : { ...baseTelemetryContext, toolkitSlug: yield* toolkitFromToolSlug(executeToolSlug) };
74 - // `composio run` mints its run id here so the lifecycle events and the id the spawned script
75 - // inherits are the same value; every other command leaves it unset.
76 - const bootstrap: RootCommandBootstrap =
77 - commandTelemetryContext.commandPath === 'run' && commandTelemetryContext.runId
78 - ? { runId: commandTelemetryContext.runId }
79 - : {};
78 + const invocationContext = yield* cliInvocationContext;
79 const telemetry = yield* CommandLifecycleTelemetry;
81 - return yield* telemetry.invoked(commandTelemetryContext).pipe(
82 - Effect.andThen(runWithArgs(argv, bootstrap)),
80 + const toolkitLookup = yield* Effect.context<ComposioToolkitsRepository | ToolkitSlugCatalog>();
81 + const startedAt = Date.now();
82 +
83 + const contextFor = (identity: CommandIdentity, input: Option.Option<unknown>) =>
84 + Effect.gen(function* () {
85 + const context = createCliCommandTelemetryContext({
86 + argv,
87 + cliVersion: version,
88 + terminal,
89 + invocation: invocationContext,
90 + identity,
91 + input,
92 + startedAt,
93 + });
94 + if (context.family !== 'execute' || context.argument === undefined) {
95 + return context;
96 + }
97 + const toolkitSlug = yield* toolkitFromToolSlug(context.argument).pipe(
98 + Effect.provideContext(toolkitLookup)
99 + );
100 + return { ...context, toolkitSlug };
101 + });
102 +
103 + const started = yield* Ref.make(Option.none<CliCommandTelemetryContext>());
104 + const entered = yield* Ref.make(ROOT_IDENTITY);
105 + const start = (identity: CommandIdentity, input: Option.Option<unknown>) =>
106 + contextFor(identity, input).pipe(
107 + Effect.tap(context => Ref.set(started, Option.some(context))),
108 + Effect.tap(context => telemetry.invoked(context))
109 + );
110 + const invocation: CommandInvocationShape = {
111 + // Only the first command to begin counts: the bare group whose help ended in `ShowHelp`.
112 + begin: (identity, input) =>
113 + Effect.flatMap(Ref.get(started), current =>
114 + Option.match(current, {
115 + onSome: () => Effect.void,
116 + onNone: () => Effect.asVoid(start(identity, input)),
117 + })
118 + ),
119 + enter: identity => Ref.set(entered, identity),
120 + runId: Effect.map(
121 + Ref.get(started),
122 + Option.flatMap(context => Option.fromNullishOr(context.runId))
123 + ),
124 + };
125 + // The command the outcome is reported for: the one that began, else the deepest registration
126 + // entered, begun now so its invoked event still precedes the outcome.
127 + const outcomeContext = Effect.flatMap(Ref.get(started), current =>
128 + Option.match(current, {
129 + onSome: Effect.succeed,
130 + onNone: () => Effect.flatMap(Ref.get(entered), identity => start(identity, Option.none())),
131 + })
132 + );
133 +
134 + return yield* runWithArgs(argv).pipe(
135 + Effect.provideService(CommandInvocation, invocation),
136 Effect.scoped,
137 Effect.mapError(error =>
138 CliError.isCliError(error) ? error : mapOnlyComposioOverrideError({ error })
139 ),
87 - Effect.tap(() => telemetry.succeeded(commandTelemetryContext)),
88 - Effect.tapCause(cause => telemetry.failed(commandTelemetryContext, cause))
140 + Effect.tap(() => Effect.flatMap(outcomeContext, context => telemetry.succeeded(context))),
141 + Effect.tapCause(cause =>
142 + Effect.flatMap(outcomeContext, context => telemetry.failed(context, cause))
143 + )
144 );
145 });
146
ts/packages/cli/src/services/runtime-cli-context.ts
+1 -16
@@ -1,4 +1,4 @@
1 -import { Context, Effect, Layer, Option } from 'effect';
1 +import { Effect } from 'effect';
2 import { APP_CONFIG } from 'src/config';
3
4 export const DEFAULT_CLI_INVOCATION_ORIGIN = 'cli';
@@ -25,18 +25,3 @@ export const cliInvocationContext: Effect.Effect<CliInvocationContext> = Effect.
25 parentRunId,
26 }))
27 );
28 -
29 -/**
30 - * Run id the bootstrap resolved for a `composio run` invocation.
31 - *
32 - * The invocation (`src/invocation/invocation.ts`) mints it while building the run's telemetry context and hands it to the command,
33 - * so the `CLI_RUN_*` events and the `COMPOSIO_CLI_PARENT_RUN_ID` the script's child process
34 - * inherits carry the same id. `None` for every other command, and for callers that drive the root
35 - * command directly.
36 - */
37 -export class CliRunId extends Context.Service<CliRunId, Option.Option<string>>()(
38 - 'services/CliRunId'
39 -) {}
40 -
41 -export const cliRunIdLayer = (runId: string | undefined): Layer.Layer<CliRunId> =>
42 - Layer.succeed(CliRunId, Option.fromNullishOr(runId));
ts/packages/cli/test/__utils__/telemetry-context.ts new
+39
@@ -0,0 +1,39 @@
1 +import { Option } from 'effect';
2 +import { createCliCommandTelemetryContext } from 'src/analytics/events';
3 +import type { TelemetryFamily } from 'src/analytics/types';
4 +import {
5 + DEFAULT_CLI_INVOCATION_ORIGIN,
6 + type CliInvocationContext,
7 +} from 'src/services/runtime-cli-context';
8 +
9 +/**
10 + * The lifecycle telemetry context of `args` (argv after `composio`) run as the command
11 + * registration `path` of `family`, with the input `effect/cli` parsed for it. `input` omitted
12 + * means nothing was parsed, as for `--help`, `--version`, and parse failures.
13 + */
14 +export const commandTelemetryContext = (
15 + args: ReadonlyArray<string>,
16 + options: {
17 + readonly path: ReadonlyArray<string>;
18 + readonly family?: TelemetryFamily;
19 + readonly input?: unknown;
20 + readonly cliVersion?: string;
21 + readonly terminal?: { readonly stdoutIsTTY: boolean; readonly stderrIsTTY: boolean };
22 + readonly invocation?: CliInvocationContext;
23 + }
24 +) =>
25 + createCliCommandTelemetryContext({
26 + argv: ['/bin/bun', '/cli/bin.ts', ...args],
27 + cliVersion: options.cliVersion ?? '1.2.3',
28 + terminal: options.terminal ?? { stdoutIsTTY: false, stderrIsTTY: false },
29 + invocation: options.invocation ?? {
30 + invocationOrigin: DEFAULT_CLI_INVOCATION_ORIGIN,
31 + parentRunId: undefined,
32 + },
33 + identity: {
34 + path: options.path,
35 + meta: { telemetryFamily: options.family ?? 'command', requiresLogin: false },
36 + },
37 + input: options.input === undefined ? Option.none() : Option.some(options.input),
38 + startedAt: Date.now(),
39 + });
ts/packages/cli/test/src/analytics.dispatch.test.ts
+10 -3
@@ -18,7 +18,7 @@ import {
18 trackCliEventEffect,
19 } from 'src/analytics/dispatch';
20 import { CLI_ANALYTICS_EVENTS } from 'src/analytics/events';
21 -import { cliRunIdLayer } from 'src/services/runtime-cli-context';
21 +import { CommandInvocation } from 'src/invocation/command-identity';
22 import { APP_VERSION, USER_CONFIG_FILE_NAME } from 'src/constants';
23 import { defaultNodeOs, NodeOs } from 'src/services/node-os';
24 import { TerminalUITest } from 'test/__utils__/services/terminal-ui-test';
@@ -447,7 +447,7 @@ describe('CLI analytics dispatch', () => {
447 });
448
449 it.effect(
450 - 'stamps codact failures with the minted CliRunId when no parent run id is inherited',
450 + 'stamps codact failures with the run id the command minted when no parent run id is inherited',
451 () => {
452 const home = tempy.temporaryDirectory();
453 const scriptPath = `${home}/composio.ts`;
@@ -470,7 +470,14 @@ describe('CLI analytics dispatch', () => {
470 parent_run_id: 'run_minted',
471 },
472 });
473 - }).pipe(Effect.provide(cliRunIdLayer('run_minted')), Effect.provide(makePlatformLayer(home)));
473 + }).pipe(
474 + Effect.provideService(CommandInvocation, {
475 + begin: () => Effect.void,
476 + enter: () => Effect.void,
477 + runId: Effect.succeedSome('run_minted'),
478 + }),
479 + Effect.provide(makePlatformLayer(home))
480 + );
481 }
482 );
483
ts/packages/cli/test/src/analytics.events.test.ts
+127 -96
@@ -7,13 +7,13 @@ import { afterEach, describe, expect, vi } from 'vitest';
7 import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
8 import * as BunPath from '@effect/platform-bun/BunPath';
9 import { Effect, Layer, Option } from 'effect';
10 +import { CliError } from 'effect/cli';
11 import { createCliCodactFailureBody } from 'src/analytics/dispatch';
12 import {
13 CLI_ANALYTICS_EVENTS,
14 CLI_EVENT_JOURNEY_STAGES,
15 CLI_JOURNEY_STAGES,
16 configureCliAnalyticsReleaseVersion,
16 - createCliCommandTelemetryContext,
17 getPluginHintShownEvent,
18 getPluginLifecycleFailedEvent,
19 getPluginLifecycleSucceededEvent,
@@ -41,20 +41,27 @@ import { ChildProcessExited } from 'src/effects/child-process-exited';
41 import { SetupCommandError } from 'src/services/setup-command-error';
42 import { ToolInputValidationError } from 'src/services/tool-input-validation';
43 import { resolveInstalledCliVersion } from 'src/services/run-companion-modules';
44 +import type { TelemetryFamily } from 'src/analytics/types';
45 +import { commandTelemetryContext } from 'test/__utils__/telemetry-context';
46
47 const CLI_INVOCATION = {
48 invocationOrigin: DEFAULT_CLI_INVOCATION_ORIGIN,
49 parentRunId: undefined,
50 } as const;
51
52 +/** The context of `args` with this file's defaults: the package version, `cli` origin. */
53 +const commandContext = (
54 + args: ReadonlyArray<string>,
55 + options: Parameters<typeof commandTelemetryContext>[1]
56 +) => commandTelemetryContext(args, { cliVersion: APP_VERSION, ...options });
57 +
58 describe('CLI analytics execute failure events', () => {
59 it('records terminal capabilities supplied by the terminal service', () => {
52 - const context = createCliCommandTelemetryContext(
53 - ['bun', 'composio'],
54 - '0.3.0',
55 - { stdoutIsTTY: true, stderrIsTTY: false },
56 - CLI_INVOCATION
57 - );
60 + const context = commandContext([], {
61 + path: [],
62 + cliVersion: '0.3.0',
63 + terminal: { stdoutIsTTY: true, stderrIsTTY: false },
64 + });
65
66 const event = getPrimaryLifecycleInvokedEvent(context);
67
@@ -65,12 +72,12 @@ describe('CLI analytics execute failure events', () => {
72 });
73
74 it('keeps CLI product and installed library separate on tool-router command events', () => {
68 - const context = createCliCommandTelemetryContext(
69 - ['bun', 'composio', 'execute', 'GITHUB_GET_ME'],
70 - '0.4.2',
71 - { stdoutIsTTY: false, stderrIsTTY: false },
72 - CLI_INVOCATION
73 - );
75 + const context = commandContext(['execute', 'GITHUB_GET_ME'], {
76 + path: ['execute'],
77 + family: 'execute',
78 + input: { slug: 'GITHUB_GET_ME' },
79 + cliVersion: '0.4.2',
80 + });
81 expect(getPrimaryLifecycleSucceededEvent(context)?.properties).toMatchObject({
82 client_name: '@composio/cli',
83 client_version: '0.4.2',
@@ -206,12 +213,11 @@ describe('CLI analytics execute failure events', () => {
213
214 describe('CLI analytics setup and install lifecycle events', () => {
215 it('tracks setup as a dedicated lifecycle with safe option properties', () => {
209 - const context = createCliCommandTelemetryContext(
210 - ['bun', 'composio', 'setup', '--target', 'codex', '--uninstall', '--yes'],
211 - APP_VERSION,
212 - { stdoutIsTTY: false, stderrIsTTY: false },
213 - CLI_INVOCATION
214 - );
216 + const context = commandContext(['setup', '--target', 'codex', '--uninstall', '--yes'], {
217 + path: ['setup'],
218 + family: 'setup',
219 + input: {},
220 + });
221
222 const invoked = getPrimaryLifecycleInvokedEvent(context);
223 const succeeded = getPrimaryLifecycleSucceededEvent(context);
@@ -231,12 +237,11 @@ describe('CLI analytics setup and install lifecycle events', () => {
237 });
238
239 it('tracks shell installation separately from plugin setup', () => {
234 - const context = createCliCommandTelemetryContext(
235 - ['bun', 'composio', 'install', '--completions'],
236 - APP_VERSION,
237 - { stdoutIsTTY: false, stderrIsTTY: false },
238 - CLI_INVOCATION
239 - );
240 + const context = commandContext(['install', '--completions'], {
241 + path: ['install'],
242 + family: 'install',
243 + input: {},
244 + });
245
246 expect(getPrimaryLifecycleInvokedEvent(context)).toMatchObject({
247 name: CLI_ANALYTICS_EVENTS.CLI_INSTALL_INVOKED,
@@ -249,22 +254,16 @@ describe('CLI analytics setup and install lifecycle events', () => {
254 });
255
256 it('summarizes user-controlled search and proxy input without recording it', () => {
252 - const terminal = { stdoutIsTTY: false, stderrIsTTY: false };
257 + const endpoint = 'https://user:password@example.com/private?token=small';
258 const search = getPrimaryLifecycleInvokedEvent(
254 - createCliCommandTelemetryContext(
255 - ['bun', 'composio', 'search', 'customer@example.com secret'],
256 - APP_VERSION,
257 - terminal,
258 - CLI_INVOCATION
259 - )
259 + commandContext(['search', 'customer@example.com secret'], {
260 + path: ['search'],
261 + family: 'search',
262 + input: { query: ['customer@example.com secret'] },
263 + })
264 );
265 const proxy = getPrimaryLifecycleInvokedEvent(
262 - createCliCommandTelemetryContext(
263 - ['bun', 'composio', 'proxy', 'https://user:password@example.com/private?token=small'],
264 - APP_VERSION,
265 - terminal,
266 - CLI_INVOCATION
267 - )
266 + commandContext(['proxy', endpoint], { path: ['proxy'], family: 'proxy', input: { endpoint } })
267 );
268
269 expect(search?.properties).toMatchObject({
@@ -391,34 +390,28 @@ describe('CLI analytics setup runtime-context events', () => {
390 });
391
392 // Execute, search, link, connections, listen and proxy each used to report their own class.
394 - it.each(['execute', 'search', 'link', 'connections list', 'listen', 'proxy'])(
395 - 'reports a missing user on `%s` as MissingActingUserError',
396 - command => {
397 - const context = createCliCommandTelemetryContext(
398 - ['bun', 'composio', ...command.split(' ')],
399 - APP_VERSION,
400 - { stdoutIsTTY: false, stderrIsTTY: false },
401 - CLI_INVOCATION
402 - );
403 - const error = new MissingActingUserError({
404 - tree: 'root',
405 - projectName: Option.none(),
406 - message: 'Missing consumer user id. Run `composio login` and try again.',
407 - });
393 + it.each([
394 + { path: ['execute'], family: 'execute' },
395 + { path: ['search'], family: 'search' },
396 + { path: ['link'], family: 'link' },
397 + { path: ['connections', 'list'], family: 'command' },
398 + { path: ['listen'], family: 'command' },
399 + { path: ['proxy'], family: 'proxy' },
400 + ] as const)('reports a missing user on `$path` as MissingActingUserError', ({ path, family }) => {
401 + const context = commandContext(path, { path, family });
402 + const error = new MissingActingUserError({
403 + tree: 'root',
404 + projectName: Option.none(),
405 + message: 'Missing consumer user id. Run `composio login` and try again.',
406 + });
407
409 - expect(getPrimaryLifecycleFailedEvent(context, error)?.properties).toMatchObject({
410 - error_name: 'commands/MissingActingUserError',
411 - });
412 - }
413 - );
408 + expect(getPrimaryLifecycleFailedEvent(context, error)?.properties).toMatchObject({
409 + error_name: 'commands/MissingActingUserError',
410 + });
411 + });
412
413 it('records the setup failure reason code carried by SetupCommandError', () => {
416 - const context = createCliCommandTelemetryContext(
417 - ['bun', 'composio', 'setup'],
418 - APP_VERSION,
419 - { stdoutIsTTY: false, stderrIsTTY: false },
420 - CLI_INVOCATION
421 - );
414 + const context = commandContext(['setup'], { path: ['setup'], family: 'setup', input: {} });
415 const error = new SetupCommandError({
416 message: 'Non-interactive setup requires `--yes` to approve local changes.',
417 operation: 'setup',
@@ -443,12 +436,11 @@ describe('CLI analytics setup runtime-context events', () => {
436 });
437
438 it('records a run whose child exited non-zero as failed with reason child_exit', () => {
446 - const context = createCliCommandTelemetryContext(
447 - ['bun', 'composio', 'run', 'process.exit(3)'],
448 - APP_VERSION,
449 - { stdoutIsTTY: false, stderrIsTTY: false },
450 - CLI_INVOCATION
451 - );
439 + const context = commandContext(['run', 'process.exit(3)'], {
440 + path: ['run'],
441 + family: 'run',
442 + input: {},
443 + });
444
445 const event = getPrimaryLifecycleFailedEvent(context, new ChildProcessExited({ code: 3 }));
446
@@ -554,16 +546,19 @@ describe('CLI analytics journey taxonomy', () => {
546 vi.unstubAllEnvs();
547 });
548
549 + /** The context of a root command whose name is its family, or the generic `version`. */
550 const contextFor = (
551 argv: ReadonlyArray<string>,
552 invocation: CliInvocationContext = CLI_INVOCATION
560 - ) =>
561 - createCliCommandTelemetryContext(
562 - ['bun', 'composio', ...argv],
563 - APP_VERSION,
564 - { stdoutIsTTY: false, stderrIsTTY: false },
565 - invocation
566 - );
553 + ) => {
554 + const [name = 'version'] = argv;
555 + return commandContext(argv, {
556 + path: [name],
557 + family: name === 'version' ? 'command' : (name as TelemetryFamily),
558 + input: {},
559 + invocation,
560 + });
561 + };
562
563 const lifecycleCases: ReadonlyArray<[ReadonlyArray<string>, string]> = [
564 [['execute', 'GMAIL_SEND_EMAIL'], 'execute'],
@@ -645,12 +640,12 @@ describe('CLI analytics journey taxonomy', () => {
640 const resolvedVersion = yield* resolveInstalledCliVersion(execPath, APP_VERSION);
641 configureCliAnalyticsReleaseVersion(resolvedVersion);
642
648 - const context = createCliCommandTelemetryContext(
649 - ['bun', 'composio', 'login'],
650 - resolvedVersion,
651 - { stdoutIsTTY: false, stderrIsTTY: false },
652 - CLI_INVOCATION
653 - );
643 + const context = commandContext(['login'], {
644 + path: ['login'],
645 + family: 'login',
646 + input: {},
647 + cliVersion: resolvedVersion,
648 + });
649 const properties = getPrimaryLifecycleInvokedEvent(context)?.properties;
650 const pluginProperties = getPluginLifecycleSucceededEvent({
651 operation: 'setup',
@@ -676,29 +671,65 @@ describe('CLI analytics journey taxonomy', () => {
671 });
672 });
673
679 - it.each([
680 - { flags: ['--telemetry-debug'] },
681 - { flags: ['--telemetry-debug=false'] },
682 - { flags: ['--no-telemetry-debug'] },
683 - { flags: ['--tool-debug', '--perf-debug'] },
684 - { flags: ['--log-level', 'Debug'] },
685 - { flags: ['--log-level=Debug', '--telemetry-debug'] },
686 - ])('identifies run and execute after shared options: $flags', ({ flags }) => {
687 - const runArgs = [...flags, 'run', 'console.log("hi")'];
688 - const run = contextFor(runArgs);
689 - expect(run.argv).toEqual(['bun', 'composio', ...runArgs]);
690 - expect(run.commandPath).toBe('run');
674 + it('mints a run id for run and reads the execute slug from the parsed input', () => {
675 + const run = commandContext(['--telemetry-debug', 'run', 'console.log("hi")'], {
676 + path: ['run'],
677 + family: 'run',
678 + input: {},
679 + });
680 expect(run.runId).toEqual(expect.any(String));
681 expect(getPrimaryLifecycleInvokedEvent(run)).toMatchObject({
682 name: CLI_ANALYTICS_EVENTS.CLI_RUN_INVOKED,
683 properties: { run_id: run.runId, command_path: 'run' },
684 });
685
697 - const execute = contextFor([...flags, 'execute', 'GMAIL_SEND_EMAIL', '--get-schema']);
686 + const execute = commandContext(['--log-level', 'Debug', 'execute', 'GMAIL_SEND_EMAIL'], {
687 + path: ['execute'],
688 + family: 'execute',
689 + input: { slug: 'GMAIL_SEND_EMAIL', data: Option.none() },
690 + });
691 expect(getPrimaryLifecycleInvokedEvent(execute)).toMatchObject({
692 name: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_INVOKED,
700 - properties: { command_path: 'execute', tool_slug: 'GMAIL_SEND_EMAIL' },
693 + properties: {
694 + command_path: 'execute',
695 + tool_slug: 'GMAIL_SEND_EMAIL',
696 + toolkit_slug: 'gmail',
697 + },
698 + });
699 + });
700 +
701 + it('reads the link toolkit from the parsed input, and nothing for help or a parse failure', () => {
702 + const link = (input?: unknown) =>
703 + getPrimaryLifecycleInvokedEvent(
704 + commandContext(['link', '--alias', 'work', 'gmail'], {
705 + path: ['link'],
706 + family: 'link',
707 + input,
708 + })
709 + )?.properties;
710 + expect(link({ toolkit: Option.some('gmail'), alias: Option.some('work') })).toMatchObject({
711 + toolkit: 'gmail',
712 + });
713 + expect(link({ toolkit: Option.none() })?.toolkit).toBeUndefined();
714 + expect(link()?.toolkit).toBeUndefined();
715 + });
716 +
717 + it('records a parse failure with reason parse_error, and a bare group help without one', () => {
718 + const context = commandContext(['dev', 'triggers', 'list'], {
719 + path: ['dev', 'triggers', 'list'],
720 + });
721 + const parseError = new CliError.ShowHelp({
722 + commandPath: ['composio', 'dev', 'triggers', 'list'],
723 + errors: [new CliError.MissingArgument({ argument: 'toolkit' })],
724 });
725 + expect(getPrimaryLifecycleFailedEvent(context, parseError)).toMatchObject({
726 + name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED,
727 + properties: { command_path: 'dev triggers list', failure_reason_code: 'parse_error' },
728 + });
729 + const bareGroup = new CliError.ShowHelp({ commandPath: ['composio', 'dev'], errors: [] });
730 + expect(getPrimaryLifecycleFailedEvent(context, bareGroup)?.properties).not.toHaveProperty(
731 + 'failure_reason_code'
732 + );
733 });
734
735 it('uses the configured parent run id for nested run telemetry', () => {
ts/packages/cli/test/src/commands/registration.test.ts new
+225
@@ -0,0 +1,225 @@
1 +/**
2 + * Pins the order in which `effect/cli` composes a command's handler with the providers and guards
3 + * of the groups above it. Command identity depends on it (`src/commands/registration.ts`) and the
4 + * framework does not document it: if an `effect` upgrade changes it, these cases fail first.
5 + */
6 +import { describe, expect, layer } from '@effect/vitest';
7 +import { Effect, Exit, Option, Ref } from 'effect';
8 +import { CliError, Command } from 'effect/cli';
9 +import { NotLoggedInError } from 'src/commands/errors';
10 +import { withRegisteredSubcommands } from 'src/commands/registration';
11 +import { requireLogin } from 'src/effects/require-auth';
12 +import { CommandInvocation, commandPathOf, withCommandMeta } from 'src/invocation/command-identity';
13 +import { TestLive } from 'test/__utils__';
14 +
15 +class GuardFailed extends CliError.UserError {}
16 +
17 +/**
18 + * A tree shaped like the CLI's: `app` (own handler) registers `outer` (own handler), a root
19 + * shortcut to `link` with its own family, a login-gated group, and a group whose own guard fails.
20 + * `outer` registers `inner` (no handler, aliased `in`) and the same `link` value again. Every
21 + * provider, registration, `begin`, and handler appends to the trace.
22 + */
23 +const traced = (args: ReadonlyArray<string>) =>
24 + Effect.gen(function* () {
25 + const trace = yield* Ref.make<ReadonlyArray<string>>([]);
26 + const note = (entry: string) => Ref.update(trace, entries => [...entries, entry]);
27 + const handler = (name: string) => () => note(`handler ${name}`);
28 + const provider =
29 + (name: string) =>
30 + <const Name extends string, Input, ContextInput, E, R>(
31 + self: Command.Command<Name, Input, ContextInput, E, R>
32 + ) =>
33 + Command.provideEffectDiscard(self, note(`provider ${name}`));
34 +
35 + const show = Command.make('show', {}, handler('show'));
36 + const link = Command.make('link', {}, handler('link'));
37 + const inner = Command.make('inner').pipe(
38 + Command.withAlias('in'),
39 + withRegisteredSubcommands([show]),
40 + provider('inner')
41 + );
42 + const outer = Command.make('outer', {}, handler('outer')).pipe(
43 + withRegisteredSubcommands([inner, link]),
44 + provider('outer')
45 + );
46 + const gated = Command.make('gated').pipe(
47 + withRegisteredSubcommands([Command.make('leaf', {}, handler('gated leaf'))]),
48 + requireLogin
49 + );
50 + const guarded = Command.make('guarded').pipe(
51 + withRegisteredSubcommands([Command.make('leaf', {}, handler('guarded leaf'))]),
52 + Command.provideEffectDiscard(
53 + Effect.andThen(note('guard guarded'), Effect.fail(new GuardFailed({ cause: 'guard' })))
54 + )
55 + );
56 + const app = Command.make('app', {}, handler('app')).pipe(
57 + withRegisteredSubcommands([
58 + outer,
59 + link.pipe(withCommandMeta({ telemetryFamily: 'link' })),
60 + gated,
61 + guarded,
62 + ]),
63 + provider('app')
64 + );
65 +
66 + const exit = yield* Command.runWith(app, { version: '1.0.0' })(args).pipe(
67 + Effect.provideService(CommandInvocation, {
68 + begin: (identity, input) =>
69 + note(
70 + `begin ${commandPathOf(identity)} ${identity.meta.telemetryFamily}${Option.isSome(input) ? '' : ' unparsed'}`
71 + ),
72 + enter: identity => note(`enter ${commandPathOf(identity)}`),
73 + runId: Effect.succeedNone,
74 + }),
75 + Effect.exit
76 + );
77 + return { exit, trace: yield* Ref.get(trace) };
78 + });
79 +
80 +const failureOf = (exit: Exit.Exit<unknown, unknown>) =>
81 + Exit.isFailure(exit) ? Option.getOrUndefined(Exit.findErrorOption(exit)) : undefined;
82 +
83 +describe('effect/cli handler composition', () => {
84 + layer(TestLive())(it => {
85 + it.effect.each([
86 + {
87 + name: 'a nested leaf runs inside every ancestor provider, outermost first',
88 + args: ['outer', 'inner', 'show'],
89 + trace: [
90 + 'provider app',
91 + 'enter outer',
92 + 'provider outer',
93 + 'enter outer inner',
94 + 'provider inner',
95 + 'enter outer inner show',
96 + 'begin outer inner show command',
97 + 'handler show',
98 + ],
99 + },
100 + {
101 + name: 'an alias resolves to the canonical registration',
102 + args: ['outer', 'in', 'show'],
103 + trace: [
104 + 'provider app',
105 + 'enter outer',
106 + 'provider outer',
107 + 'enter outer inner',
108 + 'provider inner',
109 + 'enter outer inner show',
110 + 'begin outer inner show command',
111 + 'handler show',
112 + ],
113 + },
114 + {
115 + name: 'a bare group with a handler runs its own handler, no subcommand',
116 + args: ['outer'],
117 + trace: [
118 + 'provider app',
119 + 'enter outer',
120 + 'provider outer',
121 + 'begin outer command',
122 + 'handler outer',
123 + ],
124 + },
125 + {
126 + name: 'the root with no subcommand runs its own handler',
127 + args: [],
128 + trace: ['provider app', 'begin composio command', 'handler app'],
129 + },
130 + {
131 + name: 'a root shortcut is its own registration, with its own meta',
132 + args: ['link'],
133 + trace: ['provider app', 'enter link', 'begin link link', 'handler link'],
134 + },
135 + {
136 + name: 'the same value registered in a group has the group path and no root meta',
137 + args: ['outer', 'link'],
138 + trace: [
139 + 'provider app',
140 + 'enter outer',
141 + 'provider outer',
142 + 'enter outer link',
143 + 'begin outer link command',
144 + 'handler link',
145 + ],
146 + },
147 + ])('$name', ({ args, trace }) =>
148 + Effect.gen(function* () {
149 + const result = yield* traced(args);
150 + expect(Exit.isSuccess(result.exit)).toBe(true);
151 + expect(result.trace).toEqual(trace);
152 + })
153 + );
154 +
155 + it.effect('a bare group without a handler begins, then shows its help', () =>
156 + Effect.gen(function* () {
157 + const { exit, trace } = yield* traced(['outer', 'inner']);
158 + expect(trace).toEqual([
159 + 'provider app',
160 + 'enter outer',
161 + 'provider outer',
162 + 'enter outer inner',
163 + 'provider inner',
164 + 'begin outer inner command',
165 + ]);
166 + expect(failureOf(exit)).toMatchObject({
167 + _tag: 'ShowHelp',
168 + commandPath: ['app', 'outer', 'inner'],
169 + errors: [],
170 + });
171 + })
172 + );
173 +
174 + it.effect('a login a group requires is checked after the selected command began', () =>
175 + Effect.gen(function* () {
176 + const { exit, trace } = yield* traced(['gated', 'leaf']);
177 + expect(trace).toEqual([
178 + 'provider app',
179 + 'enter gated',
180 + 'enter gated leaf',
181 + 'begin gated leaf command',
182 + ]);
183 + expect(failureOf(exit)).toBeInstanceOf(NotLoggedInError);
184 + })
185 + );
186 +
187 + // A guard a group pipes on itself wraps its whole dispatch, so it runs before the selected
188 + // command is reached: only the registrations entered so far are known. `requireLogin` is
189 + // `CommandMeta` for this reason; the `dev` group's `rejectsSharedFlags` guards are not yet.
190 + it.effect('a group-level guard runs before the selected command begins', () =>
191 + Effect.gen(function* () {
192 + const { exit, trace } = yield* traced(['guarded', 'leaf']);
193 + expect(trace).toEqual(['provider app', 'enter guarded', 'guard guarded']);
194 + expect(failureOf(exit)).toBeInstanceOf(GuardFailed);
195 + })
196 + );
197 +
198 + it.effect('a parse failure runs no provider, and names the canonical path reached', () =>
199 + Effect.gen(function* () {
200 + const { exit, trace } = yield* traced(['outer', 'in', 'shw']);
201 + expect(trace).toEqual([]);
202 + expect(failureOf(exit)).toMatchObject({
203 + _tag: 'ShowHelp',
204 + commandPath: ['app', 'outer', 'inner'],
205 + errors: [{ _tag: 'UnknownSubcommand', subcommand: 'shw' }],
206 + });
207 + })
208 + );
209 +
210 + it.effect.each([
211 + {
212 + flag: '--help',
213 + args: ['outer', 'in', '--help'],
214 + begun: 'begin outer inner command unparsed',
215 + },
216 + { flag: '--version', args: ['link', '--version'], begun: 'begin link link unparsed' },
217 + ])('$flag begins the command it answers for, and runs no handler', ({ args, begun }) =>
218 + Effect.gen(function* () {
219 + const { exit, trace } = yield* traced(args);
220 + expect(Exit.isSuccess(exit)).toBe(true);
221 + expect(trace).toEqual([begun]);
222 + })
223 + );
224 + });
225 +});
ts/packages/cli/test/src/invocation/command-identity.before.ts new
+167
@@ -0,0 +1,167 @@
1 +import type { TelemetryFamily } from 'src/analytics/types';
2 +
3 +/**
4 + * The command path and lifecycle family telemetry recorded for every command path of the tree
5 + * (developer mode and every experimental feature on) before the identity came from the parsed
6 + * command tree: the argv extractor it replaced matched tokens against a hand-kept allowlist
7 + * (`KNOWN_COMMAND_TOKENS` in `src/analytics/events.ts`) and stopped at the first unknown one.
8 + * Frozen data for `command-identity.test.ts`; do not add new commands here.
9 + */
10 +export const RECORDED_BEFORE_IDENTITY: Readonly<
11 + Record<string, { readonly path: string; readonly family: TelemetryFamily }>
12 +> = {
13 + composio: { path: 'composio', family: 'command' },
14 + debug: { path: 'composio', family: 'command' },
15 + 'debug generate-graph': { path: 'composio', family: 'command' },
16 + 'debug api-info': { path: 'composio', family: 'command' },
17 + 'debug who-is-my-master': { path: 'composio', family: 'command' },
18 + version: { path: 'version', family: 'command' },
19 + upgrade: { path: 'upgrade', family: 'command' },
20 + whoami: { path: 'whoami', family: 'command' },
21 + login: { path: 'login', family: 'login' },
22 + signup: { path: 'composio', family: 'command' },
23 + setup: { path: 'setup', family: 'setup' },
24 + 'setup skill': { path: 'setup', family: 'setup' },
25 + agent: { path: 'composio', family: 'command' },
26 + 'agent signup': { path: 'composio', family: 'command' },
27 + 'agent login': { path: 'composio', family: 'command' },
28 + 'agent whoami': { path: 'composio', family: 'command' },
29 + 'agent claim': { path: 'composio', family: 'command' },
30 + 'agent inbox': { path: 'composio', family: 'command' },
31 + listen: { path: 'listen', family: 'command' },
32 + logout: { path: 'logout', family: 'logout' },
33 + run: { path: 'run', family: 'run' },
34 + proxy: { path: 'proxy', family: 'proxy' },
35 + artifacts: { path: 'artifacts', family: 'command' },
36 + 'artifacts cwd': { path: 'artifacts cwd', family: 'command' },
37 + install: { path: 'install', family: 'install' },
38 + tools: { path: 'tools', family: 'command' },
39 + 'tools list': { path: 'tools list', family: 'command' },
40 + 'tools info': { path: 'tools info', family: 'command' },
41 + triggers: { path: 'triggers', family: 'command' },
42 + 'triggers list': { path: 'triggers list', family: 'command' },
43 + 'triggers info': { path: 'triggers info', family: 'command' },
44 + search: { path: 'search', family: 'search' },
45 + link: { path: 'link', family: 'link' },
46 + execute: { path: 'execute', family: 'execute' },
47 + connections: { path: 'composio', family: 'command' },
48 + 'connections list': { path: 'composio', family: 'command' },
49 + 'connections remove': { path: 'composio', family: 'command' },
50 + generate: { path: 'generate', family: 'command' },
51 + 'generate py': { path: 'generate py', family: 'command' },
52 + 'generate ts': { path: 'generate ts', family: 'command' },
53 + orgs: { path: 'orgs', family: 'command' },
54 + 'orgs list': { path: 'orgs list', family: 'command' },
55 + 'orgs switch': { path: 'orgs switch', family: 'command' },
56 + config: { path: 'composio', family: 'command' },
57 + 'config experimental': { path: 'composio', family: 'command' },
58 + dev: { path: 'dev', family: 'command' },
59 + 'dev init': { path: 'dev', family: 'command' },
60 + 'dev playground-execute': { path: 'dev playground-execute', family: 'command' },
61 + 'dev listen': { path: 'dev listen', family: 'command' },
62 + 'dev logs': { path: 'dev logs', family: 'command' },
63 + 'dev logs triggers': { path: 'dev logs triggers', family: 'command' },
64 + 'dev logs tools': { path: 'dev logs tools', family: 'command' },
65 + 'dev toolkits': { path: 'dev toolkits', family: 'command' },
66 + 'dev toolkits list': { path: 'dev toolkits list', family: 'command' },
67 + 'dev toolkits info': { path: 'dev toolkits info', family: 'command' },
68 + 'dev toolkits search': { path: 'dev toolkits search', family: 'command' },
69 + 'dev toolkits version': { path: 'dev toolkits version', family: 'command' },
70 + 'dev auth-configs': { path: 'dev auth-configs', family: 'command' },
71 + 'dev auth-configs list': { path: 'dev auth-configs list', family: 'command' },
72 + 'dev auth-configs info': { path: 'dev auth-configs info', family: 'command' },
73 + 'dev auth-configs create': { path: 'dev auth-configs create', family: 'command' },
74 + 'dev connected-accounts': { path: 'dev connected-accounts', family: 'command' },
75 + 'dev connected-accounts link': { path: 'dev connected-accounts link', family: 'command' },
76 + 'dev connected-accounts list': { path: 'dev connected-accounts list', family: 'command' },
77 + 'dev connected-accounts info': { path: 'dev connected-accounts info', family: 'command' },
78 + 'dev connected-accounts whoami': { path: 'dev connected-accounts whoami', family: 'command' },
79 + 'dev triggers': { path: 'dev triggers', family: 'command' },
80 + 'dev triggers listen': { path: 'dev triggers listen', family: 'command' },
81 + 'dev triggers list': { path: 'dev triggers list', family: 'command' },
82 + 'dev triggers info': { path: 'dev triggers info', family: 'command' },
83 + 'dev triggers status': { path: 'dev triggers status', family: 'command' },
84 + 'dev triggers create': { path: 'dev triggers create', family: 'command' },
85 + 'dev triggers enable': { path: 'dev triggers enable', family: 'command' },
86 + 'dev triggers disable': { path: 'dev triggers disable', family: 'command' },
87 + 'dev projects': { path: 'dev projects', family: 'command' },
88 + 'dev projects list': { path: 'dev projects list', family: 'command' },
89 + 'dev projects switch': { path: 'dev projects switch', family: 'command' },
90 + help: { path: 'composio', family: 'command' },
91 + 'help debug': { path: 'composio', family: 'command' },
92 + 'help debug generate-graph': { path: 'composio', family: 'command' },
93 + 'help debug api-info': { path: 'composio', family: 'command' },
94 + 'help debug who-is-my-master': { path: 'composio', family: 'command' },
95 + 'help version': { path: 'composio', family: 'command' },
96 + 'help upgrade': { path: 'composio', family: 'command' },
97 + 'help whoami': { path: 'composio', family: 'command' },
98 + 'help login': { path: 'composio', family: 'command' },
99 + 'help signup': { path: 'composio', family: 'command' },
100 + 'help setup': { path: 'composio', family: 'command' },
101 + 'help setup skill': { path: 'composio', family: 'command' },
102 + 'help agent': { path: 'composio', family: 'command' },
103 + 'help agent signup': { path: 'composio', family: 'command' },
104 + 'help agent login': { path: 'composio', family: 'command' },
105 + 'help agent whoami': { path: 'composio', family: 'command' },
106 + 'help agent claim': { path: 'composio', family: 'command' },
107 + 'help agent inbox': { path: 'composio', family: 'command' },
108 + 'help listen': { path: 'composio', family: 'command' },
109 + 'help logout': { path: 'composio', family: 'command' },
110 + 'help run': { path: 'composio', family: 'command' },
111 + 'help proxy': { path: 'composio', family: 'command' },
112 + 'help artifacts': { path: 'composio', family: 'command' },
113 + 'help artifacts cwd': { path: 'composio', family: 'command' },
114 + 'help install': { path: 'composio', family: 'command' },
115 + 'help tools': { path: 'composio', family: 'command' },
116 + 'help tools list': { path: 'composio', family: 'command' },
117 + 'help tools info': { path: 'composio', family: 'command' },
118 + 'help triggers': { path: 'composio', family: 'command' },
119 + 'help triggers list': { path: 'composio', family: 'command' },
120 + 'help triggers info': { path: 'composio', family: 'command' },
121 + 'help search': { path: 'composio', family: 'command' },
122 + 'help link': { path: 'composio', family: 'command' },
123 + 'help execute': { path: 'composio', family: 'command' },
124 + 'help connections': { path: 'composio', family: 'command' },
125 + 'help connections list': { path: 'composio', family: 'command' },
126 + 'help connections remove': { path: 'composio', family: 'command' },
127 + 'help generate': { path: 'composio', family: 'command' },
128 + 'help generate py': { path: 'composio', family: 'command' },
129 + 'help generate ts': { path: 'composio', family: 'command' },
130 + 'help orgs': { path: 'composio', family: 'command' },
131 + 'help orgs list': { path: 'composio', family: 'command' },
132 + 'help orgs switch': { path: 'composio', family: 'command' },
133 + 'help config': { path: 'composio', family: 'command' },
134 + 'help config experimental': { path: 'composio', family: 'command' },
135 + 'help dev': { path: 'composio', family: 'command' },
136 + 'help dev init': { path: 'composio', family: 'command' },
137 + 'help dev playground-execute': { path: 'composio', family: 'command' },
138 + 'help dev listen': { path: 'composio', family: 'command' },
139 + 'help dev logs': { path: 'composio', family: 'command' },
140 + 'help dev logs triggers': { path: 'composio', family: 'command' },
141 + 'help dev logs tools': { path: 'composio', family: 'command' },
142 + 'help dev toolkits': { path: 'composio', family: 'command' },
143 + 'help dev toolkits list': { path: 'composio', family: 'command' },
144 + 'help dev toolkits info': { path: 'composio', family: 'command' },
145 + 'help dev toolkits search': { path: 'composio', family: 'command' },
146 + 'help dev toolkits version': { path: 'composio', family: 'command' },
147 + 'help dev auth-configs': { path: 'composio', family: 'command' },
148 + 'help dev auth-configs list': { path: 'composio', family: 'command' },
149 + 'help dev auth-configs info': { path: 'composio', family: 'command' },
150 + 'help dev auth-configs create': { path: 'composio', family: 'command' },
151 + 'help dev connected-accounts': { path: 'composio', family: 'command' },
152 + 'help dev connected-accounts link': { path: 'composio', family: 'command' },
153 + 'help dev connected-accounts list': { path: 'composio', family: 'command' },
154 + 'help dev connected-accounts info': { path: 'composio', family: 'command' },
155 + 'help dev connected-accounts whoami': { path: 'composio', family: 'command' },
156 + 'help dev triggers': { path: 'composio', family: 'command' },
157 + 'help dev triggers listen': { path: 'composio', family: 'command' },
158 + 'help dev triggers list': { path: 'composio', family: 'command' },
159 + 'help dev triggers info': { path: 'composio', family: 'command' },
160 + 'help dev triggers status': { path: 'composio', family: 'command' },
161 + 'help dev triggers create': { path: 'composio', family: 'command' },
162 + 'help dev triggers enable': { path: 'composio', family: 'command' },
163 + 'help dev triggers disable': { path: 'composio', family: 'command' },
164 + 'help dev projects': { path: 'composio', family: 'command' },
165 + 'help dev projects list': { path: 'composio', family: 'command' },
166 + 'help dev projects switch': { path: 'composio', family: 'command' },
167 +};
ts/packages/cli/test/src/invocation/command-identity.test.ts new
+225
@@ -0,0 +1,225 @@
1 +import { describe, expect, it, layer } from '@effect/vitest';
2 +import { Cause, Data, Effect, Option, Ref } from 'effect';
3 +import type { Command } from 'effect/cli';
4 +import { getPrimaryLifecycleFailedEvent } from 'src/analytics/events';
5 +import type { TelemetryFamily } from 'src/analytics/types';
6 +import { buildRootCommand, runWithConfig } from 'src/commands';
7 +import {
8 + CommandInvocation,
9 + type CommandIdentity,
10 + commandPathOf,
11 +} from 'src/invocation/command-identity';
12 +import { cliExit, recordedInvocationCalls, TestLive } from 'test/__utils__';
13 +import { RECORDED_BEFORE_IDENTITY } from './command-identity.before';
14 +
15 +const commandPaths = (
16 + command: Command.Command.Any,
17 + prefix: ReadonlyArray<string>
18 +): ReadonlyArray<ReadonlyArray<string>> =>
19 + command.subcommands
20 + .flatMap(group => group.commands)
21 + .flatMap(child => {
22 + const path = [...prefix, child.name];
23 + return [path, ...commandPaths(child, path)];
24 + });
25 +
26 +const everyFeature = { isDevModeEnabled: true, isExperimentalFeatureEnabled: () => true };
27 +const PATHS = [[], ...commandPaths(buildRootCommand(everyFeature), [])].map(path => ({
28 + args: path,
29 + name: path.join(' ') || 'composio',
30 +}));
31 +
32 +/** The root registrations with their own lifecycle family; every other command is `command`. */
33 +const FAMILIES: Readonly<Record<string, TelemetryFamily>> = {
34 + execute: 'execute',
35 + install: 'install',
36 + link: 'link',
37 + login: 'login',
38 + logout: 'logout',
39 + proxy: 'proxy',
40 + run: 'run',
41 + search: 'search',
42 + setup: 'setup',
43 +};
44 +
45 +/**
46 + * The command paths the argv extractor recorded wrongly (`RECORDED_BEFORE_IDENTITY`): a token
47 + * missing from its allowlist stopped it early, so these were recorded as `composio`, as their
48 + * parent (`dev init` as `dev`), or as their parent's family (`setup skill` as `setup`). Every
49 + * other path is recorded as before.
50 + */
51 +const CORRECTED_PATHS = [
52 + 'agent',
53 + 'agent claim',
54 + 'agent inbox',
55 + 'agent login',
56 + 'agent signup',
57 + 'agent whoami',
58 + 'config',
59 + 'config experimental',
60 + 'connections',
61 + 'connections list',
62 + 'connections remove',
63 + 'debug',
64 + 'debug api-info',
65 + 'debug generate-graph',
66 + 'debug who-is-my-master',
67 + 'dev init',
68 + 'setup skill',
69 + 'signup',
70 + // `composio help <command>`, all recorded as `composio`.
71 + ...PATHS.filter(({ args }) => args[0] === 'help').map(({ name }) => name),
72 +].toSorted();
73 +
74 +class StopAtBegin extends Data.TaggedError('test/StopAtBegin') {}
75 +
76 +/**
77 + * The identity `effect/cli` gives `args` at runtime: the selected registration's, or for help
78 + * and parse failures the one the parser names. Stops at `begin`, so no handler runs.
79 + */
80 +const identityOf = (args: ReadonlyArray<string>) =>
81 + Effect.gen(function* () {
82 + const begun = yield* Ref.make(Option.none<CommandIdentity>());
83 + const run = yield* runWithConfig;
84 + yield* run(['node', '<CMD>', ...args]).pipe(
85 + Effect.provideService(CommandInvocation, {
86 + begin: identity =>
87 + Ref.set(begun, Option.some(identity)).pipe(Effect.andThen(Effect.die(new StopAtBegin()))),
88 + enter: () => Effect.void,
89 + runId: Effect.succeedNone,
90 + }),
91 + Effect.exit
92 + );
93 + return yield* Ref.get(begun);
94 + });
95 +
96 +describe('command identity', () => {
97 + layer(TestLive({ cliUserConfig: { experimentalFeatures: { listen: true } } }))(it => {
98 + it.effect.each(PATHS)('`$name` is recorded as itself, with its family', ({ args, name }) =>
99 + Effect.gen(function* () {
100 + const identity = yield* identityOf(args);
101 + expect(Option.map(identity, commandPathOf)).toEqual(Option.some(name));
102 + expect(Option.map(identity, ({ meta }) => meta.telemetryFamily)).toEqual(
103 + Option.some(FAMILIES[name] ?? 'command')
104 + );
105 + })
106 + );
107 + });
108 +
109 + it('changes the recorded path or family only of the paths the argv extractor got wrong', () => {
110 + const changed = PATHS.filter(({ name }) => {
111 + const before = RECORDED_BEFORE_IDENTITY[name];
112 + return before === undefined
113 + ? false
114 + : before.path !== name || before.family !== (FAMILIES[name] ?? 'command');
115 + }).map(({ name }) => name);
116 + expect(changed.toSorted()).toEqual(CORRECTED_PATHS);
117 + expect(PATHS.map(({ name }) => name).toSorted()).toEqual(
118 + Object.keys(RECORDED_BEFORE_IDENTITY).toSorted()
119 + );
120 + });
121 +});
122 +
123 +/** The lifecycle events `cli(args)` recorded, as `<event> <command path> <family>`. */
124 +const lifecycleOf = (args: ReadonlyArray<string>) =>
125 + Effect.gen(function* () {
126 + yield* cliExit(args);
127 + const calls = yield* recordedInvocationCalls;
128 + return calls.flatMap(call =>
129 + call.service === 'CommandLifecycleTelemetry'
130 + ? [{ event: call.event, path: call.context.commandPath, family: call.context.family, call }]
131 + : []
132 + );
133 + }).pipe(Effect.provide(TestLive()));
134 +
135 +describe('lifecycle telemetry from the command identity', () => {
136 + it.effect.each([
137 + { args: ['signup', '--help'], path: 'signup', family: 'command', outcome: 'succeeded' },
138 + {
139 + args: ['setup', 'skill', '--help'],
140 + path: 'setup skill',
141 + family: 'command',
142 + outcome: 'succeeded',
143 + },
144 + { args: ['--version'], path: 'composio', family: 'command', outcome: 'succeeded' },
145 + {
146 + args: ['connections', 'list'],
147 + path: 'connections list',
148 + family: 'command',
149 + outcome: 'failed',
150 + },
151 + { args: ['tools'], path: 'tools', family: 'command', outcome: 'failed' },
152 + { args: ['link', 'gmail'], path: 'link', family: 'link', outcome: 'failed' },
153 + {
154 + args: ['dev', 'connected-accounts', 'link', 'gmail'],
155 + path: 'dev connected-accounts link',
156 + family: 'command',
157 + outcome: 'failed',
158 + },
159 + {
160 + args: ['dev', '--user-id', 'u', 'triggers', 'list', 'gmail'],
161 + path: 'dev triggers list',
162 + family: 'command',
163 + outcome: 'failed',
164 + },
165 + {
166 + args: ['dev', 'triggers', 'list', 'gmail', '--user-id', 'u'],
167 + path: 'dev triggers list',
168 + family: 'command',
169 + outcome: 'failed',
170 + },
171 + // `rejectsSharedFlags` on the `logs` group fails before `dev logs tools` is reached.
172 + {
173 + args: ['dev', 'logs', 'tools', '--project-name', 'p'],
174 + path: 'dev logs',
175 + family: 'command',
176 + outcome: 'failed',
177 + },
178 + ])(
179 + '[Given] logged out, `composio $args` [Then] records $path ($family) as $outcome',
180 + ({ args, path, family, outcome }) =>
181 + Effect.gen(function* () {
182 + const events = yield* lifecycleOf(args);
183 + expect(events.map(({ event, path, family }) => ({ event, path, family }))).toEqual([
184 + { event: 'invoked', path, family },
185 + { event: outcome, path, family },
186 + ]);
187 + })
188 + );
189 +
190 + it.effect('records a typo against the path the parser reached, never the typed token', () =>
191 + Effect.gen(function* () {
192 + const events = yield* lifecycleOf(['dve', 'list']);
193 + expect(events.map(({ event, path }) => ({ event, path }))).toEqual([
194 + { event: 'invoked', path: 'composio' },
195 + { event: 'failed', path: 'composio' },
196 + ]);
197 + const failed = events[1]!.call;
198 + expect(failed.event).toBe('failed');
199 + const properties =
200 + failed.event === 'failed'
201 + ? getPrimaryLifecycleFailedEvent(failed.context, Cause.squash(failed.cause))?.properties
202 + : undefined;
203 + expect(properties).toMatchObject({
204 + command_path: 'composio',
205 + failure_reason_code: 'parse_error',
206 + });
207 + expect(JSON.stringify(properties)).not.toContain('dve');
208 + })
209 + );
210 +
211 + it.effect('reads the execute tool slug from the parsed input, and none for --help', () =>
212 + Effect.gen(function* () {
213 + const [executed] = yield* lifecycleOf(['execute', 'GMAIL_SEND_EMAIL']);
214 + expect(executed?.call.context).toMatchObject({
215 + commandPath: 'execute',
216 + family: 'execute',
217 + argument: 'GMAIL_SEND_EMAIL',
218 + toolkitSlug: 'gmail',
219 + });
220 + const [help] = yield* lifecycleOf(['execute', 'GMAIL_SEND_EMAIL', '--help']);
221 + expect(help?.call.context).toMatchObject({ commandPath: 'execute', family: 'execute' });
222 + expect(help?.call.context.argument).toBeUndefined();
223 + })
224 + );
225 +});
ts/packages/cli/test/src/services/command-lifecycle-telemetry.test.ts
+11 -8
@@ -3,7 +3,7 @@ import { afterEach, vi } from 'vitest';
3 import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
4 import * as BunPath from '@effect/platform-bun/BunPath';
5 import { Cause, Effect, Layer } from 'effect';
6 -import { createCliCommandTelemetryContext } from 'src/analytics/events';
6 +import type { TelemetryFamily } from 'src/analytics/types';
7 import { ChildProcessExited } from 'src/effects/child-process-exited';
8 import {
9 CommandLifecycleTelemetry,
@@ -11,6 +11,7 @@ import {
11 } from 'src/services/command-lifecycle-telemetry';
12 import { NodeOs } from 'src/services/node-os';
13 import { TerminalUITest } from 'test/__utils__/services/terminal-ui-test';
14 +import { commandTelemetryContext } from 'test/__utils__/telemetry-context';
15 import { trackedEvents } from 'test/__utils__/tracked-events';
16
17 vi.mock('src/analytics/dispatch', async importOriginal => {
@@ -30,13 +31,15 @@ const TelemetryLive = Layer.provide(
31 Layer.mergeAll(BunFileSystem.layer, BunPath.layer, NodeOs.Default, TerminalUITest)
32 );
33
33 -const contextFor = (args: ReadonlyArray<string>) =>
34 - createCliCommandTelemetryContext(
35 - ['/bin/bun', '/cli/bin.ts', ...args],
36 - '1.2.3',
37 - { stdoutIsTTY: false, stderrIsTTY: false },
38 - { invocationOrigin: 'cli', parentRunId: undefined }
39 - );
34 +// The root commands these tests run are named after their families, except generic `whoami`.
35 +const contextFor = (args: ReadonlyArray<string>) => {
36 + const [name = 'whoami'] = args;
37 + return commandTelemetryContext(args, {
38 + path: [name],
39 + family: name === 'whoami' ? 'command' : (name as TelemetryFamily),
40 + input: {},
41 + });
42 +};
43
44 const report = (
45 telemetry: CommandLifecycleTelemetryShape,
ts/packages/cli/test/src/services/invocation-hooks-test-layer.test.ts
+2 -7
@@ -1,7 +1,7 @@
1 import { describe, expect, layer } from '@effect/vitest';
2 import { vi } from 'vitest';
3 import { Cause, Effect } from 'effect';
4 -import { createCliCommandTelemetryContext } from 'src/analytics/events';
4 +import { commandTelemetryContext } from 'test/__utils__/telemetry-context';
5 import { BackendMismatchWarning } from 'src/services/backend-mismatch-warning';
6 import { CommandLifecycleTelemetry } from 'src/services/command-lifecycle-telemetry';
7 import { PluginHint } from 'src/services/plugin-hint';
@@ -28,12 +28,7 @@ describe('TestLive invocation hooks and telemetry sink', () => {
28 it.effect('[Given] every hook and lifecycle event [Then] records each call, in order', () =>
29 Effect.gen(function* () {
30 const invocation = { argv: ['/bin/bun', '/cli/bin.ts', 'whoami'] };
31 - const context = createCliCommandTelemetryContext(
32 - invocation.argv,
33 - '1.2.3',
34 - { stdoutIsTTY: false, stderrIsTTY: false },
35 - { invocationOrigin: 'cli', parentRunId: undefined }
36 - );
31 + const context = commandTelemetryContext(['whoami'], { path: ['whoami'], input: {} });
32 const cause = Cause.fail(new TypeError('boom'));
33
34 yield* (yield* BackendMismatchWarning).run(invocation);