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

chore(cli): land Effect-first guidelines and inert guardrail rule groups (#3877)

This PR: - opens the CLI Effect-guardrails stack that re-slices https://github.com/ComposioHQ/composio/pull/3859 into reviewable PRs - rewrites the CLI `AGENTS.md` Effect guidance: typed `Data.TaggedError` failures, `Schema`/`Predicate` decoding at trust boundaries, and Effect platform services over Node builtins — policy for new code effective now - adds the matching "Effect Platform Boundaries" section to the `cli-command` skill reference - defines every new ESLint rule group (platform imports, terminal streams, descriptor seam, zod ban, test rules, try/catch + `process.env`) as live constants in the root `eslint.config.mjs`, with the entries applying them commented out and annotated with the stack PR that activates each group - bumps the vendored `ts/vendor/effect` reference to the pin used across the stack (CI never initializes submodules) No CLI source is touched; `pnpm lint` stays green with the rules inert. --- **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 ← **this PR** 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 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:13 UTC 3c7a6c6c91fc42cda51c2925b0d4056f60d58d9e
4 files changed +224 -21
.agents/skills/cli-command/references/implementation.md
+12
@@ -25,6 +25,18 @@ export const myCmd = Command.make('my-command', {}, () =>
25
26 Follow existing local patterns before introducing new service abstractions.
27
28 +## Effect Platform Boundaries
29 +
30 +`node:path`, `node:fs`, `node:os`, `node:child_process`, `process.env`, and `try`/`catch` are banned policy for new code in `src/` (ESLint rule groups are defined in the root `eslint.config.mjs` and activated group-by-group over the guardrails PR stack):
31 +
32 +- Path arithmetic → `Path` service from `@effect/platform` (`const path = yield* Path.Path`).
33 +- Filesystem I/O → `FileSystem` service from `@effect/platform`.
34 +- homedir/tmpdir/platform/arch → the `NodeOs` service; subprocesses → platform `Command`.
35 +- Environment reads → `effect/Config`; sync fallible ops (`JSON.parse`, `new URL`) → `Either.try` with a `Data.TaggedError`.
36 +- Helpers that cannot become Effects (sync callbacks, promise pipelines) take the resolved service instance as a plain parameter instead of importing Node builtins.
37 +
38 +Never add an `eslint-disable` for these rules in new code — thread the service instead. Full policy: `ts/packages/cli/AGENTS.md`.
39 +
40 ## Required Checks
41
42 For CLI source changes, run from the repo root:
eslint.config.mjs
+202 -20
@@ -1,10 +1,123 @@
1 import globals from 'globals';
2 import tseslint from 'typescript-eslint';
3
4 +const portableRestrictedImportPaths = [
5 + {
6 + name: 'crypto',
7 + message: 'Use Web Crypto API instead.',
8 + },
9 + {
10 + name: 'node:crypto',
11 + message: 'Use Web Crypto API instead.',
12 + },
13 + {
14 + name: 'buffer',
15 + message: 'Use Uint8Array instead.',
16 + },
17 + {
18 + name: 'node:buffer',
19 + message: 'Use Uint8Array instead.',
20 + },
21 +];
22 +
23 +const cliRestrictedSyntax = [
24 + {
25 + selector: 'TryStatement',
26 + message:
27 + 'Use Effect.try, Effect.tryPromise, or typed Effect error recovery instead of try/catch.',
28 + },
29 + {
30 + selector: "MemberExpression[object.name='process'][property.name='env']",
31 + message: 'Read environment variables through effect/Config instead of process.env.',
32 + },
33 +];
34 +
35 +const cliProcessStreamRestrictions = [
36 + {
37 + selector: "MemberExpression[object.name='process'][property.name='stdout']",
38 + message: 'Write output and read terminal capabilities through TerminalUI.',
39 + },
40 + {
41 + selector: "MemberExpression[object.name='process'][property.name='stderr']",
42 + message: 'Write errors and read terminal capabilities through TerminalUI.',
43 + },
44 +];
45 +
46 +const cliRestrictedImportPaths = [
47 + ...portableRestrictedImportPaths,
48 + {
49 + name: 'child_process',
50 + message: 'Use Command from @effect/platform instead.',
51 + },
52 + {
53 + name: 'node:child_process',
54 + message: 'Use Command from @effect/platform instead.',
55 + },
56 + {
57 + name: 'node:fs',
58 + message: 'Use FileSystem from @effect/platform instead.',
59 + },
60 + {
61 + name: 'node:os',
62 + message: 'Use an Effect service instead of importing node:os directly.',
63 + },
64 + {
65 + name: 'node:path',
66 + message: 'Use Path from @effect/platform instead.',
67 + },
68 +];
69 +
70 +const cliRestrictedImportPatterns = [
71 + {
72 + group: ['node:fs/*'],
73 + message: 'Use FileSystem from @effect/platform instead.',
74 + },
75 +];
76 +
77 +const cliDescriptorSeamMessage =
78 + 'CommandDescriptor/Usage introspection is the @effect/cli v4 seam. Use the helpers in ts/packages/cli/src/commands/command-introspection.ts instead.';
79 +
80 +const cliDescriptorSeamRestrictedImportPaths = [
81 + {
82 + name: '@effect/cli',
83 + importNames: ['CommandDescriptor', 'Usage'],
84 + message: cliDescriptorSeamMessage,
85 + },
86 +];
87 +
88 +const cliDescriptorSeamRestrictedImportPatterns = [
89 + {
90 + group: ['@effect/cli/CommandDescriptor', '@effect/cli/Usage'],
91 + message: cliDescriptorSeamMessage,
92 + },
93 +];
94 +
95 +const effectSchemaRestrictedImportPaths = [
96 + {
97 + name: 'zod',
98 + message: 'Use Schema from effect for tool input validation.',
99 + },
100 +];
101 +
102 +const effectSchemaRestrictedImportPatterns = [
103 + {
104 + group: ['zod/*'],
105 + message: 'Use Schema from effect for tool input validation.',
106 + },
107 +];
108 +
109 /** @type {import('eslint').Linter.Config[]} */
110 export default [
111 {
112 ignores: [
113 + '**/.venv/**',
114 + '**/.next/**',
115 + '**/site-packages/**',
116 + '**/__fixtures__/**',
117 + '**/fixtures/**',
118 + 'docs/.source/**',
119 + 'ts/vendor/**',
120 + 'ts/packages/cli-local-tools/vendor/**',
121 'ts/packages/**/dist/**',
122 'ts/packages/**/.generated/**',
123 'ts/packages/**/acp-adapters/**',
@@ -14,6 +127,13 @@ export default [
127 'ts/examples/**/dist-worker/**',
128 'scripts/**',
129 '**/test/**',
130 + // uncommented by the test-rules PR of this stack: the CLI test sources
131 + // become linted (unlike other packages' tests) so the @effect/vitest
132 + // guardrail below is actually enforced. Fixtures and the test/__utils__
133 + // harness glue stay unlinted.
134 + // '!ts/packages/cli/test/**',
135 + // 'ts/packages/cli/test/__fixtures__/**',
136 + // 'ts/packages/cli/test/__utils__/**',
137 ],
138 },
139 { files: ['ts/packages/**/*.ts', 'ts/examples/**/*.ts'] },
@@ -23,26 +143,7 @@ export default [
143 rules: {
144 // "@typescript-eslint/no-var-requires": "off",
145 'no-restricted-globals': ['error', 'Buffer'],
26 - "no-restricted-imports": ["error", {
27 - "paths": [
28 - {
29 - "name": "crypto",
30 - "message": "Use Web Crypto API instead.",
31 - },
32 - {
33 - "name": "node:crypto",
34 - "message": "Use Web Crypto API instead.",
35 - },
36 - {
37 - "name": "buffer",
38 - "message": "Use Uint8Array instead.",
39 - },
40 - {
41 - "name": "node:buffer",
42 - "message": "Use Uint8Array instead.",
43 - },
44 - ],
45 - }],
146 + 'no-restricted-imports': ['error', { paths: portableRestrictedImportPaths }],
147 '@typescript-eslint/no-require-imports': 'warn',
148 '@typescript-eslint/no-unsafe-function-type': 'off',
149 'no-prototype-builtins': 'off',
@@ -70,6 +171,87 @@ export default [
171 ],
172 },
173 },
174 + {
175 + files: ['ts/packages/cli/src/**/*.{ts,tsx}'],
176 + rules: {
177 + // uncommented by the platform-imports PR of this stack (the
178 + // CommandDescriptor/Usage seam entries by the seam-rules PR).
179 + // 'no-restricted-imports': [
180 + // 'error',
181 + // {
182 + // paths: [...cliRestrictedImportPaths, ...cliDescriptorSeamRestrictedImportPaths],
183 + // patterns: [...cliRestrictedImportPatterns, ...cliDescriptorSeamRestrictedImportPatterns],
184 + // },
185 + // ],
186 + // uncommented by the terminal-streams PR of this stack (the try/catch and
187 + // process.env entries by the boundary-ratchet PR).
188 + // 'no-restricted-syntax': ['error', ...cliRestrictedSyntax, ...cliProcessStreamRestrictions],
189 + },
190 + },
191 + // uncommented by the test-rules PR of this stack.
192 + // {
193 + // // Tests exercise Effects through @effect/vitest (it.effect, it.scoped,
194 + // // it.live) so failures surface as typed Exits instead of thrown
195 + // // FiberFailures. The test/__utils__ harness glue (vitest setup files,
196 + // // TestLayer runner) is intentionally outside this glob: it is the one
197 + // // boundary allowed to run Effects directly.
198 + // files: ['ts/packages/cli/test/src/**/*.{ts,tsx}'],
199 + // rules: {
200 + // // Vitest suites are one long describe() block by design, and mock
201 + // // plumbing casts freely; the SUT's own types carry the safety.
202 + // 'max-lines-per-function': 'off',
203 + // '@typescript-eslint/no-explicit-any': 'off',
204 + // 'no-restricted-syntax': [
205 + // 'error',
206 + // {
207 + // selector: "MemberExpression[object.name='Effect'][property.name=/^run/]",
208 + // message:
209 + // 'Run Effects through @effect/vitest (it.effect, it.scoped, it.live) instead of Effect.run* in tests.',
210 + // },
211 + // {
212 + // selector: "CallExpression[callee.object.name='Date'][callee.property.name='now']",
213 + // message:
214 + // 'Tests must be deterministic: pin time with vi.setSystemTime / TestClock-relative fixtures, use crypto.randomUUID() for unique names.',
215 + // },
216 + // ],
217 + // },
218 + // },
219 + // uncommented by the seam-rules PR of this stack.
220 + // {
221 + // // The one file allowed to touch @effect/cli's CommandDescriptor/Usage
222 + // // modules (the Effect CLI v4 redesign seam).
223 + // files: ['ts/packages/cli/src/commands/command-introspection.ts'],
224 + // rules: {
225 + // 'no-restricted-imports': [
226 + // 'error',
227 + // {
228 + // paths: cliRestrictedImportPaths,
229 + // patterns: cliRestrictedImportPatterns,
230 + // },
231 + // ],
232 + // },
233 + // },
234 + // uncommented by the seam-rules PR of this stack.
235 + // {
236 + // files: ['ts/packages/cli/src/services/tool-input-validation.ts'],
237 + // rules: {
238 + // 'no-restricted-imports': [
239 + // 'error',
240 + // {
241 + // paths: [...cliRestrictedImportPaths, ...effectSchemaRestrictedImportPaths],
242 + // patterns: [...cliRestrictedImportPatterns, ...effectSchemaRestrictedImportPatterns],
243 + // },
244 + // ],
245 + // },
246 + // },
247 + // uncommented by the terminal-streams PR of this stack.
248 + // {
249 + // files: ['ts/packages/cli/src/services/terminal-ui.ts'],
250 + // rules: {
251 + // // TerminalUI is the sole CLI boundary for Node's stdout and stderr streams.
252 + // 'no-restricted-syntax': ['error', ...cliRestrictedSyntax],
253 + // },
254 + // },
255 {
256 // Examples are console-driven references. Keep type-safety rules
257 // (no-explicit-any, unused-vars) but drop console noise. The Buffer/crypto
ts/packages/cli/AGENTS.md
+9
@@ -136,6 +136,15 @@ Effect.gen(function* () {
136
137 Key patterns: `Effect.all([...], { concurrency: 'unbounded' })` for parallel work, `Layer.provide()` for dependency composition, `Effect.mapError()` / `Effect.catchTag()` for typed errors, `Effect.scoped` for resource cleanup.
138
139 +### Effect safety and migration seams
140 +
141 +- Never branch on an Effect value's internal tag field directly. Use the owning module's public refinement or matcher (`Option`, `Either`, `Exit`, `Cause`, `ValidationError`), `Match.valueTags` for exhaustive unions, or `Predicate.isTagged` for a single narrowing guard.
142 +- Do not wrap a plain `Error` in `Effect.fail` for expected failures. Give the failure a meaningful `Data.TaggedError` type with structured fields and a preserved cause, then recover with `catchTag` / `catchTags`. Reserve `Effect.die` and `Effect.dieMessage` for impossible invariants.
143 +- Treat `unknown`, JSON, persisted state, and API payloads as trust boundaries. Decode them with `Schema` or narrow them with `Predicate`; an `as` assertion is not validation.
144 +- Do not inspect private `@effect/cli` descriptor shapes. Use public `CommandDescriptor` operations or keep declarative command metadata that can move to Effect v4's public command tree.
145 +- Prefer `Effect.mapError`, `Effect.matchEffect`, and typed recovery over `catchAll` blocks that flatten distinct failures into one message-only error.
146 +- Prefer Effect services over Node builtins for platform access in new code: `Path`/`FileSystem`/`Command` from `@effect/platform` instead of `node:path`/`node:fs`/`node:child_process`, and `effect/Config` instead of `process.env`. These rules are policy for new CLI code effective now; the matching ESLint rule groups are defined (commented out) in the root `eslint.config.mjs` and are activated group-by-group over the guardrails PR stack as existing code migrates.
147 +
148 ## Vendor Reference Sources
149
150 Read-only submodules under `ts/vendor/` (do NOT modify — actual deps come from npm):
ts/vendor/effect
+1 -1
@@ -1 +1 @@
1 -Subproject commit 4f2107548fa64c21a8643b7b0efcd556cd16d4b9
1 +Subproject commit 703792d9dea3f49acdeb8cce85b261b302fee4e3