@devries-cameron20 / composio Mirror · read-only / commits / 1ea1e77c6
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, 06:00 UTC

fix(cli): show dev-tree examples on `dev connected-accounts link --help` (#5327)

This PR: - builds the `link` examples from the help page's path (`Command.withExamples(({ commandPath }) => …)`), so the one definition registered as `composio link` and as `composio dev connected-accounts link` shows each page its own command; the dev page used to show `composio link github` and two more root examples, which link the consumer user - replaces "so tools can act on your behalf" with a description that says which user each tree acts as, without naming the dev group's flags on the root page - adds a check to `command-references.test.ts`: every listed page's rendered `--help`, each `composio …` example under EXAMPLES must resolve to a command on the page's own tree; on the old code it fails with exactly the three dev-page examples - adds argv-level help tests for both `link` pages, and regenerates `COMMANDS.md` ## Context An audit of all 78 registrations and 66 rendered examples found this page to be the only one whose examples cross trees; `execute` / `dev playground-execute` already rewrites its examples. The existing reference test only checks that `composio link github` names a real command, not that it is on the tree of the page that shows it. Found while measuring agent runs for https://github.com/ComposioHQ/composio/pull/5312, where agents on developer tasks reached for root commands.

Alberto Schiabel committed Nov 12, 2026 at 14:37 UTC 1ea1e77c6478c35eda7aac1c2d10a04c19e5b50e
5 files changed +113 -16
ts/packages/cli/CHANGELOG.md
+6
@@ -4,6 +4,12 @@
4
5 ### Patch Changes
6
7 +- `composio dev connected-accounts link --help` now shows
8 + `composio dev connected-accounts link …` examples. It showed root
9 + `composio link …` examples, which link the consumer user, not a user of the
10 + developer project. The description of both pages now says which user each
11 + command acts as.
12 +
13 - `composio link` and `composio dev connected-accounts link` now print the
14 authorization URL when stderr is not a terminal, as under a script, CI or a
15 coding agent, before they wait for the authorization. The URL used to go
ts/packages/cli/src/commands/COMMANDS.md
+2 -2
@@ -38,7 +38,7 @@ Every command registration of the CLI, its help summary, and the file that defin
38 | `dev auth-configs list` | “List auth configs.” | dev | `ts/packages/cli/src/commands/auth-configs/list/auth-configs.list.cmd.ts` | | | yes | listed |
39 | `dev connected-accounts` | “View and manage Composio connected accounts.” | dev | `ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts` | | | yes | listed |
40 | `dev connected-accounts info` | “View details of a specific connected account.” | dev | `ts/packages/cli/src/commands/connected-accounts/info/connected-accounts.info.cmd.ts` | | | yes | listed |
41 -| `dev connected-accounts link` | “Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf.” | dev | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `link` | yes | listed |
41 +| `dev connected-accounts link` | “Connect an external account (GitHub, Gmail, Slack, etc.) for the user this command acts as.” | dev | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `link` | yes | listed |
42 | `dev connected-accounts list` | “List connected accounts.” | dev | `ts/packages/cli/src/commands/connected-accounts/list/connected-accounts.list.cmd.ts` | | | yes | listed |
43 | `dev connected-accounts whoami` | “Show the external account profile for a connected account.” | dev | `ts/packages/cli/src/commands/connected-accounts/whoami/connected-accounts.whoami.cmd.ts` | | | yes | listed |
44 | `dev init` | “Initialize this directory with a developer project.” | dev | `ts/packages/cli/src/commands/init.cmd.ts` | | | no | listed |
@@ -69,7 +69,7 @@ Every command registration of the CLI, its help summary, and the file that defin
69 | `generate ts` | “Generate TypeScript type stubs for toolkits, tools, and triggers.” | root | `ts/packages/cli/src/commands/generate/ts/generate.ts.cmd.ts` | | | no | listed |
70 | `help` | “Show help for a command.” | root | `ts/packages/cli/src/commands/root-help.ts` | | | no | listed |
71 | `install` | “Set up shell integration (PATH and completions). Set COMPOSIO_BIN_DIR to choose the directory added to PATH; it otherwise defaults to ~/.local/bin when that holds this executable, and to the directory of the running binary.” | root | `ts/packages/cli/src/commands/install/install.cmd.ts` | | | no | listed |
72 -| `link` | “Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf.” | root | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `dev connected-accounts link` | yes | listed |
72 +| `link` | “Connect an external account (GitHub, Gmail, Slack, etc.) for the user this command acts as.” | root | `ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts` | | `dev connected-accounts link` | yes | listed |
73 | `listen` | “Listen to consumer-project realtime events. Trigger slugs create a temporary trigger; top-level composio.* event types subscribe directly.” | root | `ts/packages/cli/src/commands/listen/listen.cmd.ts` | | | yes | experimental |
74 | `login` | “Log in to the Composio SDK.” | root | `ts/packages/cli/src/commands/login/login.cmd.ts` | | | no | listed |
75 | `logout` | “Log out from the Composio SDK.” | root | `ts/packages/cli/src/commands/logout.cmd.ts` | | | no | listed |
ts/packages/cli/src/commands/connected-accounts/link/connected-accounts.link.cmd.ts
+16 -13
@@ -37,17 +37,20 @@ const list = Flag.Boolean('list').pipe(
37 )
38 );
39
40 -const linkExamples = [
41 - {
42 - command: 'composio link github',
43 - },
44 - {
45 - command: 'composio link gmail --alias work',
46 - },
47 - {
48 - command: 'composio link github --list',
49 - },
50 -];
40 +/**
41 + * Built from the path the help page shows, because this one definition is registered on both
42 + * trees: as `composio link` (the consumer user) and as `composio dev connected-accounts link`
43 + * (a developer project's user). A fixed `composio link …` would teach the root command on the
44 + * dev page.
45 + */
46 +const linkExamples = ({ commandPath }: { readonly commandPath: ReadonlyArray<string> }) => {
47 + const command = commandPath.join(' ');
48 + return [
49 + { command: `${command} github` },
50 + { command: `${command} gmail --alias work` },
51 + { command: `${command} github --list` },
52 + ];
53 +};
54
55 const connectedAccountsCmd$LinkBase = Command.make(
56 'link',
@@ -55,10 +58,10 @@ const connectedAccountsCmd$LinkBase = Command.make(
58 runConnectedAccountsLink
59 ).pipe(
60 Command.withDescription(
58 - 'Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf.\nOpens a browser for OAuth authorization and waits for confirmation.'
61 + 'Connect an external account (GitHub, Gmail, Slack, etc.) for the user this command acts as.\nOpens a browser for OAuth authorization and waits for confirmation.\n`composio link` acts as you; `composio dev connected-accounts link` acts as a user of a developer project, its test user unless another is named.'
62 ),
63 Command.withShortDescription(
61 - 'Connect an external account (GitHub, Gmail, Slack, etc.) so tools can act on your behalf.'
64 + 'Connect an external account (GitHub, Gmail, Slack, etc.) for the user this command acts as.'
65 ),
66 Command.withExamples(linkExamples),
67 withCommandMeta({ requiresLogin: true })
ts/packages/cli/test/src/commands/command-references.test.ts
+42
@@ -8,12 +8,18 @@
8 * (`test/__utils__/command-tree.ts`). The walk stops at the first word that is not a subcommand;
9 * the reference is broken when it stopped at a group whose next word looks like a subcommand
10 * name, or before any command at all, unless that text is prose listed in `NOT_COMMANDS`.
11 + *
12 + * A help page's examples are checked again as the page renders them, since a definition
13 + * registered on both trees renders one set of examples on two pages: each example must name a
14 + * command on the tree of the page that shows it.
15 */
16 import * as fs from 'node:fs';
17 import * as path from 'node:path';
18 import { describe, expect, it } from '@effect/vitest';
19 +import { Effect } from 'effect';
20 import type { Command } from 'effect/cli';
21 import ts from 'typescript';
22 +import { cli, MockConsole, TestLive } from 'test/__utils__';
23 import { registrationsOf } from 'test/__utils__/command-tree';
24
25 const srcDir = path.resolve(import.meta.dirname, '../../../src');
@@ -112,3 +118,39 @@ describe('command references in user-facing strings', () => {
118 expect(NOT_COMMANDS.filter(reference => !unresolved.includes(reference))).toEqual([]);
119 });
120 });
121 +
122 +/** The tree a command path is on: everything under `dev` is the dev tree. */
123 +const treeOf = (names: ReadonlyArray<string>) => (names[0] === 'dev' ? 'dev' : 'root');
124 +
125 +/** The `composio …` lines of the EXAMPLES section of a rendered help page. */
126 +const examplesOf = (help: string): ReadonlyArray<string> => {
127 + const [, section = ''] = help.split(/^EXAMPLES$/m);
128 + return section
129 + .split('\n')
130 + .map(line => line.trim())
131 + .filter(line => line.startsWith('composio '));
132 +};
133 +
134 +const helpPages = registrationsOf()
135 + .filter(({ identity, unlisted }) => identity.path.length > 0 && !unlisted)
136 + .filter(({ identity }) => identity.path[0] !== 'help')
137 + .map(({ identity }) => ({ path: identity.path, page: identity.path.join(' ') }));
138 +
139 +describe('help examples', () => {
140 + // A fresh layer per page, so one page's output is not read as the next one's.
141 + it.effect.each(helpPages)('on `composio $page --help` name commands on its tree', ({ path }) =>
142 + Effect.gen(function* () {
143 + yield* cli([...path, '--help']);
144 + const help = (yield* MockConsole.getLines({ stripAnsi: true, stream: 'stdout' })).join('\n');
145 + const offTree = examplesOf(help).flatMap(example =>
146 + [...example.matchAll(REFERENCE)].flatMap(match => {
147 + const { names } = resolve(match[1]!.trim().split(' '));
148 + return names.length > 0 && treeOf(names) !== treeOf(path)
149 + ? [`${example} (names \`composio ${names.join(' ')}\`)`]
150 + : [];
151 + })
152 + );
153 + expect(offTree).toEqual([]);
154 + }).pipe(Effect.provide(TestLive()))
155 + );
156 +});
ts/packages/cli/test/src/commands/connected-accounts/link/connected-accounts.link.cmd.test.ts
+47 -1
@@ -1,5 +1,5 @@
1 import { BadRequestError } from '@composio/client/effect';
2 -import { describe, expect, layer } from '@effect/vitest';
2 +import { describe, expect, it, layer } from '@effect/vitest';
3 import { ConfigProvider, Console, Effect } from 'effect';
4 import { cli, TestLive, MockConsole } from 'test/__utils__';
5 import { exitCodeOf } from 'test/__utils__/exit-code';
@@ -603,3 +603,49 @@ describe('CLI: composio dev connected-accounts link', () => {
603 );
604 });
605 });
606 +
607 +describe('CLI: link --help on each tree', () => {
608 + /** What `--help` printed on stdout, and how it exited. */
609 + const help = (args: ReadonlyArray<string>) =>
610 + Effect.gen(function* () {
611 + const exitCode = exitCodeOf(yield* Effect.exit(cli([...args, '--help'])));
612 + const stdout = yield* MockConsole.getLines({ stripAnsi: true, stream: 'stdout' });
613 + return { exitCode, stdout: stdout.join('\n') };
614 + }).pipe(Effect.provide(TestLive()));
615 +
616 + const examples = (stdout: string) =>
617 + (stdout.split(/^EXAMPLES$/m)[1] ?? '')
618 + .split('\n')
619 + .map(line => line.trim())
620 + .filter(line => line !== '');
621 +
622 + it.effect('[Given] composio link --help [Then] its examples are root `composio link`', () =>
623 + Effect.gen(function* () {
624 + const { exitCode, stdout } = yield* help(['link']);
625 + expect(exitCode).toBe(0);
626 + expect(examples(stdout)).toEqual([
627 + 'composio link github',
628 + 'composio link gmail --alias work',
629 + 'composio link github --list',
630 + ]);
631 + })
632 + );
633 +
634 + it.effect(
635 + '[Given] composio dev connected-accounts link --help [Then] its examples stay on the dev tree',
636 + () =>
637 + Effect.gen(function* () {
638 + const { exitCode, stdout } = yield* help(['dev', 'connected-accounts', 'link']);
639 + expect(exitCode).toBe(0);
640 + expect(examples(stdout)).toEqual([
641 + 'composio dev connected-accounts link github',
642 + 'composio dev connected-accounts link gmail --alias work',
643 + 'composio dev connected-accounts link github --list',
644 + ]);
645 + // The page says who it acts as, and offers the dev group's user and project flags.
646 + expect(stdout).toContain('acts as a user of a developer project');
647 + expect(stdout).toContain('--user-id');
648 + expect(stdout).toContain('--project-name');
649 + })
650 + );
651 +});