@cosmicdrift/kumiko-framework 0.365.1 → 0.367.0

package/dist/pipeline/tenant-timezone-config-key.js

@@ -0,0 +1,6 @@
+// Framework/pipeline stays bundled-features-free, so this can't import the
+// `tenant` feature — the literal below IS the coupling to its `timezone`
+// config key. Renaming that key (or the "tenant" feature name) must update
+// this constant too; tenant-timezone-boot.integration.test.ts boots the real
+// createTenantFeature() and would catch a drift.
+export const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";

package/dist/testing/index.d.ts

@@ -13,6 +13,7 @@ export { describeFileProviderContract } from "./file-provider-contract.js";
 export { bridgeStub } from "./handler-context.js";
 export { getSetCookieRaw, getSetCookies, getSetCookieValue, type ParsedSetCookie, } from "./http-cookies.js";
 export { createLateBoundHolder, type LateBoundHolder } from "./late-bound.js";
+export { createManualClock, type ManualClock } from "./manual-clock.js";
 export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper.js";
 export { createMutableMasterKeyProvider, createTestEnvelopeCipher, createTestMasterKeyProvider, type MutableMasterKeyProvider, } from "./mutable-master-key-provider.js";
 export { createRecordingProvider, type RecordingProvider, } from "./observability-recorder.js";

package/dist/testing/index.js

@@ -21,6 +21,7 @@ export { describeFileProviderContract } from "./file-provider-contract.js";
 export { bridgeStub } from "./handler-context.js";
 export { getSetCookieRaw, getSetCookies, getSetCookieValue, } from "./http-cookies.js";
 export { createLateBoundHolder } from "./late-bound.js";
+export { createManualClock } from "./manual-clock.js";
 export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper.js";
 export { createMutableMasterKeyProvider, createTestEnvelopeCipher, createTestMasterKeyProvider, } from "./mutable-master-key-provider.js";
 export { createRecordingProvider, } from "./observability-recorder.js";

package/dist/testing/manual-clock.d.ts

@@ -0,0 +1,14 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { Clock } from "@cosmicdrift/kumiko-types/tz-context";
+type ClockStep = {
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+    readonly milliseconds?: number;
+};
+export type ManualClock = Clock & {
+    set(instant: Temporal.Instant): void;
+    advance(step: ClockStep): void;
+};
+export declare function createManualClock(start: Temporal.Instant): ManualClock;
+export {};

package/dist/testing/manual-clock.js

@@ -0,0 +1,12 @@
+export function createManualClock(start) {
+    let current = start;
+    return {
+        now: () => current,
+        set: (instant) => {
+            current = instant;
+        },
+        advance: (step) => {
+            current = current.add(step);
+        },
+    };
+}

package/dist/time/index.d.ts

@@ -3,4 +3,4 @@ export type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz.js";
 export { isValidIanaTimeZone } from "./iana.js";
 export { instantToLegacyDate, legacyDateToInstant } from "./legacy-date.js";
 export { ensureTemporalPolyfill, getTemporal } from "./polyfill.js";
-export { createTzContext, createTzContextAsync, type LocatedTimestampJson, type TzContext, type TzContextOptions, } from "./tz-context.js";
+export { type Clock, createTzContext, createTzContextAsync, type LocatedTimestampJson, type TzContext, type TzContextOptions, } from "./tz-context.js";

package/dist/time/tz-context.d.ts

@@ -1,5 +1,5 @@
 import type { TzContext, TzContextOptions } from "@cosmicdrift/kumiko-types/tz-context";
-export type { LocatedTimestampJson, TzContext, TzContextOptions, } from "@cosmicdrift/kumiko-types/tz-context";
+export type { Clock, LocatedTimestampJson, TzContext, TzContextOptions, } from "@cosmicdrift/kumiko-types/tz-context";
 /**
  * Factory: creates a TzContext for the current request.
  * Uses the kumiko-types Temporal module export (not globalThis.Temporal) so

package/dist/time/tz-context.js

@@ -19,6 +19,9 @@
 // live in @cosmicdrift/kumiko-types/tz-context — only the factories are here.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { ensureTemporalPolyfill } from "./polyfill.js";
+const SYSTEM_CLOCK = {
+    now: () => Temporal.Now.instant(), // @wrapper-known semantic-alias
+};
 /**
  * Factory: creates a TzContext for the current request.
  * Uses the kumiko-types Temporal module export (not globalThis.Temporal) so
@@ -28,14 +31,16 @@ export function createTzContext(options = {}) {
     const tenant = options.tenant ?? "UTC";
     const user = options.user ?? tenant;
     const geoTz = options.geoTz;
+    const clock = options.clock ?? SYSTEM_CLOCK;
+    const nowIn = (tz) => clock.now().toZonedDateTimeISO(tz);
     return {
         tenant,
         user,
-        now: () => Temporal.Now.instant(), // @wrapper-known semantic-alias
-        nowIn: (tz) => Temporal.Now.zonedDateTimeISO(tz), // @wrapper-known semantic-alias
-        today: (tz) => Temporal.Now.plainDateISO(tz), // @wrapper-known semantic-alias
+        now: () => clock.now(),
+        nowIn,
+        today: (tz) => nowIn(tz).toPlainDate(),
         todayRange: (tz) => {
-            const today = Temporal.Now.plainDateISO(tz);
+            const today = nowIn(tz).toPlainDate();
             const startZdt = today.toZonedDateTime({ timeZone: tz });
             const endZdt = today.add({ days: 1 }).toZonedDateTime({ timeZone: tz });
             return { start: startZdt.toInstant(), end: endZdt.toInstant() };

package/dist/upgrade-cli.js

@@ -297,6 +297,12 @@ export function manualEntryId(version, title) {
     const hash = createHash("sha256").update(title).digest("hex").slice(0, MANUAL_ID_HASH_LENGTH);
     return `${version}:${hash}`;
 }
+// Breaking entries that need hand work carry the id `kumiko-upgrade --resolve` takes.
+function manualIdOf(entry) {
+    return entry.type === "breaking" && needsManualMigration(entry)
+        ? manualEntryId(entry.version, entry.title)
+        : undefined;
+}
 function toMarkerManual(entry) {
     return {
         id: manualEntryId(entry.version, entry.title),
@@ -739,7 +745,11 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     }
     if (jsonMode) {
         const { pendingManual } = carryOf(markerRead);
-        out.log(JSON.stringify({ currentVersion, installedVersion, pending, pendingManual }, null, 2));
+        const pendingWithManualId = pending.map((entry) => {
+            const manualId = manualIdOf(entry);
+            return manualId === undefined ? entry : { ...entry, manualId };
+        });
+        out.log(JSON.stringify({ currentVersion, installedVersion, pending: pendingWithManualId, pendingManual }, null, 2));
         return 0;
     }
     const breaking = pending.filter((e) => e.type === "breaking");
@@ -759,7 +769,8 @@ export async function runUpgradeCli(argv, cwd, out, options) {
         out.log(`  ⚠ BREAKING (${breaking.length})`);
         out.log("");
         for (const e of breaking) {
-            out.log(`    ${e.version} · ${e.title}`);
+            const manualId = manualIdOf(e);
+            out.log(`    ${e.version} · ${e.title}${manualId === undefined ? "" : `  [${manualId}]`}`);
             if (verbose && e.detail) {
                 out.log(`      ${e.detail}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.365.1",
+  "version": "0.367.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>",
@@ -210,8 +210,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.365.1",
-    "@cosmicdrift/kumiko-types": "0.365.1",
+    "@cosmicdrift/kumiko-http": "0.367.0",
+    "@cosmicdrift/kumiko-types": "0.367.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,7 +227,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.365.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.367.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "Seed context finds template resources again",
+    "detail": "findTemplateResources in the seed context filtered on an is_deleted column that the template resource table does not have, so every seed that read template resources failed. The query now reads the live rows only."
+  },
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Seeds can store files and see why a write failed",
+    "detail": "ProdSeedFn deps now carry createFileRef(tenantId, input), which stores bytes as a fileRef with the same validation and storage layout as POST /files, without a helper write handler. A seed write that fails with internal_error now names the handler and the cause message instead of a bare \"internal error\". The seed dispatcher gets the app's dispatcherOptions (and the job runner in all-in-one mode), like the HTTP dispatcher. The \"ctx.files is unavailable\" message of createFileRefFromBytes names the real cause: the dispatcher context has no file-provider resolver."
+  },
+  {
+    "version": "0.366.0",
+    "type": "breaking",
+    "title": "One injectable Clock for ctx.tz in handlers and jobs",
+    "detail": "New type Clock and TzContextOptions.clock. AppContext.clock feeds ctx.tz.now() in handlers, and JobContext.tz gives jobs the same ctx.tz API (tenant timezone from tenant config, read once per job run, UTC fallback). The testing helper createManualClock(start) returns a clock with set and advance. The tenant-lifecycle job now reads time through ctx.tz.now().",
+    "migration": "Code that builds a JobContext literal itself (boot seeds, test doubles) adds `tz: createTzContext()`."
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "Handler input references work on nested fields and record keys",
+    "detail": "The references meta on handler input schemas is now found on fields inside arrays, nested objects and records, and on record keys. The new readHandlerFieldReferences and handlerFieldReferences return each hit with a path such as \"channels[].channelKey\" or \"labels{key}\" plus typed path segments. Boot validation checks nested references too and names the path in its error message. readHandlerFieldReference and handlerFieldReference behave as before."
+  },
+  {
+    "version": "0.366.0",
+    "type": "breaking",
+    "title": "Registrar methods take a single object, positional calls throw at registration",
+    "detail": "r.writeHandler, r.queryHandler, r.entity, r.requires and r.hook now take one object. The positional overloads are gone from the types and throw when the feature is defined, with a message that points at the codemod. The throw is removed in the first release after 2026-10-29.\n\nwriteHandler (queryHandler is the same shape):\n  before: r.writeHandler(\"order:archive\", schema, handler, { access });\n  after:  r.writeHandler({ name: \"order:archive\", schema, handler, access });\n\nhook (type picks the handler shape, target is a name, a list or { allOf }):\n  before: r.hook(\"postSave\", \"order\", handler, { escapeHatch });\n  after:  r.hook({ type: \"postSave\", target: \"order\", handler, escapeHatch });\n\nentity and requires:\n  before: r.entity(\"order\", definition, { table: ordersTable });  r.requires(\"auth\", \"tenant\");\n  after:  r.entity({ name: \"order\", ...definition, backingTable: ordersTable });  r.requires({ features: [\"auth\", \"tenant\"] });\n\nregisterEntityCrud is no longer exported from @cosmicdrift/kumiko-framework/engine; call r.crud(name, entity, options) instead. The entity option { table } is now backingTable on the r.entity object and lands in the feature's entityTables, not in its entities. HookDefinition and EntityObjectDefinition are exported from @cosmicdrift/kumiko-types. Hook definitions are checked per type: validation takes no escapeHatch, phase only exists on postSave and postDelete, and { allOf } is not accepted on preSave.",
+    "migration": "Run `bun kumiko-upgrade --apply`. It rewrites every positional r.writeHandler, r.queryHandler, r.entity, r.requires, r.hook and registerEntityCrud call to the object form. Calls it cannot resolve statically (a spread argument, a registrar that is not typed as FeatureRegistrar) are listed as manual work with file and line; rewrite those by hand.",
+    "codemod": "scripts/codemod/object-form.ts",
+    "manualAfterCodemod": true
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "The app schema no longer lists screens, navs and workspaces of features a tenant has switched off",
+    "detail": "A feature declared with r.toggleable() that is off for the caller's tenant (tier engine or feature toggles) used to stay in the nav while all its handlers answered 403 feature_disabled. GET /api/schema now drops its screens, navs, content collections and workspaces for that tenant, and every action, redirect, nav parent and workspace member that pointed at them is removed too. Entities and translations stay. The response is cached per role set and per set of disabled features, so tenants with the same set share one ETag. Without an effectiveFeatures resolver nothing changes."
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "selectMany supports column projection via SelectOptions.fields",
+    "detail": "SelectOptions gains fields, a list of entity field names. selectMany then selects only those columns instead of all of them. An empty list or a name that is not a column of the table throws."
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "kumiko-upgrade names each pending manual step by an id",
+    "detail": "Every pending manual step of kumiko-upgrade now has a stable id, derived from the release version and the step title. The text output shows it in brackets and the JSON output carries it as manualId, so a script or an agent can tell steps apart and record which ones it has done."
+  },
   {
     "version": "0.365.1",
     "type": "fix",

package/src/scripts/codemod/README.md

@@ -34,3 +34,26 @@ at — fix those by hand. The report also lists every field that newly
 gains `lookupable` (searchable-only fields resolving to `find: "fuzzy"`)
 — each of those needs a `_bidx` column migration, which this script does
 not write.
+
+## object-form.ts
+
+Rewrites the positional registrar calls `r.writeHandler(name, schema, handler, options)`,
+`r.queryHandler(…)`, `r.entity(name, definition, { table })`, `r.requires("a", "b")` and
+`r.hook(type, target, fn, options?)` to their object form, and
+`registerEntityCrud(r, name, entity, options?)` to `r.crud(name, entity, options?)`
+(the now-unused import is removed). Idempotent — object-form calls are left alone.
+
+A call is only touched when its receiver is provably a feature registrar: a parameter of
+the `defineFeature(name, (r) => …)` callback, or a binding typed `FeatureRegistrar`.
+Anything else (`sessions.requires("x")`, `foo.entity(…)`) stays untouched. A call on an
+untyped `r`/`registrar` it cannot resolve, a spread argument, too few arguments or
+`entity` options other than `{ table }` are reported as `manual` instead of guessed at.
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/object-form.ts <dir> [--check | --dry-run | --write] [--no-format]
+```
+
+Runs automatically via `bun kumiko-upgrade --apply`. Without a mode flag it writes, then
+formats the changed files with the Biome binary found in `node_modules/.bin` (`--no-format`
+skips that). `--dry-run` only reports; `--check` reports and exits 1 while any rewritable
+or manual site is left.