@devries-cameron20 / composio-1 / commits / 4b5f3ac17
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.

Add .agent_cache and cursor rules for bugfix, testing and api updates (#2434)

Musthaq Ahamad committed Jan 22, 2026 at 17:14 UTC 4b5f3ac1700803236da98d3b9b8ee71245e39eb8
3 files changed +275
.cursor/commands/api-update.md new
+138
@@ -0,0 +1,138 @@
1 +# API Update Command
2 +
3 +Check for open PRs in the Composio client repositories and create a plan for updating the SDKs.
4 +
5 +## Workflow
6 +
7 +### Step 1: Check for Open PRs
8 +
9 +Fetch open PRs from both client repositories:
10 +
11 +1. **TypeScript Client**: `github.com/composiohq/composio-base-ts`
12 +2. **Python Client**: `github.com/composiohq/composio-base-py`
13 +
14 +Use the GitHub CLI (`gh`) to list open PRs:
15 +```bash
16 +gh pr list --repo composiohq/composio-base-ts --state open --json number,title,url,headRefName,body
17 +gh pr list --repo composiohq/composio-base-py --state open --json number,title,url,headRefName,body
18 +```
19 +
20 +### Step 2: Get PR Patches
21 +
22 +For each open PR, fetch the diff/patch to understand the changes:
23 +```bash
24 +gh pr diff <PR_NUMBER> --repo composiohq/composio-base-ts
25 +gh pr diff <PR_NUMBER> --repo composiohq/composio-base-py
26 +```
27 +
28 +### Step 3: Analyze Changes
29 +
30 +For each PR, analyze the diff to identify:
31 +
32 +1. **New API endpoints** - New methods/functions added to the client
33 +2. **Modified parameters** - Changes to existing function signatures
34 +3. **Deprecated endpoints** - Removed or deprecated functionality
35 +4. **Type changes** - Updates to type definitions/schemas
36 +5. **Breaking changes** - Any backward-incompatible changes
37 +
38 +### Step 4: Identify SDK Impact
39 +
40 +Map client changes to SDK files that need updates:
41 +
42 +**TypeScript SDK (`@composio/core`)**:
43 +- Check `ts/packages/core/src/` for affected code
44 +- Types: `ts/packages/core/src/types/`
45 +- Models: `ts/packages/core/src/models/`
46 +- Services: `ts/packages/core/src/services/`
47 +
48 +> **Important - Naming Convention for TypeScript:**
49 +> The API uses **kebab-case** (e.g., `connected-accounts`, `auth-configs`, `tool-router`) but the TypeScript SDK uses **camelCase** (e.g., `connectedAccounts`, `authConfigs`, `toolRouter`).
50 +>
51 +> When mapping API changes to TypeScript SDK:
52 +> - Convert all kebab-case parameter names to camelCase
53 +> - Convert all kebab-case property names to camelCase
54 +> - Keep the original kebab-case names in comments for reference to the API
55 +> - Example: API's `callback_url` or `callback-url` becomes `callbackUrl` in TypeScript
56 +
57 +**Python SDK (`composio`)**:
58 +- Check `python/composio/` for affected code
59 +- Types and models in `python/composio/core/`
60 +- Python typically uses snake_case which often matches API naming
61 +
62 +### Step 5: Check Current Client Versions
63 +
64 +Current client dependency versions:
65 +- **TypeScript**: Check `pnpm-workspace.yaml` catalog for `@composio/client` version
66 +- **Python**: Check `python/pyproject.toml` for `composio-client` version
67 +
68 +### Step 6: Create Update Plan
69 +
70 +Create a plan document in `.agent_cache/` folder with the following structure:
71 +
72 +```
73 +.agent_cache/
74 +└── api-update-plan-<YYYY-MM-DD>.md
75 +```
76 +
77 +## Plan Document Structure
78 +
79 +The plan document should contain:
80 +
81 +### 1. PR Summary
82 +- List all open PRs with their numbers, titles, and URLs
83 +- Brief description of what each PR changes
84 +
85 +### 2. Client Version Updates
86 +- Current versions of both clients
87 +- Target versions (from PR branch or proposed release)
88 +- Files to update:
89 + - `pnpm-workspace.yaml` (catalog section for `@composio/client`)
90 + - `python/pyproject.toml` (dependencies section for `composio-client`)
91 +
92 +### 3. TypeScript SDK Changes
93 +For each change needed:
94 +- File path
95 +- Change description
96 +- Code snippet showing before/after (if applicable)
97 +- Whether it's a breaking change
98 +- **Naming mapping**: Show the API name (kebab-case/snake_case) → TypeScript name (camelCase)
99 + - Example: `callback_url` → `callbackUrl`
100 + - Example: `connected-account-id` → `connectedAccountId`
101 +
102 +### 4. Python SDK Changes
103 +For each change needed:
104 +- File path
105 +- Change description
106 +- Code snippet showing before/after (if applicable)
107 +- Whether it's a breaking change
108 +
109 +### 5. Breaking Changes Summary
110 +- List all breaking changes
111 +- Migration steps required
112 +- Affected public APIs
113 +
114 +### 6. Test Updates Required
115 +- New tests to add
116 +- Existing tests to update
117 +
118 +### 7. Documentation Updates
119 +- API documentation changes needed
120 +- Changelog entries to create
121 +
122 +## Important Notes
123 +
124 +- **DO NOT** apply any changes to the codebase
125 +- Only create the plan document in `.agent_cache/`
126 +- Wait for user confirmation before proceeding with any changes
127 +- If no open PRs are found, report that and exit
128 +- If PRs exist but have no SDK-impacting changes, note that in the plan
129 +
130 +## Example Output Path
131 +
132 +`.agent_cache/api-update-plan-2026-01-22.md`
133 +
134 +## Error Handling
135 +
136 +- If `gh` CLI is not authenticated, prompt user to run `gh auth login`
137 +- If repositories are not accessible, report the error
138 +- If PR diff is too large, summarize key changes only
.cursor/rules/bug-fix-testing.mdc new
+133
@@ -0,0 +1,133 @@
1 +---
2 +description: Apply when fixing bugs, addressing issues, or resolving defects in the codebase
3 +globs:
4 +alwaysApply: false
5 +---
6 +
7 +# Bug Fix Testing Requirements
8 +
9 +When fixing bugs or addressing issues in the codebase, always ensure proper test coverage:
10 +
11 +## Required Actions
12 +
13 +1. **Identify existing tests** - Check if there are existing tests for the affected code
14 + - TypeScript: Look in `ts/packages/<package>/test/` directories
15 + - Python: Look in `python/tests/` directory
16 +
17 +2. **Add regression tests** - Create tests that:
18 + - Reproduce the original bug (the test should fail before the fix)
19 + - Verify the fix works correctly (the test should pass after the fix)
20 + - Cover edge cases related to the bug
21 +
22 +3. **Update existing tests** - If the fix changes expected behavior:
23 + - Update affected test assertions
24 + - Add new test cases for the changed behavior
25 + - Ensure no unrelated tests are broken
26 +
27 +## Test Location Guidelines
28 +
29 +**Important:** Add regression tests to existing test files that cover the affected feature/module. Do NOT create new test files specifically for regressions.
30 +
31 +### TypeScript
32 +
33 +**Test Structure:**
34 +- Tests location: `ts/packages/<package-name>/test/<feature>/<feature>.test.ts`
35 +- Mocks location: `ts/packages/<package-name>/test/utils/mocks/`
36 +- E2E tests: `ts/e2e-tests/`
37 +
38 +**Framework:** Vitest
39 +
40 +**Test Pattern:**
41 +```typescript
42 +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
43 +
44 +describe('FeatureName', () => {
45 + beforeEach(() => {
46 + // Setup
47 + });
48 +
49 + afterEach(() => {
50 + // Cleanup
51 + });
52 +
53 + describe('methodName', () => {
54 + it('should <expected_behavior> when <condition>', async () => {
55 + // Arrange
56 + // Act
57 + // Assert
58 + expect(result).toEqual(expected);
59 + });
60 + });
61 +});
62 +```
63 +
64 +**Mocking:**
65 +- Use `vi.mock()` for module mocking
66 +- Use `vi.spyOn()` for spying on methods
67 +- Use `vi.fn()` for creating mock functions
68 +- Store reusable mocks in `test/utils/mocks/`
69 +
70 +### Python
71 +
72 +**Test Structure:**
73 +- Tests location: `python/tests/test_<feature>.py`
74 +- Shared fixtures: `python/tests/conftest.py`
75 +
76 +**Framework:** pytest with markers (`core`, `openai`, `langchain`, `vercel`)
77 +
78 +**Test Pattern:**
79 +```python
80 +import pytest
81 +from unittest.mock import MagicMock, patch
82 +
83 +@pytest.fixture
84 +def mock_client():
85 + """Create a mock client."""
86 + client = MagicMock()
87 + return client
88 +
89 +class TestFeatureName:
90 + """Test cases for FeatureName."""
91 +
92 + def test_method_expected_behavior_when_condition(self, mock_client):
93 + """Test that method behaves correctly when condition."""
94 + # Arrange
95 + # Act
96 + # Assert
97 + assert result == expected
98 +
99 + def test_method_handles_error_gracefully(self, mock_client):
100 + """Test that method handles errors gracefully."""
101 + mock_client.some_method.side_effect = Exception("Error")
102 +
103 + with pytest.raises(Exception, match="Error"):
104 + # Act
105 + pass
106 +```
107 +
108 +**Mocking:**
109 +- Use `@pytest.fixture` for reusable test dependencies
110 +- Use `unittest.mock.MagicMock` for mock objects
111 +- Use `@patch` decorator for patching modules
112 +- Use `mock.return_value` and `mock.side_effect` for return values
113 +
114 +## Test Naming Conventions
115 +
116 +**TypeScript:**
117 +- `describe()` blocks: Feature/class name
118 +- `it()` blocks: `'should <expected_behavior> when <condition>'`
119 +- Example: `it('should throw validation error when both tools and toolkits are provided')`
120 +
121 +**Python:**
122 +- Class: `TestFeatureName`
123 +- Method: `test_<feature>_<expected_behavior>_when_<condition>`
124 +- Example: `test_create_session_with_toolkits_list`
125 +
126 +## Verification
127 +
128 +Before completing the bug fix:
129 +1. Run the new/updated tests to confirm they pass
130 + - TypeScript: `pnpm test` or `cd ts/packages/<package> && pnpm test`
131 + - Python: `make tst` or `pytest -m <marker>`
132 +2. Run the full test suite to ensure no regressions
133 +3. Document the test in the PR/commit message
.gitignore
+4
@@ -71,3 +71,7 @@ fern/llms-txt-worker/public/*
71 # E2E test node_modules
72 test/e2e/*/node_modules
73 .vercel
74 +
75 +
76 +# Agent memory
77 +.agent_cache
\ No newline at end of file