opencode-effect-enforcer 0.2.5 → 0.2.6

package/README.md

@@ -3,80 +3,54 @@
 [![npm version](https://img.shields.io/npm/v/opencode-effect-enforcer.svg)](https://www.npmjs.com/package/opencode-effect-enforcer)
 [![license](https://img.shields.io/npm/l/opencode-effect-enforcer.svg)](LICENSE)
 
-An opinionated OpenCode V2 plugin that gives coding agents current Effect v4
-guidance and reviews their TypeScript edits for common Effect anti-patterns.
+**Spend less time teaching your coding agent Effect.**
 
-**Supported Effect version: `4.0.0-rc.112`.** See the
-[full rc.111 → rc.112 release notes and audit](docs/effect-4.0.0-rc.112.md)
-for upstream changes, companion-package notes, and repository migration details.
+If you keep reminding your agent to use typed errors, decode with Schema, or
+check the current API, this plugin gives those reminders a permanent home in
+OpenCode V2. It includes Effect guidance and skills the agent can consult while
+working, plus checks that send common mistakes back for correction after edits.
 
-## Install
+## How it helps
 
-Add the npm package to your global or project `opencode.jsonc`:
+**Guidance** is included before every model call. Four documents cover
+Effect-first design, schema-first modeling, typed dependencies, and how to
+choose the relevant skills.
 
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugins": ["opencode-effect-enforcer"],
-}
-```
+**Skills** explain how to use specific Effect APIs. The agent loads the relevant
+guides through OpenCode's native skill tool, with 53 to choose from across
+services, streams, HTTP, SQL, React, AI, and more.
 
-That is the complete installation. OpenCode resolves published package entries
-for you; there is no separate `npm install` step. Use the global config at
-`~/.config/opencode/opencode.jsonc` to enable it everywhere, or a project config
-to enable it only for that project. You can also pin a release, for example
-`"opencode-effect-enforcer@0.2.5"`.
+**Patterns** check the code after edits. 45 tested checks look for common
+TypeScript and TSX mistakes and return correction advice and relevant skill
+suggestions to the agent for its next turn.
 
-Start a new OpenCode session, then verify the plugin if needed:
+Checks run after successful `write`, `edit`, `patch`, and `apply_patch` calls.
+Edits and patches are checked only in newly added text; full-file writes and new
+files are checked in full. Feedback asks the agent to fix valid findings or
+explain intentional exceptions. Checks are advisory and do not block writes.
 
-```sh
-opencode2 api get /api/plugin
-```
+The bundled guidance and skills target **Effect `4.0.0-rc.116`**.
+See the [rc.112 → rc.116 migration audit](docs/effect-4.0.0-rc.116.md)
+and [complete upstream release notes](docs/effect-4.0.0-rc.116-changelog.md).
 
-### Local Checkout
+## Install
 
-When loading this repository directly, configure its `src` directory:
+Add the plugin to `opencode.jsonc` in your project, or
+`~/.config/opencode/opencode.jsonc` for all projects:
 
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["/absolute/path/opencode-effect-enforcer/src"],
+  "plugins": ["opencode-effect-enforcer"],
 }
 ```
 
-OpenCode `v0.0.0-beta-19157` resolves local directories by looking for `server`
-or `index` directly inside them, rather than using `package.json` exports.
-Pointing at the repository root silently skips the plugin; pointing at the
-`src/index.ts` file is rejected because configured local paths must be directories.
+Start a new session. OpenCode installs the package automatically.
 
-Verify activation for the session's actual working directory, replacing the
-example path below:
+## Explore what's included
 
-```sh
-opencode2 api post '/api/plugin/await-activation?location[directory]=/path/to/project'
-opencode2 api get '/api/plugin?location[directory]=/path/to/project'
-```
-
-Look for `opencode.effect-enforcer` with `state.status` set to `active`.
-
-## What You Get
-
-- **53 focused skills** registered in OpenCode's native skill catalog, covering
-  Effect's core, platform, AI, RPC, SQL, frontend, and testing APIs.
-- **4 guidance documents** injected into model context so Effect-first
-  boundaries, domain modeling, dependency design, and skill routing stay
-  visible while the agent works.
-- **45 tested patterns** run after successful `write`, `edit`, `patch`, and
-  `apply_patch` calls, reporting only violations in newly added text.
-- **Advisory remediation** appended to the completed tool result so the model
-  reviews and fixes valid findings without a detector blocking the underlying
-  write.
-
-## Source Catalog
-
-Every bundled skill, pattern, and guidance document is linked below. Open only
-the area relevant to your task, or expand a catalog to browse everything
-available.
+Browse the guidance, find a skill for your next task, or see what the patterns
+look for.
 
 ### Guidance (4)
 
@@ -87,7 +61,7 @@ available.
 
 ### Skills (53)
 
-#### Modeling And Core APIs
+#### Modeling and core APIs
 
 - [`effect-error-handling`](skills/effect-error-handling/SKILL.md): Model typed failures, inspect causes, report errors, and recover precisely.
 - [`effect-schema-v4`](skills/effect-schema-v4/SKILL.md): Use current Effect Schema v4 APIs and migrate away from v3 patterns.
@@ -99,7 +73,7 @@ available.
 - [`effect-typeclass-design`](skills/effect-typeclass-design/SKILL.md): Design typeclasses with curried signatures and dual data-first/data-last APIs.
 - [`effect-graph`](skills/effect-graph/SKILL.md): Construct, traverse, analyze, and render immutable graphs.
 
-#### Services, Lifecycle, And Concurrency
+#### Services, lifecycle, and concurrency
 
 - [`effect-context-witness`](skills/effect-context-witness/SKILL.md): Choose between service witnesses and capability-based dependency injection.
 - [`effect-service-implementation`](skills/effect-service-implementation/SKILL.md): Implement focused Effect services without monolithic interfaces.
@@ -114,7 +88,7 @@ available.
 - [`effect-pubsub-event-bus`](skills/effect-pubsub-event-bus/SKILL.md): Implement typed publish/subscribe event buses with PubSub and Stream.
 - [`effect-workflow`](skills/effect-workflow/SKILL.md): Build durable workflows, activities, queues, clocks, and compensating transactions.
 
-#### Platform And Runtime Integration
+#### Platform and runtime integration
 
 - [`effect-platform-abstraction`](skills/effect-platform-abstraction/SKILL.md): Keep filesystem, process, HTTP, crypto, and terminal code portable.
 - [`effect-platform-layers`](skills/effect-platform-layers/SKILL.md): Provide platform implementations cleanly at application boundaries.
@@ -125,7 +99,7 @@ available.
 - [`effect-socket`](skills/effect-socket/SKILL.md): Build TCP, Unix-domain, and WebSocket clients, servers, and framed transports.
 - [`effect-cli`](skills/effect-cli/SKILL.md): Build type-safe command-line interfaces with arguments, options, commands, and Layers.
 
-#### HTTP, RPC, And Persistence
+#### HTTP, RPC, and persistence
 
 - [`effect-http-api`](skills/effect-http-api/SKILL.md): Define typed HTTP APIs with schemas, security, handlers, clients, and OpenAPI.
 - [`effect-http-client`](skills/effect-http-client/SKILL.md): Make typed outgoing HTTP requests with decoding, retries, streaming, and test transports.
@@ -136,7 +110,7 @@ available.
 - [`effect-rpc-cluster`](skills/effect-rpc-cluster/SKILL.md): Build clustered RPC entities, sharding, singletons, cron jobs, and workflows.
 - [`effect-sql`](skills/effect-sql/SKILL.md): Query databases and build schemas, models, resolvers, repositories, and migrations.
 
-#### AI And MCP
+#### AI and MCP
 
 - [`effect-ai-language-model`](skills/effect-ai-language-model/SKILL.md): Generate text, structured output, streams, and tool calls through `LanguageModel`.
 - [`effect-ai-prompt`](skills/effect-ai-prompt/SKILL.md): Construct and compose prompts from messages and multimodal parts.
@@ -146,13 +120,13 @@ available.
 - [`effect-ai-chat`](skills/effect-ai-chat/SKILL.md): Build persistent multi-turn chats and agentic tool-calling loops.
 - [`effect-mcp-server`](skills/effect-mcp-server/SKILL.md): Expose MCP tools, resources, and prompts over stdio or HTTP.
 
-#### Frontend State And Composition
+#### Frontend state and composition
 
 - [`effect-atom-state`](skills/effect-atom-state/SKILL.md): Manage reactive React state with Effect Atom.
 - [`effect-atom-rpc`](skills/effect-atom-rpc/SKILL.md): Build cached, invalidating, SSR-aware RPC atoms for React clients.
 - [`effect-react-composition`](skills/effect-react-composition/SKILL.md): Compose React components around explicit Effect Atom state and behavior.
 
-#### Configuration, Operations, And Testing
+#### Configuration, operations, and testing
 
 - [`effect-config`](skills/effect-config/SKILL.md): Load, validate, compose, and test typed configuration sources.
 - [`effect-observability`](skills/effect-observability/SKILL.md): Add structured logs, traces, metrics, and OTLP or Prometheus export.
@@ -163,7 +137,7 @@ available.
 
 ### Patterns (45)
 
-#### Types, Modeling, And Collections
+#### Types, modeling, and collections
 
 - [`avoid-any`](patterns/avoid-any.md): Flags assertions to `any` or `unknown` that erase type safety.
 - [`casting-awareness`](patterns/casting-awareness.md): Reviews type assertions and suggests decoding, guards, or `satisfies`.
@@ -180,7 +154,7 @@ available.
 - [`imperative-loops`](patterns/imperative-loops.md): Replaces imperative loops with functional collection transformations.
 - [`prefer-arr-sort`](patterns/prefer-arr-sort.md): Replaces native array sorting with `Arr.sort` and explicit `Order`.
 
-#### Errors And Effect Boundaries
+#### Errors and Effect boundaries
 
 - [`avoid-data-tagged-error`](patterns/avoid-data-tagged-error.md): Reviews public or serialized `Data.TaggedError` values for schema-backed errors.
 - [`avoid-untagged-errors`](patterns/avoid-untagged-errors.md): Reviews raw `Error` construction and discrimination in recoverable code.
@@ -192,7 +166,7 @@ available.
 - [`prefer-effect-fn`](patterns/prefer-effect-fn.md): Wraps service methods with named, traced `Effect.fn` definitions.
 - [`avoid-yield-ref`](patterns/avoid-yield-ref.md): Replaces direct yielding of Ref, Deferred, Fiber, and Latch with explicit operations.
 
-#### Services, Concurrency, And Time
+#### Services, concurrency, and time
 
 - [`context-tag-extends`](patterns/context-tag-extends.md): Replaces legacy service-tag APIs with `Context.Service`.
 - [`avoid-mutable-state`](patterns/avoid-mutable-state.md): Reviews mutable `let` state inside Effect services in favor of `Ref`.
@@ -203,7 +177,7 @@ available.
 - [`use-random-service`](patterns/use-random-service.md): Replaces `Math.random()` with Effect's testable Random service.
 - [`use-console-service`](patterns/use-console-service.md): Replaces native console calls with Effect logging or Console services.
 
-#### Platform, I/O, And Configuration
+#### Platform, I/O, and configuration
 
 - [`avoid-native-fetch`](patterns/avoid-native-fetch.md): Replaces native `fetch` with Effect HTTP client modules.
 - [`use-http-client-service`](patterns/use-http-client-service.md): Replaces `node:http` and `node:https` with Effect `HttpClient`.
@@ -218,83 +192,11 @@ available.
 - [`avoid-process-env`](patterns/avoid-process-env.md): Replaces direct environment access with Effect Config.
 - [`prefer-redacted-config`](patterns/prefer-redacted-config.md): Requires secret-like configuration values to remain redacted.
 
-#### React And Testing Conventions
+#### React and testing conventions
 
 - [`avoid-react-hooks`](patterns/avoid-react-hooks.md): Reviews React state and effects for Effect Atom alternatives.
 - [`avoid-expect-in-if`](patterns/avoid-expect-in-if.md): Prevents conditional assertions that allow tests to pass without checking behavior.
 
-## Per-Agent Opt-Out
-
-Set `opencode-effect-enforcer: false` in an agent's `request.body` when that
-agent does not write Effect code. The plugin consumes the setting before the
-request reaches the model provider.
-
-```jsonc
-{
-  "agents": {
-    "researcher": {
-      "description": "Handles non-code research",
-      "mode": "subagent",
-      "request": {
-        "body": {
-          "opencode-effect-enforcer": false,
-        },
-      },
-    },
-  },
-}
-```
-
-For opted-out agents, the plugin does not inject guidance, advertise or allow
-its `effect-*` skills, or run post-write pattern enforcement.
-
-To disable the plugin entirely without removing its package entry, add a later
-selector using the exported plugin ID:
-
-```jsonc
-{
-  "plugins": ["opencode-effect-enforcer", "-opencode.effect-enforcer"],
-}
-```
-
-## Enforcement Semantics
-
-Patterns run only after successful writes. For edits and patches, the plugin
-captures the original files and computes changed spans from the final output,
-so it does not report a pre-existing violation outside newly added text.
-Full-file writes and new files treat the complete result as changed.
-
-The matcher supports TypeScript and TSX ast-grep rules, regex detectors with
-comment filtering, include and ignore globs, severity ordering, and targeted
-skill suggestions. Inspection failures remain advisory and never convert a
-successful write into a failed tool call.
-
-## Development
-
-```sh
-bun install
-bun run check
-bun run test
-```
-
-The tests enforce a bidirectional pattern/test inventory and require every
-skill, pattern, and guidance source to remain linked from this README.
-
-GitHub releases are automatically verified and published to npm with provenance.
-The release tag must exactly match the package version, such as `v0.2.0` for
-`"version": "0.2.0"`.
-
-There is no generated `dist` tree. OpenCode imports the TypeScript entrypoint,
-and npm publishes the authoritative `src/`, `skills/`, `guidance/`, `patterns/`,
-and `docs/` directories directly.
-
-## Credits
-
-This project is the OpenCode V2 port of
-[`pi-effect-harness`](https://github.com/mpsuesser/pi-effect-harness). It keeps
-the source guidance and pattern policy while using OpenCode's native skills,
-context hooks, and package loading.
-
 ## License
 
 [MIT](LICENSE)