@cosmicdrift/kumiko-framework 0.294.0 → 0.295.0

package/package.json

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

package/src/__tests__/schema-cli-temporal-polyfill.test.ts

@@ -28,7 +28,7 @@ describe("runSchemaCli — Temporal polyfill", () => {
     // never retried on the next run.
     //
     // Asserting on globalThis.Temporal directly doesn't work here: the test
-    // harness's own preload (test-setup/base.preload.ts) already calls
+    // harness's own preload (@cosmicdrift/kumiko-testing/preload/temporal) already calls
     // ensureTemporalPolyfill() once per process, and its idempotency cache
     // (a module-level flag, not re-derived from globalThis) short-circuits
     // any later call regardless of what a test does to globalThis.Temporal in

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.294.1",
+    "type": "fix",
+    "title": "Fix parseEnv for refined env schemas with ciphertext-only Key Manager slots",
+    "detail": "Relaxing a `kms` slot that is present only as `<NAME>_CIPHERTEXT` used `schema.extend`, which Zod 4 rejects for object schemas carrying refinements (\"Cannot overwrite keys on object schemas containing refinements\"). An app whose composed env schema ends in `.superRefine(...)` therefore failed at boot as soon as its slots were delivered as ciphertext. The relaxation now uses `safeExtend`, which keeps the refinements running."
+  },
   {
     "version": "0.294.0",
     "type": "improvement",

package/src/env/__tests__/compose-env-schema.test.ts

@@ -334,6 +334,23 @@ describe("kms env slots", () => {
   it("parseEnv still validates a kms slot that is set", () => {
     expect(() => parseEnv(schema, { MASTER_KEY: "" })).toThrow(KumikoBootError);
   });
+
+  describe("schema carrying a refinement", () => {
+    const refined = schema.superRefine((value, ctx) => {
+      if (value.PLAIN === "forbidden") {
+        ctx.addIssue({ code: "custom", path: ["PLAIN"], message: "PLAIN is forbidden" });
+      }
+    });
+
+    it("parseEnv relaxes a ciphertext-only slot without dropping the refinement", () => {
+      expect(parseEnv(refined, { MASTER_KEY_CIPHERTEXT: "abc" })["MASTER_KEY_CIPHERTEXT"]).toBe(
+        "abc",
+      );
+      expect(() => parseEnv(refined, { MASTER_KEY_CIPHERTEXT: "abc", PLAIN: "forbidden" })).toThrow(
+        KumikoBootError,
+      );
+    });
+  });
 });
 
 describe("composeEnvSchema kms twins", () => {

package/src/env/index.ts

@@ -76,7 +76,8 @@ export function kmsSlotsOf(schema: z.ZodObject<z.ZodRawShape>): readonly string[
 
 // A ciphertext-only slot is satisfied by its `_CIPHERTEXT` twin: the plaintext
 // only exists after the boot-time decrypt, so requiring it here would reject
-// exactly the deployment this meta enables.
+// exactly the deployment this meta enables. safeExtend, not extend: Zod 4 throws
+// on extend for schemas carrying refinements (app-level superRefine).
 function relaxCiphertextOnlySlots<S extends z.ZodObject<z.ZodRawShape>>(
   schema: S,
   env: Readonly<Record<string, string>>,
@@ -88,7 +89,7 @@ function relaxCiphertextOnlySlots<S extends z.ZodObject<z.ZodRawShape>>(
     if (field && env[name] === undefined && env[`${name}_CIPHERTEXT`])
       relaxed[name] = field.optional();
   }
-  return Object.keys(relaxed).length === 0 ? schema : schema.extend(relaxed);
+  return Object.keys(relaxed).length === 0 ? schema : schema.safeExtend(relaxed);
 }
 
 // --- Field-classification helpers (Zod v4 introspection) ---

package/src/search/__tests__/meilisearch-adapter.integration.test.ts

@@ -42,7 +42,7 @@ let indexPrefix: string;
 describe.skipIf(!MEILI_UP)("meilisearch adapter (live)", () => {
   beforeAll(async () => {
     client = new Meilisearch({ host: MEILI_URL, apiKey: MEILI_KEY });
-    indexPrefix = `test_${uuid().slice(-6)}_`;
+    indexPrefix = `test_${uuid()}_`;
     adapter = createMeilisearchAdapter({
       url: MEILI_URL,
       apiKey: MEILI_KEY,
@@ -110,10 +110,9 @@ describe.skipIf(!MEILI_UP)("meilisearch adapter (live)", () => {
   });
 
   afterAll(async () => {
-    // Clean up all test indices
     const indices = await client.getIndexes();
     for (const idx of indices.results) {
-      if (idx.uid.startsWith("test_")) {
+      if (idx.uid.startsWith(indexPrefix)) {
         try {
           await client.index(idx.uid).delete().waitTask();
         } catch {

package/src/stack/db.ts

@@ -12,7 +12,7 @@ function requireEnv(name: string): string {
   const value = process.env[name];
   if (!value) {
     throw new Error(
-      `Missing required env var: ${name}. Copy .env.example to .env and fill in values.`,
+      `Missing required env var: ${name}. Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".`,
     );
   }
   return value;

package/src/testing/__tests__/real-providers.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { requireRealProviders } from "../real-providers";
+
+const CI = "CI";
+const FLAG = "KUMIKO_REAL_PROVIDERS";
+const API_KEY = "ANTHROPIC_API_KEY";
+const TOUCHED_ENV = [CI, FLAG, API_KEY];
+
+describe("requireRealProviders", () => {
+  const saved = new Map<string, string | undefined>();
+
+  beforeEach(() => {
+    for (const name of TOUCHED_ENV) {
+      saved.set(name, process.env[name]);
+      delete process.env[name];
+    }
+  });
+
+  afterEach(() => {
+    for (const [name, value] of saved) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  test("throws when the flag is missing, even with an API key set", () => {
+    process.env[API_KEY] = "sk-test";
+    expect(() => requireRealProviders()).toThrow(/KUMIKO_REAL_PROVIDERS=1/);
+  });
+
+  test("throws when the flag has any value other than 1", () => {
+    process.env[FLAG] = "true";
+    expect(() => requireRealProviders()).toThrow(/KUMIKO_REAL_PROVIDERS=1/);
+  });
+
+  test("throws in CI even with the flag set", () => {
+    process.env[CI] = "true";
+    process.env[FLAG] = "1";
+    expect(() => requireRealProviders()).toThrow(/never run in CI/);
+  });
+
+  test("does not throw with the flag set outside CI", () => {
+    process.env[FLAG] = "1";
+    expect(() => requireRealProviders()).not.toThrow();
+  });
+
+  test("treats CI=false and CI=0 as not CI", () => {
+    process.env[FLAG] = "1";
+    process.env[CI] = "false";
+    expect(() => requireRealProviders()).not.toThrow();
+    process.env[CI] = "0";
+    expect(() => requireRealProviders()).not.toThrow();
+  });
+});

package/src/testing/index.ts

@@ -44,6 +44,7 @@ export {
   createRecordingProvider,
   type RecordingProvider,
 } from "./observability-recorder";
+export { requireRealProviders } from "./real-providers";
 export { deleteRows, seedRow, seedRows, updateRows } from "./seed";
 export {
   sharedItemEntity,

package/src/testing/real-providers.ts

@@ -0,0 +1,20 @@
+const REAL_PROVIDERS_FLAG = "KUMIKO_REAL_PROVIDERS";
+const CI_FLAG = "CI";
+
+function isCi(): boolean {
+  const ci = process.env[CI_FLAG];
+  return ci !== undefined && ci !== "" && ci !== "0" && ci.toLowerCase() !== "false";
+}
+
+export function requireRealProviders(): void {
+  if (isCi()) {
+    throw new Error(
+      `Real-provider tests never run in CI (CI is set). Run them locally with ${REAL_PROVIDERS_FLAG}=1 via the test:real / e2e:real script.`,
+    );
+  }
+  if (process.env[REAL_PROVIDERS_FLAG] !== "1") {
+    throw new Error(
+      `Real-provider test needs ${REAL_PROVIDERS_FLAG}=1 (an API key alone never enables it). Run it via the test:real / e2e:real script.`,
+    );
+  }
+}