@dokebi/module 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AI.md CHANGED
@@ -1,6 +1,6 @@
1
- # AI guide — @dokebi/module 0.4.0
1
+ # AI guide — @dokebi/module
2
2
 
3
- A module is **one feature as a unit of business code** (D-0032). It keeps controllers, models, views, routes and sockets in one folder, and apps mount it under a prefix. Business code without a web side (job handlers, event subscriptions, shared APIs) is a module too. Node >=24.0.0, core ^0.4.0. Details are in the [README](README.md).
3
+ A module is **one feature as a unit of business code** (D-0032). It keeps controllers, services, models, views, routes and sockets in one folder, and apps mount it under a prefix. Business code without a web side (job handlers, event subscriptions, shared APIs) is a module too. Node >=24.0.0, core ^0.4.0. Details are in the [README](README.md).
4
4
 
5
5
  ## 1. Creating modules
6
6
 
@@ -20,7 +20,7 @@ A hand-made module folder is not registered. The generated registration code pas
20
20
  src/shared/modules/<module>/
21
21
  module.ts export default defineModule({ ... })
22
22
  routes.ts routes registered when an app mounts the module
23
- controllers/ models/ views/default/ (modules with pages) sockets/ (when needed)
23
+ controllers/ services/ models/ views/default/ (modules with pages) sockets/ (when needed)
24
24
  ```
25
25
 
26
26
  Do not scatter controllers, models and views into layer folders (`src/shared/controllers` and so on).
@@ -30,12 +30,14 @@ Do not scatter controllers, models and views into layer folders (`src/shared/con
30
30
  ```ts snippet
31
31
  import { defineModule } from '@dokebi/module';
32
32
  import { dependency as db } from '@dokebi/db';
33
+ import { mcpTools } from '@dokebi/mcp';
33
34
  import { postsController } from './controllers/posts.ts';
34
35
 
35
36
  export default defineModule({
36
37
  name: 'board', // the folder name; the plugin id is dokebi-module.board
37
38
  requires: [db], // instances, descriptors, other modules
38
39
  controllers: [postsController],
40
+ contributes: [mcpTools], // points of plugins this module contributes to (§3a)
39
41
  views: new URL('./views/', import.meta.url), // default/ is required (adds a template-ejs dependency)
40
42
  routes(route, module) { // registered for every app that mounts it, on that app's domains and prefix
41
43
  route.get('/', async (request, reply, page) =>
@@ -57,6 +59,7 @@ export default defineModule({
57
59
  - `controllers`: uses @dokebi/controller (optional peer). Calling `module.controller()` without controllers is `NO_CONTROLLERS` (`declares no controllers`).
58
60
  - `module.runtime` is core's runtime role (`solo`, `primary`, `worker`; D-0063 §4). Do not read `node:cluster` yourself.
59
61
  - Route options are `WebRoute` options without `handler` and `constraints` (`ModuleRouteOptions`, so `seal` works).
62
+ - `contributes`: the points of other plugins this module contributes to (§3a). Without it `module.contribute` is `UNDECLARED_POINT`.
60
63
 
61
64
  ## 3. Mounting on apps and shared APIs
62
65
 
@@ -65,6 +68,36 @@ export default defineModule({
65
68
  - APIs that must answer on every domain (such as `/api/*`) are not `routes`; register them in `setup` directly with `@dokebi/router` (`mount`) or web.
66
69
  - For another module or plugin to use this module's API, put this module into its `requires` and `get(module)`; it receives what `setup` returned.
67
70
 
71
+ ## 3a. Contributing to plugin points (MCP tools and others)
72
+
73
+ A module offers values to a plugin that collects a point ([D-0130](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0130-module-contributions.md); the points are core's, D-0063): MCP tools, prompts and resources of @dokebi/mcp (`mcpTools`, `mcpPrompts`, `mcpResources`), mail template folders, error translators. It is the same mechanism for every point; nothing is special to MCP.
74
+
75
+ ```ts snippet
76
+ import { dependency as db } from '@dokebi/db';
77
+ import { mcpTools } from '@dokebi/mcp';
78
+ import { defineModule } from '@dokebi/module';
79
+ import { DocumentService } from './services/documents.ts';
80
+ import { ListDocuments } from './tools/list-documents.ts';
81
+
82
+ export default defineModule({
83
+ name: 'workspace',
84
+ requires: [db],
85
+ contributes: [mcpTools], // declared when the module is defined
86
+ setup(module) {
87
+ const documents = new DocumentService(module.getDependency(db));
88
+ module.contribute(mcpTools, new ListDocuments(documents)); // the module's own service
89
+ return { documents }; // the module API: the same object
90
+ },
91
+ });
92
+ ```
93
+
94
+ - **Declared, not dynamic**: `contributes` becomes the module plugin's `metadata.contributes` when `defineModule` runs, before the app registers anything, so core checks every `module.contribute` against it and `npx dokebi describe` lists it (each plugin's `contributes` and `collects`, and a summary line per module point with its collector). Points made by `definePoint`, each once, at most 64 (`INVALID_CONTRIBUTION`).
95
+ - **Order**: core's rule for every contributor: the module sets up (and builds its services) before every plugin that collects the point, and drains after it; registration order does not matter. Contribute in `setup` only (in `start`, `drain` or a route it is core's `CONTRIBUTIONS_CLOSED`).
96
+ - **The module boundary holds**: the contributed objects get the services the module built; nothing builds them again. Another module that contributes tools for this one lists it in `requires` and reads `module.get(workspace).documents`. Never write a separate `definePlugin` that builds the services a second time, and never register an app plugin by hand in `src/main.ts` or `src/infra/runtime/application.ts` for this: `npx dokebi describe` and the tests build the app from the generated registration and do not see it, and doctor and check do not read it.
97
+ - **A module never collects**: `module.collect` is `UNDECLARED_POINT` (collecting is a plugin's role).
98
+ - **No collector**: when no registered plugin collects a point (its plugin is not installed, or a test app leaves it out), the start goes on, the values are dropped and the module hears warn `POINT_NOT_COLLECTED` once per point (`point`, `count`, `fix`). Module tests without the MCP stack keep working; `npx dokebi check` makes the missing plugin an error (`module-point-not-installed`).
99
+ - A module that `requires` the collector of a point it contributes to is a `DEPENDENCY_CYCLE` (the contributor must set up first). Values with rules of their own are checked by the collector (two tools with one name: @dokebi/mcp's `INVALID_TOOL`, naming both modules).
100
+
68
101
  ## 4. View lookup order (how an app changes a module page)
69
102
 
70
103
  1. `<app>/<template>/<module>/…`
@@ -82,18 +115,29 @@ To change a module page, an app never edits the module file; it puts a file with
82
115
  - Hooks: setup (register routes, return the API) → start → drain (stop new input, wait for work in progress) → deferred cleanup. Drain runs in reverse dependency order (modules that depend on this one first); unrelated modules drain at the same time.
83
116
  - A module instance is used by one Application only. There is no automatic discovery, dynamic import or hot reload while running.
84
117
  - Options of the group plugin are an empty object.
85
- - Debug logs (D-0047): `Modules registered` (the group), `Module set up` (requires, number of controllers, views prefix, whether routes, sockets and events exist, ms), `Module start finished`, `Module drain finished`. A missing or unreadable `views/default/` fails the start, with the original file error kept as `cause`.
118
+ - Debug logs (D-0047): `Modules registered` (the group), `Module set up` (requires, number of controllers, contributes, views prefix, whether routes, sockets and events exist, ms), `Module start finished`, `Module drain finished`. A missing or unreadable `views/default/` fails the start, with the original file error kept as `cause`.
86
119
 
87
120
  ## 6. Errors
88
121
 
89
122
  <!-- docs-check: complete-error-codes ModuleErrorCode -->
90
- `DokebiError` (`plugin: 'dokebi-module'`, a `fix` that says how to repair it): `INVALID_DEFINITION` (arguments of `defineModule`), `INVALID_REQUIREMENT` (shape of requires, duplicate names), `INVALID_ENTRY` (the group entry file; at registration the cause of `INVALID_PLUGIN_INPUT`), `ALREADY_SET_UP` (one instance in two apps), `NOT_SET_UP` (context used before setup), `NO_CONTROLLERS`, `VIEWS_MISSING` (no `views/default/`; the file error is the `cause`). Options of the group plugin other than an empty object are `INVALID_PLUGIN_OPTIONS` (cause `INVALID_OPTIONS`). The `defineOptions` declaration in `src/options.ts` is the parser, and the build writes `options.schema.json` from it (D-0063 §3; never edit it by hand). Before 0.4.0 the codes had a `MODULE_` prefix (D-0071).
123
+ `DokebiError` (`plugin: 'dokebi-module'`, a `fix` that says how to repair it): `INVALID_DEFINITION` (arguments of `defineModule`), `INVALID_REQUIREMENT` (shape of requires, duplicate names), `INVALID_ENTRY` (the group entry file; at registration the cause of `INVALID_PLUGIN_INPUT`), `ALREADY_SET_UP` (one instance in two apps), `NOT_SET_UP` (context used before setup), `NO_CONTROLLERS`, `VIEWS_MISSING` (no `views/default/`; the file error is the `cause`), `INVALID_CONTRIBUTION` (`contributes` is not a list of distinct points made by `definePoint`, or has more than 64), `UNDECLARED_POINT` (`module.contribute` to a point missing from `contributes`, or `module.collect`; the `fix` names the module). Warn log `POINT_NOT_COLLECTED` (core): values no registered plugin collects were dropped. Options of the group plugin other than an empty object are `INVALID_PLUGIN_OPTIONS` (cause `INVALID_OPTIONS`). The `defineOptions` declaration in `src/options.ts` is the parser, and the build writes `options.schema.json` from it (D-0063 §3; never edit it by hand). Before 0.4.0 the codes had a `MODULE_` prefix (D-0071).
91
124
 
92
125
  ## 7. Cautions
93
126
 
94
127
  - A module does not depend on apps (never branch on an app name). Handle per-app differences with `page.app` and the app's view overrides.
95
128
  - `moduleMount` and `MODULE_MOUNT` are the internal link @dokebi/app uses. App code does not use them.
96
- - Socket and SSE route types (`ModuleSocketRoute`, `ModuleEventRoute`) are defined by shape only, so projects that do not use them need neither @dokebi/websocket nor @dokebi/sse. When used, add that package (otherwise the app start fails: `has sockets; add @dokebi/websocket`, `has event streams; add @dokebi/sse`).
129
+ - Socket and SSE route types (`ModuleSocketRoute`, `ModuleEventRoute`) are defined by shape only, so projects that do not use them need neither @dokebi/websocket nor @dokebi/sse. When used, add that package (otherwise the app start fails: `has sockets; add @dokebi/websocket`, `has event streams; add @dokebi/sse`). Both take `config: { id }`, the route id (D-0140), like the module's routes: it must be unique among the routes, sockets and streams of each app that mounts the module (`DUPLICATE_ROUTE_ID` at start otherwise).
97
130
  - Do not treat the end of a response or a dropped connection as the work being done. Work detached from the request is awaited in the module's `drain`.
98
131
 
99
132
  References: `examples/26-scaffold` (repeated generation, mounting and overriding), `examples/25-playground` (eight feature modules; the sse module mounts `/api/sse/events` on every app through `events`), `examples/22-web/main.ts` (assembled in code), D-0022, D-0032.
133
+
134
+ ## Service composition
135
+
136
+ Use Controller -> Service -> Model for application data. Controllers handle HTTP input/output;
137
+ services provide data and coordinate workflows through models; models own persistence.
138
+ Generated app/module starters include this chain. Keep services free of request/reply and
139
+ rendering objects, and reuse them from jobs. Compose dependencies once during setup.
140
+ App-specific services belong in `src/apps/<app>/services`, cross-app services in
141
+ `src/shared/services`, and module services in `src/shared/modules/<module>/services`.
142
+ Shared services must not import app-specific code. These are ordinary application classes,
143
+ not a new framework plugin or service registry. Existing projects are not moved automatically.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # @dokebi/module 0.4.0
1
+ # @dokebi/module 0.4.1
2
2
 
3
- An optional package for Node >=24.0.0 and core ^0.4.0 (public on npm). A module is **one feature as an MVC unit of business code** ([D-0022](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0022-plugin-boundaries-and-db.md), [D-0032](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0032-feature-modules.md)). It keeps controllers, models, views, routes and sockets in one folder, and apps mount it under a prefix. It is not an HTTP-only bundle, so business code without a web side (job processing, event subscriptions) is a module too.
3
+ An optional package for Node >=24.0.0 and core ^0.4.0 (public on npm). A module is **one feature as an MVC unit of business code** ([D-0022](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0022-plugin-boundaries-and-db.md), [D-0032](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0032-feature-modules.md)). It keeps controllers, services, models, views, routes and sockets in one folder, and apps mount it under a prefix. It is not an HTTP-only bundle, so business code without a web side (job processing, event subscriptions) is a module too.
4
4
 
5
5
  ## Folder
6
6
 
@@ -23,6 +23,7 @@ export default defineModule({
23
23
  name: 'board', // the folder name; the ID is dokebi-module.board
24
24
  requires: [db, other], // plugin instances, descriptors, other modules
25
25
  controllers: [postsController], // created once with the module context
26
+ contributes: [mcpTools], // points of plugins it contributes to; module.contribute in setup
26
27
  views: new URL('./views/', import.meta.url), // default/ required; template names get the prefix module.board
27
28
  routes(route, module) { // registered per app (when mounted). page = { app, module, base, view, inertia }
28
29
  route.get('/', (request, reply, page) =>
@@ -42,6 +43,7 @@ export default defineModule({
42
43
  - **`views`:** adds a template-ejs dependency automatically. Without `views/default/` the start fails.
43
44
  - **`controllers`:** uses @dokebi/controller (optional peer). Calling `module.controller()` without controllers fails with `declares no controllers`.
44
45
  - **`setup`:** optional. The older `setup(context)` form still works.
46
+ - **`contributes`** ([D-0130](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0130-module-contributions.md)): the points of other plugins this module contributes to (for example `mcpTools` of @dokebi/mcp). `setup` calls `module.contribute(point, value)` with objects that use the module's own services; core sets the module up before every collector of the point. A point that nothing collects drops its values with warn `POINT_NOT_COLLECTED`; an undeclared point is `UNDECLARED_POINT`; modules never collect. See AI.md §3a.
45
47
  - **Shared APIs:** APIs that must answer on every domain are registered directly with router or web in setup, for example the playground's `/api/*`.
46
48
  - **Mounting on apps:** `defineApp({ modules: { '/board': board } })`. Routes and sockets answer only on that app's domains and prefix. A mounted module's API is readable with `app.get(board)` without listing it in the app's `requires`. Details are in [@dokebi/app](https://git.nyx-zone.com/dokebi/framework/-/blob/main/plugins/dokebi-app/README.md).
47
49
  - **View lookup order:**
@@ -76,3 +78,14 @@ Examples:
76
78
  - `examples/22-web/main.ts`: assembled in code
77
79
 
78
80
  See the [AI guide](AI.md) for errors and cautions.
81
+
82
+ ## Service composition
83
+
84
+ Use Controller -> Service -> Model for application data. Controllers handle HTTP input/output;
85
+ services provide data and coordinate workflows through models; models own persistence.
86
+ Generated app/module starters include this chain. Keep services free of request/reply and
87
+ rendering objects, and reuse them from jobs. Compose dependencies once during setup.
88
+ App-specific services belong in `src/apps/<app>/services`, cross-app services in
89
+ `src/shared/services`, and module services in `src/shared/modules/<module>/services`.
90
+ Shared services must not import app-specific code. These are ordinary application classes,
91
+ not a new framework plugin or service registry. Existing projects are not moved automatically.
package/dist/index.d.ts CHANGED
@@ -1,11 +1,11 @@
1
1
  import type { ControllerDefinition } from '@dokebi/controller';
2
- import { type Awaitable, type Plugin, type PluginContext, type PluginDependency } from '@dokebi/core';
2
+ import { type Awaitable, type ContributionPoint, type Plugin, type PluginContext, type PluginDependency } from '@dokebi/core';
3
3
  import type { TemplateApi } from '@dokebi/template-ejs';
4
4
  import type { InertiaApi } from '@dokebi/template-inertia';
5
5
  import type { WebRoute } from '@dokebi/web';
6
6
  import type { FastifyReply, FastifyRequest } from 'fastify';
7
7
  /** Codes of the errors this package throws (`DokebiError` with `plugin: 'dokebi-module'`). */
8
- export type ModuleErrorCode = 'INVALID_DEFINITION' | 'INVALID_REQUIREMENT' | 'INVALID_ENTRY' | 'ALREADY_SET_UP' | 'NOT_SET_UP' | 'NO_CONTROLLERS' | 'VIEWS_MISSING';
8
+ export type ModuleErrorCode = 'INVALID_DEFINITION' | 'INVALID_REQUIREMENT' | 'INVALID_ENTRY' | 'ALREADY_SET_UP' | 'NOT_SET_UP' | 'NO_CONTROLLERS' | 'VIEWS_MISSING' | 'INVALID_CONTRIBUTION' | 'UNDECLARED_POINT';
9
9
  /** A plugin instance (read with context.get) or a descriptor (read with context.getDependency). */
10
10
  export type ModuleRequirement = Plugin<unknown> | PluginDependency;
11
11
  /** The plugin context of a module, plus the controllers the module declares. */
@@ -52,6 +52,10 @@ export interface ModuleRouter {
52
52
  */
53
53
  export interface ModuleSocketRoute {
54
54
  readonly path: string;
55
+ /** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
56
+ readonly config?: {
57
+ readonly id?: string;
58
+ };
55
59
  readonly constraints?: Readonly<Record<string, unknown>>;
56
60
  /**
57
61
  * `namespace` (D-0061): one of the mounting app's `realtime.namespaces` (default its first);
@@ -69,6 +73,10 @@ export interface ModuleSocketRoute {
69
73
  */
70
74
  export interface ModuleEventRoute {
71
75
  readonly path: string;
76
+ /** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
77
+ readonly config?: {
78
+ readonly id?: string;
79
+ };
72
80
  readonly constraints?: Readonly<Record<string, unknown>>;
73
81
  authenticate(request: FastifyRequest): Awaitable<{
74
82
  readonly tenant: string;
@@ -82,6 +90,13 @@ export interface ModuleDefinition<T> {
82
90
  readonly requires?: readonly ModuleRequirement[];
83
91
  /** `defineController` tokens, built once with this module's context. */
84
92
  readonly controllers?: readonly ControllerDefinition<unknown>[];
93
+ /**
94
+ * Points this module contributes to (D-0130), made by `definePoint` and imported from the
95
+ * plugin that owns them (for example `mcpTools` of @dokebi/mcp). The module's setup calls
96
+ * `module.contribute(point, value)`; core sets the module up before every collector of the
97
+ * point. Values that no registered plugin collects are dropped with warn `POINT_NOT_COLLECTED`.
98
+ */
99
+ readonly contributes?: readonly Pick<ContributionPoint<unknown>, 'name'>[];
85
100
  /** Folder with one sub-folder per template (`default/` is required). */
86
101
  readonly views?: URL;
87
102
  /** Routes registered by every app that mounts this module (`defineApp({ modules })`). */
package/dist/index.js CHANGED
@@ -11,21 +11,27 @@ const FIX = {
11
11
  NOT_SET_UP: 'Read the module context after the module plugin has set up.',
12
12
  NO_CONTROLLERS: 'Add the controller token to controllers of defineModule before calling module.controller().',
13
13
  VIEWS_MISSING: 'Create the views/default/ folder of the module (the cause names the file system error), or remove views.',
14
+ INVALID_CONTRIBUTION: 'List in contributes the points made by definePoint that the module contributes to, each once and at most 64 (import them from the plugin that owns them, as mcpTools from @dokebi/mcp).',
15
+ UNDECLARED_POINT: 'Add the point to contributes of defineModule and call module.contribute(point, value) in the setup of the module. Modules only contribute: a plugin collects.',
14
16
  };
15
- function moduleError(code, message, cause) {
17
+ function moduleError(code, message, cause, fix = FIX[code]) {
16
18
  return new DokebiError(code, message, {
17
19
  plugin: 'dokebi-module',
18
- fix: FIX[code],
20
+ fix,
19
21
  ...(cause === undefined ? {} : { cause }),
20
22
  });
21
23
  }
22
24
  export const MODULE_MOUNT = Symbol.for('dokebi.module.mount');
23
25
  const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
26
+ /** core's point name (`<owner plugin>:<name>`) and its limit per plugin (D-0063). */
27
+ const POINT_NAME = /^[a-z0-9][a-z0-9._/-]{0,95}:[a-z0-9][a-z0-9._-]{0,63}$/;
28
+ const POINT_LIMIT = 64;
24
29
  const DEFINITION_KEYS = new Set([
25
30
  'name',
26
31
  'version',
27
32
  'requires',
28
33
  'controllers',
34
+ 'contributes',
29
35
  'views',
30
36
  'routes',
31
37
  'sockets',
@@ -49,7 +55,27 @@ function requirement(value) {
49
55
  throw moduleError('INVALID_REQUIREMENT', 'Invalid module requirement');
50
56
  return value;
51
57
  }
52
- function moduleContext(context, name, declared, controllers) {
58
+ /** The point names of `contributes` (D-0130): made by definePoint, distinct, at most 64. */
59
+ function contributedPoints(value, module) {
60
+ if (value === undefined)
61
+ return Object.freeze([]);
62
+ const invalid = (detail) => moduleError('INVALID_CONTRIBUTION', `Invalid contributes of module ${module}: ${detail}`);
63
+ if (!Array.isArray(value) || types.isProxy(value))
64
+ throw invalid('expected an array of points');
65
+ if (value.length > POINT_LIMIT)
66
+ throw invalid(`more than ${POINT_LIMIT} points`);
67
+ const names = new Set();
68
+ for (const point of value) {
69
+ const name = point?.name;
70
+ if (typeof name !== 'string' || !POINT_NAME.test(name))
71
+ throw invalid('a point made by definePoint (<owner plugin>:<name>) was expected');
72
+ if (names.has(name))
73
+ throw invalid(`${name} is listed twice`);
74
+ names.add(name);
75
+ }
76
+ return Object.freeze([...names]);
77
+ }
78
+ function moduleContext(context, name, declared, controllers, points) {
53
79
  // core accepts only the descriptor object this module declared; look it up by name.
54
80
  const own = (dependency) => declared.get(dependency?.name) ?? dependency;
55
81
  return Object.freeze({
@@ -66,16 +92,29 @@ function moduleContext(context, name, declared, controllers) {
66
92
  get drainSignal() {
67
93
  return context.drainSignal;
68
94
  },
95
+ // Set when the drain phase starts: read it there, not at setup.
96
+ get drainDeadline() {
97
+ return context.drainDeadline;
98
+ },
69
99
  // The same frozen object for the whole application (core's own).
70
100
  runtime: context.runtime,
71
101
  get: (plugin) => context.get(plugin),
72
102
  getDependency: (dependency) => context.getDependency(own(dependency)),
73
103
  getOptionalDependency: (dependency) => context.getOptionalDependency(own(dependency)),
74
104
  defer: (cleanup) => context.defer(cleanup),
75
- // The module plugin declares no contribution points, so core answers these with its coded
76
- // errors (UNDECLARED_POINT, CONTRIBUTIONS_CLOSED); forwarded so ModuleContext stays a PluginContext.
77
- contribute: (point, value) => context.contribute(point, value),
78
- collect: (point) => context.collect(point),
105
+ // D-0130: a module contributes to the points of its `contributes`; core then checks the
106
+ // phase (CONTRIBUTIONS_CLOSED outside the module's setup) and orders the collectors after it.
107
+ contribute: (point, value) => {
108
+ const pointName = point?.name;
109
+ if (typeof pointName === 'string' && POINT_NAME.test(pointName) && !points.has(pointName))
110
+ throw moduleError('UNDECLARED_POINT', `Module ${name} does not declare the point ${pointName}`, undefined, `Add ${pointName} to contributes of defineModule({ name: '${name}', contributes: [...] }).`);
111
+ context.contribute(point, value);
112
+ },
113
+ // Modules never collect: reading a point is a plugin's role (definePlugin collects).
114
+ collect: (point) => {
115
+ const pointName = point?.name;
116
+ throw moduleError('UNDECLARED_POINT', `Module ${name} cannot collect ${typeof pointName === 'string' ? pointName : 'a point'}`, undefined, 'Modules only contribute. Collect the point in a plugin that declares it in collects (definePlugin), and give the module what it needs through requires.');
117
+ },
79
118
  controller: (definition) => {
80
119
  const api = controllers();
81
120
  if (!api)
@@ -100,6 +139,8 @@ export function defineModule(definition) {
100
139
  ['routes', 'sockets', 'events', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
101
140
  throw moduleError('INVALID_DEFINITION', 'Invalid module definition');
102
141
  const { name, views } = definition;
142
+ const points = contributedPoints(definition.contributes, name);
143
+ const pointSet = new Set(points);
103
144
  const dependencies = (definition.requires ?? []).map(requirement);
104
145
  if (new Set(dependencies.map((dependency) => dependency.name)).size !== dependencies.length)
105
146
  throw moduleError('INVALID_REQUIREMENT', 'Duplicate module requirement');
@@ -114,7 +155,7 @@ export function defineModule(definition) {
114
155
  const prefix = `module.${name}`;
115
156
  const hook = (key) => async (context) => {
116
157
  const begin = performance.now();
117
- await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers));
158
+ await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers, pointSet));
118
159
  context.logger.log('debug', `Module ${key} finished`, {
119
160
  module: name,
120
161
  ms: Math.round(performance.now() - begin),
@@ -126,12 +167,14 @@ export function defineModule(definition) {
126
167
  version,
127
168
  core: '^0.4.0',
128
169
  dependencies: Object.freeze(dependencies),
170
+ // D-0130: declared when the module is defined, so core orders the collectors after it.
171
+ ...(points.length ? { contributes: points, uncollected: 'warn' } : {}),
129
172
  }),
130
173
  async setup(context) {
131
174
  if (started)
132
175
  throw moduleError('ALREADY_SET_UP', 'Create one module instance per Application');
133
176
  started = true;
134
- current = moduleContext(context, name, declared, () => controllers);
177
+ current = moduleContext(context, name, declared, () => controllers, pointSet);
135
178
  const begin = performance.now();
136
179
  if (definition.controllers?.length) {
137
180
  const { createControllers } = await import('@dokebi/controller');
@@ -155,6 +198,7 @@ export function defineModule(definition) {
155
198
  version,
156
199
  requires: dependencies.map((dependency) => dependency.name),
157
200
  controllers: definition.controllers?.length ?? 0,
201
+ contributes: points,
158
202
  views: views ? prefix : false,
159
203
  routes: Boolean(definition.routes),
160
204
  sockets: Boolean(definition.sockets),
@@ -231,7 +275,7 @@ class ModuleGroupRuntime {
231
275
  }
232
276
  export const createPlugin = definePlugin({
233
277
  name: 'dokebi-module',
234
- version: '0.4.0',
278
+ version: '0.4.1',
235
279
  core: '^0.4.0',
236
280
  options,
237
281
  entry: parseEntry,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dokebi/module",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "Feature modules for Dokebi apps: controllers, models, views and routes in one folder mounted under a prefix.",
5
5
  "keywords": [
6
6
  "dokebi",
@@ -93,10 +93,10 @@
93
93
  }
94
94
  },
95
95
  "devDependencies": {
96
- "@dokebi/controller": "0.4.0",
97
- "@dokebi/template-ejs": "0.4.0",
98
- "@dokebi/template-inertia": "0.4.0",
99
- "@dokebi/web": "0.4.0"
96
+ "@dokebi/controller": "0.4.2",
97
+ "@dokebi/template-ejs": "0.4.3",
98
+ "@dokebi/template-inertia": "0.4.4",
99
+ "@dokebi/web": "0.4.3"
100
100
  },
101
101
  "publishConfig": {
102
102
  "access": "public",
@@ -1,11 +1,22 @@
1
1
  import { defineController } from '@dokebi/controller';
2
2
  import type { ModulePage } from '@dokebi/module';
3
- import { summary } from '../models/summary.ts';
3
+ import { ItemsService } from '../services/items.ts';
4
4
 
5
5
  export class ItemsController {
6
+ readonly #service: ItemsService;
7
+ constructor(service: ItemsService) {
8
+ this.#service = service;
9
+ }
6
10
  list(page: ModulePage) {
7
- return { title: '{{module}}', message: summary(page) };
11
+ return this.#service.list({
12
+ appName: page.app.name,
13
+ base: page.base,
14
+ template: page.app.template,
15
+ });
8
16
  }
9
17
  }
10
18
  // Built once with this module's context; read it with module.controller(itemsController).
11
- export const itemsController = defineController('items', () => new ItemsController());
19
+ export const itemsController = defineController(
20
+ 'items',
21
+ () => new ItemsController(new ItemsService()),
22
+ );
@@ -1,6 +1,6 @@
1
- import type { ModulePage } from '@dokebi/module';
1
+ export type ModuleIdentity = { appName: string; base: string; template: string };
2
2
 
3
- /** Models are plain code; controllers pass them what they need. */
4
- export function summary(page: ModulePage): string {
5
- return `{{module}} module in app ${page.app.name} at ${page.base || '/'} (template: ${page.app.template})`;
3
+ /** A pure model for this starter; services provide data without HTTP objects. */
4
+ export function summary(module: ModuleIdentity): string {
5
+ return `{{module}} module in app ${module.appName} at ${module.base || '/'} (template: ${module.template})`;
6
6
  }
@@ -11,6 +11,10 @@ export default defineModule({
11
11
  // Plugins and other modules this module uses (instances or dependency descriptors).
12
12
  requires: [],
13
13
  controllers: [itemsController],
14
+ // Points of plugins this module contributes to (D-0130), for example MCP tools:
15
+ // contributes: [mcpTools], // import { mcpTools } from '@dokebi/mcp'
16
+ // setup(module) { module.contribute(mcpTools, new ListItems(service)); },
17
+ // The contributed objects use this module's own services; the collector sets up after it.
14
18
  // One folder per template; `default` is required. An app replaces a file of this module by
15
19
  // putting it in src/apps/<app>/views/<template>/{{module}}/.
16
20
  views: new URL('./views/', import.meta.url),
@@ -0,0 +1,7 @@
1
+ import { type ModuleIdentity, summary } from '../models/summary.ts';
2
+
3
+ export class ItemsService {
4
+ list(module: ModuleIdentity) {
5
+ return { title: '{{module}}', message: summary(module) };
6
+ }
7
+ }
@@ -1,11 +1,22 @@
1
1
  import { defineController } from '@dokebi/controller';
2
2
  import type { ModulePage } from '@dokebi/module';
3
- import { summary } from '../models/summary.ts';
3
+ import { ItemsService } from '../services/items.ts';
4
4
 
5
5
  export class ItemsController {
6
+ readonly #service: ItemsService;
7
+ constructor(service: ItemsService) {
8
+ this.#service = service;
9
+ }
6
10
  list(page: ModulePage) {
7
- return { title: '{{module}}', message: summary(page) };
11
+ return this.#service.list({
12
+ appName: page.app.name,
13
+ base: page.base,
14
+ template: page.app.template,
15
+ });
8
16
  }
9
17
  }
10
18
  // Built once with this module's context; read it with module.controller(itemsController).
11
- export const itemsController = defineController('items', () => new ItemsController());
19
+ export const itemsController = defineController(
20
+ 'items',
21
+ () => new ItemsController(new ItemsService()),
22
+ );
@@ -1,6 +1,6 @@
1
- import type { ModulePage } from '@dokebi/module';
1
+ export type ModuleIdentity = { appName: string; base: string; template: string };
2
2
 
3
- /** Models are plain code; controllers pass them what they need. */
4
- export function summary(page: ModulePage): string {
5
- return `{{module}} module in app ${page.app.name} at ${page.base || '/'} (template: ${page.app.template})`;
3
+ /** A pure model for this starter; services provide data without HTTP objects. */
4
+ export function summary(module: ModuleIdentity): string {
5
+ return `{{module}} module in app ${module.appName} at ${module.base || '/'} (template: ${module.template})`;
6
6
  }
@@ -12,5 +12,9 @@ export default defineModule({
12
12
  // Plugins and other modules this module uses (instances or dependency descriptors).
13
13
  requires: [],
14
14
  controllers: [itemsController],
15
+ // Points of plugins this module contributes to (D-0130), for example MCP tools:
16
+ // contributes: [mcpTools], // import { mcpTools } from '@dokebi/mcp'
17
+ // setup(module) { module.contribute(mcpTools, new ListItems(service)); },
18
+ // The contributed objects use this module's own services; the collector sets up after it.
15
19
  routes,
16
20
  });
@@ -0,0 +1,7 @@
1
+ import { type ModuleIdentity, summary } from '../models/summary.ts';
2
+
3
+ export class ItemsService {
4
+ list(module: ModuleIdentity) {
5
+ return { title: '{{module}}', message: summary(module) };
6
+ }
7
+ }