@frontmcp/utils 1.9.1 → 1.9.2

package/env/browser-env.d.ts

@@ -7,6 +7,12 @@
 export declare function getEnv(_key: string): string | undefined;
 export declare function getEnv(_key: string, defaultValue: string): string;
 export declare function getCwd(): string;
+/**
+ * The NODE_ENV the page runs with: a `process` shim's live value first, then the value a
+ * bundler inlined for `process.env.NODE_ENV`, else none. `isProduction()`, `isDevelopment()`
+ * and the runtime context's `env` all read it (#770). As on Node, with no NODE_ENV the
+ * runtime context reports `development` while `isDevelopment()` stays false.
+ */
 export declare function getNodeEnv(): string | undefined;
 export declare function isProduction(): boolean;
 export declare function isDevelopment(): boolean;

package/env/browser-env.js

@@ -50,6 +50,14 @@ function isBrowserWorkerScope() {
 }
 
 // libs/utils/src/env/browser-env.ts
+var NODE_ENV_KEY = "NODE_ENV";
+function bundlerDefinedNodeEnv() {
+  try {
+    return process.env["NODE_ENV"] || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function getEnv(_key, defaultValue) {
   return defaultValue;
 }
@@ -57,13 +65,14 @@ function getCwd() {
   return "/";
 }
 function getNodeEnv() {
-  return void 0;
+  const shim = globalThis.process;
+  return shim?.env?.[NODE_ENV_KEY] || bundlerDefinedNodeEnv();
 }
 function isProduction() {
-  return false;
+  return getNodeEnv() === "production";
 }
 function isDevelopment() {
-  return false;
+  return getNodeEnv() === "development";
 }
 function getEnvFlag(_key) {
   return false;

package/env/browser-runtime-context.d.ts

@@ -57,5 +57,9 @@ export declare function checkEntryAvailability(availability: EntryAvailability |
     missingAxes: (keyof EntryAvailability)[];
 };
 export declare function detectRuntimeContext(): RuntimeContext;
+/**
+ * The browser runtime context. Its `env` is read live from the same NODE_ENV as
+ * `isProduction()`, defaulting to `development` as on Node (#770).
+ */
 export declare function getRuntimeContext(): RuntimeContext;
 export declare function resetRuntimeContext(): void;

package/env/browser-runtime-context.js

@@ -29,6 +29,22 @@ __export(browser_runtime_context_exports, {
 });
 module.exports = __toCommonJS(browser_runtime_context_exports);
 var import_lazy_zod = require("@frontmcp/lazy-zod");
+
+// libs/utils/src/env/browser-env.ts
+var NODE_ENV_KEY = "NODE_ENV";
+function bundlerDefinedNodeEnv() {
+  try {
+    return process.env["NODE_ENV"] || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getNodeEnv() {
+  const shim = globalThis.process;
+  return shim?.env?.[NODE_ENV_KEY] || bundlerDefinedNodeEnv();
+}
+
+// libs/utils/src/env/browser-runtime-context.ts
 var entryAvailabilitySchema = import_lazy_zod.z.object({
   os: import_lazy_zod.z.array(import_lazy_zod.z.string().min(1)).optional(),
   platform: import_lazy_zod.z.array(import_lazy_zod.z.string().min(1)).optional(),
@@ -84,14 +100,24 @@ function detectRuntimeContext() {
     deployment: "standalone",
     provider: "bare",
     target: "browser",
-    env: "production"
+    env: getNodeEnv() || "development"
   };
 }
-var browserContext = detectRuntimeContext();
+var cached;
 function getRuntimeContext() {
-  return browserContext;
+  if (!cached) {
+    const detected = detectRuntimeContext();
+    Object.defineProperty(detected, "env", {
+      get: () => getNodeEnv() || "development",
+      enumerable: true,
+      configurable: true
+    });
+    cached = detected;
+  }
+  return cached;
 }
 function resetRuntimeContext() {
+  cached = void 0;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/esm/env/browser-env.mjs

@@ -17,6 +17,14 @@ function isBrowserWorkerScope() {
 }
 
 // libs/utils/src/env/browser-env.ts
+var NODE_ENV_KEY = "NODE_ENV";
+function bundlerDefinedNodeEnv() {
+  try {
+    return process.env["NODE_ENV"] || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function getEnv(_key, defaultValue) {
   return defaultValue;
 }
@@ -24,13 +32,14 @@ function getCwd() {
   return "/";
 }
 function getNodeEnv() {
-  return void 0;
+  const shim = globalThis.process;
+  return shim?.env?.[NODE_ENV_KEY] || bundlerDefinedNodeEnv();
 }
 function isProduction() {
-  return false;
+  return getNodeEnv() === "production";
 }
 function isDevelopment() {
-  return false;
+  return getNodeEnv() === "development";
 }
 function getEnvFlag(_key) {
   return false;

package/esm/env/browser-runtime-context.mjs

@@ -3,6 +3,22 @@ const require = __frontmcpModule ? __frontmcpModule.createRequire(import.meta.ur
 // __frontmcpCreateRequire
 // libs/utils/src/env/browser-runtime-context.ts
 import { z } from "@frontmcp/lazy-zod";
+
+// libs/utils/src/env/browser-env.ts
+var NODE_ENV_KEY = "NODE_ENV";
+function bundlerDefinedNodeEnv() {
+  try {
+    return process.env["NODE_ENV"] || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getNodeEnv() {
+  const shim = globalThis.process;
+  return shim?.env?.[NODE_ENV_KEY] || bundlerDefinedNodeEnv();
+}
+
+// libs/utils/src/env/browser-runtime-context.ts
 var entryAvailabilitySchema = z.object({
   os: z.array(z.string().min(1)).optional(),
   platform: z.array(z.string().min(1)).optional(),
@@ -58,14 +74,24 @@ function detectRuntimeContext() {
     deployment: "standalone",
     provider: "bare",
     target: "browser",
-    env: "production"
+    env: getNodeEnv() || "development"
   };
 }
-var browserContext = detectRuntimeContext();
+var cached;
 function getRuntimeContext() {
-  return browserContext;
+  if (!cached) {
+    const detected = detectRuntimeContext();
+    Object.defineProperty(detected, "env", {
+      get: () => getNodeEnv() || "development",
+      enumerable: true,
+      configurable: true
+    });
+    cached = detected;
+  }
+  return cached;
 }
 function resetRuntimeContext() {
+  cached = void 0;
 }
 export {
   checkEntryAvailability,

package/esm/index.mjs

@@ -3015,6 +3015,55 @@ var init_redis_error_listener = __esm({
   }
 });
 
+// libs/utils/src/storage/redis-url.ts
+function decodeOrRaw(encoded) {
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return encoded;
+  }
+}
+function mergeRedisUrlFields(rawUrl, fields) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return void 0;
+  }
+  const urlHost = url.hostname.replace(/^\[(.*)\]$/, "$1");
+  const urlPort = url.port ? Number(url.port) : void 0;
+  const urlPassword = url.password ? decodeOrRaw(url.password) : void 0;
+  const urlDbText = url.pathname.replace(/^\/+/, "") || url.searchParams.get("db") || void 0;
+  const urlDb = urlDbText === void 0 ? void 0 : Number(urlDbText);
+  const urlUsesTls = url.protocol === "rediss:";
+  const fillIns = {};
+  const conflicts = [];
+  if (fields.host !== void 0 && fields.host !== urlHost) conflicts.push("host");
+  if (fields.port !== void 0) {
+    if (urlPort === void 0) fillIns.port = fields.port;
+    else if (fields.port !== urlPort) conflicts.push("port");
+  }
+  if (fields.password !== void 0) {
+    if (urlPassword === void 0) fillIns.password = fields.password;
+    else if (fields.password !== urlPassword) conflicts.push("password");
+  }
+  if (fields.db !== void 0) {
+    if (urlDb === void 0) fillIns.db = fields.db;
+    else if (fields.db !== urlDb) conflicts.push("db");
+  }
+  if (fields.tls === true && !urlUsesTls) fillIns.tls = true;
+  if (fields.tls === false && urlUsesTls) conflicts.push("tls");
+  return { fillIns, conflicts };
+}
+function describeRedisUrlConflicts(conflicts) {
+  return `redis ${conflicts.join(", ")} contradict${conflicts.length === 1 ? "s" : ""} redis.url. Fields beside a url only fill in what the URL leaves out (port, password, db, tls); put the value in the URL or drop the field.`;
+}
+var init_redis_url = __esm({
+  "libs/utils/src/storage/redis-url.ts"() {
+    "use strict";
+  }
+});
+
 // libs/utils/src/storage/utils/index.ts
 var init_utils = __esm({
   "libs/utils/src/storage/utils/index.ts"() {
@@ -3054,6 +3103,17 @@ function getRedisClass() {
     });
   }
 }
+function resolveUrlFillIns(connectionUrl, options) {
+  const { url: configUrl, ...siblingFields } = { url: void 0, ...options.config };
+  if (options.url && configUrl && configUrl !== options.url) {
+    throw new StorageConfigError("redis", "redis.url and redis.config.url name different servers; set one of them.");
+  }
+  const merge = mergeRedisUrlFields(connectionUrl, siblingFields);
+  if (merge && merge.conflicts.length > 0) {
+    throw new StorageConfigError("redis", describeRedisUrlConflicts(merge.conflicts));
+  }
+  return merge?.fillIns ?? {};
+}
 function createRedisClient(options) {
   const RedisClass = getRedisClass();
   const baseOptions = { lazyConnect: false, maxRetriesPerRequest: 3 };
@@ -3074,6 +3134,7 @@ var init_redis = __esm({
     "use strict";
     init_errors();
     init_redis_error_listener();
+    init_redis_url();
     init_utils();
     init_compare_and_delete();
     init_base();
@@ -3087,6 +3148,8 @@ var init_redis = __esm({
       connecting;
       keyPrefix;
       subscriptionHandlers = /* @__PURE__ */ new Map();
+      connectionUrl;
+      urlFillIns;
       constructor(options = {}) {
         super();
         const hasClient = options.client !== void 0;
@@ -3108,6 +3171,9 @@ var init_redis = __esm({
         this.options = options;
         this.ownsClient = !hasClient;
         this.keyPrefix = options.keyPrefix ?? "";
+        const configUrl = options.config?.url;
+        this.connectionUrl = options.url ?? (typeof configUrl === "string" ? configUrl : void 0);
+        this.urlFillIns = this.connectionUrl ? resolveUrlFillIns(this.connectionUrl, options) : {};
       }
       // ============================================
       // Connection Lifecycle
@@ -3130,8 +3196,8 @@ var init_redis = __esm({
             client = this.options.client;
           } else {
             const RedisClass = getRedisClass();
-            if (this.options.url) {
-              client = new RedisClass(this.options.url, this.buildRedisOptions());
+            if (this.connectionUrl) {
+              client = new RedisClass(this.connectionUrl, this.buildRedisOptions());
             } else {
               client = new RedisClass(this.buildRedisOptions());
             }
@@ -3367,14 +3433,19 @@ var init_redis = __esm({
        * Build Redis options from config.
        */
       buildRedisOptions() {
-        if (this.options.url) {
+        if (this.connectionUrl) {
+          const { port, password, db, tls } = this.urlFillIns;
           return {
+            ...port !== void 0 ? { port } : {},
+            ...password !== void 0 ? { password } : {},
+            ...db !== void 0 ? { db } : {},
+            ...tls ? { tls: {} } : {},
             lazyConnect: false,
             maxRetriesPerRequest: 3
           };
         }
         const config = this.options.config;
-        if (!config) {
+        if (!config || typeof config.url === "string" || config.host === void 0) {
           throw new StorageConfigError("redis", "Redis config is required when URL is not provided");
         }
         return {
@@ -3393,8 +3464,8 @@ var init_redis = __esm({
       async createSubscriber() {
         const RedisClass = getRedisClass();
         let subscriber;
-        if (this.options.url) {
-          subscriber = new RedisClass(this.options.url);
+        if (this.connectionUrl) {
+          subscriber = new RedisClass(this.connectionUrl, this.buildRedisOptions());
         } else if (this.options.config) {
           subscriber = new RedisClass(this.buildRedisOptions());
         } else if (this.options.client) {
@@ -3445,7 +3516,8 @@ var init_redis = __esm({
 // libs/utils/src/storage/adapters/vercel-kv.ts
 var vercel_kv_exports = {};
 __export(vercel_kv_exports, {
-  VercelKvStorageAdapter: () => VercelKvStorageAdapter
+  VercelKvStorageAdapter: () => VercelKvStorageAdapter,
+  createVercelKvClient: () => createVercelKvClient
 });
 async function loadVercelKv() {
   try {
@@ -3457,6 +3529,15 @@ async function loadVercelKv() {
     throw new Error("@vercel/kv is required for Vercel KV storage adapter. Install it with: npm install @vercel/kv");
   }
 }
+async function createVercelKvClient(connection = {}) {
+  const url = connection.url ?? process.env["KV_REST_API_URL"];
+  const token = connection.token ?? process.env["KV_REST_API_TOKEN"];
+  if (!url || !token) {
+    throw new StorageConfigError("vercel-kv", "Pass url and token, or set KV_REST_API_URL and KV_REST_API_TOKEN.");
+  }
+  const { createClient } = await loadVercelKv();
+  return createClient({ url, token, cache: void 0, automaticDeserialization: false });
+}
 var VercelKvStorageAdapter;
 var init_vercel_kv = __esm({
   "libs/utils/src/storage/adapters/vercel-kv.ts"() {
@@ -3489,13 +3570,7 @@ var init_vercel_kv = __esm({
       async connect() {
         if (this.connected) return;
         try {
-          const { createClient } = await loadVercelKv();
-          const url = this.options.url;
-          const token = this.options.token;
-          if (!url || !token) {
-            throw new StorageConfigError("vercel-kv", "URL and token are required");
-          }
-          this.client = createClient({ url, token, cache: void 0, automaticDeserialization: false });
+          this.client = await createVercelKvClient({ url: this.options.url, token: this.options.token });
           await this.client.exists("__healthcheck__");
           this.connected = true;
         } catch (e) {
@@ -3668,9 +3743,12 @@ var upstash_exports = {};
 __export(upstash_exports, {
   UpstashStorageAdapter: () => UpstashStorageAdapter
 });
-function getUpstashRedis() {
+async function loadUpstashRedis() {
   try {
-    return __require("@upstash/redis");
+    const mod = await import("@upstash/redis");
+    const resolved = typeof mod.Redis === "function" ? mod : mod.default;
+    if (!resolved || typeof resolved.Redis !== "function") throw new Error("Redis missing");
+    return resolved;
   } catch {
     throw new Error(
       "@upstash/redis is required for Upstash storage adapter. Install it with: npm install @upstash/redis"
@@ -3715,7 +3793,7 @@ var init_upstash = __esm({
       async connect() {
         if (this.connected) return;
         try {
-          const { Redis } = getUpstashRedis();
+          const { Redis } = await loadUpstashRedis();
           const url = this.options.url;
           const token = this.options.token;
           if (!url || !token) {
@@ -5243,6 +5321,7 @@ function getDetectedStorageType() {
 
 // libs/utils/src/storage/index.ts
 init_redis_error_listener();
+init_redis_url();
 init_errors();
 
 // libs/utils/src/storage/typed-storage.ts
@@ -5956,9 +6035,11 @@ export {
   createSafeRegExp,
   createSecretData,
   createStorage,
+  createVercelKvClient,
   decryptAesGcm,
   decryptValue,
   deleteSecret,
+  describeRedisUrlConflicts,
   deserializeAndDecrypt,
   deserializeBlob,
   detectRuntimeContext,
@@ -6042,6 +6123,7 @@ export {
   loadSecret,
   matchUriTemplate,
   matchesPattern,
+  mergeRedisUrlFields,
   mkdir,
   mkdtemp,
   normalizeTTL,

package/index.d.ts

@@ -26,8 +26,8 @@ export { EventEmitter } from './event-emitter';
 export { getEnv, getNodeEnv, getCwd, isProduction, isDevelopment, getEnvFlag, isDebug, setEnv, isEdgeRuntime, isServerless, supportsAnsi, getRuntimeContext, resetRuntimeContext, detectRuntimeContext, isEntryAvailable, checkEntryAvailability, entryAvailabilitySchema, } from './env';
 export type { RuntimeContext, EntryAvailability } from './env';
 export { analyzePattern, isPatternSafe, createSafeRegExp, safeTest, safeMatch, safeReplace, safeExec, isInputLengthSafe, DEFAULT_MAX_INPUT_LENGTH, REDOS_THRESHOLDS, trimLeading, trimTrailing, trimBoth, trimChars, extractBracedParams, expandTemplate, hasTemplatePlaceholders, collapseChar, collapseWhitespace, type SafeRegexOptions, type PatternAnalysisResult, } from './regex';
-export { createStorage, createMemoryStorage, getDetectedStorageType, NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, EncryptedStorageError, BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, createRedisClient, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, type FileSystemAdapterOptions, TypedStorage, type TypedStorageOptions, type TypedSetOptions, type TypedSetEntry, EncryptedTypedStorage, type EncryptedTypedStorageOptions, type EncryptedSetOptions, type EncryptedSetEntry, type EncryptionKey, type StoredEncryptedBlob, type ClientKeyBinding, globToRegex, matchesPattern, validatePattern, escapeGlob, MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, attachRedisErrorListener, DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS, } from './storage';
-export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, RedisErrorListenerOptions, CreateRedisClientOptions, ErrorEmitterClient, } from './storage';
+export { createStorage, createMemoryStorage, getDetectedStorageType, NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, EncryptedStorageError, BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, createRedisClient, VercelKvStorageAdapter, createVercelKvClient, type VercelKvConnection, UpstashStorageAdapter, FileSystemStorageAdapter, type FileSystemAdapterOptions, TypedStorage, type TypedStorageOptions, type TypedSetOptions, type TypedSetEntry, EncryptedTypedStorage, type EncryptedTypedStorageOptions, type EncryptedSetOptions, type EncryptedSetEntry, type EncryptionKey, type StoredEncryptedBlob, type ClientKeyBinding, globToRegex, matchesPattern, validatePattern, escapeGlob, MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, attachRedisErrorListener, DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS, mergeRedisUrlFields, describeRedisUrlConflicts, } from './storage';
+export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, RedisHostConnectionConfig, RedisUrlConnectionConfig, RedisUrlFillInConfig, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, RedisErrorListenerOptions, RedisUrlMerge, RedisUrlSiblingFields, CreateRedisClientOptions, ErrorEmitterClient, } from './storage';
 export { processPlatformToolCalls } from './llm';
 export type { CallToolFn, OpenAIToolCallItem, OpenAIToolResponse, ClaudeToolUseBlock, ClaudeToolResultBlock, VercelToolCallInfo, PlatformToolCallsInput, PlatformToolCallsOutput, SupportedPlatform, } from './llm';
 export { getMachineId, setMachineIdOverride } from './machine-id';

package/index.js

@@ -3017,6 +3017,55 @@ var init_redis_error_listener = __esm({
   }
 });
 
+// libs/utils/src/storage/redis-url.ts
+function decodeOrRaw(encoded) {
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return encoded;
+  }
+}
+function mergeRedisUrlFields(rawUrl, fields) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return void 0;
+  }
+  const urlHost = url.hostname.replace(/^\[(.*)\]$/, "$1");
+  const urlPort = url.port ? Number(url.port) : void 0;
+  const urlPassword = url.password ? decodeOrRaw(url.password) : void 0;
+  const urlDbText = url.pathname.replace(/^\/+/, "") || url.searchParams.get("db") || void 0;
+  const urlDb = urlDbText === void 0 ? void 0 : Number(urlDbText);
+  const urlUsesTls = url.protocol === "rediss:";
+  const fillIns = {};
+  const conflicts = [];
+  if (fields.host !== void 0 && fields.host !== urlHost) conflicts.push("host");
+  if (fields.port !== void 0) {
+    if (urlPort === void 0) fillIns.port = fields.port;
+    else if (fields.port !== urlPort) conflicts.push("port");
+  }
+  if (fields.password !== void 0) {
+    if (urlPassword === void 0) fillIns.password = fields.password;
+    else if (fields.password !== urlPassword) conflicts.push("password");
+  }
+  if (fields.db !== void 0) {
+    if (urlDb === void 0) fillIns.db = fields.db;
+    else if (fields.db !== urlDb) conflicts.push("db");
+  }
+  if (fields.tls === true && !urlUsesTls) fillIns.tls = true;
+  if (fields.tls === false && urlUsesTls) conflicts.push("tls");
+  return { fillIns, conflicts };
+}
+function describeRedisUrlConflicts(conflicts) {
+  return `redis ${conflicts.join(", ")} contradict${conflicts.length === 1 ? "s" : ""} redis.url. Fields beside a url only fill in what the URL leaves out (port, password, db, tls); put the value in the URL or drop the field.`;
+}
+var init_redis_url = __esm({
+  "libs/utils/src/storage/redis-url.ts"() {
+    "use strict";
+  }
+});
+
 // libs/utils/src/storage/utils/index.ts
 var init_utils = __esm({
   "libs/utils/src/storage/utils/index.ts"() {
@@ -3056,6 +3105,17 @@ function getRedisClass() {
     });
   }
 }
+function resolveUrlFillIns(connectionUrl, options) {
+  const { url: configUrl, ...siblingFields } = { url: void 0, ...options.config };
+  if (options.url && configUrl && configUrl !== options.url) {
+    throw new StorageConfigError("redis", "redis.url and redis.config.url name different servers; set one of them.");
+  }
+  const merge = mergeRedisUrlFields(connectionUrl, siblingFields);
+  if (merge && merge.conflicts.length > 0) {
+    throw new StorageConfigError("redis", describeRedisUrlConflicts(merge.conflicts));
+  }
+  return merge?.fillIns ?? {};
+}
 function createRedisClient(options) {
   const RedisClass = getRedisClass();
   const baseOptions = { lazyConnect: false, maxRetriesPerRequest: 3 };
@@ -3076,6 +3136,7 @@ var init_redis = __esm({
     "use strict";
     init_errors();
     init_redis_error_listener();
+    init_redis_url();
     init_utils();
     init_compare_and_delete();
     init_base();
@@ -3089,6 +3150,8 @@ var init_redis = __esm({
       connecting;
       keyPrefix;
       subscriptionHandlers = /* @__PURE__ */ new Map();
+      connectionUrl;
+      urlFillIns;
       constructor(options = {}) {
         super();
         const hasClient = options.client !== void 0;
@@ -3110,6 +3173,9 @@ var init_redis = __esm({
         this.options = options;
         this.ownsClient = !hasClient;
         this.keyPrefix = options.keyPrefix ?? "";
+        const configUrl = options.config?.url;
+        this.connectionUrl = options.url ?? (typeof configUrl === "string" ? configUrl : void 0);
+        this.urlFillIns = this.connectionUrl ? resolveUrlFillIns(this.connectionUrl, options) : {};
       }
       // ============================================
       // Connection Lifecycle
@@ -3132,8 +3198,8 @@ var init_redis = __esm({
             client = this.options.client;
           } else {
             const RedisClass = getRedisClass();
-            if (this.options.url) {
-              client = new RedisClass(this.options.url, this.buildRedisOptions());
+            if (this.connectionUrl) {
+              client = new RedisClass(this.connectionUrl, this.buildRedisOptions());
             } else {
               client = new RedisClass(this.buildRedisOptions());
             }
@@ -3369,14 +3435,19 @@ var init_redis = __esm({
        * Build Redis options from config.
        */
       buildRedisOptions() {
-        if (this.options.url) {
+        if (this.connectionUrl) {
+          const { port, password, db, tls } = this.urlFillIns;
           return {
+            ...port !== void 0 ? { port } : {},
+            ...password !== void 0 ? { password } : {},
+            ...db !== void 0 ? { db } : {},
+            ...tls ? { tls: {} } : {},
             lazyConnect: false,
             maxRetriesPerRequest: 3
           };
         }
         const config = this.options.config;
-        if (!config) {
+        if (!config || typeof config.url === "string" || config.host === void 0) {
           throw new StorageConfigError("redis", "Redis config is required when URL is not provided");
         }
         return {
@@ -3395,8 +3466,8 @@ var init_redis = __esm({
       async createSubscriber() {
         const RedisClass = getRedisClass();
         let subscriber;
-        if (this.options.url) {
-          subscriber = new RedisClass(this.options.url);
+        if (this.connectionUrl) {
+          subscriber = new RedisClass(this.connectionUrl, this.buildRedisOptions());
         } else if (this.options.config) {
           subscriber = new RedisClass(this.buildRedisOptions());
         } else if (this.options.client) {
@@ -3447,7 +3518,8 @@ var init_redis = __esm({
 // libs/utils/src/storage/adapters/vercel-kv.ts
 var vercel_kv_exports = {};
 __export(vercel_kv_exports, {
-  VercelKvStorageAdapter: () => VercelKvStorageAdapter
+  VercelKvStorageAdapter: () => VercelKvStorageAdapter,
+  createVercelKvClient: () => createVercelKvClient
 });
 async function loadVercelKv() {
   try {
@@ -3459,6 +3531,15 @@ async function loadVercelKv() {
     throw new Error("@vercel/kv is required for Vercel KV storage adapter. Install it with: npm install @vercel/kv");
   }
 }
+async function createVercelKvClient(connection = {}) {
+  const url = connection.url ?? process.env["KV_REST_API_URL"];
+  const token = connection.token ?? process.env["KV_REST_API_TOKEN"];
+  if (!url || !token) {
+    throw new StorageConfigError("vercel-kv", "Pass url and token, or set KV_REST_API_URL and KV_REST_API_TOKEN.");
+  }
+  const { createClient } = await loadVercelKv();
+  return createClient({ url, token, cache: void 0, automaticDeserialization: false });
+}
 var VercelKvStorageAdapter;
 var init_vercel_kv = __esm({
   "libs/utils/src/storage/adapters/vercel-kv.ts"() {
@@ -3491,13 +3572,7 @@ var init_vercel_kv = __esm({
       async connect() {
         if (this.connected) return;
         try {
-          const { createClient } = await loadVercelKv();
-          const url = this.options.url;
-          const token = this.options.token;
-          if (!url || !token) {
-            throw new StorageConfigError("vercel-kv", "URL and token are required");
-          }
-          this.client = createClient({ url, token, cache: void 0, automaticDeserialization: false });
+          this.client = await createVercelKvClient({ url: this.options.url, token: this.options.token });
           await this.client.exists("__healthcheck__");
           this.connected = true;
         } catch (e) {
@@ -3670,9 +3745,12 @@ var upstash_exports = {};
 __export(upstash_exports, {
   UpstashStorageAdapter: () => UpstashStorageAdapter
 });
-function getUpstashRedis() {
+async function loadUpstashRedis() {
   try {
-    return require("@upstash/redis");
+    const mod = await import("@upstash/redis");
+    const resolved = typeof mod.Redis === "function" ? mod : mod.default;
+    if (!resolved || typeof resolved.Redis !== "function") throw new Error("Redis missing");
+    return resolved;
   } catch {
     throw new Error(
       "@upstash/redis is required for Upstash storage adapter. Install it with: npm install @upstash/redis"
@@ -3717,7 +3795,7 @@ var init_upstash = __esm({
       async connect() {
         if (this.connected) return;
         try {
-          const { Redis } = getUpstashRedis();
+          const { Redis } = await loadUpstashRedis();
           const url = this.options.url;
           const token = this.options.token;
           if (!url || !token) {
@@ -4184,9 +4262,11 @@ __export(index_exports, {
   createSafeRegExp: () => createSafeRegExp,
   createSecretData: () => createSecretData,
   createStorage: () => createStorage,
+  createVercelKvClient: () => createVercelKvClient,
   decryptAesGcm: () => decryptAesGcm,
   decryptValue: () => decryptValue,
   deleteSecret: () => deleteSecret,
+  describeRedisUrlConflicts: () => describeRedisUrlConflicts,
   deserializeAndDecrypt: () => deserializeAndDecrypt,
   deserializeBlob: () => deserializeBlob,
   detectRuntimeContext: () => import_runtime_context.detectRuntimeContext,
@@ -4270,6 +4350,7 @@ __export(index_exports, {
   loadSecret: () => loadSecret,
   matchUriTemplate: () => matchUriTemplate,
   matchesPattern: () => matchesPattern,
+  mergeRedisUrlFields: () => mergeRedisUrlFields,
   mkdir: () => mkdir,
   mkdtemp: () => mkdtemp,
   normalizeTTL: () => normalizeTTL,
@@ -5446,6 +5527,7 @@ function getDetectedStorageType() {
 
 // libs/utils/src/storage/index.ts
 init_redis_error_listener();
+init_redis_url();
 init_errors();
 
 // libs/utils/src/storage/typed-storage.ts
@@ -6160,9 +6242,11 @@ function setMachineIdOverride(id) {
   createSafeRegExp,
   createSecretData,
   createStorage,
+  createVercelKvClient,
   decryptAesGcm,
   decryptValue,
   deleteSecret,
+  describeRedisUrlConflicts,
   deserializeAndDecrypt,
   deserializeBlob,
   detectRuntimeContext,
@@ -6246,6 +6330,7 @@ function setMachineIdOverride(id) {
   loadSecret,
   matchUriTemplate,
   matchesPattern,
+  mergeRedisUrlFields,
   mkdir,
   mkdtemp,
   normalizeTTL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.9.1",
+    "@frontmcp/lazy-zod": "1.9.2",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"
   },

package/storage/adapters/index.d.ts

@@ -7,7 +7,7 @@ export { BaseStorageAdapter } from './base';
 export { MemoryStorageAdapter } from './memory';
 export { RedisStorageAdapter, createRedisClient } from './redis';
 export type { CreateRedisClientOptions } from './redis';
-export { VercelKvStorageAdapter } from './vercel-kv';
+export { VercelKvStorageAdapter, createVercelKvClient, type VercelKvConnection } from './vercel-kv';
 export { UpstashStorageAdapter } from './upstash';
 export { CloudflareKvStorageAdapter } from './cloudflare-kv';
 export { FileSystemStorageAdapter } from './filesystem';

package/storage/adapters/redis.d.ts

@@ -39,6 +39,8 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     private connecting?;
     private readonly keyPrefix;
     private readonly subscriptionHandlers;
+    private readonly connectionUrl?;
+    private readonly urlFillIns;
     constructor(options?: RedisAdapterOptions);
     connect(): Promise<void>;
     private openConnection;

package/storage/adapters/vercel-kv.d.ts

@@ -6,6 +6,46 @@
  */
 import type { SetOptions, VercelKvAdapterOptions } from '../types';
 import { BaseStorageAdapter } from './base';
+type VercelKvClient = {
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, options?: {
+        ex?: number;
+        nx?: boolean;
+        xx?: boolean;
+    }) => Promise<string | null>;
+    del: (...keys: string[]) => Promise<number>;
+    exists: (...keys: string[]) => Promise<number>;
+    mget: (...keys: string[]) => Promise<(string | null)[]>;
+    expire: (key: string, seconds: number) => Promise<number>;
+    ttl: (key: string) => Promise<number>;
+    incr: (key: string) => Promise<number>;
+    decr: (key: string) => Promise<number>;
+    incrby: (key: string, increment: number) => Promise<number>;
+    eval: (script: string, keys: string[], args: string[]) => Promise<unknown>;
+    scan: (cursor: number, options?: {
+        match?: string;
+        count?: number;
+    }) => Promise<[string, string[]]>;
+    keys: (pattern: string) => Promise<string[]>;
+};
+/** Where a Vercel KV client connects; both default to the `KV_REST_API_URL` / `KV_REST_API_TOKEN` variables. */
+export interface VercelKvConnection {
+    url?: string;
+    token?: string;
+}
+/**
+ * Build a `@vercel/kv` REST client, the one loader every FrontMCP Vercel KV store shares (#711).
+ *
+ * `@vercel/kv` sets `cache: 'default'` on every request, which Cloudflare Workers reject ("The
+ * 'cache' field on 'RequestInitializerDict' is not implemented" / "Unsupported cache mode:
+ * default"), and the module's `kv` singleton cannot take another value. So each store gets a client
+ * of its own with the fetch cache mode unset (the value `@vercel/kv` itself calls equivalent), and
+ * values are read back exactly as stored instead of being JSON-parsed.
+ *
+ * @param connection - URL and token; each falls back to its environment variable
+ * @returns The client, typed as the subset of it the caller uses
+ */
+export declare function createVercelKvClient<TClient = VercelKvClient>(connection?: VercelKvConnection): Promise<TClient>;
 /**
  * Vercel KV storage adapter.
  *
@@ -68,3 +108,4 @@ export declare class VercelKvStorageAdapter extends BaseStorageAdapter {
      */
     private unprefixKey;
 }
+export {};

package/storage/index.d.ts

@@ -4,17 +4,19 @@
  * Unified storage abstraction with pluggable backends.
  * Supports Memory (dev), Redis (prod), Vercel KV (edge), and Upstash (edge + pub/sub).
  */
-export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, } from './types';
+export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, RedisHostConnectionConfig, RedisUrlConnectionConfig, RedisUrlFillInConfig, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, } from './types';
 export { createStorage, createMemoryStorage, getDetectedStorageType } from './factory';
 export { attachRedisErrorListener, DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS } from './redis-error-listener';
 export type { RedisErrorListenerOptions, ErrorEmitterClient } from './redis-error-listener';
+export { mergeRedisUrlFields, describeRedisUrlConflicts } from './redis-url';
+export type { RedisUrlMerge, RedisUrlSiblingFields } from './redis-url';
 export { NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, } from './namespace';
 export { StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, EncryptedStorageError, } from './errors';
 export { TypedStorage } from './typed-storage';
 export type { TypedStorageOptions, TypedSetOptions, TypedSetEntry } from './typed-storage.types';
 export { EncryptedTypedStorage } from './encrypted-typed-storage';
 export type { EncryptedTypedStorageOptions, EncryptedSetOptions, EncryptedSetEntry, EncryptionKey, StoredEncryptedBlob, ClientKeyBinding, } from './encrypted-typed-storage.types';
-export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, createRedisClient, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, LocalStorageAdapter, IndexedDBStorageAdapter, } from './adapters';
-export type { CreateRedisClientOptions, FileSystemAdapterOptions, LocalStorageAdapterOptions, IndexedDBAdapterOptions, } from './adapters';
+export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, createRedisClient, VercelKvStorageAdapter, createVercelKvClient, UpstashStorageAdapter, FileSystemStorageAdapter, LocalStorageAdapter, IndexedDBStorageAdapter, } from './adapters';
+export type { CreateRedisClientOptions, VercelKvConnection, FileSystemAdapterOptions, LocalStorageAdapterOptions, IndexedDBAdapterOptions, } from './adapters';
 export { globToRegex, matchesPattern, validatePattern, escapeGlob } from './utils/pattern';
 export { MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './utils/ttl';

package/storage/redis-url.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Connection fields that may be written beside a Redis `url`.
+ */
+export interface RedisUrlSiblingFields {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+}
+/**
+ * Outcome of combining a Redis URL with the fields written beside it.
+ */
+export interface RedisUrlMerge {
+    /** Fields the URL leaves out that the sibling fields supply. */
+    fillIns: Pick<RedisUrlSiblingFields, 'port' | 'password' | 'db' | 'tls'>;
+    /** Sibling fields whose value contradicts the URL. */
+    conflicts: Array<keyof RedisUrlSiblingFields>;
+}
+/**
+ * The URL is the base: fields beside it fill in only what it leaves out (a
+ * port, a password, a database, TLS), and a field that contradicts it is a
+ * conflict the caller must reject (#768). Returns `undefined` for an
+ * unparseable URL, which the caller reports on its own terms.
+ */
+export declare function mergeRedisUrlFields(rawUrl: string, fields: RedisUrlSiblingFields): RedisUrlMerge | undefined;
+/** Human-readable reason for {@link RedisUrlMerge.conflicts}. */
+export declare function describeRedisUrlConflicts(conflicts: RedisUrlMerge['conflicts']): string;

package/storage/types.d.ts

@@ -309,6 +309,31 @@ export interface MemoryAdapterOptions {
      */
     maxEntries?: number;
 }
+/**
+ * Redis connection by host.
+ */
+export interface RedisHostConnectionConfig {
+    host: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+    /** Unset for a host config (a config built from optional settings may carry `url: undefined`). */
+    url?: undefined;
+}
+/**
+ * Redis connection by URL (`redis://` / `rediss://`).
+ */
+export interface RedisUrlConnectionConfig extends Partial<Omit<RedisHostConnectionConfig, 'url'>> {
+    url: string;
+}
+/**
+ * Fields beside a top-level `url` (`{ url, config: { password } }`) that fill in what the URL
+ * leaves out. Without a `url` the adapter needs a `host` and rejects this shape.
+ */
+export interface RedisUrlFillInConfig extends Partial<Omit<RedisHostConnectionConfig, 'url'>> {
+    url?: undefined;
+}
 /**
  * Options for Redis storage adapter.
  */
@@ -319,19 +344,16 @@ export interface RedisAdapterOptions {
      */
     client?: unknown;
     /**
-     * Redis connection configuration.
+     * Redis connection configuration — `host`, or a `url` like the top-level
+     * `redis` option. Beside a URL, the other fields only fill in what the URL
+     * leaves out; a contradicting field is rejected.
      * Mutually exclusive with `client`.
      */
-    config?: {
-        host: string;
-        port?: number;
-        password?: string;
-        db?: number;
-        tls?: boolean;
-    };
+    config?: RedisHostConnectionConfig | RedisUrlConnectionConfig | RedisUrlFillInConfig;
     /**
      * Redis connection URI.
-     * e.g., "redis://user:pass@host:6379/0"
+     * e.g., "redis://user:pass@host:6379/0". Fields in `config` fill in what it
+     * leaves out (port, password, db, tls).
      * Mutually exclusive with `client`.
      */
     url?: string;