@cosmicdrift/kumiko-framework 0.342.0 → 0.344.0

package/dist/stack/test-stack.d.ts

@@ -3,6 +3,7 @@ import type { AuthRoutesConfig } from "../api/auth-routes.js";
 import type { JwtHelper } from "../api/jwt.js";
 import { type SseBroker } from "../api/sse-broker.js";
 import type { AppContext, FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types/index.js";
+import type { ErrorDocsConfig } from "../errors/docs-url.js";
 import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import { type ObservabilityProvider } from "../observability/index.js";
@@ -159,6 +160,8 @@ export type TestStackOptions = {
     /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
      *  — see there. Default 0. */
     trustedProxyHops?: number;
+    /** Links the app's own error reasons to its own docs (`docsUrl` in error responses); framework reasons keep the framework docs link. Passed to buildServer's `ServerOptions.errorDocs`. */
+    errorDocs?: ErrorDocsConfig;
     /** Second stack on the Redis namespace of `owner`: own connection, same
      *  keyPrefix, so rate-limit buckets, locks, idempotency keys and the
      *  cache-sync channel are shared across both. The derived
@@ -172,5 +175,9 @@ export type TestStackOptions = {
      *  Implied by `sharedRedisWith`; set it on the owner stack too, or its writes
      *  never reach the borrower. Without it the stack uses a process-local bus. */
     cacheSync?: boolean;
+    /** "full" runs the prod-boot validateBoot over `features` (screens and ref
+     *  entities across features included). Use it with the app's complete feature
+     *  composition; the default only checks what is safe on a feature subset. */
+    validateBoot?: "full";
 };
 export declare function setupTestStack(options: TestStackOptions): Promise<TestStack>;

package/dist/stack/test-stack.js

@@ -1,5 +1,6 @@
 import { buildServer } from "../api/server.js";
 import { createSseBroker } from "../api/sse-broker.js";
+import { validateBoot, validateNavBootSubset } from "../engine/boot-validator/index.js";
 import { validateOwnershipBoot } from "../engine/boot-validator/ownership.js";
 import { createRegistry } from "../engine/registry.js";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store/index.js";
@@ -31,6 +32,10 @@ export async function setupTestStack(options) {
     // columns) and before the ephemeral DB/Redis exist, so a throw can't leak
     // a database that nothing will clean up.
     validateOwnershipBoot(options.features);
+    // Nav/workspace refs fail the prod boot too; the subset check tolerates refs into unmounted features.
+    validateNavBootSubset(options.features);
+    if (options.validateBoot === "full")
+        validateBoot(options.features);
     // Forward db-name/persistent-flag through to createTestDb. The
     // defaults (undefined dbName, persistent:false) keep the legacy
     // test contract: fresh kumiko_test_<random> DB per setup, dropped
@@ -280,6 +285,7 @@ export async function setupTestStack(options) {
             eventDedup,
             sseBroker,
             ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
+            ...(options.errorDocs && { errorDocs: options.errorDocs }),
             ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
             ...(options.metrics && { metrics: options.metrics }),
             // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.342.0",
+  "version": "0.344.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.342.0",
-    "@cosmicdrift/kumiko-types": "0.342.0",
+    "@cosmicdrift/kumiko-http": "0.344.0",
+    "@cosmicdrift/kumiko-types": "0.344.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.342.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.344.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,36 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "breaking",
+    "title": "App error reasons only carry a docsUrl when errorDocs covers them",
+    "detail": "`docsUrl` in error responses is now resolved at serialization by `resolveErrorDocsUrl`. Framework reasons (and errors without a reason) link to the framework docs as before. An app's own reasons no longer link to the framework docs, where no page exists for them: they get a `docsUrl` only if the new option `errorDocs: { baseUrl, reasons: string[] | \"all\" }` (on `runProdApp`, `buildServer`, `createKumikoServer`, `setupTestStack`) covers them.\nMigration: `KumikoError.docsUrl` (the getter) is removed; use `resolveErrorDocsUrl(err, errorDocs?)`. `ErrorResponseBody.docsUrl` is now optional. Apps whose clients read `docsUrl` for app reasons pass `errorDocs` or handle the missing field.",
+    "migration": "KumikoError.docsUrl (the getter) is removed; call resolveErrorDocsUrl(err, errorDocs?) instead. ErrorResponseBody.docsUrl is optional. Apps whose clients read docsUrl for app reasons pass errorDocs or handle the missing field."
+  },
+  {
+    "version": "0.343.0",
+    "type": "fix",
+    "title": "Executor writes outside the dispatcher no longer skip custom projections",
+    "detail": "Executor writes run custom projections\n`EventStoreExecutor` create, update, delete, forget and restore now run the custom projections registered for the written event, in the same savepoint as the write. The registry is bound to the `TenantDb` by the dispatcher and the job runner; a `TenantDb` built elsewhere skips custom projections. Projection runs are idempotent per event object, so the dispatcher's own pass after the handler does not run them twice.",
+    "migration": "Remove manual `runProjections` calls after executor writes in hooks or jobs together with the bump. A call is a no-op only when it passes the exact event object the executor returned; a spread or rebuilt event projects twice."
+  },
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "isFailedWriteResult is exported from the pipeline entry",
+    "detail": "`isFailedWriteResult` and `FailedWriteResult` are exported from the pipeline entry\nConsumers can narrow a `WriteResult` to its failure branch with `import { isFailedWriteResult } from \"@cosmicdrift/kumiko-framework/pipeline\"` instead of re-implementing the check."
+  },
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "retiredCookieDomains clears auth cookies left on a former cookieDomain",
+    "detail": "`AuthRoutesConfig.retiredCookieDomains` lists domains that used to carry the auth cookies. Login and logout also send delete headers for `kumiko_auth` and `kumiko_csrf` with `Domain=<entry>`, so a stale cookie from an earlier `cookieDomain` no longer shadows the new session after the value changes. Login sends these deletes before the new `Set-Cookie` headers. `createAuthRoutes` throws on an empty entry, on `;`, comma, whitespace, CR or LF, and on an entry equal to the current `cookieDomain`. Without the option nothing changes. Remove an entry once the session TTL has passed since the switch."
+  },
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "Test stacks validate nav references and can run the full boot validation",
+    "detail": "`setupTestStack` now validates nav, workspace and tree-action references on the mounted features, with the same error messages as the prod boot. References into features that are not mounted are skipped. The new option `validateBoot: \"full\"` runs the complete `validateBoot`, including the screen and ref-entity checks that span features; give apps one boot test with their prod feature composition and this option."
+  },
   {
     "version": "0.342.0",
     "type": "improvement",