@dokebi/module 0.4.0 → 0.4.2

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.
@@ -0,0 +1,3 @@
1
+ import type { ModuleGroupApi } from './index.js';
2
+ export declare const provider: import("@dokebi/core").ProviderDescriptor<ModuleGroupApi>;
3
+ export declare const dependency: import("@dokebi/core").PluginDependency<ModuleGroupApi>;
@@ -0,0 +1,10 @@
1
+ // The module group as a dependency (D-0199): an app's routes read the group API with
2
+ // `app.getDependency(dependency)` — `data.routes(route)` mounts the general read of the data sources.
3
+ import { defineProvider } from '@dokebi/core';
4
+ export const provider = defineProvider({
5
+ name: 'dokebi-module',
6
+ packageName: '@dokebi/module',
7
+ version: '^0.4.2',
8
+ load: () => import('./index.js'),
9
+ });
10
+ export const dependency = provider.dependency;
package/dist/index.d.ts CHANGED
@@ -1,17 +1,29 @@
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
+ import { type ActionApi, type ActionErrorCode } from './action-api.js';
8
+ import { type DescribedModule, type ModuleContract, type ModuleContractFields } from './contract.js';
9
+ import { type DataApi, type DataErrorCode } from './data-api.js';
10
+ export { ACTION_LIMITS, type ActionActor, type ActionField, type ActionFieldProblem, type ActionRun, type ActionTextFormat, checkInput, inputSchema, type ModuleAction, TEXT_FORMATS, } from './action.js';
11
+ export { type ActionApi, type ActionBody, type ActionEntry, type ActionErrorCode, type ActionHandler, type ActionResult, type ActionRouter, ActionValidationError, actionConflict, actionError, actionInvalid, actorOf, runAction, } from './action-api.js';
12
+ export { CONTRACT_LIMITS, type DescribedAction, type DescribedDataSource, type DescribedModule, islandName, type ModuleContract, type ModuleContractFields, type ModuleDataSource, type ModuleMenuEntry, type ModuleMenuItem, type ModulePermission, type ModulePreset, type ModuleText, type ModuleWidget, type ModuleWidgetLoadInput, } from './contract.js';
13
+ export { type DataApi, type DataErrorCode, type DataHandler, type DataPage, type DataRouter, dataError, } from './data-api.js';
14
+ export { CHOICE_TONES, type ChoiceTone, checkQuery, DATA_LIMITS, type DataAction, type DataField, type DataFieldType, type DataFilter, type DataFilterKind, type DataFilterValue, type DataRow, type DataSearch, type DataSort, type DataSourceRead, type DataValue, decodeCursor, encodeCursor, FIELD_TYPES, type ReadSql, readSql, } from './data-source.js';
15
+ export { checkParts, type ModulePart, type ModuleParts, PART_KINDS, PARTS_LIMITS, type PartEvent, type PartKind, type PartProp, type PartSlot, PartsIssue, type PartText, type PartVariant, readParts, } from './parts.js';
16
+ export { checkPresetApp, isSiteFile, PRESET_APP_KEYS, PRESET_KINDS, PRESET_LIMITS, type PresetKind, } from './preset.js';
7
17
  /** 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';
18
+ export type ModuleErrorCode = 'INVALID_DEFINITION' | 'INVALID_REQUIREMENT' | 'INVALID_ENTRY' | 'ALREADY_SET_UP' | 'NOT_SET_UP' | 'NO_CONTROLLERS' | 'VIEWS_MISSING' | 'INVALID_CONTRIBUTION' | 'UNDECLARED_POINT' | 'INVALID_CONTRACT' | 'MODULE_MISSING' | DataErrorCode | ActionErrorCode;
9
19
  /** A plugin instance (read with context.get) or a descriptor (read with context.getDependency). */
10
20
  export type ModuleRequirement = Plugin<unknown> | PluginDependency;
11
21
  /** The plugin context of a module, plus the controllers the module declares. */
12
22
  export interface ModuleContext extends PluginContext {
13
23
  /** The module name (the folder name under src/shared/modules). */
14
24
  readonly module: string;
25
+ /** The checked contract of the module (D-0197): what `@dokebi/module/mcp` reads its actions from. */
26
+ readonly contract: ModuleContract;
15
27
  controller<T>(definition: ControllerDefinition<T>): T;
16
28
  }
17
29
  /** What a module route handler receives besides the Fastify request and reply (D-0032). */
@@ -52,6 +64,10 @@ export interface ModuleRouter {
52
64
  */
53
65
  export interface ModuleSocketRoute {
54
66
  readonly path: string;
67
+ /** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
68
+ readonly config?: {
69
+ readonly id?: string;
70
+ };
55
71
  readonly constraints?: Readonly<Record<string, unknown>>;
56
72
  /**
57
73
  * `namespace` (D-0061): one of the mounting app's `realtime.namespaces` (default its first);
@@ -69,19 +85,30 @@ export interface ModuleSocketRoute {
69
85
  */
70
86
  export interface ModuleEventRoute {
71
87
  readonly path: string;
88
+ /** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
89
+ readonly config?: {
90
+ readonly id?: string;
91
+ };
72
92
  readonly constraints?: Readonly<Record<string, unknown>>;
73
93
  authenticate(request: FastifyRequest): Awaitable<{
74
94
  readonly tenant: string;
75
95
  readonly namespace?: string;
76
96
  } | undefined>;
77
97
  }
78
- export interface ModuleDefinition<T> {
98
+ export interface ModuleDefinition<T> extends ModuleContractFields {
79
99
  readonly name: string;
80
100
  /** Exact plugin version of this module. Default '0.1.0'. */
81
101
  readonly version?: string;
82
102
  readonly requires?: readonly ModuleRequirement[];
83
103
  /** `defineController` tokens, built once with this module's context. */
84
104
  readonly controllers?: readonly ControllerDefinition<unknown>[];
105
+ /**
106
+ * Points this module contributes to (D-0130), made by `definePoint` and imported from the
107
+ * plugin that owns them (for example `mcpTools` of @dokebi/mcp). The module's setup calls
108
+ * `module.contribute(point, value)`; core sets the module up before every collector of the
109
+ * point. Values that no registered plugin collects are dropped with warn `POINT_NOT_COLLECTED`.
110
+ */
111
+ readonly contributes?: readonly Pick<ContributionPoint<unknown>, 'name'>[];
85
112
  /** Folder with one sub-folder per template (`default/` is required). */
86
113
  readonly views?: URL;
87
114
  /** Routes registered by every app that mounts this module (`defineApp({ modules })`). */
@@ -109,6 +136,10 @@ export interface ModuleMount {
109
136
  readonly events: ModuleDefinition<unknown>['events'];
110
137
  /** The module context; available once the module has been set up. */
111
138
  context(): ModuleContext;
139
+ /** The checked contract (D-0197): what the module declares about itself. */
140
+ readonly contract: ModuleContract;
141
+ /** The module as `dokebi describe --json` gives it (reads its folders and widget templates). */
142
+ describe(): Promise<DescribedModule>;
112
143
  }
113
144
  export declare const MODULE_MOUNT: unique symbol;
114
145
  export declare function defineModule<T = void>(definition: ModuleDefinition<T>): Plugin<T>;
@@ -119,5 +150,14 @@ export interface ModuleEntry {
119
150
  }
120
151
  export interface ModuleGroupApi {
121
152
  readonly names: readonly string[];
153
+ /**
154
+ * The mount of a module of this group by its name (`members`), or undefined (D-0198): what an
155
+ * app runtime such as @dokebi/pages reads to draw the module's widgets.
156
+ */
157
+ module(name: string): ModuleMount | undefined;
158
+ /** The data sources of the modules (D-0199): the general read and its route. */
159
+ readonly data: DataApi;
160
+ /** The actions of the modules (D-0202): the general write and its route. */
161
+ readonly actions: ActionApi;
122
162
  }
123
163
  export declare const createPlugin: import("@dokebi/core").PluginFactory<ModuleGroupApi>;
package/dist/index.js CHANGED
@@ -1,8 +1,18 @@
1
1
  import { stat } from 'node:fs/promises';
2
2
  import { fileURLToPath } from 'node:url';
3
3
  import { types } from 'node:util';
4
- import { DokebiError, definePlugin, dependencyOf, providerDependency, } from '@dokebi/core';
4
+ import { DokebiError, definePlugin, definePoint, dependencyOf, providerDependency, } from '@dokebi/core';
5
+ import { createActionApi, } from './action-api.js';
6
+ import { CONTRACT_KEYS, ContractIssue, describeContract, readContract, readPresets, readTemplate, } from './contract.js';
7
+ import { createDataApi } from './data-api.js';
5
8
  import { options } from './options.js';
9
+ export { ACTION_LIMITS, checkInput, inputSchema, TEXT_FORMATS, } from './action.js';
10
+ export { ActionValidationError, actionConflict, actionError, actionInvalid, actorOf, runAction, } from './action-api.js';
11
+ export { CONTRACT_LIMITS, islandName, } from './contract.js';
12
+ export { dataError, } from './data-api.js';
13
+ export { CHOICE_TONES, checkQuery, DATA_LIMITS, decodeCursor, encodeCursor, FIELD_TYPES, readSql, } from './data-source.js';
14
+ export { checkParts, PART_KINDS, PARTS_LIMITS, PartsIssue, readParts, } from './parts.js';
15
+ export { checkPresetApp, isSiteFile, PRESET_APP_KEYS, PRESET_KINDS, PRESET_LIMITS, } from './preset.js';
6
16
  const FIX = {
7
17
  INVALID_DEFINITION: 'Pass defineModule a lower-case name (a-z, 0-9, ., _, -) and only the documented fields: requires and controllers arrays, views as a file: URL, hooks as functions.',
8
18
  INVALID_REQUIREMENT: 'List plugin instances or dependency descriptors ({ name, version }) in requires, each name once.',
@@ -11,21 +21,36 @@ const FIX = {
11
21
  NOT_SET_UP: 'Read the module context after the module plugin has set up.',
12
22
  NO_CONTROLLERS: 'Add the controller token to controllers of defineModule before calling module.controller().',
13
23
  VIEWS_MISSING: 'Create the views/default/ folder of the module (the cause names the file system error), or remove views.',
24
+ 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).',
25
+ 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.',
26
+ INVALID_CONTRACT: 'Correct the contract fields of defineModule as the message says (AI.md of @dokebi/module, section 2a): titles, permission keys <module>.<action>, data source, action (input fields, permission, danger with preview), widget and menu names, file: URLs for db, locales and widget templates (.html, at most 64 KB).',
27
+ MODULE_MISSING: 'Add the module the message names to the project (npx dokebi module add <name>, or its package), or remove it from modules of the module that needs it.',
14
28
  };
15
- function moduleError(code, message, cause) {
29
+ function moduleError(code, message, cause, fix = FIX[code]) {
16
30
  return new DokebiError(code, message, {
17
31
  plugin: 'dokebi-module',
18
- fix: FIX[code],
32
+ fix,
19
33
  ...(cause === undefined ? {} : { cause }),
20
34
  });
21
35
  }
22
36
  export const MODULE_MOUNT = Symbol.for('dokebi.module.mount');
23
37
  const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
38
+ /** Module plugins are `dokebi-module.<name>` (D-0032). */
39
+ const MODULE_PREFIX = 'dokebi-module.';
40
+ /**
41
+ * The `core:describe` point of @dokebi/core 0.4.2, declared here by name (its identity) so this
42
+ * package keeps working with older cores, which never describe.
43
+ */
44
+ const describePoint = definePoint('core:describe');
45
+ /** core's point name (`<owner plugin>:<name>`) and its limit per plugin (D-0063). */
46
+ const POINT_NAME = /^[a-z0-9][a-z0-9._/-]{0,95}:[a-z0-9][a-z0-9._-]{0,63}$/;
47
+ const POINT_LIMIT = 64;
24
48
  const DEFINITION_KEYS = new Set([
25
49
  'name',
26
50
  'version',
27
51
  'requires',
28
52
  'controllers',
53
+ 'contributes',
29
54
  'views',
30
55
  'routes',
31
56
  'sockets',
@@ -33,6 +58,7 @@ const DEFINITION_KEYS = new Set([
33
58
  'setup',
34
59
  'start',
35
60
  'drain',
61
+ ...CONTRACT_KEYS,
36
62
  ]);
37
63
  const ejs = providerDependency({
38
64
  name: 'dokebi-template-ejs',
@@ -49,11 +75,32 @@ function requirement(value) {
49
75
  throw moduleError('INVALID_REQUIREMENT', 'Invalid module requirement');
50
76
  return value;
51
77
  }
52
- function moduleContext(context, name, declared, controllers) {
78
+ /** The point names of `contributes` (D-0130): made by definePoint, distinct, at most 64. */
79
+ function contributedPoints(value, module) {
80
+ if (value === undefined)
81
+ return Object.freeze([]);
82
+ const invalid = (detail) => moduleError('INVALID_CONTRIBUTION', `Invalid contributes of module ${module}: ${detail}`);
83
+ if (!Array.isArray(value) || types.isProxy(value))
84
+ throw invalid('expected an array of points');
85
+ if (value.length > POINT_LIMIT)
86
+ throw invalid(`more than ${POINT_LIMIT} points`);
87
+ const names = new Set();
88
+ for (const point of value) {
89
+ const name = point?.name;
90
+ if (typeof name !== 'string' || !POINT_NAME.test(name))
91
+ throw invalid('a point made by definePoint (<owner plugin>:<name>) was expected');
92
+ if (names.has(name))
93
+ throw invalid(`${name} is listed twice`);
94
+ names.add(name);
95
+ }
96
+ return Object.freeze([...names]);
97
+ }
98
+ function moduleContext(context, name, declared, controllers, points, contract) {
53
99
  // core accepts only the descriptor object this module declared; look it up by name.
54
100
  const own = (dependency) => declared.get(dependency?.name) ?? dependency;
55
101
  return Object.freeze({
56
102
  module: name,
103
+ contract,
57
104
  get app() {
58
105
  return context.app;
59
106
  },
@@ -66,16 +113,29 @@ function moduleContext(context, name, declared, controllers) {
66
113
  get drainSignal() {
67
114
  return context.drainSignal;
68
115
  },
116
+ // Set when the drain phase starts: read it there, not at setup.
117
+ get drainDeadline() {
118
+ return context.drainDeadline;
119
+ },
69
120
  // The same frozen object for the whole application (core's own).
70
121
  runtime: context.runtime,
71
122
  get: (plugin) => context.get(plugin),
72
123
  getDependency: (dependency) => context.getDependency(own(dependency)),
73
124
  getOptionalDependency: (dependency) => context.getOptionalDependency(own(dependency)),
74
125
  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),
126
+ // D-0130: a module contributes to the points of its `contributes`; core then checks the
127
+ // phase (CONTRIBUTIONS_CLOSED outside the module's setup) and orders the collectors after it.
128
+ contribute: (point, value) => {
129
+ const pointName = point?.name;
130
+ if (typeof pointName === 'string' && POINT_NAME.test(pointName) && !points.has(pointName))
131
+ throw moduleError('UNDECLARED_POINT', `Module ${name} does not declare the point ${pointName}`, undefined, `Add ${pointName} to contributes of defineModule({ name: '${name}', contributes: [...] }).`);
132
+ context.contribute(point, value);
133
+ },
134
+ // Modules never collect: reading a point is a plugin's role (definePlugin collects).
135
+ collect: (point) => {
136
+ const pointName = point?.name;
137
+ 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.');
138
+ },
79
139
  controller: (definition) => {
80
140
  const api = controllers();
81
141
  if (!api)
@@ -100,7 +160,21 @@ export function defineModule(definition) {
100
160
  ['routes', 'sockets', 'events', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
101
161
  throw moduleError('INVALID_DEFINITION', 'Invalid module definition');
102
162
  const { name, views } = definition;
163
+ let contract;
164
+ try {
165
+ contract = readContract(name, definition);
166
+ }
167
+ catch (error) {
168
+ if (error instanceof ContractIssue)
169
+ throw moduleError('INVALID_CONTRACT', error.message);
170
+ throw error;
171
+ }
172
+ const points = contributedPoints(definition.contributes, name);
173
+ const pointSet = new Set(points);
103
174
  const dependencies = (definition.requires ?? []).map(requirement);
175
+ // D-0197: the modules it needs by name and range; core refuses the start without them.
176
+ for (const [other, range] of Object.entries(contract.modules))
177
+ dependencies.push(Object.freeze({ name: MODULE_PREFIX + other, version: range }));
104
178
  if (new Set(dependencies.map((dependency) => dependency.name)).size !== dependencies.length)
105
179
  throw moduleError('INVALID_REQUIREMENT', 'Duplicate module requirement');
106
180
  if (views && !dependencies.some((dependency) => dependency.name === ejs.name))
@@ -114,7 +188,7 @@ export function defineModule(definition) {
114
188
  const prefix = `module.${name}`;
115
189
  const hook = (key) => async (context) => {
116
190
  const begin = performance.now();
117
- await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers));
191
+ await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers, pointSet, contract));
118
192
  context.logger.log('debug', `Module ${key} finished`, {
119
193
  module: name,
120
194
  ms: Math.round(performance.now() - begin),
@@ -122,16 +196,18 @@ export function defineModule(definition) {
122
196
  };
123
197
  const plugin = {
124
198
  metadata: Object.freeze({
125
- name: 'dokebi-module.' + name,
199
+ name: MODULE_PREFIX + name,
126
200
  version,
127
201
  core: '^0.4.0',
128
202
  dependencies: Object.freeze(dependencies),
203
+ // D-0130: declared when the module is defined, so core orders the collectors after it.
204
+ ...(points.length ? { contributes: points, uncollected: 'warn' } : {}),
129
205
  }),
130
206
  async setup(context) {
131
207
  if (started)
132
208
  throw moduleError('ALREADY_SET_UP', 'Create one module instance per Application');
133
209
  started = true;
134
- current = moduleContext(context, name, declared, () => controllers);
210
+ current = moduleContext(context, name, declared, () => controllers, pointSet, contract);
135
211
  const begin = performance.now();
136
212
  if (definition.controllers?.length) {
137
213
  const { createControllers } = await import('@dokebi/controller');
@@ -149,16 +225,44 @@ export function defineModule(definition) {
149
225
  throw moduleError('VIEWS_MISSING', `Module ${name} has no views/default/ folder`, failure);
150
226
  await context.getDependency(templates ?? ejs).addDirectory(views, prefix);
151
227
  }
228
+ // D-0197: a widget's first HTML must be readable and its settings valid before anything runs.
229
+ for (const [widget, item] of Object.entries(contract.widgets)) {
230
+ try {
231
+ await readTemplate(item.template);
232
+ }
233
+ catch (cause) {
234
+ throw moduleError('INVALID_CONTRACT', `The template of widget ${widget} of module ${name} cannot be read as UTF-8 HTML of at most 64 KB`, cause);
235
+ }
236
+ }
237
+ // dokebi-platform DEC-16: a preset folder must have the shape of an app folder before anything runs.
238
+ try {
239
+ await readPresets(name, contract.presets);
240
+ }
241
+ catch (error) {
242
+ if (error instanceof ContractIssue)
243
+ throw moduleError('INVALID_CONTRACT', error.message);
244
+ throw error;
245
+ }
246
+ // Throws INVALID_PLUGIN_OPTIONS (paths, never values) for settings that do not fit.
247
+ contract.settings?.read(context.app.config);
152
248
  const api = (await definition.setup?.(current));
153
249
  context.logger.log('debug', 'Module set up', {
154
250
  module: name,
155
251
  version,
156
252
  requires: dependencies.map((dependency) => dependency.name),
157
253
  controllers: definition.controllers?.length ?? 0,
254
+ contributes: points,
158
255
  views: views ? prefix : false,
159
256
  routes: Boolean(definition.routes),
160
257
  sockets: Boolean(definition.sockets),
161
258
  events: Boolean(definition.events),
259
+ modules: contract.modules,
260
+ permissions: Object.keys(contract.permissions).length,
261
+ dataSources: Object.keys(contract.dataSources),
262
+ actions: Object.keys(contract.actions),
263
+ widgets: Object.keys(contract.widgets),
264
+ menu: contract.menu.length,
265
+ settings: contract.settings?.section ?? false,
162
266
  ms: Math.round(performance.now() - begin),
163
267
  });
164
268
  return api;
@@ -177,6 +281,27 @@ export function defineModule(definition) {
177
281
  throw moduleError('NOT_SET_UP', `Module ${name} is not set up yet`);
178
282
  return current;
179
283
  },
284
+ contract,
285
+ describe: () => describeContract({
286
+ name,
287
+ version,
288
+ requires: dependencies
289
+ .map((dependency) => dependency.name)
290
+ .filter((dependency) => !dependency.startsWith(MODULE_PREFIX)),
291
+ contributes: points,
292
+ views: views ? prefix : undefined,
293
+ hooks: {
294
+ routes: Boolean(definition.routes),
295
+ sockets: Boolean(definition.sockets),
296
+ events: Boolean(definition.events),
297
+ },
298
+ contract,
299
+ }).catch((error) => {
300
+ // A parts file that breaks its rules (D-0203) is found here, when it is read.
301
+ if (error instanceof ContractIssue)
302
+ throw moduleError('INVALID_CONTRACT', error.message);
303
+ throw error;
304
+ }),
180
305
  });
181
306
  Object.defineProperty(plugin, MODULE_MOUNT, { value: mount });
182
307
  return Object.freeze(plugin);
@@ -214,27 +339,94 @@ function parseEntry(input) {
214
339
  if (!Array.isArray(modules) || modules.length > LIMIT)
215
340
  throw moduleError('INVALID_ENTRY', 'Expected a modules array');
216
341
  const names = modules.map((module) => module?.metadata?.name);
217
- if (names.some((name) => typeof name !== 'string' || !name.startsWith('dokebi-module.')) ||
342
+ if (names.some((name) => typeof name !== 'string' || !name.startsWith(MODULE_PREFIX)) ||
218
343
  new Set(names).size !== names.length)
219
344
  throw moduleError('INVALID_ENTRY', 'Expected distinct module plugins');
345
+ // D-0197: a module that needs another one which is not in the project says so by name, before
346
+ // core's MISSING_DEPENDENCY (whose message only names the plugin).
347
+ const present = new Set(names);
348
+ for (const module of modules) {
349
+ const mount = moduleMount(module);
350
+ for (const [other, range] of Object.entries(mount?.contract?.modules ?? {}))
351
+ if (!present.has(MODULE_PREFIX + other))
352
+ throw moduleError('MODULE_MISSING', `Module ${mount?.name} needs module ${other} (${range}), which is not in the project`, undefined, `Add module ${other} to the project (npx dokebi module add ${other}, or install the package that provides it), or remove ${other} from modules of module ${mount?.name}.`);
353
+ }
220
354
  return [...modules];
221
355
  }
222
356
  class ModuleGroupRuntime {
223
357
  names;
224
- constructor(names) {
358
+ modules;
359
+ constructor(names, modules) {
225
360
  this.names = names;
361
+ this.modules = modules;
226
362
  }
227
363
  setup(context) {
228
364
  context.logger.log('debug', 'Modules registered', { modules: this.names });
229
- return Object.freeze({ names: this.names });
365
+ // D-0197: only `dokebi describe` (runtime.describing) asks; a normal start adds nothing.
366
+ if (context.runtime.describing) {
367
+ const mounts = this.modules
368
+ .map((module) => moduleMount(module))
369
+ .filter((mount) => mount !== undefined);
370
+ context.contribute(describePoint, {
371
+ section: 'modules',
372
+ describe: async () => {
373
+ const described = [];
374
+ for (const mount of mounts)
375
+ described.push(await mount.describe());
376
+ return described;
377
+ },
378
+ });
379
+ }
380
+ const byName = new Map();
381
+ for (const module of this.modules) {
382
+ const mount = moduleMount(module);
383
+ if (mount)
384
+ byName.set(mount.name, mount);
385
+ }
386
+ const sources = new Map();
387
+ for (const mount of byName.values())
388
+ for (const [name, declaration] of Object.entries(mount.contract?.dataSources ?? {}))
389
+ sources.set(`${mount.name}.${name}`, {
390
+ module: mount.name,
391
+ declaration,
392
+ context: () => mount.context(),
393
+ });
394
+ const data = createDataApi(sources, context.logger);
395
+ context.logger.log('debug', 'Data sources registered', { sources: data.ids });
396
+ const actions = new Map();
397
+ for (const mount of byName.values())
398
+ for (const [name, declaration] of Object.entries(mount.contract?.actions ?? {}))
399
+ actions.set(`${mount.name}.${name}`, {
400
+ id: `${mount.name}.${name}`,
401
+ module: mount.name,
402
+ declaration,
403
+ context: () => mount.context(),
404
+ });
405
+ // D-0202: a row action naming another module's action names one that module declares.
406
+ for (const mount of byName.values())
407
+ for (const [source, item] of Object.entries(mount.contract?.dataSources ?? {}))
408
+ for (const [name, rowAction] of Object.entries(item.actions ?? {})) {
409
+ const target = rowAction.action;
410
+ if (target?.includes('.') && !actions.has(target))
411
+ throw moduleError('INVALID_CONTRACT', `dataSources.${source}.actions.${name}.action of module ${mount.name} names ${target}, which no module of the project declares`);
412
+ }
413
+ const write = createActionApi(actions, context.logger);
414
+ context.logger.log('debug', 'Actions registered', { actions: write.ids });
415
+ return Object.freeze({
416
+ names: this.names,
417
+ module: (name) => byName.get(name),
418
+ data,
419
+ actions: write,
420
+ });
230
421
  }
231
422
  }
232
423
  export const createPlugin = definePlugin({
233
424
  name: 'dokebi-module',
234
- version: '0.4.0',
425
+ version: '0.4.2',
235
426
  core: '^0.4.0',
236
427
  options,
428
+ contributes: [describePoint],
237
429
  entry: parseEntry,
238
430
  dependencies: ({ entry }) => (entry ?? []).map((module) => dependencyOf(module)),
239
- instance: ({ dependencies }) => new ModuleGroupRuntime(Object.freeze(dependencies.map((dependency) => dependency.name))),
431
+ instance: ({ dependencies, entry }) => new ModuleGroupRuntime(Object.freeze(dependencies.map((dependency) => dependency.name)), Object.freeze([...(entry ?? [])])),
240
432
  });
@@ -0,0 +1,75 @@
1
+ /** A text, or a text per locale (`{ en: 'Button', ko: '단추' }`). */
2
+ export type PartText = string | Readonly<Record<string, string>>;
3
+ export declare const PART_KINDS: readonly ['component', 'directive', 'class', 'widget'];
4
+ export type PartKind = (typeof PART_KINDS)[number];
5
+ export interface PartProp {
6
+ readonly name: string;
7
+ /** The type as written (`'sm' | 'md'`, `boolean`, `UiOption[]`). */
8
+ readonly type: string;
9
+ readonly required: boolean;
10
+ /** The default as written (`'md'`, `false`, `() => []`), when there is one. */
11
+ readonly default?: string;
12
+ readonly description?: PartText;
13
+ }
14
+ export interface PartSlot {
15
+ readonly name: string;
16
+ /** What the slot hands its content (`{ row, value }`), when anything. */
17
+ readonly props?: string;
18
+ readonly description?: PartText;
19
+ }
20
+ export interface PartEvent {
21
+ readonly name: string;
22
+ /** The payload type (`[value: string]`), when there is one. */
23
+ readonly payload?: string;
24
+ readonly description?: PartText;
25
+ }
26
+ export interface PartVariant {
27
+ /** A class (`btn-primary`) or a prop value (`variant="outline"`). */
28
+ readonly name: string;
29
+ readonly description?: PartText;
30
+ }
31
+ export interface ModulePart {
32
+ /** `UiButton`, `v-truncate-tooltip`, `.btn`, or the widget's name. */
33
+ readonly name: string;
34
+ readonly kind: PartKind;
35
+ /** One line: what it is. */
36
+ readonly title: PartText;
37
+ readonly description?: PartText;
38
+ /** When to use it (and when not). */
39
+ readonly use?: PartText;
40
+ /** The source file, relative to the module folder. */
41
+ readonly file?: string;
42
+ readonly props?: readonly PartProp[];
43
+ readonly slots?: readonly PartSlot[];
44
+ readonly events?: readonly PartEvent[];
45
+ readonly variants?: readonly PartVariant[];
46
+ /** Markup to start from (Vue template or page HTML). */
47
+ readonly examples?: readonly string[];
48
+ /** Where its live sample is (`/ui#buttons`), an address of the app that shows the samples. */
49
+ readonly sample?: string;
50
+ /** kind `widget`: the widget of this module (`admin-header`). */
51
+ readonly widget?: string;
52
+ }
53
+ export interface ModuleParts {
54
+ readonly parts: readonly ModulePart[];
55
+ }
56
+ export declare const PARTS_LIMITS: Readonly<{
57
+ /** Bytes of the parts file. */
58
+ fileBytes: 2000000;
59
+ parts: 512;
60
+ /** Props, slots, events or variants of one part. */
61
+ members: 128;
62
+ examples: 16;
63
+ /** Characters of one text (a description, a type, a default). */
64
+ textChars: 2000;
65
+ /** Characters of one example. */
66
+ exampleChars: 8000;
67
+ locales: 32;
68
+ }>;
69
+ /** Thrown for a parts file that breaks a rule; the caller turns it into INVALID_CONTRACT. */
70
+ export declare class PartsIssue extends Error {
71
+ }
72
+ /** Checks parsed parts (`{ parts: [...] }`) against the module's widget names. */
73
+ export declare function checkParts(value: unknown, widgets: Iterable<string>, where?: string): ModuleParts;
74
+ /** Reads and checks a module's parts file (UTF-8 JSON of at most PARTS_LIMITS.fileBytes). */
75
+ export declare function readParts(file: URL, widgets: Iterable<string>): Promise<ModuleParts>;