effect-v4

Files (6)

• SKILL.md
• cli-surface.md · references/
• core-patterns.md · references/
• upgrade-workflow.md · references/
• check-examples.mjs · scripts/
• versions.json

SKILL.md (first lines)

# Effect v4

The CLI, `@composio/cli-keyring`, and `@composio/json-schema-to-effect-schema` run on
Effect v4. Every claim below is grounded in the migrated source, not memory of v3.

## Exact version matrix

`effect`, `@effect/platform-bun`, and `@effect/vitest`
are pinned to the **same exact** `4.0.5` — never `^`, `@next`, or a mismatched
version across packages. `@effect/cli` and `@effect/platform` no longer exist as
dependencies; their surfaces are consolidated into `effect` and `effect/*`.
See [versions.json](versions.json) for the full matrix (also `typescript`, `vitest`).

## Read next

- [references/core-patterns.md](references/core-patterns.md) — services, layers, typed
  errors, Schema, choosing between `Effect.gen` and `Effect.fn`, `Option` combinators in
  place of `isSome` ternaries, driving time in tests with
  `TestClock` (fork, adjust until the fiber settles, join) instead of `it.live`, and the v3→v4 rename table
  (labeled historical, for recognizing stale patterns).
- [references/cli-surface.md](references/cli-surface.md) — `effect/cli`:
  `Command`, `Flag`, `Argument`, `GlobalFlag`, `CliConfig`, the custom
  `CliOutput.Formatter`, and the runner's double-print rule.
- [references/upgrade-workflow.md](references/upgrade-workflow.md) — procedure for
  bumping to a newer release.

Code excerpts in those references are short quotes from real, currently-compiling repo
files (path cited at each excerpt) — not standalone examples. The compile-checked
source of truth is always the cited file itself; when it and a reference disagree,
trust the file and fix the reference.

## Non-negotiables

- `Effect.gen(function* () {...})` for effect values — the dominant form, including named
  module consts — and `(params) => Effect.gen(...)` for parameterized helpers.
  `Effect.fn(...)` is the function form whose effects carry stack-frame annotations (its
  optional name string adds a per-call tracing span), worth it for service members and
  combinator callbacks that should be attributable in error reports. All forms re-run
  their body per execution. See "`Effect.gen` vs `Effect.fn`" in core-patterns.
- Define services with `Context.Service` and an explicit `static readonly Default`/`layer`
  layer built with `Layer.succeed`/`Layer.effect`/`Layer.provide`. V4 does not generate a
  layer for you.
- Model expected failures with `Schema.TaggedError` (or a plain `Data.TaggedError`
  when no Schema fields are needed) and recover with `Effect.catchTag`/`catchTags`/`Match`,
  never manual `_tag` string comparisons.
- Wrap fallible Promises with `Effect.tryPromise({ try, catch })`; `Effect.promise` turns
  rejection into a defect. No `async`/`await` or `try`/`catch` inside Effect workflows —
  ESLint bans them in `ts/packages/cli/src`.
- Treat every remembered v3 package name and API as wrong until verified against
  `ts/vendor/effect` (read-only source oracle — never edit or import from it) and the
  installed `effect@4.0.5` typings. Source may be ahead of the published package;
  the compiler is the compatibility gate.

## Verification

```bash
pnpm typecheck
pnpm --filter @composio/cli test
```

Run `pnpm validate:agent-skills` and `pnpm validate:skill-routing` after editing this
skill or its descriptions, and compile the TypeScript blocks in this skill and in
`typescript-testing/references/effect-v4-cli.md` against the pinned packages with:

```bash
node .agents/skills/effect-v4/scripts/check-examples.mjs
```

Blocks that quote repo files with unresolvable imports carry a `no-check` fence info string.

From ComposioHQ/composio, MIT.

More from ComposioHQ/composio