@devries-cameron20 / composio Mirror · read-only / commits / 878da4fdf
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 08:30 UTC

fix(cli): print an unmatched `--account` as a usage error, not a crash (#5003)

> Stacked on #5002 (base `fix/cli-execute-failure-exit-code`). It reuses the fake backend/Dashboard subprocess harness that #5002 adds to `test/src/cli-main.test.ts`. Retarget to `next` after #5002 merges. This PR: - Adds `ConnectedAccountResolutionError` to the existing `UsageFailure` union (`src/commands/errors.ts`). An `--account` that matches no connected account now prints as one plain line on stderr and exits 1, with nothing on stdout, like `CommandInputError` / `NotLoggedInError` / `ProjectResolutionError`. - Applies to `composio execute` and `composio proxy`, which both resolve `--account` through `resolveConnectedAccountForToolkit`. A failure to load the toolkit's connected accounts uses the same path. - Updates the `UsageFailure` notes in `ts/packages/cli/AGENTS.md`, the `cli-command` skill reference, and the comment in `cli-main.ts`. - Adds a subprocess test and a CHANGELOG entry. ## Context `composio execute GMAIL_FETCH_EMAILS --account does-not-exist-xyz -d '{}'` printed a good message under a crash banner: ``` 💥 services/ConnectedAccountResolutionError • No connected account matched "does-not-exist-xyz" for toolkit "gmail". No active connected accounts were found for that toolkit. ◯ ╰─ composio-cli at jKt (/$bunfs/root/composio:1178:10294) ``` `cli-main.ts` already has one path for expected failures (`isUsageFailure`), so this PR adds the error to that union instead of adding a special case. It joins the union as a whole, the way `ProjectResolutionError` (including its `request_failed` reason) already does. Verification: - New test in `test/src/cli-main.test.ts` spawns `src/bin.ts` against the local fake backend. It asserts exit 1, empty stdout, and stderr equal to the one-line message, with no `💥`, error tag, or `composio-cli` span. With the `errors.ts` change reverted it fails (`expected '💥 services/ConnectedAccountResoluti…'`). - Ran CLI `pnpm run test` (2203 passed; `validate:command-tests` still has 2 exemptions), `pnpm run typecheck`, `lint:effect`, oxlint, prettier, and root `pnpm typecheck`. - Built the binary from `origin/next` and from this branch and ran both with an isolated HOME and a fake `uak_` key against a local fake server: - `next`, `execute … --account does-not-exist-xyz`: exit 1, stderr is the banner and stack shown above. - This branch, same command: exit 1, empty stdout, stderr is only `No connected account matched "does-not-exist-xyz" for toolkit "gmail". No active connected accounts were found for that toolkit.` - `proxy … --toolkit gmail --account does-not-exist-xyz`: same before and after as `execute`.

Alberto Schiabel committed Oct 21, 2026 at 19:05 UTC 878da4fdf62185a57f8a59258e7f09e0dfb6c1f6
6 files changed +44 -7
.agents/skills/cli-command/references/implementation.md
+1 -1
@@ -17,7 +17,7 @@ test/src/commands/<group>/<name>/<group>.<name>.handler.test.ts handler-level
17 - Top-level commands use the same shape without a group: `src/commands/<name>/<name>.cmd.ts`.
18 - Register new commands through `src/commands/index.ts` or the nearest group entry.
19 - A usage mistake the parser cannot see (flag combination, business rule, missing input) raises `CommandInputError` via `commandInputError('<command>')` from `src/commands/errors.ts`, with the `option` at fault; `cli-main.ts` prints the message and exits 1. Do not add a per-command message-only error class.
20 -- A command that needs a login pipes `requireLogin` from `src/effects/require-auth.ts` on itself or on its group entry after `Command.withSubcommands`; the handler never checks `apiKey`. `resolveCommandProject` fails with `ProjectResolutionError`; let it flow, it prints and exits 1 like `CommandInputError`.
20 +- A command that needs a login pipes `requireLogin` from `src/effects/require-auth.ts` on itself or on its group entry after `Command.withSubcommands`; the handler never checks `apiKey`. `resolveCommandProject` fails with `ProjectResolutionError` and `resolveConnectedAccountForToolkit` with `ConnectedAccountResolutionError`; let them flow, they print and exit 1 like `CommandInputError`.
21 - A command still in the legacy single-file shape (`<group>/commands/<group>.<name>.cmd.ts`, or top-level `<name>.cmd.ts`) is migrated in the PR that next changes it substantively, one command per PR.
22 - `pnpm run validate:command-tests` (in `pnpm test`) fails on a command without its mirrored `.cmd.test.ts`, on an orphan `.cmd.test.ts`, and on a stale exemption. Add the test with the command; do not add exemptions.
23
ts/packages/cli/AGENTS.md
+1 -1
@@ -214,7 +214,7 @@ Each `Arr.bind` adds one independent axis to the generated cases.
214 - Never branch on an Effect value's internal tag field directly. Use the owning module's public refinement or matcher (`Option`, `Result`, `Exit`, `Cause`, `CliError`), `Match.valueTags` for exhaustive unions, or `Predicate.isTagged` for a single narrowing guard.
215 - Do not wrap a plain `Error` in `Effect.fail` for expected failures. Give the failure a meaningful `Data.TaggedError` type with structured fields and a preserved cause, then recover with `catchTag` / `catchTags`. Reserve `Effect.die` and `Effect.dieMessage` for impossible invariants.
216 - Treat `unknown`, JSON, and persisted state as trust boundaries. Decode them with `effect/Schema` or narrow them with `Predicate`; an `as` assertion is not validation, and hand-rolled structural guards (`'x' in obj` / `typeof` chains) are not a substitute for a schema. Each typed API response is validated at most once. The CLI's own schema validates a response the CLI transforms, filters for stdout, or writes to a cache file: the catalog models (`src/models/toolkits.ts`, `tools.ts`, `trigger-types.ts`), the auth-config and connected-account allowlists that keep credential-bearing fields off stdout (including the list responses and the `auth-configs create` response in `src/models/auth-configs.ts` and `connected-accounts.ts`), the `ToolkitSlug` path-safety check, the `Session` `DateTime` transform, and `TriggerInstanceItems`. Those calls decode with the CLI schema, failing with `services/HttpDecodingError`. The client validates a response against its own generated schema only when the call passes the `validated` request option (`src/services/composio-request.ts`); a mismatch fails with the client's `DecodeError`, which the CLI reports with the operation, the request id, and an upgrade hint. Pass `validated` only on a read the CLI consumes whole through the client's types, where no field may drift: `cli.realtime.credentials` (every field feeds the realtime connection), `org.list` (organization ids and names for login), and `org.consumer.listConnectedToolkits` (a list of slugs). Every other typed call leaves it off: calls that are not reads, because failing after the server acted would invite a retry that repeats the side effect; reads the CLI validates with its own schema; and reads that must tolerate drift because the CLI consumes a few fields of a response whose client schema fixes enums or requires fields the CLI never reads (`logs.tools.*`, `logs.triggers.*`, `tools.list`, `tools.retrieve`, `org.project.list`, `toolRouter.session.search`, `toolRouter.session.toolkits`, `connectedAccounts.list`, which tolerates unknown statuses, and `triggerInstances.listActive`, whose page counts the CLI defaults). Adding a validated read means saying in its doc comment why the CLI cannot tolerate drift there. Responses fetched with the raw `client.get`/`client.post` are untyped and always need a CLI schema (`LatestToolVersionResponse` in `src/models/tools.ts`, and the consumer config and permission payloads in `tool-permissions.ts`). `effect/Schema` is the CLI's schema tool — do not introduce zod here (zod is the convention in the SDK packages and docs).
217 -- Do not inspect private `effect/cli` internals (parser state, `HelpDoc` string shapes, `CliError` suggestion machinery). `Command.runWith` renders help and parse/validation errors itself — see the entry-point section above — so command-tree introspection must stay on the public `Command.Any` surface (`name`, `alias`, `subcommands`). `CliError.InvalidValue` takes structured `{ option, value, expected, kind }` fields, not a free-form message — handler-level validation raises `CommandInputError` from `src/commands/errors.ts` (built with `commandInputError('<command>')`, carrying `command`, `message`, and the `option` at fault), not a hand-built `CliError`. It, `NotLoggedInError`, and `ProjectResolutionError` are the `UsageFailure` union (`isUsageFailure` in `errors.ts`): `cli-main.ts` prints the message as one line and exits 1, with no defect banner.
217 +- Do not inspect private `effect/cli` internals (parser state, `HelpDoc` string shapes, `CliError` suggestion machinery). `Command.runWith` renders help and parse/validation errors itself — see the entry-point section above — so command-tree introspection must stay on the public `Command.Any` surface (`name`, `alias`, `subcommands`). `CliError.InvalidValue` takes structured `{ option, value, expected, kind }` fields, not a free-form message — handler-level validation raises `CommandInputError` from `src/commands/errors.ts` (built with `commandInputError('<command>')`, carrying `command`, `message`, and the `option` at fault), not a hand-built `CliError`. It, `NotLoggedInError`, `ProjectResolutionError`, and `ConnectedAccountResolutionError` (an `--account` selector that matches no connected account, or the account lookup behind it failing) are the `UsageFailure` union (`isUsageFailure` in `errors.ts`): `cli-main.ts` prints the message as one line and exits 1, with no defect banner.
218 - Prefer `Effect.mapError`, `Effect.matchEffect`, and typed recovery over `Effect.catch` blocks (the v4 name for what was `Effect.catchAll`) that flatten distinct failures into one message-only error.
219
220 ### Effect Boundary Policy
ts/packages/cli/CHANGELOG.md
+7
@@ -11,6 +11,13 @@
11 messages on stderr are unchanged. In `composio run`, `execute()` still
12 rejects with the tool's error message and the failed result.
13
14 +- `composio execute` and `composio proxy` now report an `--account` that
15 + matches no connected account (`No connected account matched "…"`) as one
16 + line on stderr and exit 1, like other usage errors. They used to print it
17 + under a `💥` banner with the error tag and a stack location, as if the CLI had
18 + crashed. A failure to load the toolkit's connected accounts is reported the
19 + same way. Nothing is printed on stdout.
20 +
21 - `composio execute` now sends the execution itself (single, `--parallel`, and
22 meta tools) through the Composio Dashboard instead of calling the backend
23 directly. Output, exit codes, error details, connection tips, and `--json`
ts/packages/cli/src/cli-main.ts
+3 -3
@@ -318,9 +318,9 @@ const cliProgram = (argv: ReadonlyArray<string>) =>
318 process.exitCode = 1;
319 })
320 ),
321 - // A usage mistake, a missing login, or an unresolved project is not a broken invariant:
322 - // print the one-line fix and exit non-zero instead of routing it through the defect
323 - // reporter below.
321 + // A usage mistake, a missing login, an unresolved project, or an `--account` that selects
322 + // no connected account is not a broken invariant: print the one-line fix and exit non-zero
323 + // instead of routing it through the defect reporter below.
324 Effect.catchIf(
325 (error): error is UsageFailure => isUsageFailure(error),
326 error =>
ts/packages/cli/src/commands/errors.ts
+5 -2
@@ -1,5 +1,6 @@
1 import { Data } from 'effect';
2 import { ProjectResolutionError } from 'src/services/command-project';
3 +import { ConnectedAccountResolutionError } from 'src/services/connected-account-selection';
4
5 /**
6 * A usage mistake the parser cannot see: a flag combination, a value that fails a business
@@ -28,12 +29,14 @@ export const notLoggedIn = (): NotLoggedInError =>
29 * Failures the user fixes by changing the invocation or their setup, not defects. `cli-main.ts`
30 * prints the message as one line on stderr and exits 1.
31 */
31 -export type UsageFailure = CommandInputError | NotLoggedInError | ProjectResolutionError;
32 +export type UsageFailure =
33 + CommandInputError | NotLoggedInError | ProjectResolutionError | ConnectedAccountResolutionError;
34
35 export const isUsageFailure = (error: unknown): error is UsageFailure =>
36 error instanceof CommandInputError ||
37 error instanceof NotLoggedInError ||
36 - error instanceof ProjectResolutionError;
38 + error instanceof ProjectResolutionError ||
39 + error instanceof ConnectedAccountResolutionError;
40
41 /** Builds the constructor a command uses for its own input errors. */
42 export const commandInputError =
ts/packages/cli/test/src/cli-main.test.ts
+27
@@ -499,3 +499,30 @@ describe('reported tool execution failures', () => {
499 30_000
500 );
501 });
502 +
503 +describe('account selection errors', () => {
504 + it(
505 + '[Given] an `--account` that matches no connected account [Then] prints the message as one line and exits 1',
506 + () =>
507 + withHttpServer(fakeComposio, async baseUrl => {
508 + const result = await runCliAgainst(baseUrl, [
509 + 'execute',
510 + 'GMAIL_FETCH_EMAILS',
511 + '--account',
512 + 'does-not-exist-xyz',
513 + '-d',
514 + '{}',
515 + ]);
516 +
517 + expect(result.status).toBe(1);
518 + expect(result.stdout).toBe('');
519 + expect(result.stderr.trim()).toBe(
520 + 'No connected account matched "does-not-exist-xyz" for toolkit "gmail". No active connected accounts were found for that toolkit.'
521 + );
522 + expect(result.stderr).not.toContain('💥');
523 + expect(result.stderr).not.toContain('ConnectedAccountResolutionError');
524 + expect(result.stderr).not.toContain('composio-cli');
525 + }),
526 + 30_000
527 + );
528 +});