@cosmicdrift/kumiko-framework 0.412.0 → 0.413.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/agents/api/framework-engine.md +1 -0
- package/agents/boot-rules.md +343 -0
- package/agents/examples/api-docs.md +79 -71
- package/agents/examples/golden-path.md +11 -11
- package/agents/examples/{contact.md → helpdesk.md} +41 -34
- package/agents/examples.md +1 -1
- package/agents/features-index.md +2 -2
- package/agents/features.md +16 -16
- package/dist/engine/boot-validator/boot-report.d.ts +3 -0
- package/dist/engine/boot-validator/boot-report.js +2 -2
- package/dist/engine/boot-validator/boot-rules.d.ts +570 -0
- package/dist/engine/boot-validator/boot-rules.js +20 -0
- package/dist/engine/boot-validator/definition-config-events-jobs-rules.d.ts +77 -0
- package/dist/engine/boot-validator/definition-config-events-jobs-rules.js +77 -0
- package/dist/engine/boot-validator/definition-events-rules.d.ts +42 -0
- package/dist/engine/boot-validator/definition-events-rules.js +42 -0
- package/dist/engine/boot-validator/definition-feature-rules.d.ts +42 -0
- package/dist/engine/boot-validator/definition-feature-rules.js +42 -0
- package/dist/engine/boot-validator/definition-field-factories-rules.d.ts +17 -0
- package/dist/engine/boot-validator/definition-field-factories-rules.js +17 -0
- package/dist/engine/boot-validator/definition-handlers-rules.d.ts +72 -0
- package/dist/engine/boot-validator/definition-handlers-rules.js +72 -0
- package/dist/engine/boot-validator/definition-ownership-from-rules.d.ts +27 -0
- package/dist/engine/boot-validator/definition-ownership-from-rules.js +27 -0
- package/dist/engine/boot-validator/definition-probes-rules.d.ts +47 -0
- package/dist/engine/boot-validator/definition-probes-rules.js +47 -0
- package/dist/engine/boot-validator/definition-role-assignment-rules.d.ts +27 -0
- package/dist/engine/boot-validator/definition-role-assignment-rules.js +27 -0
- package/dist/engine/boot-validator/definition-ui-extensions-rules.d.ts +197 -0
- package/dist/engine/boot-validator/definition-ui-extensions-rules.js +197 -0
- package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +32 -0
- package/dist/engine/boot-validator/definition-webhook-events-rules.js +32 -0
- package/dist/engine/define-feature.js +26 -9
- package/dist/engine/define-handler.js +8 -4
- package/dist/engine/definition-violations.d.ts +14 -0
- package/dist/engine/definition-violations.js +71 -0
- package/dist/engine/entity-handlers.js +39 -13
- package/dist/engine/event-def.js +32 -12
- package/dist/engine/factories.js +16 -5
- package/dist/engine/feature-config-events-jobs.js +63 -27
- package/dist/engine/feature-entity-handlers.js +15 -6
- package/dist/engine/feature-probes.js +29 -9
- package/dist/engine/feature-ui-extensions.js +178 -92
- package/dist/engine/object-form.js +8 -2
- package/dist/engine/ownership.js +17 -5
- package/dist/engine/registry-validate.d.ts +1 -0
- package/dist/engine/registry-validate.js +7 -0
- package/dist/engine/registry.js +2 -1
- package/dist/engine/role-assignment.js +17 -5
- package/dist/engine/soft-delete-cleanup.js +4 -3
- package/dist/engine/webhook-events.js +20 -6
- package/dist/files/feature.js +1 -0
- package/dist/files/file-routes.js +1 -1
- package/dist/jobs/job-runner-gates.js +5 -1
- package/dist/schema-cli/shared.d.ts +11 -0
- package/dist/schema-cli/shared.js +37 -3
- package/dist/schema-cli/validate-command.js +10 -3
- package/package.json +3 -3
- package/src/changes.json +12 -0
|
@@ -1,33 +1,51 @@
|
|
|
1
|
+
import { bootRuleError } from "./boot-validator/boot-rule.js";
|
|
2
|
+
import { DEFINITION_PROBE_RULES } from "./boot-validator/definition-probes-rules.js";
|
|
1
3
|
import { isKebabSegment, QnTypes, qn, toKebab } from "./qualified-name.js";
|
|
2
4
|
const PROBE_SCOPES = ["tenant", "system"];
|
|
3
5
|
const PROBE_COSTS = ["free", "paid"];
|
|
4
6
|
function assertValidProbe(featureName, options) {
|
|
5
7
|
const prefix = `[Feature ${featureName}] r.probe()`;
|
|
6
8
|
if (typeof options.name !== "string" || options.name.length === 0) {
|
|
7
|
-
throw
|
|
9
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.nameEmpty, {
|
|
10
|
+
message: `${prefix}: name must be a non-empty string`,
|
|
11
|
+
});
|
|
8
12
|
}
|
|
9
13
|
if (!isKebabSegment(options.name)) {
|
|
10
|
-
throw
|
|
14
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.nameNotKebab, {
|
|
15
|
+
message: `${prefix}: name "${options.name}" must be kebab-case`,
|
|
16
|
+
});
|
|
11
17
|
}
|
|
12
18
|
if (!PROBE_SCOPES.includes(options.scope)) {
|
|
13
|
-
throw
|
|
19
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.scopeInvalid, {
|
|
20
|
+
message: `${prefix} "${options.name}": scope must be one of ${PROBE_SCOPES.join(", ")}`,
|
|
21
|
+
});
|
|
14
22
|
}
|
|
15
23
|
if (!PROBE_COSTS.includes(options.cost)) {
|
|
16
|
-
throw
|
|
24
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.costInvalid, {
|
|
25
|
+
message: `${prefix} "${options.name}": cost must be one of ${PROBE_COSTS.join(", ")}`,
|
|
26
|
+
});
|
|
17
27
|
}
|
|
18
28
|
for (const field of ["area", "label"]) {
|
|
19
29
|
if (typeof options[field] !== "string" || options[field].length === 0) {
|
|
20
|
-
throw
|
|
30
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.i18nKeyEmpty, {
|
|
31
|
+
message: `${prefix} "${options.name}": ${field} must be a non-empty i18n key`,
|
|
32
|
+
});
|
|
21
33
|
}
|
|
22
34
|
}
|
|
23
35
|
if (options.timeoutMs !== undefined && !(options.timeoutMs > 0)) {
|
|
24
|
-
throw
|
|
36
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.timeoutInvalid, {
|
|
37
|
+
message: `${prefix} "${options.name}": timeoutMs must be > 0`,
|
|
38
|
+
});
|
|
25
39
|
}
|
|
26
40
|
if (typeof options.run !== "function") {
|
|
27
|
-
throw
|
|
41
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.runNotFunction, {
|
|
42
|
+
message: `${prefix} "${options.name}": run must be a function`,
|
|
43
|
+
});
|
|
28
44
|
}
|
|
29
45
|
if (options.targets !== undefined && typeof options.targets !== "function") {
|
|
30
|
-
throw
|
|
46
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.targetsNotFunction, {
|
|
47
|
+
message: `${prefix} "${options.name}": targets must be a function`,
|
|
48
|
+
});
|
|
31
49
|
}
|
|
32
50
|
}
|
|
33
51
|
export function buildProbeMethods(state, featureName) {
|
|
@@ -35,7 +53,9 @@ export function buildProbeMethods(state, featureName) {
|
|
|
35
53
|
probe(options) {
|
|
36
54
|
assertValidProbe(featureName, options);
|
|
37
55
|
if (state.probes[options.name]) {
|
|
38
|
-
throw
|
|
56
|
+
throw bootRuleError(DEFINITION_PROBE_RULES.duplicate, {
|
|
57
|
+
message: `[Feature ${featureName}] Probe "${options.name}" already registered. Probe names must be unique per feature.`,
|
|
58
|
+
});
|
|
39
59
|
}
|
|
40
60
|
state.probes[options.name] = {
|
|
41
61
|
...options,
|
|
@@ -3,6 +3,8 @@ import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
|
|
|
3
3
|
import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
|
|
4
4
|
import { markExecutorManagedTable } from "../db/executor-managed-tables.js";
|
|
5
5
|
import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
|
|
6
|
+
import { bootRuleError } from "./boot-validator/boot-rule.js";
|
|
7
|
+
import { DEFINITION_UI_EXTENSION_RULES } from "./boot-validator/definition-ui-extensions-rules.js";
|
|
6
8
|
import { LifecycleHookTypes } from "./constants.js";
|
|
7
9
|
import { reasonProblem } from "./escape-hatch-reason.js";
|
|
8
10
|
import { resolveName } from "./handler-helpers.js";
|
|
@@ -17,8 +19,10 @@ function assertSelectorPanelIds(featureName, extensionName, panels) {
|
|
|
17
19
|
const seen = new Set();
|
|
18
20
|
for (const { id } of panels) {
|
|
19
21
|
if (id === "" || id === RESERVED_SELECTION_PANEL_ID || seen.has(id)) {
|
|
20
|
-
throw
|
|
21
|
-
`
|
|
22
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorPanelIdInvalid, {
|
|
23
|
+
message: `[Feature ${featureName}] extensionSelector("${extensionName}") panel id "${id}" must be unique, ` +
|
|
24
|
+
`non-empty and not "${RESERVED_SELECTION_PANEL_ID}" (reserved for the selector panel).`,
|
|
25
|
+
});
|
|
22
26
|
}
|
|
23
27
|
seen.add(id);
|
|
24
28
|
}
|
|
@@ -30,8 +34,10 @@ function qualifySelectorPanel(featureName, panel) {
|
|
|
30
34
|
return panel;
|
|
31
35
|
if (panel.kind === "screen") {
|
|
32
36
|
if ("label" in panel) {
|
|
33
|
-
throw
|
|
34
|
-
`
|
|
37
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorScreenPanelLabel, {
|
|
38
|
+
message: `[Feature ${featureName}] extensionSelector screen panel "${panel.id}" must not set a label — ` +
|
|
39
|
+
`the settings dashboard has no i18n namespace for it; the embedded screen carries its own title.`,
|
|
40
|
+
});
|
|
35
41
|
}
|
|
36
42
|
const qualify = (ref) => ref === "" || isValidQn(ref) ? ref : qualifyEntityName(featureName, "screen", ref);
|
|
37
43
|
const screen = qualify(panel.screen);
|
|
@@ -40,8 +46,10 @@ function qualifySelectorPanel(featureName, panel) {
|
|
|
40
46
|
return panel;
|
|
41
47
|
return { ...panel, screen, ...(fallback !== undefined && { fallback }) };
|
|
42
48
|
}
|
|
43
|
-
throw
|
|
44
|
-
`
|
|
49
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorPanelKindUnsupported, {
|
|
50
|
+
message: `[Feature ${featureName}] extensionSelector panel ${JSON.stringify(panel)} has an unsupported kind — ` +
|
|
51
|
+
`only "custom" and "screen" panels are allowed.`,
|
|
52
|
+
});
|
|
45
53
|
}
|
|
46
54
|
function isEntityWideHookType(type) {
|
|
47
55
|
return (type === LifecycleHookTypes.postSave ||
|
|
@@ -98,14 +106,18 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
98
106
|
// instead of only the standalone r.nav() one.
|
|
99
107
|
function registerNav(navDefinition) {
|
|
100
108
|
if (!isKebabSegment(navDefinition.id)) {
|
|
101
|
-
throw
|
|
102
|
-
`
|
|
103
|
-
|
|
109
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.navIdNotKebab, {
|
|
110
|
+
message: `[Feature ${name}] Nav id "${navDefinition.id}" must be kebab-case ` +
|
|
111
|
+
`(lowercase letters, digits, dashes; start with a letter). ` +
|
|
112
|
+
`Got "${navDefinition.id}" — try "${toKebab(navDefinition.id).replace(/_/g, "-")}".`,
|
|
113
|
+
});
|
|
104
114
|
}
|
|
105
115
|
if (state.navs[navDefinition.id]) {
|
|
106
|
-
throw
|
|
107
|
-
`
|
|
108
|
-
|
|
116
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.navIdDuplicate, {
|
|
117
|
+
message: `[Feature ${name}] Nav entry "${navDefinition.id}" already registered. ` +
|
|
118
|
+
`Nav ids must be unique per feature — remove the standalone ` +
|
|
119
|
+
`r.nav("${navDefinition.id}", ...) call or the screen's inline nav.`,
|
|
120
|
+
});
|
|
109
121
|
}
|
|
110
122
|
// Explicit `undefined` values (e.g. `icon: cond ? "x" : undefined`) would trip
|
|
111
123
|
// buildAppSchema's JSON-safety check, so strip them for every nav path.
|
|
@@ -123,19 +135,25 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
123
135
|
};
|
|
124
136
|
if (type === "validation") {
|
|
125
137
|
if (options?.escapeHatch !== undefined) {
|
|
126
|
-
throw
|
|
127
|
-
"validation
|
|
138
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookValidationEscapeHatch, {
|
|
139
|
+
message: `[Feature ${name}] r.hook({ type: "validation", … }) does not accept escapeHatch — ` +
|
|
140
|
+
"validation hooks receive no context to switch identity with.",
|
|
141
|
+
});
|
|
128
142
|
}
|
|
129
143
|
}
|
|
130
144
|
else if (options?.escapeHatch !== undefined) {
|
|
131
145
|
const hookReasonProblem = reasonProblem(options.escapeHatch.reason);
|
|
132
146
|
if (hookReasonProblem !== undefined) {
|
|
133
|
-
throw
|
|
147
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookEscapeHatchInvalid, {
|
|
148
|
+
message: `[Feature ${name}] r.hook({ type: "${type}", … }) declares an invalid escapeHatch — ${hookReasonProblem}`,
|
|
149
|
+
});
|
|
134
150
|
}
|
|
135
151
|
}
|
|
136
152
|
const hookGrantsProblem = options?.escapeHatch && escapeHatchGrantsProblem(options.escapeHatch);
|
|
137
153
|
if (hookGrantsProblem) {
|
|
138
|
-
throw
|
|
154
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookEscapeHatchInvalid, {
|
|
155
|
+
message: `[Feature ${name}] r.hook({ type: "${type}", … }) declares an invalid escapeHatch — ${hookGrantsProblem}`,
|
|
156
|
+
});
|
|
139
157
|
}
|
|
140
158
|
// Wrapped once for both branches below; validation hooks stay unwrapped (no context).
|
|
141
159
|
const hookLabel = `${type} hook of feature "${name}"`;
|
|
@@ -149,8 +167,10 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
149
167
|
!Array.isArray(target) &&
|
|
150
168
|
"allOf" in target) {
|
|
151
169
|
if (!isEntityWideHookType(type)) {
|
|
152
|
-
throw
|
|
153
|
-
`
|
|
170
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookAllOfUnsupportedType, {
|
|
171
|
+
message: `[Feature ${name}] r.hook({ type: "${type}", target: { allOf }, … }) only supports ` +
|
|
172
|
+
`postSave/preDelete/postDelete/postQuery, not "${type}".`,
|
|
173
|
+
});
|
|
154
174
|
}
|
|
155
175
|
registerEntityWideHook(state, name, type, resolveName(target.allOf), wrapped, // @cast-boundary engine-bridge
|
|
156
176
|
options);
|
|
@@ -183,8 +203,10 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
183
203
|
return;
|
|
184
204
|
}
|
|
185
205
|
if (!(type in state.phasedLifecycleHooks)) {
|
|
186
|
-
throw
|
|
187
|
-
|
|
206
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookTypeUnknown, {
|
|
207
|
+
message: `[Feature ${name}] r.hook({ type: "${type}", … }) is not a known hook type ` +
|
|
208
|
+
"(preQuery hooks were never invoked and have been removed).",
|
|
209
|
+
});
|
|
188
210
|
}
|
|
189
211
|
// Phased storage. preDelete has no phase option (always inTransaction);
|
|
190
212
|
// postSave/postDelete default to afterCommit.
|
|
@@ -233,16 +255,22 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
233
255
|
const escapeHatchObject = isPlainObject(escapeHatch) ? escapeHatch : undefined;
|
|
234
256
|
const reason = escapeHatchObject?.["reason"];
|
|
235
257
|
if (escapeHatchObject === undefined || typeof reason !== "string") {
|
|
236
|
-
throw
|
|
237
|
-
`
|
|
258
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.useExtensionEscapeHatchInvalid, {
|
|
259
|
+
message: `[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
|
|
260
|
+
`must be { reason: "<explanation>" } explaining why this usage needs unfiltered db access.`,
|
|
261
|
+
});
|
|
238
262
|
}
|
|
239
263
|
const extReasonProblem = reasonProblem(reason);
|
|
240
264
|
if (extReasonProblem !== undefined) {
|
|
241
|
-
throw
|
|
265
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.useExtensionEscapeHatchInvalid, {
|
|
266
|
+
message: `[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extReasonProblem}`,
|
|
267
|
+
});
|
|
242
268
|
}
|
|
243
269
|
const extGrantsProblem = escapeHatchGrantsProblem(escapeHatchObject);
|
|
244
270
|
if (extGrantsProblem) {
|
|
245
|
-
throw
|
|
271
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.useExtensionEscapeHatchInvalid, {
|
|
272
|
+
message: `[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extGrantsProblem}`,
|
|
273
|
+
});
|
|
246
274
|
}
|
|
247
275
|
}
|
|
248
276
|
state.extensionUsages.push({
|
|
@@ -253,8 +281,10 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
253
281
|
},
|
|
254
282
|
extensionSelector(extensionName, key, options) {
|
|
255
283
|
if (state.extensionSelectors.some((s) => s.extensionName === extensionName)) {
|
|
256
|
-
throw
|
|
257
|
-
`
|
|
284
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorDuplicate, {
|
|
285
|
+
message: `[Feature ${name}] extensionSelector("${extensionName}") declared twice — ` +
|
|
286
|
+
`one selector key per extension point.`,
|
|
287
|
+
});
|
|
258
288
|
}
|
|
259
289
|
const qualifiedKey = typeof key === "string" ? key : key.name;
|
|
260
290
|
const panels = options?.panels?.map((panel) => qualifySelectorPanel(name, panel));
|
|
@@ -284,7 +314,9 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
284
314
|
*/
|
|
285
315
|
exposesApi(apiName) {
|
|
286
316
|
if (state.exposedApis.has(apiName)) {
|
|
287
|
-
throw
|
|
317
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.exposesApiTwice, {
|
|
318
|
+
message: `[Feature ${name}] r.exposesApi("${apiName}") called twice — API names must be unique within a feature.`,
|
|
319
|
+
});
|
|
288
320
|
}
|
|
289
321
|
state.exposedApis.add(apiName);
|
|
290
322
|
},
|
|
@@ -304,13 +336,17 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
304
336
|
// Catch it at the registration site so the stack trace points at the
|
|
305
337
|
// feature file, not at framework internals.
|
|
306
338
|
if (!isKebabSegment(definition.name)) {
|
|
307
|
-
throw
|
|
308
|
-
`
|
|
309
|
-
|
|
339
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.projectionNameNotKebab, {
|
|
340
|
+
message: `[Feature ${name}] Projection name "${definition.name}" must be kebab-case ` +
|
|
341
|
+
`(lowercase letters, digits, dashes; start with a letter). ` +
|
|
342
|
+
`Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`,
|
|
343
|
+
});
|
|
310
344
|
}
|
|
311
345
|
if (state.projections[definition.name]) {
|
|
312
|
-
throw
|
|
313
|
-
`Projection
|
|
346
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.projectionNameDuplicate, {
|
|
347
|
+
message: `[Feature ${name}] Projection "${definition.name}" already registered. ` +
|
|
348
|
+
`Projection names must be unique per feature.`,
|
|
349
|
+
});
|
|
314
350
|
}
|
|
315
351
|
if (typeof definition.table === "object" && definition.table !== null) {
|
|
316
352
|
markExecutorManagedTable(definition.table);
|
|
@@ -319,24 +355,32 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
319
355
|
},
|
|
320
356
|
multiStreamProjection(definition) {
|
|
321
357
|
if (!isKebabSegment(definition.name)) {
|
|
322
|
-
throw
|
|
323
|
-
`
|
|
324
|
-
|
|
358
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.multiStreamProjectionNameNotKebab, {
|
|
359
|
+
message: `[Feature ${name}] MultiStreamProjection name "${definition.name}" must be kebab-case ` +
|
|
360
|
+
`(lowercase letters, digits, dashes; start with a letter). ` +
|
|
361
|
+
`Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`,
|
|
362
|
+
});
|
|
325
363
|
}
|
|
326
364
|
if (state.multiStreamProjections[definition.name] || state.projections[definition.name]) {
|
|
327
|
-
throw
|
|
328
|
-
`
|
|
365
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.multiStreamProjectionNameDuplicate, {
|
|
366
|
+
message: `[Feature ${name}] Projection name "${definition.name}" already registered. ` +
|
|
367
|
+
`r.projection and r.multiStreamProjection share a namespace — pick a unique short name.`,
|
|
368
|
+
});
|
|
329
369
|
}
|
|
330
370
|
if (Object.keys(definition.apply).length === 0) {
|
|
331
|
-
throw
|
|
332
|
-
`
|
|
371
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.multiStreamProjectionWithoutApply, {
|
|
372
|
+
message: `[Feature ${name}] MultiStreamProjection "${definition.name}" has no apply handlers. ` +
|
|
373
|
+
`Declare at least one event type it reacts to, otherwise the dispatcher has nothing to route.`,
|
|
374
|
+
});
|
|
333
375
|
}
|
|
334
376
|
state.multiStreamProjections[definition.name] = definition;
|
|
335
377
|
},
|
|
336
378
|
extendEntityProjection(entityName, extension) {
|
|
337
379
|
if (Object.keys(extension.apply).length === 0) {
|
|
338
|
-
throw
|
|
339
|
-
`
|
|
380
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extendEntityProjectionWithoutApply, {
|
|
381
|
+
message: `[Feature ${name}] extendEntityProjection("${entityName}") has no apply handlers. ` +
|
|
382
|
+
`Declare at least one event type, otherwise the rebuild replay has nothing to do.`,
|
|
383
|
+
});
|
|
340
384
|
}
|
|
341
385
|
// Entity existence + apply-key collisions are validated at registry
|
|
342
386
|
// build — r.entity may legally be called after this in the same feature.
|
|
@@ -367,13 +411,17 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
367
411
|
// the feature file, not at registry-boot. Same guard pattern as
|
|
368
412
|
// r.projection / r.multiStreamProjection.
|
|
369
413
|
if (!isKebabSegment(definition.id)) {
|
|
370
|
-
throw
|
|
371
|
-
`
|
|
372
|
-
|
|
414
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.screenIdNotKebab, {
|
|
415
|
+
message: `[Feature ${name}] Screen id "${definition.id}" must be kebab-case ` +
|
|
416
|
+
`(lowercase letters, digits, dashes; start with a letter). ` +
|
|
417
|
+
`Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`,
|
|
418
|
+
});
|
|
373
419
|
}
|
|
374
420
|
if (state.screens[definition.id]) {
|
|
375
|
-
throw
|
|
376
|
-
`Screen
|
|
421
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.screenIdDuplicate, {
|
|
422
|
+
message: `[Feature ${name}] Screen "${definition.id}" already registered. ` +
|
|
423
|
+
`Screen ids must be unique per feature.`,
|
|
424
|
+
});
|
|
377
425
|
}
|
|
378
426
|
state.screens[definition.id] = definition;
|
|
379
427
|
if (definition.nav) {
|
|
@@ -395,8 +443,10 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
395
443
|
},
|
|
396
444
|
contentCollection(definition) {
|
|
397
445
|
if (state.contentCollections[definition.id]) {
|
|
398
|
-
throw
|
|
399
|
-
`
|
|
446
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.contentCollectionIdDuplicate, {
|
|
447
|
+
message: `[Feature ${name}] Content collection "${definition.id}" already registered. ` +
|
|
448
|
+
`Collection ids must be unique per feature.`,
|
|
449
|
+
});
|
|
400
450
|
}
|
|
401
451
|
// registerNav owns the kebab + collision checks, including collisions
|
|
402
452
|
// with a plain r.nav() of the same id.
|
|
@@ -424,13 +474,17 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
424
474
|
// Same kebab guard as r.screen / r.nav so authoring-time mistakes
|
|
425
475
|
// surface at the feature file, not deep in registry boot.
|
|
426
476
|
if (!isKebabSegment(definition.id)) {
|
|
427
|
-
throw
|
|
428
|
-
`
|
|
429
|
-
|
|
477
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.workspaceIdNotKebab, {
|
|
478
|
+
message: `[Feature ${name}] Workspace id "${definition.id}" must be kebab-case ` +
|
|
479
|
+
`(lowercase letters, digits, dashes; start with a letter). ` +
|
|
480
|
+
`Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`,
|
|
481
|
+
});
|
|
430
482
|
}
|
|
431
483
|
if (state.workspaces[definition.id]) {
|
|
432
|
-
throw
|
|
433
|
-
`Workspace
|
|
484
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.workspaceIdDuplicate, {
|
|
485
|
+
message: `[Feature ${name}] Workspace "${definition.id}" already registered. ` +
|
|
486
|
+
`Workspace ids must be unique per feature.`,
|
|
487
|
+
});
|
|
434
488
|
}
|
|
435
489
|
state.workspaces[definition.id] = definition;
|
|
436
490
|
},
|
|
@@ -439,17 +493,23 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
439
493
|
// dispatcher. An HTTP route occupying /api/foo could bypass the auth
|
|
440
494
|
// middleware without the author explicitly intending it, so block it.
|
|
441
495
|
if (!definition.path.startsWith("/")) {
|
|
442
|
-
throw
|
|
443
|
-
`
|
|
496
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRoutePathNotAbsolute, {
|
|
497
|
+
message: `[Feature ${name}] httpRoute path "${definition.path}" must start with "/". ` +
|
|
498
|
+
`Got "${definition.path}".`,
|
|
499
|
+
});
|
|
444
500
|
}
|
|
445
501
|
if (definition.path === "/api" || definition.path.startsWith("/api/")) {
|
|
446
|
-
throw
|
|
447
|
-
`
|
|
448
|
-
|
|
502
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRoutePathReserved, {
|
|
503
|
+
message: `[Feature ${name}] httpRoute path "${definition.path}" is in the /api/* namespace ` +
|
|
504
|
+
`which is reserved for the dispatcher (write/query/batch/auth/sse). ` +
|
|
505
|
+
`Pick a different path or use r.queryHandler / r.writeHandler.`,
|
|
506
|
+
});
|
|
449
507
|
}
|
|
450
508
|
if (typeof definition.anonymous !== "boolean") {
|
|
451
|
-
throw
|
|
452
|
-
|
|
509
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRouteAnonymousMissing, {
|
|
510
|
+
message: `[Feature ${name}] httpRoute "${definition.method} ${definition.path}" must declare ` +
|
|
511
|
+
`anonymous: true | false — true mounts it public, false behind the session auth chain.`,
|
|
512
|
+
});
|
|
453
513
|
}
|
|
454
514
|
const routeLimit = definition.rateLimit;
|
|
455
515
|
if (routeLimit !== undefined &&
|
|
@@ -457,45 +517,59 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
457
517
|
routeLimit.limit < 1 ||
|
|
458
518
|
!Number.isInteger(routeLimit.windowSeconds) ||
|
|
459
519
|
routeLimit.windowSeconds < 1)) {
|
|
460
|
-
throw
|
|
461
|
-
`
|
|
520
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRouteRateLimitInvalid, {
|
|
521
|
+
message: `[Feature ${name}] httpRoute "${definition.method} ${definition.path}" rateLimit needs ` +
|
|
522
|
+
`positive integer limit and windowSeconds.`,
|
|
523
|
+
});
|
|
462
524
|
}
|
|
463
525
|
const key = `${definition.method} ${definition.path}`;
|
|
464
526
|
if (state.httpRoutes[key]) {
|
|
465
|
-
throw
|
|
466
|
-
`
|
|
527
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRouteDuplicate, {
|
|
528
|
+
message: `[Feature ${name}] HTTP-Route "${key}" already registered. ` +
|
|
529
|
+
`method + path must be unique per feature.`,
|
|
530
|
+
});
|
|
467
531
|
}
|
|
468
532
|
state.httpRoutes[key] = definition;
|
|
469
533
|
},
|
|
470
534
|
webSocketRoute(definition) {
|
|
471
535
|
if (!definition.path.startsWith(WEBSOCKET_ROUTE_PATH_PREFIX)) {
|
|
472
|
-
throw
|
|
473
|
-
`
|
|
474
|
-
|
|
536
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRoutePathPrefix, {
|
|
537
|
+
message: `[Feature ${name}] webSocketRoute path "${definition.path}" must start with ` +
|
|
538
|
+
`"${WEBSOCKET_ROUTE_PATH_PREFIX}" — only that namespace rides the /api/* auth chain ` +
|
|
539
|
+
"the upgrade relies on.",
|
|
540
|
+
});
|
|
475
541
|
}
|
|
476
542
|
if (definition.path.includes("*")) {
|
|
477
|
-
throw
|
|
478
|
-
|
|
543
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRoutePathWildcard, {
|
|
544
|
+
message: `[Feature ${name}] webSocketRoute path "${definition.path}" must not contain "*" — ` +
|
|
545
|
+
"wildcards would let one route swallow unrelated /api/ws/* paths.",
|
|
546
|
+
});
|
|
479
547
|
}
|
|
480
548
|
const { maxMessageBytes } = definition;
|
|
481
549
|
if (maxMessageBytes !== undefined &&
|
|
482
550
|
(!Number.isInteger(maxMessageBytes) ||
|
|
483
551
|
maxMessageBytes < 1 ||
|
|
484
552
|
maxMessageBytes > WEBSOCKET_MAX_PAYLOAD_BYTES)) {
|
|
485
|
-
throw
|
|
486
|
-
`
|
|
553
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRouteMaxMessageBytesInvalid, {
|
|
554
|
+
message: `[Feature ${name}] webSocketRoute "${definition.path}" maxMessageBytes must be an ` +
|
|
555
|
+
`integer between 1 and ${WEBSOCKET_MAX_PAYLOAD_BYTES}, got ${maxMessageBytes}.`,
|
|
556
|
+
});
|
|
487
557
|
}
|
|
488
558
|
const { maxConnectionsPerUser } = definition;
|
|
489
559
|
if (maxConnectionsPerUser !== undefined &&
|
|
490
560
|
(!Number.isInteger(maxConnectionsPerUser) ||
|
|
491
561
|
maxConnectionsPerUser < 1 ||
|
|
492
562
|
maxConnectionsPerUser > WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT)) {
|
|
493
|
-
throw
|
|
494
|
-
`
|
|
563
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRouteMaxConnectionsInvalid, {
|
|
564
|
+
message: `[Feature ${name}] webSocketRoute "${definition.path}" maxConnectionsPerUser must be an ` +
|
|
565
|
+
`integer between 1 and ${WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT}, got ${maxConnectionsPerUser}.`,
|
|
566
|
+
});
|
|
495
567
|
}
|
|
496
568
|
if (state.webSocketRoutes[definition.path]) {
|
|
497
|
-
throw
|
|
498
|
-
|
|
569
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRouteDuplicate, {
|
|
570
|
+
message: `[Feature ${name}] WebSocket route "${definition.path}" already registered. ` +
|
|
571
|
+
"path must be unique per feature.",
|
|
572
|
+
});
|
|
499
573
|
}
|
|
500
574
|
state.webSocketRoutes[definition.path] = definition;
|
|
501
575
|
},
|
|
@@ -506,39 +580,49 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
506
580
|
if (!isKebabSegment(tableName.replace(/_/g, "-"))) {
|
|
507
581
|
// EntityTableMeta uses snake_case for tableName (matches Postgres
|
|
508
582
|
// convention); we just guard against truly broken input.
|
|
509
|
-
throw
|
|
510
|
-
`
|
|
583
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableNameInvalid, {
|
|
584
|
+
message: `[Feature ${name}] Store-table name "${tableName}" must be a ` +
|
|
585
|
+
`valid identifier (lowercase letters, digits, underscores; start with a letter).`,
|
|
586
|
+
});
|
|
511
587
|
}
|
|
512
588
|
if (state.storeTables[tableName]) {
|
|
513
|
-
throw
|
|
514
|
-
`
|
|
589
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableDuplicate, {
|
|
590
|
+
message: `[Feature ${name}] r.storeTable("${tableName}") already registered. ` +
|
|
591
|
+
`Store-table names must be unique per feature.`,
|
|
592
|
+
});
|
|
515
593
|
}
|
|
516
594
|
// `read_` is reserved for r.entity()/r.projection() (managed,
|
|
517
595
|
// event-sourced, rebuildable). storeTable is the unmanaged
|
|
518
596
|
// direct-write escape hatch — the prefix must say so.
|
|
519
597
|
if (tableName.startsWith("read_")) {
|
|
520
|
-
throw
|
|
521
|
-
`
|
|
522
|
-
|
|
598
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableReadPrefixReserved, {
|
|
599
|
+
message: `[Feature ${name}] r.storeTable("${tableName}"): the "read_" prefix is reserved ` +
|
|
600
|
+
`for managed r.entity()/r.projection() tables. Pick an unprefixed name or a ` +
|
|
601
|
+
`distinct prefix (e.g. "store_${tableName.slice("read_".length)}").`,
|
|
602
|
+
});
|
|
523
603
|
}
|
|
524
604
|
// meta.source must agree with the r.storeTable() escape hatch, or the
|
|
525
605
|
// migrate-generator treats schema drift on this table as safe to
|
|
526
606
|
// DROP+rebuild-from-events — wiping direct-write data with no events
|
|
527
607
|
// to replay it from.
|
|
528
608
|
if (meta.source !== "unmanaged") {
|
|
529
|
-
throw
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
609
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableMetaNotUnmanaged, {
|
|
610
|
+
message: `[Feature ${name}] r.storeTable("${tableName}") was given an EntityTableMeta with ` +
|
|
611
|
+
`source: "${meta.source}". r.storeTable() requires source: "unmanaged" (via ` +
|
|
612
|
+
`defineUnmanagedTable(), or deriveEntityTableMeta(..., { source: "unmanaged" })) — ` +
|
|
613
|
+
`otherwise the migration generator will treat schema drift on this table as safe ` +
|
|
614
|
+
`to DROP+rebuild, wiping any direct-write data.`,
|
|
615
|
+
});
|
|
534
616
|
}
|
|
535
617
|
// The `reason` is the marker that justifies the bypass — empty
|
|
536
618
|
// strings would defeat the audit trail. Reject early so the
|
|
537
619
|
// failure points at the feature file.
|
|
538
620
|
if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
|
|
539
|
-
throw
|
|
540
|
-
`
|
|
541
|
-
|
|
621
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableReasonMissing, {
|
|
622
|
+
message: `[Feature ${name}] r.storeTable("${tableName}"): options.reason must be a ` +
|
|
623
|
+
`non-empty string. The reason justifies the audit-trail bypass — ` +
|
|
624
|
+
`if you can't write one, declare data via r.entity() instead.`,
|
|
625
|
+
});
|
|
542
626
|
}
|
|
543
627
|
state.storeTables[tableName] = {
|
|
544
628
|
name: tableName,
|
|
@@ -551,8 +635,10 @@ export function buildUiExtensionsMethods(state, name) {
|
|
|
551
635
|
// Only-once guard: a second call is an authoring error that should surface in
|
|
552
636
|
// the feature file (matching the behavior of r.toggleable).
|
|
553
637
|
if (state.treeActions !== undefined) {
|
|
554
|
-
throw
|
|
555
|
-
`
|
|
638
|
+
throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.treeActionsTwice, {
|
|
639
|
+
message: `[Feature ${name}] r.treeActions() already called. ` +
|
|
640
|
+
`Each feature may declare a single tree-actions schema.`,
|
|
641
|
+
});
|
|
556
642
|
}
|
|
557
643
|
state.treeActions = actions;
|
|
558
644
|
// Return a typed handle for the setup export. Freeze it so callers cannot
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { bootRuleError } from "./boot-validator/boot-rule.js";
|
|
2
|
+
import { FEATURE_DEFINITION_RULES } from "./boot-validator/definition-feature-rules.js";
|
|
1
3
|
// Shared helpers for registrar methods that take a single object argument
|
|
2
4
|
// (`r.entity({ name: "item", ... })`).
|
|
3
5
|
export function splitNamedDefinition(definition) {
|
|
@@ -8,7 +10,9 @@ export function splitNamedDefinition(definition) {
|
|
|
8
10
|
// the implementation signature has to stay optional, so untyped callers are caught here.
|
|
9
11
|
export function requireArgument(value, featureName, method, argument) {
|
|
10
12
|
if (value === undefined) {
|
|
11
|
-
throw
|
|
13
|
+
throw bootRuleError(FEATURE_DEFINITION_RULES.argumentMissing, {
|
|
14
|
+
message: `[Feature ${featureName}] r.${method}() needs its ${argument} argument`,
|
|
15
|
+
});
|
|
12
16
|
}
|
|
13
17
|
return value;
|
|
14
18
|
}
|
|
@@ -29,5 +33,7 @@ export function isObjectArgument(value) {
|
|
|
29
33
|
// Untyped JS callers bypass the types; without this check a positional call would
|
|
30
34
|
// register a definition built from undefined fields instead of failing.
|
|
31
35
|
export function throwObjectArgumentRequired(featureName, method) {
|
|
32
|
-
throw
|
|
36
|
+
throw bootRuleError(FEATURE_DEFINITION_RULES.optionsObjectRequired, {
|
|
37
|
+
message: `[Feature ${featureName}] r.${method}() takes one options object`,
|
|
38
|
+
});
|
|
33
39
|
}
|