anomalyco_opencode/packages/opencode/src/plug/README.md

plug

Type-only sketch for a cleaner plugin architecture.

This folder is intentionally not wired into the application yet. It exists so the shape of a redesign is easy to inspect without mixing design work with runtime changes.

Files

• common.ts shared helper types used by the rest of the sketch
• spec.ts plugin declaration and normalization types
• package.ts package metadata and capability inspection types
• module.ts imported module shape and validation types
• external.ts external plugin load pipeline types
• meta.ts plugin metadata store types
• install.ts install and config patch workflow types
• server.ts server plugin service types
• tui.ts TUI plugin manager service types

Reading order

If you want the sketch to build up from small concepts to runtime orchestration, read the files in this order:

1. spec.ts Start here for the basic nouns: plugin kinds, sources, declarations, config origins, and normalized candidates.
2. package.ts Next read how package metadata is described after a plugin target has been resolved.
3. module.ts Then read the imported module shapes and validation results for v1 and legacy modules.
4. external.ts This is the shared external loading pipeline that connects spec parsing, package inspection, and module import.
5. meta.ts Read this next to see what state should be persisted across runs and why it belongs behind a service.
6. install.ts This describes the install, manifest, and config patch workflow shared by CLI and TUI.
7. server.ts Read the server runtime service after the lower-level pipeline files, since it mainly composes those pieces.
8. tui.ts Read this last because it has the largest runtime surface and depends on most of the earlier concepts.
9. common.ts This file is only shared utility typing. You can skim it first or ignore it until you see a helper type you want to expand.

Intent

• Stateful parts are described as service interfaces.
• Stateless parts are described as function types returning Effect.
• The comments explain what each type is for and where it would sit in the architecture.