@devries-cameron20 / composio Mirror · read-only / commits / 2b375b485
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(cli): handle plugin setup errors gracefully

Kshitij Jhunjhunwala committed Jul 14, 2026 at 19:20 UTC 2b375b48552c4b06c54803ba8dd8d41277749c40
6 files changed +433 -61
ts/e2e-tests/cli/setup-plugins/e2e.test.ts
+70 -1
@@ -53,6 +53,17 @@ export PATH=/tmp/bin:$PATH
53 composio setup --target auto --yes
54 `;
55
56 +const legacyClaudeFixture = `
57 +set -eu
58 +mkdir -p /tmp/bin /tmp/host-state
59 +cp fixtures/fake-agent-host.sh /tmp/bin/claude
60 +chmod +x /tmp/bin/claude
61 +touch /tmp/host-state/claude-without-json
62 +export HOST_STATE_DIR=/tmp/host-state
63 +export PATH=/tmp/bin:$PATH
64 +composio setup --target auto --yes
65 +`;
66 +
67 const claudeWithLegacyCodexFixture = `
68 set -eu
69 mkdir -p /tmp/bin /tmp/host-state
@@ -71,6 +82,31 @@ test -f /tmp/host-state/claude-plugin
82 test ! -f /tmp/host-state/codex-plugin
83 `;
84
85 +const codexWithLegacyClaudeFixture = `
86 +set -eu
87 +mkdir -p /tmp/bin /tmp/host-state
88 +cp fixtures/fake-agent-host.sh /tmp/bin/claude
89 +cp fixtures/fake-agent-host.sh /tmp/bin/codex
90 +chmod +x /tmp/bin/claude /tmp/bin/codex
91 +touch /tmp/host-state/claude-without-json
92 +export HOST_STATE_DIR=/tmp/host-state
93 +export PATH=/tmp/bin:$PATH
94 +composio setup --target auto --yes
95 +test ! -f /tmp/host-state/claude-plugin
96 +test -f /tmp/host-state/codex-plugin
97 +`;
98 +
99 +const failedClaudeInspectionFixture = `
100 +set -eu
101 +mkdir -p /tmp/bin /tmp/host-state
102 +cp fixtures/fake-agent-host.sh /tmp/bin/claude
103 +chmod +x /tmp/bin/claude
104 +touch /tmp/host-state/claude-inspection-fails
105 +export HOST_STATE_DIR=/tmp/host-state
106 +export PATH=/tmp/bin:$PATH
107 +composio setup --target auto --yes
108 +`;
109 +
110 e2e(import.meta.url, {
111 versions: {
112 cli: ['current'],
@@ -81,8 +117,11 @@ e2e(import.meta.url, {
117 let unavailable: E2ETestResult;
118 let skippedUnavailable: E2ETestResult;
119 let skippedUnavailableUninstall: E2ETestResult;
120 + let legacyClaude: E2ETestResult;
121 let legacyCodex: E2ETestResult;
122 let claudeWithLegacyCodex: E2ETestResult;
123 + let codexWithLegacyClaude: E2ETestResult;
124 + let failedClaudeInspection: E2ETestResult;
125
126 beforeAll(async () => {
127 // The shared E2E runner derives container names from Date.now(), so keep
@@ -100,8 +139,11 @@ e2e(import.meta.url, {
139 skippedUnavailableUninstall = await runCmd(
140 'composio setup --uninstall --target auto --yes --if-present'
141 );
142 + legacyClaude = await runCmd(legacyClaudeFixture);
143 legacyCodex = await runCmd(legacyCodexFixture);
144 claudeWithLegacyCodex = await runCmd(claudeWithLegacyCodexFixture);
145 + codexWithLegacyClaude = await runCmd(codexWithLegacyClaudeFixture);
146 + failedClaudeInspection = await runCmd(failedClaudeInspectionFixture);
147 }, TIMEOUTS.FIXTURE);
148
149 describe.each([
@@ -180,7 +222,14 @@ e2e(import.meta.url, {
222 });
223 });
224
183 - describe('Codex compatibility', () => {
225 + describe('agent compatibility', () => {
226 + it('exits with Claude update instructions when no supported host remains', () => {
227 + expect(legacyClaude.exitCode).not.toBe(0);
228 + expect(legacyClaude.stdout).toBe('');
229 + expect(legacyClaude.stderr).toContain('requires JSON plugin inspection');
230 + expect(legacyClaude.stderr).toContain('claude update');
231 + });
232 +
233 it('exits with upgrade instructions when no supported host remains', () => {
234 expect(legacyCodex.exitCode).not.toBe(0);
235 expect(legacyCodex.stdout).toBe('');
@@ -194,6 +243,26 @@ e2e(import.meta.url, {
243 expect(claudeWithLegacyCodex.stdout).toBe('');
244 expect(claudeWithLegacyCodex.stderr).toBe('');
245 });
246 +
247 + it('continues with Codex when Claude is unsupported', () => {
248 + expect(codexWithLegacyClaude.exitCode).toBe(0);
249 + expect(codexWithLegacyClaude.stdout).toBe('');
250 + expect(codexWithLegacyClaude.stderr).toBe('');
251 + });
252 + });
253 +
254 + describe('graceful failures', () => {
255 + it('reports the failed host, recovery command, and no generic usage dump', () => {
256 + expect(failedClaudeInspection.exitCode).not.toBe(0);
257 + expect(failedClaudeInspection.stdout).toBe('');
258 + expect(failedClaudeInspection.stderr).toContain('Composio setup was unsuccessful.');
259 + expect(failedClaudeInspection.stderr).toContain(
260 + 'Failed to inspect Claude Code plugins: native inspection failed.'
261 + );
262 + expect(failedClaudeInspection.stderr).toContain('composio setup --target claude');
263 + expect(failedClaudeInspection.stderr).not.toContain('USAGE');
264 + expect(failedClaudeInspection.stderr).not.toContain('effect-errors');
265 + });
266 });
267 },
268 });
ts/e2e-tests/cli/setup-plugins/fixtures/fake-agent-host.sh
+16
@@ -12,6 +12,12 @@ case "$host:$command" in
12 "claude:--version")
13 printf '%s\n' '2.1.207 (Claude Code)'
14 ;;
15 + "claude:plugin marketplace list --help"|"claude:plugin list --help")
16 + printf '%s\n' "Usage: claude $command [OPTIONS]"
17 + if [ ! -f "$state_dir/claude-without-json" ]; then
18 + printf '%s\n' ' --json'
19 + fi
20 + ;;
21 "claude:plugin marketplace list --json")
22 if [ -f "$state_dir/claude-marketplace" ]; then
23 printf '%s\n' '[{"name":"composio","source":"git","url":"https://github.com/ComposioHQ/composio-plugin-cc.git"}]'
@@ -20,6 +26,10 @@ case "$host:$command" in
26 fi
27 ;;
28 "claude:plugin list --json")
29 + if [ -f "$state_dir/claude-inspection-fails" ]; then
30 + printf '%s\n' 'native inspection failed' 'Usage: claude plugin list [options]' >&2
31 + exit 2
32 + fi
33 if [ -f "$state_dir/claude-plugin" ]; then
34 printf '%s\n' '[{"id":"composio@composio","scope":"user","enabled":true}]'
35 else
@@ -51,6 +61,12 @@ case "$host:$command" in
61 printf '%s\n' ' --json'
62 fi
63 ;;
64 + "codex:plugin list --help")
65 + printf '%s\n' 'Usage: codex plugin list [OPTIONS]'
66 + if [ ! -f "$state_dir/codex-without-json" ]; then
67 + printf '%s\n' ' --json'
68 + fi
69 + ;;
70 "codex:plugin marketplace list --json")
71 if [ -f "$state_dir/codex-marketplace" ]; then
72 printf '%s\n' '{"marketplaces":[{"name":"composio","marketplaceSource":{"sourceType":"git","source":"ComposioHQ/composio-plugin-openai"}}]}'
ts/packages/cli/src/cli-main.ts
+21 -1
@@ -22,7 +22,7 @@ import { JsPackageManagerDetector } from 'src/services/js-package-manager-detect
22 import { ComposioCliUserConfigLive, ComposioCliUserConfig } from 'src/services/cli-user-config';
23 import { ComposioUserContextLive as _ComposioUserContextLive } from 'src/services/user-context';
24 import { UpgradeBinary } from 'src/services/upgrade-binary';
25 -import { TerminalUILive } from 'src/services/terminal-ui';
25 +import { TerminalUI, TerminalUILive } from 'src/services/terminal-ui';
26 import { TriggersRealtime } from 'src/services/triggers-realtime';
27 import { ToolsExecutorLive as _ToolsExecutorLive } from 'src/services/tools-executor';
28 import { ProjectContext } from 'src/services/project-context';
@@ -39,6 +39,8 @@ import {
39 import { trackCliEvent, trackCliEventEffect } from 'src/analytics/dispatch';
40 import { mapOnlyComposioOverrideError } from 'src/services/composio-error-overrides';
41 import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
42 +import { SetupCommandError } from 'src/services/setup';
43 +import { canRenderTerminalDecoration } from 'src/utils/stdio';
44
45 // eslint-disable-next-line @typescript-eslint/no-explicit-any
46 type RequiredLayer = Layer.Layer<any, any, never>;
@@ -235,6 +237,24 @@ runWithArgs.pipe(
237 );
238 });
239 }),
240 + Effect.catchIf(
241 + (error): error is SetupCommandError => error instanceof SetupCommandError,
242 + error =>
243 + Effect.gen(function* () {
244 + const ui = yield* TerminalUI;
245 + const summary =
246 + error.operation === 'uninstall'
247 + ? 'Composio plugin uninstall was unsuccessful.'
248 + : 'Composio setup was unsuccessful.';
249 + if (canRenderTerminalDecoration()) {
250 + yield* ui.log.error(error.message);
251 + yield* ui.outro(summary);
252 + } else {
253 + yield* Console.error(`${summary} ${error.message}`);
254 + }
255 + process.exitCode = 1;
256 + })
257 + ),
258 Effect.withSpan('composio-cli', {
259 attributes: {
260 name: constants.APP_NAME,
ts/packages/cli/src/commands/setup.cmd.ts
+14 -1
@@ -7,6 +7,7 @@ import {
7 isSetupPluginReady,
8 isSetupReady,
9 SETUP_TARGETS,
10 + SetupCommandError,
11 uninstallSetupTargets,
12 type AgentHost,
13 type SetupTarget,
@@ -44,6 +45,9 @@ const TARGET_LABELS: Readonly<Record<AgentHost, string>> = {
45 const formatTargets = (targets: ReadonlyArray<AgentHost>): string =>
46 targets.map(target => TARGET_LABELS[target]).join(' and ');
47
48 +const errorMessage = (error: unknown): string =>
49 + error instanceof Error ? error.message : String(error);
50 +
51 const setupBaseCmd = Command.make(
52 'setup',
53 { target, yes, ifPresent, uninstall },
@@ -108,6 +112,7 @@ const setupBaseCmd = Command.make(
112
113 const inspected = yield* inspectSetupTargets(detections, {
114 allowMarketplaceConflict: uninstall,
115 + operation: uninstall ? 'uninstall' : 'setup',
116 });
117 if (uninstall) {
118 const installed = inspected.filter(status => status.plugin_installed);
@@ -203,7 +208,15 @@ const setupBaseCmd = Command.make(
208 }
209
210 yield* ui.outro('Composio setup complete.');
206 - })
211 + }).pipe(
212 + Effect.mapError(
213 + error =>
214 + new SetupCommandError({
215 + message: errorMessage(error),
216 + operation: uninstall ? 'uninstall' : 'setup',
217 + })
218 + )
219 + )
220 );
221
222 export const setupCmd = setupBaseCmd.pipe(
ts/packages/cli/src/services/setup.ts
+228 -51
@@ -1,5 +1,5 @@
1 import { Command } from '@effect/platform';
2 -import { Effect } from 'effect';
2 +import { Data, Effect } from 'effect';
3 import semver from 'semver';
4 import { CommandRunner, type CommandResult } from './command-runner';
5 import { SetupSkillInstaller } from './setup-skill-installer';
@@ -46,6 +46,7 @@ interface SetupTargetAdapter {
46 readonly pluginInstallArgs: ReadonlyArray<string>;
47 readonly pluginEnableArgs: ReadonlyArray<string>;
48 readonly pluginUninstallArgs: ReadonlyArray<string>;
49 + readonly inspectionHelpArgs: ReadonlyArray<ReadonlyArray<string>>;
50 readonly marketplaceRecordsKey?: string;
51 readonly pluginRecordsKey?: string;
52 readonly pluginScope?: string;
@@ -82,6 +83,10 @@ const ADAPTERS: Readonly<Record<AgentHost, SetupTargetAdapter>> = {
83 'user',
84 '--yes',
85 ],
86 + inspectionHelpArgs: [
87 + ['plugin', 'marketplace', 'list', '--help'],
88 + ['plugin', 'list', '--help'],
89 + ],
90 pluginScope: 'user',
91 marketplaceRemoveCommand: 'claude plugin marketplace remove composio --scope user',
92 skillSource: 'standalone',
@@ -97,6 +102,10 @@ const ADAPTERS: Readonly<Record<AgentHost, SetupTargetAdapter>> = {
102 // Codex has no separate enable command. Re-adding is its native install/repair path.
103 pluginEnableArgs: ['plugin', 'add', CODEX_PLUGIN_MARKETPLACE.plugin, '--json'],
104 pluginUninstallArgs: ['plugin', 'remove', CODEX_PLUGIN_MARKETPLACE.plugin, '--json'],
105 + inspectionHelpArgs: [
106 + ['plugin', 'marketplace', 'list', '--help'],
107 + ['plugin', 'list', '--help'],
108 + ],
109 marketplaceRecordsKey: 'marketplaces',
110 pluginRecordsKey: 'installed',
111 marketplaceRemoveCommand: 'codex plugin marketplace remove composio --json',
@@ -108,6 +117,11 @@ const ADAPTER_LIST = Object.values(ADAPTERS);
117 const SETUP_COMMAND_TIMEOUT = '2 minutes';
118 const MINIMUM_CODEX_SETUP_VERSION = '0.139.0';
119
120 +export class SetupCommandError extends Data.TaggedError('services/SetupCommandError')<{
121 + readonly message: string;
122 + readonly operation: 'setup' | 'uninstall';
123 +}> {}
124 +
125 const asRecord = (value: unknown): Record<string, unknown> | undefined => {
126 if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
127 return value as Record<string, unknown>;
@@ -228,61 +242,154 @@ const pluginState = (
242 return { installed: true, enabled: plugin.enabled !== false };
243 };
244
245 +const commandText = (executable: string, args: ReadonlyArray<string>) =>
246 + [executable, ...args].join(' ');
247 +
248 const capture = (executable: string, args: ReadonlyArray<string>) =>
249 Effect.gen(function* () {
250 const runner = yield* CommandRunner;
251 return yield* runner.capture(Command.make(executable, ...args)).pipe(
235 - Effect.catchAll(() => Effect.succeed<CommandResult | undefined>(undefined)),
252 Effect.timeoutFail({
253 duration: SETUP_COMMAND_TIMEOUT,
238 - onTimeout: () => new Error(`${executable} command timed out.`),
254 + onTimeout: () =>
255 + new Error(
256 + `The \`${commandText(executable, args)}\` command timed out after ${SETUP_COMMAND_TIMEOUT}.`
257 + ),
258 })
259 );
260 });
261
243 -const unsupportedCodexInspectionMessage = () =>
244 - `This Codex installation does not support safe automatic plugin inspection. Composio setup requires Codex ${MINIMUM_CODEX_SETUP_VERSION} or newer with JSON plugin inspection. Run \`codex update\`, then rerun this command.`;
262 +const isCommandNotFound = (error: unknown): boolean => {
263 + if (error === null || typeof error !== 'object') return false;
264 + const record = error as Record<string, unknown>;
265 + return record._tag === 'SystemError' && record.reason === 'NotFound';
266 +};
267 +
268 +const captureOptional = (executable: string, args: ReadonlyArray<string>) =>
269 + capture(executable, args).pipe(
270 + Effect.catchIf(isCommandNotFound, () => Effect.succeed<CommandResult | undefined>(undefined))
271 + );
272 +
273 +const targetLabel = (target: AgentHost): string => (target === 'claude' ? 'Claude Code' : 'Codex');
274 +
275 +const hostUpdateCommand = (adapter: SetupTargetAdapter): string => `${adapter.executable} update`;
276 +
277 +const unsupportedInspectionMessage = (adapter: SetupTargetAdapter) => {
278 + if (adapter.target === 'codex') {
279 + return `This Codex installation does not support safe automatic plugin inspection. Composio setup requires Codex ${MINIMUM_CODEX_SETUP_VERSION} or newer with JSON plugin inspection. Run \`codex update\`, then rerun this command.`;
280 + }
281 + return 'This Claude Code installation does not support safe automatic plugin inspection. Composio setup requires JSON plugin inspection. Run `claude update`, then rerun this command.';
282 +};
283 +
284 +const compactCommandDetail = (value: string): string | undefined => {
285 + const firstLine = value
286 + .split(/\r?\n/u)
287 + .map(line => line.trim())
288 + .find(Boolean);
289 + if (!firstLine) return undefined;
290 + return firstLine.length > 300 ? `${firstLine.slice(0, 297)}...` : firstLine;
291 +};
292 +
293 +const commandResultDetail = (result: CommandResult): string => {
294 + const detail = compactCommandDetail(result.stderr) ?? compactCommandDetail(result.stdout);
295 + return detail ?? `exit ${result.exitCode}`;
296 +};
297 +
298 +const capabilityCheckFailureMessage = (
299 + adapter: SetupTargetAdapter,
300 + command: string,
301 + detail: string
302 +) => {
303 + const normalizedDetail = detail.trim().replace(/[.]+$/u, '');
304 + return `Composio could not verify plugin support for ${targetLabel(adapter.target)} because \`${command}\` failed: ${normalizedDetail}. Run \`${hostUpdateCommand(adapter)}\`, then rerun this command.`;
305 +};
306
307 const supportsInspection = (adapter: SetupTargetAdapter, versionOutput?: string) =>
308 Effect.gen(function* () {
248 - if (adapter.target !== 'codex') return true;
249 -
250 - const version = versionOutput?.match(/\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\b/)?.[0];
251 - if (!version || !semver.valid(version) || semver.lt(version, MINIMUM_CODEX_SETUP_VERSION)) {
252 - return false;
309 + if (adapter.target === 'codex') {
310 + const version = versionOutput?.match(/\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\b/)?.[0];
311 + if (!version || !semver.valid(version) || semver.lt(version, MINIMUM_CODEX_SETUP_VERSION)) {
312 + return { supported: false, reason: unsupportedInspectionMessage(adapter) };
313 + }
314 }
315
255 - const result = yield* capture(adapter.executable, ['plugin', 'marketplace', 'list', '--help']);
256 - const help = result ? `${result.stdout}\n${result.stderr}` : '';
257 - return result?.exitCode === 0 && /^\s*--json\b/m.test(help);
316 + for (const args of adapter.inspectionHelpArgs) {
317 + const command = commandText(adapter.executable, args);
318 + const result = yield* capture(adapter.executable, args).pipe(
319 + Effect.mapError(
320 + error => new Error(capabilityCheckFailureMessage(adapter, command, errorMessage(error)))
321 + )
322 + );
323 + if (result.exitCode !== 0) {
324 + return {
325 + supported: false,
326 + reason: capabilityCheckFailureMessage(adapter, command, commandResultDetail(result)),
327 + };
328 + }
329 + const help = `${result.stdout}\n${result.stderr}`;
330 + if (!/^\s*--json\b/m.test(help)) {
331 + return { supported: false, reason: unsupportedInspectionMessage(adapter) };
332 + }
333 + }
334 + return { supported: true };
335 });
336
337 const detectAdapter = (adapter: SetupTargetAdapter) =>
338 Effect.gen(function* () {
262 - const result = yield* capture(adapter.executable, ['--version']);
263 - const available = result !== undefined && result.exitCode === 0;
264 - if (!available) return { available, supported: false };
339 + const versionArgs = ['--version'] as const;
340 + const versionCommand = commandText(adapter.executable, versionArgs);
341 + const captureResult = yield* captureOptional(adapter.executable, versionArgs).pipe(
342 + Effect.map(result => ({ result }) as const),
343 + Effect.catchAll(error => Effect.succeed({ error } as const))
344 + );
345 + if ('error' in captureResult) {
346 + return {
347 + available: true,
348 + supported: false,
349 + unsupportedReason: capabilityCheckFailureMessage(
350 + adapter,
351 + versionCommand,
352 + errorMessage(captureResult.error)
353 + ),
354 + };
355 + }
356 + const { result } = captureResult;
357 + if (!result) return { available: false, supported: false };
358 + if (result.exitCode === 127) return { available: false, supported: false };
359 + if (result.exitCode !== 0) {
360 + return {
361 + available: true,
362 + supported: false,
363 + unsupportedReason: capabilityCheckFailureMessage(
364 + adapter,
365 + versionCommand,
366 + commandResultDetail(result)
367 + ),
368 + };
369 + }
370
371 const version = result.stdout.trim() || result.stderr.trim();
267 - const supported = yield* supportsInspection(adapter, version);
372 + const support = yield* supportsInspection(adapter, version).pipe(
373 + Effect.catchAll(error =>
374 + Effect.succeed({ supported: false, reason: errorMessage(error) } as const)
375 + )
376 + );
377 return version
378 ? {
270 - available,
271 - supported,
379 + available: true,
380 + supported: support.supported,
381 version,
273 - ...(supported ? {} : { unsupportedReason: unsupportedCodexInspectionMessage() }),
382 + ...(support.supported ? {} : { unsupportedReason: support.reason }),
383 }
384 : {
276 - available,
277 - supported,
278 - ...(supported ? {} : { unsupportedReason: unsupportedCodexInspectionMessage() }),
385 + available: true,
386 + supported: support.supported,
387 + ...(support.supported ? {} : { unsupportedReason: support.reason }),
388 };
389 });
390
391 const commandFailureSuffix = (result: CommandResult): string => {
283 - const detail = result.stderr.trim() || result.stdout.trim();
284 - if (detail) return `: ${detail}`;
285 - return ` (exit ${result.exitCode})`;
392 + return `: ${commandResultDetail(result)}`;
393 };
394
395 const errorMessage = (error: unknown): string => {
@@ -290,23 +397,50 @@ const errorMessage = (error: unknown): string => {
397 return String(error);
398 };
399
400 +type SetupOperation = 'setup' | 'uninstall';
401 +
402 +const setupCommand = (adapter: SetupTargetAdapter, operation: SetupOperation): string =>
403 + `composio setup${operation === 'uninstall' ? ' --uninstall' : ''} --target ${adapter.target}`;
404 +
405 +const recoveryHint = (adapter: SetupTargetAdapter, operation: SetupOperation): string =>
406 + `Run \`${setupCommand(adapter, operation)}\` again. If the problem persists, run \`${hostUpdateCommand(adapter)}\` and retry.`;
407 +
408 +const captureInspection = (
409 + adapter: SetupTargetAdapter,
410 + args: ReadonlyArray<string>,
411 + operation: string,
412 + setupOperation: SetupOperation
413 +) =>
414 + capture(adapter.executable, args).pipe(
415 + Effect.mapError(
416 + error =>
417 + new Error(
418 + `Failed to inspect ${targetLabel(adapter.target)} ${operation}: ${errorMessage(error)}. ${recoveryHint(adapter, setupOperation)}`
419 + )
420 + )
421 + );
422 +
423 const requireInspection = <T>(
424 adapter: SetupTargetAdapter,
425 operation: string,
296 - result: CommandResult | undefined,
297 - parse: (output: string) => T | undefined
426 + result: CommandResult,
427 + parse: (output: string) => T | undefined,
428 + setupOperation: SetupOperation
429 ) => {
299 - if (!result) {
300 - return Effect.fail(new Error(`Failed to inspect ${adapter.target} ${operation}.`));
301 - }
430 if (result.exitCode !== 0) {
431 return Effect.fail(
304 - new Error(`Failed to inspect ${adapter.target} ${operation}${commandFailureSuffix(result)}.`)
432 + new Error(
433 + `Failed to inspect ${targetLabel(adapter.target)} ${operation}${commandFailureSuffix(result)}. ${recoveryHint(adapter, setupOperation)}`
434 + )
435 );
436 }
437 const inspected = parse(result.stdout);
438 if (!inspected) {
309 - return Effect.fail(new Error(`${adapter.target} returned invalid JSON for ${operation}.`));
439 + return Effect.fail(
440 + new Error(
441 + `${targetLabel(adapter.target)} returned invalid JSON while inspecting ${operation}. ${recoveryHint(adapter, setupOperation)}`
442 + )
443 + );
444 }
445 return Effect.succeed(inspected);
446 };
@@ -317,7 +451,8 @@ const inspectAdapter = (
451 readonly available: boolean;
452 readonly supported: boolean;
453 readonly version?: string;
320 - }
454 + },
455 + setupOperation: SetupOperation = 'setup'
456 ) =>
457 Effect.gen(function* () {
458 const skillInstaller = yield* SetupSkillInstaller;
@@ -335,19 +470,27 @@ const inspectAdapter = (
470 }
471
472 if (!detection.supported) {
338 - return yield* Effect.fail(new Error(unsupportedCodexInspectionMessage()));
473 + return yield* Effect.fail(new Error(unsupportedInspectionMessage(adapter)));
474 }
475
476 const [marketplaces, plugins] = yield* Effect.all([
342 - capture(adapter.executable, adapter.marketplaceListArgs),
343 - capture(adapter.executable, adapter.pluginListArgs),
477 + captureInspection(adapter, adapter.marketplaceListArgs, 'marketplaces', setupOperation),
478 + captureInspection(adapter, adapter.pluginListArgs, 'plugins', setupOperation),
479 ]);
345 - const plugin = yield* requireInspection(adapter, 'plugins', plugins, output =>
346 - pluginState(adapter, output)
480 + const plugin = yield* requireInspection(
481 + adapter,
482 + 'plugins',
483 + plugins,
484 + output => pluginState(adapter, output),
485 + setupOperation
486 );
487 const pluginReady = plugin.installed && plugin.enabled;
349 - const marketplace = yield* requireInspection(adapter, 'marketplaces', marketplaces, output =>
350 - marketplaceState(adapter, output)
488 + const marketplace = yield* requireInspection(
489 + adapter,
490 + 'marketplaces',
491 + marketplaces,
492 + output => marketplaceState(adapter, output),
493 + setupOperation
494 );
495 let cliSkillReady = pluginReady;
496 if (adapter.skillSource === 'standalone') {
@@ -397,17 +540,32 @@ export const isSetupPluginReady = (status: SetupTargetStatus): boolean =>
540 export const isSetupReady = (status: SetupTargetStatus): boolean =>
541 isSetupPluginReady(status) && status.cli_skill_ready;
542
400 -const runRequired = (adapter: SetupTargetAdapter, args: ReadonlyArray<string>, operation: string) =>
543 +const runRequired = (
544 + adapter: SetupTargetAdapter,
545 + args: ReadonlyArray<string>,
546 + operation: string,
547 + setupOperation: SetupOperation
548 +) =>
549 Effect.gen(function* () {
550 const runner = yield* CommandRunner;
551 const result = yield* runner.capture(Command.make(adapter.executable, ...args)).pipe(
552 Effect.timeoutFail({
553 duration: SETUP_COMMAND_TIMEOUT,
554 onTimeout: () => new Error(`${operation} timed out after ${SETUP_COMMAND_TIMEOUT}.`),
407 - })
555 + }),
556 + Effect.mapError(
557 + error =>
558 + new Error(
559 + `${operation} failed: ${errorMessage(error)}. ${recoveryHint(adapter, setupOperation)}`
560 + )
561 + )
562 );
563 if (result.exitCode !== 0) {
410 - return yield* Effect.fail(new Error(`${operation} failed${commandFailureSuffix(result)}`));
564 + return yield* Effect.fail(
565 + new Error(
566 + `${operation} failed${commandFailureSuffix(result)}. ${recoveryHint(adapter, setupOperation)}`
567 + )
568 + );
569 }
570 });
571
@@ -441,14 +599,21 @@ const installAdapter = (adapter: SetupTargetAdapter, initial: InspectedSetupTarg
599 const repairStep = pluginRepairStep(adapter, initial);
600 if (repairStep) steps.push(repairStep);
601 for (const step of steps) {
444 - yield* runRequired(adapter, step.args, step.operation);
602 + yield* runRequired(adapter, step.args, step.operation, 'setup');
603 }
604 const pluginChanged = steps.length > 0;
605
606 const skillInstaller = yield* SetupSkillInstaller;
607 let skillChanged = false;
608 if (adapter.skillSource === 'standalone' && !initial.cli_skill_ready) {
451 - skillChanged = yield* skillInstaller.ensureClaudeSkill;
609 + skillChanged = yield* skillInstaller.ensureClaudeSkill.pipe(
610 + Effect.mapError(
611 + error =>
612 + new Error(
613 + `Installing the Claude Code CLI skill failed: ${errorMessage(error)}. ${recoveryHint(adapter, 'setup')}`
614 + )
615 + )
616 + );
617 }
618
619 const final = yield* inspectAdapter(adapter);
@@ -480,7 +645,8 @@ const uninstallAdapter = (adapter: SetupTargetAdapter, initial: InspectedSetupTa
645 yield* runRequired(
646 adapter,
647 adapter.pluginUninstallArgs,
483 - `Uninstalling the ${adapter.target} plugin`
648 + `Uninstalling the ${adapter.target} plugin`,
649 + 'uninstall'
650 );
651 pluginChanged = true;
652 }
@@ -488,10 +654,17 @@ const uninstallAdapter = (adapter: SetupTargetAdapter, initial: InspectedSetupTa
654 const skillInstaller = yield* SetupSkillInstaller;
655 let skillChanged = false;
656 if (adapter.skillSource === 'standalone') {
491 - skillChanged = yield* skillInstaller.removeClaudeSkill;
657 + skillChanged = yield* skillInstaller.removeClaudeSkill.pipe(
658 + Effect.mapError(
659 + error =>
660 + new Error(
661 + `Removing the Claude Code CLI skill failed: ${errorMessage(error)}. ${recoveryHint(adapter, 'uninstall')}`
662 + )
663 + )
664 + );
665 }
666
494 - const final = yield* inspectAdapter(adapter);
667 + const final = yield* inspectAdapter(adapter, undefined, 'uninstall');
668 if (final.plugin_installed) {
669 return yield* Effect.fail(
670 new Error(
@@ -541,12 +714,16 @@ export const detectSetupTargets = (target: SetupTarget) =>
714
715 export const inspectSetupTargets = (
716 detections: ReadonlyArray<SetupTargetDetection>,
544 - options: { readonly allowMarketplaceConflict?: boolean } = {}
717 + options: {
718 + readonly allowMarketplaceConflict?: boolean;
719 + readonly operation?: SetupOperation;
720 + } = {}
721 ) =>
722 Effect.gen(function* () {
723 const inspected = yield* Effect.forEach(
724 detections.filter(detection => detection.available && detection.supported),
549 - detection => inspectAdapter(ADAPTERS[detection.target], detection)
725 + detection =>
726 + inspectAdapter(ADAPTERS[detection.target], detection, options.operation ?? 'setup')
727 );
728 if (!options.allowMarketplaceConflict) {
729 yield* Effect.forEach(inspected, status =>
ts/packages/cli/test/src/commands/setup.cmd.test.ts
+84 -7
@@ -122,6 +122,7 @@ const makeFakeHosts = (
122 readonly noOp?: boolean;
123 readonly failOn?: string;
124 readonly malformedOn?: string;
125 + readonly claudeJsonInspection?: boolean;
126 readonly codexJsonInspection?: boolean;
127 readonly codexVersion?: string;
128 readonly marketplaceSource?: Partial<Record<AgentHost, string>>;
@@ -164,12 +165,18 @@ const makeFakeHosts = (
165 : HOST_OUTPUT_FORMATTERS[host].version,
166 };
167 }
167 - if (command === 'codex plugin marketplace list --help') {
168 + if (
169 + command === `${host} plugin marketplace list --help` ||
170 + command === `${host} plugin list --help`
171 + ) {
172 + const supportsJson =
173 + host === 'claude'
174 + ? options.claudeJsonInspection !== false
175 + : options.codexJsonInspection !== false;
176 return {
169 - stdout:
170 - options.codexJsonInspection === false
171 - ? 'Usage: codex plugin marketplace list [OPTIONS]'
172 - : 'Usage: codex plugin marketplace list [OPTIONS]\n\n --json',
177 + stdout: supportsJson
178 + ? `Usage: ${command.replace(' --help', ' [OPTIONS]')}\n\n --json`
179 + : `Usage: ${command.replace(' --help', ' [OPTIONS]')}`,
180 };
181 }
182 if (options.failOn && command.includes(options.failOn)) {
@@ -484,6 +491,46 @@ describe('CLI: composio setup', () => {
491 );
492 });
493
494 + const autoCodexWithLegacyClaude = makeFakeHosts(
495 + {
496 + claude: { available: true },
497 + codex: { available: true },
498 + },
499 + { claudeJsonInspection: false }
500 + );
501 + layer(TestLive({ commandRunner: autoCodexWithLegacyClaude.runner }))(
502 + 'automatic setup with unsupported Claude and Codex',
503 + it => {
504 + it.scoped('installs Codex and reports that Claude was skipped', () =>
505 + Effect.gen(function* () {
506 + yield* cli(['setup', '--target', 'auto', '--yes']);
507 +
508 + expect(autoCodexWithLegacyClaude.state.claude).toMatchObject({
509 + marketplace: 'missing',
510 + plugin: 'missing',
511 + });
512 + expect(autoCodexWithLegacyClaude.state.codex).toMatchObject({
513 + marketplace: 'canonical',
514 + plugin: 'enabled',
515 + });
516 + expect(
517 + autoCodexWithLegacyClaude.commands.some(
518 + parts => parts[0] === 'claude' && parts.includes('--json')
519 + )
520 + ).toBe(false);
521 +
522 + const output = (yield* MockConsole.getLines()).join('\n');
523 + expect(output).toContain('Claude Code and Codex detected.');
524 + expect(output).toContain('Claude Code plugin setup skipped.');
525 + expect(output).toContain('Run `claude update`');
526 + expect(output).toContain(
527 + 'Successfully installed and enabled the Composio plugin for Codex.'
528 + );
529 + })
530 + );
531 + }
532 + );
533 +
534 const allTargets = makeFakeHosts({
535 claude: { available: true },
536 codex: { available: true },
@@ -525,7 +572,7 @@ describe('CLI: composio setup', () => {
572 });
573 expect(
574 partialAllTargets.commands.some(parts =>
528 - ['marketplace', 'install', 'enable'].some(operation => parts.includes(operation))
575 + ['add', 'install', 'enable'].some(operation => parts.includes(operation))
576 )
577 ).toBe(false);
578 })
@@ -914,6 +961,34 @@ describe('CLI: composio setup', () => {
961 { codex: { available: true } },
962 { codexJsonInspection: false, codexVersion: 'codex-cli 0.137.0' }
963 );
964 +
965 + const legacyClaude = makeFakeHosts(
966 + { claude: { available: true } },
967 + { claudeJsonInspection: false }
968 + );
969 + layer(TestLive({ commandRunner: legacyClaude.runner }))(
970 + 'Claude without JSON plugin inspection',
971 + it => {
972 + it.scoped('fails automatic setup with actionable update instructions', () =>
973 + Effect.gen(function* () {
974 + const exit = yield* Effect.exit(cli(['setup', '--target', 'auto', '--yes']));
975 +
976 + expect(Exit.isFailure(exit)).toBe(true);
977 + if (Exit.isFailure(exit)) {
978 + const renderedCause = Cause.pretty(exit.cause);
979 + expect(renderedCause).toContain('requires JSON plugin inspection');
980 + expect(renderedCause).toContain('claude update');
981 + }
982 + expect(legacyClaude.commands.some(parts => parts.includes('--json'))).toBe(false);
983 + expect(
984 + legacyClaude.commands.some(parts =>
985 + ['add', 'install', 'enable', 'uninstall'].some(operation => parts.includes(operation))
986 + )
987 + ).toBe(false);
988 + })
989 + );
990 + }
991 + );
992 layer(TestLive({ commandRunner: legacyCodex.runner }))(
993 'Codex without JSON marketplace inspection',
994 it => {
@@ -1053,7 +1128,9 @@ describe('CLI: composio setup', () => {
1128 expect(Exit.isFailure(exit)).toBe(true);
1129 if (Exit.isFailure(exit)) {
1130 const renderedCause = Cause.pretty(exit.cause);
1056 - expect(renderedCause).toContain('claude command timed out');
1131 + expect(renderedCause).toContain(
1132 + 'The `claude --version` command timed out after 2 minutes'
1133 + );
1134 expect(renderedCause).not.toContain('not installed or not available on PATH');
1135 }
1136 })