@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

package/dist/schema-cli/validate-command.js

@@ -4,6 +4,7 @@ import { assertRowLevelSecurityTableState, createDbConnection, generateMigration
 import { isLiveFrameworkTable } from "../db/known-table-names.js";
 import { readMigrationSqlTexts } from "../db/migrate-runner.js";
 import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../db/replay-migration-sql.js";
+import { BootValidationError } from "../engine/boot-validator/boot-rule.js";
 import { validateBoot } from "../engine/boot-validator.js";
 import { describeThrown, loadPreviousSnapshot, loadSchemaModOrReport, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
 import { featureDefinitionsOf, parseValidateBootOptions, withFileStoragePresence, } from "./validate-boot-input.js";
@@ -35,6 +36,16 @@ function checkSchemaDrift(ctx, schemaMod, prevSnapshot) {
     out.err("    Fix: `kumiko-schema generate <name>`, then commit the migration.");
     return false;
 }
+function unclassifiedViolation(check, e) {
+    return { ruleId: `unclassified/${check}`, check, message: describeThrown(e) };
+}
+function reportBootViolations(out, violations) {
+    for (const v of violations) {
+        out.err(`  ✗ boot [${v.ruleId}] ${v.message}`);
+        if (v.fix !== undefined)
+            out.err(`    Fix: ${v.fix}`);
+    }
+}
 // 2. Boot validity — needs the composed feature set.
 function checkBootValidity(out, schemaMod) {
     let bootFeatures;
@@ -43,11 +54,11 @@ function checkBootValidity(out, schemaMod) {
     }
     catch (e) {
         out.err(`  ✗ boot: ${describeThrown(e)}`);
-        return false;
+        return { ok: false, violations: [unclassifiedViolation("featureDefinitionsOf", e)] };
     }
     if (bootFeatures === undefined) {
         out.log("  · boot: skipped — add `export const FEATURES = composeFeatures(APP_FEATURES, { includeBundled: true })` to kumiko/schema.ts to enable validateBoot.");
-        return true;
+        return { ok: true, skipped: true, violations: [] };
     }
     try {
         validateBoot(bootFeatures, {
@@ -55,11 +66,15 @@ function checkBootValidity(out, schemaMod) {
             env: withFileStoragePresence(process.env),
         });
         out.log("  ✓ boot: feature configuration is valid");
-        return true;
+        return { ok: true, violations: [] };
     }
     catch (e) {
+        if (e instanceof BootValidationError) {
+            reportBootViolations(out, e.violations);
+            return { ok: false, violations: e.violations };
+        }
         out.err(`  ✗ boot: ${describeThrown(e)}`);
-        return false;
+        return { ok: false, violations: [unclassifiedViolation("validateBoot", e)] };
     }
 }
 function declaredTablesOf(schemaMod) {
@@ -150,7 +165,8 @@ function checkMigrationContentDrift(ctx, prevSnapshot) {
 //      added/changed but never generated → missing table → prod 500)
 //   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
 //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES;
-//      honours its optional VALIDATE_BOOT_OPTIONS export.
+//      honours its optional VALIDATE_BOOT_OPTIONS export. `--json` prints
+//      this result as one JSON document on stdout.
 //   3. migration-content drift: replay every committed *.sql file and
 //      diff the result against .snapshot.json — catches a migration
 //      file whose SQL body doesn't match what its own snapshot entry
@@ -161,14 +177,32 @@ function checkMigrationContentDrift(ctx, prevSnapshot) {
 //   4. live row-level security (only with DATABASE_URL): the boot's
 //      table-state check against the real database (not the role: that is a boot-time property).
 // The DB-level gate (assertKumikoSchemaCurrent) stays at boot/deploy.
+function printBootJson(ctx, boot) {
+    const { ok, skipped, violations } = boot;
+    ctx.out.log(JSON.stringify({ boot: { ok, ...(skipped ? { skipped } : {}), violations } }));
+}
 export async function runValidateCommand(ctx) {
-    const schemaMod = await loadSchemaModOrReport(ctx);
-    if (schemaMod === undefined)
+    const jsonMode = ctx.argv.includes("--json");
+    // stdout carries exactly one JSON document in --json mode.
+    const out = jsonMode ? { log: ctx.out.err, err: ctx.out.err } : ctx.out;
+    const humanCtx = { ...ctx, out };
+    const schemaMod = await loadSchemaModOrReport(humanCtx);
+    if (schemaMod === undefined) {
+        if (jsonMode) {
+            const message = "kumiko/schema.ts could not be loaded";
+            printBootJson(ctx, {
+                ok: false,
+                violations: [{ ruleId: "unclassified/loadSchemaMod", check: "loadSchemaMod", message }],
+            });
+        }
         return 1;
+    }
     const prevSnapshot = loadPreviousSnapshot(join(ctx.migrationsDir, SNAPSHOT_FILENAME));
-    const schemaOk = checkSchemaDrift(ctx, schemaMod, prevSnapshot);
-    const bootOk = checkBootValidity(ctx.out, schemaMod);
-    const migrationsOk = checkMigrationContentDrift(ctx, prevSnapshot);
-    const rowLevelSecurityOk = await checkLiveRowLevelSecurity(ctx.out, schemaMod);
-    return schemaOk && bootOk && migrationsOk && rowLevelSecurityOk ? 0 : 1;
+    const schemaOk = checkSchemaDrift(humanCtx, schemaMod, prevSnapshot);
+    const boot = checkBootValidity(out, schemaMod);
+    const migrationsOk = checkMigrationContentDrift(humanCtx, prevSnapshot);
+    const rowLevelSecurityOk = await checkLiveRowLevelSecurity(out, schemaMod);
+    if (jsonMode)
+        printBootJson(ctx, boot);
+    return schemaOk && boot.ok && migrationsOk && rowLevelSecurityOk ? 0 : 1;
 }

package/dist/schema-cli.js

@@ -28,7 +28,7 @@ function printSchemaCliUsage(out) {
     out.log("");
     out.log("  Subcommands:");
     out.log("    generate <name>   Write a new migration from the EntityTableMeta diff");
-    out.log("    validate          Static CI gate (no DB): schema drift + validateBoot");
+    out.log("    validate [--json] Static CI gate (no DB): schema drift + validateBoot");
     out.log("    apply             Apply pending checked-in SQL files");
     out.log("    baseline          Mark checked-in migrations as applied (no SQL run)");
     out.log("    status            List applied vs pending");

package/dist/ui-types/index.d.ts

@@ -1,6 +1,7 @@
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export type { DerivedCellRoundingTarget } from "../engine/embedded-derived.ts";
-export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.ts";
+export { computeDerivedCellValue, roundDerivedCellValue, withDerivedCells, } from "../engine/embedded-derived.ts";
+export { findMissingConditionalRequirements, isFieldRequired, isFieldVisible, isMissingRequiredValue, } from "../engine/field-state.ts";
 export type { FormDerivationScreen } from "../engine/form-derivations.ts";
 export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperand, } from "../engine/form-derivations.ts";
 export type { ParsedRefTarget } from "../engine/parse-ref-target.ts";

package/dist/ui-types/index.js

@@ -20,7 +20,8 @@
 // When adding a symbol here, verify it's either a type or a pure
 // helper with no cross-module side-effects.
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
-export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.js";
+export { computeDerivedCellValue, roundDerivedCellValue, withDerivedCells, } from "../engine/embedded-derived.js";
+export { findMissingConditionalRequirements, isFieldRequired, isFieldVisible, isMissingRequiredValue, } from "../engine/field-state.js";
 export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperand, } from "../engine/form-derivations.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export { ACTION_FORM_PSEUDO_ENTITY, availableSelectOptions, evalFieldCondition, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.398.0",
+  "version": "0.400.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.398.0",
+    "@cosmicdrift/kumiko-types": "0.400.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.398.0",
+    "@cosmicdrift/kumiko-testing": "0.400.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,71 @@
 [
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Boot validation reports all violations at once",
+    "detail": "validateBoot runs its checks in phases and collects the violations of each phase into one BootValidationError with a `violations` list (ruleId, check, feature, message). Structural violations (duplicate API names, screen short-id collisions, unresolved query references, circular dependencies, extension usages, API exposure, reference fields, parent refs) abort before the per-feature and app-wide checks, which would only echo them. The error message starts with `Boot validation failed: N violation(s)` followed by one line per violation, each keeping its original text. A feature whose action or field wiring is invalid skips its screen check. `kumiko-schema validate` prints one ✗ line per violation and takes `--json`, which prints a single JSON document on stdout and moves the human lines to stderr."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Slimmer checklist cards and locale numbers in embedded lists",
+    "detail": "On narrow screens an embedded list with an `inRange` derived cell no longer shows the min and max sub-fields as their own rows. The card shows them as a hint under the measured value (\"Limit 0.05 to 0.2\", \"At least …\", \"At most …\"; new keys `kumiko.field.embedded-list.limit-range`, `limit-min`, `limit-max`). The result badge sits next to the measured value without a label. The new `embeddedList.cardHiddenCells` on an entityEdit field hides sub-fields that only steer a row (such as the kind of a checkpoint) on phone cards; boot rejects names that are not sub-fields. The desktop table is unchanged. Number and decimal cells now use the locale text input (`NumberInput`) instead of a native `type=\"number\"`, so input and read-only cells share one locale format (\"0,31\" in de, \"0.31\" in en). Tests that located these cells by role `spinbutton` must use `textbox`."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "SQL derived fields, query-gated relatedList tabs, count badge",
+    "detail": "A derived field with `sql` (coalesce over fields, or a related-table count, countDistinct or first with optional label and conditions incl. activeOn/today/now) is computed inside the list SELECT and may set `sortable: true`, also as entityList defaultSort; JS `derive` fields stay display-only and read the SQL values. Related rows and measured fields respect the viewer's read access, a gated value is NULL. GET /api/schema removes relatedList sections (tabs, entityEdit sections, expandableRow) whose query the caller's roles cannot run, and metrics linking to a removed tab lose their navigate. `count: true` on a relatedList tab shows the tab badge from the section's own query total. A metric only becomes clickable when its entityId target resolves, and groupBy labels now also resolve for entities with a backingTable. `valueType: \"money\"` is allowed for a SQL derived `related` + `first` on a money field: amount and currency are read together and the row carries the stored money shape (no key when unset), sorting is by minor units. Ownership where-rules of a label target or related table are qualified with the subquery's own alias (a label of a row the viewer cannot read no longer leaks when the target is the outer entity), the related entity and label target must also be readable through a query handler of the viewer's roles, backingTable entities are read from their real table (also for reference labels, reference search and label sort, which returned a 500 before), an entity may derive from itself, and a sortable related derived field needs an index on the join column."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Entity readGate and the documents feature",
+    "detail": "`createEntity({ readGate: { anyLink, fileOwner, linkExemptRoles } })` hides a row unless the viewer can read at least one linked host (join rows with a parentRef) and the owner of the referenced file; it is applied in list, detail, eager-load and relation reads, fail-closed without the registry, and the framework system user passes. Hand-written list/detail handlers for a gated entity are rejected at boot, live signals for gated entities stay anonymous. `ParentVisibilityOption` gains `canReadEntity` and `resolveTable`. The new `documents` feature (`createDocumentsFeature({ categories, linkTargets, capture?, retention? })`) files documents with category, issue and expiry date, links them to records (link, unlink, for-record and per-type queries, expiry overview), lists them on the `documents:screen:list` projection list through `documents:query:overview` (an `expiry` state per row and an \"expiring\" filter that returns expired and soon-expiring documents), captures files saved into configured entity fields via a postSave hook, and offers an idempotent SYSTEM-only import for jobs. Updating or deleting a document needs write access to one of its linked hosts (admin roles and the system user are exempt). Reference search and sort on a readGate target now apply the gate, and `parentVisibilityFor` decides `canReadEntity` by the entity's own detail query, the same rule the file route uses, so a `liveEntities` query no longer widens what a file owner shows. A document cannot claim another user's unbound upload. A document never defaults its title to the file name."
+  },
+  {
+    "version": "0.400.0",
+    "type": "fix",
+    "title": "Hooks run for handlers that return response data; readOnly related lists",
+    "detail": "A write handler wrapped by `withResponseData` (for example `tenant:write:remove-member`) lost its lifecycle result, so postSave/postDelete hooks and projections were skipped. `WriteResult` now carries an optional `lifecycle` that the dispatcher and batch flush use and that is stripped from client responses. `EditRelatedListSection` gains `readOnly: true` for plain tables without an entity; the boot validator rejects it together with rowClick/rowActions and guard R2 skips it. The bin test helpers and `envWithoutGitOverrides` now also strip GIT_COMMON_DIR and the other git location variables."
+  },
+  {
+    "version": "0.400.0",
+    "type": "breaking",
+    "title": "An untouched money field is no longer submitted as 0",
+    "detail": "Forms seed a money field with its currency only and drop that currency-only value on submit, so a handler can tell a deliberately typed 0 from an untouched field. A currency-only value counts as missing for required checks, and the input shows empty instead of 0.00; config forms keep their plain-number contract.",
+    "migration": "A form that left a required money field untouched used to submit 0 and now fails validation; type the amount (also in e2e and DOM tests) or give the field a value through `load` or the record. Handlers that read an absent optional money field as 0 must default it themselves."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "documents entities are filed-document and filed-document-link; safe import; split access",
+    "detail": "The documents feature registers its entities as `filed-document` (table `read_filed_documents`) and `filed-document-link` (table `read_filed_document_links`), so an app that has its own `document` entity keeps its events and tables; handler and query names follow (`documents:write:filed-document:create`, `documents:query:filed-document:list`, `documents:query:filed-document-link:list`), and so do the field label keys `documents:entity:filed-document:field:*`. `documents:write:import` now fails with a conflict (`documents.errors.import-id-taken`) and links nothing when the id is already used by a stream that is not a document; a repeat import of the same document, deleted or not, still changes nothing; the check reads the stream, so a row-level `readAccess` cannot turn a retry into a refusal. With `readAccess` set, the system user keeps reading every document, so capture and import still find the ones the rule hides. An imported document's createdAt is the time of the import, because the event store does not backdate events; issuedAt carries the business date. `createDocumentsFeature({ access })` takes either one rule for everything, as before, or `{ read, write, delete }` (type `DocumentsAccess`): read covers the lists, detail, for-record, the overviews and the list screen, write covers create, update, link and unlink; a missing read or write keeps the TenantAdmin and TenantMember default and a missing delete follows write. The readGate on the document is unchanged."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Embedded list as inspection checklist",
+    "detail": "Every entity field and every embedded sub-field takes `visibleWhen` and `requiredWhen` (FieldCondition). The executor enforces `requiredWhen` on create and update; it returns `validation_error` with paths like `checkpoints.0.finding`, and on update it only checks fields whose value or condition field changed. A field is required only while it is visible, and hidden values are kept. Embedded sub-fields can be `images` (with `capture`) or `files` (`maxSize`, `accept`, `maxCount`). Uploads send `subField` next to `fieldName`, and `file_refs.fieldName` stays the embedded field, so binding, tenant check, disposal, read access, GDPR forget and retention work as for top-level file fields. The new derived op `inRange` (`from: [value, min, max]`, `inside`, `outside`) writes into a select sub-field. Any derived cell can carry a row-level `when`, and server and client compute through the same `withDerivedCells`. Select sub-fields take `optionTones`; segments show the tone of the selected option, and narrow screens render cards with 44px controls and the read-only label as the card title. Boot validates the condition fields and rejects `required: true` combined with `visibleWhen`/`requiredWhen`. Saving now enforces `access.write` on embedded sub-fields per row (`ownership_denied`, path `field.subField`); before, only the read side honored sub-field access. Saving also checks each newly placed file id against the `accept`/`maxSize` of the sub-field it lands in (`file_violates_bind_target`). Boot also rejects a numeric derived op whose target is not numeric, which can break an app that derived into a text or select cell. Recipe: `samples/recipes/inspection-checklist`."
+  },
+  {
+    "version": "0.400.0",
+    "type": "fix",
+    "title": "count badge works with strict query schemas",
+    "detail": "The boot check for a relatedList with `count: true` treated every Zod object with a catchall as having open keys and skipped the `limit` and `totalCount` lookup, so a query declared with `.strict()` (catchall `never`) failed boot although it accepts both keys. Only a catchall other than `never` now counts as open; `.loose()` and `.catchall()` schemas still fail the check."
+  },
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Agent docs ship an API reference and a compact feature index",
+    "detail": "`packages/framework/agents/` now contains `api.md` with one file per app-facing entry point (engine, errors, ui-types, db, event-store, seeding, renderer/web, testing/stack, testing/helpers, dev-server/testing) plus `api/types.md` for the types they reference. Signatures are one line each, option types are property lists with the first doc sentence, and `@internal` declarations are left out. `features-index.md` lists every bundled feature with one sentence, the import of its factory, its required features, config keys without a default and secrets. `AGENTS.md` points agents at the index first and at `api.md` instead of `dist/*.d.ts`. Both files are generated by `bun run gen:agent-docs` and checked by the agent-docs-drift guard."
+  },
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Opt-in anonymous uploads per file field",
+    "detail": "Since the upload route rejects anonymous callers, `POST /api/files` answered 401 for every anonymous visitor. A file, image, files or images field with `anonymousUpload: true` now accepts a pending upload from an anonymous visitor (entityType and fieldName, no entityId, no actionForm); the app binds the file itself. Everything else stays 401 for anonymous callers."
+  },
   {
     "version": "0.398.0",
     "type": "fix",