@devries-cameron20 / composio Mirror · read-only / commits / 6d5465acd
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

refactor(cli): seal the CommandDescriptor seam and drop zod for Schema (#3882)

This PR: - activates the descriptor-seam rule group: `commands/command-introspection.ts` becomes the only module allowed to import `CommandDescriptor`/`Usage` from `@effect/cli` — the redesign seam the Effect CLI v4 migration will reimplement - routes root command assembly, preflight parsing, help routing, and value-option collection through the seam helpers instead of descriptor walks - replaces the Zod-backed tool-input adapter with an internal `@composio/json-schema-to-effect-schema` compiler backed by the eval-free `@cfworker/json-schema` interpreter - normalizes the OpenAPI and Composio extensions accepted by the previous validator, while preserving typed `ToolInputValidationError` failures, field paths, multi-error reporting, and typo suggestions - extends the descriptor and Zod boundaries to reject static imports, dynamic `import()`, and `require()` bypasses - adds compiler parity tests plus CLI regression coverage for multiple simultaneous field and unknown-key failures - introspection tests pin that the helpers yield identical descriptors and usage strings --- **Stack** (re-slice of https://github.com/ComposioHQ/composio/pull/3859; each PR targets its parent and auto-retargets to `next` as parents merge): 1. https://github.com/ComposioHQ/composio/pull/3877 — guidelines + inert rule groups 2. https://github.com/ComposioHQ/composio/pull/3878 — `new Function()` eval security fix 3. https://github.com/ComposioHQ/composio/pull/3879 — behavioral fix pack 4. https://github.com/ComposioHQ/composio/pull/3880 — platform-imports rule + migration 5. https://github.com/ComposioHQ/composio/pull/3881 — terminal-streams rule + TerminalUI boundary 6. https://github.com/ComposioHQ/composio/pull/3882 — descriptor seam + Zod→Schema ← **this PR** 7. https://github.com/ComposioHQ/composio/pull/3883 — test-tree lint + deterministic suites 8. https://github.com/ComposioHQ/composio/pull/3884 — typed error boundaries + v4 seams 9. https://github.com/ComposioHQ/composio/pull/3885 — try/catch+env ban + boundary ratchet On stacked bases CI runs lint/build and the CLI Docker e2e job; unit tests and typecheck are verified locally per PR and re-verified by full CI when each PR is retargeted to `next`.

Alberto Schiabel committed Jul 21, 2026 at 11:25 UTC 6d5465acd37f72ab9b9fb2c5abcaf9db8c963e50
29 files changed +1567 -656
eslint.config.mjs
+59 -38
@@ -104,6 +104,18 @@ const cliDescriptorSeamRestrictedImportPatterns = [
104 },
105 ];
106
107 +const cliDescriptorSeamRestrictedSyntax = [
108 + {
109 + selector: 'ImportExpression[source.value=/^@effect\\/cli(?:\\/(?:CommandDescriptor|Usage))?$/]',
110 + message: cliDescriptorSeamMessage,
111 + },
112 + {
113 + selector:
114 + "CallExpression[callee.name='require'][arguments.0.value=/^@effect\\/cli(?:\\/(?:CommandDescriptor|Usage))?$/]",
115 + message: cliDescriptorSeamMessage,
116 + },
117 +];
118 +
119 const effectSchemaRestrictedImportPaths = [
120 {
121 name: 'zod',
@@ -118,6 +130,17 @@ const effectSchemaRestrictedImportPatterns = [
130 },
131 ];
132
133 +const effectSchemaRestrictedSyntax = [
134 + {
135 + selector: 'ImportExpression[source.value=/^zod(?:\\/|$)/]',
136 + message: 'Use Schema from effect for tool input validation.',
137 + },
138 + {
139 + selector: "CallExpression[callee.name='require'][arguments.0.value=/^zod(?:\\/|$)/]",
140 + message: 'Use Schema from effect for tool input validation.',
141 + },
142 +];
143 +
144 /** @type {import('eslint').Linter.Config[]} */
145 export default [
146 {
@@ -189,16 +212,8 @@ export default [
212 'no-restricted-imports': [
213 'error',
214 {
192 - paths: [
193 - ...cliRestrictedImportPaths,
194 - // uncommented by the seam-rules PR of this stack
195 - // ...cliDescriptorSeamRestrictedImportPaths,
196 - ],
197 - patterns: [
198 - ...cliRestrictedImportPatterns,
199 - // uncommented by the seam-rules PR of this stack
200 - // ...cliDescriptorSeamRestrictedImportPatterns,
201 - ],
215 + paths: [...cliRestrictedImportPaths, ...cliDescriptorSeamRestrictedImportPaths],
216 + patterns: [...cliRestrictedImportPatterns, ...cliDescriptorSeamRestrictedImportPatterns],
217 },
218 ],
219 'no-restricted-syntax': [
@@ -206,6 +221,7 @@ export default [
221 // uncommented by the boundary-ratchet PR of this stack
222 // ...cliRestrictedSyntax,
223 ...cliProcessStreamRestrictions,
224 + ...cliDescriptorSeamRestrictedSyntax,
225 ],
226 },
227 },
@@ -237,34 +253,39 @@ export default [
253 // ],
254 // },
255 // },
240 - // uncommented by the seam-rules PR of this stack.
241 - // {
242 - // // The one file allowed to touch @effect/cli's CommandDescriptor/Usage
243 - // // modules (the Effect CLI v4 redesign seam).
244 - // files: ['ts/packages/cli/src/commands/command-introspection.ts'],
245 - // rules: {
246 - // 'no-restricted-imports': [
247 - // 'error',
248 - // {
249 - // paths: cliRestrictedImportPaths,
250 - // patterns: cliRestrictedImportPatterns,
251 - // },
252 - // ],
253 - // },
254 - // },
255 - // uncommented by the seam-rules PR of this stack.
256 - // {
257 - // files: ['ts/packages/cli/src/services/tool-input-validation.ts'],
258 - // rules: {
259 - // 'no-restricted-imports': [
260 - // 'error',
261 - // {
262 - // paths: [...cliRestrictedImportPaths, ...effectSchemaRestrictedImportPaths],
263 - // patterns: [...cliRestrictedImportPatterns, ...effectSchemaRestrictedImportPatterns],
264 - // },
265 - // ],
266 - // },
267 - // },
256 + {
257 + // The one file allowed to touch @effect/cli's CommandDescriptor/Usage
258 + // modules (the Effect CLI v4 redesign seam).
259 + files: ['ts/packages/cli/src/commands/command-introspection.ts'],
260 + rules: {
261 + 'no-restricted-imports': [
262 + 'error',
263 + {
264 + paths: cliRestrictedImportPaths,
265 + patterns: cliRestrictedImportPatterns,
266 + },
267 + ],
268 + 'no-restricted-syntax': ['error', ...cliProcessStreamRestrictions],
269 + },
270 + },
271 + {
272 + files: ['ts/packages/cli/src/services/tool-input-validation.ts'],
273 + rules: {
274 + 'no-restricted-imports': [
275 + 'error',
276 + {
277 + paths: [...cliRestrictedImportPaths, ...effectSchemaRestrictedImportPaths],
278 + patterns: [...cliRestrictedImportPatterns, ...effectSchemaRestrictedImportPatterns],
279 + },
280 + ],
281 + 'no-restricted-syntax': [
282 + 'error',
283 + ...cliProcessStreamRestrictions,
284 + ...cliDescriptorSeamRestrictedSyntax,
285 + ...effectSchemaRestrictedSyntax,
286 + ],
287 + },
288 + },
289 {
290 files: ['ts/packages/cli/src/services/terminal-ui.ts'],
291 rules: {
package.json
+1
@@ -9,6 +9,7 @@
9 "ts/packages/core",
10 "ts/packages/experimental",
11 "ts/packages/slim",
12 + "ts/packages/json-schema-to-effect-schema",
13 "ts/packages/json-schema-to-zod",
14 "ts/packages/cli",
15 "ts/packages/cli-keyring",
pnpm-lock.yaml
+28
@@ -1141,6 +1141,9 @@ importers:
1141 '@composio/core':
1142 specifier: workspace:*
1143 version: link:../core
1144 + '@composio/json-schema-to-effect-schema':
1145 + specifier: workspace:*
1146 + version: link:../json-schema-to-effect-schema
1147 '@composio/json-schema-to-zod':
1148 specifier: workspace:*
1149 version: link:../json-schema-to-zod
@@ -1404,6 +1407,31 @@ importers:
1407 specifier: 'catalog:'
1408 version: 4.1.10(@opentelemetry/api@1.9.0)(@types/node@26.1.0)(@vitest/ui@4.1.10)(vite@7.3.1(@types/node@26.1.0)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
1409
1410 + ts/packages/json-schema-to-effect-schema:
1411 + dependencies:
1412 + '@cfworker/json-schema':
1413 + specifier: ^4.1.1
1414 + version: 4.1.1
1415 + effect:
1416 + specifier: 'catalog:'
1417 + version: 3.21.4
1418 + devDependencies:
1419 + '@composio/json-schema-to-zod':
1420 + specifier: workspace:*
1421 + version: link:../json-schema-to-zod
1422 + tsdown:
1423 + specifier: 'catalog:'
1424 + version: 0.22.3(@arethetypeswrong/core@0.18.4)(@typescript/native-preview@7.0.0-dev.20260703.1)(publint@0.3.21)(tsx@4.23.0)(typescript@6.0.3)(unrun@0.2.27(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1))
1425 + typescript:
1426 + specifier: 'catalog:'
1427 + version: 6.0.3
1428 + vitest:
1429 + specifier: 'catalog:'
1430 + version: 4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.0)(@vitest/ui@4.1.10)(vite@7.3.1(@types/node@26.1.0)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
1431 + zod:
1432 + specifier: 'catalog:'
1433 + version: 4.4.3
1434 +
1435 ts/packages/json-schema-to-zod:
1436 devDependencies:
1437 '@types/json-schema':
pnpm-workspace.yaml
+1
@@ -11,6 +11,7 @@ packages:
11 - ts/packages/cli-local-tools
12 - ts/packages/core
13 - ts/packages/experimental
14 + - ts/packages/json-schema-to-effect-schema
15 - ts/packages/json-schema-to-zod
16 - ts/packages/slim
17 - ts/packages/providers/*
ts/packages/cli/package.json
+1
@@ -86,6 +86,7 @@
86 "@composio/cli-local-tools": "workspace:*",
87 "@composio/client": "catalog:",
88 "@composio/core": "workspace:*",
89 + "@composio/json-schema-to-effect-schema": "workspace:*",
90 "@composio/json-schema-to-zod": "workspace:*",
91 "@composio/ts-builders": "workspace:*",
92 "@effect/cli": "catalog:",
ts/packages/cli/src/cli-main.ts
+4 -51
@@ -1,11 +1,12 @@
1 import process from 'node:process';
2 -import { Cause, Effect, Exit, HashMap, Layer, Logger, Option } from 'effect';
2 +import { Cause, Effect, Exit, Layer, Logger } from 'effect';
3 import { captureErrors, prettyPrintFromCapturedErrors } from 'effect-errors/index';
4 -import { CliConfig, CommandDescriptor, HelpDoc, Usage, ValidationError } from '@effect/cli';
4 +import { CliConfig, HelpDoc, ValidationError } from '@effect/cli';
5 import { FetchHttpClient } from '@effect/platform';
6 import { BunContext, BunRuntime, BunFileSystem, BunPath } from '@effect/platform-bun';
7 import type { Teardown } from '@effect/platform/Runtime';
8 import { buildRootCommand, runWithConfig } from 'src/commands';
9 +import { collectValueOptionNames } from 'src/commands/command-introspection';
10 import { matchCommandFromArgv, getCommandHelpText } from 'src/commands/root-help';
11 import * as constants from 'src/constants';
12 import { ComposioCliConfig } from 'src/cli-config';
@@ -140,53 +141,6 @@ const runWithArgs = Effect.flatMap(runWithConfig, run => run(process.argv)) sati
141 unknown
142 >;
143
143 -const collectValueOptionNamesFromUsage = (usage: Usage.Usage, acc: Set<string>) => {
144 - switch (usage._tag) {
145 - case 'Named': {
146 - if (Option.isSome(usage.acceptedValues)) {
147 - for (const name of usage.names) {
148 - if (name.startsWith('-')) {
149 - acc.add(name);
150 - }
151 - }
152 - }
153 - return;
154 - }
155 - case 'Optional':
156 - case 'Repeated': {
157 - collectValueOptionNamesFromUsage(usage.usage, acc);
158 - return;
159 - }
160 - case 'Alternation':
161 - case 'Concat': {
162 - collectValueOptionNamesFromUsage(usage.left, acc);
163 - collectValueOptionNamesFromUsage(usage.right, acc);
164 - return;
165 - }
166 - case 'Mixed':
167 - case 'Empty': {
168 - return;
169 - }
170 - }
171 -};
172 -
173 -const collectValueOptionNames = (rootCommand: ReturnType<typeof buildRootCommand>) => {
174 - const names = new Set<string>();
175 - const visited = new Set<CommandDescriptor.Command<unknown>>();
176 - const visit = (command: CommandDescriptor.Command<unknown>) => {
177 - if (visited.has(command)) {
178 - return;
179 - }
180 - visited.add(command);
181 - collectValueOptionNamesFromUsage(CommandDescriptor.getUsage(command), names);
182 - for (const [, subcommand] of HashMap.toEntries(CommandDescriptor.getSubcommands(command))) {
183 - visit(subcommand);
184 - }
185 - };
186 - visit(rootCommand.descriptor);
187 - return names;
188 -};
189 -
144 const runWithTelemetry = Effect.gen(function* () {
145 const ui = yield* TerminalUI;
146 const terminal = yield* ui.capabilities;
@@ -314,6 +268,5 @@ showUpdateNotice.pipe(
268 ),
269 Effect.provide(layers),
270 Effect.withConfigProvider(extendConfigProvider(BaseConfigProviderLive)),
317 - effect =>
318 - (BunRuntime.runMain({ teardown }) as (e: Effect.Effect<void, unknown, unknown>) => void)(effect)
271 + BunRuntime.runMain({ teardown })
272 );
ts/packages/cli/src/commands/$default.cmd.ts
+22 -5
@@ -1,9 +1,26 @@
1 -import { Context, Schema, LogLevel, String, pipe, Layer, Effect } from 'effect';
1 +import { Context, Schema, LogLevel, Equal, Layer, Effect } from 'effect';
2 import { Command, Options } from '@effect/cli';
3 import { setMinimumLogLevel } from 'src/effects/with-log-level';
4 import type { ConfigError } from 'effect/ConfigError';
5
6 -const logLevelChoices = LogLevel.allLevels.map(level => String.toLowerCase(level._tag));
6 +const logLevelEntries = [
7 + ['all', LogLevel.All],
8 + ['fatal', LogLevel.Fatal],
9 + ['error', LogLevel.Error],
10 + ['warning', LogLevel.Warning],
11 + ['info', LogLevel.Info],
12 + ['debug', LogLevel.Debug],
13 + ['trace', LogLevel.Trace],
14 + ['none', LogLevel.None],
15 +] as const satisfies ReadonlyArray<readonly [string, LogLevel.LogLevel]>;
16 +
17 +const logLevelChoices = logLevelEntries.map(([choice]) => choice);
18 +
19 +const decodeLogLevel = (literal: (typeof logLevelChoices)[number]): LogLevel.LogLevel =>
20 + logLevelEntries.find(([choice]) => choice === literal)?.[1] ?? LogLevel.None;
21 +
22 +const encodeLogLevel = (logLevel: LogLevel.LogLevel): (typeof logLevelChoices)[number] =>
23 + logLevelEntries.find(([, value]) => Equal.equals(value, logLevel))?.[0] ?? 'none';
24
25 const LogLevelLiteralSchema = Schema.Literal(...logLevelChoices)
26 .annotations({
@@ -12,13 +29,13 @@ const LogLevelLiteralSchema = Schema.Literal(...logLevelChoices)
29 .pipe(
30 Schema.transform(
31 Schema.declare((input: unknown): input is LogLevel.LogLevel =>
15 - LogLevel.allLevels.includes(input as LogLevel.LogLevel)
32 + logLevelEntries.some(([, logLevel]) => Equal.equals(input, logLevel))
33 ).annotations({
34 identifier: 'LogLevel',
35 }),
36 {
20 - decode: literal => pipe(literal, String.capitalize, LogLevel.fromLiteral),
21 - encode: logLevel => String.toLowerCase(logLevel._tag),
37 + decode: decodeLogLevel,
38 + encode: encodeLogLevel,
39 strict: true,
40 }
41 )
ts/packages/cli/src/commands/command-introspection.ts new
+94
@@ -0,0 +1,94 @@
1 +import { Array as Arr, Effect, HashMap, HashSet, Match, Option } from 'effect';
2 +import { CliConfig, CommandDescriptor, Usage } from '@effect/cli';
3 +import { ComposioCliConfig } from 'src/cli-config';
4 +
5 +/**
6 + * The only module in `src/` allowed to import `CommandDescriptor` or `Usage`
7 + * from `@effect/cli`. Those modules are the redesign seam for Effect CLI v4's
8 + * public command tree, so every descriptor walk must stay behind the small
9 + * CLI-domain-shaped operations exported here — the v4 migration should only
10 + * ever reimplement this file. An ESLint `no-restricted-imports` override in
11 + * the repo-root `eslint.config.mjs` keeps the seam sealed.
12 + */
13 +
14 +export type AnyCommandDescriptor = CommandDescriptor.Command<unknown>;
15 +
16 +export type AnyCommand = { readonly descriptor: AnyCommandDescriptor };
17 +
18 +const collectValueOptionNamesFromUsage = (usage: Usage.Usage, acc: Set<string>): void =>
19 + Match.valueTags(usage, {
20 + Named: usage => {
21 + if (Option.isSome(usage.acceptedValues)) {
22 + for (const name of usage.names) {
23 + if (name.startsWith('-')) {
24 + acc.add(name);
25 + }
26 + }
27 + }
28 + },
29 + Optional: usage => {
30 + collectValueOptionNamesFromUsage(usage.usage, acc);
31 + },
32 + Repeated: usage => {
33 + collectValueOptionNamesFromUsage(usage.usage, acc);
34 + },
35 + Alternation: usage => {
36 + collectValueOptionNamesFromUsage(usage.left, acc);
37 + collectValueOptionNamesFromUsage(usage.right, acc);
38 + },
39 + Concat: usage => {
40 + collectValueOptionNamesFromUsage(usage.left, acc);
41 + collectValueOptionNamesFromUsage(usage.right, acc);
42 + },
43 + Mixed: () => undefined,
44 + Empty: () => undefined,
45 + });
46 +
47 +/**
48 + * Collects the names of every flag that accepts a value (e.g. `--org`)
49 + * across the whole command tree, so the top-level error handler can print
50 + * a "Tip: --flag requires a value" hint on unknown-argument failures.
51 + */
52 +export const collectValueOptionNames = (command: AnyCommand): ReadonlySet<string> => {
53 + const names = new Set<string>();
54 + const visited = new Set<AnyCommandDescriptor>();
55 + const visit = (descriptor: AnyCommandDescriptor) => {
56 + if (visited.has(descriptor)) {
57 + return;
58 + }
59 + visited.add(descriptor);
60 + collectValueOptionNamesFromUsage(CommandDescriptor.getUsage(descriptor), names);
61 + for (const [, subcommand] of HashMap.toEntries(CommandDescriptor.getSubcommands(descriptor))) {
62 + visit(subcommand);
63 + }
64 + };
65 + visit(command.descriptor);
66 + return names;
67 +};
68 +
69 +/** Whether `name` is one of the names the command itself answers to. */
70 +export const hasCommandName = (command: AnyCommand, name: string): boolean =>
71 + HashSet.has(CommandDescriptor.getNames(command.descriptor), name);
72 +
73 +/**
74 + * Lists the names of a command's direct subcommands, excluding the
75 + * command's own names (the descriptor's subcommand map includes those).
76 + */
77 +export const listSubcommandNames = (descriptor: AnyCommandDescriptor): ReadonlyArray<string> => {
78 + const ownNames = CommandDescriptor.getNames(descriptor);
79 + return Array.from(HashMap.keys(CommandDescriptor.getSubcommands(descriptor))).filter(
80 + name => !HashSet.has(ownNames, name)
81 + );
82 +};
83 +
84 +/**
85 + * Parses `argv` (a full `process.argv`) against the command tree without
86 + * running it, using the CLI's own config — a pre-flight check that surfaces
87 + * `ValidationError`s (e.g. command mismatches) before the command executes.
88 + */
89 +export const preflightParse = (command: AnyCommand, argv: ReadonlyArray<string>) =>
90 + CommandDescriptor.parse(
91 + command.descriptor,
92 + Arr.prepend(Arr.drop(argv, 2), 'composio'),
93 + CliConfig.make(ComposioCliConfig)
94 + ).pipe(Effect.asVoid);
ts/packages/cli/src/commands/dev.cmd.ts
+1 -1
@@ -20,7 +20,7 @@ const devMode = Options.choice('mode', ['on', 'off'] as const).pipe(
20 Options.optional
21 );
22
23 -const devSubcommands = [
23 +export const devSubcommands = [
24 initCmd,
25 devToolsCmd$Execute,
26 triggersCmd$Listen,
ts/packages/cli/src/commands/index.ts
+269 -358
@@ -1,6 +1,12 @@
1 import process from 'node:process';
2 -import { Effect, Option } from 'effect';
2 +import { Array as Arr, Data, Effect, HashSet, Option } from 'effect';
3 import { Command, HelpDoc, ValidationError } from '@effect/cli';
4 +import {
5 + hasCommandName,
6 + listSubcommandNames,
7 + preflightParse,
8 + type AnyCommandDescriptor,
9 +} from './command-introspection';
10 import { $defaultCmd } from './$default.cmd';
11 import { getVersion } from 'src/effects/version';
12 import { versionCmd } from './version.cmd';
@@ -17,10 +23,11 @@ import { artifactsCmd } from './artifacts.cmd';
23 import { installCmd } from './install.cmd';
24 import { localToolsCmd } from './local-tools/local-tools.cmd';
25 import { generateCmd } from './generate/generate.cmd';
20 -import { buildDevCommand } from './dev.cmd';
26 +import { buildDevCommand, devSubcommands } from './dev.cmd';
27 import {
28 runParallelToolsExecuteFromArgv,
29 showToolsExecuteInputHelp,
30 + TOOLS_EXECUTE_VALUE_OPTIONS,
31 } from './tools/commands/tools.execute.cmd';
32 import {
33 printRootHelp,
@@ -49,16 +56,9 @@ import {
56 } from 'src/services/command-project';
57 import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
58 import { installSkill, type SkillInstallTarget } from 'src/effects/install-skill';
52 -import {
53 - experimental,
54 - type CommandVisibility,
55 - type TaggedValue,
56 - tagged,
57 - visibleValues,
58 -} from './feature-tags';
59 -
60 -// eslint-disable-next-line @typescript-eslint/no-explicit-any
61 -const ROOT_COMMANDS: ReadonlyArray<TaggedValue<Command.Command<any, any, any, any>>> = [
59 +import { experimental, type CommandVisibility, tagged, visibleValues } from './feature-tags';
60 +
61 +const ROOT_COMMANDS = [
62 tagged(versionCmd),
63 tagged(upgradeCmd),
64 tagged(whoamiCmd),
@@ -84,193 +84,139 @@ const ROOT_COMMANDS: ReadonlyArray<TaggedValue<Command.Command<any, any, any, an
84 tagged(configCmd),
85 ];
86
87 -export const buildRootCommand = (visibility: CommandVisibility) => {
88 - const subcommands = [...visibleValues(ROOT_COMMANDS, visibility), buildDevCommand(visibility)];
89 - // eslint-disable-next-line @typescript-eslint/no-explicit-any
90 - return $defaultCmd.pipe(Command.withSubcommands(subcommands as any));
91 -};
92 -
93 -const formatSubcommandChoices = (choices: ReadonlyArray<string>) =>
94 - choices.map(choice => `'${choice}'`).join(', ');
95 -
96 -/**
97 - * Internal shape of an `@effect/cli` command descriptor. The public
98 - * `CommandDescriptor.getSubcommands` helper flattens nested subcommand trees
99 - * and only returns the *parent* Standard node for each branch, which means we
100 - * can't use it to walk deeper than one level. Walking the `_tag`-based
101 - * internal tree directly is the only way to recover the full descendable
102 - * structure without losing subcommand context on descent.
103 - */
104 -type InternalDescriptor =
105 - | { _tag: 'Standard'; name: string }
106 - | { _tag: 'GetUserInput'; name: string }
107 - | { _tag: 'Map'; command: InternalDescriptor }
108 - | {
109 - _tag: 'Subcommands';
110 - parent: InternalDescriptor;
111 - children: ReadonlyArray<InternalDescriptor>;
112 - };
113 -
114 -type UnwrappedDescriptor = Exclude<InternalDescriptor, { _tag: 'Map' }>;
115 -
116 -const unwrapMaps = (cmd: InternalDescriptor): UnwrappedDescriptor => {
117 - let current: InternalDescriptor = cmd;
118 - while (current._tag === 'Map') {
119 - current = current.command;
120 - }
121 - return current;
122 -};
123 -
124 -const getCommandName = (cmd: InternalDescriptor): string => {
125 - const unwrapped = unwrapMaps(cmd);
126 - if (unwrapped._tag === 'Subcommands') {
127 - return getCommandName(unwrapped.parent);
128 - }
129 - return unwrapped.name;
130 -};
131 -
132 -const getChildEntries = (
133 - cmd: InternalDescriptor
134 -): ReadonlyArray<readonly [string, InternalDescriptor]> => {
135 - const unwrapped = unwrapMaps(cmd);
136 - if (unwrapped._tag !== 'Subcommands') {
137 - return [];
138 - }
139 - return unwrapped.children.map(child => [getCommandName(child), child] as const);
87 +const getVisibleRootCommands = (visibility: CommandVisibility) => {
88 + type RootCommand = (typeof ROOT_COMMANDS)[number]['value'];
89 + return Arr.append(
90 + visibleValues<RootCommand>(ROOT_COMMANDS, visibility),
91 + buildDevCommand(visibility)
92 + );
93 };
94
142 -const findNestedSubcommandMismatch = (
143 - argv: ReadonlyArray<string>,
144 - rootCommand: ReturnType<typeof buildRootCommand>
145 -): ReturnType<typeof ValidationError.commandMismatch> | undefined => {
146 - const args = argv.slice(2);
147 - let current: InternalDescriptor = rootCommand.descriptor as unknown as InternalDescriptor;
148 - const path = ['composio'];
149 -
150 - for (const token of args) {
151 - if (!token || token === '--' || token === '--help' || token === '-h' || token.startsWith('-')) {
152 - return undefined;
153 - }
154 -
155 - const children = getChildEntries(current);
156 - if (children.length === 0) {
157 - return undefined;
158 - }
159 -
160 - const match = children.find(([name]) => name === token);
161 - if (match) {
162 - current = match[1];
163 - path.push(token);
164 - continue;
165 - }
95 +export const buildRootCommand = (visibility: CommandVisibility) =>
96 + $defaultCmd.pipe(Command.withSubcommands(getVisibleRootCommands(visibility)));
97
167 - if (path.length === 1) {
168 - return undefined;
169 - }
98 +const ROOT_INSTALL_SKILL_FLAGS = HashSet.make('--install-skill', '--instal-skill');
99 +const SKILL_INSTALL_TARGETS: ReadonlyArray<SkillInstallTarget> = ['claude', 'codex', 'openclaw'];
100
171 - const available = children.map(([name]) => name).sort();
172 - return ValidationError.commandMismatch(
173 - HelpDoc.p(
174 - `Invalid subcommand for ${path.join(' ')} - use one of ${formatSubcommandChoices(available)}`
175 - )
176 - );
177 - }
101 +class RootCommandError extends Data.TaggedError('commands/RootCommandError')<{
102 + readonly message: string;
103 +}> {}
104
179 - return undefined;
105 +type RootInstallSkillRequest = {
106 + readonly skillName?: string;
107 + readonly target: SkillInstallTarget;
108 };
109
182 -const ROOT_INSTALL_SKILL_FLAGS = ['--install-skill', '--instal-skill'] as const;
183 -const SKILL_INSTALL_TARGETS = [
184 - 'claude',
185 - 'codex',
186 - 'openclaw',
187 -] as const satisfies ReadonlyArray<SkillInstallTarget>;
188 -
189 -type RootInstallSkillRequest =
190 - | {
191 - _tag: 'parsed';
192 - skillName?: string;
193 - target: SkillInstallTarget;
194 - }
195 - | { _tag: 'error'; message: string };
196 -
110 const isSkillInstallTarget = (value: string): value is SkillInstallTarget =>
198 - (SKILL_INSTALL_TARGETS as ReadonlyArray<string>).includes(value);
199 -
200 -export const parseRootInstallSkillRequest = (
201 - argv: ReadonlyArray<string>
202 -): RootInstallSkillRequest | undefined => {
203 - const args = argv.slice(2);
204 - for (let i = 0; i < args.length; i += 1) {
205 - const token = args[i];
206 - if (!token) continue;
207 -
208 - if ((ROOT_INSTALL_SKILL_FLAGS as ReadonlyArray<string>).includes(token)) {
209 - const rawValues: string[] = [];
210 - for (let j = i + 1; j < args.length; j += 1) {
211 - const next = args[j];
212 - if (!next) continue;
213 - if (next.startsWith('-')) break;
214 - rawValues.push(next);
111 + SKILL_INSTALL_TARGETS.some(target => target === value);
112 +
113 +const rootCommandError = (message: string) => Effect.fail(new RootCommandError({ message }));
114 +
115 +const findRootInstallSkillValues = (
116 + args: ReadonlyArray<string>
117 +): Option.Option<ReadonlyArray<string>> =>
118 + Arr.matchLeft(args, {
119 + onEmpty: Option.none,
120 + onNonEmpty: (token, tail) => {
121 + if (HashSet.has(ROOT_INSTALL_SKILL_FLAGS, token)) {
122 + return Option.some(Arr.takeWhile(tail, value => !value.startsWith('-')));
123 }
216 -
217 - if (rawValues.length === 0) {
218 - return {
219 - _tag: 'error',
220 - message:
221 - 'Missing target for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>',
222 - };
124 + if (token === '--log-level') {
125 + return findRootInstallSkillValues(Arr.drop(tail, 1));
126 }
224 -
225 - if (rawValues.length === 1) {
226 - const [target] = rawValues;
227 - if (!isSkillInstallTarget(target)) {
228 - return {
229 - _tag: 'error',
230 - message:
231 - 'Invalid target for --install-skill. Expected one of: claude, codex, openclaw.',
232 - };
233 - }
234 - return { _tag: 'parsed', target };
127 + if (token.startsWith('--log-level=') || token.startsWith('-')) {
128 + return findRootInstallSkillValues(tail);
129 }
130 + return Option.none();
131 + },
132 + });
133
237 - if (rawValues.length === 2) {
238 - const [skillName, target] = rawValues;
239 - if (!isSkillInstallTarget(target)) {
240 - return {
241 - _tag: 'error',
242 - message:
243 - 'Invalid target for --install-skill. Expected one of: claude, codex, openclaw.',
244 - };
245 - }
246 - return { _tag: 'parsed', skillName, target };
134 +const parseRootInstallSkillValues = (
135 + rawValues: ReadonlyArray<string>
136 +): Effect.Effect<RootInstallSkillRequest, RootCommandError> =>
137 + Arr.match(rawValues, {
138 + onEmpty: () =>
139 + rootCommandError(
140 + 'Missing target for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>'
141 + ),
142 + onNonEmpty: ([first, second, ...rest]) => {
143 + if (rest.length > 0) {
144 + return rootCommandError(
145 + 'Too many arguments for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>'
146 + );
147 }
148 + const target = second ?? first;
149 + if (!isSkillInstallTarget(target)) {
150 + return rootCommandError(
151 + 'Invalid target for --install-skill. Expected one of: claude, codex, openclaw.'
152 + );
153 + }
154 + return Effect.succeed(second === undefined ? { target } : { skillName: first, target });
155 + },
156 + });
157
249 - return {
250 - _tag: 'error',
251 - message:
252 - 'Too many arguments for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>',
253 - };
254 - }
158 +export const parseRootInstallSkillRequest = (
159 + argv: ReadonlyArray<string>
160 +): Effect.Effect<Option.Option<RootInstallSkillRequest>, RootCommandError> =>
161 + Option.match(findRootInstallSkillValues(Arr.drop(argv, 2)), {
162 + onNone: () => Effect.succeed(Option.none()),
163 + onSome: values => Effect.map(parseRootInstallSkillValues(values), Option.some),
164 + });
165
256 - if (token === '--log-level') {
257 - i += 1;
258 - continue;
259 - }
166 +const scopeCommandMismatch = (
167 + commandPath: string,
168 + descriptor: AnyCommandDescriptor,
169 + error: unknown
170 +) => {
171 + if (!ValidationError.isValidationError(error) || !ValidationError.isCommandMismatch(error)) {
172 + return error;
173 + }
174 + const childNames = listSubcommandNames(descriptor).map(name => `'${name}'`);
175 + if (childNames.length === 0) return error;
176 +
177 + const oneOf = childNames.length === 1 ? '' : ' one of';
178 + return ValidationError.commandMismatch(
179 + HelpDoc.p(
180 + `Invalid subcommand for composio ${commandPath} - use${oneOf} ${childNames.join(', ')}`
181 + )
182 + );
183 +};
184
261 - if (token.startsWith('--log-level=')) {
262 - continue;
263 - }
185 +const refineRootCommandMismatch = (
186 + argv: ReadonlyArray<string>,
187 + visibility: CommandVisibility,
188 + originalError: ValidationError.ValidationError
189 +) => {
190 + const rootCommandName = argv[2];
191 + if (!rootCommandName || !ValidationError.isCommandMismatch(originalError)) {
192 + return Effect.fail(originalError);
193 + }
194
265 - if (!token.startsWith('-')) {
266 - return undefined;
267 - }
195 + const rootCommand = Arr.findFirst(getVisibleRootCommands(visibility), command =>
196 + hasCommandName(command, rootCommandName)
197 + );
198 + if (Option.isNone(rootCommand)) {
199 + return Effect.fail(originalError);
200 }
269 - return undefined;
201 +
202 + const nestedCommandName = argv[3];
203 + const nestedDevCommand =
204 + rootCommandName === 'dev' && visibility.isDevModeEnabled && nestedCommandName
205 + ? Arr.findFirst(devSubcommands, command => hasCommandName(command, nestedCommandName))
206 + : Option.none();
207 + const descriptor = Option.match(nestedDevCommand, {
208 + onNone: () => rootCommand.value.descriptor,
209 + onSome: command => command.descriptor,
210 + });
211 + const commandPath = Option.isSome(nestedDevCommand)
212 + ? `${rootCommandName} ${nestedCommandName}`
213 + : rootCommandName;
214 +
215 + return Effect.fail(scopeCommandMismatch(commandPath, descriptor, originalError));
216 };
217
272 -const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefined => {
273 - const args = argv.slice(2);
218 +export const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefined => {
219 + const args = Arr.drop(argv, 2);
220 const isRootExecute = args[0] === 'execute';
221 const isDevExecute = args[0] === 'dev' && args[1] === 'playground-execute';
222 if (!isRootExecute && !isDevExecute) return undefined;
@@ -278,55 +224,29 @@ const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefi
224 const hasHelp = args.includes('--help') || args.includes('-h');
225 if (!hasHelp) return undefined;
226
281 - const tail = isRootExecute ? args.slice(1) : args.slice(2);
282 - for (let i = 0; i < tail.length; i += 1) {
283 - const token = tail[i];
284 - if (!token) continue;
285 -
286 - // Stop option parsing after "--" and treat next positional as slug.
287 - if (token === '--') {
288 - const candidate = tail[i + 1];
289 - return candidate && !candidate.startsWith('-') ? candidate : undefined;
290 - }
291 -
292 - // Ignore help flags.
293 - if (token === '--help' || token === '-h') {
294 - continue;
295 - }
296 -
297 - // Skip known execute option values.
298 - if (
299 - token === '--data' ||
300 - token === '-d' ||
301 - token === '--parallel' ||
302 - token === '-p' ||
303 - token === '--user-id' ||
304 - token === '--project-name'
305 - ) {
306 - i += 1;
307 - continue;
308 - }
309 - if (
310 - token.startsWith('--data=') ||
311 - token.startsWith('-d=') ||
312 - token === '--parallel' ||
313 - token === '-p' ||
314 - token.startsWith('--user-id=') ||
315 - token.startsWith('--project-name=')
316 - ) {
317 - continue;
318 - }
319 -
320 - // Skip unknown flags.
321 - if (token.startsWith('-')) {
322 - continue;
323 - }
324 -
325 - // First positional token is the slug.
326 - return token;
327 - }
227 + const findSlug = (tail: ReadonlyArray<string>): string | undefined =>
228 + Arr.matchLeft(tail, {
229 + onEmpty: () => undefined,
230 + onNonEmpty: (token, rest) => {
231 + if (token === '--') {
232 + return Option.getOrUndefined(
233 + Option.filter(Arr.head(rest), candidate => !candidate.startsWith('-'))
234 + );
235 + }
236 + if (token === '--help' || token === '-h') {
237 + return findSlug(rest);
238 + }
239 + if (HashSet.has(TOOLS_EXECUTE_VALUE_OPTIONS, token)) {
240 + return findSlug(Arr.drop(rest, 1));
241 + }
242 + if (token.startsWith('-')) {
243 + return findSlug(rest);
244 + }
245 + return token;
246 + },
247 + });
248
329 - return undefined;
249 + return findSlug(Arr.drop(args, isRootExecute ? 1 : 2));
250 };
251
252 const normalizeVersionShortFlag = (argv: ReadonlyArray<string>): ReadonlyArray<string> => {
@@ -338,78 +258,54 @@ const normalizeVersionShortFlag = (argv: ReadonlyArray<string>): ReadonlyArray<s
258 };
259
260 const normalizeListenStreamFlag = (argv: ReadonlyArray<string>): ReadonlyArray<string> => {
341 - const head = argv.slice(0, 2);
342 - const args = argv.slice(2);
261 + const head = Arr.take(argv, 2);
262 + const args = Arr.drop(argv, 2);
263 const isListen = args[0] === 'listen';
264 if (!isListen) {
265 return argv;
266 }
267
348 - const normalized: string[] = [...head];
349 - for (let i = 0; i < args.length; i += 1) {
350 - const token = args[i];
351 - if (token !== '--stream') {
352 - normalized.push(token ?? '');
353 - continue;
354 - }
355 -
356 - const next = args[i + 1];
357 - if (next === undefined || next.startsWith('-')) {
358 - normalized.push('--stream=');
359 - continue;
360 - }
268 + return Arr.appendAll(
269 + head,
270 + Arr.map(args, (token, index) => {
271 + const next = args[index + 1];
272 + return token === '--stream' && (next === undefined || next.startsWith('-'))
273 + ? '--stream='
274 + : token;
275 + })
276 + );
277 +};
278
362 - normalized.push(token);
279 +const parseBooleanFlag = (argument: string, name: string): Option.Option<boolean> => {
280 + if (argument === name || argument === `${name}=true`) {
281 + return Option.some(true);
282 }
364 -
365 - return normalized;
283 + return argument === `${name}=false` ? Option.some(false) : Option.none();
284 };
285
286 const normalizeHiddenDebugFlags = (argv: ReadonlyArray<string>): ReadonlyArray<string> => {
369 - const normalized: string[] = [...argv.slice(0, 2)];
370 - const args = argv.slice(2);
287 + const retainedArgs: Array<string> = [];
288 let perfDebug: boolean | undefined;
289 let toolDebug: boolean | undefined;
290 let acpOnly: boolean | undefined;
291
375 - for (const arg of args) {
376 - if (arg === '--perf-debug') {
377 - perfDebug = true;
378 - continue;
379 - }
380 - if (arg === '--tool-debug') {
381 - toolDebug = true;
382 - continue;
383 - }
384 - if (arg === '--perf-debug=false') {
385 - perfDebug = false;
292 + for (const argument of Arr.drop(argv, 2)) {
293 + const parsedPerfDebug = Option.getOrUndefined(parseBooleanFlag(argument, '--perf-debug'));
294 + if (parsedPerfDebug !== undefined) {
295 + perfDebug = parsedPerfDebug;
296 continue;
297 }
388 - if (arg === '--tool-debug=false') {
389 - toolDebug = false;
298 + const parsedToolDebug = Option.getOrUndefined(parseBooleanFlag(argument, '--tool-debug'));
299 + if (parsedToolDebug !== undefined) {
300 + toolDebug = parsedToolDebug;
301 continue;
302 }
392 - if (arg === '--perf-debug=true') {
393 - perfDebug = true;
303 + const parsedAcpOnly = Option.getOrUndefined(parseBooleanFlag(argument, '--acp-only'));
304 + if (parsedAcpOnly !== undefined) {
305 + acpOnly = parsedAcpOnly;
306 continue;
307 }
396 - if (arg === '--tool-debug=true') {
397 - toolDebug = true;
398 - continue;
399 - }
400 - if (arg === '--acp-only') {
401 - acpOnly = true;
402 - continue;
403 - }
404 - if (arg === '--acp-only=false') {
405 - acpOnly = false;
406 - continue;
407 - }
408 - if (arg === '--acp-only=true') {
409 - acpOnly = true;
410 - continue;
411 - }
412 - normalized.push(arg);
308 + retainedArgs.push(argument);
309 }
310
311 resetRuntimeDebugFlags();
@@ -417,13 +313,15 @@ const normalizeHiddenDebugFlags = (argv: ReadonlyArray<string>): ReadonlyArray<s
313 ...(perfDebug === undefined ? {} : { perfDebug }),
314 ...(toolDebug === undefined ? {} : { toolDebug }),
315 });
316 + // The hidden --acp-only flag is stripped from argv before @effect/cli parses it, so its value
317 + // travels to run.cmd.ts through the environment; effect/Config cannot write or delete env vars.
318 if (acpOnly === undefined) {
319 delete process.env.COMPOSIO_RUN_ACP_ONLY;
320 } else {
321 process.env.COMPOSIO_RUN_ACP_ONLY = acpOnly ? '1' : '0';
322 }
323
426 - return normalized;
324 + return Arr.appendAll(Arr.take(argv, 2), retainedArgs);
325 };
326
327 const isRootHelp = (argv: ReadonlyArray<string>): boolean => {
@@ -453,19 +351,18 @@ const isDebugWhoIsMyMaster = (argv: ReadonlyArray<string>): boolean => {
351 };
352
353 const normalizeDangerouslyAllowFlag = (argv: ReadonlyArray<string>) => {
456 - const normalized: string[] = [...argv.slice(0, 2)];
354 + const retainedArgs: Array<string> = [];
355 let dangerouslyAllow = false;
458 -
459 - for (const arg of argv.slice(2)) {
460 - if (arg === '--dangerously-allow') {
356 + for (const argument of Arr.drop(argv, 2)) {
357 + if (argument === '--dangerously-allow') {
358 dangerouslyAllow = true;
462 - continue;
359 + } else {
360 + retainedArgs.push(argument);
361 }
464 - normalized.push(arg);
362 }
363
364 return {
468 - argv: normalized,
365 + argv: Arr.appendAll(Arr.take(argv, 2), retainedArgs),
366 dangerouslyAllow,
367 };
368 };
@@ -492,6 +389,60 @@ const isDangerousDevCommand = (args: ReadonlyArray<string>): boolean => {
389 return false;
390 };
391
392 +const printCommandHintGraph = Effect.suspend(() =>
393 + Effect.flatMap(TerminalUI, ui =>
394 + ui.output(JSON.stringify(renderCommandHintGraph(), null, 2), { force: true })
395 + )
396 +);
397 +
398 +const printDebugApiInfo = Effect.gen(function* () {
399 + const ui = yield* TerminalUI;
400 + const confirmed = yield* ui.confirm(
401 + 'This will print your current CLI API key and scoped identifiers to stdout. Continue?',
402 + { defaultValue: false }
403 + );
404 + if (!confirmed) {
405 + return yield* rootCommandError('Aborted printing API credentials.');
406 + }
407 + const ctx = yield* ComposioUserContext;
408 + const apiKey = Option.getOrUndefined(ctx.data.apiKey);
409 + if (!apiKey) {
410 + return yield* rootCommandError('No user API key found in the current CLI session.');
411 + }
412 + const orgId = Option.getOrUndefined(ctx.data.orgId);
413 + const consumerProject = yield* resolveCommandProject({ mode: 'consumer' }).pipe(
414 + Effect.mapError(formatResolveCommandProjectError),
415 + Effect.option
416 + );
417 + return yield* ui.output(
418 + JSON.stringify(
419 + {
420 + apiKey,
421 + orgId: orgId ?? null,
422 + consumerUserId:
423 + Option.isSome(consumerProject) && consumerProject.value.projectType === 'CONSUMER'
424 + ? (consumerProject.value.consumerUserId ?? null)
425 + : null,
426 + },
427 + null,
428 + 2
429 + ),
430 + { force: true }
431 + );
432 +});
433 +
434 +const printDetectedMaster = Effect.suspend(() =>
435 + Effect.flatMap(TerminalUI, ui =>
436 + ui.output(JSON.stringify({ master: detectMaster() }, null, 2), { force: true })
437 + )
438 +);
439 +
440 +const printDevModeDisabled = Effect.gen(function* () {
441 + const ui = yield* TerminalUI;
442 + yield* ui.log.error('Developer mode is off.');
443 + yield* ui.log.step('Run `composio dev --mode on` in an interactive terminal to enable it.');
444 +});
445 +
446 export const runWithConfig = Effect.gen(function* () {
447 const cliUserConfig = yield* ComposioCliUserConfig;
448 const visibility: CommandVisibility = {
@@ -506,23 +457,8 @@ export const runWithConfig = Effect.gen(function* () {
457 version,
458 });
459
509 - return (argv: ReadonlyArray<string>) => {
510 - const { argv: argvWithoutDangerouslyAllow, dangerouslyAllow } =
511 - normalizeDangerouslyAllowFlag(argv);
512 - const normalizedArgv = normalizeHiddenDebugFlags(
513 - normalizeListenStreamFlag(normalizeVersionShortFlag(argvWithoutDangerouslyAllow))
514 - );
460 + const routeRootCommand = (normalizedArgv: ReadonlyArray<string>, dangerouslyAllow: boolean) => {
461 const args = normalizedArgv.slice(2);
516 - const installSkillRequest = parseRootInstallSkillRequest(normalizedArgv);
517 - if (installSkillRequest) {
518 - if (installSkillRequest._tag === 'error') {
519 - return Effect.fail(new Error(installSkillRequest.message));
520 - }
521 - return installSkill({
522 - skillName: installSkillRequest.skillName,
523 - target: installSkillRequest.target,
524 - });
525 - }
462 if (isRootHelp(normalizedArgv)) {
463 return printRootHelp(visibility, parseHelpLevel(normalizedArgv[3]) ?? 'default');
464 }
@@ -531,75 +467,25 @@ export const runWithConfig = Effect.gen(function* () {
467 const helpLevel = parseHelpLevel(normalizedArgv[normalizedArgv.length - 1]) ?? 'default';
468 return printSubcommandHelp(subHelp, visibility, helpLevel);
469 }
534 - const nestedMismatch = findNestedSubcommandMismatch(normalizedArgv, rootCommand);
535 - if (nestedMismatch) {
536 - return Effect.fail(nestedMismatch);
537 - }
470 const parallelExecute = runParallelToolsExecuteFromArgv(normalizedArgv);
471 if (parallelExecute) {
472 return parallelExecute;
473 }
474 if (isGenerateGraph(normalizedArgv)) {
543 - return Effect.sync(() => {
544 - // eslint-disable-next-line no-restricted-syntax -- migrated with the seam-rules slice (PR 6 of this stack)
545 - process.stdout.write(`${JSON.stringify(renderCommandHintGraph(), null, 2)}\n`);
546 - });
475 + return printCommandHintGraph;
476 }
477 if (isDebugApiInfo(normalizedArgv)) {
549 - return Effect.gen(function* () {
550 - const ui = yield* TerminalUI;
551 - const confirmed = yield* ui.confirm(
552 - 'This will print your current CLI API key and scoped identifiers to stdout. Continue?',
553 - { defaultValue: false }
554 - );
555 - if (!confirmed) {
556 - return yield* Effect.fail(new Error('Aborted printing API credentials.'));
557 - }
558 - const ctx = yield* ComposioUserContext;
559 - const apiKey = Option.getOrUndefined(ctx.data.apiKey);
560 - if (!apiKey) {
561 - return yield* Effect.fail(new Error('No user API key found in the current CLI session.'));
562 - }
563 - const orgId = Option.getOrUndefined(ctx.data.orgId);
564 - const consumerProject = yield* resolveCommandProject({ mode: 'consumer' }).pipe(
565 - Effect.mapError(formatResolveCommandProjectError),
566 - Effect.option
567 - );
568 - return yield* Effect.sync(() => {
569 - // eslint-disable-next-line no-restricted-syntax -- migrated with the seam-rules slice (PR 6 of this stack)
570 - process.stdout.write(
571 - `${JSON.stringify(
572 - {
573 - apiKey,
574 - orgId: orgId ?? null,
575 - consumerUserId:
576 - Option.isSome(consumerProject) && consumerProject.value.projectType === 'CONSUMER'
577 - ? (consumerProject.value.consumerUserId ?? null)
578 - : null,
579 - },
580 - null,
581 - 2
582 - )}\n`
583 - );
584 - });
585 - });
478 + return printDebugApiInfo;
479 }
480 if (isDebugWhoIsMyMaster(normalizedArgv)) {
588 - return Effect.sync(() => {
589 - // eslint-disable-next-line no-restricted-syntax -- migrated with the seam-rules slice (PR 6 of this stack)
590 - process.stdout.write(`${JSON.stringify({ master: detectMaster() }, null, 2)}\n`);
591 - });
481 + return printDetectedMaster;
482 }
483 const executeHelpSlug = parseExecuteInputHelpSlug(normalizedArgv);
484 if (executeHelpSlug) {
485 return showToolsExecuteInputHelp(executeHelpSlug);
486 }
487 if (!visibility.isDevModeEnabled && args[0] === 'dev' && !isDevModeOnlyInvocation(args)) {
598 - return Effect.gen(function* () {
599 - const ui = yield* TerminalUI;
600 - yield* ui.log.error('Developer mode is off.');
601 - yield* ui.log.step('Run `composio dev --mode on` in an interactive terminal to enable it.');
602 - });
488 + return printDevModeDisabled;
489 }
490 if (isDangerousDevCommand(args)) {
491 return Effect.gen(function* () {
@@ -619,6 +505,31 @@ export const runWithConfig = Effect.gen(function* () {
505 return yield* run(normalizedArgv);
506 });
507 }
622 - return run(normalizedArgv);
508 + return preflightParse(rootCommand, normalizedArgv).pipe(
509 + Effect.matchEffect({
510 + onFailure: error =>
511 + ValidationError.isCommandMismatch(error)
512 + ? refineRootCommandMismatch(normalizedArgv, visibility, error)
513 + : run(normalizedArgv),
514 + onSuccess: () => run(normalizedArgv),
515 + })
516 + );
517 + };
518 +
519 + return (argv: ReadonlyArray<string>) => {
520 + const { argv: argvWithoutDangerouslyAllow, dangerouslyAllow } =
521 + normalizeDangerouslyAllowFlag(argv);
522 + const normalizedArgv = normalizeHiddenDebugFlags(
523 + normalizeListenStreamFlag(normalizeVersionShortFlag(argvWithoutDangerouslyAllow))
524 + );
525 +
526 + return parseRootInstallSkillRequest(normalizedArgv).pipe(
527 + Effect.flatMap(
528 + Option.match({
529 + onNone: () => routeRootCommand(normalizedArgv, dangerouslyAllow),
530 + onSome: installSkill,
531 + })
532 + )
533 + );
534 };
535 });
ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts
+15 -2
@@ -2,7 +2,7 @@ import { Args, Command, Options } from '@effect/cli';
2 import type { Composio } from '@composio/client';
3 import { isLocalToolSlug } from '@composio/cli-local-tools';
4 import util from 'node:util';
5 -import { Effect, Option, Either, Exit, Fiber, Cause } from 'effect';
5 +import { Effect, Option, Either, Exit, Fiber, Cause, HashSet } from 'effect';
6 import { encodingForModel } from 'js-tiktoken';
7 import { redact } from 'src/ui/redact';
8 import { parseJsonRecord } from 'src/utils/parse-json';
@@ -84,6 +84,15 @@ const accountOption = Options.text('account').pipe(
84 Options.optional
85 );
86
87 +export const TOOLS_EXECUTE_VALUE_OPTIONS = HashSet.make(
88 + '--data',
89 + '-d',
90 + '--file',
91 + '--account',
92 + '--user-id',
93 + '--project-name'
94 +);
95 +
96 const userId = Options.text('user-id').pipe(
97 Options.optional,
98 Options.withDescription('Developer-project user ID override')
@@ -458,7 +467,11 @@ const emitExecuteFailureTelemetry = (params: {
467 ? getToolExecuteValidationFailedEvent({
468 toolSlug: params.toolSlug,
469 args: params.args,
461 - error: new ToolInputValidationError(params.toolSlug, 'server', [message]),
470 + error: new ToolInputValidationError({
471 + toolSlug: params.toolSlug,
472 + schemaPath: 'server',
473 + issues: [message],
474 + }),
475 surface: params.surface,
476 projectMode: params.projectMode,
477 stage:
ts/packages/cli/src/services/tool-input-validation.ts
+172 -136
@@ -1,13 +1,15 @@
1 -// eslint-disable-next-line no-restricted-imports -- migrated with the seam-rules slice (PR 6 of this stack)
2 -import path from 'node:path';
3 -import { FileSystem } from '@effect/platform';
4 -import { Effect, Option } from 'effect';
5 -import { jsonSchemaToZodSchema } from '@composio/core';
1 +import { AutoCorrect, CliConfig } from '@effect/cli';
2 +import { FileSystem, Path } from '@effect/platform';
3 +import { Data, Effect, Option, ParseResult, Schema } from 'effect';
4 import { getLocalToolInputDefinition } from '@composio/cli-local-tools';
7 -import { z } from 'zod/v3';
5 +import {
6 + jsonSchemaToEffectSchema,
7 + type JsonSchemaValidationIssue,
8 +} from '@composio/json-schema-to-effect-schema';
9 +import { JsonRecordSchema } from 'src/effects/json';
10 import { setupCacheDir } from 'src/effects/setup-cache-dir';
11 import { ComposioToolkitsRepository, getLatestToolVersion } from 'src/services/composio-clients';
10 -import { isToolDebugEnabled } from 'src/services/runtime-debug-flags';
12 +import { logToolDebug } from 'src/services/runtime-debug-logger';
13 import { normalizeFileUploadSchema } from 'src/services/tool-file-uploads';
14 import { ComposioUserContext } from 'src/services/user-context';
15
@@ -18,22 +20,32 @@ type CachedToolInputDefinition = {
20 readonly inputSchema: Record<string, unknown>;
21 };
22
23 +const CachedToolInputDefinitionEnvelope = Schema.Struct({
24 + version: Schema.optional(Schema.Unknown),
25 + inputSchema: JsonRecordSchema,
26 +});
27 +const ObjectSchemaWithProperties = Schema.Struct({ properties: JsonRecordSchema });
28 +
29 +const decodeJsonObject = Schema.decodeUnknown(Schema.parseJson(JsonRecordSchema));
30 +const decodeCachedToolInputDefinitionEnvelope = Schema.decodeUnknownOption(
31 + CachedToolInputDefinitionEnvelope
32 +);
33 +const decodeObjectSchemaWithProperties = Schema.decodeUnknownOption(ObjectSchemaWithProperties);
34 +
35 const sanitizeToolSlug = (slug: string) => slug.replace(/[^A-Za-z0-9_.-]/g, '_');
36
23 -const toolDefinitionPath = (cacheDir: string, slug: string) =>
37 +const toolDefinitionPath = (path: Path.Path, cacheDir: string, slug: string) =>
38 path.join(cacheDir, TOOL_DEFINITIONS_DIR, `${sanitizeToolSlug(slug)}.json`);
39
26 -const ensureToolDefinitionsDir = (fs: FileSystem.FileSystem, cacheDir: string) =>
40 +const ensureToolDefinitionsDir = (fs: FileSystem.FileSystem, path: Path.Path, cacheDir: string) =>
41 fs.makeDirectory(path.join(cacheDir, TOOL_DEFINITIONS_DIR), { recursive: true });
42
43 const parseSchemaFile = (raw: string, schemaPath: string) =>
30 - Effect.try({
31 - try: () => JSON.parse(raw) as Record<string, unknown>,
32 - catch: () => new Error(`Cached tool schema at ${schemaPath} is not valid JSON.`),
33 - });
34 -
35 -const isRecord = (value: unknown): value is Record<string, unknown> =>
36 - typeof value === 'object' && value !== null && !Array.isArray(value);
44 + decodeJsonObject(raw).pipe(
45 + Effect.mapError(
46 + cause => new Error(`Cached tool schema at ${schemaPath} is not valid JSON.`, { cause })
47 + )
48 + );
49
50 const PLACEHOLDER_TOOL_VERSION = '00000000_00';
51
@@ -70,17 +82,12 @@ const resolveLatestAvailableVersion = (params: {
82 return params.toolkitLatestVersion;
83 };
84
73 -const toolDebugLog = (label: string, details: Record<string, unknown>) => {
74 - if (!isToolDebugEnabled()) return;
75 - console.error(`[tool-debug] ${JSON.stringify({ label, ...details })}`);
76 -};
77 -
85 const parseCachedToolDefinition = (parsed: Record<string, unknown>): CachedToolInputDefinition => {
79 - const inputSchema = parsed.inputSchema;
80 - if (isRecord(inputSchema)) {
86 + const envelope = decodeCachedToolInputDefinitionEnvelope(parsed);
87 + if (Option.isSome(envelope)) {
88 return {
82 - version: typeof parsed.version === 'string' ? parsed.version : null,
83 - inputSchema,
89 + version: typeof envelope.value.version === 'string' ? envelope.value.version : null,
90 + inputSchema: envelope.value.inputSchema,
91 };
92 }
93
@@ -104,14 +111,21 @@ const serializeCachedToolDefinition = (definition: CachedToolInputDefinition): s
111 export const getCachedToolInputDefinition = (slug: string) =>
112 Effect.gen(function* () {
113 const fs = yield* FileSystem.FileSystem;
114 + const path = yield* Path.Path;
115 const cacheDir = yield* setupCacheDir;
108 - const schemaPath = toolDefinitionPath(cacheDir, slug);
109 -
110 - if (!(yield* fs.exists(schemaPath))) {
116 + const schemaPath = toolDefinitionPath(path, cacheDir, slug);
117 +
118 + const raw = yield* fs
119 + .readFileString(schemaPath, 'utf8')
120 + .pipe(
121 + Effect.catchTag('SystemError', error =>
122 + error.reason === 'NotFound' ? Effect.succeed(null) : Effect.fail(error)
123 + )
124 + );
125 + if (raw === null) {
126 return null;
127 }
128
114 - const raw = yield* fs.readFileString(schemaPath, 'utf8');
129 const parsed = yield* parseSchemaFile(raw, schemaPath);
130 const cached = parseCachedToolDefinition(parsed);
131 return {
@@ -123,18 +137,24 @@ export const getCachedToolInputDefinition = (slug: string) =>
137
138 export const getToolDefinitionCachePath = (slug: string) =>
139 Effect.gen(function* () {
140 + const path = yield* Path.Path;
141 const cacheDir = yield* setupCacheDir;
127 - return toolDefinitionPath(cacheDir, slug);
142 + return toolDefinitionPath(path, cacheDir, slug);
143 });
144
145 export const invalidateToolInputDefinition = (slug: string) =>
146 Effect.gen(function* () {
147 const fs = yield* FileSystem.FileSystem;
148 + const path = yield* Path.Path;
149 const cacheDir = yield* setupCacheDir;
134 - const schemaPath = toolDefinitionPath(cacheDir, slug);
135 - if (yield* fs.exists(schemaPath)) {
136 - yield* fs.remove(schemaPath);
137 - }
150 + const schemaPath = toolDefinitionPath(path, cacheDir, slug);
151 + yield* fs
152 + .remove(schemaPath)
153 + .pipe(
154 + Effect.catchTag('SystemError', error =>
155 + error.reason === 'NotFound' ? Effect.void : Effect.fail(error)
156 + )
157 + );
158 });
159
160 const fetchResolvedLatestToolVersion = (
@@ -155,7 +175,7 @@ const fetchResolvedLatestToolVersion = (
175 orgId: params?.orgId,
176 projectId: params?.projectId,
177 });
158 - toolDebugLog('latest_tool_version', {
178 + yield* logToolDebug('latest_tool_version', {
179 slug,
180 orgId: params?.orgId,
181 projectId: params?.projectId,
@@ -170,11 +190,12 @@ const fetchAndCacheToolInputDefinition = (
190 ) =>
191 Effect.gen(function* () {
192 const fs = yield* FileSystem.FileSystem;
193 + const path = yield* Path.Path;
194 const repo = yield* ComposioToolkitsRepository;
195 const cacheDir = yield* setupCacheDir;
196 const localDefinition = getLocalToolInputDefinition(slug);
176 - const schemaPath = toolDefinitionPath(cacheDir, localDefinition?.finalSlug ?? slug);
177 - yield* ensureToolDefinitionsDir(fs, cacheDir);
197 + const schemaPath = toolDefinitionPath(path, cacheDir, localDefinition?.finalSlug ?? slug);
198 + yield* ensureToolDefinitionsDir(fs, path, cacheDir);
199
200 if (localDefinition) {
201 yield* fs.writeFileString(
@@ -191,21 +212,27 @@ const fetchAndCacheToolInputDefinition = (
212 };
213 }
214
194 - const tool = yield* repo.getToolDetailed(slug);
195 - toolDebugLog('tool_detail', {
215 + const [tool, latestVersion] = yield* Effect.all(
216 + [
217 + repo.getToolDetailed(slug),
218 + fetchResolvedLatestToolVersion(slug, params).pipe(
219 + Effect.catchAll(() => Effect.succeed(null))
220 + ),
221 + ],
222 + { concurrency: 2 }
223 + );
224 + yield* logToolDebug('tool_detail', {
225 slug,
226 tool,
227 });
199 - const schema = (tool.input_parameters ?? {}) as Record<string, unknown>;
228 + const schema = tool.input_parameters;
229 const version =
201 - (yield* fetchResolvedLatestToolVersion(slug, params).pipe(
202 - Effect.catchAll(() => Effect.succeed(null))
203 - )) ??
230 + latestVersion ??
231 resolveLatestAvailableVersion({
232 toolLatestVersion: selectLatestVersion(tool.available_versions),
233 toolkitLatestVersion: null,
234 });
208 - toolDebugLog('resolved_tool_version', {
235 + yield* logToolDebug('resolved_tool_version', {
236 slug,
237 resolvedVersion: version,
238 cachePath: schemaPath,
@@ -231,7 +258,7 @@ export const getOrFetchToolInputDefinition = (
258 return yield* fetchAndCacheToolInputDefinition(slug, params);
259 }
260
234 - const freshness = yield* refreshToolInputDefinitionIfVersionChanged(
261 + const freshness = yield* refreshAndFetchToolInputDefinitionIfVersionChanged(
262 slug,
263 cached.version,
264 params
@@ -240,6 +267,7 @@ export const getOrFetchToolInputDefinition = (
267 Effect.succeed({
268 isStale: false,
269 latestVersion: cached.version,
270 + definition: null,
271 skipped: false as const,
272 })
273 )
@@ -249,18 +277,20 @@ export const getOrFetchToolInputDefinition = (
277 return cached;
278 }
279
252 - const refreshed = yield* getCachedToolInputDefinition(slug);
253 - return refreshed ?? (yield* fetchAndCacheToolInputDefinition(slug, params));
280 + return freshness.definition ?? cached;
281 });
282
256 -export const refreshToolInputDefinitionIfVersionChanged = (
283 +// Returns the freshly fetched definition on the stale path so callers that
284 +// need it (getOrFetchToolInputDefinition) don't re-read the cache file that
285 +// fetchAndCacheToolInputDefinition just wrote.
286 +const refreshAndFetchToolInputDefinitionIfVersionChanged = (
287 slug: string,
288 cachedVersion: string | null,
289 params?: { readonly orgId?: string; readonly projectId?: string }
290 ) =>
291 Effect.gen(function* () {
292 const latestVersion = yield* fetchResolvedLatestToolVersion(slug, params);
263 - toolDebugLog('resolved_tool_version', {
293 + yield* logToolDebug('resolved_tool_version', {
294 slug,
295 mode: 'refresh',
296 cachedVersion,
@@ -269,65 +299,47 @@ export const refreshToolInputDefinitionIfVersionChanged = (
299 projectId: params?.projectId,
300 });
301 const isStale = latestVersion !== cachedVersion;
302 + const definition = isStale ? yield* fetchAndCacheToolInputDefinition(slug, params) : null;
303
273 - if (isStale) {
274 - yield* fetchAndCacheToolInputDefinition(slug, params);
275 - }
276 -
277 - return { isStale, latestVersion, skipped: false as const };
304 + return { isStale, latestVersion, definition, skipped: false as const };
305 });
306
280 -export class ToolInputValidationError extends Error {
281 - readonly _tag = 'ToolInputValidationError';
307 +export const refreshToolInputDefinitionIfVersionChanged = (
308 + slug: string,
309 + cachedVersion: string | null,
310 + params?: { readonly orgId?: string; readonly projectId?: string }
311 +) =>
312 + refreshAndFetchToolInputDefinitionIfVersionChanged(slug, cachedVersion, params).pipe(
313 + Effect.map(({ isStale, latestVersion, skipped }) => ({ isStale, latestVersion, skipped }))
314 + );
315
283 - constructor(
284 - readonly toolSlug: string,
285 - readonly schemaPath: string,
286 - readonly issues: ReadonlyArray<string>,
287 - options?: ErrorOptions
288 - ) {
289 - super(
290 - [
291 - `Input validation failed for ${toolSlug}.`,
292 - `Schema: ${schemaPath}`,
293 - ...issues.map(issue => `- ${issue}`),
294 - ].join('\n'),
295 - options
296 - );
316 +export class ToolInputValidationError extends Data.TaggedError('ToolInputValidationError')<{
317 + readonly toolSlug: string;
318 + readonly schemaPath: string;
319 + readonly issues: ReadonlyArray<string>;
320 + readonly cause?: unknown;
321 +}> {
322 + override get message(): string {
323 + return [
324 + `Input validation failed for ${this.toolSlug}.`,
325 + `Schema: ${this.schemaPath}`,
326 + ...this.issues.map(issue => `- ${issue}`),
327 + ].join('\n');
328 }
329 }
330
331 const getObjectSchemaProperties = (schema: Record<string, unknown>): ReadonlyArray<string> => {
301 - const properties = schema.properties;
302 - if (!properties || typeof properties !== 'object' || Array.isArray(properties)) {
303 - return [];
304 - }
305 -
306 - return Object.keys(properties as Record<string, unknown>);
332 + const objectSchema = decodeObjectSchemaWithProperties(schema);
333 + return Option.isSome(objectSchema) ? Object.keys(objectSchema.value.properties) : [];
334 };
335
336 const normalizeKey = (value: string) => value.toLowerCase().replace(/[^a-z0-9]/g, '');
337
311 -const levenshteinDistance = (left: string, right: string): number => {
312 - if (left === right) return 0;
313 - if (left.length === 0) return right.length;
314 - if (right.length === 0) return left.length;
315 -
316 - const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
317 - const current = new Array<number>(right.length + 1);
318 -
319 - for (let i = 0; i < left.length; i += 1) {
320 - current[0] = i + 1;
321 - for (let j = 0; j < right.length; j += 1) {
322 - const cost = left[i] === right[j] ? 0 : 1;
323 - current[j + 1] = Math.min(current[j]! + 1, previous[j + 1]! + 1, previous[j]! + cost);
324 - }
325 - for (let j = 0; j <= right.length; j += 1) {
326 - previous[j] = current[j]!;
327 - }
328 - }
338 +const schemaKeySuggestionConfig = CliConfig.defaultConfig;
339
330 - return previous[right.length]!;
340 +type SchemaKeyCandidate = {
341 + readonly key: string;
342 + readonly score: number;
343 };
344
345 const findClosestSchemaKey = (
@@ -335,32 +347,39 @@ const findClosestSchemaKey = (
347 allowedKeys: ReadonlyArray<string>
348 ): string | undefined => {
349 const normalizedUnknownKey = normalizeKey(unknownKey);
338 - const candidates = allowedKeys
339 - .map(key => ({
350 + if (!normalizedUnknownKey) {
351 + return undefined;
352 + }
353 +
354 + const closest = allowedKeys.reduce<SchemaKeyCandidate | undefined>((best, key) => {
355 + const normalizedKey = normalizeKey(key);
356 + const distance = AutoCorrect.levensteinDistance(
357 + normalizedUnknownKey,
358 + normalizedKey,
359 + schemaKeySuggestionConfig
360 + );
361 + const containsBonus =
362 + normalizedKey.includes(normalizedUnknownKey) || normalizedUnknownKey.includes(normalizedKey)
363 + ? -2
364 + : 0;
365 + const candidate = {
366 key,
341 - normalized: normalizeKey(key),
342 - }))
343 - .map(candidate => {
344 - const distance = levenshteinDistance(normalizedUnknownKey, candidate.normalized);
345 - const containsBonus =
346 - candidate.normalized.includes(normalizedUnknownKey) ||
347 - normalizedUnknownKey.includes(candidate.normalized)
348 - ? -2
349 - : 0;
350 - return {
351 - key: candidate.key,
352 - score: distance + containsBonus,
353 - };
354 - })
355 - .sort((left, right) => left.score - right.score);
367 + score: distance + containsBonus,
368 + };
369 +
370 + if (!best || candidate.score < best.score) {
371 + return candidate;
372 + }
373
357 - const best = candidates[0];
358 - if (!best) {
374 + return best;
375 + }, undefined);
376 +
377 + const threshold = Math.max(3, Math.ceil(normalizedUnknownKey.length * 0.6));
378 + if (!closest || closest.score > threshold) {
379 return undefined;
380 }
381
362 - const threshold = Math.max(3, Math.ceil(normalizedUnknownKey.length * 0.6));
363 - return best.score <= threshold ? best.key : undefined;
382 + return closest.key;
383 };
384
385 const formatUnknownKeyIssue = (
@@ -381,6 +400,27 @@ const formatUnknownKeyIssue = (
400 });
401 };
402
403 +const formatSchemaIssues = (
404 + schemaIssues: ReadonlyArray<JsonSchemaValidationIssue>,
405 + allowedKeys: ReadonlyArray<string>
406 +): ReadonlyArray<string> =>
407 + schemaIssues.flatMap(issue => {
408 + if (issue.code === 'unrecognized_keys' && issue.keys) {
409 + return formatUnknownKeyIssue(issue.keys, allowedKeys);
410 + }
411 +
412 + const location = issue.path.length > 0 ? issue.path.join('.') : '<root>';
413 + return [`${location}: ${issue.message}`];
414 + });
415 +
416 +const compileToolInputSchema = (
417 + jsonSchema: Record<string, unknown>,
418 + allowedKeys: ReadonlyArray<string>
419 +) =>
420 + jsonSchemaToEffectSchema(jsonSchema, {
421 + formatIssues: issues => formatSchemaIssues(issues, allowedKeys),
422 + });
423 +
424 export const validateToolInputArgumentsWithDefinition = (
425 slug: string,
426 args: Record<string, unknown>,
@@ -394,31 +434,27 @@ export const validateToolInputArgumentsWithDefinition = (
434 const allowedKeys = getObjectSchemaProperties(schema);
435 const normalizedSchema = normalizeFileUploadSchema(schema);
436
397 - const zodSchema = yield* Effect.try({
398 - try: () => jsonSchemaToZodSchema<z.ZodTypeAny>(normalizedSchema),
437 + const inputSchema = yield* Effect.try({
438 + try: () => compileToolInputSchema(normalizedSchema, allowedKeys),
439 catch: error =>
400 - new ToolInputValidationError(
401 - slug,
440 + new ToolInputValidationError({
441 + toolSlug: slug,
442 schemaPath,
403 - ['Could not compile the cached JSON schema into a Zod validator.'],
404 - { cause: error }
405 - ),
443 + issues: ['Could not compile the cached JSON schema into a validator.'],
444 + cause: error,
445 + }),
446 });
447
408 - const parsed = zodSchema.safeParse(args);
409 - if (parsed.success) {
410 - return { schemaPath, schema };
411 - }
412 -
413 - const issues = parsed.error.issues.flatMap(issue => {
414 - if (issue.code === 'unrecognized_keys') {
415 - return formatUnknownKeyIssue(issue.keys, allowedKeys);
416 - }
417 - const location = issue.path.length > 0 ? issue.path.join('.') : '<root>';
418 - return [`${location}: ${issue.message}`];
419 - });
448 + yield* Schema.decodeUnknown(inputSchema, { errors: 'all' })(args).pipe(
449 + Effect.mapError(error => {
450 + const issues = ParseResult.ArrayFormatter.formatErrorSync(error).map(
451 + issue => issue.message
452 + );
453 + return new ToolInputValidationError({ toolSlug: slug, schemaPath, issues, cause: error });
454 + })
455 + );
456
421 - return yield* Effect.fail(new ToolInputValidationError(slug, schemaPath, issues));
457 + return { schemaPath, schema };
458 });
459
460 export const validateToolInputArgumentsIfCached = (slug: string, args: Record<string, unknown>) =>
ts/packages/cli/src/services/tools-executor.ts
+2
@@ -20,6 +20,7 @@ import type { NodeOs } from 'src/services/node-os';
20 import type { NodeProcess } from 'src/services/node-process';
21 import type { ComposioUserContext } from 'src/services/user-context';
22 import type { ComposioToolkitsRepository } from 'src/services/composio-clients';
23 +import type { TerminalUI } from 'src/services/terminal-ui';
24 import { ComposioCliUserConfig } from 'src/services/cli-user-config';
25 import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
26
@@ -63,6 +64,7 @@ export interface ToolsExecutor {
64 | ComposioUserContext
65 | ComposioToolkitsRepository
66 | ComposioCliUserConfig
67 + | TerminalUI
68 >;
69 }
70
ts/packages/cli/test/src/analytics.events.test.ts
+5 -3
@@ -27,9 +27,11 @@ describe('CLI analytics execute failure events', () => {
27 });
28
29 it('marks cached-schema validation failures as fast_fail', () => {
30 - const error = new ToolInputValidationError('GMAIL_SEND_EMAIL', '/tmp/schema.json', [
31 - 'Unknown key "recipient"',
32 - ]);
30 + const error = new ToolInputValidationError({
31 + toolSlug: 'GMAIL_SEND_EMAIL',
32 + schemaPath: '/tmp/schema.json',
33 + issues: ['Unknown key "recipient"'],
34 + });
35
36 const event = getToolExecuteValidationFailedEvent({
37 toolSlug: 'GMAIL_SEND_EMAIL',
ts/packages/cli/test/src/commands/$default.cmd.test.ts
+1 -6
@@ -138,14 +138,9 @@ describe('CLI: composio', () => {
138 Effect.gen(function* () {
139 vi.stubEnv('CODEX_THREAD_ID', 'thread_123');
140 vi.stubEnv('CLAUDE_CODE_ENTRYPOINT', 'sdk-ts');
141 - // The debug command still writes to process.stdout until the
142 - // seam-rules PR of this stack routes it through TerminalUI.
143 - const write = vi
144 - .spyOn(process.stdout, 'write')
145 - .mockImplementation((() => true) as typeof process.stdout.write);
141
142 yield* cli(['debug', 'who-is-my-master']);
148 - const output = write.mock.calls.map(call => String(call[0])).join('\n');
143 + const output = (yield* MockConsole.getLines()).join('\n');
144
145 expect(output).toContain('"master": "codex"');
146 })
ts/packages/cli/test/src/commands/index.test.ts new
+36
@@ -0,0 +1,36 @@
1 +import { describe, expect, it } from 'vitest';
2 +import { parseExecuteInputHelpSlug } from 'src/commands';
3 +
4 +describe('execute input-help routing', () => {
5 + it('does not mistake value-taking option values for the slug', () => {
6 + expect(
7 + parseExecuteInputHelpSlug([
8 + 'bun',
9 + 'composio',
10 + 'execute',
11 + '--account',
12 + 'default',
13 + '--file',
14 + './input.txt',
15 + 'GMAIL_SEND_EMAIL',
16 + '--help',
17 + ])
18 + ).toBe('GMAIL_SEND_EMAIL');
19 + });
20 +
21 + it('does not treat the parallel flag as a value-taking option', () => {
22 + expect(
23 + parseExecuteInputHelpSlug([
24 + 'bun',
25 + 'composio',
26 + 'execute',
27 + '--parallel',
28 + 'GMAIL_SEND_EMAIL',
29 + '-d',
30 + '{}',
31 + 'GITHUB_CREATE_AN_ISSUE',
32 + '--help',
33 + ])
34 + ).toBe('GMAIL_SEND_EMAIL');
35 + });
36 +});
ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts
+76 -56
@@ -1,78 +1,98 @@
1 import { describe, expect, it } from '@effect/vitest';
2 +import { Effect, Option } from 'effect';
3 import { parseRootInstallSkillRequest } from 'src/commands';
4
5 describe('CLI: --install-skill', () => {
5 - it('parses the default skill name when only a target is provided', () => {
6 - expect(
7 - parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'claude'])
8 - ).toEqual({
9 - _tag: 'parsed',
10 - target: 'claude',
11 - });
12 - });
6 + it.effect('parses the default skill name when only a target is provided', () =>
7 + Effect.gen(function* () {
8 + const request = yield* parseRootInstallSkillRequest([
9 + 'node',
10 + 'composio',
11 + '--install-skill',
12 + 'claude',
13 + ]);
14 + expect(Option.getOrUndefined(request)).toEqual({ target: 'claude' });
15 + })
16 + );
17
14 - it('parses an explicit skill name and target', () => {
15 - expect(
16 - parseRootInstallSkillRequest([
18 + it.effect('parses an explicit skill name and target', () =>
19 + Effect.gen(function* () {
20 + const request = yield* parseRootInstallSkillRequest([
21 'node',
22 'composio',
23 '--install-skill',
24 'composio-cli',
25 'codex',
22 - ])
23 - ).toEqual({
24 - _tag: 'parsed',
25 - skillName: 'composio-cli',
26 - target: 'codex',
27 - });
28 - });
26 + ]);
27 + expect(Option.getOrUndefined(request)).toEqual({
28 + skillName: 'composio-cli',
29 + target: 'codex',
30 + });
31 + })
32 + );
33
30 - it('accepts the legacy --instal-skill alias', () => {
31 - expect(
32 - parseRootInstallSkillRequest(['node', 'composio', '--instal-skill', 'openclaw'])
33 - ).toEqual({
34 - _tag: 'parsed',
35 - target: 'openclaw',
36 - });
37 - });
34 + it.effect('accepts the legacy --instal-skill alias', () =>
35 + Effect.gen(function* () {
36 + const request = yield* parseRootInstallSkillRequest([
37 + 'node',
38 + 'composio',
39 + '--instal-skill',
40 + 'openclaw',
41 + ]);
42 + expect(Option.getOrUndefined(request)).toEqual({
43 + target: 'openclaw',
44 + });
45 + })
46 + );
47
39 - it('accepts the root flag after leading global options', () => {
40 - expect(
41 - parseRootInstallSkillRequest([
48 + it.effect('accepts the root flag after leading global options', () =>
49 + Effect.gen(function* () {
50 + const request = yield* parseRootInstallSkillRequest([
51 'node',
52 'composio',
53 '--log-level',
54 'debug',
55 '--install-skill',
56 'claude',
48 - ])
49 - ).toEqual({
50 - _tag: 'parsed',
51 - target: 'claude',
52 - });
53 - });
57 + ]);
58 + expect(Option.getOrUndefined(request)).toEqual({
59 + target: 'claude',
60 + });
61 + })
62 + );
63
55 - it('does not intercept subcommand flags after a positional command', () => {
56 - expect(
57 - parseRootInstallSkillRequest(['node', 'composio', 'upgrade', '--install-skill', 'claude'])
58 - ).toBeUndefined();
59 - });
64 + it.effect('does not intercept subcommand flags after a positional command', () =>
65 + Effect.gen(function* () {
66 + const request = yield* parseRootInstallSkillRequest([
67 + 'node',
68 + 'composio',
69 + 'upgrade',
70 + '--install-skill',
71 + 'claude',
72 + ]);
73 + expect(Option.isNone(request)).toBe(true);
74 + })
75 + );
76
61 - it('returns a helpful error when the target is missing', () => {
62 - expect(parseRootInstallSkillRequest(['node', 'composio', '--install-skill'])).toEqual({
63 - _tag: 'error',
64 - message:
65 - 'Missing target for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>',
66 - });
67 - });
77 + it.effect('returns a helpful error when the target is missing', () =>
78 + Effect.gen(function* () {
79 + const error = yield* Effect.flip(
80 + parseRootInstallSkillRequest(['node', 'composio', '--install-skill'])
81 + );
82 + expect(error.message).toBe(
83 + 'Missing target for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>'
84 + );
85 + })
86 + );
87
69 - it('returns a helpful error for invalid targets', () => {
70 - expect(parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'cursor'])).toEqual(
71 - {
72 - _tag: 'error',
73 - message:
74 - 'Invalid target for --install-skill. Expected one of: claude, codex, openclaw.',
75 - }
76 - );
77 - });
88 + it.effect('returns a helpful error for invalid targets', () =>
89 + Effect.gen(function* () {
90 + const error = yield* Effect.flip(
91 + parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'cursor'])
92 + );
93 + expect(error.message).toBe(
94 + 'Invalid target for --install-skill. Expected one of: claude, codex, openclaw.'
95 + );
96 + })
97 + );
98 });
ts/packages/cli/test/src/services/tool-input-validation.test.ts new
+164
@@ -0,0 +1,164 @@
1 +import fs from 'node:fs';
2 +import path from 'node:path';
3 +import { describe, expect, it } from '@effect/vitest';
4 +import { BunFileSystem, BunPath } from '@effect/platform-bun';
5 +import { ConfigProvider, Effect, Layer } from 'effect';
6 +import * as tempy from 'tempy';
7 +import {
8 + getCachedToolInputDefinition,
9 + ToolInputValidationError,
10 + validateToolInputArgumentsWithDefinition,
11 +} from 'src/services/tool-input-validation';
12 +import { defaultNodeOs, NodeOs } from 'src/services/node-os';
13 +
14 +const definition = {
15 + schemaPath: '/tmp/GMAIL_SEND_EMAIL.json',
16 + schema: {
17 + type: 'object',
18 + additionalProperties: false,
19 + required: ['recipient_email'],
20 + properties: {
21 + recipient_email: { type: 'string' },
22 + subject: { type: 'string' },
23 + body: { type: 'string' },
24 + },
25 + },
26 +} as const;
27 +
28 +describe('tool input validation', () => {
29 + it.effect('validates tool input through Effect Schema', () =>
30 + Effect.gen(function* () {
31 + const result = yield* validateToolInputArgumentsWithDefinition(
32 + 'GMAIL_SEND_EMAIL',
33 + { recipient_email: 'karan@composio.dev', subject: 'Hello' },
34 + definition
35 + );
36 +
37 + expect(result).toEqual(definition);
38 + })
39 + );
40 +
41 + it.effect('suggests a schema key using the CLI autocorrect distance', () =>
42 + Effect.gen(function* () {
43 + const error = yield* validateToolInputArgumentsWithDefinition(
44 + 'GMAIL_SEND_EMAIL',
45 + { recipent_email: 'karan@composio.dev' },
46 + definition
47 + ).pipe(Effect.flip);
48 +
49 + expect(error).toBeInstanceOf(ToolInputValidationError);
50 + expect(error.issues).toContain(
51 + '<root>: Unknown key "recipent_email". Use "recipient_email" instead. Allowed top-level keys: recipient_email, subject, body'
52 + );
53 + })
54 + );
55 +
56 + it.effect('keeps prefix-based suggestions without guessing unrelated keys', () =>
57 + Effect.gen(function* () {
58 + const prefixError = yield* validateToolInputArgumentsWithDefinition(
59 + 'GMAIL_SEND_EMAIL',
60 + { recipient: 'karan@composio.dev' },
61 + definition
62 + ).pipe(Effect.flip);
63 + const unrelatedError = yield* validateToolInputArgumentsWithDefinition(
64 + 'GMAIL_SEND_EMAIL',
65 + { account: 'karan@composio.dev' },
66 + definition
67 + ).pipe(Effect.flip);
68 +
69 + expect(prefixError.issues).toContain(
70 + '<root>: Unknown key "recipient". Use "recipient_email" instead. Allowed top-level keys: recipient_email, subject, body'
71 + );
72 + expect(unrelatedError.issues).toContain(
73 + '<root>: Unknown key "account". Allowed top-level keys: recipient_email, subject, body'
74 + );
75 + })
76 + );
77 +
78 + it.effect(
79 + 'keeps length-aware typo suggestions without letting containment bypass the limit',
80 + () =>
81 + Effect.gen(function* () {
82 + const longTypoError = yield* validateToolInputArgumentsWithDefinition(
83 + 'GMAIL_SEND_EMAIL',
84 + { recpnt_email: 'karan@composio.dev' },
85 + definition
86 + ).pipe(Effect.flip);
87 + const containmentError = yield* validateToolInputArgumentsWithDefinition(
88 + 'TEST_TOOL',
89 + { to: true },
90 + {
91 + schemaPath: '/tmp/TEST_TOOL.json',
92 + schema: {
93 + type: 'object',
94 + additionalProperties: false,
95 + properties: { auto_reply: { type: 'boolean' } },
96 + },
97 + }
98 + ).pipe(Effect.flip);
99 +
100 + expect(longTypoError.issues).toContain(
101 + '<root>: Unknown key "recpnt_email". Use "recipient_email" instead. Allowed top-level keys: recipient_email, subject, body'
102 + );
103 + expect(containmentError.issues).toContain(
104 + '<root>: Unknown key "to". Allowed top-level keys: auto_reply'
105 + );
106 + })
107 + );
108 +
109 + it.effect('reads legacy bare-schema cache entries through the Effect decoder', () => {
110 + const cacheDir = tempy.temporaryDirectory();
111 + const schemaPath = path.join(cacheDir, 'tool_definitions', 'GMAIL_SEND_EMAIL.json');
112 + fs.mkdirSync(path.dirname(schemaPath), { recursive: true });
113 + fs.writeFileSync(schemaPath, JSON.stringify(definition.schema));
114 +
115 + return Effect.gen(function* () {
116 + const cached = yield* getCachedToolInputDefinition('GMAIL_SEND_EMAIL');
117 +
118 + expect(cached).toEqual({
119 + schemaPath,
120 + schema: definition.schema,
121 + version: null,
122 + });
123 + }).pipe(
124 + Effect.provide(
125 + Layer.mergeAll(
126 + BunFileSystem.layer,
127 + BunPath.layer,
128 + Layer.succeed(NodeOs, defaultNodeOs({ homedir: cacheDir }))
129 + )
130 + ),
131 + Effect.withConfigProvider(
132 + ConfigProvider.fromMap(new Map([['CACHE_DIR', cacheDir]] satisfies Array<[string, string]>))
133 + )
134 + );
135 + });
136 +
137 + it.effect('preserves field paths in validation errors', () =>
138 + Effect.gen(function* () {
139 + const error = yield* validateToolInputArgumentsWithDefinition(
140 + 'GMAIL_SEND_EMAIL',
141 + { recipient_email: 42 },
142 + definition
143 + ).pipe(Effect.flip);
144 +
145 + expect(error.issues.some(issue => issue.startsWith('recipient_email:'))).toBe(true);
146 + })
147 + );
148 +
149 + it.effect('preserves all field and unknown-key failures in one validation pass', () =>
150 + Effect.gen(function* () {
151 + const error = yield* validateToolInputArgumentsWithDefinition(
152 + 'GMAIL_SEND_EMAIL',
153 + { recipient_email: 42, subject: false, recipent_email: 'karan@composio.dev' },
154 + definition
155 + ).pipe(Effect.flip);
156 +
157 + expect(error.issues.some(issue => issue.startsWith('recipient_email:'))).toBe(true);
158 + expect(error.issues.some(issue => issue.startsWith('subject:'))).toBe(true);
159 + expect(error.issues).toContain(
160 + '<root>: Unknown key "recipent_email". Use "recipient_email" instead. Allowed top-level keys: recipient_email, subject, body'
161 + );
162 + })
163 + );
164 +});
ts/packages/cli/vitest.config.ts
+5
@@ -4,6 +4,7 @@ import path from 'node:path';
4 const __dirname = path.resolve(path.dirname(new URL(import.meta.url).pathname));
5 const coreDir = path.resolve(__dirname, '../core');
6 const tsBuildersDir = path.resolve(__dirname, '../ts-builders');
7 +const jsonSchemaToEffectSchemaDir = path.resolve(__dirname, '../json-schema-to-effect-schema');
8 const jsonSchemaToZodDir = path.resolve(__dirname, '../json-schema-to-zod');
9 const cliLocalToolsDir = path.resolve(__dirname, '../cli-local-tools');
10
@@ -16,6 +17,10 @@ export default defineConfig({
17 '@composio/core/experimental': path.join(coreDir, 'src/experimental/index.ts'),
18 '@composio/core': path.join(coreDir, 'src/index.ts'),
19 '@composio/ts-builders': path.join(tsBuildersDir, 'src/index.ts'),
20 + '@composio/json-schema-to-effect-schema': path.join(
21 + jsonSchemaToEffectSchemaDir,
22 + 'src/index.ts'
23 + ),
24 '@composio/json-schema-to-zod': path.join(jsonSchemaToZodDir, 'src/index.ts'),
25 '@composio/cli-local-tools': path.join(cliLocalToolsDir, 'src/index.ts'),
26 'effect-errors/*': path.resolve(__dirname, './src/effect-errors'),
ts/packages/json-schema-to-effect-schema/README.md new
+7
@@ -0,0 +1,7 @@
1 +# `@composio/json-schema-to-effect-schema`
2 +
3 +Internal, eval-free JSON Schema validation exposed through Effect Schema.
4 +
5 +The package uses `@cfworker/json-schema`, an interpreter designed for runtimes where dynamic code
6 +generation is unavailable. It also normalizes the OpenAPI and Composio schema extensions accepted by
7 +the previous Zod-backed tool-input validator.
ts/packages/json-schema-to-effect-schema/package.json new
+46
@@ -0,0 +1,46 @@
1 +{
2 + "name": "@composio/json-schema-to-effect-schema",
3 + "version": "0.1.0",
4 + "description": "Eval-free JSON Schema validation exposed as Effect Schema.",
5 + "main": "src/index.ts",
6 + "private": true,
7 + "type": "module",
8 + "repository": {
9 + "type": "git",
10 + "url": "https://github.com/ComposioHQ/composio.git",
11 + "directory": "ts/packages/json-schema-to-effect-schema"
12 + },
13 + "exports": {
14 + ".": {
15 + "types": "./dist/index.d.mts",
16 + "default": "./dist/index.mjs"
17 + }
18 + },
19 + "files": [
20 + "README.md",
21 + "dist"
22 + ],
23 + "scripts": {
24 + "clean": "git clean -xdf node_modules",
25 + "build": "tsdown",
26 + "test": "vitest run",
27 + "typecheck:src": "pnpm exec tsgo --noEmit -p ./tsconfig.src.json",
28 + "typecheck:test": "pnpm exec tsgo --noEmit -p ./tsconfig.test.json",
29 + "typecheck": "pnpm run typecheck:src && pnpm run typecheck:test",
30 + "typecheck:src:tsc": "tsc --noEmit -p ./tsconfig.src.json",
31 + "typecheck:test:tsc": "tsc --noEmit -p ./tsconfig.test.json",
32 + "typecheck:tsc": "pnpm run typecheck:src:tsc && pnpm run typecheck:test:tsc"
33 + },
34 + "license": "ISC",
35 + "dependencies": {
36 + "@cfworker/json-schema": "^4.1.1",
37 + "effect": "catalog:"
38 + },
39 + "devDependencies": {
40 + "@composio/json-schema-to-zod": "workspace:*",
41 + "tsdown": "catalog:",
42 + "typescript": "catalog:",
43 + "vitest": "catalog:",
44 + "zod": "catalog:"
45 + }
46 +}
ts/packages/json-schema-to-effect-schema/src/index.ts new
+362
@@ -0,0 +1,362 @@
1 +import { Validator } from '@cfworker/json-schema';
2 +import type { OutputUnit, Schema as InterpreterSchema, SchemaDraft } from '@cfworker/json-schema';
3 +import { Either, ParseResult, Schema } from 'effect';
4 +
5 +export type JsonSchemaValidationIssue = {
6 + readonly code: string;
7 + readonly keys?: ReadonlyArray<string>;
8 + readonly message: string;
9 + readonly path: ReadonlyArray<PropertyKey>;
10 +};
11 +
12 +export type JsonSchemaToEffectSchemaOptions = {
13 + readonly draft?: SchemaDraft;
14 + readonly formatIssues?: (
15 + issues: ReadonlyArray<JsonSchemaValidationIssue>
16 + ) => ReadonlyArray<string>;
17 +};
18 +
19 +type JsonObject = Record<string, unknown>;
20 +
21 +const BASE64_PATTERN = '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$';
22 +
23 +const schemaMapKeywords = new Set([
24 + '$defs',
25 + 'definitions',
26 + 'dependentSchemas',
27 + 'patternProperties',
28 + 'properties',
29 +]);
30 +
31 +const schemaArrayKeywords = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
32 +
33 +const schemaValueKeywords = new Set([
34 + 'additionalItems',
35 + 'additionalProperties',
36 + 'contains',
37 + 'else',
38 + 'if',
39 + 'items',
40 + 'not',
41 + 'propertyNames',
42 + 'then',
43 + 'unevaluatedItems',
44 + 'unevaluatedProperties',
45 +]);
46 +
47 +const isJsonObject = (value: unknown): value is JsonObject =>
48 + typeof value === 'object' && value !== null && !Array.isArray(value);
49 +
50 +const isObjectSchema = (schema: JsonObject): boolean =>
51 + schema.type === 'object' ||
52 + 'properties' in schema ||
53 + 'patternProperties' in schema ||
54 + 'additionalProperties' in schema;
55 +
56 +const appendAllOf = (schema: JsonObject, constraint: JsonObject): void => {
57 + const current = schema.allOf;
58 + schema.allOf = Array.isArray(current) ? [...current, constraint] : [constraint];
59 +};
60 +
61 +const normalizeBounds = (schema: JsonObject): void => {
62 + const type = schema.type;
63 + const minimum = schema.min;
64 + const maximum = schema.max;
65 +
66 + if (typeof minimum === 'number') {
67 + if ((type === 'number' || type === 'integer') && schema.minimum === undefined) {
68 + schema.minimum = minimum;
69 + } else if (type === 'string' && schema.minLength === undefined) {
70 + schema.minLength = minimum;
71 + } else if (type === 'array' && schema.minItems === undefined) {
72 + schema.minItems = minimum;
73 + }
74 + }
75 +
76 + if (typeof maximum === 'number') {
77 + if ((type === 'number' || type === 'integer') && schema.maximum === undefined) {
78 + schema.maximum = maximum;
79 + } else if (type === 'string' && schema.maxLength === undefined) {
80 + schema.maxLength = maximum;
81 + } else if (type === 'array' && schema.maxItems === undefined) {
82 + schema.maxItems = maximum;
83 + }
84 + }
85 +};
86 +
87 +const normalizeFormats = (schema: JsonObject): void => {
88 + if (schema.type === 'number' && schema.format === 'int64') {
89 + schema.type = 'integer';
90 + }
91 +
92 + if (schema.type !== 'string') {
93 + return;
94 + }
95 +
96 + if (schema.format === 'binary' || schema.contentEncoding !== undefined) {
97 + if (schema.pattern === undefined) {
98 + schema.pattern = BASE64_PATTERN;
99 + } else {
100 + appendAllOf(schema, { pattern: BASE64_PATTERN });
101 + }
102 + }
103 +
104 + if (schema.format === 'ip') {
105 + delete schema.format;
106 + appendAllOf(schema, {
107 + anyOf: [{ format: 'ipv4' }, { format: 'ipv6' }],
108 + });
109 + }
110 +};
111 +
112 +const normalizeNullable = (schema: JsonObject): JsonObject => {
113 + if (schema.nullable !== true) {
114 + return schema;
115 + }
116 +
117 + delete schema.nullable;
118 + if (typeof schema.type === 'string') {
119 + schema.type = [schema.type, 'null'];
120 + return schema;
121 + }
122 + if (Array.isArray(schema.type)) {
123 + schema.type = schema.type.includes('null') ? schema.type : [...schema.type, 'null'];
124 + return schema;
125 + }
126 +
127 + return { anyOf: [schema, { type: 'null' }] };
128 +};
129 +
130 +const normalizeSchemaNode = (
131 + value: unknown,
132 + seen: WeakMap<object, InterpreterSchema | boolean>
133 +): InterpreterSchema | boolean => {
134 + if (typeof value === 'boolean') {
135 + return value;
136 + }
137 + if (!isJsonObject(value)) {
138 + return true;
139 + }
140 +
141 + const existing = seen.get(value);
142 + if (existing) {
143 + return existing;
144 + }
145 +
146 + const normalized: JsonObject = {};
147 + seen.set(value, normalized as InterpreterSchema);
148 +
149 + for (const [key, child] of Object.entries(value)) {
150 + if (schemaMapKeywords.has(key) && isJsonObject(child)) {
151 + normalized[key] = Object.fromEntries(
152 + Object.entries(child).map(([name, nested]) => [name, normalizeSchemaNode(nested, seen)])
153 + );
154 + } else if (schemaArrayKeywords.has(key) && Array.isArray(child)) {
155 + normalized[key] = child.map(nested => normalizeSchemaNode(nested, seen));
156 + } else if (schemaValueKeywords.has(key)) {
157 + normalized[key] = Array.isArray(child)
158 + ? child.map(nested => normalizeSchemaNode(nested, seen))
159 + : normalizeSchemaNode(child, seen);
160 + } else {
161 + normalized[key] = child;
162 + }
163 + }
164 +
165 + if (isObjectSchema(normalized) && normalized.additionalProperties === undefined) {
166 + normalized.additionalProperties = false;
167 + }
168 +
169 + normalizeBounds(normalized);
170 + normalizeFormats(normalized);
171 + const withNullable = normalizeNullable(normalized);
172 + seen.set(value, withNullable as InterpreterSchema);
173 + return withNullable as InterpreterSchema;
174 +};
175 +
176 +const normalizeJsonSchema = (schema: JsonObject): InterpreterSchema =>
177 + normalizeSchemaNode(schema, new WeakMap()) as InterpreterSchema;
178 +
179 +const decodePointer = (pointer: string): ReadonlyArray<string> => {
180 + if (pointer === '#' || pointer === '') {
181 + return [];
182 + }
183 +
184 + const fragment = pointer.startsWith('#') ? pointer.slice(1) : pointer;
185 + return fragment
186 + .split('/')
187 + .slice(1)
188 + .map(part => part.replace(/~1/g, '/').replace(/~0/g, '~'));
189 +};
190 +
191 +const encodePointerPart = (part: string): string => part.replace(/~/g, '~0').replace(/\//g, '~1');
192 +
193 +const instancePath = (pointer: string): ReadonlyArray<PropertyKey> =>
194 + decodePointer(pointer).map(part => (/^(?:0|[1-9]\d*)$/.test(part) ? Number(part) : part));
195 +
196 +const valueAtPointer = (root: unknown, pointer: string): unknown =>
197 + decodePointer(pointer).reduce<unknown>((current, part) => {
198 + if (isJsonObject(current)) {
199 + return current[part];
200 + }
201 + if (Array.isArray(current) && /^(?:0|[1-9]\d*)$/.test(part)) {
202 + return current[Number(part)];
203 + }
204 + return undefined;
205 + }, root);
206 +
207 +const parentSchemaAtKeyword = (
208 + schema: InterpreterSchema,
209 + keywordLocation: string
210 +): JsonObject | null => {
211 + const parts = decodePointer(keywordLocation);
212 + const parentPointer = `#/${parts.slice(0, -1).map(encodePointerPart).join('/')}`;
213 + const parent = valueAtPointer(schema, parts.length === 1 ? '#' : parentPointer);
214 + return isJsonObject(parent) ? parent : null;
215 +};
216 +
217 +const propertyNameFromError = (error: OutputUnit): string | undefined =>
218 + error.error.match(/^Property "([^"]+)"/)?.[1];
219 +
220 +const requiredNameFromError = (error: OutputUnit): string | undefined =>
221 + error.error.match(/required property "([^"]+)"/)?.[1];
222 +
223 +const propertyIsDeclared = (parent: JsonObject | null, key: string): boolean => {
224 + if (!parent) {
225 + return false;
226 + }
227 + if (isJsonObject(parent.properties) && key in parent.properties) {
228 + return true;
229 + }
230 + if (!isJsonObject(parent.patternProperties)) {
231 + return false;
232 + }
233 +
234 + return Object.keys(parent.patternProperties).some(pattern =>
235 + Either.getOrElse(
236 + Either.try(() => new RegExp(pattern, 'u').test(key)),
237 + () => false
238 + )
239 + );
240 +};
241 +
242 +const hasSpecificChildError = (errors: ReadonlyArray<OutputUnit>, error: OutputUnit): boolean =>
243 + errors.some(
244 + candidate =>
245 + candidate !== error &&
246 + candidate.instanceLocation.startsWith(`${error.instanceLocation}/`) &&
247 + candidate.keyword !== 'additionalProperties'
248 + );
249 +
250 +const mapValidationErrors = (
251 + errors: ReadonlyArray<OutputUnit>,
252 + schema: InterpreterSchema
253 +): ReadonlyArray<JsonSchemaValidationIssue> => {
254 + const ignored = new Set<OutputUnit>();
255 + const unknownByLocation = new Map<string, Array<string>>();
256 +
257 + for (const [index, error] of errors.entries()) {
258 + if (error.keyword !== 'additionalProperties') {
259 + continue;
260 + }
261 + const key = propertyNameFromError(error);
262 + if (!key) {
263 + continue;
264 + }
265 + const parent = parentSchemaAtKeyword(schema, error.keywordLocation);
266 + const additionalProperties = valueAtPointer(schema, error.keywordLocation);
267 + if (additionalProperties === false) {
268 + const child = errors[index + 1];
269 + const childLocation = `${error.instanceLocation}/${encodePointerPart(key)}`;
270 + if (child?.keyword === 'false' && child.instanceLocation === childLocation) {
271 + ignored.add(child);
272 + }
273 + }
274 + if (propertyIsDeclared(parent, key)) {
275 + ignored.add(error);
276 + continue;
277 + }
278 +
279 + if (additionalProperties === false) {
280 + const keys = unknownByLocation.get(error.instanceLocation) ?? [];
281 + keys.push(key);
282 + unknownByLocation.set(error.instanceLocation, keys);
283 + ignored.add(error);
284 + } else if (hasSpecificChildError(errors, error)) {
285 + ignored.add(error);
286 + }
287 + }
288 +
289 + const issues: Array<JsonSchemaValidationIssue> = [];
290 + for (const [location, keys] of unknownByLocation) {
291 + issues.push({
292 + code: 'unrecognized_keys',
293 + keys,
294 + message: `Unknown key${keys.length === 1 ? '' : 's'}: ${keys.join(', ')}`,
295 + path: instancePath(location),
296 + });
297 + }
298 +
299 + for (const error of errors) {
300 + if (ignored.has(error)) {
301 + continue;
302 + }
303 + if (
304 + (error.keyword === 'properties' ||
305 + error.keyword === 'patternProperties' ||
306 + error.keyword === '$ref') &&
307 + hasSpecificChildError(errors, error)
308 + ) {
309 + continue;
310 + }
311 +
312 + const path = [...instancePath(error.instanceLocation)];
313 + const requiredName = error.keyword === 'required' ? requiredNameFromError(error) : undefined;
314 + if (requiredName) {
315 + path.push(requiredName);
316 + }
317 + issues.push({ code: error.keyword, message: error.error, path });
318 + }
319 +
320 + return issues;
321 +};
322 +
323 +const defaultFormatIssues = (
324 + issues: ReadonlyArray<JsonSchemaValidationIssue>
325 +): ReadonlyArray<string> =>
326 + issues.map(issue => {
327 + const location = issue.path.length > 0 ? issue.path.join('.') : '<root>';
328 + return `${location}: ${issue.message}`;
329 + });
330 +
331 +export const jsonSchemaToEffectSchema = (
332 + jsonSchema: JsonObject,
333 + options: JsonSchemaToEffectSchemaOptions = {}
334 +) => {
335 + const normalizedSchema = normalizeJsonSchema(jsonSchema);
336 + const validator = new Validator(normalizedSchema, options.draft ?? '7', false);
337 + const formatIssues = options.formatIssues ?? defaultFormatIssues;
338 +
339 + return Schema.declare([Schema.Unknown], {
340 + decode: () => (input, _parseOptions, ast) => {
341 + const validation = Either.try(() => validator.validate(input));
342 + if (Either.isLeft(validation)) {
343 + return ParseResult.fail(
344 + new ParseResult.Type(ast, input, `JSON Schema validation failed: ${validation.left}`)
345 + );
346 + }
347 + if (validation.right.valid) {
348 + return ParseResult.succeed(input);
349 + }
350 +
351 + const issues = mapValidationErrors(validation.right.errors, normalizedSchema);
352 + const messages = formatIssues(issues);
353 + const [first, ...rest] = messages.map(message => new ParseResult.Type(ast, input, message));
354 + return ParseResult.fail(
355 + first
356 + ? new ParseResult.Composite(ast, input, [first, ...rest])
357 + : new ParseResult.Type(ast, input, 'Input does not match the JSON schema.')
358 + );
359 + },
360 + encode: () => input => ParseResult.succeed(input),
361 + });
362 +};
ts/packages/json-schema-to-effect-schema/test/json-schema-to-effect-schema.test.ts new
+118
@@ -0,0 +1,118 @@
1 +import { jsonSchemaToZod } from '@composio/json-schema-to-zod';
2 +import { Either, Schema } from 'effect';
3 +import { describe, expect, it } from 'vitest';
4 +import { jsonSchemaToEffectSchema, type JsonSchemaValidationIssue } from '../src/index';
5 +
6 +type JsonSchema = Record<string, unknown>;
7 +
8 +const effectAccepts = (schema: JsonSchema, input: unknown): boolean =>
9 + Either.isRight(
10 + Schema.decodeUnknownEither(jsonSchemaToEffectSchema(schema), { errors: 'all' })(input)
11 + );
12 +
13 +const zodAccepts = (schema: JsonSchema, input: unknown): boolean =>
14 + jsonSchemaToZod(schema).safeParse(input).success;
15 +
16 +const expectParity = (schema: JsonSchema, input: unknown, expected: boolean): void => {
17 + expect(effectAccepts(schema, input)).toBe(expected);
18 + expect(zodAccepts(schema, input)).toBe(expected);
19 +};
20 +
21 +describe('jsonSchemaToEffectSchema', () => {
22 + it('matches the previous validator for object, required, and additional-property checks', () => {
23 + const strictSchema = {
24 + type: 'object',
25 + required: ['name'],
26 + properties: {
27 + name: { type: 'string' },
28 + metadata: {
29 + type: 'object',
30 + properties: { count: { type: 'integer' } },
31 + },
32 + },
33 + } satisfies JsonSchema;
34 +
35 + expectParity(strictSchema, { name: 'Ada', metadata: { count: 1 } }, true);
36 + expectParity(strictSchema, { name: 'Ada', extra: true }, false);
37 + expectParity(strictSchema, { name: 'Ada', metadata: { count: 1.5 } }, false);
38 + expectParity(strictSchema, { metadata: { count: 1 } }, false);
39 +
40 + expectParity({ type: 'object', additionalProperties: true }, { arbitrary: 'value' }, true);
41 + });
42 +
43 + it('normalizes the OpenAPI and Composio extensions accepted by the previous validator', () => {
44 + expectParity({ type: 'string', nullable: true }, null, true);
45 + expectParity({ type: 'string', nullable: true }, 42, false);
46 + expectParity({ type: 'string', min: 2, max: 4 }, 'abc', true);
47 + expectParity({ type: 'string', min: 2, max: 4 }, 'a', false);
48 + expectParity({ type: 'array', min: 1, max: 2, items: { type: 'number' } }, [1], true);
49 + expectParity({ type: 'array', min: 1, max: 2, items: { type: 'number' } }, [], false);
50 + expectParity({ type: 'number', format: 'int64' }, 42, true);
51 + expectParity({ type: 'number', format: 'int64' }, 4.2, false);
52 + expectParity({ type: 'string', format: 'binary' }, 'aGVsbG8=', true);
53 + expectParity({ type: 'string', format: 'binary' }, 'not base64', false);
54 + expectParity({ type: 'string', format: 'ip' }, '127.0.0.1', true);
55 + expectParity({ type: 'string', format: 'ip' }, 'not-an-ip', false);
56 + });
57 +
58 + it('supports JSON Schema composition without generated code', () => {
59 + const schema = {
60 + type: 'object',
61 + additionalProperties: false,
62 + required: ['value'],
63 + properties: {
64 + value: {
65 + anyOf: [
66 + { type: 'string', minLength: 1 },
67 + { type: 'integer', minimum: 1 },
68 + ],
69 + },
70 + },
71 + } satisfies JsonSchema;
72 +
73 + expect(effectAccepts(schema, { value: 'ready' })).toBe(true);
74 + expect(effectAccepts(schema, { value: 2 })).toBe(true);
75 + expect(effectAccepts(schema, { value: 0 })).toBe(false);
76 + expect(effectAccepts(schema, { value: false })).toBe(false);
77 + });
78 +
79 + it('reports all failures with field paths and groups unknown keys', () => {
80 + const schema = {
81 + type: 'object',
82 + additionalProperties: false,
83 + required: ['email', 'profile'],
84 + properties: {
85 + email: { type: 'string' },
86 + profile: {
87 + type: 'object',
88 + additionalProperties: false,
89 + required: ['age'],
90 + properties: { age: { type: 'integer' } },
91 + },
92 + },
93 + } satisfies JsonSchema;
94 + let captured: ReadonlyArray<JsonSchemaValidationIssue> = [];
95 + const effectSchema = jsonSchemaToEffectSchema(schema, {
96 + formatIssues: issues => {
97 + captured = issues;
98 + return issues.map(issue => issue.message);
99 + },
100 + });
101 +
102 + const result = Schema.decodeUnknownEither(effectSchema, { errors: 'all' })({
103 + email: 42,
104 + profile: { age: 'old', extra: true },
105 + typo: true,
106 + });
107 +
108 + expect(Either.isLeft(result)).toBe(true);
109 + expect(captured).toEqual(
110 + expect.arrayContaining([
111 + expect.objectContaining({ code: 'type', path: ['email'] }),
112 + expect.objectContaining({ code: 'type', path: ['profile', 'age'] }),
113 + expect.objectContaining({ code: 'unrecognized_keys', keys: ['extra'], path: ['profile'] }),
114 + expect.objectContaining({ code: 'unrecognized_keys', keys: ['typo'], path: [] }),
115 + ])
116 + );
117 + });
118 +});
ts/packages/json-schema-to-effect-schema/tsconfig.json new
+8
@@ -0,0 +1,8 @@
1 +{
2 + "$schema": "https://json.schemastore.org/tsconfig",
3 + "extends": "./tsconfig.options.json",
4 + "compilerOptions": {
5 + "rootDir": "."
6 + },
7 + "include": ["src/**/*", "test/**/*", "package.json"]
8 +}
ts/packages/json-schema-to-effect-schema/tsconfig.options.json new
+22
@@ -0,0 +1,22 @@
1 +{
2 + "$schema": "https://json.schemastore.org/tsconfig",
3 + "compilerOptions": {
4 + "target": "es2022",
5 + "module": "es2022",
6 + "lib": ["es2022", "DOM"],
7 + "declaration": true,
8 + "outDir": "./dist",
9 + "rootDir": ".",
10 + "strict": true,
11 + "esModuleInterop": true,
12 + "moduleResolution": "bundler",
13 + "skipLibCheck": true,
14 + "resolveJsonModule": true,
15 + "pretty": true,
16 + "noImplicitReturns": true,
17 + "noFallthroughCasesInSwitch": true,
18 + "noUnusedLocals": false,
19 + "noUnusedParameters": false
20 + },
21 + "exclude": ["node_modules", "**/dist"]
22 +}
ts/packages/json-schema-to-effect-schema/tsconfig.src.json new
+10
@@ -0,0 +1,10 @@
1 +{
2 + "$schema": "https://json.schemastore.org/tsconfig",
3 + "extends": "./tsconfig.options.json",
4 + "compilerOptions": {
5 + "outDir": "./dist",
6 + "rootDir": "."
7 + },
8 + "include": ["src/**/*", "package.json"],
9 + "exclude": ["node_modules", "../../../node_modules", "**/dist"]
10 +}
ts/packages/json-schema-to-effect-schema/tsconfig.test.json new
+9
@@ -0,0 +1,9 @@
1 +{
2 + "$schema": "https://json.schemastore.org/tsconfig",
3 + "extends": "./tsconfig.options.json",
4 + "compilerOptions": {
5 + "rootDir": "."
6 + },
7 + "include": ["src/**/*", "test/**/*", "package.json"],
8 + "exclude": ["node_modules", "../../../node_modules", "**/dist"]
9 +}
ts/packages/json-schema-to-effect-schema/tsdown.config.ts new
+11
@@ -0,0 +1,11 @@
1 +import { defineConfig } from 'tsdown';
2 +import { baseConfig, baseNeverBundle } from '../../../tsdown.config.base.ts';
3 +
4 +export default defineConfig({
5 + ...baseConfig,
6 + tsconfig: 'tsconfig.src.json',
7 + deps: {
8 + neverBundle: [...baseNeverBundle, '@cfworker/json-schema', 'effect'],
9 + onlyBundle: false,
10 + },
11 +});
ts/packages/json-schema-to-effect-schema/vitest.config.ts new
+18
@@ -0,0 +1,18 @@
1 +import { defineConfig } from 'vitest/config';
2 +import path from 'node:path';
3 +
4 +const packageDir = path.resolve(path.dirname(new URL(import.meta.url).pathname));
5 +
6 +export default defineConfig({
7 + resolve: {
8 + alias: {
9 + '@composio/json-schema-to-zod': path.resolve(
10 + packageDir,
11 + '../json-schema-to-zod/src/index.ts'
12 + ),
13 + },
14 + },
15 + test: {
16 + exclude: ['**/node_modules/**', '**/dist/**'],
17 + },
18 +});