AGENTS.md@internal/modules · diff
git:20260715.158c111 to git:20260724.cb0170c
11 added, 26 removed. Audit A to A.
# Module Guide
- Interaction modules implement command, form, webhook, webservice, cron, page, and event entry points.
+ Interaction entry points: command, form, webhook, webservice, cron, page, event. Not provider clients.
- ## Structure
+ ## Entry points
```text
modules/<name>/
├── module.go # moduleHandler + module.Base, Register(), Init(), Rules(), Webservice()
- ├── command.go # Slash/chat commands
- ├── form.go # Interactive forms
- ├── webhook.go # HTTP webhooks
- ├── webservice.go # HTTP handlers
- ├── *_test.go # Tests (TDD: table-driven)
- └── utils.go # Helper functions
+ ├── command.go / form.go / webhook.go / webservice.go
+ ├── *_test.go
+ └── utils.go
```
- Module `Register()` functions are wired via `fx.Invoke` in `internal/modules/fx.go` (pulled into the server app through `modules.Modules`).
-
- ## Reference Implementation
-
- - When creating or modifying a module, reference `internal/modules/example/` for file structure, naming, and code style.
- - `module.go`: `moduleHandler` struct embedding `module.Base`, `Register()` → `module.Register(Name, &handler)`, `Init(jsonconf) error` with `configType{Enabled bool}`, `Rules() []any`, `Webservice(app)`
- - `webservice.go`: `webservice.Rule` definitions, route handlers call `capability.Invoke()`
- - `webhook.go`: Webhook route rule; hub modules may register webhooks directly in `Bootstrap()` via `EventSourceManager.RegisterWebhook()`
+ `Register()` wired via `fx.Invoke` in `internal/modules/fx.go` → `modules.Modules`. Reference: `internal/modules/example/`.
- ## Rules
+ ## Boundaries
- - Modules are interaction entry points, not provider clients
- - Do not import `pkg/providers/*` from `internal/modules/*` — use `capability.Invoke` or go through the adapter layer
- - New capability modules call `capability.Invoke`
- - Provider wiring happens inside the capability adapter (`pkg/capability/<provider>/adapter.go`), not in the module
- - Webservice routes: `/service/{module}/*` (see `pkg/route`), management: `/hub/*`
+ - Do not import `pkg/providers/*` — use `capability.Invoke`
+ - Provider wiring belongs in `pkg/capability/<provider>/adapter.go`
+ - Routes: `/service/{module}/*`; management: `/hub/*`
- Cross-service orchestration in Pipeline, not cron/event handlers
## Testing
- - Prefer a `*_test.go` counterpart for each non-trivial component
- - Table-driven tests with `require`/`assert`
- - BDD integration tests live under `tests/specs/` (Ginkgo v2 + Gomega)
- - Mock external dependencies
+ Table-driven unit tests; BDD under `tests/specs/`.