@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
@@ -166,6 +166,8 @@
166
166
  | <a id="dashboard-filter-options-empty"></a>`dashboard/filter-options-empty` | Static filter options are non-empty. | Declare at least one option or use optionsQuery. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
167
167
  | <a id="dashboard-filter-options-query-empty"></a>`dashboard/filter-options-query-empty` | filter.optionsQuery is non-empty when set. | Set optionsQuery to a query name or remove it. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
168
168
  | <a id="dashboard-filter-options-xor"></a>`dashboard/filter-options-xor` | The dashboard filter sets exactly one of options and optionsQuery. | Keep either options or optionsQuery. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
169
+ | <a id="dashboard-layout-invalid"></a>`dashboard/layout-invalid` | 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. | Set layout: "main-side" on the dashboard to use column: "side" or "top", or remove column. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
170
+ | <a id="dashboard-list-column-variant-invalid"></a>`dashboard/list-column-variant-invalid` | A list column variant is "primary" and needs display: "button". | Set display: "button" on the column or remove variant. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
169
171
  | <a id="dashboard-list-narrow-field-unknown"></a>`dashboard/list-narrow-field-unknown` | A list panel's narrow.field is set only with narrow.layout "line" and names a non-empty query output field; narrow.titleField needs the cards layout and a hint column. | Set narrow.layout "line" and name a field of the query output, or remove narrow.field. For narrow.titleField keep the cards layout and a hint column. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
170
172
  | <a id="dashboard-list-narrow-invalid"></a>`dashboard/list-narrow-invalid` | A list panel's narrow.limit is a positive integer, narrow.layout is "cards" or "line", and narrow.moreText and icon appear only with the "line" layout. | Set narrow.limit to a whole number of at least 1 and narrow.layout to "cards" or "line"; use narrow.moreText and icon only with "line". | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
171
173
  | <a id="dashboard-list-narrow-line-without-footer-link"></a>`dashboard/list-narrow-line-without-footer-link` | A list panel with narrow.layout "line" declares footerLink, the target of the line. | Add footerLink or use narrow.layout "cards". | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
@@ -188,7 +190,7 @@
188
190
  | <a id="dashboard-refresh-field-without-record-query"></a>`dashboard/refresh-field-without-record-query` | A field-driven refresh has a record.query to read the seconds from. | Add record: { param, query } or use refresh: { seconds }. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
189
191
  | <a id="dashboard-refresh-seconds-and-field"></a>`dashboard/refresh-seconds-and-field` | A dashboard refresh sets either seconds or field, not both. | Keep exactly one of seconds and field. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
190
192
  | <a id="dashboard-refresh-seconds-too-short"></a>`dashboard/refresh-seconds-too-short` | refresh.seconds is a number of at least DASHBOARD_MIN_REFRESH_SECONDS. | Raise refresh.seconds to the minimum or more. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
191
- | <a id="dashboard-stat-group-child-hide-on-narrow"></a>`dashboard/stat-group-child-hide-on-narrow` | Stat-group children do not set hideOnNarrow. | Set hideOnNarrow on the whole group instead. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
193
+ | <a id="dashboard-stat-group-child-hide-on-narrow"></a>`dashboard/stat-group-child-hide-on-narrow` | A stat-group keeps at least one child on a phone: not every child sets hideOnNarrow. | Set hideOnNarrow on the whole group instead, or keep one child visible. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
192
194
  | <a id="dashboard-stat-group-child-visible-when"></a>`dashboard/stat-group-child-visible-when` | Stat-group children do not set visibleWhen. | Gate the whole group with visibleWhen instead. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
193
195
  | <a id="dashboard-stat-group-columns-invalid"></a>`dashboard/stat-group-columns-invalid` | A stat-group's columns is 2, 3 or 4 and needs layout "cards". | Set columns to 2, 3 or 4 and give the group a label or layout: "cards", or remove columns. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
194
196
  | <a id="dashboard-stat-group-empty"></a>`dashboard/stat-group-empty` | A stat-group declares at least one stat. | Add at least one stat. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
@@ -429,6 +431,13 @@
429
431
  | --- | --- | --- | --- |
430
432
  | <a id="file-storage-provider-env-missing"></a>`file-storage/provider-env-missing` | An app with file or image fields sets the FILE_STORAGE_PROVIDER environment variable. | Set FILE_STORAGE_PROVIDER in the environment. | `packages/framework/src/engine/boot-validator/boot-environment-rules.ts` |
431
433
 
434
+ ## files
435
+
436
+ | Rule | Summary | Fix | Source |
437
+ | --- | --- | --- | --- |
438
+ | <a id="files-cross-tenant-read-query-unregistered"></a>`files/cross-tenant-read-query-unregistered` | crossTenantFileRead.query names a registered query handler. | Use the qualified name of a query handler (<feature>:query:<name>) and register it. | `packages/framework/src/engine/boot-validator/entity-declaration-rules.ts` |
439
+ | <a id="files-cross-tenant-read-reason-missing"></a>`files/cross-tenant-read-reason-missing` | crossTenantFileRead declares a non-empty reason. | State why files of this entity are readable across tenants. | `packages/framework/src/engine/boot-validator/entity-declaration-rules.ts` |
440
+
432
441
  ## folders
433
442
 
434
443
  | Rule | Summary | Fix | Source |
@@ -440,6 +449,13 @@
440
449
  | Rule | Summary | Fix | Source |
441
450
  | --- | --- | --- | --- |
442
451
  | <a id="form-affix-unknown-field"></a>`form/affix-unknown-field` | A { field } prefix or suffix names another field of the same form. | Name a field of the same form. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
452
+ | <a id="form-ai-assist-chip-invalid"></a>`form/ai-assist-chip-invalid` | An aiAssist chip has a label and at least one param. | Set a non-empty label and params such as { style: "short" }. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
453
+ | <a id="form-ai-assist-context-field-unknown"></a>`form/ai-assist-context-field-unknown` | aiAssist.contextFields names fields of the same form. | Name other fields of the same form or remove the entry. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
454
+ | <a id="form-ai-assist-empty"></a>`form/ai-assist-empty` | aiAssist declares at least one chip or a prompt. | Add chips or prompt, or remove aiAssist. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
455
+ | <a id="form-ai-assist-field-type"></a>`form/ai-assist-field-type` | aiAssist targets a text or longText field. | Remove aiAssist or use a text or longText field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
456
+ | <a id="form-ai-assist-prompt-param-empty"></a>`form/ai-assist-prompt-param-empty` | aiAssist.prompt names a non-empty param. | Set prompt.param to the query payload key that receives the typed instruction. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
457
+ | <a id="form-ai-assist-result-field-empty"></a>`form/ai-assist-result-field-empty` | aiAssist names a non-empty resultField. | Set resultField to the key of the query result that holds the text. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
458
+ | <a id="form-ai-assist-sensitive-field"></a>`form/ai-assist-sensitive-field` | aiAssist does not target a sensitive, writeOnly or password field. | Remove aiAssist; the field text would be sent to the AI. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
443
459
  | <a id="form-config-secret-also-config-key"></a>`form/config-secret-also-config-key` | A configEdit field is mapped in configKeys or secretKeys, not both. | Keep one of the mappings. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
444
460
  | <a id="form-config-secret-field-type"></a>`form/config-secret-field-type` | A secret-mapped configEdit field is a writeOnly text field. | Make the field a writeOnly text field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
445
461
  | <a id="form-config-secret-scope"></a>`form/config-secret-scope` | Secret-mapped configEdit fields are on a tenant- or system-scope screen. | Use scope "tenant" or "system", or drop the secret mapping. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
@@ -454,6 +470,9 @@
454
470
  | <a id="form-embedded-list-on-non-list-field"></a>`form/embedded-list-on-non-list-field` | embeddedList is set only on an embedded list field. | Remove embeddedList or point it at an embedded list field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
455
471
  | <a id="form-embedded-list-unknown-sub-field"></a>`form/embedded-list-unknown-sub-field` | embeddedList cell options name sub-fields of the embedded schema. | Name an existing sub-field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
456
472
  | <a id="form-extension-section-no-component"></a>`form/extension-section-no-component` | An extension section declares a react or native component. | Declare a react/native component marker. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
473
+ | <a id="form-field-badge-unknown-field"></a>`form/field-badge-unknown-field` | actionForm fieldBadges keys name fields of the form. | Name a field of the form or remove the entry. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
474
+ | <a id="form-field-description-unknown-field"></a>`form/field-description-unknown-field` | actionForm fieldDescriptions keys name fields of the form. | Name a field of the form or remove the entry. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
475
+ | <a id="form-field-text-param-unknown-field"></a>`form/field-text-param-unknown-field` | actionForm fieldLabels and fieldDescriptions params name fields of the form. | Point each param at a field of the form or use the plain i18n key. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
457
476
  | <a id="form-field-type-missing"></a>`form/field-type-missing` | Every inline form field declares a type. | Declare a type such as "text", "number" or "select". | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
458
477
  | <a id="form-fields-empty"></a>`form/fields-empty` | An inline form declares at least one field. | Declare at least one field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
459
478
  | <a id="form-fill-action-field-type"></a>`form/fill-action-field-type` | fillAction targets a text, number, decimal or bigInt field. | Remove fillAction or use a fitting field type. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
@@ -481,6 +500,7 @@
481
500
  | <a id="form-select-options-and-query"></a>`form/select-options-and-query` | A select field declares static options or optionsQuery, not both. | Pick one of options and optionsQuery. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
482
501
  | <a id="form-select-options-query-empty"></a>`form/select-options-query-empty` | A select field's optionsQuery is non-empty when set. | Set it to a query name or remove it. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
483
502
  | <a id="form-select-query-and-availability"></a>`form/select-query-and-availability` | optionsAvailabilityQuery is not combined with optionsQuery. | Remove optionsAvailabilityQuery or use static options. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
503
+ | <a id="form-step-list-section-unsupported"></a>`form/step-list-section-unsupported` | Inline form layouts have no stepList sections. | Move the section to a projectionDetail screen or remove it. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
484
504
  | <a id="form-success-facts-with-redirect"></a>`form/success-facts-with-redirect` | An actionForm sets either redirect or successFacts. | Use one of them. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
485
505
  | <a id="form-success-links-with-redirect"></a>`form/success-links-with-redirect` | An actionForm sets either redirect or successLinks. | Use one of them. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
486
506
  | <a id="form-tab-id-duplicate"></a>`form/tab-id-duplicate` | Tab section ids are unique. | Give each tab section a unique id. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
@@ -489,6 +509,8 @@
489
509
  | <a id="form-tab-title-missing"></a>`form/tab-title-missing` | Every tab section has a non-empty title. | Give each tab section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
490
510
  | <a id="form-tabs-too-few-sections"></a>`form/tabs-too-few-sections` | A tabs layout has at least two sections. | Add a section or use another mode. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
491
511
  | <a id="form-tabs-unsupported-screen-type"></a>`form/tabs-unsupported-screen-type` | Tabs layout is used only on projectionDetail and entityEdit screens. | Use mode: "wizard" or "single". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
512
+ | <a id="form-value-chips-field-type"></a>`form/value-chips-field-type` | valueChips targets a number, decimal, bigInt or money field. | Remove valueChips or use a numeric or money field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
513
+ | <a id="form-value-chips-unknown-field"></a>`form/value-chips-unknown-field` | valueChips.from names a field of the same form. | Name a field of the same form (hidden and submit: false is fine) that holds the numbers. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
492
514
  | <a id="form-wizard-option-without-wizard"></a>`form/wizard-option-without-wizard` | layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout. | Remove the option or set mode: "wizard". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
493
515
  | <a id="form-wizard-step-title-missing"></a>`form/wizard-step-title-missing` | Every wizard section has a non-empty title. | Give each wizard section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
494
516
  | <a id="form-wizard-submit-condition-field-unknown"></a>`form/wizard-submit-condition-field-unknown` | layout.wizard.submitDisabledWhen names a field of the layout. | Use a field name declared in one of the sections. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
@@ -663,7 +685,7 @@
663
685
  | <a id="list-guidance-field-empty"></a>`list/guidance-field-empty` | rowToneField, linkParamsField and the hint field names are non-empty strings. | Name a row field or remove the option. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
664
686
  | <a id="list-hint-column-display"></a>`list/hint-column-display` | A hint column owns its cell rendering and sets no display. | Remove display or hint from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
665
687
  | <a id="list-hint-column-empty-placeholder"></a>`list/hint-column-empty-placeholder` | A hint column shows hint.emptyLabel for an empty value and sets no emptyPlaceholder. | Remove emptyPlaceholder, or name the empty sentence with hint.emptyLabel. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
666
- | <a id="list-hint-column-link"></a>`list/hint-column-link` | A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot. | Remove the link or badge option, or move the hint to its own column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
688
+ | <a id="list-hint-column-link"></a>`list/hint-column-link` | A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField, badgeDot or pillField. | Remove the link or badge option, or move the hint to its own column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
667
689
  | <a id="list-hint-column-renderer"></a>`list/hint-column-renderer` | A hint column owns its cell rendering and sets no renderer. | Remove renderer or hint from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
668
690
  | <a id="list-link-params-without-screen-field"></a>`list/link-params-without-screen-field` | linkParamsField only parametrizes the linkScreenField target. | Set linkScreenField on the column or remove linkParamsField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
669
691
  | <a id="list-named-filter-empty-state-params-query-empty"></a>`list/named-filter-empty-state-params-query-empty` | A named filter's emptyState.paramsQuery is a non-empty query QN. | Name the query or remove paramsQuery from the emptyState. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
@@ -675,12 +697,16 @@
675
697
  | <a id="list-narrow-detail-field-without-detail-field"></a>`list/narrow-detail-field-without-detail-field` | hint.narrowDetailField replaces hint.detailField below sm, so it needs detailField. | Set hint.detailField or remove narrowDetailField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
676
698
  | <a id="list-narrow-facets-invalid"></a>`list/narrow-facets-invalid` | narrowFacets is "pills". | Use "pills", or remove narrowFacets. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
677
699
  | <a id="list-narrow-only-conflict"></a>`list/narrow-only-conflict` | A showOnNarrowOnly column sets none of hideOnNarrow: true, hidden: true or pinned. | Remove the conflicting option or showOnNarrowOnly. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
700
+ | <a id="list-photo-grid-field-not-in-columns"></a>`list/photo-grid-field-not-in-columns` | photoGrid.imageField and photoGrid.captionField name a field of the section's columns, so the query output is checked. | Add the field to the section's columns or name another field. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
701
+ | <a id="list-pill-tone-without-pill"></a>`list/pill-tone-without-pill` | pillToneField colors the pillField pill, so it needs pillField. | Set pillField on the column or remove pillToneField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
702
+ | <a id="list-pill-with-display"></a>`list/pill-with-display` | pillField adds a pill beside the cell value and is not combined with display. | Remove display or pillField from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
678
703
  | <a id="list-reason-option-without-reason-field"></a>`list/reason-option-without-reason-field` | hint.reasonOpenField and hint.reasonTitleField shape the reason text, so they need reasonField. | Set hint.reasonField or remove reasonOpenField and reasonTitleField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
679
704
  | <a id="list-ref-target-entity-unknown"></a>`list/ref-target-entity-unknown` | An entity reference target resolves to a registered entity. | Name an entity the target feature registers. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
680
705
  | <a id="list-ref-target-feature-not-mounted"></a>`list/ref-target-feature-not-mounted` | An entity reference target belongs to a mounted feature. | Mount the feature and declare it in r.requires({ features }). | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
681
706
  | <a id="list-related-read-only-with-row-interaction"></a>`list/related-read-only-with-row-interaction` | A readOnly relatedList section declares no rowClick or rowActions. | Remove readOnly or the row interaction. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
682
707
  | <a id="list-related-row-click-no-detail"></a>`list/related-row-click-no-detail` | A relatedList rowClick entity target has a screen declaring detailFor for it. | Add detailFor to the screen that shows the entity. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
683
708
  | <a id="list-related-toolbar-visible-when"></a>`list/related-toolbar-visible-when` | relatedList toolbarActions use visible instead of visibleWhen. | Use visible, a condition on the enclosing record. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
709
+ | <a id="list-relative-time-options-invalid"></a>`list/relative-time-options-invalid` | relativeTime format options (style, absoluteAfterDays, withTime, timeZone) are valid. | Use style long, short or narrow, an integer absoluteAfterDays of at least 1 and a boolean withTime and an IANA timeZone. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
684
710
  | <a id="list-row-decoration-ids-missing"></a>`list/row-decoration-ids-missing` | The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call. | Add `ids: z.array(z.string())` to the decoration query's schema; `.max(...)` must cover at least the list page size; the list asks in batches of the first page size. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
685
711
  | <a id="list-row-decoration-query-empty"></a>`list/row-decoration-query-empty` | rowDecoration.query is a non-empty query QN. | Name the decoration query or remove rowDecoration. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
686
712
  | <a id="list-screen-id-unresolved"></a>`list/screen-id-unresolved` | listScreenId names a mounted screen. | Fix the listScreenId or mount the list screen. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
@@ -938,6 +964,7 @@
938
964
  | <a id="projection-detail-guidance-action-show-on-tabs"></a>`projection-detail/guidance-action-show-on-tabs` | Banner and steps actions set no showOnTabs. | Remove showOnTabs. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
939
965
  | <a id="projection-detail-guidance-field-empty"></a>`projection-detail/guidance-field-empty` | The field names of breadcrumb, summary, banner, steps and progress are non-empty strings. | Name a query output field or remove the block. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
940
966
  | <a id="projection-detail-header-with-record-title-field"></a>`projection-detail/header-with-record-title-field` | A projectionDetail with a header sets no recordTitleField. | Drop recordTitleField; header.title names the record. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
967
+ | <a id="projection-detail-initial-tab-invalid"></a>`projection-detail/initial-tab-invalid` | initialTab needs layout.mode tabs and each rule names an existing section id; footerHint needs footerActions. | Use tabs mode and section ids from the layout for initialTab, or declare footerActions next to footerHint. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
941
968
  | <a id="projection-detail-metric-label-missing"></a>`projection-detail/metric-label-missing` | Every metric has an i18n label key. | Set label on the metric. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
942
969
  | <a id="projection-detail-metric-navigate-tab-unknown"></a>`projection-detail/metric-navigate-tab-unknown` | A metric navigate.tab names a section id of the screen. | Navigate to an existing section id or remove navigate.tab. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
943
970
  | <a id="projection-detail-progress-beside-steps-without-steps"></a>`projection-detail/progress-beside-steps-without-steps` | progress.placement "beside-steps" needs a steps block to sit next to. | Add steps to the projectionDetail or remove progress.placement. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
@@ -1075,6 +1102,7 @@
1075
1102
  | <a id="screen-fallback-unknown-reason"></a>`screen/fallback-unknown-reason` | Fallback map keys are known fallback reasons. | Use only the documented fallback reasons. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1076
1103
  | <a id="screen-fallback-without-visible-when"></a>`screen/fallback-without-visible-when` | A screen with a fallback also declares visibleWhen. | Add visibleWhen or remove fallback. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1077
1104
  | <a id="screen-filter-in-needs-array"></a>`screen/filter-in-needs-array` | A filter with op in has an array value. | Pass an array as filter.value. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
1105
+ | <a id="screen-footer-action-conflict"></a>`screen/footer-action-conflict` | A footerActions id is neither the primaryAction nor in inlineActions. | Keep each action in one place: header (primaryAction), inline row or pinned footer. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1078
1106
  | <a id="screen-header-action-row-click"></a>`screen/header-action-row-click` | Record header actions do not set rowClick, because a record screen has no row. | Remove rowClick. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
1079
1107
  | <a id="screen-id-duplicate"></a>`screen/id-duplicate` | Screen ids are unique per feature. | Rename one of the screens. | `packages/framework/src/engine/boot-validator/definition-ui-extensions-rules.ts` |
1080
1108
  | <a id="screen-id-not-kebab"></a>`screen/id-not-kebab` | Screen ids are kebab-case. | Rename the screen id to lowercase letters, digits and dashes. | `packages/framework/src/engine/boot-validator/definition-ui-extensions-rules.ts` |
@@ -1093,12 +1121,14 @@
1093
1121
  | <a id="screen-prefill-param-not-rendered"></a>`screen/prefill-param-not-rendered` | Prefill params only name fields the target form renders in its layout. | Add the field to the target layout or remove the param. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1094
1122
  | <a id="screen-prefill-param-sensitive-field"></a>`screen/prefill-param-sensitive-field` | Prefill params never name sensitive or password fields of the target form. | Remove the param or prefill a non-sensitive field. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1095
1123
  | <a id="screen-prefill-param-unknown-field"></a>`screen/prefill-param-unknown-field` | Prefill params only name fields the target form declares. | Name a field the target form declares, or remove the param. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1096
- | <a id="screen-primary-action-unknown"></a>`screen/primary-action-unknown` | primaryAction and inlineActions name a declared action id or the default edit. | Use a declared action id, or "edit" when the screen sets detailFor. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1124
+ | <a id="screen-primary-action-unknown"></a>`screen/primary-action-unknown` | primaryAction, inlineActions and footerActions name a declared action id or the default edit. | Use a declared action id, or "edit" when the screen sets detailFor. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1097
1125
  | <a id="screen-query-empty"></a>`screen/query-empty` | A screen or section query is a non-empty string. | Set query to a registered query name. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
1098
1126
  | <a id="screen-redirect-id-from-empty"></a>`screen/redirect-id-from-empty` | A redirect object's idFrom is a non-empty string. | Name the success-payload field carrying the navigation id, or use the plain string redirect. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1099
1127
  | <a id="screen-redirect-id-from-on-idless-target"></a>`screen/redirect-id-from-on-idless-target` | A redirect idFrom only targets entityEdit or projectionDetail screens. | Use the plain string redirect form. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1100
1128
  | <a id="screen-redirect-id-from-whitespace"></a>`screen/redirect-id-from-whitespace` | A redirect idFrom has no leading or trailing whitespace. | Remove the whitespace from idFrom. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1101
1129
  | <a id="screen-redirect-on-list-row-action"></a>`screen/redirect-on-list-row-action` | List and related-list row actions do not set redirect. | Remove redirect; it is only honored on record actions. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1130
+ | <a id="screen-redirect-search-params-empty"></a>`screen/redirect-search-params-empty` | A redirect searchParams entry has a non-empty param name and payload field. | Map each search param name to a success-payload field. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1131
+ | <a id="screen-redirect-search-params-only-action-form"></a>`screen/redirect-search-params-only-action-form` | A redirect searchParams is only set on actionForm redirects. | Remove searchParams; other screen kinds do not read it. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1102
1132
  | <a id="screen-renderer-function"></a>`screen/renderer-function` | Field and column renderers are FormatSpecs, not functions. | Use a FormatSpec ({ format: "..." }). | `packages/framework/src/engine/boot-validator/screens-rules.ts` |
1103
1133
  | <a id="screen-row-click-at-most-one"></a>`screen/row-click-at-most-one` | At most one row-body click target (rowClick) is declared per list. | Mark at most one rowAction with rowClick: true. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1104
1134
  | <a id="screen-short-id-collision"></a>`screen/short-id-collision` | A screen short id is registered by at most one feature. | Give each screen a distinct id. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
@@ -34,6 +34,10 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
34
34
  entries (`{ label, from }`). The handler wraps its schema with
35
35
  `withFormDerivations(schema, screen)` (`src/handlers/invoice-receive.write.ts`),
36
36
  so totals sent by the client are replaced on the server.
37
+ - **Redirect with search params**: after submit, `invoice-receive` redirects to
38
+ `invoice-list` with `searchParams: { "invoice-list.q": "invoiceNumber" }`, so the list opens
39
+ with the number the handler returns in its search box. The receive handler stores nothing in
40
+ this recipe; the search finds invoices saved through `invoice-edit` with that number.
37
41
 
38
42
  ## When to reach for it
39
43
 
@@ -410,6 +414,7 @@ describe("invoice line items with select/reference/derived/totals metadata", ()
410
414
 
411
415
  describe("invoice receive form derives its totals on the server", () => {
412
416
  type ReceiveTotals = {
417
+ invoiceNumber: string;
413
418
  netTotal: { amount: number; currency: string };
414
419
  vatTotal: { amount: number; currency: string };
415
420
  grossTotal: { amount: number; currency: string };
@@ -432,7 +437,10 @@ describe("invoice receive form derives its totals on the server", () => {
432
437
  },
433
438
  admin,
434
439
  );
440
+ // The screen's redirect searchParams read `invoiceNumber` from this payload; the
441
+ // stack booted, so boot validation accepted the redirect to the invoice list.
435
442
  expect(totals).toEqual({
443
+ invoiceNumber: "RE-2026-0042",
436
444
  netTotal: eur(30.05),
437
445
  vatTotal: eur(3.31),
438
446
  grossTotal: eur(33.36),
@@ -534,6 +542,12 @@ export const invoiceEntity = createEntity({
534
542
  table: "read_sample_invoices",
535
543
  fields: {
536
544
  customer: createTextField({ personal: { of: "id" }, find: "none", required: true }),
545
+ // Business data, so the list can search it: invoice-receive redirects here by number.
546
+ invoiceNumber: createTextField({
547
+ personal: false,
548
+ reason: "is_business_data",
549
+ searchable: true,
550
+ }),
537
551
  lines: createEmbeddedListField(
538
552
  {
539
553
  product: { type: "reference", entity: "product", required: true },
@@ -638,10 +652,16 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
638
652
  type: "entityEdit",
639
653
  entity: "invoice",
640
654
  layout: {
641
- sections: [{ columns: 1, fields: ["customer", "lines"] }],
655
+ sections: [{ columns: 1, fields: ["invoiceNumber", "customer", "lines"] }],
642
656
  },
643
657
  });
644
658
 
659
+ r.screen({
660
+ id: "invoice-list",
661
+ type: "entityList",
662
+ entity: "invoice",
663
+ columns: ["invoiceNumber", "customer"],
664
+ });
645
665
  r.screen(invoiceReceiveScreen);
646
666
  });
647
667
  ```
@@ -755,6 +775,7 @@ export const invoiceReceive = defineWriteHandler({
755
775
  handler: async (event) => ({
756
776
  isSuccess: true,
757
777
  data: {
778
+ invoiceNumber: event.payload.invoiceNumber,
758
779
  netTotal: event.payload.netTotal,
759
780
  vatTotal: event.payload.vatTotal,
760
781
  grossTotal: event.payload.grossTotal,
@@ -798,6 +819,8 @@ export const invoiceReceiveScreen: ActionFormScreenDefinition = {
798
819
  id: "invoice-receive",
799
820
  type: "actionForm",
800
821
  handler: "contacts:write:invoice:receive",
822
+ // Lands on the invoice list with its search box filled from the result.
823
+ redirect: { screen: "invoice-list", searchParams: { "invoice-list.q": "invoiceNumber" } },
801
824
  fields: {
802
825
  supplier: createTextField({ required: true, personal: "tenant", find: "none" }),
803
826
  invoiceNumber: createTextField({
@@ -0,0 +1,129 @@
1
+ <!-- Generated by `bun run gen:agent-docs` from samples/recipes/handbook-knowledge. Do not edit. -->
2
+
3
+ # handbook-knowledge
4
+
5
+ The handbook-knowledge bundled feature: a fixed handbook JSON served to the AI assistant as list-pages and read-page query tools.
6
+
7
+ ## README
8
+
9
+ # Handbook knowledge
10
+
11
+ Serves the app's handbook to the AI assistant. `kumiko handbuch knowledge` exports
12
+ the pages per locale as JSON; the `handbook-knowledge` bundled feature mounts them
13
+ as two query tools, so the assistant can answer how-do-I questions from the real
14
+ handbook text.
15
+
16
+ ## What it shows
17
+
18
+ - **Feature** — `createHandbookKnowledgeFeature({ pages, access, publicPath })`.
19
+ No entity, no migration; `access` decides which roles see the tools.
20
+ - **list-pages** — catalog of id, kind, title and questions in the caller's language.
21
+ - **read-page** — one page body; the language falls back to the handbook's default
22
+ language, long pages are cut with a visible notice, unknown ids are `not_found`.
23
+ - **Test** — `setupTestStack` and HTTP with an `X-Locale` header.
24
+
25
+ ## Files
26
+
27
+ ```
28
+ src/feature.ts fixed handbook JSON and the feature
29
+ src/__tests__/feature.integration.test.ts list-pages, read-page, fallback, not found
30
+ ```
31
+
32
+ ## Source files
33
+
34
+ ### src/__tests__/feature.integration.test.ts
35
+
36
+ ```ts
37
+ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
38
+ import { createTestUser } from "@cosmicdrift/kumiko-framework/seeding";
39
+ import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
40
+ import { handbookKnowledgeFeature } from "../feature";
41
+
42
+ const LIST_PAGES = "handbook-knowledge:query:list-pages";
43
+ const READ_PAGE = "handbook-knowledge:query:read-page";
44
+
45
+ type ListResult = { locale: string; pages: { id: string; title: string }[] };
46
+ type ReadResult = { id: string; locale: string; bodyMd: string; publicPath?: string };
47
+
48
+ const user = createTestUser({ roles: ["User"] });
49
+ let stack: TestStack;
50
+
51
+ beforeAll(async () => {
52
+ stack = await setupTestStack({ features: [handbookKnowledgeFeature] });
53
+ });
54
+
55
+ afterAll(async () => {
56
+ await stack.cleanup();
57
+ });
58
+
59
+ async function queryIn<T>(type: string, payload: unknown, locale: string): Promise<T> {
60
+ const res = await stack.http.queryWithHeaders(type, payload, user, { "X-Locale": locale });
61
+ expect(res.status).toBe(200);
62
+ return ((await res.json()) as { data: T }).data;
63
+ }
64
+
65
+ describe("handbook-knowledge recipe", () => {
66
+ test("list-pages returns the catalog in the caller's language", async () => {
67
+ const de = await queryIn<ListResult>(LIST_PAGES, {}, "de");
68
+ expect(de.pages[0]).toMatchObject({ id: "prozess-add-tenant", title: "Mieter hinzufügen" });
69
+ });
70
+
71
+ test("read-page falls back to the default language and links the public handbook", async () => {
72
+ const page = await queryIn<ReadResult>(READ_PAGE, { id: "lease-detail" }, "de");
73
+ expect(page).toMatchObject({ locale: "en", publicPath: "/handbuch/lease-detail" });
74
+ expect(page.bodyMd).toContain("tenants, rent and documents");
75
+ });
76
+
77
+ test("read-page rejects an unknown id", async () => {
78
+ const error = await stack.http.queryErr(READ_PAGE, { id: "missing" }, user);
79
+ expect(error.code).toBe("not_found");
80
+ });
81
+ });
82
+ ```
83
+
84
+ ### src/feature.ts
85
+
86
+ ```ts
87
+ import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge";
88
+
89
+ // In an app this object is the output of `kumiko handbuch knowledge <config> --out <file>`.
90
+ const handbook = {
91
+ defaultLocale: "en",
92
+ locales: {
93
+ en: [
94
+ {
95
+ id: "prozess-add-tenant",
96
+ kind: "process" as const,
97
+ title: "Add a tenant",
98
+ questions: ["How do I add a tenant?"],
99
+ screens: [],
100
+ bodyMd: "Open the lease, choose Add tenant and confirm the change.",
101
+ },
102
+ {
103
+ id: "lease-detail",
104
+ kind: "screen" as const,
105
+ title: "Lease",
106
+ questions: [],
107
+ screens: [],
108
+ bodyMd: "The lease screen shows tenants, rent and documents.",
109
+ },
110
+ ],
111
+ de: [
112
+ {
113
+ id: "prozess-add-tenant",
114
+ kind: "process" as const,
115
+ title: "Mieter hinzufügen",
116
+ questions: ["Wie füge ich einen Mieter hinzu?"],
117
+ screens: [],
118
+ bodyMd: "Vertrag öffnen, Mieter hinzufügen wählen und die Änderung bestätigen.",
119
+ },
120
+ ],
121
+ },
122
+ };
123
+
124
+ export const handbookKnowledgeFeature = createHandbookKnowledgeFeature({
125
+ pages: handbook,
126
+ access: { roles: ["User"] },
127
+ publicPath: "/handbuch",
128
+ });
129
+ ```
@@ -0,0 +1,186 @@
1
+ <!-- Generated by `bun run gen:agent-docs` from samples/recipes/signature. Do not edit. -->
2
+
3
+ # signature
4
+
5
+ The signature bundled feature: a request for several signers, a signing link that is delivered by the app, and a completed PDF with a signature page.
6
+
7
+ ## README
8
+
9
+ # Signature
10
+
11
+ Several people sign one PDF of the tenant, in person on a display or through a link. The last
12
+ signature moves the request to `all-signed`; a job renders a signature page, appends it to the
13
+ unchanged original and completes the request.
14
+
15
+ ## What it shows
16
+
17
+ - **Feature** - `createSignatureFeature({ retention, linkSecret, renderHtmlToPdf, deliverLink, signaturePageUrl })`.
18
+ Needs `files` and `user-data-rights` (exports and erases signer data); the test mounts user-data-rights with its own dependencies.
19
+ - **deliverLink** - `issue-link` hands the signing link to the app (mail) and returns only
20
+ `{ signerId, linkSentAt }`: whoever may issue a link must not be able to sign with it.
21
+ - **renderHtmlToPdf** - injected; in an app it is the client of `@cosmicdrift/kumiko-renderer-puppeteer-client`.
22
+ - **Test** - `setupTestStack` and HTTP: request, issue-link, anonymous sign-by-link, sweep job, completed.
23
+
24
+ ## Files
25
+
26
+ ```
27
+ src/feature.ts the feature with a link outbox and a stand-in printer
28
+ src/__tests__/feature.integration.test.ts request to completed request over HTTP
29
+ ```
30
+
31
+ ## Source files
32
+
33
+ ### src/__tests__/feature.integration.test.ts
34
+
35
+ ```ts
36
+ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
37
+ import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
38
+ import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
39
+ import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
40
+ import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
41
+ import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
42
+ import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
43
+ import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
44
+ import { createSystemUser, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
45
+ import {
46
+ createFilesFeature,
47
+ createInMemoryFileProvider,
48
+ fileRefEntity,
49
+ fileRefsTable,
50
+ } from "@cosmicdrift/kumiko-framework/files";
51
+ import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
52
+ import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
53
+ import { PDFDocument } from "pdf-lib";
54
+ import { deliveredLinks, signatureFeature } from "../feature";
55
+
56
+ const TENANT = testTenantId(1);
57
+ const admin = createTestUser({ roles: ["TenantAdmin"], tenantId: TENANT });
58
+ const SIGNATURE_PNG =
59
+ "iVBORw0KGgoAAAANSUhEUgAAACgAAAAQCAYAAABk1z2tAAAANklEQVR4nGNgYGD4j4QHJUB24KB0LC4HDjqHgsCoY0dDdTS9jmas0SJrtGwdrbVGq9f/yCUBAOaodYsn7bfwAAAAAElFTkSuQmCC";
60
+
61
+ const provider = createInMemoryFileProvider();
62
+ let stack: TestStack;
63
+
64
+ beforeAll(async () => {
65
+ stack = await setupTestStack({
66
+ features: [
67
+ createUserFeature(),
68
+ createAuthFoundationFeature(),
69
+ createSessionsFeature(),
70
+ createDataRetentionFeature(),
71
+ createComplianceProfilesFeature(),
72
+ createUserDataRightsFeature(),
73
+ createFilesFeature(),
74
+ signatureFeature,
75
+ ],
76
+ files: { storageProvider: provider },
77
+ jobs: { consumerLane: "worker", getActiveTenantIds: async () => [TENANT] },
78
+ anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
79
+ });
80
+ });
81
+
82
+ afterAll(async () => {
83
+ await stack.cleanup();
84
+ });
85
+
86
+ async function seedContract(): Promise<string> {
87
+ const bytes = await (async () => {
88
+ const pdf = await PDFDocument.create();
89
+ pdf.addPage();
90
+ return pdf.save();
91
+ })();
92
+ const storageKey = `${TENANT}/contract.pdf`;
93
+ await provider.write(storageKey, bytes, "application/pdf");
94
+ const db = createTenantDb({
95
+ db: stack.db,
96
+ tenantId: TENANT,
97
+ mode: "system",
98
+ reason: "recipe seeds the document the request refers to",
99
+ });
100
+ const created = await createEventStoreExecutor(fileRefsTable, fileRefEntity, {
101
+ entityName: "fileRef",
102
+ }).create(
103
+ { storageKey, fileName: "contract.pdf", mimeType: "application/pdf", size: bytes.length },
104
+ createSystemUser(TENANT),
105
+ db,
106
+ );
107
+ if (!created.isSuccess) throw new Error(created.error.message);
108
+ return String(created.data.id);
109
+ }
110
+
111
+ describe("signature recipe", () => {
112
+ test("a link is delivered, never returned, and the last signature completes the request", async () => {
113
+ const { requestId, signerIds } = await stack.http.writeOk<{
114
+ requestId: string;
115
+ signerIds: string[];
116
+ }>(
117
+ "signature:write:request",
118
+ {
119
+ documentFileId: await seedContract(),
120
+ title: "Rental agreement",
121
+ subjectType: "lease",
122
+ subjectId: "lease-1",
123
+ signers: [{ name: "Ada", email: "ada@example.test" }],
124
+ },
125
+ admin,
126
+ );
127
+ const signerId = signerIds[0] as string;
128
+
129
+ const issued = await stack.http.writeOk<Record<string, unknown>>(
130
+ "signature:write:issue-link",
131
+ { signerId },
132
+ admin,
133
+ );
134
+ expect(Object.keys(issued).sort()).toEqual(["linkSentAt", "signerId"]);
135
+
136
+ const url = deliveredLinks.get(signerId) ?? "";
137
+ expect(url.startsWith("https://app.example/sign#")).toBe(true);
138
+ const signed = await stack.http.raw("POST", "/api/write", {
139
+ type: "signature:write:sign-by-link",
140
+ payload: { token: url.slice(url.indexOf("#") + 1), imagePngBase64: SIGNATURE_PNG },
141
+ });
142
+ expect(signed.status).toBe(200);
143
+
144
+ await stack.jobRunner?.dispatch("signature:job:sweep", { tenantId: TENANT });
145
+ await stack.drainJobs();
146
+
147
+ const request = await stack.http.queryOk<{ status: string }>(
148
+ "signature:query:signature-request:detail",
149
+ { id: requestId },
150
+ admin,
151
+ );
152
+ expect(request.status).toBe("completed");
153
+ });
154
+ });
155
+ ```
156
+
157
+ ### src/feature.ts
158
+
159
+ ```ts
160
+ import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature";
161
+ import { PDFDocument } from "pdf-lib";
162
+
163
+ // In an app `deliverLink` sends a mail to the signer. The recipe keeps the links in a map so the
164
+ // test can open them: the link is never part of a handler result.
165
+ export const deliveredLinks = new Map<string, string>();
166
+
167
+ // In an app this is `renderHtmlToPdf` from @cosmicdrift/kumiko-renderer-puppeteer-client, which
168
+ // needs the print service; the recipe prints a blank page instead.
169
+ async function printSignaturePage(): Promise<Uint8Array> {
170
+ const pdf = await PDFDocument.create();
171
+ pdf.addPage();
172
+ return pdf.save();
173
+ }
174
+
175
+ export const SIGNATURE_LINK_SECRET = "signature-recipe-link-secret-0123456789";
176
+
177
+ export const signatureFeature = createSignatureFeature({
178
+ retention: { keepFor: "10y" },
179
+ linkSecret: SIGNATURE_LINK_SECRET,
180
+ renderHtmlToPdf: printSignaturePage,
181
+ signaturePageUrl: "https://app.example/sign",
182
+ deliverLink: async (_ctx, { signerId, url }) => {
183
+ deliveredLinks.set(signerId, url);
184
+ },
185
+ });
186
+ ```
@@ -651,6 +651,7 @@ describe("writeform-section sample — registration", () => {
651
651
  editSection === undefined ||
652
652
  editSection.kind === "extension" ||
653
653
  editSection.kind === "relatedList" ||
654
+ editSection.kind === "stepList" ||
654
655
  detailSection?.kind !== "writeForm"
655
656
  ) {
656
657
  throw new Error("expected an entityEdit fields section and a writeForm section");
@@ -42,6 +42,7 @@
42
42
  | `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
43
43
  | `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.services.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
44
44
  | `golden-path` | The smallest complete feature: entity, write handler, event, projection, screen and an integration test. | `examples/golden-path.md` |
45
+ | `handbook-knowledge` | The handbook-knowledge bundled feature: a fixed handbook JSON served to the AI assistant as list-pages and read-page query tools. | `examples/handbook-knowledge.md` |
45
46
  | `helpdesk` | Public contact form backend: the helpdesk bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client. | `examples/helpdesk.md` |
46
47
  | `host-routing` | createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server. | `examples/host-routing.md` |
47
48
  | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
@@ -74,6 +75,7 @@
74
75
  | `security-baseline` | composeSecurityStack(): sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing. | `examples/security-baseline.md` |
75
76
  | `seed-migration` | ES-Operations seed-migrations — file-based diff-and-apply für Aggregate-Updates die idempotent-Seeder nicht erfassen. | `examples/seed-migration.md` |
76
77
  | `session-revocation` | createSessionCallbacks + sessionChecker — server-side session revocation via JWT jti. | `examples/session-revocation.md` |
78
+ | `signature` | The signature bundled feature: a request for several signers, a signing link that is delivered by the app, and a completed PDF with a signature page. | `examples/signature.md` |
77
79
  | `state-machine` | Enforced entity state transitions. No more illegal state changes. | `examples/state-machine.md` |
78
80
  | `tags-basic` | Tag and group any entity without changing it — host-agnostic, event-sourced. | `examples/tags-basic.md` |
79
81
  | `tenant-inactivity` | tenant-inactivity: warn abandoned free accounts, then file the regular tenant-lifecycle deletion request; tier-based exemption and a keep-account link. | `examples/tenant-inactivity.md` |
@@ -90,6 +90,8 @@ One entry per feature a package ships: purpose, import of its factory, required
90
90
  `import { createFormDraftFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft"`
91
91
  - `form-draft-user-data`: GDPR (Art.
92
92
  `import { createFormDraftUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft-user-data"`; requires `user-data-rights`
93
+ - `handbook-knowledge`: 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.
94
+ `import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge"`
93
95
  - `helpdesk`: 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.
94
96
  `import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk"`; requires `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
95
97
  - `host-routing`: Host- and path-based tenant routing: an authoritative tenant resolver from the subdomain (tenantBy host), a tenant existence check against enabled, active tenants, and the tenant-key query behind createHostDispatch, which picks the HTML file, CSP, locale redirect or 404 per host for runProdApp's hostDispatch.
@@ -144,6 +146,8 @@ One entry per feature a package ships: purpose, import of its factory, required
144
146
  `import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo"`; requires `config`
145
147
  - `sessions`: Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`.
146
148
  `import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions"`; requires `user`, `auth-foundation`
149
+ - `signature`: Signature requests: a signed-in user asks several people to sign one PDF of the tenant.
150
+ `import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature"`; requires `files`, `user-data-rights`
147
151
  - `step-dispatcher`: Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits.
148
152
  `import { createStepDispatcherFeature } from "@cosmicdrift/kumiko-bundled-features/step-dispatcher"`; requires `secrets`
149
153
  - `subscription-mollie`: Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case.