Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

refactor(cli): activate the try/catch and env ban and pin the boundary ratchet (#3885)

Alberto Schiabel0979159e104b
diff --git a/.agents/skills/cli-command/references/implementation.md b/.agents/skills/cli-command/references/implementation.md
index 82ef68e59..41b92fa99 100644
--- a/.agents/skills/cli-command/references/implementation.md
+++ b/.agents/skills/cli-command/references/implementation.md
@@ -27,15 +27,15 @@ Follow existing local patterns before introducing new service abstractions.
## Effect Platform Boundaries
-`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):
+`node:path`, `node:fs`, `node:os`, `node:child_process`, `process.env`, and `try`/`catch` are eslint-banned in `src/`:
- Path arithmetic → `Path` service from `@effect/platform` (`const path = yield* Path.Path`).
- Filesystem I/O → `FileSystem` service from `@effect/platform`.
-- homedir/tmpdir/platform/arch → the `NodeOs` service; subprocesses → platform `Command`.
-- Environment reads → `effect/Config`; sync fallible ops (`JSON.parse`, `new URL`) → `Either.try` with a `Data.TaggedError`.
+- homedir/tmpdir/platform/arch → the `NodeOs` service; subprocesses → platform `Command` or `services/detached-process.ts`.
+- Environment reads → `effect/Config`; sync fallible ops (`JSON.parse`, `new URL`) → `Either.try` with a `Data.TaggedError` (JSON records via `parseJsonRecord` in `src/utils/parse-json.ts`).
- Helpers that cannot become Effects (sync callbacks, promise pipelines) take the resolved service instance as a plain parameter instead of importing Node builtins.
-Never add an `eslint-disable` for these rules in new code — thread the service instead. Full policy: `ts/packages/cli/AGENTS.md`.
+Never add an `eslint-disable`: `pnpm run validate:boundaries` (CI-blocking via `pnpm test`) rejects any disable not registered in `eslint-boundaries.json`. Genuine new runtime boundaries require regenerating the manifest with `pnpm run validate:boundaries -- --update` plus a justification in the PR. Full policy: "Effect Boundary Policy" in `ts/packages/cli/AGENTS.md`.
## Required Checks
diff --git a/.gitleaks.toml b/.gitleaks.toml
index 02469261f..547485731 100644
--- a/.gitleaks.toml
+++ b/.gitleaks.toml
@@ -1,8 +1,2 @@
[extend]
useDefault = true
-
-[allowlist]
-description = "Ignore test fixtures and assertions in TypeScript test files"
-paths = [
- '''\.test\.ts$''',
-]
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 6907e8975..5423a4202 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -20,16 +20,27 @@ const portableRestrictedImportPaths = [
},
];
+const cliProcessEnvMessage =
+ 'Read environment variables through effect/Config instead of process.env.';
+
+const cliProcessEnvRestrictions = [
+ "MemberExpression[object.name='process'][computed=false][property.name='env']",
+ "MemberExpression[object.name='process'][computed=true][property.value='env']",
+ "VariableDeclarator[init.name='process'] > ObjectPattern > Property[key.name='env']",
+ "VariableDeclarator[init.name='process'] > ObjectPattern > Property[key.value='env']",
+ "AssignmentExpression[right.name='process'] > ObjectPattern > Property[key.name='env']",
+ "AssignmentExpression[right.name='process'] > ObjectPattern > Property[key.value='env']",
+ "AssignmentPattern[right.name='process'] > ObjectPattern > Property[key.name='env']",
+ "AssignmentPattern[right.name='process'] > ObjectPattern > Property[key.value='env']",
+].map(selector => ({ selector, message: cliProcessEnvMessage }));
+
const cliRestrictedSyntax = [
{
selector: 'TryStatement',
message:
'Use Effect.try, Effect.tryPromise, or typed Effect error recovery instead of try/catch.',
},
- {
- selector: "MemberExpression[object.name='process'][property.name='env']",
- message: 'Read environment variables through effect/Config instead of process.env.',
- },
+ ...cliProcessEnvRestrictions,
];
const cliProcessStreamRestrictions = [
@@ -217,8 +228,7 @@ export default [
],
'no-restricted-syntax': [
'error',
- // uncommented by the boundary-ratchet PR of this stack
- // ...cliRestrictedSyntax,
+ ...cliRestrictedSyntax,
...cliProcessStreamRestrictions,
...cliDescriptorSeamRestrictedSyntax,
],
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
index c8b3af9aa..526d043b9 100644
--- a/ts/packages/cli/AGENTS.md
+++ b/ts/packages/cli/AGENTS.md
@@ -142,7 +142,30 @@ Key patterns: `Effect.all([...], { concurrency: 'unbounded' })` for parallel wor
- 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.
- 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.
- Prefer `Effect.mapError`, `Effect.matchEffect`, and typed recovery over `catchAll` blocks that flatten distinct failures into one message-only error.
-- 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.
+
+### Effect Boundary Policy
+
+All platform access goes through Effect services. `node:path`, `node:fs`, `node:os`, `node:child_process`, `process.env`, and `try`/`catch` are eslint-banned in `src/`. Use the sanctioned equivalents:
+
+| Need | Use |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Path arithmetic (join/resolve/dirname/…) | `Path` service from `@effect/platform` (`const path = yield* Path.Path`) |
+| Filesystem I/O | `FileSystem` service from `@effect/platform` |
+| homedir / tmpdir / platform / arch | `NodeOs` service (`src/services/node-os.ts`, the sole `node:os` boundary) |
+| Subprocesses | `Command` from `@effect/platform`; children that outlive the CLI via `src/services/detached-process.ts` (sole detached-spawn boundary) |
+| Environment reads | `effect/Config` |
+| Sync fallible ops (`JSON.parse`, `new URL`, `JSON.stringify`) | `Either.try` with a `Data.TaggedError`; JSON records via `parseJsonRecord` (`src/utils/parse-json.ts`) |
+
+Conversion patterns, in order of preference:
+
+1. Yield the service inside existing Effect code.
+2. Convert a plain helper into an Effect when its callers are Effect-hosted (`Either` is a subtype of `Effect`, so both compose with `yield*`).
+3. Pass the resolved service instance (e.g. `Path.Path`, `FileSystem.FileSystem`) as a plain parameter into sync callbacks or promise pipelines that cannot become Effects (see `tool-permissions.ts`, `generation/typescript/virtual-compiler-host.ts`).
+4. Modules that self-provide layers add `Path.layer` / `BunFileSystem.layer` / `NodeOs.Default` to their stack instead of reaching for Node builtins.
+
+The only code allowed to bypass services sits at declared runtime boundaries: the `bin.ts` bootstrap, the child-process companion runtime (`run-helpers-runtime.ts`, `run-subagent-*` — bundled into `.mjs` files that run in the user's spawned process), import-time UI setup (`ui/colors.ts`, `ui/redact.ts`), environment **writes** and whole-environment enumeration (which `effect/Config` cannot express), and spawn-time env handshakes between parent and child `composio run` processes. Every such boundary is an inline `// eslint-disable-next-line <rule> -- <reason>` comment registered in `eslint-boundaries.json`.
+
+**Enforcement**: `pnpm run validate:boundaries` (part of `pnpm test`, CI-blocking) fails when any eslint-disable in `src/` is missing from the manifest, lacks a `-- reason`, or uses a file-wide form. Do not add new disables — thread the service instead. If code genuinely cannot run inside the Effect runtime, that is a new boundary: regenerate the manifest with `pnpm run validate:boundaries -- --update` and justify the boundary in the PR. Never add entries to `eslint-suppressions.json`.
## Vendor Reference Sources
diff --git a/ts/packages/cli/eslint-boundaries.json b/ts/packages/cli/eslint-boundaries.json
new file mode 100644
index 000000000..a25fdc36a
--- /dev/null
+++ b/ts/packages/cli/eslint-boundaries.json
@@ -0,0 +1,276 @@
+{
+ "src/analytics/events.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "spawn-time env handoff from parent run",
+ "target": "(process.env.COMPOSIO_CLI_PARENT_RUN_ID ?? crypto.randomUUID())"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "spawn-time env handoff read outside Effect",
+ "target": "const getInvocationOrigin = (): string => process.env.COMPOSIO_CLI_INVOCATION_ORIGIN ?? 'cli';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "spawn-time env handoff read outside Effect",
+ "target": "const getParentRunId = (): string | undefined => process.env.COMPOSIO_CLI_PARENT_RUN_ID;"
+ }
+ ],
+ "src/bin.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "pre-runtime env write during bootstrap",
+ "target": "process.env[CLI_TELEMETRY_DEBUG_ENV_VAR] = 'true';"
+ }
+ ],
+ "src/cli-main.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "env write propagates run id to children",
+ "target": "process.env.COMPOSIO_CLI_PARENT_RUN_ID = commandTelemetryContext.runId;"
+ }
+ ],
+ "src/commands/index.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "env delete clears a stale hidden-flag value",
+ "target": "delete process.env.COMPOSIO_RUN_ACP_ONLY;"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "env write hands the stripped flag to run.cmd",
+ "target": "process.env.COMPOSIO_RUN_ACP_ONLY = acpOnly ? '1' : '0';"
+ }
+ ],
+ "src/commands/install.cmd.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "$SHELL is read inside a plain synchronous helper that mirrors install.sh's shell detection, outside any Effect context",
+ "target": "const shellEnv = process.env.SHELL ?? '';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "COMPOSIO_INSTALL_DIR is the handoff variable set by the install.sh bootstrapper for this one-shot post-install step; read directly to stay byte-compatible with the script",
+ "target": "const installDir = process.env.COMPOSIO_INSTALL_DIR ?? path.join(os.homedir, '.composio');"
+ }
+ ],
+ "src/commands/run.cmd.ts": [
+ {
+ "rule": "no-restricted-imports",
+ "reason": "os.tmpdir and os.homedir locate the preload scratch directory and ~/.composio in the same synchronous helpers",
+ "target": "import * as os from 'node:os';"
+ },
+ {
+ "rule": "no-restricted-imports",
+ "reason": "synchronous fs (mkdtempSync/writeFileSync/rmSync/existsSync) builds and tears down the run preload files in plain helpers that execute outside the Effect runtime",
+ "target": "import * as fs from 'node:fs';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "honors the same COMPOSIO_CACHE_DIR/CACHE_DIR overrides the run-helpers child runtime reads, so the sandbox read roots match the child's cache location",
+ "target": "process.env.COMPOSIO_CACHE_DIR?.trim() || process.env.CACHE_DIR?.trim() || defaultComposioDir;"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "reads the COMPOSIO_RUN_ACP_ONLY flag a parent process sets to force the ACP-only subagent path in the child run",
+ "target": "const acpOnly = process.env.COMPOSIO_RUN_ACP_ONLY === '1';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "reuses the run ID a parent `composio run` process passed via env so nested runs share one run identity",
+ "target": "const runId = process.env.COMPOSIO_CLI_PARENT_RUN_ID ?? crypto.randomUUID();"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "spreads the caller's full environment into the spawned script so user-provided variables reach the child process",
+ "target": "...process.env,"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "try/finally removes the temp preload and wrapper files around the imperative Bun.spawn block, whose success path ends in process.exit",
+ "target": "try {"
+ }
+ ],
+ "src/commands/tools/commands/tools.execute.cmd.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "COMPOSIO_CLI_INVOCATION_ORIGIN is a spawn-time handshake the parent `composio run` process injects into nested CLI invocations, not user configuration, and it must be read fresh at call time",
+ "target": "const shouldStoreLargeExecuteOutput = () => process.env.COMPOSIO_CLI_INVOCATION_ORIGIN !== 'run';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "COMPOSIO_RUN_OUTPUT_DIR is injected per-subprocess by the parent `composio run` and must take precedence over the session artifacts directory; inter-process plumbing, not user configuration",
+ "target": "process.env.COMPOSIO_RUN_OUTPUT_DIR?.trim() ||"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "COMPOSIO_RUN_OUTPUT_DIR is injected per-subprocess by the parent `composio run` so nested executions share one output directory; it is inter-process plumbing, not user configuration",
+ "target": "directoryPath: sharedDirectory?.trim() || process.env.COMPOSIO_RUN_OUTPUT_DIR?.trim(),"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "COMPOSIO_RUN_OUTPUT_DIR is injected per-subprocess by the parent `composio run` so nested local-tool executions write into its shared output directory; inter-process plumbing, not user configuration",
+ "target": "executeOutputDir: process.env.COMPOSIO_RUN_OUTPUT_DIR?.trim() || undefined,"
+ }
+ ],
+ "src/commands/triggers/commands/triggers.listen.cmd.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "re-checks the same raw env var to tell the user whether they supplied a secret or this session generated one",
+ "target": "if (process.env.COMPOSIO_WEBHOOK_SECRET) {"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "the forward signing secret is an optional raw passthrough from the user's shell; its literal presence/absence selects the generated-secret fallback",
+ "target": "const webhookSecret = process.env.COMPOSIO_WEBHOOK_SECRET ?? generatedWebhookSecret;"
+ }
+ ],
+ "src/services/agents.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "read lazily at request time inside a plain sync helper so tests can repoint agents.composio.dev per call without rebuilding a Config layer",
+ "target": "(process.env.COMPOSIO_AGENTS_BASE_URL ?? DEFAULT_AGENTS_BASE_URL).replace(/\\/+$/, '');"
+ }
+ ],
+ "src/services/cli-session-artifacts.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "COMPOSIO_CACHE_DIR is the second rung of the same fall-through chain: env overrides must beat the persisted artifactDirectory before the tmpdir default",
+ "target": "process.env.COMPOSIO_CACHE_DIR?.trim() ||"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "read inline so a blank/whitespace-only COMPOSIO_SESSION_DIR falls through the || precedence chain (session dir > cache dir > user config > tmpdir)",
+ "target": "process.env.COMPOSIO_SESSION_DIR?.trim() ||"
+ }
+ ],
+ "src/services/cli-user-config.ts": [
+ {
+ "rule": "no-restricted-imports",
+ "reason": "os.homedir feeds resolveCliConfigDirectorySync, which runs from synchronous non-Effect call sites (dev.cmd messages, run-helpers-runtime readFileSync) where the NodeOs service is unavailable",
+ "target": "import os from 'node:os';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "this resolver is called from synchronous non-Effect code, so the COMPOSIO_CACHE_DIR override cannot come from effect/Config here",
+ "target": "process.env.COMPOSIO_CACHE_DIR?.trim() ||"
+ }
+ ],
+ "src/services/detached-process.ts": [
+ {
+ "rule": "no-restricted-imports",
+ "reason": "This Effect helper is the sole detached-spawn boundary for CLI source: @effect/platform Command processes are scope-bound and are killed when their scope closes, while these children must outlive the CLI process.",
+ "target": "import { spawn } from 'node:child_process';"
+ }
+ ],
+ "src/services/master-detector.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "classifies the driving agent by scanning every env key for CODEX_/CLAUDE_ prefixes; effect/Config reads known keys and cannot enumerate the whole environment",
+ "target": "export const detectMaster = (env: Record<string, string | undefined> = process.env): MasterKind => {"
+ }
+ ],
+ "src/services/native-ui-sidecar.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "Sole raw-env boundary of this module: prefix scanning needs the full environment map, which effect/Config cannot enumerate.",
+ "target": "const rawProcessEnv: NodeJS.ProcessEnv = process.env;"
+ }
+ ],
+ "src/services/node-os.ts": [
+ {
+ "rule": "no-restricted-imports",
+ "reason": "This Effect service is the sole node:os boundary for CLI source.",
+ "target": "import os from 'node:os';"
+ }
+ ],
+ "src/services/project-environment-detector.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "npm_config_user_agent is transient metadata injected by the package manager that spawned this process, not CLI configuration; read once as the last-resort heuristic when no lockfile or manifest evidence exists",
+ "target": "const userAgent = parseUserAgent(process.env.npm_config_user_agent);"
+ }
+ ],
+ "src/services/run-helpers-runtime.ts": [
+ {
+ "rule": "no-restricted-imports",
+ "reason": "os.tmpdir() locates the fallback run-files directory in the child process, outside the Effect runtime",
+ "target": "import * as os from 'node:os';"
+ },
+ {
+ "rule": "no-restricted-imports",
+ "reason": "sync fs for run-log appends, run-file writes, and CLI config reads in the child process, outside the Effect runtime",
+ "target": "import * as fs from 'node:fs';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "JSON.stringify throws on circular user values in this sync formatter injected into user code; String() is the entire fallback",
+ "target": "try {"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "async fallback chain in the user's child process: ACP invoke errors route to the legacy sub-agent path, everything else rethrows",
+ "target": "try {"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "debug flag reaches the child process via inherited environment; the CLI's Config provider is not available here",
+ "target": "helperContext.perfDebug === true || process.env.COMPOSIO_PERF_DEBUG === '1';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "debug flag reaches the child process via inherited environment; the CLI's Config provider is not available here",
+ "target": "helperContext.toolDebug === true || process.env.COMPOSIO_TOOL_DEBUG === '1';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "sync config read at the child-process boundary; a missing or malformed CLI config file just means the 'auto' target",
+ "target": "try {"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "the spawned CLI child must inherit the caller's full environment before Composio-specific overrides are layered on top",
+ "target": "...process.env,"
+ }
+ ],
+ "src/services/run-subagent-output-mcp.ts": [
+ {
+ "rule": "no-restricted-imports",
+ "reason": "standalone MCP stdio sidecar entrypoint runs outside the CLI's Effect runtime; sync fs reads the schema file and writes the structured result file",
+ "target": "import * as fs from 'node:fs';"
+ }
+ ],
+ "src/services/runtime-debug-flags.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "called from sync non-Effect helper code in spawned child processes, where the flag arrives via inherited environment rather than a Config provider",
+ "target": "runtimeDebugFlags.perfDebug || process.env.COMPOSIO_PERF_DEBUG === '1';"
+ },
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "called from sync non-Effect helper code in spawned child processes, where the flag arrives via inherited environment rather than a Config provider",
+ "target": "runtimeDebugFlags.toolDebug || process.env.COMPOSIO_TOOL_DEBUG === '1';"
+ }
+ ],
+ "src/services/tool-permissions.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "node:http listen callback inside a Promise executor: on failure to open the browser, close the server and reject the surrounding Promise; Effect's error channel is not available here",
+ "target": "try {"
+ }
+ ],
+ "src/ui/colors.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "palette is created eagerly at import time, before any Effect runtime; honors the NO_COLOR convention",
+ "target": "} = color.createColors(!Boolean(process.env.NO_COLOR));"
+ }
+ ],
+ "src/ui/redact.ts": [
+ {
+ "rule": "no-restricted-syntax",
+ "reason": "plain sync string helper called from formatting code; CI flag toggles redaction in recorded CLI output",
+ "target": "if (process.env.CI !== 'true') return value as `${Prefix}${string}`;"
+ }
+ ]
+}
diff --git a/ts/packages/cli/package.json b/ts/packages/cli/package.json
index 74e785336..d6fb34977 100644
--- a/ts/packages/cli/package.json
+++ b/ts/packages/cli/package.json
@@ -33,13 +33,14 @@
"build:binary:checksums": "bun run ./scripts/generate-checksums.ts",
"build:skills": "tsx ./scripts/build-skills.ts",
"validate:skills": "tsx ./scripts/validate-skills.ts",
+ "validate:boundaries": "tsx ./scripts/validate-eslint-boundaries.ts",
"install:binary": "bun run ./scripts/install-binary.ts ./dist/composio",
"table:metrics": "bun run ./scripts/optimize-metrics-table.ts",
"mock": "bun run ./scripts/copy-mocks-from-cache.ts",
"prebuild": "pnpm run typecheck",
"build": "tsdown && bun run ./scripts/copy-local-tools-assets.ts ./dist",
"bin": "./dist/composio",
- "test": "pnpm run validate:skills && vitest run",
+ "test": "pnpm run validate:skills && pnpm run validate:boundaries && vitest run",
"prepublishOnly": "pnpm run build && pnpm run build:binary",
"typecheck:src": "pnpm exec tsgo --noEmit -p ./tsconfig.src.json",
"typecheck:test": "pnpm exec tsgo --noEmit -p ./tsconfig.test.json",
diff --git a/ts/packages/cli/scripts/eslint-boundaries.ts b/ts/packages/cli/scripts/eslint-boundaries.ts
new file mode 100644
index 000000000..0c66057c5
--- /dev/null
+++ b/ts/packages/cli/scripts/eslint-boundaries.ts
@@ -0,0 +1,149 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface BoundarySite {
+ readonly rule: string;
+ readonly reason: string;
+ readonly target: string;
+}
+
+export type BoundaryManifest = Record<string, BoundarySite[]>;
+
+export interface CollectedBoundaries {
+ readonly manifest: BoundaryManifest;
+ readonly errors: readonly string[];
+}
+
+const NEXT_LINE_FORM = /\/\/ eslint-disable-next-line (?<rules>[\w@/,\- ]+?) -- (?<reason>.+?)\s*$/;
+
+const boundarySiteKey = (site: BoundarySite): string =>
+ JSON.stringify([site.rule, site.reason, site.target]);
+
+const compareBoundarySites = (left: BoundarySite, right: BoundarySite): number => {
+ const leftKey = boundarySiteKey(left);
+ const rightKey = boundarySiteKey(right);
+ return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+};
+
+const formatBoundarySite = (site: BoundarySite): string =>
+ `"${site.rule}" -- ${site.reason} -> ${JSON.stringify(site.target)}`;
+
+export const listSourceFiles = (dir: string): string[] =>
+ fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) return listSourceFiles(full);
+ return entry.isFile() && /\.tsx?$/.test(entry.name) ? [full] : [];
+ });
+
+export const parseBoundarySites = (
+ relativePath: string,
+ source: string
+): { readonly sites: readonly BoundarySite[]; readonly errors: readonly string[] } => {
+ const lines = source.split('\n');
+ const sites: BoundarySite[] = [];
+ const errors: string[] = [];
+
+ lines.forEach((line, index) => {
+ if (!line.includes('eslint-disable')) return;
+
+ const location = `${relativePath}:${index + 1}`;
+ const match = NEXT_LINE_FORM.exec(line);
+ if (!match?.groups) {
+ errors.push(
+ `${location}: only "// eslint-disable-next-line <rules> -- <reason>" is allowed ` +
+ '(no file-wide disables, no bare disables without a justification).'
+ );
+ return;
+ }
+
+ const target = lines[index + 1]?.trim();
+ if (!target) {
+ errors.push(`${location}: eslint-disable-next-line must govern a non-empty next line.`);
+ return;
+ }
+
+ const reason = match.groups.reason.trim();
+ for (const rule of match.groups.rules.split(',').map(rule => rule.trim())) {
+ sites.push({ rule, reason, target });
+ }
+ });
+
+ return { errors, sites };
+};
+
+export const collectBoundaryManifest = (
+ packageRoot: string,
+ srcRoot: string
+): CollectedBoundaries => {
+ const manifest: BoundaryManifest = {};
+ const errors: string[] = [];
+
+ for (const file of listSourceFiles(srcRoot).sort()) {
+ const relative = path.relative(packageRoot, file).split(path.sep).join('/');
+ const parsed = parseBoundarySites(relative, fs.readFileSync(file, 'utf8'));
+ errors.push(...parsed.errors);
+
+ if (parsed.sites.length > 0) {
+ manifest[relative] = [...parsed.sites].sort(compareBoundarySites);
+ }
+ }
+
+ return { errors, manifest };
+};
+
+const countSites = (sites: readonly BoundarySite[]): Map<string, number> => {
+ const counts = new Map<string, number>();
+ for (const site of sites) {
+ const key = boundarySiteKey(site);
+ counts.set(key, (counts.get(key) ?? 0) + 1);
+ }
+ return counts;
+};
+
+export const compareBoundaryManifests = (
+ found: BoundaryManifest,
+ registered: BoundaryManifest
+): readonly string[] => {
+ const errors: string[] = [];
+ const files = [...new Set([...Object.keys(found), ...Object.keys(registered)])].sort();
+
+ for (const file of files) {
+ const foundSites = found[file] ?? [];
+ const registeredSites = registered[file] ?? [];
+ const foundCounts = countSites(foundSites);
+ const registeredCounts = countSites(registeredSites);
+ const sitesByKey = new Map(
+ [...foundSites, ...registeredSites].map(site => [boundarySiteKey(site), site])
+ );
+
+ for (const key of [...sitesByKey.keys()].sort()) {
+ const site = sitesByKey.get(key)!;
+ const foundCount = foundCounts.get(key) ?? 0;
+ const registeredCount = registeredCounts.get(key) ?? 0;
+
+ if (foundCount > registeredCount) {
+ errors.push(
+ `${file}: ${foundCount}x ${formatBoundarySite(site)} found, ${registeredCount} registered. ` +
+ 'New or relocated eslint-disables are not allowed in CLI src: thread the ' +
+ '@effect/platform service (Path, FileSystem), effect/Config, or Either.try instead — ' +
+ 'see "Effect Boundary Policy" in ts/packages/cli/AGENTS.md. If this is genuinely a new ' +
+ 'runtime boundary, regenerate the manifest with ' +
+ '`pnpm run validate:boundaries -- --update` and justify the boundary in your PR.'
+ );
+ }
+
+ if (foundCount < registeredCount) {
+ errors.push(
+ `${file}: manifest registers ${registeredCount}x ${formatBoundarySite(site)} but only ` +
+ `${foundCount} exist. Nice — a boundary went away or moved. Regenerate the manifest ` +
+ 'with `pnpm run validate:boundaries -- --update`.'
+ );
+ }
+ }
+ }
+
+ return errors;
+};
+
+export const countBoundarySites = (manifest: BoundaryManifest): number =>
+ Object.values(manifest).reduce((sum, sites) => sum + sites.length, 0);
diff --git a/ts/packages/cli/scripts/validate-eslint-boundaries.ts b/ts/packages/cli/scripts/validate-eslint-boundaries.ts
new file mode 100644
index 000000000..7226d59cf
--- /dev/null
+++ b/ts/packages/cli/scripts/validate-eslint-boundaries.ts
@@ -0,0 +1,53 @@
+// Guards the CLI's Effect platform boundaries: every eslint-disable comment in
+// src/ must be a single-line `eslint-disable-next-line` with a `-- reason`
+// justification, and must be registered in eslint-boundaries.json. The manifest
+// pins each rule, justification, and governed next-line target, so adding or
+// relocating a disable fails until the manifest is regenerated on purpose (see
+// AGENTS.md, "Effect Boundary Policy").
+//
+// Usage:
+// tsx ./scripts/validate-eslint-boundaries.ts # verify (CI)
+// tsx ./scripts/validate-eslint-boundaries.ts --update # regenerate manifest
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+ collectBoundaryManifest,
+ compareBoundaryManifests,
+ countBoundarySites,
+ type BoundaryManifest,
+} from './eslint-boundaries';
+
+const scriptDir = import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname);
+const packageRoot = path.resolve(scriptDir, '..');
+const srcRoot = path.join(packageRoot, 'src');
+const manifestPath = path.join(packageRoot, 'eslint-boundaries.json');
+
+const collected = collectBoundaryManifest(packageRoot, srcRoot);
+const errors = [...collected.errors];
+const found = collected.manifest;
+
+if (process.argv.includes('--update')) {
+ if (errors.length > 0) {
+ console.error(errors.join('\n'));
+ console.error('\nFix the malformed disables above before regenerating the manifest.');
+ process.exit(1);
+ }
+ fs.writeFileSync(manifestPath, `${JSON.stringify(found, null, 2)}\n`);
+ console.log(
+ `Wrote ${path.relative(packageRoot, manifestPath)} (${Object.keys(found).length} files).`
+ );
+ process.exit(0);
+}
+
+const manifest: BoundaryManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+errors.push(...compareBoundaryManifests(found, manifest));
+
+if (errors.length > 0) {
+ console.error(errors.join('\n'));
+ process.exit(1);
+}
+
+console.log(
+ `eslint boundaries OK: ${countBoundarySites(found)} registered disables across ${Object.keys(found).length} files.`
+);
diff --git a/ts/packages/cli/src/analytics/events.ts b/ts/packages/cli/src/analytics/events.ts
index e0f5e327f..3dadf1d65 100644
--- a/ts/packages/cli/src/analytics/events.ts
+++ b/ts/packages/cli/src/analytics/events.ts
@@ -90,7 +90,9 @@ const TOOL_VALIDATION_CODES: ReadonlySet<number> = new Set([
// A parent `composio run` process hands these values to child CLI invocations through the
// environment at spawn time; the event builders below are plain synchronous functions that
// run outside any Effect context, so effect/Config is not available here.
+// eslint-disable-next-line no-restricted-syntax -- spawn-time env handoff read outside Effect
const getInvocationOrigin = (): string => process.env.COMPOSIO_CLI_INVOCATION_ORIGIN ?? 'cli';
+// eslint-disable-next-line no-restricted-syntax -- spawn-time env handoff read outside Effect
const getParentRunId = (): string | undefined => process.env.COMPOSIO_CLI_PARENT_RUN_ID;
const extractCommandPath = (argv: ReadonlyArray<string>): string => {
@@ -353,7 +355,8 @@ export const createCliCommandTelemetryContext = (
startedAt: Date.now(),
runId:
extractCommandPath(argv) === 'run'
- ? (process.env.COMPOSIO_CLI_PARENT_RUN_ID ?? crypto.randomUUID())
+ ? // eslint-disable-next-line no-restricted-syntax -- spawn-time env handoff from parent run
+ (process.env.COMPOSIO_CLI_PARENT_RUN_ID ?? crypto.randomUUID())
: undefined,
});
diff --git a/ts/packages/cli/src/bin.ts b/ts/packages/cli/src/bin.ts
index b133c185a..8d864ba1d 100644
--- a/ts/packages/cli/src/bin.ts
+++ b/ts/packages/cli/src/bin.ts
@@ -19,6 +19,7 @@ const stripTelemetryDebugFlag = (argv: ReadonlyArray<string>): string[] => {
normalizedArgv.splice(flagIndex, 1);
// Bootstrap runs before the Effect runtime and ConfigProvider exist; the stripped flag is
// persisted as an env var so later effect/Config reads and child processes observe it.
+ // eslint-disable-next-line no-restricted-syntax -- pre-runtime env write during bootstrap
process.env[CLI_TELEMETRY_DEBUG_ENV_VAR] = 'true';
return normalizedArgv;
};
diff --git a/ts/packages/cli/src/cli-main.ts b/ts/packages/cli/src/cli-main.ts
index 0e9b513f2..68d86d95f 100644
--- a/ts/packages/cli/src/cli-main.ts
+++ b/ts/packages/cli/src/cli-main.ts
@@ -152,6 +152,7 @@ const runWithTelemetry = Effect.gen(function* () {
if (commandTelemetryContext.commandPath === 'run' && commandTelemetryContext.runId) {
// effect/Config is read-only; the run id must be written into the environment so the run
// command and the child processes it spawns observe the same telemetry run id.
+ // eslint-disable-next-line no-restricted-syntax -- env write propagates run id to children
process.env.COMPOSIO_CLI_PARENT_RUN_ID = commandTelemetryContext.runId;
}
diff --git a/ts/packages/cli/src/commands/auth-configs/commands/auth-configs.create.cmd.ts b/ts/packages/cli/src/commands/auth-configs/commands/auth-configs.create.cmd.ts
index ffae8c672..684b6ca8b 100644
--- a/ts/packages/cli/src/commands/auth-configs/commands/auth-configs.create.cmd.ts
+++ b/ts/packages/cli/src/commands/auth-configs/commands/auth-configs.create.cmd.ts
@@ -1,6 +1,7 @@
import { Args, Command, Options } from '@effect/cli';
-import { Effect, Option } from 'effect';
+import { Effect, Either, Option } from 'effect';
import type { AuthConfigCreateParams } from '@composio/client/resources/auth-configs';
+import { parseJsonRecord } from 'src/utils/parse-json';
import { ComposioToolkitsRepository } from 'src/services/composio-clients';
import { TerminalUI } from 'src/services/terminal-ui';
import { requireAuth } from 'src/effects/require-auth';
@@ -62,15 +63,15 @@ export const authConfigsCmd$Create = Command.make(
// Parse custom credentials JSON if provided
let parsedCustomCredentials: Record<string, unknown> | undefined;
if (Option.isSome(customCredentials)) {
- try {
- parsedCustomCredentials = JSON.parse(customCredentials.value) as Record<string, unknown>;
- } catch {
+ const parsed = parseJsonRecord(customCredentials.value);
+ if (Either.isLeft(parsed)) {
yield* ui.log.error('Invalid JSON in --custom-credentials. Please provide valid JSON.');
yield* ui.log.step(
'Example:\n> composio dev auth-configs create "name" --toolkit "gmail" --custom-credentials \'{"client_id":"...","client_secret":"..."}\''
);
return;
}
+ parsedCustomCredentials = parsed.right;
}
// Parse scopes into array
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index f4232f968..0034a54f6 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/ts/packages/cli/src/commands/index.ts
@@ -316,8 +316,10 @@ const normalizeHiddenDebugFlags = (argv: ReadonlyArray<string>): ReadonlyArray<s
// The hidden --acp-only flag is stripped from argv before @effect/cli parses it, so its value
// travels to run.cmd.ts through the environment; effect/Config cannot write or delete env vars.
if (acpOnly === undefined) {
+ // eslint-disable-next-line no-restricted-syntax -- env delete clears a stale hidden-flag value
delete process.env.COMPOSIO_RUN_ACP_ONLY;
} else {
+ // eslint-disable-next-line no-restricted-syntax -- env write hands the stripped flag to run.cmd
process.env.COMPOSIO_RUN_ACP_ONLY = acpOnly ? '1' : '0';
}
diff --git a/ts/packages/cli/src/commands/install.cmd.ts b/ts/packages/cli/src/commands/install.cmd.ts
index 29f97e085..10e7c1e80 100644
--- a/ts/packages/cli/src/commands/install.cmd.ts
+++ b/ts/packages/cli/src/commands/install.cmd.ts
@@ -48,6 +48,7 @@ const UNSAFE_PATH_CHARS = /[;`$|&"'()\n\r\\]/;
const isUnsafePath = (p: string): boolean => UNSAFE_PATH_CHARS.test(p);
const detectShell = (path: Path.Path): Shell | undefined => {
+ // eslint-disable-next-line no-restricted-syntax -- $SHELL is read inside a plain synchronous helper that mirrors install.sh's shell detection, outside any Effect context
const shellEnv = process.env.SHELL ?? '';
const base = path.basename(shellEnv);
if (base === 'zsh') return 'zsh';
@@ -161,6 +162,7 @@ export const installShellIntegration = (params: {
yield* ui.intro('composio install');
// Detect install directory — either from env or default ~/.composio
+ // eslint-disable-next-line no-restricted-syntax -- COMPOSIO_INSTALL_DIR is the handoff variable set by the install.sh bootstrapper for this one-shot post-install step; read directly to stay byte-compatible with the script
const installDir = process.env.COMPOSIO_INSTALL_DIR ?? path.join(os.homedir, '.composio');
if (isUnsafePath(installDir)) {
diff --git a/ts/packages/cli/src/commands/run.cmd.ts b/ts/packages/cli/src/commands/run.cmd.ts
index 8ef2f96b4..94ed0ef07 100644
--- a/ts/packages/cli/src/commands/run.cmd.ts
+++ b/ts/packages/cli/src/commands/run.cmd.ts
@@ -301,6 +301,7 @@ const resolveRunHelperContext = () =>
const orgId = Option.getOrUndefined(userContext.data.orgId);
const defaultComposioDir = path.join(os.homedir(), USER_COMPOSIO_DIR);
const configuredCacheDir =
+ // eslint-disable-next-line no-restricted-syntax -- honors the same COMPOSIO_CACHE_DIR/CACHE_DIR overrides the run-helpers child runtime reads, so the sandbox read roots match the child's cache location
process.env.COMPOSIO_CACHE_DIR?.trim() || process.env.CACHE_DIR?.trim() || defaultComposioDir;
const baseReadAccessRoots = [
...new Set([defaultComposioDir, configuredCacheDir].map(value => path.resolve(value))),
@@ -429,9 +430,11 @@ export const runCmd = Command.make('run', {
}) =>
Effect.gen(function* () {
const path = yield* Path.Path;
+ // eslint-disable-next-line no-restricted-syntax -- reuses the run ID a parent `composio run` process passed via env so nested runs share one run identity
const runId = process.env.COMPOSIO_CLI_PARENT_RUN_ID ?? crypto.randomUUID();
const perfDebug = isPerfDebugEnabled();
const toolDebug = isToolDebugEnabled();
+ // eslint-disable-next-line no-restricted-syntax -- reads the COMPOSIO_RUN_ACP_ONLY flag a parent process sets to force the ACP-only subagent path in the child run
const acpOnly = process.env.COMPOSIO_RUN_ACP_ONLY === '1';
if (Option.isNone(file)) {
const [inlineCode] = args;
@@ -474,6 +477,7 @@ export const runCmd = Command.make('run', {
);
const ui = yield* TerminalUI;
let cleanupPaths: ReadonlyArray<string> = [];
+ // eslint-disable-next-line no-restricted-syntax -- try/finally removes the temp preload and wrapper files around the imperative Bun.spawn block, whose success path ends in process.exit
try {
yield* appendCliSessionHistory({
orgId: helperContext.orgId,
@@ -498,6 +502,7 @@ export const runCmd = Command.make('run', {
const child = Bun.spawn({
cmd: runCommand.cmd,
env: {
+ // eslint-disable-next-line no-restricted-syntax -- spreads the caller's full environment into the spawned script so user-provided variables reach the child process
...process.env,
BUN_BE_BUN: '1',
COMPOSIO_CLI_PARENT_RUN_ID: runId,
diff --git a/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts b/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts
index 22ed20cd1..58503be7d 100644
--- a/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts
+++ b/ts/packages/cli/src/commands/toolkits/commands/toolkits.search.cmd.ts
@@ -1,6 +1,6 @@
import process from 'node:process';
import { Args, Command, Options } from '@effect/cli';
-import { Effect, Option } from 'effect';
+import { Effect } from 'effect';
import { ComposioToolkitsRepository } from 'src/services/composio-clients';
import { TerminalUI } from 'src/services/terminal-ui';
import { requireAuth } from 'src/effects/require-auth';
diff --git a/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts b/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts
index d347af39a..ced2d7025 100644
--- a/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts
+++ b/ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts
@@ -316,6 +316,7 @@ const getExecuteOutputEncoder = () => {
return executeOutputEncoder;
};
+// eslint-disable-next-line no-restricted-syntax -- COMPOSIO_CLI_INVOCATION_ORIGIN is a spawn-time handshake the parent `composio run` process injects into nested CLI invocations, not user configuration, and it must be read fresh at call time
const shouldStoreLargeExecuteOutput = () => process.env.COMPOSIO_CLI_INVOCATION_ORIGIN !== 'run';
type StoredExecuteOutputSummary = {
@@ -366,6 +367,7 @@ const persistLargeExecuteOutput = (toolSlug: string, json: string, sharedDirecto
contents: json,
name: `${toolSlug}_OUTPUT`,
extension: 'json',
+ // eslint-disable-next-line no-restricted-syntax -- COMPOSIO_RUN_OUTPUT_DIR is injected per-subprocess by the parent `composio run` so nested executions share one output directory; it is inter-process plumbing, not user configuration
directoryPath: sharedDirectory?.trim() || process.env.COMPOSIO_RUN_OUTPUT_DIR?.trim(),
});
@@ -1067,6 +1069,7 @@ const resolveExecuteContext = (params: RunToolsExecuteParams) =>
args: parsedArgs,
resolvedUserId: 'local',
selectedConnectedAccountId: undefined,
+ // eslint-disable-next-line no-restricted-syntax -- COMPOSIO_RUN_OUTPUT_DIR is injected per-subprocess by the parent `composio run` so nested local-tool executions write into its shared output directory; inter-process plumbing, not user configuration
executeOutputDir: process.env.COMPOSIO_RUN_OUTPUT_DIR?.trim() || undefined,
executeParams: {
userId: 'local',
@@ -1139,6 +1142,7 @@ const resolveExecuteContext = (params: RunToolsExecuteParams) =>
)
: parsedArgs;
const executeOutputDir =
+ // eslint-disable-next-line no-restricted-syntax -- COMPOSIO_RUN_OUTPUT_DIR is injected per-subprocess by the parent `composio run` and must take precedence over the session artifacts directory; inter-process plumbing, not user configuration
process.env.COMPOSIO_RUN_OUTPUT_DIR?.trim() ||
Option.getOrUndefined(
yield* resolveCliSessionArtifacts({
diff --git a/ts/packages/cli/src/commands/triggers/commands/triggers.create.cmd.ts b/ts/packages/cli/src/commands/triggers/commands/triggers.create.cmd.ts
index 7b846a4eb..15496f321 100644
--- a/ts/packages/cli/src/commands/triggers/commands/triggers.create.cmd.ts
+++ b/ts/packages/cli/src/commands/triggers/commands/triggers.create.cmd.ts
@@ -1,5 +1,6 @@
import { Args, Command, Options } from '@effect/cli';
-import { Effect, Option } from 'effect';
+import { Effect, Either, Option } from 'effect';
+import { parseJsonRecord } from 'src/utils/parse-json';
import { requireAuth } from 'src/effects/require-auth';
import { handleHttpServerError } from 'src/effects/handle-http-error';
import { ComposioToolkitsRepository } from 'src/services/composio-clients';
@@ -43,22 +44,21 @@ export const triggersCmd$Create = Command.make(
let parsedTriggerConfig: Record<string, unknown> | undefined;
if (Option.isSome(triggerConfig)) {
- try {
- const parsed: unknown = JSON.parse(triggerConfig.value);
- if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+ const parsed = parseJsonRecord(triggerConfig.value);
+ if (Either.isLeft(parsed)) {
+ if (parsed.left.reason === 'not-a-record') {
yield* ui.log.error(
'--trigger-config must be a JSON object (e.g. \'{"key":"value"}\').'
);
- return;
+ } else {
+ yield* ui.log.error('Invalid JSON in --trigger-config. Please provide valid JSON.');
+ yield* ui.log.step(
+ 'Example:\n> composio dev triggers create "GMAIL_NEW_GMAIL_MESSAGE" --trigger-config \'{"label":"inbox"}\''
+ );
}
- parsedTriggerConfig = parsed as Record<string, unknown>;
- } catch {
- yield* ui.log.error('Invalid JSON in --trigger-config. Please provide valid JSON.');
- yield* ui.log.step(
- 'Example:\n> composio dev triggers create "GMAIL_NEW_GMAIL_MESSAGE" --trigger-config \'{"label":"inbox"}\''
- );
return;
}
+ parsedTriggerConfig = parsed.right;
}
const createdOpt = yield* ui
diff --git a/ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts b/ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts
index 27a4a3700..5969cc37a 100644
--- a/ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts
+++ b/ts/packages/cli/src/commands/triggers/commands/triggers.listen.cmd.ts
@@ -184,6 +184,7 @@ export const triggersCmd$Listen = Command.make(
const runtime = yield* Effect.runtime<never>();
const forwardUrl = Option.getOrUndefined(forward);
const generatedWebhookSecret = `composio-forward-secret-${randomUUID()}`;
+ // eslint-disable-next-line no-restricted-syntax -- the forward signing secret is an optional raw passthrough from the user's shell; its literal presence/absence selects the generated-secret fallback
const webhookSecret = process.env.COMPOSIO_WEBHOOK_SECRET ?? generatedWebhookSecret;
const outputFilePathOption = Option.getOrUndefined(out);
const outputFilePath = outputFilePathOption ? path.resolve(outputFilePathOption) : undefined;
@@ -210,6 +211,7 @@ export const triggersCmd$Listen = Command.make(
yield* ui.intro('composio dev triggers listen');
if (forwardUrl) {
+ // eslint-disable-next-line no-restricted-syntax -- re-checks the same raw env var to tell the user whether they supplied a secret or this session generated one
if (process.env.COMPOSIO_WEBHOOK_SECRET) {
yield* ui.note(
`Forward URL: ${forwardUrl}\nSigning secret: ${webhookSecret}`,
diff --git a/ts/packages/cli/src/services/agents.ts b/ts/packages/cli/src/services/agents.ts
index a17758159..b47a36307 100644
--- a/ts/packages/cli/src/services/agents.ts
+++ b/ts/packages/cli/src/services/agents.ts
@@ -80,6 +80,7 @@ export class AgentResponseDecodeError extends Data.TaggedError(
}> {}
const agentsBaseURL = (): string =>
+ // eslint-disable-next-line no-restricted-syntax -- read lazily at request time inside a plain sync helper so tests can repoint agents.composio.dev per call without rebuilding a Config layer
(process.env.COMPOSIO_AGENTS_BASE_URL ?? DEFAULT_AGENTS_BASE_URL).replace(/\/+$/, '');
const decodeAgentResponse =
diff --git a/ts/packages/cli/src/services/cli-session-artifacts.ts b/ts/packages/cli/src/services/cli-session-artifacts.ts
index 835f46b73..f48cea1cc 100644
--- a/ts/packages/cli/src/services/cli-session-artifacts.ts
+++ b/ts/packages/cli/src/services/cli-session-artifacts.ts
@@ -10,7 +10,9 @@ export const resolveArtifactsRoot = Effect.gen(function* () {
const cliUserConfig = yield* ComposioCliUserConfig;
return (
+ // eslint-disable-next-line no-restricted-syntax -- read inline so a blank/whitespace-only COMPOSIO_SESSION_DIR falls through the || precedence chain (session dir > cache dir > user config > tmpdir)
process.env.COMPOSIO_SESSION_DIR?.trim() ||
+ // eslint-disable-next-line no-restricted-syntax -- COMPOSIO_CACHE_DIR is the second rung of the same fall-through chain: env overrides must beat the persisted artifactDirectory before the tmpdir default
process.env.COMPOSIO_CACHE_DIR?.trim() ||
cliUserConfig.data.artifactDirectory?.trim() ||
path.join(os.tmpdir, 'composio')
diff --git a/ts/packages/cli/src/services/cli-user-config.ts b/ts/packages/cli/src/services/cli-user-config.ts
index 7760ca22e..f1c7cb481 100644
--- a/ts/packages/cli/src/services/cli-user-config.ts
+++ b/ts/packages/cli/src/services/cli-user-config.ts
@@ -54,6 +54,7 @@ const decodeConfigJson = Schema.decodeUnknown(Schema.parseJson(JsonRecordSchema)
const syncPath = Effect.runSync(Path.Path.pipe(Effect.provide(Path.layer)));
export const resolveCliConfigDirectorySync = (): string =>
+ // eslint-disable-next-line no-restricted-syntax -- this resolver is called from synchronous non-Effect code, so the COMPOSIO_CACHE_DIR override cannot come from effect/Config here
process.env.COMPOSIO_CACHE_DIR?.trim() ||
syncPath.join(os.homedir(), constants.USER_COMPOSIO_DIR);
diff --git a/ts/packages/cli/src/services/master-detector.ts b/ts/packages/cli/src/services/master-detector.ts
index 529d3e0d4..e420f4c3d 100644
--- a/ts/packages/cli/src/services/master-detector.ts
+++ b/ts/packages/cli/src/services/master-detector.ts
@@ -3,6 +3,7 @@ export type MasterKind = 'claude' | 'codex' | 'user';
export const hasEnvPrefix = (env: Record<string, string | undefined>, prefix: string): boolean =>
Object.keys(env).some(key => key.startsWith(prefix));
+// eslint-disable-next-line no-restricted-syntax -- classifies the driving agent by scanning every env key for CODEX_/CLAUDE_ prefixes; effect/Config reads known keys and cannot enumerate the whole environment
export const detectMaster = (env: Record<string, string | undefined> = process.env): MasterKind => {
if (hasEnvPrefix(env, 'CODEX_')) {
return 'codex';
diff --git a/ts/packages/cli/src/services/native-ui-sidecar.ts b/ts/packages/cli/src/services/native-ui-sidecar.ts
index e60bdaaac..fe80d06a5 100644
--- a/ts/packages/cli/src/services/native-ui-sidecar.ts
+++ b/ts/packages/cli/src/services/native-ui-sidecar.ts
@@ -65,6 +65,7 @@ export class NativeUiDecisionMissingError extends Data.TaggedError(
// prefixes (OPENCLAW_*, CLAUDE_*, CODEX_*). effect/Config can only read named
// keys, so this module keeps a single raw-env boundary, mirroring the
// node-os.ts precedent.
+// eslint-disable-next-line no-restricted-syntax -- Sole raw-env boundary of this module: prefix scanning needs the full environment map, which effect/Config cannot enumerate.
const rawProcessEnv: NodeJS.ProcessEnv = process.env;
const FALSY_ENV_FLAG_VALUES: ReadonlyArray<string> = ['0', 'false', 'no', 'off'];
diff --git a/ts/packages/cli/src/services/project-environment-detector.ts b/ts/packages/cli/src/services/project-environment-detector.ts
index fa8757dc5..c33ced478 100644
--- a/ts/packages/cli/src/services/project-environment-detector.ts
+++ b/ts/packages/cli/src/services/project-environment-detector.ts
@@ -498,6 +498,7 @@ const detectJsPackageManager = (fs: FileSystem.FileSystem, cwd: string) =>
if (fileSet.has('pnpm-workspace.yaml')) return 'pnpm' as const;
}
+ // eslint-disable-next-line no-restricted-syntax -- npm_config_user_agent is transient metadata injected by the package manager that spawned this process, not CLI configuration; read once as the last-resort heuristic when no lockfile or manifest evidence exists
const userAgent = parseUserAgent(process.env.npm_config_user_agent);
if (userAgent) return userAgent;
diff --git a/ts/packages/cli/src/services/run-helpers-runtime.ts b/ts/packages/cli/src/services/run-helpers-runtime.ts
index cca3bdd25..9bb9fe41a 100644
--- a/ts/packages/cli/src/services/run-helpers-runtime.ts
+++ b/ts/packages/cli/src/services/run-helpers-runtime.ts
@@ -262,6 +262,7 @@ const stringifyForPrompt = (value: unknown): string => {
if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
return String(value);
}
+ // eslint-disable-next-line no-restricted-syntax -- JSON.stringify throws on circular user values in this sync formatter injected into user code; String() is the entire fallback
try {
return JSON.stringify(value, null, 2);
} catch {
@@ -318,6 +319,7 @@ const summarizeCliResultPreview = (result: RunCliResult): unknown => {
};
const readConfiguredExperimentalSubagentTarget = (): 'auto' | 'claude' | 'codex' => {
+ // eslint-disable-next-line no-restricted-syntax -- sync config read at the child-process boundary; a missing or malformed CLI config file just means the 'auto' target
try {
const raw = fs.readFileSync(resolveCliConfigPathSync(), 'utf8');
const parsed = decodeExperimentalSubagentConfig(raw);
@@ -614,6 +616,7 @@ const createCliRunner = (params: {
const requestId = `${args[0] ?? 'cli'}#${++perfDebugSeq}`;
helperDebugLog('cli.start', { requestId, args });
const env: Record<string, string | undefined> = {
+ // eslint-disable-next-line no-restricted-syntax -- the spawned CLI child must inherit the caller's full environment before Composio-specific overrides are layered on top
...process.env,
...(helperContext.apiKey ? { COMPOSIO_USER_API_KEY: helperContext.apiKey } : {}),
...(helperContext.baseURL ? { COMPOSIO_BASE_URL: helperContext.baseURL } : {}),
@@ -802,6 +805,7 @@ const createExperimentalSubAgent = (params: {
resolvedTarget: target,
master,
});
+ // eslint-disable-next-line no-restricted-syntax -- async fallback chain in the user's child process: ACP invoke errors route to the legacy sub-agent path, everything else rethrows
try {
const response = await invokeAcpSubAgent({
prompt: prompt.trim(),
@@ -967,8 +971,10 @@ export const installRunHelpers = async ({
Reflect.set(globalThis, 'zod', z);
const perfDebugEnabled =
+ // eslint-disable-next-line no-restricted-syntax -- debug flag reaches the child process via inherited environment; the CLI's Config provider is not available here
helperContext.perfDebug === true || process.env.COMPOSIO_PERF_DEBUG === '1';
const toolDebugEnabled =
+ // eslint-disable-next-line no-restricted-syntax -- debug flag reaches the child process via inherited environment; the CLI's Config provider is not available here
helperContext.toolDebug === true || process.env.COMPOSIO_TOOL_DEBUG === '1';
const perfDebugStart = Date.now();
const composioBaseURL = (helperContext.baseURL || 'https://backend.composio.dev').replace(
diff --git a/ts/packages/cli/src/services/runtime-debug-flags.ts b/ts/packages/cli/src/services/runtime-debug-flags.ts
index 6ce337e2f..2914ddead 100644
--- a/ts/packages/cli/src/services/runtime-debug-flags.ts
+++ b/ts/packages/cli/src/services/runtime-debug-flags.ts
@@ -23,7 +23,9 @@ export const resetRuntimeDebugFlags = () => {
};
export const isPerfDebugEnabled = () =>
+ // eslint-disable-next-line no-restricted-syntax -- called from sync non-Effect helper code in spawned child processes, where the flag arrives via inherited environment rather than a Config provider
runtimeDebugFlags.perfDebug || process.env.COMPOSIO_PERF_DEBUG === '1';
export const isToolDebugEnabled = () =>
+ // eslint-disable-next-line no-restricted-syntax -- called from sync non-Effect helper code in spawned child processes, where the flag arrives via inherited environment rather than a Config provider
runtimeDebugFlags.toolDebug || process.env.COMPOSIO_TOOL_DEBUG === '1';
diff --git a/ts/packages/cli/src/services/tool-permissions.ts b/ts/packages/cli/src/services/tool-permissions.ts
index 5e6677496..01273bc14 100644
--- a/ts/packages/cli/src/services/tool-permissions.ts
+++ b/ts/packages/cli/src/services/tool-permissions.ts
@@ -1007,6 +1007,7 @@ const requestPermissionInBrowser = (params: {
reject(error);
});
server.listen(0, '127.0.0.1', async () => {
+ // eslint-disable-next-line no-restricted-syntax -- node:http listen callback inside a Promise executor: on failure to open the browser, close the server and reject the surrounding Promise; Effect's error channel is not available here
try {
const address = server.address();
const port = typeof address === 'object' && address ? address.port : undefined;
diff --git a/ts/packages/cli/src/ui/colors.ts b/ts/packages/cli/src/ui/colors.ts
index 358379fe5..643cd4ddf 100644
--- a/ts/packages/cli/src/ui/colors.ts
+++ b/ts/packages/cli/src/ui/colors.ts
@@ -14,4 +14,5 @@ export const {
white,
blue,
cyanBright,
+ // eslint-disable-next-line no-restricted-syntax -- palette is created eagerly at import time, before any Effect runtime; honors the NO_COLOR convention
} = color.createColors(!Boolean(process.env.NO_COLOR));
diff --git a/ts/packages/cli/src/ui/redact.ts b/ts/packages/cli/src/ui/redact.ts
index 9f5cd682a..05a5501cd 100644
--- a/ts/packages/cli/src/ui/redact.ts
+++ b/ts/packages/cli/src/ui/redact.ts
@@ -12,6 +12,7 @@ export function redact<const Prefix extends string = string>({
value: string;
prefix?: Prefix;
}): `${Prefix}${string}` {
+ // eslint-disable-next-line no-restricted-syntax -- plain sync string helper called from formatting code; CI flag toggles redaction in recorded CLI output
if (process.env.CI !== 'true') return value as `${Prefix}${string}`;
return `${prefix ?? ''}<REDACTED>` as `${Prefix}${string}`;
}
diff --git a/ts/packages/cli/test/src/scripts/validate-eslint-boundaries.test.ts b/ts/packages/cli/test/src/scripts/validate-eslint-boundaries.test.ts
new file mode 100644
index 000000000..e98e9c342
--- /dev/null
+++ b/ts/packages/cli/test/src/scripts/validate-eslint-boundaries.test.ts
@@ -0,0 +1,104 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+ collectBoundaryManifest,
+ compareBoundaryManifests,
+ parseBoundarySites,
+} from '../../../scripts/eslint-boundaries';
+
+const temporaryDirectories: string[] = [];
+
+afterEach(() => {
+ for (const directory of temporaryDirectories.splice(0)) {
+ fs.rmSync(directory, { force: true, recursive: true });
+ }
+});
+
+describe('eslint boundary manifest', () => {
+ it('includes both TypeScript and TSX source files', () => {
+ const packageRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'composio-eslint-boundaries-'));
+ const sourceRoot = path.join(packageRoot, 'src');
+ temporaryDirectories.push(packageRoot);
+ fs.mkdirSync(sourceRoot);
+ fs.writeFileSync(path.join(sourceRoot, 'plain.ts'), 'export const plain = true;\n');
+ fs.writeFileSync(
+ path.join(sourceRoot, 'component.tsx'),
+ [
+ '// eslint-disable-next-line no-restricted-syntax -- import-time runtime bridge',
+ 'export const Component = () => process.env.COMPONENT_NAME;',
+ ].join('\n')
+ );
+ fs.writeFileSync(
+ path.join(sourceRoot, 'ignored.js'),
+ [
+ '// eslint-disable-next-line no-restricted-syntax -- should not be scanned',
+ 'export const ignored = process.env.IGNORED;',
+ ].join('\n')
+ );
+
+ expect(collectBoundaryManifest(packageRoot, sourceRoot)).toEqual({
+ errors: [],
+ manifest: {
+ 'src/component.tsx': [
+ {
+ reason: 'import-time runtime bridge',
+ rule: 'no-restricted-syntax',
+ target: 'export const Component = () => process.env.COMPONENT_NAME;',
+ },
+ ],
+ },
+ });
+ });
+
+ it('rejects moving a registered disable to another target in the same file', () => {
+ const registered = parseBoundarySites(
+ 'src/example.ts',
+ [
+ '// eslint-disable-next-line no-restricted-syntax -- runtime environment bridge',
+ 'const apiKey = process.env.COMPOSIO_API_KEY;',
+ ].join('\n')
+ );
+ const relocated = parseBoundarySites(
+ 'src/example.ts',
+ [
+ '// eslint-disable-next-line no-restricted-syntax -- runtime environment bridge',
+ 'const debug = process.env.DEBUG;',
+ ].join('\n')
+ );
+
+ const errors = compareBoundaryManifests(
+ { 'src/example.ts': [...relocated.sites] },
+ { 'src/example.ts': [...registered.sites] }
+ );
+
+ expect(errors).toHaveLength(2);
+ expect(errors).toEqual(
+ expect.arrayContaining([
+ expect.stringContaining('process.env.COMPOSIO_API_KEY'),
+ expect.stringContaining('process.env.DEBUG'),
+ ])
+ );
+ });
+
+ it('preserves duplicate semantic sites as a deterministic multiset', () => {
+ const directive =
+ '// eslint-disable-next-line no-restricted-syntax -- runtime environment bridge';
+ const target = 'process.env.COMPOSIO_API_KEY = apiKey;';
+ const registered = parseBoundarySites(
+ 'src/example.ts',
+ [directive, target, directive, target].join('\n')
+ );
+ const found = parseBoundarySites('src/example.ts', [directive, target].join('\n'));
+
+ expect(
+ compareBoundaryManifests(
+ { 'src/example.ts': [...found.sites] },
+ { 'src/example.ts': [...registered.sites] }
+ )
+ ).toEqual([expect.stringContaining('manifest registers 2x "no-restricted-syntax"')]);
+ });
+});