@cosmicdrift/kumiko-framework 0.411.0 → 0.413.0

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.
Files changed (87) hide show
  1. package/agents/api/framework-db.md +1 -1
  2. package/agents/api/framework-engine.md +48 -1
  3. package/agents/api/framework-errors.md +2 -0
  4. package/agents/api/types.md +8 -0
  5. package/agents/api.md +2 -2
  6. package/agents/boot-rules.md +343 -0
  7. package/agents/examples/api-docs.md +710 -0
  8. package/agents/examples/golden-path.md +11 -11
  9. package/agents/examples/{contact.md → helpdesk.md} +31 -31
  10. package/agents/examples.md +2 -1
  11. package/agents/features-index.md +2 -2
  12. package/agents/features.md +16 -16
  13. package/dist/api/auth-middleware.d.ts +1 -0
  14. package/dist/api/index.d.ts +3 -0
  15. package/dist/api/index.js +3 -0
  16. package/dist/api/pat-auth-reject.d.ts +7 -0
  17. package/dist/api/pat-auth-reject.js +7 -0
  18. package/dist/api/server-middleware.js +2 -1
  19. package/dist/compliance/sub-processors.js +2 -2
  20. package/dist/config/index.d.ts +25 -0
  21. package/dist/config/index.js +28 -1
  22. package/dist/db/event-store-executor-read-paging.d.ts +1 -0
  23. package/dist/db/event-store-executor-read-paging.js +2 -1
  24. package/dist/db/read-gate-clause.js +26 -7
  25. package/dist/db/table-builder.d.ts +1 -2
  26. package/dist/engine/boot-validator/boot-report.d.ts +3 -0
  27. package/dist/engine/boot-validator/boot-report.js +2 -2
  28. package/dist/engine/boot-validator/boot-rules.d.ts +570 -0
  29. package/dist/engine/boot-validator/boot-rules.js +20 -0
  30. package/dist/engine/boot-validator/definition-config-events-jobs-rules.d.ts +77 -0
  31. package/dist/engine/boot-validator/definition-config-events-jobs-rules.js +77 -0
  32. package/dist/engine/boot-validator/definition-events-rules.d.ts +42 -0
  33. package/dist/engine/boot-validator/definition-events-rules.js +42 -0
  34. package/dist/engine/boot-validator/definition-feature-rules.d.ts +42 -0
  35. package/dist/engine/boot-validator/definition-feature-rules.js +42 -0
  36. package/dist/engine/boot-validator/definition-field-factories-rules.d.ts +17 -0
  37. package/dist/engine/boot-validator/definition-field-factories-rules.js +17 -0
  38. package/dist/engine/boot-validator/definition-handlers-rules.d.ts +72 -0
  39. package/dist/engine/boot-validator/definition-handlers-rules.js +72 -0
  40. package/dist/engine/boot-validator/definition-ownership-from-rules.d.ts +27 -0
  41. package/dist/engine/boot-validator/definition-ownership-from-rules.js +27 -0
  42. package/dist/engine/boot-validator/definition-probes-rules.d.ts +47 -0
  43. package/dist/engine/boot-validator/definition-probes-rules.js +47 -0
  44. package/dist/engine/boot-validator/definition-role-assignment-rules.d.ts +27 -0
  45. package/dist/engine/boot-validator/definition-role-assignment-rules.js +27 -0
  46. package/dist/engine/boot-validator/definition-ui-extensions-rules.d.ts +197 -0
  47. package/dist/engine/boot-validator/definition-ui-extensions-rules.js +197 -0
  48. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +32 -0
  49. package/dist/engine/boot-validator/definition-webhook-events-rules.js +32 -0
  50. package/dist/engine/define-feature.js +29 -9
  51. package/dist/engine/define-handler.js +8 -4
  52. package/dist/engine/definition-violations.d.ts +14 -0
  53. package/dist/engine/definition-violations.js +71 -0
  54. package/dist/engine/entity-handlers.js +39 -13
  55. package/dist/engine/entity-list-runtime-options.js +12 -0
  56. package/dist/engine/event-def.js +32 -12
  57. package/dist/engine/factories.d.ts +2 -0
  58. package/dist/engine/factories.js +16 -5
  59. package/dist/engine/feature-builder-state.d.ts +2 -1
  60. package/dist/engine/feature-builder-state.js +1 -0
  61. package/dist/engine/feature-config-events-jobs.js +63 -27
  62. package/dist/engine/feature-entity-handlers.js +15 -6
  63. package/dist/engine/feature-probes.js +29 -9
  64. package/dist/engine/feature-ui-extensions.js +178 -92
  65. package/dist/engine/index.d.ts +5 -2
  66. package/dist/engine/index.js +4 -1
  67. package/dist/engine/object-form.js +8 -2
  68. package/dist/engine/ownership.js +17 -5
  69. package/dist/engine/registry-facade.js +13 -0
  70. package/dist/engine/role-assignment.js +17 -5
  71. package/dist/engine/webhook-contracts.d.ts +12 -0
  72. package/dist/engine/webhook-contracts.js +172 -0
  73. package/dist/engine/webhook-events.d.ts +34 -0
  74. package/dist/engine/webhook-events.js +85 -0
  75. package/dist/errors/docs-url.js +2 -19
  76. package/dist/errors/error-codes.d.ts +20 -0
  77. package/dist/errors/error-codes.js +19 -0
  78. package/dist/errors/index.d.ts +2 -0
  79. package/dist/errors/index.js +1 -0
  80. package/dist/files/file-routes.js +1 -1
  81. package/dist/i18n/required-surface-keys.d.ts +4 -0
  82. package/dist/i18n/required-surface-keys.js +15 -0
  83. package/dist/schema-cli/shared.d.ts +11 -0
  84. package/dist/schema-cli/shared.js +37 -3
  85. package/dist/schema-cli/validate-command.js +10 -3
  86. package/package.json +3 -3
  87. package/src/changes.json +42 -0
@@ -16,6 +16,21 @@ export function fieldLabelKey(featureName, entityName, fieldName) {
16
16
  export function handlerTitleKey(handlerQn) {
17
17
  return `${handlerQn}:title`;
18
18
  }
19
+ export function handlerDescriptionKey(handlerQn) {
20
+ return `${handlerQn}:description`;
21
+ }
22
+ // `feature:name` becomes `feature:webhook:name`, so the keys never collide with handler keys.
23
+ function webhookEventKeyBase(webhookEventQn) {
24
+ const separator = webhookEventQn.indexOf(":");
25
+ return `${webhookEventQn.slice(0, separator)}:webhook:${webhookEventQn.slice(separator + 1)}`;
26
+ }
27
+ export function webhookEventDescriptionKey(webhookEventQn) {
28
+ return `${webhookEventKeyBase(webhookEventQn)}:description`;
29
+ }
30
+ /** `fieldPath` is the payload row name as the docs list it, nested fields dotted. */
31
+ export function webhookEventFieldKey(webhookEventQn, fieldPath) {
32
+ return `${webhookEventKeyBase(webhookEventQn)}:field:${fieldPath}`;
33
+ }
19
34
  export function handlerFieldLabelKey(handlerQn, fieldName) {
20
35
  return `${handlerQn}:field:${fieldName}`;
21
36
  }
@@ -1,5 +1,6 @@
1
1
  import { type renderTablesDdl } from "../db/index.ts";
2
2
  import { type RowLevelSecurityMode } from "../db/render-rls-ddl.ts";
3
+ import type { BootViolation } from "../engine/boot-validator/boot-rule.ts";
3
4
  import type { FeatureDefinition } from "../engine/types/feature.ts";
4
5
  export type SchemaCliOut = {
5
6
  readonly log: (line: string) => void;
@@ -42,6 +43,16 @@ export declare function parseSchemaRowLevelSecurity(value: unknown, schemaFile:
42
43
  export declare function describeThrown(e: unknown): string;
43
44
  export declare function nextSequenceNumber(migrationsDir: string): number;
44
45
  export declare function loadPreviousSnapshot(snapshotPath: string): import("../db/migrate-generator.ts").Snapshot | null;
46
+ export type CollectedSchemaLoad = {
47
+ readonly kind: "loaded";
48
+ readonly schemaMod: SchemaMod;
49
+ } | {
50
+ readonly kind: "violations";
51
+ readonly violations: readonly BootViolation[];
52
+ } | {
53
+ readonly kind: "failed";
54
+ };
55
+ export declare function loadSchemaModCollectingDefinitionViolations(ctx: SchemaCliContext): Promise<CollectedSchemaLoad>;
45
56
  export declare function loadSchemaModOrReport(ctx: SchemaCliContext): Promise<SchemaMod | undefined>;
46
57
  export declare function loadRowLevelSecurityModeOrReport(ctx: SchemaCliContext): Promise<RowLevelSecurityMode | undefined>;
47
58
  export declare function readDatabaseUrlOrReport(out: SchemaCliOut): string | undefined;
@@ -12,6 +12,8 @@ import { loadSnapshotJson } from "../db/index.js";
12
12
  import { assertUniqueTableNames } from "../db/migrate-generator.js";
13
13
  import { DEFAULT_ROW_LEVEL_SECURITY_MODE, ROW_LEVEL_SECURITY_MODES, } from "../db/render-rls-ddl.js";
14
14
  import { isEntityTableMeta } from "../db/table-introspection.js";
15
+ import { isRuntimeCrash, violationsOf } from "../engine/boot-validator/boot-report.js";
16
+ import { collectDefinitionViolations } from "../engine/definition-violations.js";
15
17
  export const SNAPSHOT_FILENAME = ".snapshot.json";
16
18
  // An absent export means the default mode; a typo must not silently switch tenant isolation off.
17
19
  export function parseSchemaRowLevelSecurity(value, schemaFile) {
@@ -74,12 +76,44 @@ export function nextSequenceNumber(migrationsDir) {
74
76
  export function loadPreviousSnapshot(snapshotPath) {
75
77
  return existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
76
78
  }
79
+ function reportMissingSchemaFile({ out, schemaFile }) {
80
+ out.err(` ${schemaFile} is missing.`);
81
+ out.err(" App convention: kumiko/schema.ts with");
82
+ out.err(" export const ENTITY_METAS: EntityTableMeta[] = [...]");
83
+ }
84
+ // Loads kumiko/schema.ts in collect mode: definition-layer violations of all features come back
85
+ // together instead of the first one aborting the import.
86
+ export async function loadSchemaModCollectingDefinitionViolations(ctx) {
87
+ const { out, schemaFile } = ctx;
88
+ if (!existsSync(schemaFile)) {
89
+ reportMissingSchemaFile(ctx);
90
+ return { kind: "failed" };
91
+ }
92
+ const { violations, outcome } = await collectDefinitionViolations(() => loadSchemaModFromApp(schemaFile));
93
+ if (outcome.loaded) {
94
+ return violations.length === 0
95
+ ? { kind: "loaded", schemaMod: outcome.value }
96
+ : { kind: "violations", violations };
97
+ }
98
+ const { thrown } = outcome;
99
+ if (isRuntimeCrash(thrown)) {
100
+ if (violations.length > 0)
101
+ return { kind: "violations", violations };
102
+ out.err(` ${describeThrown(thrown)}`);
103
+ return { kind: "failed" };
104
+ }
105
+ if (thrown instanceof Error) {
106
+ return {
107
+ kind: "violations",
108
+ violations: [...violations, ...violationsOf(thrown, "loadSchemaMod", undefined)],
109
+ };
110
+ }
111
+ return { kind: "violations", violations };
112
+ }
77
113
  export async function loadSchemaModOrReport(ctx) {
78
114
  const { out, schemaFile } = ctx;
79
115
  if (!existsSync(schemaFile)) {
80
- out.err(` ${schemaFile} is missing.`);
81
- out.err(" App convention: kumiko/schema.ts with");
82
- out.err(" export const ENTITY_METAS: EntityTableMeta[] = [...]");
116
+ reportMissingSchemaFile(ctx);
83
117
  return undefined;
84
118
  }
85
119
  try {
@@ -6,7 +6,7 @@ import { readMigrationSqlTexts } from "../db/migrate-runner.js";
6
6
  import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../db/replay-migration-sql.js";
7
7
  import { BootValidationError, bootRuleDocLink, } from "../engine/boot-validator/boot-rule.js";
8
8
  import { validateBoot } from "../engine/boot-validator.js";
9
- import { describeThrown, loadPreviousSnapshot, loadSchemaModOrReport, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
9
+ import { describeThrown, loadPreviousSnapshot, loadSchemaModCollectingDefinitionViolations, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
10
10
  import { featureDefinitionsOf, parseValidateBootOptions, withFileStoragePresence, } from "./validate-boot-input.js";
11
11
  // 1. Schema drift — compute the diff, never write.
12
12
  function checkSchemaDrift(ctx, schemaMod, prevSnapshot) {
@@ -189,8 +189,14 @@ export async function runValidateCommand(ctx) {
189
189
  // stdout carries exactly one JSON document in --json mode.
190
190
  const out = jsonMode ? { log: ctx.out.err, err: ctx.out.err } : ctx.out;
191
191
  const humanCtx = { ...ctx, out };
192
- const schemaMod = await loadSchemaModOrReport(humanCtx);
193
- if (schemaMod === undefined) {
192
+ const loaded = await loadSchemaModCollectingDefinitionViolations(humanCtx);
193
+ if (loaded.kind === "violations") {
194
+ reportBootViolations(out, loaded.violations);
195
+ if (jsonMode)
196
+ printBootJson(ctx, { ok: false, violations: loaded.violations });
197
+ return 1;
198
+ }
199
+ if (loaded.kind === "failed") {
194
200
  if (jsonMode) {
195
201
  const message = "kumiko/schema.ts could not be loaded";
196
202
  printBootJson(ctx, {
@@ -200,6 +206,7 @@ export async function runValidateCommand(ctx) {
200
206
  }
201
207
  return 1;
202
208
  }
209
+ const { schemaMod } = loaded;
203
210
  const prevSnapshot = loadPreviousSnapshot(join(ctx.migrationsDir, SNAPSHOT_FILENAME));
204
211
  const schemaOk = checkSchemaDrift(humanCtx, schemaMod, prevSnapshot);
205
212
  const boot = checkBootValidity(out, schemaMod);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-framework",
3
- "version": "0.411.0",
3
+ "version": "0.413.0",
4
4
  "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
203
203
  "./package.json": "./package.json"
204
204
  },
205
205
  "dependencies": {
206
- "@cosmicdrift/kumiko-types": "0.411.0",
206
+ "@cosmicdrift/kumiko-types": "0.413.0",
207
207
  "bullmq": "^5.81.5",
208
208
  "hono": "^4.13.14",
209
209
  "i18next": "^26.5.12",
@@ -225,7 +225,7 @@
225
225
  }
226
226
  },
227
227
  "devDependencies": {
228
- "@cosmicdrift/kumiko-testing": "0.411.0",
228
+ "@cosmicdrift/kumiko-testing": "0.413.0",
229
229
  "bun-types": "^1.4.4",
230
230
  "fflate": "^0.8.3",
231
231
  "meilisearch": "^0.62.0",
package/src/changes.json CHANGED
@@ -1,4 +1,46 @@
1
1
  [
2
+ {
3
+ "version": "0.413.0",
4
+ "type": "improvement",
5
+ "title": "Definition errors in schema.ts are collected by validate",
6
+ "detail": "`kumiko-schema validate` (and `kumiko check`) loads `kumiko/schema.ts` in a collect mode. Every failing registrar call and every failing feature setup is recorded instead of aborting the import, so one run prints one `✗ boot [<id>]` line per violation across all features, with `Fix:` and `Rule:` lines, and `--json` lists them in `boot.violations` with `check` (e.g. `r.nav`) and `feature`. Example ids: `nav/id-not-kebab`, `feature/describe-twice`, `handler/access-missing`, `event/pii-stance-empty`, `probe/name-not-kebab`. When such violations exist, validate skips the boot and migration checks, because the feature set is incomplete. Outside validate nothing changes: createApp, the server, the dev server and tests still throw at the first error, at the same place and with the same message; the thrown error is now a `BootRuleViolation` (a subclass of `Error`). A throw at module level outside `defineFeature` still stops the import and appears next to the violations collected before it."
7
+ },
8
+ {
9
+ "version": "0.413.0",
10
+ "type": "improvement",
11
+ "title": "Bundled-feature factory options fail with boot rule ids",
12
+ "detail": "Invalid factory options (`createBillingFoundationFeature` baseUrl and consumerProtection, `createHostDispatch` redirects and locales, `createMetricsFeature` duplicate ids, `createTemplateResolverFeature` tenantEditable, `createSubscriptionMollieFeature` price maps, empty `parents` allowlists on folders, tags and notes-history, and the tenant, readiness and personal-access-tokens boot checks) now throw a `BootRuleViolation` (a subclass of `Error`) carrying `rule.id`. Example ids: `billing-foundation/base-url-required`, `host-routing/invalid-redirect`, `subscription-mollie/price-map-drift`, `template-resolver/tenant-editable-duplicate`, `shared/where-rule-in-ownership-write`. Messages, conditions and the fail-fast behaviour at the same place are unchanged."
13
+ },
14
+ {
15
+ "version": "0.412.0",
16
+ "type": "fix",
17
+ "title": "readGate.fileOwner counts read-model entities as file owners",
18
+ "detail": "A document whose file is attached to a projection entity (for example a mail attachment owned by `inbound-message`) was invisible to everyone but the framework system user, because only `r.entity` entities were owner candidates. Read-model entities with a file field now count, with the same rules as entities (no parentRef, no readGate, uuid ids, tenant scope, soft delete) plus two fail-closed conditions: the viewer's roles must pass the access rule of the read model's `<source>:detail` query, and the entity must declare `access.read`, since its queries filter rows by hand and the gate can only reproduce `access.read`. A read model without `access.read` never makes a document visible. `ParentVisibilityOption` has the optional `readModelEntities` map (entity and projection table) for this; `resolveTable`, link and parentRef gates are unchanged."
19
+ },
20
+ {
21
+ "version": "0.412.0",
22
+ "type": "fix",
23
+ "title": "Scaleway Key Manager and Transactional Email listed as active sub-processor",
24
+ "detail": "The `KUMIKO_SUB_PROCESSORS` entry \"Platform key custody (Key Manager) and Transactional Email Delivery\" moves from `status: \"planned\"` to `\"active\"` (`addedAt` 2026-11-01), so `getActiveSubProcessors()` and the generated privacy texts name it. Transactional mail of the Kumiko apps now goes through Scaleway TEM; the Brevo entry stays until that account is closed, because Brevo still holds the logs of mail it sent."
25
+ },
26
+ {
27
+ "version": "0.412.0",
28
+ "type": "improvement",
29
+ "title": "entity webhook events need `webhookEvents: true` on the entity",
30
+ "detail": "`<entity>.created`, `.updated` and `.deleted` get a derived webhook contract only for entities that set `webhookEvents: true`, so bundle system entities such as `config-value` or `tenant-secret` can never be released through a token scope. Without the flag the entity has no contract and a scope that lists its events fails at boot, with a message naming the entity and the option. Add `webhookEvents: true` to every entity whose events a scope lists; the field exclusions still apply."
31
+ },
32
+ {
33
+ "version": "0.412.0",
34
+ "type": "improvement",
35
+ "title": "r.defineWebhookEvent takes an optional wireName",
36
+ "detail": "`wireName` is the event name receivers see in the delivered webhook, for example `incident.created` for the contract `publicstatus:incident-created`. It defaults to the unqualified `name`, must not be empty, and is `entity.verb` for derived entity contracts. `WebhookEventContract` and `WebhookEventDef` carry it."
37
+ },
38
+ {
39
+ "version": "0.412.0",
40
+ "type": "improvement",
41
+ "title": "r.defineWebhookEvent declares a public webhook event contract",
42
+ "detail": "`r.defineWebhookEvent({ name, description, payload, version })` registers a contract under `<feature>:<name>`, separate from `r.defineEvent`, so an internal event is never released by accident. `registry.getWebhookEventContract(qn)` also returns the contract derived for an entity event (`ticket.created`, `ticket.updated`, `ticket.deleted`): every payload carries the entity `id`, created adds the releasable fields, updated adds `changes` and `previous`, deleted adds `previous`; `toEntityWebhookPayload(contract, event)` maps a stored entity event (aggregate id plus payload) to that shape and drops everything the contract does not release; personal fields, the CRUD `excludedFields`, money and located timestamp fields and encrypted, write-only or sensitive text fields are left out. `registry.getWebhookEventContracts()` lists the declared ones sorted by name. `parseWebhookPayload(contract, payload)` validates a payload and strips unknown keys. New exports: `WebhookEventContract`, `WebhookEventHandle`, `parseWebhookPayload`, `toEntityWebhookPayload`."
43
+ },
2
44
  {
3
45
  "version": "0.411.0",
4
46
  "type": "fix",