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): provide the command surface and share the dev group's flags (#4900)
This PR: - adds `CommandSurface` (`src/commands/surface.ts`): the root tree provides `{ tree: 'root' }`, the `dev` group provides `{ tree: 'dev', userId, projectName }` from its new shared `--user-id` and `--project-name` flags (`Command.withSharedFlags` + `Command.provide` on `dev.cmd.ts`), accepted before or after the subcommand name - defines each dual command once and moves it to the directory shape: `search` (`tools/search/`, the never-registered dev variant `toolsCmd$Search` is gone), `link` (`connected-accounts/link/`), `triggers list` and `triggers info` (`triggers/list/`, `triggers/info/`; the per-tree hints come from the surface), `toolkits info` (`toolkits/info/`); their handlers read the surface instead of a `rootOnly` parameter - keeps two registrations for `execute` / `playground-execute` because the names differ, over one handler that reads `--user-id`/`--project-name` from the surface - drops the private `--user-id` of `connected-accounts list`, `toolkits list` and `triggers listen`, which `withSharedFlags` rejects as duplicates on a direct `dev` subcommand; they read the surface and stay in the legacy shape until their own units - makes every `dev` command either honor each shared flag or reject it: `connected-accounts list`, `toolkits list`, `toolkits info`, `listen` and `triggers listen` resolve the named project (`resolveSurfaceProject`, `namedProjectClient`); the commands that cannot honor a flag yet (`init`, `auth-configs`, `projects`, `toolkits search|version`, `connected-accounts info|whoami`, `triggers list|info|status|create|enable|disable` for both flags, `logs` for `--project-name` only) pipe `rejectsSharedFlags`, and the group's own `dev --mode` toggle calls `rejectSharedFlags`, so each fails with a `CommandInputError` instead of accepting and ignoring the flag - keeps a named project from borrowing the directory's test user: without `--user-id`, `playground-execute`, `connected-accounts link` (`--list`, `--auth-config`), `toolkits info` and `toolkits list` use the directory's `test_user_id` only when `--project-name` is absent or names the directory's own project, and otherwise fall back to the global test user (`directoryTestUserId` in `surface.ts`); with no test user at all, the missing-user error points at `--user-id` or `composio login` instead of `composio dev init` - `dev logs tools` and `dev logs triggers` read their comma-separated `--user-id` filter from the surface, since the shared flag takes every `--user-id` under `dev`; `playground-execute --parallel` falls back to the surface's `--user-id`/`--project-name` when they come before the command name, and finds its command name past a flag value that spells the same word - adds `test/src/commands/surface.test.ts`: both shared rows on every `dev` page and on none of the root pages, the flags reaching a handler before and after the subcommand name, `--project-name` reaching the project resolver for every command that honors it (and `playground-execute --parallel` before and after the command name, including a `--user-id`/`--project-name` value spelled `playground-execute`), each shared flag rejected on the commands that cannot honor it and on the `dev --mode` toggle (which still toggles without them), the test-user fallback for another project, the directory's own project, and no `--project-name` on each of those four commands, and `search --user-id` rejected on the root tree; the `dev logs` client suites check the `user_id` search params before and after the subcommand name - documents the layout rule in `ts/packages/cli/AGENTS.md` and the user-visible change in `CHANGELOG.md` ## Context Unit U1 of the command-layout series (`CommandSurface` as a service, chosen over per-command factories). Two facts of `effect@4.0.3`, checked against the vendored source and a probe, made a help change unavoidable: a direct subcommand may not redeclare a shared flag, and help prepends an ancestor's shared flags to every descendant page. The deliberate help changes, agreed before implementation: - every `dev` page lists `--user-id` and `--project-name` once, with one description each; the dual commands lose their own copies of the two rows - `dev logs tools` and `dev logs triggers` keep their comma-separated `--user-id` filter (allowed below a group entry), which their page shows in place of the shared row - `composio link --help` lists `--auth-config` (one `Command` value); the root command still rejects it with the same `CommandInputError` as before - `composio dev connected-accounts link --help` shows the root examples (`composio link …`), since examples live on the one `Command` value Help diff against `next` (refreshed for the final `--user-id` description, which also covers the commands that use it as a filter), captured through the test harness for 20 pages (`execute`, `search`, `toolkits info`, `tools list`, `triggers list`, `triggers info` are byte-identical; only the rows below changed, plus column re-padding): ```diff === dev.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_auth-configs_create.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_connected-accounts_link.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory < --user-id string Developer-project user ID override < --project-name string Developer project name override for this command < composio dev connected-accounts link github < composio dev connected-accounts link gmail --alias work < composio dev connected-accounts link github --list > composio link github > composio link gmail --alias work > composio link github --list === dev_connected-accounts_list.txt < --user-id string Filter by user ID > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_init.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_logs.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_playground-execute.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory < --user-id string Developer-project user ID override < --project-name string Developer project name override for this command === dev_projects_list.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_toolkits_info.txt < --user-id string User ID for connection status (falls back to project/global test_user_id, then "default") > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_toolkits_list.txt < --user-id string User ID for connection status (falls back to project/global test_user_id) > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_triggers_info.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_triggers_list.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory === dev_triggers_listen.txt > --user-id string User id to act as or filter by. Commands that act as a user default to the project test user id, then the global one. > --project-name string Developer project to use instead of the one configured in this directory < --user-id string Filter by user id === link.txt > --auth-config string Auth config ID (e.g. "ac_..."). Uses legacy flow (no Tool Router). ``` Argv behaviour, exit codes and stdout/stderr lines are unchanged, with two exceptions: a shared flag on a `dev` command that cannot honor it exits 1 with a usage error naming the flag, after the login check (before this PR the flag did not exist there and failed as unknown at parse time, so it stays loud), and root `composio link --auth-config` fails with the consumer-only usage message after the login check instead of as an unrecognized flag. Every pre-existing suite passes as is after the moves (the `dev … --user-id` tests parse through the shared flag). Left for later units: `execute`'s internal `surface`/`projectMode` fields (U4), the `link` handler split into three functions (U5), `connected-accounts list`, `toolkits list` and `triggers listen` moving to the directory shape (U8, U9). ## Deferred - `triggers listen` stays in `COMMAND_TEST_EXEMPTIONS` until U8 adds its mirrored test; this PR does not touch the list, which may only shrink. - The plan's KTD2 (`ResolvedCommandProject` as a cached service) is not done here: each handler that needs a project resolves it once through `resolveSurfaceProject` with the surface's `projectName`, so nothing resolves twice yet. - Per-command `--help` snapshot files are not added; the help diff against `next` was captured through the test harness and is pasted above instead. Rebased on `next` after #4901, #4905, #4909 and #4906 (CHANGELOG entries kept side by side). Verified locally on the branch tip: `pnpm typecheck`; the CLI suite (153 files, 1812 passed, 1 skipped; `validate:command-tests` at 18 exemptions, `validate:boundaries` unchanged); `lint:effect` 0 diagnostics; `oxlint` and prettier clean on every touched file, `validate:agent-skills` and `validate:skill-routing` pass. Binary smoke (`build` + `build:binary`, isolated `HOME`, developer mode on, logged out): `--version` exits 0; `dev --mode off --project-name x`, `dev --user-id a --mode on` and `dev init --user-id a` exit 1 with the usage message and leave developer mode on; `dev toolkits search email --project-name x`, `dev toolkits list --project-name x` and `link gmail --auth-config ac_1` exit 1 with the login hint; `search email --user-id x` exits 1 with `Unrecognized flag: --user-id in command composio search`; `dev toolkits info --help` lists both shared flags once. The logged-in transcript needs a real account and was not run.