@dokebi/module 0.4.2 → 0.4.4
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 +3 -244
- package/README.md +1 -5
- package/dist/index.d.ts +2 -27
- package/dist/index.js +13 -159
- package/package.json +3 -13
- package/dist/action-api.d.ts +0 -73
- package/dist/action-api.js +0 -249
- package/dist/action.d.ts +0 -152
- package/dist/action.js +0 -498
- package/dist/contract.d.ts +0 -305
- package/dist/contract.js +0 -524
- package/dist/data-api.d.ts +0 -49
- package/dist/data-api.js +0 -147
- package/dist/data-source.d.ts +0 -238
- package/dist/data-source.js +0 -742
- package/dist/dependency.d.ts +0 -3
- package/dist/dependency.js +0 -10
- package/dist/parts.d.ts +0 -75
- package/dist/parts.js +0 -231
- package/dist/preset.d.ts +0 -25
- package/dist/preset.js +0 -165
package/dist/index.js
CHANGED
|
@@ -1,18 +1,8 @@
|
|
|
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,
|
|
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';
|
|
4
|
+
import { DokebiError, definePlugin, dependencyOf, providerDependency, } from '@dokebi/core';
|
|
8
5
|
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';
|
|
16
6
|
const FIX = {
|
|
17
7
|
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.',
|
|
18
8
|
INVALID_REQUIREMENT: 'List plugin instances or dependency descriptors ({ name, version }) in requires, each name once.',
|
|
@@ -23,8 +13,6 @@ const FIX = {
|
|
|
23
13
|
VIEWS_MISSING: 'Create the views/default/ folder of the module (the cause names the file system error), or remove views.',
|
|
24
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).',
|
|
25
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.',
|
|
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.',
|
|
28
16
|
};
|
|
29
17
|
function moduleError(code, message, cause, fix = FIX[code]) {
|
|
30
18
|
return new DokebiError(code, message, {
|
|
@@ -35,13 +23,6 @@ function moduleError(code, message, cause, fix = FIX[code]) {
|
|
|
35
23
|
}
|
|
36
24
|
export const MODULE_MOUNT = Symbol.for('dokebi.module.mount');
|
|
37
25
|
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
26
|
/** core's point name (`<owner plugin>:<name>`) and its limit per plugin (D-0063). */
|
|
46
27
|
const POINT_NAME = /^[a-z0-9][a-z0-9._/-]{0,95}:[a-z0-9][a-z0-9._-]{0,63}$/;
|
|
47
28
|
const POINT_LIMIT = 64;
|
|
@@ -58,7 +39,6 @@ const DEFINITION_KEYS = new Set([
|
|
|
58
39
|
'setup',
|
|
59
40
|
'start',
|
|
60
41
|
'drain',
|
|
61
|
-
...CONTRACT_KEYS,
|
|
62
42
|
]);
|
|
63
43
|
const ejs = providerDependency({
|
|
64
44
|
name: 'dokebi-template-ejs',
|
|
@@ -95,12 +75,11 @@ function contributedPoints(value, module) {
|
|
|
95
75
|
}
|
|
96
76
|
return Object.freeze([...names]);
|
|
97
77
|
}
|
|
98
|
-
function moduleContext(context, name, declared, controllers, points
|
|
78
|
+
function moduleContext(context, name, declared, controllers, points) {
|
|
99
79
|
// core accepts only the descriptor object this module declared; look it up by name.
|
|
100
80
|
const own = (dependency) => declared.get(dependency?.name) ?? dependency;
|
|
101
81
|
return Object.freeze({
|
|
102
82
|
module: name,
|
|
103
|
-
contract,
|
|
104
83
|
get app() {
|
|
105
84
|
return context.app;
|
|
106
85
|
},
|
|
@@ -145,7 +124,9 @@ function moduleContext(context, name, declared, controllers, points, contract) {
|
|
|
145
124
|
});
|
|
146
125
|
}
|
|
147
126
|
export function defineModule(definition) {
|
|
148
|
-
|
|
127
|
+
// Read after the check below would be too late for the check itself; `?.` so that nothing
|
|
128
|
+
// (null, undefined) is INVALID_DEFINITION, not a TypeError (audit R9-g13-5).
|
|
129
|
+
const version = definition?.version ?? '0.1.0';
|
|
149
130
|
if (definition === null ||
|
|
150
131
|
typeof definition !== 'object' ||
|
|
151
132
|
types.isProxy(definition) ||
|
|
@@ -160,21 +141,9 @@ export function defineModule(definition) {
|
|
|
160
141
|
['routes', 'sockets', 'events', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
|
|
161
142
|
throw moduleError('INVALID_DEFINITION', 'Invalid module definition');
|
|
162
143
|
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
144
|
const points = contributedPoints(definition.contributes, name);
|
|
173
145
|
const pointSet = new Set(points);
|
|
174
146
|
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 }));
|
|
178
147
|
if (new Set(dependencies.map((dependency) => dependency.name)).size !== dependencies.length)
|
|
179
148
|
throw moduleError('INVALID_REQUIREMENT', 'Duplicate module requirement');
|
|
180
149
|
if (views && !dependencies.some((dependency) => dependency.name === ejs.name))
|
|
@@ -188,7 +157,7 @@ export function defineModule(definition) {
|
|
|
188
157
|
const prefix = `module.${name}`;
|
|
189
158
|
const hook = (key) => async (context) => {
|
|
190
159
|
const begin = performance.now();
|
|
191
|
-
await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers, pointSet
|
|
160
|
+
await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers, pointSet));
|
|
192
161
|
context.logger.log('debug', `Module ${key} finished`, {
|
|
193
162
|
module: name,
|
|
194
163
|
ms: Math.round(performance.now() - begin),
|
|
@@ -196,7 +165,7 @@ export function defineModule(definition) {
|
|
|
196
165
|
};
|
|
197
166
|
const plugin = {
|
|
198
167
|
metadata: Object.freeze({
|
|
199
|
-
name:
|
|
168
|
+
name: 'dokebi-module.' + name,
|
|
200
169
|
version,
|
|
201
170
|
core: '^0.4.0',
|
|
202
171
|
dependencies: Object.freeze(dependencies),
|
|
@@ -207,7 +176,7 @@ export function defineModule(definition) {
|
|
|
207
176
|
if (started)
|
|
208
177
|
throw moduleError('ALREADY_SET_UP', 'Create one module instance per Application');
|
|
209
178
|
started = true;
|
|
210
|
-
current = moduleContext(context, name, declared, () => controllers, pointSet
|
|
179
|
+
current = moduleContext(context, name, declared, () => controllers, pointSet);
|
|
211
180
|
const begin = performance.now();
|
|
212
181
|
if (definition.controllers?.length) {
|
|
213
182
|
const { createControllers } = await import('@dokebi/controller');
|
|
@@ -225,26 +194,6 @@ export function defineModule(definition) {
|
|
|
225
194
|
throw moduleError('VIEWS_MISSING', `Module ${name} has no views/default/ folder`, failure);
|
|
226
195
|
await context.getDependency(templates ?? ejs).addDirectory(views, prefix);
|
|
227
196
|
}
|
|
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);
|
|
248
197
|
const api = (await definition.setup?.(current));
|
|
249
198
|
context.logger.log('debug', 'Module set up', {
|
|
250
199
|
module: name,
|
|
@@ -256,13 +205,6 @@ export function defineModule(definition) {
|
|
|
256
205
|
routes: Boolean(definition.routes),
|
|
257
206
|
sockets: Boolean(definition.sockets),
|
|
258
207
|
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,
|
|
266
208
|
ms: Math.round(performance.now() - begin),
|
|
267
209
|
});
|
|
268
210
|
return api;
|
|
@@ -281,27 +223,6 @@ export function defineModule(definition) {
|
|
|
281
223
|
throw moduleError('NOT_SET_UP', `Module ${name} is not set up yet`);
|
|
282
224
|
return current;
|
|
283
225
|
},
|
|
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
|
-
}),
|
|
305
226
|
});
|
|
306
227
|
Object.defineProperty(plugin, MODULE_MOUNT, { value: mount });
|
|
307
228
|
return Object.freeze(plugin);
|
|
@@ -339,94 +260,27 @@ function parseEntry(input) {
|
|
|
339
260
|
if (!Array.isArray(modules) || modules.length > LIMIT)
|
|
340
261
|
throw moduleError('INVALID_ENTRY', 'Expected a modules array');
|
|
341
262
|
const names = modules.map((module) => module?.metadata?.name);
|
|
342
|
-
if (names.some((name) => typeof name !== 'string' || !name.startsWith(
|
|
263
|
+
if (names.some((name) => typeof name !== 'string' || !name.startsWith('dokebi-module.')) ||
|
|
343
264
|
new Set(names).size !== names.length)
|
|
344
265
|
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
|
-
}
|
|
354
266
|
return [...modules];
|
|
355
267
|
}
|
|
356
268
|
class ModuleGroupRuntime {
|
|
357
269
|
names;
|
|
358
|
-
|
|
359
|
-
constructor(names, modules) {
|
|
270
|
+
constructor(names) {
|
|
360
271
|
this.names = names;
|
|
361
|
-
this.modules = modules;
|
|
362
272
|
}
|
|
363
273
|
setup(context) {
|
|
364
274
|
context.logger.log('debug', 'Modules registered', { modules: this.names });
|
|
365
|
-
|
|
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
|
-
});
|
|
275
|
+
return Object.freeze({ names: this.names });
|
|
421
276
|
}
|
|
422
277
|
}
|
|
423
278
|
export const createPlugin = definePlugin({
|
|
424
279
|
name: 'dokebi-module',
|
|
425
|
-
version: '0.4.
|
|
280
|
+
version: '0.4.4',
|
|
426
281
|
core: '^0.4.0',
|
|
427
282
|
options,
|
|
428
|
-
contributes: [describePoint],
|
|
429
283
|
entry: parseEntry,
|
|
430
284
|
dependencies: ({ entry }) => (entry ?? []).map((module) => dependencyOf(module)),
|
|
431
|
-
instance: ({ dependencies
|
|
285
|
+
instance: ({ dependencies }) => new ModuleGroupRuntime(Object.freeze(dependencies.map((dependency) => dependency.name))),
|
|
432
286
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dokebi/module",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.4",
|
|
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",
|
|
@@ -18,10 +18,6 @@
|
|
|
18
18
|
".": {
|
|
19
19
|
"types": "./dist/index.d.ts",
|
|
20
20
|
"import": "./dist/index.js"
|
|
21
|
-
},
|
|
22
|
-
"./dependency": {
|
|
23
|
-
"types": "./dist/dependency.d.ts",
|
|
24
|
-
"import": "./dist/dependency.js"
|
|
25
21
|
}
|
|
26
22
|
},
|
|
27
23
|
"files": [
|
|
@@ -40,9 +36,6 @@
|
|
|
40
36
|
"typecheck": "tsc -p tsconfig.test.json --noEmit",
|
|
41
37
|
"test": "node -e \"require('node:fs').rmSync('.tmp/tests',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --test .tmp/tests/tests/*.test.js"
|
|
42
38
|
},
|
|
43
|
-
"dependencies": {
|
|
44
|
-
"yaml": "2.9.1"
|
|
45
|
-
},
|
|
46
39
|
"peerDependencies": {
|
|
47
40
|
"@dokebi/controller": "^0.4.0",
|
|
48
41
|
"@dokebi/core": "^0.4.0",
|
|
@@ -59,9 +52,6 @@
|
|
|
59
52
|
"hosts": [
|
|
60
53
|
"modules"
|
|
61
54
|
],
|
|
62
|
-
"contributes": [
|
|
63
|
-
"core:describe"
|
|
64
|
-
],
|
|
65
55
|
"install": {
|
|
66
56
|
"directories": [
|
|
67
57
|
"src/shared/modules"
|
|
@@ -105,8 +95,8 @@
|
|
|
105
95
|
"devDependencies": {
|
|
106
96
|
"@dokebi/controller": "0.4.2",
|
|
107
97
|
"@dokebi/template-ejs": "0.4.3",
|
|
108
|
-
"@dokebi/template-inertia": "0.4.
|
|
109
|
-
"@dokebi/web": "0.4.
|
|
98
|
+
"@dokebi/template-inertia": "0.4.7",
|
|
99
|
+
"@dokebi/web": "0.4.7"
|
|
110
100
|
},
|
|
111
101
|
"publishConfig": {
|
|
112
102
|
"access": "public",
|
package/dist/action-api.d.ts
DELETED
|
@@ -1,73 +0,0 @@
|
|
|
1
|
-
import { DokebiError, type Logger } from '@dokebi/core';
|
|
2
|
-
import { type ActionActor, type ActionFieldProblem, type ModuleAction } from './action.js';
|
|
3
|
-
/** Codes of the general write (`DokebiError`, `plugin: 'dokebi-module'`). */
|
|
4
|
-
export type ActionErrorCode = 'ACTION_NOT_FOUND' | 'FORBIDDEN' | 'INVALID_INPUT' | 'VALIDATION_FAILED' | 'ACTION_CONFLICT' | 'CONFIRM_REQUIRED' | 'CONFIRM_STALE' | 'ACTION_FAILED';
|
|
5
|
-
export declare function actionError(code: ActionErrorCode, message: string, data?: Readonly<Record<string, unknown>>, cause?: unknown): DokebiError<ActionErrorCode>;
|
|
6
|
-
/**
|
|
7
|
-
* 422 with the refused fields, in the shape @dokebi/web answers (`fields`, `errors`) and
|
|
8
|
-
* template-inertia turns into a validation redirect. `data.rules` names the rule per field.
|
|
9
|
-
*/
|
|
10
|
-
export declare class ActionValidationError extends DokebiError<ActionErrorCode> {
|
|
11
|
-
readonly fields: readonly {
|
|
12
|
-
readonly field: string;
|
|
13
|
-
readonly message: string;
|
|
14
|
-
}[];
|
|
15
|
-
readonly errors: Readonly<Record<string, string>>;
|
|
16
|
-
constructor(problems: readonly ActionFieldProblem[], action: string);
|
|
17
|
-
}
|
|
18
|
-
/**
|
|
19
|
-
* What a run throws when the row changed since the caller read it (the `version` it sent is not the
|
|
20
|
-
* stored one): 409 ACTION_CONFLICT. `data` may carry the stored version (`{ version }`).
|
|
21
|
-
*/
|
|
22
|
-
export declare function actionConflict(message?: string, data?: Readonly<Record<string, unknown>>): DokebiError<ActionErrorCode>;
|
|
23
|
-
/**
|
|
24
|
-
* What a run throws for a field the services refuse after the input check (a username that is
|
|
25
|
-
* taken): 422 VALIDATION_FAILED like the input check, `{ field: message }`.
|
|
26
|
-
*/
|
|
27
|
-
export declare function actionInvalid(fields: Readonly<Record<string, string>>, action?: string): ActionValidationError;
|
|
28
|
-
/** What one action answers. */
|
|
29
|
-
export interface ActionResult {
|
|
30
|
-
/** `<module>.<name>`. */
|
|
31
|
-
readonly action: string;
|
|
32
|
-
/** What the run returned (JSON: ids, counts), null when it returned nothing. */
|
|
33
|
-
readonly result: unknown;
|
|
34
|
-
}
|
|
35
|
-
/** The body the general write takes. */
|
|
36
|
-
export interface ActionBody {
|
|
37
|
-
readonly input?: Readonly<Record<string, unknown>>;
|
|
38
|
-
/** The confirm token of the preview of a dangerous action. */
|
|
39
|
-
readonly confirm?: string;
|
|
40
|
-
}
|
|
41
|
-
/** The app router as @dokebi/app hands it to `routes(route, app)` (typed by shape). */
|
|
42
|
-
export interface ActionRouter {
|
|
43
|
-
post(url: string, handler: ActionHandler, options?: {
|
|
44
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
45
|
-
}): void;
|
|
46
|
-
}
|
|
47
|
-
/** A route handler (Fastify request and reply), method-typed so any app router accepts it. */
|
|
48
|
-
export type ActionHandler = {
|
|
49
|
-
handle(request: unknown, reply: unknown, page: unknown): unknown;
|
|
50
|
-
}['handle'];
|
|
51
|
-
/** The actions of the module group (`ModuleGroupApi.actions`, D-0202). */
|
|
52
|
-
export interface ActionApi {
|
|
53
|
-
/** The ids of the actions (`members.update`). */
|
|
54
|
-
readonly ids: readonly string[];
|
|
55
|
-
/** Runs action `id` for `request` (its `auth` decides the permission) with `body`. */
|
|
56
|
-
run(request: unknown, id: string, body: ActionBody): Promise<ActionResult>;
|
|
57
|
-
/** Adds `POST <path>/:module/:action` (route id `module.action`) answering `run` as JSON. */
|
|
58
|
-
routes(route: ActionRouter, options?: {
|
|
59
|
-
readonly path?: string;
|
|
60
|
-
}): void;
|
|
61
|
-
}
|
|
62
|
-
/** One action as the runner knows it. */
|
|
63
|
-
export interface ActionEntry {
|
|
64
|
-
readonly id: string;
|
|
65
|
-
readonly module: string;
|
|
66
|
-
readonly declaration: ModuleAction;
|
|
67
|
-
context(): unknown;
|
|
68
|
-
}
|
|
69
|
-
/** Who asks: the AI client of an OAuth grant (@dokebi/oauth), else the signed-in user. */
|
|
70
|
-
export declare function actorOf(request: unknown): ActionActor;
|
|
71
|
-
/** Runs one action: the steps every caller shares (route, group API, MCP tool). */
|
|
72
|
-
export declare function runAction(entry: ActionEntry, request: unknown, body: unknown, logger: Logger): Promise<ActionResult>;
|
|
73
|
-
export declare function createActionApi(actions: ReadonlyMap<string, ActionEntry>, logger: Logger): ActionApi;
|
package/dist/action-api.js
DELETED
|
@@ -1,249 +0,0 @@
|
|
|
1
|
-
// The general write of actions (D-0202): one runner for every caller of every module's actions —
|
|
2
|
-
// the route `POST <path>/:module/:action`, the group API and the MCP tools of @dokebi/module/mcp.
|
|
3
|
-
// It checks the caller's permission and scope, the input against the declaration (unknown fields
|
|
4
|
-
// 400, wrong values 422), runs a dangerous action only with the token of its preview, and checks
|
|
5
|
-
// that the result is JSON.
|
|
6
|
-
import { DokebiError } from '@dokebi/core';
|
|
7
|
-
import { ACTION_LIMITS, checkInput, confirmToken, } from './action.js';
|
|
8
|
-
const STATUS = {
|
|
9
|
-
ACTION_NOT_FOUND: 404,
|
|
10
|
-
FORBIDDEN: 403,
|
|
11
|
-
INVALID_INPUT: 400,
|
|
12
|
-
VALIDATION_FAILED: 422,
|
|
13
|
-
ACTION_CONFLICT: 409,
|
|
14
|
-
CONFIRM_REQUIRED: 428,
|
|
15
|
-
CONFIRM_STALE: 409,
|
|
16
|
-
ACTION_FAILED: 500,
|
|
17
|
-
};
|
|
18
|
-
const FIX = {
|
|
19
|
-
ACTION_NOT_FOUND: 'Run an action that npx dokebi describe --json lists under app.modules[].actions, as <module>.<name>.',
|
|
20
|
-
FORBIDDEN: 'Sign in with an account that holds the action permission (its scope must not be empty), or leave the action out.',
|
|
21
|
-
INVALID_INPUT: 'Send { input: { <declared field>: value } } and, for a dangerous action, confirm: <the token of its preview>; nothing else. data.reason and data.name say what was refused.',
|
|
22
|
-
VALIDATION_FAILED: 'Correct the fields named in fields (a fixed message each; data.rules names the broken rule) and send the input again.',
|
|
23
|
-
ACTION_CONFLICT: 'Read the row again (its new version) and send the change again on top of it.',
|
|
24
|
-
CONFIRM_REQUIRED: 'Show data.preview to the user; when they agree, send the same input with confirm: data.confirm.',
|
|
25
|
-
CONFIRM_STALE: 'The row changed after the preview: show the new data.preview and send confirm: data.confirm when the user agrees.',
|
|
26
|
-
ACTION_FAILED: 'Correct the action as the message says: its scope function answers one of its scopes, its preview and result are JSON of at most the documented size.',
|
|
27
|
-
};
|
|
28
|
-
const HINT = {
|
|
29
|
-
ACTION_NOT_FOUND: 'This action does not exist.',
|
|
30
|
-
FORBIDDEN: 'You are not allowed to do this.',
|
|
31
|
-
VALIDATION_FAILED: 'Check the highlighted fields.',
|
|
32
|
-
ACTION_CONFLICT: 'Someone changed this in the meantime. Load it again.',
|
|
33
|
-
CONFIRM_REQUIRED: 'Confirm to continue.',
|
|
34
|
-
CONFIRM_STALE: 'It changed in the meantime. Check again and confirm.',
|
|
35
|
-
};
|
|
36
|
-
export function actionError(code, message, data, cause) {
|
|
37
|
-
return new DokebiError(code, message, {
|
|
38
|
-
plugin: 'dokebi-module',
|
|
39
|
-
status: STATUS[code],
|
|
40
|
-
fix: FIX[code],
|
|
41
|
-
...(HINT[code] === undefined ? {} : { hint: HINT[code] }),
|
|
42
|
-
...(data === undefined ? {} : { data }),
|
|
43
|
-
...(cause === undefined ? {} : { cause }),
|
|
44
|
-
});
|
|
45
|
-
}
|
|
46
|
-
/**
|
|
47
|
-
* 422 with the refused fields, in the shape @dokebi/web answers (`fields`, `errors`) and
|
|
48
|
-
* template-inertia turns into a validation redirect. `data.rules` names the rule per field.
|
|
49
|
-
*/
|
|
50
|
-
export class ActionValidationError extends DokebiError {
|
|
51
|
-
fields;
|
|
52
|
-
errors;
|
|
53
|
-
constructor(problems, action) {
|
|
54
|
-
const rules = {};
|
|
55
|
-
for (const problem of problems)
|
|
56
|
-
if (!Object.hasOwn(rules, problem.field))
|
|
57
|
-
rules[problem.field] = problem.rule;
|
|
58
|
-
super('VALIDATION_FAILED', `Invalid fields: ${[...new Set(problems.map((problem) => problem.field))].join(', ')}`, {
|
|
59
|
-
plugin: 'dokebi-module',
|
|
60
|
-
status: 422,
|
|
61
|
-
fix: FIX.VALIDATION_FAILED,
|
|
62
|
-
hint: HINT.VALIDATION_FAILED,
|
|
63
|
-
data: { action, rules },
|
|
64
|
-
});
|
|
65
|
-
this.fields = Object.freeze(problems.map(({ field, message }) => Object.freeze({ field, message })));
|
|
66
|
-
const errors = {};
|
|
67
|
-
for (const { field, message } of this.fields)
|
|
68
|
-
if (!Object.hasOwn(errors, field))
|
|
69
|
-
errors[field] = message;
|
|
70
|
-
this.errors = Object.freeze(errors);
|
|
71
|
-
}
|
|
72
|
-
}
|
|
73
|
-
/**
|
|
74
|
-
* What a run throws when the row changed since the caller read it (the `version` it sent is not the
|
|
75
|
-
* stored one): 409 ACTION_CONFLICT. `data` may carry the stored version (`{ version }`).
|
|
76
|
-
*/
|
|
77
|
-
export function actionConflict(message = 'The row changed since it was read', data) {
|
|
78
|
-
return actionError('ACTION_CONFLICT', message, data);
|
|
79
|
-
}
|
|
80
|
-
/**
|
|
81
|
-
* What a run throws for a field the services refuse after the input check (a username that is
|
|
82
|
-
* taken): 422 VALIDATION_FAILED like the input check, `{ field: message }`.
|
|
83
|
-
*/
|
|
84
|
-
export function actionInvalid(fields, action = '') {
|
|
85
|
-
return new ActionValidationError(Object.entries(fields).map(([field, message]) => ({ field, message, rule: 'service' })), action);
|
|
86
|
-
}
|
|
87
|
-
/** Who asks: the AI client of an OAuth grant (@dokebi/oauth), else the signed-in user. */
|
|
88
|
-
export function actorOf(request) {
|
|
89
|
-
const asked = (request ?? {});
|
|
90
|
-
const grant = asked.oauth?.grant;
|
|
91
|
-
if (grant && typeof grant === 'object') {
|
|
92
|
-
const client = typeof grant.clientName === 'string' && grant.clientName ? grant.clientName : grant.clientId;
|
|
93
|
-
return Object.freeze({
|
|
94
|
-
type: 'ai',
|
|
95
|
-
...(typeof grant.userId === 'string' ? { id: grant.userId } : {}),
|
|
96
|
-
...(typeof client === 'string' ? { client: client.slice(0, 128) } : {}),
|
|
97
|
-
});
|
|
98
|
-
}
|
|
99
|
-
const id = asked.auth?.id;
|
|
100
|
-
return Object.freeze({ type: 'user', ...(typeof id === 'string' ? { id } : {}) });
|
|
101
|
-
}
|
|
102
|
-
/** JSON of at most `bytes`, or undefined. */
|
|
103
|
-
function json(value, bytes) {
|
|
104
|
-
let text;
|
|
105
|
-
try {
|
|
106
|
-
text = JSON.stringify(value === undefined ? null : value);
|
|
107
|
-
}
|
|
108
|
-
catch (error) {
|
|
109
|
-
throw actionError('ACTION_FAILED', 'The value is not JSON', undefined, error);
|
|
110
|
-
}
|
|
111
|
-
if (text === undefined || Buffer.byteLength(text) > bytes)
|
|
112
|
-
return undefined;
|
|
113
|
-
return JSON.parse(text);
|
|
114
|
-
}
|
|
115
|
-
/** Runs one action: the steps every caller shares (route, group API, MCP tool). */
|
|
116
|
-
export async function runAction(entry, request, body, logger) {
|
|
117
|
-
const begin = performance.now();
|
|
118
|
-
const { id, declaration } = entry;
|
|
119
|
-
const actor = actorOf(request);
|
|
120
|
-
const done = (outcome, extra = {}) => {
|
|
121
|
-
if (logger.isEnabled('debug'))
|
|
122
|
-
logger.log('debug', 'Action answered', {
|
|
123
|
-
action: id,
|
|
124
|
-
outcome,
|
|
125
|
-
actor: actor.type,
|
|
126
|
-
...(actor.id === undefined ? {} : { user: actor.id }),
|
|
127
|
-
...(actor.client === undefined ? {} : { client: actor.client }),
|
|
128
|
-
ms: Math.round((performance.now() - begin) * 10) / 10,
|
|
129
|
-
...extra,
|
|
130
|
-
});
|
|
131
|
-
};
|
|
132
|
-
try {
|
|
133
|
-
const asked = request;
|
|
134
|
-
const allowed = asked?.auth ? await asked.auth.can(declaration.permission) : false;
|
|
135
|
-
if (!allowed)
|
|
136
|
-
throw actionError('FORBIDDEN', `Running ${id} needs ${declaration.permission}`, {
|
|
137
|
-
action: id,
|
|
138
|
-
});
|
|
139
|
-
if (body === null || typeof body !== 'object' || Array.isArray(body))
|
|
140
|
-
throw actionError('INVALID_INPUT', 'The body must be { input, confirm? }', {
|
|
141
|
-
action: id,
|
|
142
|
-
reason: 'body',
|
|
143
|
-
});
|
|
144
|
-
const extra = Object.keys(body).find((key) => key !== 'input' && key !== 'confirm');
|
|
145
|
-
if (extra !== undefined)
|
|
146
|
-
throw actionError('INVALID_INPUT', `The body field ${extra.slice(0, 64)} is not known`, {
|
|
147
|
-
action: id,
|
|
148
|
-
reason: 'body',
|
|
149
|
-
name: extra.slice(0, 64),
|
|
150
|
-
});
|
|
151
|
-
const { input, confirm } = body;
|
|
152
|
-
if (confirm !== undefined &&
|
|
153
|
-
(!declaration.danger || typeof confirm !== 'string' || confirm.length > 64))
|
|
154
|
-
throw actionError('INVALID_INPUT', declaration.danger ? 'confirm must be the token of the preview' : `${id} takes no confirm`, { action: id, reason: 'confirm' });
|
|
155
|
-
const checked = checkInput(declaration.input ?? {}, input ?? {});
|
|
156
|
-
if (!checked.ok) {
|
|
157
|
-
if (checked.reason === 'fields')
|
|
158
|
-
throw new ActionValidationError(checked.problems, id);
|
|
159
|
-
throw actionError('INVALID_INPUT', checked.message, {
|
|
160
|
-
action: id,
|
|
161
|
-
reason: checked.reason,
|
|
162
|
-
...(checked.name === undefined ? {} : { name: checked.name }),
|
|
163
|
-
});
|
|
164
|
-
}
|
|
165
|
-
const module = entry.context();
|
|
166
|
-
let scope = null;
|
|
167
|
-
if (declaration.scope) {
|
|
168
|
-
const answer = await declaration.scope({ request, module });
|
|
169
|
-
if (answer === null || answer === undefined)
|
|
170
|
-
throw actionError('FORBIDDEN', `The caller has no scope on ${id}`, { action: id });
|
|
171
|
-
if (typeof answer !== 'string' || !declaration.scopes?.includes(answer))
|
|
172
|
-
throw actionError('ACTION_FAILED', `The scope function of ${id} answered something other than one of its scopes (${declaration.scopes?.join(', ')})`, { action: id });
|
|
173
|
-
scope = answer;
|
|
174
|
-
}
|
|
175
|
-
const run = Object.freeze({
|
|
176
|
-
action: id,
|
|
177
|
-
input: checked.input,
|
|
178
|
-
scope,
|
|
179
|
-
actor,
|
|
180
|
-
request,
|
|
181
|
-
module,
|
|
182
|
-
});
|
|
183
|
-
if (declaration.preview) {
|
|
184
|
-
const preview = json(await declaration.preview(run), ACTION_LIMITS.previewBytes);
|
|
185
|
-
if (preview === undefined)
|
|
186
|
-
throw actionError('ACTION_FAILED', `The preview of ${id} is larger than ${ACTION_LIMITS.previewBytes} bytes of JSON`, { action: id });
|
|
187
|
-
const token = confirmToken(id, actor, checked.input, preview);
|
|
188
|
-
if (confirm === undefined)
|
|
189
|
-
throw actionError('CONFIRM_REQUIRED', `${id} needs a confirm after its preview`, {
|
|
190
|
-
action: id,
|
|
191
|
-
preview,
|
|
192
|
-
confirm: token,
|
|
193
|
-
});
|
|
194
|
-
if (confirm !== token)
|
|
195
|
-
throw actionError('CONFIRM_STALE', `What ${id} would change is not what was previewed`, {
|
|
196
|
-
action: id,
|
|
197
|
-
preview,
|
|
198
|
-
confirm: token,
|
|
199
|
-
});
|
|
200
|
-
}
|
|
201
|
-
const value = await declaration.run(run);
|
|
202
|
-
const result = json(value, ACTION_LIMITS.resultBytes);
|
|
203
|
-
if (result === undefined)
|
|
204
|
-
throw actionError('ACTION_FAILED', `The result of ${id} is larger than ${ACTION_LIMITS.resultBytes} bytes of JSON`, { action: id });
|
|
205
|
-
done('ok');
|
|
206
|
-
return Object.freeze({ action: id, result });
|
|
207
|
-
}
|
|
208
|
-
catch (error) {
|
|
209
|
-
const code = error?.code;
|
|
210
|
-
if (code === 'ACTION_FAILED')
|
|
211
|
-
logger.log('error', 'Action broke the rules', { code: 'ACTION_FAILED', action: id, error });
|
|
212
|
-
done('refused', { code: typeof code === 'string' ? code : 'ERROR' });
|
|
213
|
-
throw error;
|
|
214
|
-
}
|
|
215
|
-
}
|
|
216
|
-
const PATH = /^(?:\/[a-z0-9][a-z0-9._-]{0,63}){1,4}$/;
|
|
217
|
-
export function createActionApi(actions, logger) {
|
|
218
|
-
const ids = Object.freeze([...actions.keys()]);
|
|
219
|
-
const run = async (request, id, body) => {
|
|
220
|
-
const entry = typeof id === 'string' ? actions.get(id) : undefined;
|
|
221
|
-
if (!entry) {
|
|
222
|
-
const error = actionError('ACTION_NOT_FOUND', `There is no action ${String(id).slice(0, 140)}`, {
|
|
223
|
-
action: String(id).slice(0, 140),
|
|
224
|
-
});
|
|
225
|
-
logger.log('debug', 'Action answered', {
|
|
226
|
-
action: String(id).slice(0, 140),
|
|
227
|
-
outcome: 'refused',
|
|
228
|
-
code: error.code,
|
|
229
|
-
});
|
|
230
|
-
throw error;
|
|
231
|
-
}
|
|
232
|
-
return runAction(entry, request, body, logger);
|
|
233
|
-
};
|
|
234
|
-
return Object.freeze({
|
|
235
|
-
ids,
|
|
236
|
-
run,
|
|
237
|
-
routes(route, options = {}) {
|
|
238
|
-
const path = options.path ?? '/actions';
|
|
239
|
-
if (!PATH.test(path))
|
|
240
|
-
throw actionError('ACTION_FAILED', `The action route path ${path} must be /a/lower-case/path`);
|
|
241
|
-
const handler = (async (request) => {
|
|
242
|
-
const asked = request;
|
|
243
|
-
const params = asked.params ?? {};
|
|
244
|
-
return run(request, `${String(params.module)}.${String(params.action)}`, (asked.body ?? {}));
|
|
245
|
-
});
|
|
246
|
-
route.post(`${path}/:module/:action`, handler, { config: { id: 'module.action' } });
|
|
247
|
-
},
|
|
248
|
-
});
|
|
249
|
-
}
|