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
})