mirror of https://github.com/ComposioHQ/composio.git synced 2026-09-22 11:46:35 +08:00

Files

T

Alberto Schiabel 07160d14fa feat(toolchain): introduce mise.toml as single source of truth (#3492 )

## Summary

This PR starts Phase 1 of PLEN-1368 by adding `mise.toml` as the
repo-owned source for the primary toolchain versions:

- Node `20.20.2`
- Bun `1.3.10`
- Deno `2.6.7`
- Python `3.12`
- uv `0.8.19`

It also keeps pnpm corepack-driven through
`package.json#packageManager`, adds `devEngines` for Node/pnpm
visibility, documents the new `mise install && corepack enable && pnpm
install` bootstrap path, ignores `.mise.local.toml`, and fixes stale
release-doc prerequisites.

## Why

The repo already has real toolchain drift, not just duplicated version
strings. The internal release docs had stale Node/Bun/pnpm versions,
Deno is repeated across workflows, Dockerfiles, docs, and e2e helpers,
and Python local setup still has a separate `3.11` venv path while the
repo pins `3.12`.

A composite-action cleanup would improve CI, but it would not solve
local development. `mise.toml` gives us one file that declares the
versions and lets contributors install or switch them with one command.
That is the main value proposition here: make the repo declare its own
toolchain, then let CI consume the same declaration in the next phase.

## Rollout

This is deliberately additive. It does not remove `.nvmrc`,
`.bun-version`, `.python-version`, or `.dvmrc`, and it does not change
CI behavior yet. Contributors who do not use mise can keep working as
before; contributors who do use mise get managed Node/Bun/Deno/Python/uv
immediately.

Phase 2 can migrate the existing composite actions to
`jdx/mise-action@v4`. Phase 3 can remove the legacy version files and
add the lockfile once the transition is complete.

## Out of Scope

- Migrating CI to `jdx/mise-action@v4`
- Removing legacy version files
- Adding `mise.lock`
- Updating nested TS package/example `packageManager` fields that still
say `pnpm@10.28.0`; that is pre-existing metadata drift and should be
handled separately to avoid broadening Phase 1

## Verification

- `git diff --check origin/next...HEAD`
- `mise install && mise current`
- `pnpm --version` -> `10.28.2`
- `pnpm dlx prettier@3.8.1 --check package.json`

Refs: PLEN-1368

2026-06-04 23:50:59 -07:00

5.3 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. Use BYPASS_BUN_VERSION_CHECK=1 if .bun-version mismatch
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. Legacy .nvmrc / .bun-version / .python-version are still read during the transition. CI sets BYPASS_BUN_VERSION_CHECK=1; local sandboxes often need it too.

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 hard-fails on Bun version mismatch — use BYPASS_BUN_VERSION_CHECK=1.
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), package.json#packageManager (pnpm), .dvmrc (Deno; mirrors mise.toml for denoland/setup-deno and _utils/src/config.ts)
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}

5.3 KiB Raw Permalink Blame History