skills/composiohq__composio
1
0
Fork 0
mirror of https://github.com/ComposioHQ/composio.git synced 2026-09-22 11:46:35 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
@composio/openai@0.9.3
composiohq__composio/CLAUDE.md
T
Alberto Schiabel 4fe776898a chore(toolchain): finish mise migration (#3493) 
## Summary

Depends on #3492.

This completes the Phase 2 migration by removing the transitional
version-file layer and making `mise.toml` plus `mise.lock` the
repository toolchain source of truth. It also moves runtime test
matrices into `toolchain-versions.json`, so CI matrix changes are
explicit and reviewable without reintroducing `.nvmrc`, `.dvmrc`,
`.bun-version`, or `.python-version`.

The Node.js e2e matrix now starts at the latest Node 22 LTS line and
also covers the latest Node 24 and Node 25 lines. That removes Node 20
from the well-known e2e versions while keeping us covered on the
runtimes SDK users are moving toward.

## Rationale

Phase 1 introduced mise side by side with the existing version files to
keep the first PR low-risk. Phase 2 removes that compatibility layer so
there is one place to update tool versions. That avoids silent drift
between local setup, GitHub Actions, Docker E2E images, release docs,
and install-time checks.

The composite setup actions now install Node, Bun, Python, and uv
through mise by default, with explicit version overrides only where a
matrix needs them. New GitHub actions added in this PR are pinned by
release commit SHA and include the release version comment.

## What changed

- Deleted the transitional root/version files: `.nvmrc`, `.bun-version`,
`.dvmrc`, root `.python-version`, and `python/.python-version`.
- Removed `idiomatic_version_file_enable_tools` from `mise.toml` and
added a committed `mise.lock` for linux/macOS x64/arm64 tool resolution.
- Replaced `BYPASS_BUN_VERSION_CHECK` with `BYPASS_TOOLCHAIN_CHECK`, and
made Docker E2E image installs use that bypass because they receive
explicit build args instead of installing mise.
- Updated Node/Bun and Python/uv composite actions to default to mise,
remove `*-version-file` inputs, report resolved versions, and cache pnpm
after `corepack enable`.
- Centralized CI runtime matrices in `toolchain-versions.json` for TS
E2E, Python tests, and CLI npm fallback coverage.
- Updated the Node E2E matrix to `22.22.3`, `24.16.0`, and `25.9.0`,
removing Node 20 from the well-known runtime versions.
- Updated workflows, docs, E2E helpers, Dockerfiles, and release
guidance to reference `mise.toml` / `mise.lock`.

## Verification

- Verified latest Node 22/24/25 releases from the official Node dist
index: `22.22.3`, `24.16.0`, `25.9.0`
(https://nodejs.org/dist/index.json).
- `pnpm install --frozen-lockfile`
- `pnpm --filter @e2e-tests/utils typecheck`
- `pnpm --filter @e2e-tests/utils exec tsc --noEmit --target es2022
--module esnext --moduleResolution bundler --types bun
--resolveJsonModule --skipLibCheck --strict scripts/docker-build.ts`
- `bash -n ts/scripts/pre-install.sh && bun run
ts/scripts/pre-install/check-toolchain.ts && BYPASS_TOOLCHAIN_CHECK=1
bash ts/scripts/pre-install.sh`
- `pnpm exec prettier --check ...` on touched YAML/Markdown/TS/JSON
files
- `ruby -e "require \"yaml\"; ARGV.each { |f| YAML.load_file(f) }" ...`
on touched actions/workflows
- `mise lock --platform linux-x64,linux-arm64,macos-arm64,macos-x64 &&
git diff --exit-code mise.lock`
- `mise exec node@22.22.3 -- pnpm --filter @e2e-tests/utils typecheck`
- `mise exec node@22.22.3 -- pnpm --filter @e2e-tests/node-esm-basic
typecheck`
- `mise exec node@22.22.3 -- pnpm --filter @e2e-tests/node-cjs-basic
typecheck`
- `docker manifest inspect node:24.16.0-slim`
- `docker manifest inspect node:25.9.0-slim`
- `git diff --check`
2026-06-15 14:03:21 +04:00

5.1 KiB
Raw Permalink Blame History

CLAUDE.md

Guidance for Claude Code when working in this repository. For Codex / generic-agent guidance see AGENTS.md.

Overview

Composio SDK v3 — monorepo containing the TypeScript SDK (primary, under ts/) and the Python SDK (under python/). Built with pnpm workspaces + Turbo for TS, uv + nox for Python. Default branch: next.

Repository Layout

composio/
├── ts/
│   ├── packages/
│   │   ├── core/              # @composio/core — main SDK
│   │   ├── providers/         # @composio/openai, anthropic, google, langchain, vercel, mastra, ...
│   │   ├── cli/               # @composio/cli — Effect.ts + Bun (see ts/packages/cli/AGENTS.md)
│   │   ├── cli-keyring/       # @composio/cli-keyring — macOS Keychain / Linux Secret Service
│   │   ├── cli-local-tools/   # @composio/cli-local-tools — local toolkit declarations
│   │   ├── json-schema-to-zod/
│   │   └── ts-builders/       # AST builders for code generation
│   ├── vendor/                # Read-only Effect + Clack submodules (do NOT modify)
│   ├── e2e-tests/             # Docker-based Node/Deno/Cloudflare runtime tests
│   └── examples/
├── python/                    # Python SDK (composio, providers, examples)
└── docs/                      # Fumadocs site (see docs/CLAUDE.md)

TypeScript Commands

mise install                # Installs Node, Bun, Deno, Python, uv from mise.toml (one-time per machine)
corepack enable             # Activates pnpm pinned in package.json#packageManager
pnpm install                # First-time setup
pnpm build                  # Build all packages (Turbo)
pnpm build:packages         # TS packages only
pnpm lint / lint:fix
pnpm format
pnpm typecheck              # MANDATORY before pushing CLI changes
pnpm test                   # Vitest, all packages
pnpm test:e2e               # All runtimes (Node CJS+ESM, Deno, Cloudflare Workers) via Docker
pnpm test:e2e:node          # Override with COMPOSIO_E2E_NODE_VERSION=22.12.0
pnpm test:e2e:deno          # Override with COMPOSIO_E2E_DENO_VERSION=2.6.7
pnpm test:e2e:cloudflare
pnpm changeset              # Create release changeset (required for stable CLI/SDK releases)
pnpm create:provider <name> [--agentic]
pnpm create:example <name>

Toolchain versions are pinned in mise.toml (Node, Bun, Deno, Python, uv) and package.json#packageManager (pnpm via corepack). Install mise once with brew install mise (macOS), winget install jdx.mise (Windows), or curl https://mise.run | sh (any), then activate it in your shell — see https://mise.jdx.dev/installing-mise.html. CI can set BYPASS_TOOLCHAIN_CHECK=1 only when using prebuilt toolchain images.

Python Commands

cd python
make env                    # uv-managed venv with all deps (NOT pre-built in sandboxes)
source .venv/bin/activate   # ALWAYS activate before pytest/ruff/pip
make fmt                    # ruff format
make chk                    # ruff check + mypy
make tst / make snt         # pytest / sanity tests
pytest -m core              # Markers: core, openai, langchain, agno
make build / make bump

Python: >=3.10, <4. Formatter/linter: Ruff (88 char). Type checker: mypy strict. Core deps include composio-client (Stainless-generated; source repo is ComposioHQ/composio-base-py).

Environment Variables

COMPOSIO_API_KEY            # Required
COMPOSIO_BASE_URL           # Optional override
COMPOSIO_LOG_LEVEL          # silent | error | warn | info | debug
COMPOSIO_DISABLE_TELEMETRY  # "true" to disable

Gotchas

  • Default branch is next, not main/master. Branch from next and target next for PRs.
  • Docs PRs also target next (see docs/CLAUDE.md rule).
  • pnpm install checks Bun against mise.toml; run mise install when it fails.
  • ts/vendor/effect/ and ts/vendor/clack/ are read-only reference submodules — npm provides the actual deps.
  • The CLI is Effect.ts + Bun, not plain Node — see ts/packages/cli/AGENTS.md (CLI's CLAUDE.md is a symlink to it).
  • E2E tests run in Docker and require Docker daemon access; skip them in restricted sandboxes.
  • Tool execution code generation is auto-derived from OpenAPI specs in hermes — don't hand-edit generated files under @composio/core/generated.

Key Files

  • Main SDK entry: ts/packages/core/src/index.ts
  • Core Composio class: ts/packages/core/src/composio.ts
  • Types: ts/packages/core/src/types/, errors: ts/packages/core/src/errors/
  • Build configs: turbo.jsonc, tsconfig.base.json, tsdown.config.base.ts
  • Toolchain pins: mise.toml (Node, Bun, Deno, Python, uv), mise.lock, toolchain-versions.json (test matrices), package.json#packageManager (pnpm)
  • CI release docs to update when bumping toolchain: ts/docs/internal/release.md
  • Python config: python/Makefile, python/noxfile.py, python/config/{pytest.ini,ruff.toml}

See Also

  • AGENTS.md — Codex/generic-agent variant of this file
  • docs/CLAUDE.md — Fumadocs site, link-checker, API-reference versioning
  • ts/packages/cli/AGENTS.md — CLI architecture, services, commands, release flow
Reference in New Issue View Git Blame Copy Permalink