@cosmicdrift/kumiko-framework 0.415.0 → 0.416.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 (64) hide show
  1. package/agents/api/framework-engine.md +37 -5
  2. package/agents/api/framework-ui-types.md +59 -3
  3. package/agents/api/renderer-web.md +7 -1
  4. package/agents/api/types.md +21 -2
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +33 -3
  7. package/agents/examples/embedded.md +24 -1
  8. package/agents/examples/handbook-knowledge.md +129 -0
  9. package/agents/examples/signature.md +186 -0
  10. package/agents/examples/writeform-section.md +1 -0
  11. package/agents/examples.md +2 -0
  12. package/agents/features-index.md +4 -0
  13. package/agents/features.md +14 -0
  14. package/dist/api/server-routes.js +2 -0
  15. package/dist/db/table-builder.js +3 -1
  16. package/dist/engine/boot-validator/boot-phases.js +5 -0
  17. package/dist/engine/boot-validator/boot-rules.d.ts +129 -4
  18. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  19. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  20. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  21. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  22. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  23. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  24. package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
  25. package/dist/engine/boot-validator/list-row-guidance.js +30 -0
  26. package/dist/engine/boot-validator/query-output-columns.js +18 -0
  27. package/dist/engine/boot-validator/query-output-guidance.js +2 -0
  28. package/dist/engine/boot-validator/query-refs.js +4 -1
  29. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  30. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  31. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  33. package/dist/engine/boot-validator/screens-actions.js +55 -15
  34. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  35. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  36. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  37. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  38. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  39. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  40. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  41. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  42. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  43. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  44. package/dist/engine/boot-validator/screens-forms.js +108 -2
  45. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  46. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  47. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  48. package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
  49. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  50. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  51. package/dist/engine/boot-validator/screens-lists.js +4 -1
  52. package/dist/engine/build-config-feature-schema.js +5 -35
  53. package/dist/engine/config-access-rules.d.ts +3 -0
  54. package/dist/engine/config-access-rules.js +34 -0
  55. package/dist/engine/factories.d.ts +2 -0
  56. package/dist/engine/project-app-schema-for-roles.js +2 -0
  57. package/dist/files/file-routes.d.ts +2 -0
  58. package/dist/files/file-routes.js +85 -22
  59. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  60. package/dist/files/foreign-tenant-file-read.js +64 -0
  61. package/dist/i18n/required-surface-keys.js +26 -6
  62. package/dist/ui-types/index.d.ts +1 -1
  63. package/package.json +3 -3
  64. package/src/changes.json +42 -0
@@ -397,6 +397,12 @@ Requires: `user-data-rights`
397
397
 
398
398
  Optional requires: `form-draft`
399
399
 
400
+ ## handbook-knowledge
401
+
402
+ Gives the AI agent the app's handbook as two read-only query tools: `list-pages` returns the catalog of task and screen pages with the questions each answers, `read-page` returns one page in the caller's language with a fallback to the default language and a fixed length cap. The pages come from a build-time JSON (`kumiko handbuch knowledge`), so no table, projection or search index is involved and the handbook text stays public content.
403
+
404
+ Category: ai
405
+
400
406
  ## helpdesk
401
407
 
402
408
  Helpdesk inbox: an anonymous browser client (GET /helpdesk/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin. Every request is stored platform-wide and every SystemAdmin is notified by mail, optionally also in a Telegram chat (option `telegram`, off by default); the notification names only the kind, the app and a link, never name, address, phone, subject or message, because mail and Telegram cannot be shredded. SystemAdmins reply by mail (Reply-To set, attachments, quoting the original) and mark requests done; a website sender gets a fixed acknowledgement, a signed-in reporter a copy and an in-app note. Personal data is crypto-shredding-ready and the EXT_USER_DATA hooks export and erase a user's requests.
@@ -660,6 +666,14 @@ Requires: `user`, `auth-foundation`
660
666
 
661
667
  Exposes APIs: `sessions.revokeAllForUser`
662
668
 
669
+ ## signature
670
+
671
+ Signature requests: a signed-in user asks several people to sign one PDF of the tenant. Each signer draws a signature on a display in person or through a link in the URL fragment (14 days, limited opens, revocable, single-use, one answer for every rejection). The last signature moves the request to all-signed; a job renders a signature page through the injected print function, appends it to the unchanged original and completes the request. Events completed, declined and expired report the outcome; signer name, email, image, IP and user agent are personal data.
672
+
673
+ Category: data
674
+
675
+ Requires: `files`, `user-data-rights`
676
+
663
677
  ## step-dispatcher
664
678
 
665
679
  Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. An `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event enqueues one `step-dispatcher:job:deliver` BullMQ job per dispatch (Redis carries only the stream id and tenant, never the request payload). The job performs the actual HTTP or mail delivery and appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream, so the outcome is recorded in the event log without a separate status table. Transient failures (network error, timeout, 5xx, 408, 429, any mail adapter failure) are retried 3 times with exponential backoff; the outcome is recorded after the final attempt and the payload key is erased only then. A request that still has no outcome after 24 hours (job stalled or lost, or its final attempt could not record one) is closed by the daily `step-dispatcher:job:sweep-abandoned` cron (it pages through all such requests; requests that already have an outcome are not swept) with a generic `dispatch-failed` event and its payload key is erased. Permanent failures (invalid url, blocked host, other 4xx, unavailable auth secret) are recorded immediately. At most 2 deliveries per tenant run at once (`maxPerTenant` with `onLimit: "defer"`), so a slow receiver of one tenant does not delay other tenants. Requires a job runner (Redis) and a worker consuming the job's default `worker` lane; without a job runner the projection fails loudly. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across retries and redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.
@@ -1,6 +1,7 @@
1
1
  import { createProjectingTenantDb } from "../db/tenant-db.js";
2
2
  import { isAnonymousSessionUser } from "../engine/system-user.js";
3
3
  import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
4
+ import { createForeignTenantFileReadCheck } from "../files/foreign-tenant-file-read.js";
4
5
  import { createRecordReadCheck } from "../files/record-read-check.js";
5
6
  import { createRecordWriteCheck } from "../files/record-write-check.js";
6
7
  import { createRateLimitResolver } from "../rate-limit/index.js";
@@ -93,6 +94,7 @@ export function mountFileRoutes(app, wiring) {
93
94
  ...(fileRateLimitResolver ? { rateLimitResolver: fileRateLimitResolver } : {}),
94
95
  clientIpResolver: wiring.clientIpResolver,
95
96
  canReadRecord,
97
+ canReadForeignTenantFile: createForeignTenantFileReadCheck(options.registry, dispatcher.query),
96
98
  canWriteRecord: createRecordWriteCheck({
97
99
  registry: options.registry,
98
100
  canReadRecord,
@@ -103,7 +103,9 @@ const COLUMN_EMITTERS = {
103
103
  embedded: (name, snakeName, field) => ({
104
104
  [name]: field.multiple === true ? emptyJsonbArray(snakeName) : emptyJsonbObject(snakeName),
105
105
  }),
106
- jsonb: (name, snakeName) => ({ [name]: emptyJsonbObject(snakeName) }),
106
+ jsonb: (name, snakeName, field) => ({
107
+ [name]: field.emptyValue === "array" ? emptyJsonbArray(snakeName) : emptyJsonbObject(snakeName),
108
+ }),
107
109
  date: singleColumnNotNullWhenRequired(plainDate),
108
110
  timestamp: singleColumnNotNullWhenRequired(instant),
109
111
  tz: singleColumnNotNullWhenRequired(text),
@@ -3,6 +3,7 @@ import { validateActionWiring, validateFieldWiring } from "./action-wiring.js";
3
3
  import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.js";
4
4
  import { collectExposedApis } from "./boot-context.js";
5
5
  import { validateCircularDeps, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, } from "./config-deps.js";
6
+ import { validateCrossTenantFileRead } from "./cross-tenant-file-read.js";
6
7
  import { validateSqlDerivedFields } from "./derived-sql-fields.js";
7
8
  import { collectDetailForScreens } from "./detail-screens.js";
8
9
  import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateExtendSchemaCollisions, validateFileFields, validateHandlerAccess, validateLocatedTimestamps, validateLockedWhen, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
@@ -107,6 +108,10 @@ const FEATURE_CHECKS = [
107
108
  run: (f, c) => validateOwnershipRules(f, c.allClaimKeys, c.knownRoles),
108
109
  },
109
110
  { check: "validateReadGates", run: (f, c) => validateReadGates(f, c.featureMap) },
111
+ {
112
+ check: "validateCrossTenantFileRead",
113
+ run: (f, c) => validateCrossTenantFileRead(f, c.queryHandlerQns),
114
+ },
110
115
  { check: "validateTransferGraph", run: (f, c) => validateTransferGraph(f, c.featureMap) },
111
116
  { check: "validateMultiStreamProjections", run: (f) => validateMultiStreamProjections(f) },
112
117
  ];
@@ -375,6 +375,16 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
375
375
  readonly summary: "A redirect idFrom only targets entityEdit or projectionDetail screens.";
376
376
  readonly fix: "Use the plain string redirect form.";
377
377
  };
378
+ readonly redirectSearchParamsOnlyActionForm: {
379
+ readonly id: "screen/redirect-search-params-only-action-form";
380
+ readonly summary: "A redirect searchParams is only set on actionForm redirects.";
381
+ readonly fix: "Remove searchParams; other screen kinds do not read it.";
382
+ };
383
+ readonly redirectSearchParamsEmpty: {
384
+ readonly id: "screen/redirect-search-params-empty";
385
+ readonly summary: "A redirect searchParams entry has a non-empty param name and payload field.";
386
+ readonly fix: "Map each search param name to a success-payload field.";
387
+ };
378
388
  readonly successLinkTargetsRecordScreen: {
379
389
  readonly id: "screen/success-link-targets-record-screen";
380
390
  readonly summary: "A success link without idFrom does not target a record screen.";
@@ -392,9 +402,14 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
392
402
  };
393
403
  readonly primaryActionUnknown: {
394
404
  readonly id: "screen/primary-action-unknown";
395
- readonly summary: "primaryAction and inlineActions name a declared action id or the default edit.";
405
+ readonly summary: "primaryAction, inlineActions and footerActions name a declared action id or the default edit.";
396
406
  readonly fix: 'Use a declared action id, or "edit" when the screen sets detailFor.';
397
407
  };
408
+ readonly footerActionConflict: {
409
+ readonly id: "screen/footer-action-conflict";
410
+ readonly summary: "A footerActions id is neither the primaryAction nor in inlineActions.";
411
+ readonly fix: "Keep each action in one place: header (primaryAction), inline row or pinned footer.";
412
+ };
398
413
  readonly fallbackWithoutVisibleWhen: {
399
414
  readonly id: "screen/fallback-without-visible-when";
400
415
  readonly summary: "A screen with a fallback also declares visibleWhen.";
@@ -669,10 +684,20 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
669
684
  readonly summary: 'A stat-group\'s columns is 2, 3 or 4 and needs layout "cards".';
670
685
  readonly fix: 'Set columns to 2, 3 or 4 and give the group a label or layout: "cards", or remove columns.';
671
686
  };
687
+ readonly layoutInvalid: {
688
+ readonly id: "dashboard/layout-invalid";
689
+ readonly summary: 'A dashboard layout is "main-side"; a panel column is "side" or "top", used only with that layout and never on a stat-group child.';
690
+ readonly fix: 'Set layout: "main-side" on the dashboard to use column: "side" or "top", or remove column.';
691
+ };
692
+ readonly listColumnVariantInvalid: {
693
+ readonly id: "dashboard/list-column-variant-invalid";
694
+ readonly summary: 'A list column variant is "primary" and needs display: "button".';
695
+ readonly fix: 'Set display: "button" on the column or remove variant.';
696
+ };
672
697
  readonly statGroupChildHideOnNarrow: {
673
698
  readonly id: "dashboard/stat-group-child-hide-on-narrow";
674
- readonly summary: "Stat-group children do not set hideOnNarrow.";
675
- readonly fix: "Set hideOnNarrow on the whole group instead.";
699
+ readonly summary: "A stat-group keeps at least one child on a phone: not every child sets hideOnNarrow.";
700
+ readonly fix: "Set hideOnNarrow on the whole group instead, or keep one child visible.";
676
701
  };
677
702
  readonly listNarrowFieldUnknown: {
678
703
  readonly id: "dashboard/list-narrow-field-unknown";
@@ -921,6 +946,66 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
921
946
  readonly summary: "fillAction does not target a sensitive, writeOnly or password field.";
922
947
  readonly fix: "Remove fillAction.";
923
948
  };
949
+ readonly fieldDescriptionUnknownField: {
950
+ readonly id: "form/field-description-unknown-field";
951
+ readonly summary: "actionForm fieldDescriptions keys name fields of the form.";
952
+ readonly fix: "Name a field of the form or remove the entry.";
953
+ };
954
+ readonly fieldTextParamUnknownField: {
955
+ readonly id: "form/field-text-param-unknown-field";
956
+ readonly summary: "actionForm fieldLabels and fieldDescriptions params name fields of the form.";
957
+ readonly fix: "Point each param at a field of the form or use the plain i18n key.";
958
+ };
959
+ readonly fieldBadgeUnknownField: {
960
+ readonly id: "form/field-badge-unknown-field";
961
+ readonly summary: "actionForm fieldBadges keys name fields of the form.";
962
+ readonly fix: "Name a field of the form or remove the entry.";
963
+ };
964
+ readonly aiAssistContextFieldUnknown: {
965
+ readonly id: "form/ai-assist-context-field-unknown";
966
+ readonly summary: "aiAssist.contextFields names fields of the same form.";
967
+ readonly fix: "Name other fields of the same form or remove the entry.";
968
+ };
969
+ readonly aiAssistFieldType: {
970
+ readonly id: "form/ai-assist-field-type";
971
+ readonly summary: "aiAssist targets a text or longText field.";
972
+ readonly fix: "Remove aiAssist or use a text or longText field.";
973
+ };
974
+ readonly aiAssistSensitiveField: {
975
+ readonly id: "form/ai-assist-sensitive-field";
976
+ readonly summary: "aiAssist does not target a sensitive, writeOnly or password field.";
977
+ readonly fix: "Remove aiAssist; the field text would be sent to the AI.";
978
+ };
979
+ readonly aiAssistChipInvalid: {
980
+ readonly id: "form/ai-assist-chip-invalid";
981
+ readonly summary: "An aiAssist chip has a label and at least one param.";
982
+ readonly fix: 'Set a non-empty label and params such as { style: "short" }.';
983
+ };
984
+ readonly aiAssistResultFieldEmpty: {
985
+ readonly id: "form/ai-assist-result-field-empty";
986
+ readonly summary: "aiAssist names a non-empty resultField.";
987
+ readonly fix: "Set resultField to the key of the query result that holds the text.";
988
+ };
989
+ readonly aiAssistPromptParamEmpty: {
990
+ readonly id: "form/ai-assist-prompt-param-empty";
991
+ readonly summary: "aiAssist.prompt names a non-empty param.";
992
+ readonly fix: "Set prompt.param to the query payload key that receives the typed instruction.";
993
+ };
994
+ readonly aiAssistEmpty: {
995
+ readonly id: "form/ai-assist-empty";
996
+ readonly summary: "aiAssist declares at least one chip or a prompt.";
997
+ readonly fix: "Add chips or prompt, or remove aiAssist.";
998
+ };
999
+ readonly valueChipsFieldType: {
1000
+ readonly id: "form/value-chips-field-type";
1001
+ readonly summary: "valueChips targets a number, decimal, bigInt or money field.";
1002
+ readonly fix: "Remove valueChips or use a numeric or money field.";
1003
+ };
1004
+ readonly valueChipsUnknownField: {
1005
+ readonly id: "form/value-chips-unknown-field";
1006
+ readonly summary: "valueChips.from names a field of the same form.";
1007
+ readonly fix: "Name a field of the same form (hidden and submit: false is fine) that holds the numbers.";
1008
+ };
924
1009
  readonly requiredFieldWithoutWidget: {
925
1010
  readonly id: "form/required-field-without-widget";
926
1011
  readonly summary: "A required entityEdit field has a widget to fill it.";
@@ -1117,6 +1202,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1117
1202
  readonly summary: "Inline form layouts have no relatedList sections.";
1118
1203
  readonly fix: "Move the section to a projectionDetail screen or remove it.";
1119
1204
  };
1205
+ readonly stepListSectionUnsupported: {
1206
+ readonly id: "form/step-list-section-unsupported";
1207
+ readonly summary: "Inline form layouts have no stepList sections.";
1208
+ readonly fix: "Move the section to a projectionDetail screen or remove it.";
1209
+ };
1120
1210
  readonly writeFormSectionUnsupported: {
1121
1211
  readonly id: "form/write-form-section-unsupported";
1122
1212
  readonly summary: "Inline form layouts have no writeForm sections.";
@@ -1175,9 +1265,24 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1175
1265
  };
1176
1266
  readonly hintColumnLink: {
1177
1267
  readonly id: "list/hint-column-link";
1178
- readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot.";
1268
+ readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField, badgeDot or pillField.";
1179
1269
  readonly fix: "Remove the link or badge option, or move the hint to its own column.";
1180
1270
  };
1271
+ readonly photoGridFieldNotInColumns: {
1272
+ readonly id: "list/photo-grid-field-not-in-columns";
1273
+ readonly summary: "photoGrid.imageField and photoGrid.captionField name a field of the section's columns, so the query output is checked.";
1274
+ readonly fix: "Add the field to the section's columns or name another field.";
1275
+ };
1276
+ readonly pillToneWithoutPill: {
1277
+ readonly id: "list/pill-tone-without-pill";
1278
+ readonly summary: "pillToneField colors the pillField pill, so it needs pillField.";
1279
+ readonly fix: "Set pillField on the column or remove pillToneField.";
1280
+ };
1281
+ readonly pillWithDisplay: {
1282
+ readonly id: "list/pill-with-display";
1283
+ readonly summary: "pillField adds a pill beside the cell value and is not combined with display.";
1284
+ readonly fix: "Remove display or pillField from the column.";
1285
+ };
1181
1286
  readonly hintColumnEmptyPlaceholder: {
1182
1287
  readonly id: "list/hint-column-empty-placeholder";
1183
1288
  readonly summary: "A hint column shows hint.emptyLabel for an empty value and sets no emptyPlaceholder.";
@@ -1274,6 +1379,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1274
1379
  readonly summary: "A column renderer's react.__component is a non-empty string.";
1275
1380
  readonly fix: "Set react.__component to the name of a client columnRenderers entry.";
1276
1381
  };
1382
+ readonly relativeTimeOptionsInvalid: {
1383
+ readonly id: "list/relative-time-options-invalid";
1384
+ readonly summary: "relativeTime format options (style, absoluteAfterDays, withTime, timeZone) are valid.";
1385
+ readonly fix: "Use style long, short or narrow, an integer absoluteAfterDays of at least 1 and a boolean withTime and an IANA timeZone.";
1386
+ };
1277
1387
  readonly enumOptionTonesInvalid: {
1278
1388
  readonly id: "list/enum-option-tones-invalid";
1279
1389
  readonly summary: "enumOption column tones are known select option tones.";
@@ -1486,6 +1596,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1486
1596
  readonly summary: "A projectionDetail with a header sets no recordTitleField.";
1487
1597
  readonly fix: "Drop recordTitleField; header.title names the record.";
1488
1598
  };
1599
+ readonly initialTabInvalid: {
1600
+ readonly id: "projection-detail/initial-tab-invalid";
1601
+ readonly summary: "initialTab needs layout.mode tabs and each rule names an existing section id; footerHint needs footerActions.";
1602
+ readonly fix: "Use tabs mode and section ids from the layout for initialTab, or declare footerActions next to footerHint.";
1603
+ };
1489
1604
  readonly tabsSectionGroupsAndActions: {
1490
1605
  readonly id: "projection-detail/tabs-section-groups-and-actions";
1491
1606
  readonly summary: "A tabs-mode section declares groups or actions, not both.";
@@ -3004,6 +3119,16 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
3004
3119
  readonly summary: 'A recordOwned (or whenAbsent: "self") field lives only on entities with idType "uuid", because forgetSubject validates the record id as a UUID.';
3005
3120
  readonly fix: 'Set idType: "uuid" on the entity, or give the field a different personal stance.';
3006
3121
  };
3122
+ readonly crossTenantFileReadQueryUnregistered: {
3123
+ readonly id: "files/cross-tenant-read-query-unregistered";
3124
+ readonly summary: "crossTenantFileRead.query names a registered query handler.";
3125
+ readonly fix: "Use the qualified name of a query handler (<feature>:query:<name>) and register it.";
3126
+ };
3127
+ readonly crossTenantFileReadReasonMissing: {
3128
+ readonly id: "files/cross-tenant-read-reason-missing";
3129
+ readonly summary: "crossTenantFileRead declares a non-empty reason.";
3130
+ readonly fix: "State why files of this entity are readable across tenants.";
3131
+ };
3007
3132
  }, {
3008
3133
  readonly openToAllReasonInvalid: {
3009
3134
  readonly id: "handler/open-to-all-reason-invalid";
@@ -0,0 +1,3 @@
1
+ import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
2
+ import type { FeatureDefinition } from "../types/index.ts";
3
+ export declare function validateCrossTenantFileRead(feature: FeatureDefinition, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
@@ -0,0 +1,19 @@
1
+ import { bootRuleError } from "./boot-rule.js";
2
+ import { ENTITY_DECLARATION_RULES } from "./entity-declaration-rules.js";
3
+ export function validateCrossTenantFileRead(feature, queryHandlers) {
4
+ for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
5
+ const declaration = entity.crossTenantFileRead;
6
+ if (declaration === undefined)
7
+ continue;
8
+ if (declaration.reason.trim().length === 0) {
9
+ throw bootRuleError(ENTITY_DECLARATION_RULES.crossTenantFileReadReasonMissing, {
10
+ message: `[Feature ${feature.name}] entity "${entityName}" declares crossTenantFileRead without a reason; state why its files are readable across tenants.`,
11
+ });
12
+ }
13
+ if (!queryHandlers.has(declaration.query)) {
14
+ throw bootRuleError(ENTITY_DECLARATION_RULES.crossTenantFileReadQueryUnregistered, {
15
+ message: `[Feature ${feature.name}] entity "${entityName}" declares crossTenantFileRead.query "${declaration.query}" which is not a registered query-handler. Check the QN spelling (expected "<feature>:query:<short>") and that the handler is declared via r.queryHandler(...).`,
16
+ });
17
+ }
18
+ }
19
+ }
@@ -94,4 +94,14 @@ export declare const ENTITY_DECLARATION_RULES: {
94
94
  readonly summary: 'A recordOwned (or whenAbsent: "self") field lives only on entities with idType "uuid", because forgetSubject validates the record id as a UUID.';
95
95
  readonly fix: 'Set idType: "uuid" on the entity, or give the field a different personal stance.';
96
96
  };
97
+ readonly crossTenantFileReadQueryUnregistered: {
98
+ readonly id: "files/cross-tenant-read-query-unregistered";
99
+ readonly summary: "crossTenantFileRead.query names a registered query handler.";
100
+ readonly fix: "Use the qualified name of a query handler (<feature>:query:<name>) and register it.";
101
+ };
102
+ readonly crossTenantFileReadReasonMissing: {
103
+ readonly id: "files/cross-tenant-read-reason-missing";
104
+ readonly summary: "crossTenantFileRead declares a non-empty reason.";
105
+ readonly fix: "State why files of this entity are readable across tenants.";
106
+ };
97
107
  };
@@ -94,4 +94,14 @@ export const ENTITY_DECLARATION_RULES = {
94
94
  summary: 'A recordOwned (or whenAbsent: "self") field lives only on entities with idType "uuid", because forgetSubject validates the record id as a UUID.',
95
95
  fix: 'Set idType: "uuid" on the entity, or give the field a different personal stance.',
96
96
  },
97
+ crossTenantFileReadQueryUnregistered: {
98
+ id: "files/cross-tenant-read-query-unregistered",
99
+ summary: "crossTenantFileRead.query names a registered query handler.",
100
+ fix: "Use the qualified name of a query handler (<feature>:query:<name>) and register it.",
101
+ },
102
+ crossTenantFileReadReasonMissing: {
103
+ id: "files/cross-tenant-read-reason-missing",
104
+ summary: "crossTenantFileRead declares a non-empty reason.",
105
+ fix: "State why files of this entity are readable across tenants.",
106
+ },
97
107
  };
@@ -11,9 +11,24 @@ export declare const LIST_ROW_GUIDANCE_RULES: {
11
11
  };
12
12
  readonly hintColumnLink: {
13
13
  readonly id: "list/hint-column-link";
14
- readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot.";
14
+ readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField, badgeDot or pillField.";
15
15
  readonly fix: "Remove the link or badge option, or move the hint to its own column.";
16
16
  };
17
+ readonly photoGridFieldNotInColumns: {
18
+ readonly id: "list/photo-grid-field-not-in-columns";
19
+ readonly summary: "photoGrid.imageField and photoGrid.captionField name a field of the section's columns, so the query output is checked.";
20
+ readonly fix: "Add the field to the section's columns or name another field.";
21
+ };
22
+ readonly pillToneWithoutPill: {
23
+ readonly id: "list/pill-tone-without-pill";
24
+ readonly summary: "pillToneField colors the pillField pill, so it needs pillField.";
25
+ readonly fix: "Set pillField on the column or remove pillToneField.";
26
+ };
27
+ readonly pillWithDisplay: {
28
+ readonly id: "list/pill-with-display";
29
+ readonly summary: "pillField adds a pill beside the cell value and is not combined with display.";
30
+ readonly fix: "Remove display or pillField from the column.";
31
+ };
17
32
  readonly hintColumnEmptyPlaceholder: {
18
33
  readonly id: "list/hint-column-empty-placeholder";
19
34
  readonly summary: "A hint column shows hint.emptyLabel for an empty value and sets no emptyPlaceholder.";
@@ -11,9 +11,24 @@ export const LIST_ROW_GUIDANCE_RULES = {
11
11
  },
12
12
  hintColumnLink: {
13
13
  id: "list/hint-column-link",
14
- summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot.",
14
+ summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField, badgeDot or pillField.",
15
15
  fix: "Remove the link or badge option, or move the hint to its own column.",
16
16
  },
17
+ photoGridFieldNotInColumns: {
18
+ id: "list/photo-grid-field-not-in-columns",
19
+ summary: "photoGrid.imageField and photoGrid.captionField name a field of the section's columns, so the query output is checked.",
20
+ fix: "Add the field to the section's columns or name another field.",
21
+ },
22
+ pillToneWithoutPill: {
23
+ id: "list/pill-tone-without-pill",
24
+ summary: "pillToneField colors the pillField pill, so it needs pillField.",
25
+ fix: "Set pillField on the column or remove pillToneField.",
26
+ },
27
+ pillWithDisplay: {
28
+ id: "list/pill-with-display",
29
+ summary: "pillField adds a pill beside the cell value and is not combined with display.",
30
+ fix: "Remove display or pillField from the column.",
31
+ },
17
32
  hintColumnEmptyPlaceholder: {
18
33
  id: "list/hint-column-empty-placeholder",
19
34
  summary: "A hint column shows hint.emptyLabel for an empty value and sets no emptyPlaceholder.",
@@ -15,6 +15,13 @@ export type EntityRowFields = {
15
15
  readonly fieldNames: ReadonlySet<string>;
16
16
  readonly rowDecorationFields?: RowDecorationFields | undefined;
17
17
  };
18
+ export declare function validatePhotoGrid(where: string, section: {
19
+ readonly columns: readonly ListColumnSpec[];
20
+ readonly photoGrid?: {
21
+ readonly imageField: string;
22
+ readonly captionField?: string;
23
+ };
24
+ }): void;
18
25
  type GuidanceListKind = "entityList" | "projectionList" | "dashboard" | "relatedList";
19
26
  export declare function validateListRowGuidance(featureName: string, screenId: string, kind: GuidanceListKind, screen: RowGuidanceScreen, entityFields?: EntityRowFields, partLabel?: string): void;
20
27
  export {};
@@ -15,6 +15,7 @@ const HINT_CONFLICTS = [
15
15
  { option: "refEntity", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
16
16
  { option: "badgeToneField", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
17
17
  { option: "badgeDot", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
18
+ { option: "pillField", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
18
19
  { option: "emptyPlaceholder", rule: LIST_ROW_GUIDANCE_RULES.hintColumnEmptyPlaceholder },
19
20
  ];
20
21
  function validateHintColumn(where, column) {
@@ -60,6 +61,34 @@ function validateNarrowOnlyColumn(where, column) {
60
61
  });
61
62
  }
62
63
  }
64
+ export function validatePhotoGrid(where, section) {
65
+ const { photoGrid } = section;
66
+ if (photoGrid === undefined)
67
+ return;
68
+ const columnFields = new Set(section.columns.map((col) => normalizeListColumn(col).field));
69
+ for (const [option, field] of [
70
+ ["imageField", photoGrid.imageField],
71
+ ["captionField", photoGrid.captionField],
72
+ ]) {
73
+ if (field === undefined || columnFields.has(field))
74
+ continue;
75
+ throw bootRuleError(LIST_ROW_GUIDANCE_RULES.photoGridFieldNotInColumns, {
76
+ message: `${where} photoGrid.${option} "${field}" is not one of the section's columns (${[...columnFields].join(", ")}). Add it to columns or name another field.`,
77
+ });
78
+ }
79
+ }
80
+ function validatePillColumn(where, column) {
81
+ if (column.pillToneField !== undefined && column.pillField === undefined) {
82
+ throw bootRuleError(LIST_ROW_GUIDANCE_RULES.pillToneWithoutPill, {
83
+ message: `${where} column "${column.field}" sets pillToneField without pillField. Set pillField or remove pillToneField.`,
84
+ });
85
+ }
86
+ if (column.pillField !== undefined && column.display !== undefined) {
87
+ throw bootRuleError(LIST_ROW_GUIDANCE_RULES.pillWithDisplay, {
88
+ message: `${where} column "${column.field}" sets both pillField and display. Remove one of them.`,
89
+ });
90
+ }
91
+ }
63
92
  function validateButtonColumn(where, column, kind) {
64
93
  if (column.display === "button" && kind !== "dashboard") {
65
94
  throw bootRuleError(LIST_ROW_GUIDANCE_RULES.buttonColumnInListTable, {
@@ -123,6 +152,7 @@ partLabel) {
123
152
  const column = normalizeListColumn(col);
124
153
  validateHintColumn(where, column);
125
154
  validateNarrowOnlyColumn(where, column);
155
+ validatePillColumn(where, column);
126
156
  validateButtonColumn(where, column, kind);
127
157
  }
128
158
  validateNamedFilterOptions(where, screen);
@@ -149,6 +149,15 @@ function checkDetailSectionFields(recordShape, prefix, screen) {
149
149
  if (countField !== undefined) {
150
150
  checkFieldExists(recordShape, countField, () => `${prefix} section "${section.title ?? "(untitled)"}" countField references field "${countField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
151
151
  }
152
+ if (section.visibleWhen !== undefined) {
153
+ const conditionField = section.visibleWhen.field;
154
+ checkFieldExists(recordShape, conditionField, () => `${prefix} section "${section.title ?? section.id ?? "(untitled)"}" visibleWhen references field "${conditionField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
155
+ }
156
+ if (section.kind === "stepList") {
157
+ const stepField = section.field;
158
+ checkFieldExists(recordShape, stepField, () => `${prefix} stepList section "${section.title ?? section.id ?? "(untitled)"}" references field "${stepField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
159
+ continue;
160
+ }
152
161
  if (section.kind !== undefined && section.kind !== "fields")
153
162
  continue;
154
163
  for (const entry of sectionFieldSpecs(section)) {
@@ -286,11 +295,20 @@ function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen)
286
295
  screen.type === "configEdit" ||
287
296
  screen.type === "secretMint") {
288
297
  checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screen.type, screen.layout);
298
+ if (screen.type === "actionForm")
299
+ checkSummaryLoadFields(queryHandlers, featureName, screenId, screen);
289
300
  }
290
301
  else if (screen.type === "dashboard") {
291
302
  checkDashboardOutputFields(queryHandlers, featureName, screenId, screen);
292
303
  }
293
304
  }
305
+ // summary.paramsFromLoad reads the raw load result, so each name must be an output field of the load query.
306
+ function checkSummaryLoadFields(queryHandlers, featureName, screenId, screen) {
307
+ const shape = getZodObjectShape(screen.load === undefined ? undefined : queryHandlers.get(screen.load.query)?.outputSchema);
308
+ for (const field of screen.summary?.paramsFromLoad ?? []) {
309
+ checkFieldExists(shape, field, () => `[Feature ${featureName}] Screen "${screenId}" (actionForm) summary.paramsFromLoad references field "${field}" which is not present in load query "${screen.load?.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
310
+ }
311
+ }
294
312
  export function validateQueryOutputColumns(features) {
295
313
  const queryHandlers = buildQueryHandlerMap(features);
296
314
  checkPagedHandlerOutputSchemaShape(queryHandlers);
@@ -27,6 +27,8 @@ export function listGuidanceFieldRefs(screen) {
27
27
  const hint = column.hint;
28
28
  return [
29
29
  { option: "linkParamsField", field: column.linkParamsField },
30
+ { option: "pillField", field: column.pillField },
31
+ { option: "pillToneField", field: column.pillToneField },
30
32
  { option: "hint.detailField", field: hint?.detailField },
31
33
  { option: "hint.narrowDetailField", field: hint?.narrowDetailField },
32
34
  { option: "hint.narrowField", field: hint?.narrowField },
@@ -48,7 +48,10 @@ function checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screenTy
48
48
  for (const section of layout.sections) {
49
49
  if (isFieldsEditSection(section)) {
50
50
  for (const fieldSpec of sectionFieldSpecs(section)) {
51
- const { field, fillAction } = normalizeEditField(fieldSpec);
51
+ const { field, fillAction, aiAssist } = normalizeEditField(fieldSpec);
52
+ if (aiAssist !== undefined) {
53
+ checkQueryRef(queryHandlers, aiAssist.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${field}" aiAssist`);
54
+ }
52
55
  if (fillAction === undefined)
53
56
  continue;
54
57
  checkQueryRef(queryHandlers, fillAction.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${field}" fillAction`);
@@ -0,0 +1 @@
1
+ export declare function validateRelativeTimeFormat(prefix: string, label: string, format: unknown): void;
@@ -0,0 +1,51 @@
1
+ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
2
+ import { bootRuleError } from "./boot-rule.js";
3
+ import { LIST_SCREEN_RULES } from "./screens-lists-rules.js";
4
+ const RELATIVE_TIME_STYLES = ["long", "short", "narrow"];
5
+ function isKnownTimeZone(value) {
6
+ if (typeof value !== "string")
7
+ return false;
8
+ try {
9
+ new Intl.DateTimeFormat("en", { timeZone: value });
10
+ return true;
11
+ }
12
+ catch {
13
+ return false;
14
+ }
15
+ }
16
+ function relativeTimeOptionProblem(format) {
17
+ const style = propertyOf(format, "style");
18
+ if (style !== undefined && !RELATIVE_TIME_STYLES.includes(style)) {
19
+ return `style ${String(style)} (expected long, short or narrow)`;
20
+ }
21
+ const absoluteAfterDays = propertyOf(format, "absoluteAfterDays");
22
+ if (absoluteAfterDays !== undefined &&
23
+ !(typeof absoluteAfterDays === "number" &&
24
+ Number.isInteger(absoluteAfterDays) &&
25
+ absoluteAfterDays >= 1)) {
26
+ return `absoluteAfterDays ${String(absoluteAfterDays)} (expected an integer of at least 1)`;
27
+ }
28
+ const timeZone = propertyOf(format, "timeZone");
29
+ if (timeZone !== undefined && !isKnownTimeZone(timeZone)) {
30
+ return `timeZone ${String(timeZone)} (expected an IANA zone id such as Europe/Berlin)`;
31
+ }
32
+ const withTime = propertyOf(format, "withTime");
33
+ if (withTime !== undefined && typeof withTime !== "boolean") {
34
+ return `withTime ${String(withTime)} (expected a boolean)`;
35
+ }
36
+ return undefined;
37
+ }
38
+ // A typo'd option would silently fall back to the plain relative text.
39
+ export function validateRelativeTimeFormat(prefix, label, format) {
40
+ // skip: only a relativeTime format has these options
41
+ if (typeof format !== "object" || format === null)
42
+ return;
43
+ if (propertyOf(format, "format") !== "relativeTime")
44
+ return;
45
+ const problem = relativeTimeOptionProblem(format);
46
+ if (problem === undefined)
47
+ return;
48
+ throw bootRuleError(LIST_SCREEN_RULES.relativeTimeOptionsInvalid, {
49
+ message: `${prefix} ${label} has relativeTime option ${problem}.`,
50
+ });
51
+ }
@@ -129,6 +129,16 @@ export declare const SCREEN_ACTION_RULES: {
129
129
  readonly summary: "A redirect idFrom only targets entityEdit or projectionDetail screens.";
130
130
  readonly fix: "Use the plain string redirect form.";
131
131
  };
132
+ readonly redirectSearchParamsOnlyActionForm: {
133
+ readonly id: "screen/redirect-search-params-only-action-form";
134
+ readonly summary: "A redirect searchParams is only set on actionForm redirects.";
135
+ readonly fix: "Remove searchParams; other screen kinds do not read it.";
136
+ };
137
+ readonly redirectSearchParamsEmpty: {
138
+ readonly id: "screen/redirect-search-params-empty";
139
+ readonly summary: "A redirect searchParams entry has a non-empty param name and payload field.";
140
+ readonly fix: "Map each search param name to a success-payload field.";
141
+ };
132
142
  readonly successLinkTargetsRecordScreen: {
133
143
  readonly id: "screen/success-link-targets-record-screen";
134
144
  readonly summary: "A success link without idFrom does not target a record screen.";
@@ -146,9 +156,14 @@ export declare const SCREEN_ACTION_RULES: {
146
156
  };
147
157
  readonly primaryActionUnknown: {
148
158
  readonly id: "screen/primary-action-unknown";
149
- readonly summary: "primaryAction and inlineActions name a declared action id or the default edit.";
159
+ readonly summary: "primaryAction, inlineActions and footerActions name a declared action id or the default edit.";
150
160
  readonly fix: 'Use a declared action id, or "edit" when the screen sets detailFor.';
151
161
  };
162
+ readonly footerActionConflict: {
163
+ readonly id: "screen/footer-action-conflict";
164
+ readonly summary: "A footerActions id is neither the primaryAction nor in inlineActions.";
165
+ readonly fix: "Keep each action in one place: header (primaryAction), inline row or pinned footer.";
166
+ };
152
167
  readonly fallbackWithoutVisibleWhen: {
153
168
  readonly id: "screen/fallback-without-visible-when";
154
169
  readonly summary: "A screen with a fallback also declares visibleWhen.";