@devries-cameron20 / composio Mirror · read-only / commits / 9498679c2
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, 18:30 UTC

fix(release): guard and document CLI releases (#3895)

This PR: - removes the stale `@composio/cli` changeset that wedges `changesets/action` and preserves its release note in the CLI changelog - adds `validate:changesets` before the TypeScript release action and covers ignored-package changesets in the release regression suite - makes the guard read changeset files directly so it also works in shallow and detached CI checkouts - refreshes `mise.lock` after the pinned Python standalone artifacts moved to the 20260718 build - adds the repo-local `cli-release` skill with beta, stable-promotion, verification, and failure-recovery procedures - replaces the contradictory "stable via changeset" contributor guidance with the tested-beta promotion path - extends skill taxonomy, routing probes, and PR path filters so the guard cannot silently drift ## Regression coverage The validator test creates a changeset fixture outside a Git repository, verifies that an ignored CLI package is rejected, then verifies that a normal package changeset passes. This reproduces the shallow-checkout failure without relying on a local `next` ref. ## Verification - `pnpm validate:agent-skills` - `pnpm validate:skill-routing` - `pnpm validate:changesets` - `pnpm test:release-workflow` - `pnpm lint` - `pnpm install --frozen-lockfile` - all 24 TypeScript package test tasks - skill-creator `quick_validate.py` - Prettier check - `git diff --check` - manual beta release [`@composio/cli@0.2.33-beta.294`](https://github.com/ComposioHQ/composio/releases/tag/%40composio/cli%400.2.33-beta.294): 33/33 release and installation jobs passed

Alberto Schiabel committed Jul 20, 2026 at 23:17 UTC 9498679c26c1f40a50409541ade54029bb1c5bb6
17 files changed +410 -63
.agents/skills/cli-release/SKILL.md new
+27
@@ -0,0 +1,27 @@
1 +---
2 +name: cli-release
3 +description: Release and recover first-party Composio CLI binaries through Build CLI Binaries, including automatic beta builds, promote-stable dispatches, beta-tag selection, asset and installation verification, and failed release recovery. Use when a contributor asks to build a CLI beta, publish or promote a stable CLI version, choose a release candidate, monitor a CLI release, or diagnose a failed CLI release. Do not use for TypeScript SDK Changesets releases or CLI source implementation.
4 +---
5 +
6 +# CLI Release
7 +
8 +Use this skill for the GitHub Release that powers the standalone `composio` binary and installer.
9 +
10 +Read `references/release-workflow.md` before selecting a candidate or dispatching a workflow.
11 +
12 +## Release Contract
13 +
14 +- Never add a Changeset for `@composio/cli` or `@composio/cli-local-tools`; both packages are ignored by Changesets and such files wedge `ts.release.yml`.
15 +- Treat a merge to `next` that touches CLI paths as a beta build. Promote a tested beta with the `promote-stable` workflow action for the normal stable-release path.
16 +- Treat a direct CLI `package.json` version bump as a release-owner-only recovery path, not the contributor default.
17 +- Resolve beta tags and workflow state from GitHub immediately before acting. Never invent or reuse a stale candidate from memory.
18 +- A stable promotion is a production write. If the user did not name the exact beta tag, present the resolved candidate and obtain explicit confirmation before dispatching it.
19 +- Follow the release through asset verification, installation tests, and the Homebrew tap update. Do not stop after the dispatch succeeds.
20 +
21 +## Execution
22 +
23 +1. Classify the request as automatic beta, manual beta, stable promotion, or recovery.
24 +2. Run the playbook's read-only preflight and identify the exact source commit and release tag.
25 +3. Dispatch only the requested workflow action and watch the resulting run to completion.
26 +4. Verify the published release and downstream checks named in the playbook.
27 +5. Report the released tag, source beta or commit, workflow URL, asset state, install-test result, and any remaining follow-up.
.agents/skills/cli-release/references/release-workflow.md new
+180
@@ -0,0 +1,180 @@
1 +# CLI Release Workflow
2 +
3 +## Contents
4 +
5 +- [Sources Of Truth](#sources-of-truth)
6 +- [Choose The Path](#choose-the-path)
7 +- [Changeset Rule](#changeset-rule)
8 +- [Inspect Candidates](#inspect-candidates)
9 +- [Build A Manual Beta](#build-a-manual-beta)
10 +- [Promote A Beta To Stable](#promote-a-beta-to-stable)
11 +- [Verify Completion](#verify-completion)
12 +- [Failure Recovery](#failure-recovery)
13 +
14 +## Sources Of Truth
15 +
16 +- `.github/workflows/build-cli-binaries.yml` owns beta and stable GitHub Releases.
17 +- `.github/scripts/cli-release/resolve-release-target.sh` decides the tag and source commit.
18 +- `.github/scripts/cli-release/verify-assets.sh` defines the required asset set.
19 +- `.github/workflows/cli.test-installation.yml` validates installers after publication.
20 +- `.github/workflows/cli.bump-homebrew-tap.yml` updates Homebrew for stable releases.
21 +- `.changeset/config.json` ignores `@composio/cli` and `@composio/cli-local-tools`.
22 +
23 +`ts.release.yml` is the TypeScript SDK/npm release train. It is not the normal CLI binary release path.
24 +
25 +## Choose The Path
26 +
27 +| Goal | Path | Result |
28 +| --- | --- | --- |
29 +| Ship an ordinary CLI change | Merge the reviewed PR to `next` | The push builds a rolling beta automatically. |
30 +| Build a beta from a branch | Dispatch `build-beta` at that branch | A prerelease is built from the branch commit. |
31 +| Publish a stable CLI | Promote an existing tested beta | The beta's source commit is rebuilt and published under the stable tag. |
32 +| Resume a failed promotion | Re-run or re-dispatch the same beta after inspecting the draft | An unpublished draft can be resumed and its assets replaced. |
33 +
34 +The resolver also treats a CLI `package.json` version change pushed to `next` as a stable release. Do not use that as the normal contributor procedure. It bypasses beta selection and is reserved for explicit release-owner recovery or migration work.
35 +
36 +## Changeset Rule
37 +
38 +Never create a `.changeset/*.md` entry for `@composio/cli` or `@composio/cli-local-tools` while those packages remain in `.changeset/config.json#ignore`.
39 +
40 +An ignored-package changeset makes `changesets/action` enter version-PR mode, while `changeset version` emits no commit. The action then fails with `No commits between next and changeset-release/next` and blocks unrelated SDK publishing.
41 +
42 +If a CLI change needs a human-facing note, update `ts/packages/cli/CHANGELOG.md` directly. Run this guard before handoff:
43 +
44 +```bash
45 +pnpm validate:changesets
46 +```
47 +
48 +## Inspect Candidates
49 +
50 +Use live GitHub state. Do not select a beta from local tags or remembered versions.
51 +
52 +```bash
53 +REPOSITORY=ComposioHQ/composio
54 +
55 +gh release list \
56 + --repo "$REPOSITORY" \
57 + --limit 100 \
58 + --json tagName,isPrerelease,isDraft,publishedAt \
59 + --jq '.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease and (.isDraft | not))'
60 +```
61 +
62 +For the chosen candidate, require a published prerelease and inspect its commit and assets:
63 +
64 +```bash
65 +BETA_TAG='@composio/cli@0.0.0-beta.000'
66 +
67 +gh release view "$BETA_TAG" \
68 + --repo "$REPOSITORY" \
69 + --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
70 + --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'
71 +```
72 +
73 +The beta must have `isDraft: false`, `isPrerelease: true`, and these six assets in `uploaded` state:
74 +
75 +- `composio-linux-x64.zip`
76 +- `composio-linux-aarch64.zip`
77 +- `composio-darwin-x64.zip`
78 +- `composio-darwin-aarch64.zip`
79 +- `composio-skill.zip`
80 +- `checksums.txt`
81 +
82 +Find the beta workflow run by its target commit and require it to be green, including the reusable installation-test jobs:
83 +
84 +```bash
85 +TARGET_COMMIT='replace-with-targetCommitish'
86 +
87 +gh run list \
88 + --repo "$REPOSITORY" \
89 + --workflow build-cli-binaries.yml \
90 + --commit "$TARGET_COMMIT" \
91 + --limit 10
92 +```
93 +
94 +If the user asked for a stable release without naming a beta, show the candidate and stop for confirmation before dispatching.
95 +
96 +## Build A Manual Beta
97 +
98 +Use this only when an explicit beta build is requested. The selected ref supplies both the workflow definition and source commit.
99 +
100 +```bash
101 +SOURCE_BRANCH='replace-with-branch'
102 +
103 +gh workflow run build-cli-binaries.yml \
104 + --repo "$REPOSITORY" \
105 + --ref "$SOURCE_BRANCH" \
106 + --raw-field action=build-beta
107 +```
108 +
109 +Watch the returned run through publication and installation tests. A beta is not a stable release and does not update Homebrew.
110 +
111 +## Promote A Beta To Stable
112 +
113 +Derive the stable tag by removing the beta suffix, then ensure no published stable release already exists:
114 +
115 +```bash
116 +STABLE_TAG="${BETA_TAG%%-beta.*}"
117 +
118 +gh release view "$STABLE_TAG" --repo "$REPOSITORY" --json tagName,isDraft,isPrerelease,publishedAt
119 +```
120 +
121 +- If the stable tag is absent, promotion may proceed.
122 +- If it is a draft, the promotion can resume it.
123 +- If it is already published, stop. Never overwrite a published release.
124 +
125 +Dispatch the current workflow from `next`; `promote-stable` resolves the source commit from the beta release itself:
126 +
127 +```bash
128 +gh workflow run build-cli-binaries.yml \
129 + --repo "$REPOSITORY" \
130 + --ref next \
131 + --raw-field action=promote-stable \
132 + --raw-field beta_tag="$BETA_TAG"
133 +```
134 +
135 +Use the returned URL when available. Otherwise identify the new dispatch, verify its creation time and actor, then watch it:
136 +
137 +```bash
138 +gh run list \
139 + --repo "$REPOSITORY" \
140 + --workflow build-cli-binaries.yml \
141 + --event workflow_dispatch \
142 + --branch next \
143 + --limit 5
144 +
145 +gh run watch RUN_ID --repo "$REPOSITORY" --compact --exit-status
146 +```
147 +
148 +## Verify Completion
149 +
150 +Do not call the release complete until all of these are true:
151 +
152 +1. `Build CLI Binaries` completed successfully.
153 +2. The stable release is published with `isDraft: false` and `isPrerelease: false`.
154 +3. All six canonical assets are present and uploaded.
155 +4. The workflow's installation-test matrix passed.
156 +5. `Bump Homebrew Tap` succeeded or reported that the formula was already current.
157 +
158 +```bash
159 +gh release view "$STABLE_TAG" \
160 + --repo "$REPOSITORY" \
161 + --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
162 + --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'
163 +
164 +gh run list \
165 + --repo "$REPOSITORY" \
166 + --workflow cli.bump-homebrew-tap.yml \
167 + --event release \
168 + --limit 5
169 +```
170 +
171 +Report the stable tag, promoted beta, target commit, workflow URL, asset count and state, installation result, and Homebrew result.
172 +
173 +## Failure Recovery
174 +
175 +- **Build matrix failed:** no release should publish. Fix the source, produce a new beta, and promote that candidate.
176 +- **Draft exists, publish did not finish:** inspect the failure, then re-run or re-dispatch the same beta. Draft assets are safely replaced with `--clobber`.
177 +- **Duplicate run says the release is already published:** this is an intentional safety failure. Verify the published release and stop the duplicate.
178 +- **Installation failed after publication:** do not mutate the published tag. Fix forward through a new beta and the next stable patch.
179 +- **Homebrew update failed:** keep the GitHub Release intact, fix the tap credential or workflow issue, then dispatch `cli.bump-homebrew-tap.yml` with the exact stable tag.
180 +- **TS release says there are no commits for the release PR:** remove any pending Changeset that targets an ignored CLI package, preserve its note in the CLI changelog, run `pnpm validate:changesets`, and let the next push retry the SDK release train.
.agents/skills/repo-guidance/references/repository-workflow.md
+1 -1
@@ -48,7 +48,7 @@ make build
48 ## Changesets
49
50 - Add a changeset for changes to published TypeScript packages.
51 -- For `@composio/cli`, add a changeset only when intentionally using the stable CLI binary release flow.
51 +- `@composio/cli` and `@composio/cli-local-tools` are ignored by Changesets. Never target them in a changeset while they remain ignored; use the `cli-release` skill for beta builds and stable promotion.
52 - Do not add a changeset for repo guidance, docs-only, tests-only, or validation-only changes unless release metadata changes.
53
54 ## Generated And Vendor Files
.changeset/whoami-respect-switched-org.md deleted
-5
@@ -1,5 +0,0 @@
1 ----
2 -'@composio/cli': patch
3 ----
4 -
5 -Fix `composio whoami` reporting the wrong organization after `composio orgs switch`. The command resolved session info without the `x-org-id` header, so the backend fell back to the API key's home org and ignored the switch. It now forwards the selected global org, matching how consumer commands resolve org context.
.github/workflows/ts.release.yml
+3
@@ -49,6 +49,9 @@ jobs:
49 - name: Install Dependencies
50 run: pnpm install --frozen-lockfile
51
52 + - name: Validate Changesets
53 + run: pnpm validate:changesets
54 +
55 - name: Run Linting
56 run: pnpm lint
57
.github/workflows/ts.test.yml
+8
@@ -4,20 +4,28 @@ on:
4 push:
5 branches: [master, next]
6 paths:
7 + - '.changeset/**'
8 - 'ts/**'
9 - '.github/actions/setup-node-pnpm-bun/action.yml'
10 + - '.github/workflows/ts.release.yml'
11 - '.github/workflows/ts.test.yml'
12 - 'mise.toml'
13 - 'mise.lock'
14 + - 'package.json'
15 + - 'test/release-workflow.test.ts'
16 - 'turbo.jsonc'
17 pull_request:
18 branches: [master, next]
19 paths:
20 + - '.changeset/**'
21 - 'ts/**'
22 - '.github/actions/setup-node-pnpm-bun/action.yml'
23 + - '.github/workflows/ts.release.yml'
24 - '.github/workflows/ts.test.yml'
25 - 'mise.toml'
26 - 'mise.lock'
27 + - 'package.json'
28 + - 'test/release-workflow.test.ts'
29 - 'turbo.jsonc'
30
31 concurrency:
AGENTS.md
+2
@@ -26,6 +26,7 @@ Use the smallest relevant skill:
26 - `eve`: durable backend AI agents built with the eve framework.
27 - `typescript-sdk`, `typescript-testing`, `typescript-providers`: TypeScript SDK/core/provider work.
28 - `cli-command`, `cli-e2e`: CLI design/implementation or CLI end-to-end tests.
29 +- `cli-release`: first-party CLI beta builds, stable promotion, release verification, or recovery.
30 - `python-sdk`, `python-testing`, `python-providers`, `python-release`: Python SDK/provider/testing/release work.
31
32 ## Repository Map
@@ -85,6 +86,7 @@ make build
86 ## Release And Package Notes
87
88 - TypeScript package releases use Changesets. Add a changeset only when published TypeScript packages change.
89 +- `@composio/cli` and `@composio/cli-local-tools` are excluded from Changesets; use `cli-release` for CLI binaries and never target those packages in a changeset while they remain ignored.
90 - Documentation-only and agent-guidance-only changes do not need a changeset.
91 - Python release metadata lives in `python/pyproject.toml`, `python/setup.py`, and `uv.lock`.
92 - Bumping generated clients is manual. Verify the package version is published before changing pins.
mise.lock
+8 -8
@@ -89,23 +89,23 @@ version = "3.12.13"
89 backend = "core:python"
90
91 [tools.python."platforms.linux-arm64"]
92 -checksum = "sha256:b85154b9c7ca9de3f85f2c9f032d503151db16ef198de86b885fc61890c075ed"
93 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz"
92 +checksum = "sha256:f226576b91491ffa5739aa85726521e9031f4d87f80627d64ed348ac77cb31e9"
93 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz"
94 provenance = "github-attestations"
95
96 [tools.python."platforms.linux-x64"]
97 -checksum = "sha256:10a452caac7041357805f0c19a60576df53f1ab06d1abfc9200f1f0157cb3bd1"
98 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"
97 +checksum = "sha256:5854aa6ec71cad00334d5065633c210b2e7feb40956767a59a91791cadcf0b79"
98 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"
99 provenance = "github-attestations"
100
101 [tools.python."platforms.macos-arm64"]
102 -checksum = "sha256:41df7d3ae4757e84b97874f76d634268456aaa271740d33f968d826374998fb7"
103 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-aarch64-apple-darwin-install_only_stripped.tar.gz"
102 +checksum = "sha256:9a1e9e06175c10efd8378b904b07fa21bd791ab3345d7cdffeb4a76c9ff55903"
103 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-aarch64-apple-darwin-install_only_stripped.tar.gz"
104 provenance = "github-attestations"
105
106 [tools.python."platforms.macos-x64"]
107 -checksum = "sha256:a6bbea996c5f14eb55ab275889d2df45408deec504b4a7219d7b59c045b2555e"
108 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260623/cpython-3.12.13+20260623-x86_64-apple-darwin-install_only_stripped.tar.gz"
107 +checksum = "sha256:8e6b7e6533bdf746287008edf91102e7bee0a6ca1d24f16c4514237cafd706c5"
108 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-x86_64-apple-darwin-install_only_stripped.tar.gz"
109 provenance = "github-attestations"
110
111 [[tools.uv]]
package.json
+2
@@ -51,6 +51,7 @@
51 "check:peer-deps": "tsx ts/scripts/check-peer-deps.ts",
52 "update:peer-deps": "tsx ts/scripts/update-peer-deps.ts",
53 "validate:agent-skills": "node ts/scripts/validate-agent-skills.mjs",
54 + "validate:changesets": "node ts/scripts/validate-changesets.mjs",
55 "validate:skill-routing": "node ts/scripts/test-skill-routing.mjs",
56 "prepublish": "pnpm run build:packages",
57 "changeset": "changeset",
@@ -71,6 +72,7 @@
72 "devDependencies": {
73 "@arethetypeswrong/cli": "catalog:",
74 "@changesets/cli": "^2.31.0",
75 + "@changesets/read": "^0.6.7",
76 "@composio/anthropic": "workspace:*",
77 "@composio/cli-local-tools": "workspace:*",
78 "@composio/core": "workspace:*",
pnpm-lock.yaml
+3
@@ -126,6 +126,9 @@ importers:
126 '@changesets/cli':
127 specifier: ^2.31.0
128 version: 2.31.0(@types/node@26.1.0)
129 + '@changesets/read':
130 + specifier: ^0.6.7
131 + version: 0.6.7
132 '@composio/anthropic':
133 specifier: workspace:*
134 version: link:ts/packages/providers/anthropic
test/release-workflow.test.ts
+74
@@ -12,6 +12,10 @@ import {
12 import { tmpdir } from 'node:os';
13 import { join } from 'node:path';
14 import { spawnSync } from 'node:child_process';
15 +import {
16 + findIgnoredChangesetReleases,
17 + validateChangesets,
18 +} from '../ts/scripts/validate-changesets.mjs';
19
20 const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
21 const tsCorePackageJson = JSON.parse(
@@ -246,6 +250,76 @@ if (packageJson.scripts?.['changeset:release'] !== 'bash ts/scripts/changeset-re
250 throw new Error('changeset:release must use the CLI-release filtering script');
251 }
252
253 +if (packageJson.scripts?.['validate:changesets'] !== 'node ts/scripts/validate-changesets.mjs') {
254 + throw new Error('validate:changesets must use the ignored-package guard');
255 +}
256 +
257 +{
258 + const violations = findIgnoredChangesetReleases(
259 + {
260 + changesets: [
261 + {
262 + id: 'ignored-package-fixture',
263 + releases: [
264 + { name: '@composio/cli', type: 'patch' },
265 + { name: '@composio/core', type: 'patch' },
266 + ],
267 + },
268 + ],
269 + },
270 + ['@composio/cli']
271 + );
272 +
273 + if (
274 + violations.length !== 1 ||
275 + violations[0].changeset !== 'ignored-package-fixture' ||
276 + violations[0].package !== '@composio/cli'
277 + ) {
278 + throw new Error('changeset validation must identify releases targeting ignored packages');
279 + }
280 +}
281 +
282 +{
283 + const fixtureDir = mkdtempSync(join(tmpdir(), 'composio-changeset-validation-'));
284 + const changesetDir = join(fixtureDir, '.changeset');
285 + const fixturePath = join(changesetDir, 'ignored-package-fixture.md');
286 +
287 + try {
288 + mkdirSync(changesetDir, { recursive: true });
289 + writeFileSync(join(changesetDir, 'config.json'), JSON.stringify({ ignore: ['@composio/cli'] }));
290 + writeFileSync(
291 + fixturePath,
292 + '---\n"@composio/cli": patch\n"@composio/core": patch\n---\n\nFixture changeset.\n'
293 + );
294 +
295 + let validationError = '';
296 + try {
297 + await validateChangesets(fixtureDir);
298 + } catch (error) {
299 + validationError = error instanceof Error ? error.message : String(error);
300 + }
301 +
302 + if (!validationError.includes('ignored-package-fixture: @composio/cli')) {
303 + throw new Error('changeset validation must reject an ignored package outside a git checkout');
304 + }
305 +
306 + writeFileSync(fixturePath, '---\n"@composio/core": patch\n---\n\nValid fixture changeset.\n');
307 + await validateChangesets(fixtureDir);
308 + } finally {
309 + rmSync(fixtureDir, { recursive: true, force: true });
310 + }
311 +}
312 +
313 +const validateChangesetsIdx = tsReleaseWorkflow.indexOf('run: pnpm validate:changesets');
314 +const changesetsActionIdx = tsReleaseWorkflow.indexOf('uses: changesets/action@');
315 +if (
316 + validateChangesetsIdx === -1 ||
317 + changesetsActionIdx === -1 ||
318 + validateChangesetsIdx > changesetsActionIdx
319 +) {
320 + throw new Error('ts.release.yml must validate pending changesets before changesets/action');
321 +}
322 +
323 if (changesetConfig.baseBranch !== 'next') {
324 throw new Error('changesets must compare against next, the active release branch');
325 }
ts/AGENTS.md
+2
@@ -12,6 +12,7 @@ TypeScript workspace guidance for AI agents.
12 - Use `typescript-providers` for packages under `ts/packages/providers/`.
13 - Use `typescript-testing` for Vitest, typecheck, package builds, examples, or runtime E2E test selection.
14 - Use `cli-command` or `cli-e2e` for `ts/packages/cli/` and `ts/e2e-tests/cli/`.
15 +- Use `cli-release` for first-party CLI beta builds, stable promotion, release verification, or recovery.
16
17 ## Commands
18
@@ -33,4 +34,5 @@ pnpm test:e2e:cli
34 - Do not edit `ts/vendor/`; those submodules are read-only references.
35 - Keep generated outputs owned by their generator.
36 - Add changesets only for changes to published TypeScript packages.
37 +- Never add changesets for `@composio/cli` or `@composio/cli-local-tools` while `.changeset/config.json` ignores them; record CLI notes in `ts/packages/cli/CHANGELOG.md` instead.
38 - Prefer focused package tests before broad workspace tests.
ts/packages/cli/AGENTS.md
+34 -49
@@ -27,34 +27,34 @@ Errors are captured via the custom `effect-errors/` module (source-mapped stack
27
28 Each command uses `@effect/cli`'s `Command.make()` pattern. Top-level command files end in `.cmd.ts`; nested command groups live in their own subdirectory with a `<group>.cmd.ts` entry. Current top-level commands:
29
30 -| Group / Command | Purpose |
30 +| Group / Command | Purpose |
31 | -------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
32 -| `version` | Display CLI version |
33 -| `whoami` | Show logged-in user info (writes raw API key to stdout when piped — see Output Conventions) |
34 -| `login` | Login with browser redirect or direct user/API key (`--no-browser`, `--no-wait`, `--key`, `--user-api-key`, `--org`) |
35 -| `logout` | Clear stored API key |
36 -| `signup` | Create a Composio account |
37 -| `upgrade` | Self-update binary from GitHub releases |
38 -| `init` | Bootstrap a Composio project in the current directory |
39 -| `install` | Install local-tool integrations |
40 -| `generate {ts | py}` | Generate type stubs (auto-detects project language if no subcommand) |
41 -| `agent` | Manage AI agent presets |
42 -| `toolkits` | List / inspect / version toolkits |
43 -| `tools` | List / inspect / `execute` tools |
44 -| `triggers` | List / manage trigger types |
45 -| `auth-configs` | Manage auth-config resources (`ac_*`) |
46 -| `connected-accounts` | Manage connected accounts (`ca_*`) |
47 -| `connections` | Alias / helper for connected-account flows |
48 -| `orgs` | Manage organizations |
49 -| `projects` | Manage projects |
50 -| `local-tools` | Manage local toolkits (via `@composio/cli-local-tools`) |
51 -| `logs` | View tool-execution logs (`logs-cmd/`) |
52 -| `config` | Read/write CLI config |
53 -| `listen` | Listen for events |
54 -| `proxy` | Proxy authenticated API requests |
55 -| `run` | Run a saved script / preset |
56 -| `dev` | Developer-only utilities |
57 -| `artifacts` | Manage generated artifacts |
32 +| `version` | Display CLI version |
33 +| `whoami` | Show logged-in user info (writes raw API key to stdout when piped — see Output Conventions) |
34 +| `login` | Login with browser redirect or direct user/API key (`--no-browser`, `--no-wait`, `--key`, `--user-api-key`, `--org`) |
35 +| `logout` | Clear stored API key |
36 +| `signup` | Create a Composio account |
37 +| `upgrade` | Self-update binary from GitHub releases |
38 +| `init` | Bootstrap a Composio project in the current directory |
39 +| `install` | Install local-tool integrations |
40 +| `generate {ts | py}` | Generate type stubs (auto-detects project language if no subcommand) |
41 +| `agent` | Manage AI agent presets |
42 +| `toolkits` | List / inspect / version toolkits |
43 +| `tools` | List / inspect / `execute` tools |
44 +| `triggers` | List / manage trigger types |
45 +| `auth-configs` | Manage auth-config resources (`ac_*`) |
46 +| `connected-accounts` | Manage connected accounts (`ca_*`) |
47 +| `connections` | Alias / helper for connected-account flows |
48 +| `orgs` | Manage organizations |
49 +| `projects` | Manage projects |
50 +| `local-tools` | Manage local toolkits (via `@composio/cli-local-tools`) |
51 +| `logs` | View tool-execution logs (`logs-cmd/`) |
52 +| `config` | Read/write CLI config |
53 +| `listen` | Listen for events |
54 +| `proxy` | Proxy authenticated API requests |
55 +| `run` | Run a saved script / preset |
56 +| `dev` | Developer-only utilities |
57 +| `artifacts` | Manage generated artifacts |
58
59 Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation. Feature flags live in `feature-tags.ts` and `experimental-features.ts`.
60
@@ -170,32 +170,17 @@ Outputs land in `recordings/{tapes,svgs,ascii}/<group>/<name>.{tape,svg,ascii}`.
170
171 ## Release Workflow
172
173 -Two channels: **beta** (automatic) and **stable** (manual promotion via changeset).
173 +Use the repo-local `cli-release` skill before building or publishing first-party CLI binaries.
174
175 -### Beta (automatic)
176 -
177 -Every push to `next` touching `ts/packages/cli/**` triggers `.github/workflows/build-cli-binaries.yml`:
178 -
179 -1. Find latest stable `@composio/cli@X.Y.Z`
180 -2. Compute next patch `X.Y.Z+1`
181 -3. Build cross-platform binaries (linux-x64, linux-aarch64, darwin-x64, darwin-aarch64)
182 -4. Publish GitHub prerelease `@composio/cli@X.Y.(Z+1)-beta.<run_number>`
183 -
184 -Also triggerable from any branch via `workflow_dispatch` → `build-beta`. Users install with `composio upgrade --beta`.
185 -
186 -### Stable (via changeset)
187 -
188 -1. Create a CLI release changeset PR only when intentionally promoting CLI binary behavior through the stable release flow (`.changeset/<name>.md` with `"@composio/cli": patch`). Ordinary CLI source fixes still follow the repo rule: add a changeset only when the release path requires one.
189 -2. Merge into `next`
190 -3. Changeset bot opens "Release: update version" PR bumping `package.json`
191 -4. Merge that PR → push to `next` detects version change → builds **stable** release (`@composio/cli@X.Y.Z`, marked `latest`)
192 -5. `ts.release.yml` publishes via the repository-controlled `changeset:release` script, which filters `@composio/cli` tag output so only `build-cli-binaries.yml` can create CLI GitHub Releases
193 -
194 -Promote an existing beta to stable via `workflow_dispatch` → `promote-stable` with the beta tag (e.g. `@composio/cli@0.2.20-beta.42`).
175 +- A push to `next` touching CLI paths publishes a rolling beta automatically.
176 +- The normal stable path promotes an existing tested beta through the `promote-stable` workflow action.
177 +- `@composio/cli` and `@composio/cli-local-tools` are ignored by Changesets. Never add a changeset targeting either package; it wedges the TypeScript SDK release action. Put human-facing CLI notes in `CHANGELOG.md` directly.
178 +- A direct `package.json` version bump is supported by the resolver only as an explicit release-owner recovery path, not the contributor default.
179
180 ### Key Workflow Files
181
182 - `.github/workflows/build-cli-binaries.yml` — binary build + release
199 -- `.github/workflows/ts.release.yml` — changeset bot + npm publish
183 - `.github/workflows/cli.test-installation.yml` — post-release install smoke tests
184 +- `.github/workflows/cli.bump-homebrew-tap.yml` — stable Homebrew formula update
185 +- `.github/scripts/cli-release/resolve-release-target.sh` — beta/stable target resolution
186 - `.changeset/config.json`
ts/packages/cli/CHANGELOG.md
+1
@@ -15,6 +15,7 @@
15
16 ### Patch Changes
17
18 +- 8467efd: Fix `composio whoami` reporting the API key's home organization after `composio orgs switch`. Session info requests now forward the selected global organization.
19 - 5f004ff: Drop `COMPOSIO_UPSERT_RECIPE` and `COMPOSIO_GET_RECIPE` from the CLI meta-tool list. These slugs were removed from `@composio/client` (alpha.74), so listing them broke the type-checked CLI build.
20 - 23f9053: Remove the unused `ansis` dependency from the CLI. Colored output is already handled by `picocolors`, so `ansis` was a dead production dependency that shipped with the package.
21 - 446c6f6: Fix virtual TypeScript file resolution used by CLI type generation so in-memory imports resolve consistently during transpilation and validation.
ts/scripts/test-skill-routing.mjs
+10
@@ -47,6 +47,16 @@ const probes = [
47 expect: 'cli-e2e',
48 terms: ['Docker-based', 'end-to-end tests', 'binary invocation', 'fixture isolation'],
49 },
50 + {
51 + task: 'promote a tested Composio CLI beta to a stable first-party binary release',
52 + expect: 'cli-release',
53 + terms: [
54 + 'first-party Composio CLI binaries',
55 + 'promote-stable',
56 + 'beta-tag selection',
57 + 'failed release recovery',
58 + ],
59 + },
60 {
61 task: 'align TypeScript and Python behavior after a backend API contract change',
62 expect: 'cross-sdk-parity',
ts/scripts/validate-agent-skills.mjs
+2
@@ -14,6 +14,7 @@ const expectedSkills = [
14 'bug-fixing',
15 'cli-command',
16 'cli-e2e',
17 + 'cli-release',
18 'cross-sdk-parity',
19 'docs-decisions',
20 'eve',
@@ -224,6 +225,7 @@ for (const relativePath of ['docs/decisions/README.md', 'docs/agent-guidance/REA
225
226 const ignoredDirs = new Set([
227 '.git',
228 + '.generated',
229 'node_modules',
230 '.turbo',
231 '.ruff_cache',
ts/scripts/validate-changesets.mjs new
+53
@@ -0,0 +1,53 @@
1 +#!/usr/bin/env node
2 +
3 +import { readFileSync } from 'node:fs';
4 +import { dirname, resolve } from 'node:path';
5 +import { fileURLToPath } from 'node:url';
6 +import readChangesets from '@changesets/read';
7 +
8 +const scriptPath = fileURLToPath(import.meta.url);
9 +const repositoryRoot = resolve(dirname(scriptPath), '../..');
10 +
11 +export function findIgnoredChangesetReleases(changesetStatus, ignoredPackages) {
12 + const ignored = new Set(ignoredPackages);
13 +
14 + return (changesetStatus.changesets ?? []).flatMap(changeset =>
15 + (changeset.releases ?? [])
16 + .filter(release => ignored.has(release.name))
17 + .map(release => ({ changeset: changeset.id, package: release.name }))
18 + );
19 +}
20 +
21 +export async function validateChangesets(cwd = repositoryRoot) {
22 + const config = JSON.parse(readFileSync(resolve(cwd, '.changeset/config.json'), 'utf8'));
23 + const changesets = await readChangesets(cwd);
24 + const violations = findIgnoredChangesetReleases({ changesets }, config.ignore ?? []);
25 +
26 + if (violations.length > 0) {
27 + const details = violations
28 + .map(({ changeset, package: packageName }) => `- ${changeset}: ${packageName}`)
29 + .join('\n');
30 +
31 + throw new Error(
32 + [
33 + 'Pending changesets must not target packages listed in .changeset/config.json#ignore.',
34 + details,
35 + '',
36 + 'An ignored-package changeset makes changesets/action enter version-PR mode, but',
37 + '`changeset version` emits no commit. The release job then fails while trying to',
38 + 'open a pull request with no commits. Remove the changeset, or remove the package',
39 + 'from the ignore list when intentionally restoring its Changesets release flow.',
40 + ].join('\n')
41 + );
42 + }
43 +}
44 +
45 +if (resolve(process.argv[1] ?? '') === scriptPath) {
46 + try {
47 + await validateChangesets();
48 + console.log('changeset validation passed');
49 + } catch (error) {
50 + console.error(error instanceof Error ? error.message : error);
51 + process.exitCode = 1;
52 + }
53 +}