1
-# feat: Add project environment detection and dependency installation to `composio init`
2
-
3
-## Overview
4
-
5
-Enhance `composio init` to automatically detect the project environment (TypeScript/Python, package manager, monorepo vs single-package) and install Composio's SDK dependencies using the correct package manager command. This replaces the existing `EnvLangDetector` + `JsPackageManagerDetector` services with a unified `ProjectEnvironmentDetector` service that produces richer detection results, and adds a `CommandRunner` service for running install commands in tests.
6
-
7
-## Problem Statement / Motivation
8
-
9
-Currently, `composio init` writes config files but does **not**:
10
-- Detect what kind of project the user is working in
11
-- Install Composio SDK packages (`@composio/core` for TS, `composio` for Python)
12
-- Install framework-specific provider packages (`@composio/mastra`, `@composio/openai`, etc.)
13
-
14
-Users must manually figure out which packages to install and run the correct package manager command. This is error-prone, especially in monorepos where the package manager may differ from what the user expects.
15
-
16
-The `composio2` branch already has working implementations of `ProjectEnvironmentDetector`, `CommandRunner`, `core-dependency.ts`, and an `install.cmd.ts` with tests. This plan imports and adapts those implementations into the current `feat/cli-login-2.0` branch.
17
-
18
-## Proposed Solution
19
-
20
-### Architecture
21
-
22
-```mermaid
23
-graph TD
24
- A[composio init] --> B[Project Selection]
25
- B --> C[Init Wizard: usage mode + framework + skills]
26
- C --> D[ProjectEnvironmentDetector.detectProjectEnvironment]
27
- D --> E{Detected?}
28
- E -->|Yes| F[Show detection + confirm]
29
- E -->|Ambiguous| G[Prompt user to choose language]
30
- E -->|No indicators| H[Prompt user to choose language + PM]
31
- F --> I[resolveCoreDependencyState]
32
- G --> I
33
- H --> I
34
- I --> J{Already installed?}
35
- J -->|Yes, not --force| K[Skip install, log info]
36
- J -->|No or --force| L[Confirm install command]
37
- L --> M[CommandRunner.run with spinner]
38
- M --> N[Write config files]
39
- N --> O[Optionally install skills]
40
-```
41
-
42
-### Key Components
43
-
44
-1. **`ProjectEnvironmentDetector`** (new service) — replaces `EnvLangDetector` + `JsPackageManagerDetector` with a single service that:
45
- - Walks up the directory tree looking for project indicators
46
- - Produces a `ProjectEnvironment` discriminated union (`js` | `python`)
47
- - Includes `language`, `packageManager`, `rootDir`, and `evidence[]`
48
- - Handles ambiguity (both JS and Python indicators) with a tagged error
49
- - Supports Deno (`deno.json`, `deno.lock`) as a JS package manager
50
-
51
-2. **`CommandRunner`** (new service) — thin wrapper around `@effect/platform` `Command.exitCode` for testability. In production, it runs the actual command; in tests, it returns a configurable exit code.
52
-
53
-3. **`core-dependency.ts`** (new effect) — maps a `ProjectEnvironment` to a `CoreDependencyPlan` containing the install command string, dependency name, and package manager. Also detects if the dependency is already installed.
54
-
55
-4. **Updated `init.cmd.ts`** — integrates detection + installation into the wizard flow after project selection.
56
-
57
-## Technical Approach
58
-
59
-### Phase 1: New Services and Effects
60
-
61
-#### 1.1 Add `ProjectEnvironmentDetector` service
62
-
63
-**File:** `ts/packages/cli/src/services/project-environment-detector.ts`
64
-
65
-Import from: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/services/project-environment-detector.ts`
66
-
67
-The reference implementation is 587 lines and provides:
68
-
69
-```typescript
70
-export type ProjectEnvironment =
71
- | { kind: 'js'; language: JsLanguage; packageManager: JsPackageManager; rootDir: string; evidence: string[] }
72
- | { kind: 'python'; language: 'python'; packageManager: PythonPackageManager; rootDir: string; evidence: string[] };
73
-
74
-export type JsLanguage = 'typescript' | 'javascript';
75
-export type JsPackageManager = 'pnpm' | 'bun' | 'yarn' | 'npm' | 'deno';
76
-export type PythonPackageManager = 'uv' | 'pip';
77
-```
78
-
79
-Key detection strategies:
80
-- **Strong JS indicators:** `package.json`, `tsconfig.json`, `pnpm-workspace.yaml`, lock files — each gets a high score
81
-- **Strong Python indicators:** `pyproject.toml`, `setup.py`, `requirements.txt`, `uv.lock`, `poetry.lock`
82
-- **Weak indicators:** file extension counts (`.ts`, `.py`), subdirectory scans
83
-- **Package manager from `package.json`:** reads `packageManager` field (e.g., `"pnpm@9.0.0"`)
84
-- **Python package manager:** checks for `uv.lock` or `[tool.uv]` in `pyproject.toml`
85
-- **Ancestor walking:** walks up from CWD to filesystem root, checking each directory
86
-
87
-**Ambiguity handling:** If both JS and Python strong indicators exist at CWD depth 0, fails with `ProjectEnvironmentDetectorError`. At deeper levels, skips and continues searching.
88
-
89
-**Service pattern:** Uses `Effect.Service` class with `effect:` body and `dependencies: [BunFileSystem.layer]`.
90
-
91
-#### 1.2 Add `CommandRunner` service
92
-
93
-**File:** `ts/packages/cli/src/services/command-runner.ts`
94
-
95
-Import from: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/services/command-runner.ts`
96
-
97
-```typescript
98
-import { Command } from '@effect/platform';
99
-import { Effect } from 'effect';
100
-
101
-export class CommandRunner extends Effect.Service<CommandRunner>()('services/CommandRunner', {
102
- sync: () => ({
103
- run: (command: Command.Command) => Command.exitCode(command),
104
- }),
105
- dependencies: [],
106
-}) {}
107
-```
108
-
109
-This is intentionally thin — the real value is in testability. In tests, we provide `Layer.succeed(CommandRunner, new CommandRunner({ run: () => Effect.succeed(ExitCode(0)) }))`.
110
-
111
-#### 1.3 Add `core-dependency.ts` effect
112
-
113
-**File:** `ts/packages/cli/src/effects/core-dependency.ts`
114
-
115
-Import from: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/effects/core-dependency.ts`
116
-
117
-Key exports:
118
-- `CoreDependencyPlan` — discriminated union with `installCommand`, `dependency`, `packageManager`, `rootDir`
119
-- `detectCoreDependencyPlan(cwd)` — maps `ProjectEnvironment` → `CoreDependencyPlan`
120
-- `detectCoreDependencyVersion(plan)` — checks if `@composio/core` or `composio` is already installed
121
-- `resolveCoreDependencyState(cwd)` — combines plan + version check
122
-- `getJsInstallCommand(pm, dependency)` — maps package manager to install command
123
-- `getPythonInstallCommand(pm, dependency)` — same for Python
124
-
125
-Install command mapping:
126
-
127
-| PM | Command |
128
-|---|---|
129
-| pnpm | `pnpm add @composio/core` |
130
-| bun | `bun add @composio/core` |
131
-| yarn | `yarn add @composio/core` |
132
-| npm | `npm install -S @composio/core` |
133
-| deno | `deno add npm:@composio/core` |
134
-| uv | `uv pip install composio` |
135
-| pip | `pip install composio` |
136
-
137
-### Phase 2: Update `composio init` Command
138
-
139
-#### 2.1 Add new CLI flags
140
-
141
-```typescript
142
-const dryRunOpt = Options.boolean('dry-run').pipe(
143
- Options.withDefault(false),
144
- Options.withDescription('Print install command without executing it')
145
-);
146
-
147
-const forceOpt = Options.boolean('force').pipe(
148
- Options.withDefault(false),
149
- Options.withDescription('Reinstall even if dependency appears installed')
150
-);
151
-
152
-const yesOpt = Options.boolean('yes').pipe(
153
- Options.withAlias('y'),
154
- Options.withDefault(false),
155
- Options.withDescription('Skip confirmation prompts')
156
-);
157
-```
158
-
159
-#### 2.2 Extend `InitConfigBuilder` and `InitConfig`
160
-
161
-Add new builder steps and fields:
162
-
163
-```typescript
164
-interface InitConfig {
165
- readonly usageMode: UsageMode;
166
- readonly framework: NativeFramework | undefined;
167
- readonly installSkills: boolean;
168
- readonly detectedEnv: ProjectEnvironment; // NEW
169
- readonly installPlan: CoreDependencyPlan; // NEW
170
-}
171
-```
172
-
173
-Add `withDetectedEnv` and `withInstallPlan` methods to `InitConfigBuilder`, and update the `build()` type constraint.
174
-
175
-#### 2.3 Updated wizard flow
176
-
177
-After the existing wizard steps (usage mode → framework → skills), add:
178
-
179
-```typescript
180
-// Step 4: Detect project environment
181
-const envDetector = yield* ProjectEnvironmentDetector;
182
-const detectedEnv = yield* envDetector
183
- .detectProjectEnvironment(proc.cwd)
184
- .pipe(
185
- Effect.catchTag('services/ProjectEnvironmentDetectorError', e =>
186
- Effect.gen(function* () {
187
- yield* ui.log.warn(e.message);
188
- // Fallback: ask user to choose
189
- const lang = yield* ui.select('What language is your project?', [
190
- { value: 'typescript', label: 'TypeScript' },
191
- { value: 'python', label: 'Python' },
192
- ]);
193
- // ... prompt for package manager too
194
- })
195
- )
196
- );
197
-
198
-yield* ui.log.step(`Detected: ${detectedEnv.language} (${detectedEnv.packageManager})`);
199
-
200
-// Step 5: Check if already installed + determine install plan
201
-const { plan, installedVersion } = yield* resolveCoreDependencyState(proc.cwd);
202
-
203
-if (installedVersion && !forceOpt) {
204
- yield* ui.log.info(`Found ${plan.dependency}: ${installedVersion.version}`);
205
- yield* ui.log.success('Dependency already installed.');
206
-} else {
207
- // Step 6: Confirm and install
208
- if (dryRunOpt) {
209
- yield* ui.note(plan.installCommand, 'Install Command');
210
- } else {
211
- const shouldInstall = yesOpt || (yield* ui.confirm(`Run: ${plan.installCommand}?`));
212
- if (shouldInstall) {
213
- yield* ui.withSpinner(`Installing ${plan.dependency}...`, installEffect, {
214
- successMessage: `Installed ${plan.dependency}`,
215
- });
216
- }
217
- }
218
-}
219
-```
220
-
221
-#### 2.4 Framework provider installation
222
-
223
-When a framework is selected (not "skip"), also install the provider package:
224
-
225
-```typescript
226
-const frameworkPackage = getFrameworkPackage(config.framework, detectedEnv);
227
-// e.g., '@composio/mastra' for TS, 'composio[mastra]' for Python
228
-```
229
-
230
-| Framework | TS Package | Python Package |
231
-|---|---|---|
232
-| ai-sdk | `@composio/vercel` | `composio[vercel]` |
233
-| mastra | `@composio/mastra` | `composio[mastra]` |
234
-| openai-agents | `@composio/openai` | `composio[openai]` |
235
-| claude-agent-sdk | `@composio/anthropic` | `composio[anthropic]` |
236
-
237
-### Phase 3: Wire Services in Layer Composition
238
-
239
-#### 3.1 Update `bin.ts`
240
-
241
-Add to the layer composition:
242
-
243
-```typescript
244
-import { ProjectEnvironmentDetector } from 'src/services/project-environment-detector';
245
-import { CommandRunner } from 'src/services/command-runner';
246
-
247
-const layers = Layer.mergeAll(
248
- // ... existing layers ...
249
- ProjectEnvironmentDetector.Default, // NEW
250
- CommandRunner.Default, // NEW
251
-);
252
-```
253
-
254
-#### 3.2 Deprecate `EnvLangDetector` and `JsPackageManagerDetector`
255
-
256
-The new `ProjectEnvironmentDetector` subsumes both. However, `EnvLangDetector` is still used by `generate.cmd.ts`. Options:
257
-
258
-- **Option A (recommended):** Keep both old services for now, use `ProjectEnvironmentDetector` only in `init.cmd.ts`. Migrate `generate.cmd.ts` in a follow-up PR.
259
-- **Option B:** Replace both immediately and update `generate.cmd.ts` to use the new service.
260
-
261
-Go with **Option A** to keep this PR focused.
262
-
263
-### Phase 4: Testing (TDD)
264
-
265
-#### 4.1 Unit tests for `ProjectEnvironmentDetector`
266
-
267
-**File:** `ts/packages/cli/test/src/services/project-environment-detector.test.ts`
268
-
269
-Uses `tempy.temporaryDirectory()` to create isolated temp dirs with specific file layouts. Tests use `BunFileSystem.layer` (real filesystem).
270
-
271
-```
272
-describe('ProjectEnvironmentDetector', () => {
273
- describe('detectProjectEnvironment', () => {
274
- // TypeScript detection
275
- it('[Given] package.json + tsconfig.json [Then] detects typescript + npm')
276
- it('[Given] pnpm-lock.yaml + package.json with packageManager:pnpm@ [Then] detects typescript + pnpm')
277
- it('[Given] bun.lockb [Then] detects javascript + bun')
278
- it('[Given] deno.json [Then] detects typescript + deno')
279
- it('[Given] package.json with typescript dep [Then] detects typescript')
280
-
281
- // Python detection
282
- it('[Given] pyproject.toml with [tool.uv] [Then] detects python + uv')
283
- it('[Given] requirements.txt only [Then] detects python + pip')
284
- it('[Given] uv.lock [Then] detects python + uv')
285
- it('[Given] setup.py only [Then] detects python + pip')
286
-
287
- // Ambiguity
288
- it('[Given] both package.json + pyproject.toml at CWD [Then] fails with ambiguity error')
289
- it('[Given] both indicators but only at parent level [Then] skips and continues')
290
-
291
- // Ancestor walking
292
- it('[Given] indicators at parent directory [Then] detects from parent')
293
- it('[Given] no indicators anywhere [Then] fails with no-detection error')
294
-
295
- // File extension fallback
296
- it('[Given] only .ts files, no config files [Then] detects typescript via weak signals')
297
- it('[Given] only .py files, no config files [Then] detects python via weak signals')
298
-
299
- // Edge cases
300
- it('[Given] empty directory [Then] fails with no-detection error')
301
- it('[Given] monorepo root with pnpm-workspace.yaml [Then] detects pnpm')
302
- })
303
-
304
- describe('detectJsPackageManager', () => {
305
- it('[Given] packageManager field in package.json [Then] uses that')
306
- it('[Given] lock file present [Then] detects from lock file')
307
- it('[Given] no lock file, no packageManager field [Then] defaults to npm')
308
- })
309
-
310
- describe('detectPythonPackageManager', () => {
311
- it('[Given] uv.lock present [Then] detects uv')
312
- it('[Given] [tool.uv] in pyproject.toml [Then] detects uv')
313
- it('[Given] no uv indicators [Then] defaults to pip')
314
- })
315
-})
316
-```
317
-
318
-#### 4.2 Unit tests for `core-dependency.ts`
319
-
320
-**File:** `ts/packages/cli/test/src/effects/core-dependency.test.ts`
321
-
322
-```
323
-describe('core-dependency', () => {
324
- describe('getJsInstallCommand', () => {
325
- it('[Given] pnpm [Then] returns "pnpm add <dep>"')
326
- it('[Given] npm [Then] returns "npm install -S <dep>"')
327
- it('[Given] yarn [Then] returns "yarn add <dep>"')
328
- it('[Given] bun [Then] returns "bun add <dep>"')
329
- it('[Given] deno [Then] returns "deno add npm:<dep>"')
330
- })
331
-
332
- describe('getPythonInstallCommand', () => {
333
- it('[Given] uv [Then] returns "uv pip install <dep>"')
334
- it('[Given] pip [Then] returns "pip install <dep>"')
335
- })
336
-
337
- describe('detectCoreDependencyPlan', () => {
338
- it('[Given] TS project [Then] plans @composio/core install')
339
- it('[Given] Python project [Then] plans composio install')
340
- })
341
-
342
- describe('detectCoreDependencyVersion', () => {
343
- it('[Given] @composio/core in node_modules [Then] returns version')
344
- it('[Given] @composio/core in pnpm virtual store [Then] returns version')
345
- it('[Given] not installed [Then] returns null')
346
- })
347
-})
348
-```
349
-
350
-#### 4.3 Command tests for `composio init`
351
-
352
-**File:** `ts/packages/cli/test/src/commands/init.cmd.test.ts`
353
-
354
-Uses `TestLive` with fixtures and mocked services.
355
-
356
-```
357
-describe('CLI: composio init', () => {
358
- // Agent-native path (--org-id + --project-id)
359
- describe('[Given] --org-id + --project-id flags', () => {
360
- layer(TestLive({ fixture: 'typescript-project' }))(it => {
361
- it.scoped('[Then] detects TS project and shows install plan', () => ...)
362
- })
363
-
364
- layer(TestLive({ fixture: 'python-project' }))(it => {
365
- it.scoped('[Then] detects Python project and shows install plan', () => ...)
366
- })
367
- })
368
-
369
- // Dry-run mode
370
- describe('[Given] --dry-run flag', () => {
371
- layer(TestLive({ fixture: 'typescript-project' }))(it => {
372
- it.scoped('[Then] prints install command without executing', () => ...)
373
- })
374
- })
375
-
376
- // Already installed
377
- describe('[Given] @composio/core already in node_modules', () => {
378
- layer(TestLive({ fixture: 'typescript-project-with-composio-core' }))(it => {
379
- it.scoped('[Then] skips install', () => ...)
380
- })
381
- })
382
-
383
- // --force reinstall
384
- describe('[Given] --force flag with dependency installed', () => {
385
- layer(TestLive({ fixture: 'typescript-project-with-composio-core', commandRunner: successRunner }))(it => {
386
- it.scoped('[Then] reinstalls', () => ...)
387
- })
388
- })
389
-
390
- // Install failure
391
- describe('[Given] install command fails', () => {
392
- layer(TestLive({ fixture: 'typescript-project', commandRunner: failRunner }))(it => {
393
- it.scoped('[Then] shows error message', () => ...)
394
- })
395
- })
396
-})
397
-```
398
-
399
-#### 4.4 New test fixtures needed
400
-
401
-```
402
-test/__fixtures__/
403
- typescript-project/ # EXISTING: package.json + tsconfig.json
404
- python-project/ # EXISTING: requirements.txt + setup.py
405
- typescript-project-with-composio-core/ # EXISTING
406
- python-project-with-composio-core/ # EXISTING
407
- typescript-pnpm-monorepo/ # NEW: pnpm-workspace.yaml + package.json with packageManager:pnpm@
408
- typescript-bun-project/ # NEW: bun.lockb + package.json
409
- python-uv-project/ # NEW: pyproject.toml with [tool.uv] + uv.lock
410
- ambiguous-project/ # NEW: package.json + pyproject.toml (for error case)
411
-```
412
-
413
-#### 4.5 Test layer updates
414
-
415
-Update `TestLive` interface to accept optional overrides:
416
-
417
-```typescript
418
-interface TestLiveInput {
419
- // ... existing fields ...
420
- commandRunner?: CommandRunner; // NEW: mock for CommandRunner
421
- terminalUI?: TerminalUI; // NEW: override TerminalUI for custom prompt behavior
422
-}
423
-```
424
-
425
-Add `ProjectEnvironmentDetector.Default` and `CommandRunner.Default` (or mock) to the test layer composition.
426
-
427
-### Phase 5: E2E Tests
428
-
429
-#### 5.1 `composio init` deterministic E2E test
430
-
431
-**Directory:** `ts/e2e-tests/cli/init/`
432
-
433
-**Constraint:** E2E tests run inside Docker containers. The init command requires API access for project listing, which makes it hard to test end-to-end without mocking.
434
-
435
-**Deterministic test strategy:** Use `--org-id` + `--project-id` flags to bypass API calls. Pre-create a fixture project directory inside the Docker container.
436
-
437
-```typescript
438
-// ts/e2e-tests/cli/init/e2e.test.ts
439
-e2e(import.meta.url, {
440
- versions: { cli: ['current'] },
441
- defineTests: ({ runCmd }) => {
442
- describe('composio init --dry-run', () => {
443
- it('detects TypeScript project', async () => {
444
- // Create a minimal TS project in the container
445
- await runCmd('mkdir -p /tmp/test-ts && echo \'{"name":"test"}\' > /tmp/test-ts/package.json');
446
- await runCmd('echo \'{}\' > /tmp/test-ts/tsconfig.json');
447
-
448
- const result = await runCmd(
449
- 'cd /tmp/test-ts && composio init --org-id test-org --project-id test-proj --dry-run'
450
- );
451
-
452
- expect(result.exitCode).toBe(0);
453
- // In non-interactive (piped) mode, output() writes JSON to stdout
454
- expect(result.stdout).toContain('typescript');
455
- });
456
- });
457
-
458
- describe('composio init on Python project', () => {
459
- it('detects Python project', async () => {
460
- await runCmd('mkdir -p /tmp/test-py && echo "composio" > /tmp/test-py/requirements.txt');
461
-
462
- const result = await runCmd(
463
- 'cd /tmp/test-py && composio init --org-id test-org --project-id test-proj --dry-run'
464
- );
465
-
466
- expect(result.exitCode).toBe(0);
467
- expect(result.stdout).toContain('python');
468
- });
469
- });
470
- },
471
-});
472
-```
473
-
474
-**Note:** The init command's interactive prompts are automatically skipped in piped mode (TerminalUI returns defaults). The `--dry-run` flag prevents actual package installation.
475
-
476
-## Alternative Approaches Considered
477
-
478
-### A. Extend existing `EnvLangDetector` + `JsPackageManagerDetector`
479
-
480
-**Rejected because:** The existing services have separate interfaces that would need to be called independently and manually composed. The `ProjectEnvironmentDetector` provides a single, unified detection result with richer evidence tracking and proper ambiguity handling.
481
-
482
-### B. Separate `composio install` command
483
-
484
-**Reference:** The `composio2` branch already has a standalone `install.cmd.ts`.
485
-
486
-**Decision:** Both approaches have merit. The `composio init` command should include dependency installation as part of the initialization flow. A separate `composio install` command could be added later for re-installation or CI use. This plan focuses on integrating detection + installation into `init`.
487
-
488
-### C. Use `Effect.Service` class vs `Context.Tag` for new services
489
-
490
-**Decision:** Use `Effect.Service` class pattern (newer pattern) for consistency with `EnvLangDetector`, `JsPackageManagerDetector`, `NodeOs`, `NodeProcess`.
491
-
492
-## Acceptance Criteria
493
-
494
-### Functional Requirements
495
-
496
-- [ ] `composio init` detects TypeScript projects (from `tsconfig.json`, `package.json`, lock files)
497
-- [ ] `composio init` detects Python projects (from `pyproject.toml`, `setup.py`, `requirements.txt`)
498
-- [ ] `composio init` detects the correct package manager (pnpm, npm, yarn, bun, deno, uv, pip)
499
-- [ ] `composio init` walks up the directory tree to find project root (monorepo support)
500
-- [ ] `composio init` shows the detected environment and asks for confirmation before installing
501
-- [ ] `composio init` runs the correct install command (`pnpm add`, `npm install`, `uv pip install`, etc.)
502
-- [ ] `composio init --dry-run` prints the install command without executing
503
-- [ ] `composio init --force` reinstalls even if dependency is already present
504
-- [ ] `composio init --yes` skips confirmation prompts
505
-- [ ] `composio init` shows appropriate error messages when detection fails (ambiguous or empty project)
506
-- [ ] `composio init` gracefully handles install command failures
507
-- [ ] `composio init` skips installation when dependency is already installed (without `--force`)
508
-- [ ] `composio init` emits structured JSON to stdout when piped (agent-native)
509
-- [ ] `composio init` writes `detectedEnv` info to `.composio/config.json`
510
-
511
-### Non-Functional Requirements
512
-
513
-- [ ] `pnpm typecheck` passes from repo root
514
-- [ ] All existing tests continue to pass
515
-- [ ] Detection completes in < 500ms for typical projects (filesystem I/O only, no network)
516
-
517
-### Quality Gates
518
-
519
-- [ ] Unit tests for `ProjectEnvironmentDetector` covering all detection strategies
520
-- [ ] Unit tests for `core-dependency.ts` covering all package managers
521
-- [ ] Command tests for `composio init` covering happy path + error cases
522
-- [ ] At least one E2E test for `composio init --dry-run` in Docker container
523
-- [ ] New test fixtures for pnpm monorepo, bun project, uv project, ambiguous project
524
-
525
-## Success Metrics
526
-
527
-- Users can run `composio init` in any TypeScript or Python project and have dependencies installed automatically
528
-- Zero manual `npm install` / `pnpm add` / `uv pip install` steps needed after init
529
-- Package manager is correctly detected in monorepo setups (pnpm workspaces, etc.)
530
-
531
-## Dependencies & Prerequisites
532
-
533
-- `@effect/platform` `Command` module is already a dependency of the CLI package
534
-- The `composio2` reference implementations are available at `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/`
535
-- Test fixtures for `typescript-project` and `python-project` already exist
536
-
537
-## Risk Analysis & Mitigation
538
-
539
-| Risk | Impact | Mitigation |
540
-|---|---|---|
541
-| Ambiguous project detection (both TS + Python) | User confusion | Prompt user to choose, provide clear error message with evidence |
542
-| Install command fails (network, permissions) | Blocked init flow | Show error with the failing command, suggest manual install |
543
-| Package manager not installed on system | Install fails | Check binary existence before running, suggest install |
544
-| Monorepo: init from subdirectory | Wrong root dir detected | Ancestor walking already handles this; root dir = where lock file or package.json with workspaces lives |
545
-| Breaking existing `generate.cmd.ts` | Regression | Keep old services (Option A), migrate generate in follow-up PR |
546
-
547
-## Implementation Phases
548
-
549
-### Phase 1: Foundation (Services + Effects)
550
-- [x] Add `ProjectEnvironmentDetector` service (`src/services/project-environment-detector.ts`)
551
-- [x] Add `CommandRunner` service (`src/services/command-runner.ts`)
552
-- [x] Add `core-dependency.ts` effect (`src/effects/core-dependency.ts`)
553
-- [x] Wire new services in `bin.ts` layer composition
554
-- [x] Add new test fixtures (pnpm monorepo, bun project, uv project, ambiguous)
555
-
556
-### Phase 2: Unit Tests (TDD Red)
557
-- [x] Write `ProjectEnvironmentDetector` tests (17 test cases)
558
-- [x] Write `core-dependency.ts` tests (7 test cases)
559
-- [x] All tests pass (green)
560
-
561
-### Phase 3: Update `composio init` (Green)
562
-- [x] Add `--dry-run`, `--force`, `--yes` flags to init command
563
-- [x] Extend `InitConfigBuilder` with `withDetectedEnv` and `withInstallPlan`
564
-- [x] Integrate detection into the wizard flow
565
-- [x] Integrate installation with spinner and error handling
566
-- [x] Update structured JSON output to include detection info
567
-- [x] Update `.composio/config.json` to include detection info
568
-
569
-### Phase 4: Command Tests
570
-- [x] Write `init.cmd.test.ts` command tests (8 scenarios)
571
-- [x] Update `TestLive` to support `commandRunner` and `terminalUI` overrides
572
-- [x] Add `ProjectEnvironmentDetector.Default` to test layer
573
-
574
-### Phase 5: E2E Tests
575
-- [ ] Add `ts/e2e-tests/cli/init/` E2E test suite (deferred to follow-up PR)
576
-- [ ] Test `--dry-run` mode with TS and Python fixtures in Docker (deferred)
577
-- [ ] Update `ts/e2e-tests/cli/README.md` with new test info (deferred)
578
-
579
-### Phase 6: Cleanup
580
-- [x] Run `pnpm typecheck` and fix any issues
581
-- [x] Run full test suite and fix regressions
582
-- [ ] Update `CLAUDE.md` if needed (document new services)
583
-
584
-## Future Considerations
585
-
586
-- **`composio install` as standalone command** — extract install logic for re-use outside init
587
-- **Framework provider installation** — add framework-specific packages based on wizard selection
588
-- **Skills installation** — run `npx skills add ComposioHQ/skills` when `installSkills: true`
589
-- **Migrate `generate.cmd.ts`** — replace `EnvLangDetector` usage with `ProjectEnvironmentDetector`
590
-- **Deno support** — handle `deno add npm:@composio/core` pattern
591
-
592
-## References & Research
593
-
594
-### Internal References
595
-
596
-- Current `composio init`: `ts/packages/cli/src/commands/init.cmd.ts`
597
-- Existing `EnvLangDetector`: `ts/packages/cli/src/services/env-lang-detector.ts`
598
-- Existing `JsPackageManagerDetector`: `ts/packages/cli/src/services/js-package-manager-detector.ts`
599
-- Layer composition: `ts/packages/cli/src/bin.ts` (lines 93-112)
600
-- Test infrastructure: `ts/packages/cli/test/__utils__/services/test-layer.ts`
601
-- E2E test framework: `ts/e2e-tests/cli/README.md`
602
-- Login command tests (pattern reference): `ts/packages/cli/test/src/commands/login.cmd.test.ts`
603
-
604
-### Reference Implementations (composio2)
605
-
606
-- `ProjectEnvironmentDetector`: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/services/project-environment-detector.ts`
607
-- `CommandRunner`: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/services/command-runner.ts`
608
-- `core-dependency.ts`: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/effects/core-dependency.ts`
609
-- `install.cmd.ts`: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/commands/install.cmd.ts`
610
-- `install.cmd.test.ts`: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/test/src/commands/install.cmd.test.ts`
611
-- `TerminalUI` with prompts: `/Users/jkomyno/work/composio/composio2/ts/packages/cli/src/services/terminal-ui.ts`
612
-
613
-### External References
614
-
615
-- Effect.ts Service pattern: `ts/vendor/effect/packages/effect/src/`
616
-- @effect/cli Command: `ts/vendor/effect/packages/cli/src/Command.ts`
617
-- @effect/platform FileSystem: `ts/vendor/effect/packages/platform/src/FileSystem.ts`
618
-- @effect/platform Command (subprocess): `ts/vendor/effect/packages/platform/src/Command.ts`
619
-- @clack/prompts: `ts/vendor/clack/packages/prompts/src/`