@frontmcp/utils 1.4.0 → 1.5.0-rc.1

package/esm/async-context/browser-async-context.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/async-context/browser-async-context.ts
 var AsyncLocalStorage = class {
   stack = [];

package/esm/async-context/node-async-context.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/async-context/node-async-context.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 export {

package/esm/crypto/browser.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/crypto/browser.ts
 import { sha256 as sha256Hash } from "@noble/hashes/sha2.js";
 import { hmac } from "@noble/hashes/hmac.js";

package/esm/crypto/node.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/crypto/node.ts
 import crypto from "node:crypto";
 

package/esm/env/browser-env.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/env/browser-env.ts
 function getEnv(_key, defaultValue) {
   return defaultValue;

package/esm/env/node-env.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/env/node-env.ts
 function getEnv(key, defaultValue) {
   return process.env[key] ?? defaultValue;

package/esm/event-emitter/browser-event-emitter.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/event-emitter/browser-event-emitter.ts
 var EventEmitter = class {
   events = /* @__PURE__ */ new Map();

package/esm/event-emitter/node-event-emitter.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 // libs/utils/src/event-emitter/node-event-emitter.ts
 import { EventEmitter } from "events";
 export {

package/esm/index.mjs

@@ -1,5 +1,5 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
-const require = __frontmcpCreateRequire(import.meta.url);
+const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -10,8 +10,13 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -75,8 +80,8 @@ async function readFile(p, encoding = "utf8") {
   return fsp.readFile(p, encoding);
 }
 function readFileSync(p, encoding = "utf8") {
-  const fs2 = getFs();
-  return fs2.readFileSync(p, encoding);
+  const fs = getFs();
+  return fs.readFileSync(p, encoding);
 }
 async function readFileBuffer(p) {
   const fsp = getFsp();
@@ -91,8 +96,8 @@ async function mkdir(p, options) {
   await fsp.mkdir(p, options);
 }
 function ensureDirSync(p) {
-  const fs2 = getFs();
-  fs2.mkdirSync(p, { recursive: true });
+  const fs = getFs();
+  fs.mkdirSync(p, { recursive: true });
 }
 async function rename(oldPath, newPath) {
   const fsp = getFsp();
@@ -153,8 +158,8 @@ async function readdir(p) {
   return fsp.readdir(p);
 }
 function readdirSync(p) {
-  const fs2 = getFs();
-  return fs2.readdirSync(p);
+  const fs = getFs();
+  return fs.readdirSync(p);
 }
 async function rm(p, options) {
   const fsp = getFsp();
@@ -187,8 +192,8 @@ function runCmd(cmd, args, opts = {}) {
   });
 }
 function watchFile(p, onChange, options) {
-  const fs2 = getFs();
-  const watcher = fs2.watch(p, { persistent: false, recursive: options?.recursive === true }, (eventType, filename) => {
+  const fs = getFs();
+  const watcher = fs.watch(p, { persistent: false, recursive: options?.recursive === true }, (eventType, filename) => {
     onChange(eventType, filename);
   });
   return {
@@ -1016,6 +1021,7 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageConnectionError";
       }
+      backend;
     };
     StorageOperationError = class extends StorageError {
       constructor(operation, key, message, cause) {
@@ -1024,6 +1030,8 @@ var init_errors = __esm({
         this.key = key;
         this.name = "StorageOperationError";
       }
+      operation;
+      key;
     };
     StorageNotSupportedError = class extends StorageError {
       constructor(operation, backend, suggestion) {
@@ -1033,6 +1041,8 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageNotSupportedError";
       }
+      operation;
+      backend;
     };
     StorageConfigError = class extends StorageError {
       constructor(backend, message) {
@@ -1040,6 +1050,7 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageConfigError";
       }
+      backend;
     };
     StorageTTLError = class extends StorageError {
       constructor(ttl, message) {
@@ -1047,6 +1058,7 @@ var init_errors = __esm({
         this.ttl = ttl;
         this.name = "StorageTTLError";
       }
+      ttl;
     };
     StoragePatternError = class extends StorageError {
       constructor(pattern, message) {
@@ -1054,6 +1066,7 @@ var init_errors = __esm({
         this.pattern = pattern;
         this.name = "StoragePatternError";
       }
+      pattern;
     };
     StorageNotConnectedError = class extends StorageError {
       constructor(backend) {
@@ -1061,6 +1074,7 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageNotConnectedError";
       }
+      backend;
     };
     EncryptedStorageError = class extends StorageError {
       constructor(message) {
@@ -3809,6 +3823,154 @@ var init_upstash = __esm({
   }
 });
 
+// libs/utils/src/storage/adapters/cloudflare-kv.ts
+var cloudflare_kv_exports = {};
+__export(cloudflare_kv_exports, {
+  CloudflareKvStorageAdapter: () => CloudflareKvStorageAdapter
+});
+function literalPrefix(pattern) {
+  const star = pattern.indexOf("*");
+  const q = pattern.indexOf("?");
+  const idx = star === -1 ? q : q === -1 ? star : Math.min(star, q);
+  return idx === -1 ? pattern : pattern.slice(0, idx);
+}
+var CF_KV_MIN_TTL_SECONDS, CloudflareKvStorageAdapter;
+var init_cloudflare_kv = __esm({
+  "libs/utils/src/storage/adapters/cloudflare-kv.ts"() {
+    "use strict";
+    init_errors();
+    init_pattern();
+    init_ttl();
+    init_base();
+    CF_KV_MIN_TTL_SECONDS = 60;
+    CloudflareKvStorageAdapter = class extends BaseStorageAdapter {
+      backendName = "cloudflare-kv";
+      kv;
+      keyPrefix;
+      constructor(options) {
+        super();
+        if (!options?.namespace) {
+          throw new Error("CloudflareKvStorageAdapter: a bound KV `namespace` is required (resolve it from the Worker `env`).");
+        }
+        this.kv = options.namespace;
+        this.keyPrefix = options.keyPrefix ?? "";
+      }
+      // ── Lifecycle ──────────────────────────────────────────────────────────
+      // A KV binding is always available; "connection" is just a readiness flag.
+      async connect() {
+        this.connected = true;
+      }
+      async disconnect() {
+        this.connected = false;
+      }
+      async ping() {
+        if (!this.connected) return false;
+        try {
+          await this.kv.list({ limit: 1 });
+          return true;
+        } catch {
+          return false;
+        }
+      }
+      // ── Core ───────────────────────────────────────────────────────────────
+      async get(key) {
+        this.ensureConnected();
+        return this.kv.get(this.prefixKey(key), "text");
+      }
+      async doSet(key, value, options) {
+        if (options?.ifNotExists || options?.ifExists) {
+          throw new StorageNotSupportedError(
+            "conditional set (ifNotExists/ifExists)",
+            this.backendName,
+            "Cloudflare KV has no compare-and-set; use a Durable Object for atomic conditional writes."
+          );
+        }
+        const putOptions = options?.ttlSeconds !== void 0 ? { expirationTtl: this.toExpirationTtl(options.ttlSeconds, key) } : void 0;
+        await this.kv.put(this.prefixKey(key), value, putOptions);
+      }
+      async delete(key) {
+        this.ensureConnected();
+        const existed = await this.exists(key);
+        await this.kv.delete(this.prefixKey(key));
+        return existed;
+      }
+      async exists(key) {
+        this.ensureConnected();
+        return await this.kv.get(this.prefixKey(key), "text") !== null;
+      }
+      // ── TTL ────────────────────────────────────────────────────────────────
+      async expire(key, ttlSeconds) {
+        this.ensureConnected();
+        const ttl = this.toExpirationTtl(ttlSeconds, key);
+        const value = await this.kv.get(this.prefixKey(key), "text");
+        if (value === null) return false;
+        await this.kv.put(this.prefixKey(key), value, { expirationTtl: ttl });
+        return true;
+      }
+      async ttl(_key) {
+        throw new StorageNotSupportedError(
+          "ttl",
+          this.backendName,
+          "Cloudflare KV does not expose a key's remaining TTL. Track expiry alongside the value if you need it."
+        );
+      }
+      // ── Enumeration ──────────────────────────────────────────────────────────
+      async keys(pattern = "*") {
+        this.ensureConnected();
+        const prefixedPattern = this.prefixKey(pattern);
+        const listPrefix = literalPrefix(prefixedPattern);
+        const out = [];
+        let cursor;
+        do {
+          const page = await this.kv.list({ prefix: listPrefix || void 0, cursor });
+          for (const { name } of page.keys) {
+            if (matchesPattern(name, prefixedPattern)) out.push(this.unprefixKey(name));
+          }
+          cursor = page.list_complete ? void 0 : page.cursor;
+        } while (cursor);
+        return out;
+      }
+      // ── Atomic (unsupported on KV) ───────────────────────────────────────────
+      async incr(key) {
+        return this.incrBy(key, 1);
+      }
+      async decr(key) {
+        return this.incrBy(key, -1);
+      }
+      async incrBy(_key, _amount) {
+        throw new StorageNotSupportedError(
+          "incr/decr/incrBy",
+          this.backendName,
+          "Cloudflare KV has no atomic increment (a get+put is racy under eventual consistency). Use a Durable Object for atomic counters."
+        );
+      }
+      // ── Pub/Sub (unsupported) ────────────────────────────────────────────────
+      getPubSubSuggestion() {
+        return "Cloudflare KV does not support pub/sub. Use a Durable Object (or Queues) for fan-out.";
+      }
+      // ── Helpers ──────────────────────────────────────────────────────────────
+      /** Validate + enforce KV's 60s minimum `expirationTtl`. */
+      toExpirationTtl(ttlSeconds, key) {
+        validateTTL(ttlSeconds);
+        if (ttlSeconds < CF_KV_MIN_TTL_SECONDS) {
+          throw new StorageOperationError(
+            "set",
+            key,
+            `cloudflare-kv: expirationTtl must be >= ${CF_KV_MIN_TTL_SECONDS}s (Cloudflare KV minimum); got ${ttlSeconds}s.`
+          );
+        }
+        return ttlSeconds;
+      }
+      prefixKey(key) {
+        return this.keyPrefix + key;
+      }
+      unprefixKey(key) {
+        return this.keyPrefix && key.startsWith(this.keyPrefix) ? key.slice(this.keyPrefix.length) : key;
+      }
+    };
+  }
+});
+
 // libs/utils/src/regex/safe-regex.ts
 import { analyzeForReDoS, REDOS_THRESHOLDS } from "@enclave-vm/ast";
 var DEFAULT_MAX_INPUT_LENGTH = 5e4;
@@ -4532,7 +4694,6 @@ function isKnownTarget(value) {
 }
 
 // libs/utils/src/env/provider.ts
-import * as fs from "node:fs";
 var cached2;
 function detectProvider() {
   if (cached2) return cached2;
@@ -4552,7 +4713,8 @@ function detectProviderUncached() {
   if (process.env["RENDER"]) return "render";
   if (process.env["RAILWAY_ENVIRONMENT"]) return "railway";
   try {
-    if (fs.existsSync("/.dockerenv")) return "docker";
+    const nodeFs = __require("node:fs");
+    if (nodeFs.existsSync("/.dockerenv")) return "docker";
   } catch {
   }
   return "bare";
@@ -4674,6 +4836,9 @@ var NamespacedStorageImpl = class _NamespacedStorageImpl {
     this.prefix = prefix;
     this.root = root;
   }
+  adapter;
+  prefix;
+  root;
   // ============================================
   // Key Prefixing Helpers
   // ============================================
@@ -4847,6 +5012,16 @@ async function createAdapter(type, config) {
       const { UpstashStorageAdapter: UpstashStorageAdapter2 } = await Promise.resolve().then(() => (init_upstash(), upstash_exports));
       return new UpstashStorageAdapter2(config.upstash);
     }
+    case "cloudflare-kv": {
+      if (!config.cloudflareKv) {
+        throw new StorageConfigError(
+          "cloudflare-kv",
+          "cloudflare-kv requires `cloudflareKv: { namespace }` (the KV binding can't be auto-detected)"
+        );
+      }
+      const { CloudflareKvStorageAdapter: CloudflareKvStorageAdapter2 } = await Promise.resolve().then(() => (init_cloudflare_kv(), cloudflare_kv_exports));
+      return new CloudflareKvStorageAdapter2(config.cloudflareKv);
+    }
     case "auto":
       throw new StorageConfigError("auto", "Auto type should be resolved before calling createAdapter");
     default:
@@ -5495,8 +5670,8 @@ function loadMachineIdSync() {
   if (!isDevPersistenceEnabled()) return null;
   const machineIdPath = resolveMachineIdPath();
   try {
-    const fs2 = __require("fs");
-    const content = fs2.readFileSync(machineIdPath, "utf8").trim();
+    const fs = __require("fs");
+    const content = fs.readFileSync(machineIdPath, "utf8").trim();
     if (/^[0-9a-f-]{32,36}$/i.test(content)) return content;
     console.warn(`[MachineId] Invalid format at ${machineIdPath}, will regenerate`);
     return null;
@@ -5507,7 +5682,7 @@ function loadMachineIdSync() {
     return null;
   }
 }
-function saveMachineIdAsync(machineId2) {
+function saveMachineIdAsync(machineId) {
   if (!isDevPersistenceEnabled()) return;
   const machineIdPath = resolveMachineIdPath();
   const path = __require("path");
@@ -5516,13 +5691,13 @@ function saveMachineIdAsync(machineId2) {
     try {
       const fsp = __require("fs").promises;
       await fsp.mkdir(dir, { recursive: true, mode: 448 });
-      await fsp.writeFile(machineIdPath, machineId2, { mode: 384 });
+      await fsp.writeFile(machineIdPath, machineId, { mode: 384 });
     } catch (error) {
       console.warn(`[MachineId] Failed to save to ${machineIdPath}: ${error.message}`);
     }
   })();
 }
-var machineId = (() => {
+function computeMachineId() {
   const envMachineId = getEnvDirect("MACHINE_ID");
   if (envMachineId) return envMachineId;
   const deploymentMode = getEnvDirect("FRONTMCP_DEPLOYMENT_MODE");
@@ -5542,10 +5717,15 @@ var machineId = (() => {
   const newId = randomUUID();
   saveMachineIdAsync(newId);
   return newId;
-})();
+}
+var cachedMachineId;
 var machineIdOverride;
 function getMachineId() {
-  return machineIdOverride ?? machineId;
+  if (machineIdOverride !== void 0) return machineIdOverride;
+  if (cachedMachineId === void 0) {
+    cachedMachineId = computeMachineId();
+  }
+  return cachedMachineId;
 }
 function setMachineIdOverride(id) {
   machineIdOverride = id;

package/index.js

@@ -5,8 +5,13 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -78,8 +83,8 @@ async function readFile(p, encoding = "utf8") {
   return fsp.readFile(p, encoding);
 }
 function readFileSync(p, encoding = "utf8") {
-  const fs2 = getFs();
-  return fs2.readFileSync(p, encoding);
+  const fs = getFs();
+  return fs.readFileSync(p, encoding);
 }
 async function readFileBuffer(p) {
   const fsp = getFsp();
@@ -94,8 +99,8 @@ async function mkdir(p, options) {
   await fsp.mkdir(p, options);
 }
 function ensureDirSync(p) {
-  const fs2 = getFs();
-  fs2.mkdirSync(p, { recursive: true });
+  const fs = getFs();
+  fs.mkdirSync(p, { recursive: true });
 }
 async function rename(oldPath, newPath) {
   const fsp = getFsp();
@@ -156,8 +161,8 @@ async function readdir(p) {
   return fsp.readdir(p);
 }
 function readdirSync(p) {
-  const fs2 = getFs();
-  return fs2.readdirSync(p);
+  const fs = getFs();
+  return fs.readdirSync(p);
 }
 async function rm(p, options) {
   const fsp = getFsp();
@@ -190,8 +195,8 @@ function runCmd(cmd, args, opts = {}) {
   });
 }
 function watchFile(p, onChange, options) {
-  const fs2 = getFs();
-  const watcher = fs2.watch(p, { persistent: false, recursive: options?.recursive === true }, (eventType, filename) => {
+  const fs = getFs();
+  const watcher = fs.watch(p, { persistent: false, recursive: options?.recursive === true }, (eventType, filename) => {
     onChange(eventType, filename);
   });
   return {
@@ -1019,6 +1024,7 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageConnectionError";
       }
+      backend;
     };
     StorageOperationError = class extends StorageError {
       constructor(operation, key, message, cause) {
@@ -1027,6 +1033,8 @@ var init_errors = __esm({
         this.key = key;
         this.name = "StorageOperationError";
       }
+      operation;
+      key;
     };
     StorageNotSupportedError = class extends StorageError {
       constructor(operation, backend, suggestion) {
@@ -1036,6 +1044,8 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageNotSupportedError";
       }
+      operation;
+      backend;
     };
     StorageConfigError = class extends StorageError {
       constructor(backend, message) {
@@ -1043,6 +1053,7 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageConfigError";
       }
+      backend;
     };
     StorageTTLError = class extends StorageError {
       constructor(ttl, message) {
@@ -1050,6 +1061,7 @@ var init_errors = __esm({
         this.ttl = ttl;
         this.name = "StorageTTLError";
       }
+      ttl;
     };
     StoragePatternError = class extends StorageError {
       constructor(pattern, message) {
@@ -1057,6 +1069,7 @@ var init_errors = __esm({
         this.pattern = pattern;
         this.name = "StoragePatternError";
       }
+      pattern;
     };
     StorageNotConnectedError = class extends StorageError {
       constructor(backend) {
@@ -1064,6 +1077,7 @@ var init_errors = __esm({
         this.backend = backend;
         this.name = "StorageNotConnectedError";
       }
+      backend;
     };
     EncryptedStorageError = class extends StorageError {
       constructor(message) {
@@ -3812,6 +3826,154 @@ var init_upstash = __esm({
   }
 });
 
+// libs/utils/src/storage/adapters/cloudflare-kv.ts
+var cloudflare_kv_exports = {};
+__export(cloudflare_kv_exports, {
+  CloudflareKvStorageAdapter: () => CloudflareKvStorageAdapter
+});
+function literalPrefix(pattern) {
+  const star = pattern.indexOf("*");
+  const q = pattern.indexOf("?");
+  const idx = star === -1 ? q : q === -1 ? star : Math.min(star, q);
+  return idx === -1 ? pattern : pattern.slice(0, idx);
+}
+var CF_KV_MIN_TTL_SECONDS, CloudflareKvStorageAdapter;
+var init_cloudflare_kv = __esm({
+  "libs/utils/src/storage/adapters/cloudflare-kv.ts"() {
+    "use strict";
+    init_errors();
+    init_pattern();
+    init_ttl();
+    init_base();
+    CF_KV_MIN_TTL_SECONDS = 60;
+    CloudflareKvStorageAdapter = class extends BaseStorageAdapter {
+      backendName = "cloudflare-kv";
+      kv;
+      keyPrefix;
+      constructor(options) {
+        super();
+        if (!options?.namespace) {
+          throw new Error("CloudflareKvStorageAdapter: a bound KV `namespace` is required (resolve it from the Worker `env`).");
+        }
+        this.kv = options.namespace;
+        this.keyPrefix = options.keyPrefix ?? "";
+      }
+      // ── Lifecycle ──────────────────────────────────────────────────────────
+      // A KV binding is always available; "connection" is just a readiness flag.
+      async connect() {
+        this.connected = true;
+      }
+      async disconnect() {
+        this.connected = false;
+      }
+      async ping() {
+        if (!this.connected) return false;
+        try {
+          await this.kv.list({ limit: 1 });
+          return true;
+        } catch {
+          return false;
+        }
+      }
+      // ── Core ───────────────────────────────────────────────────────────────
+      async get(key) {
+        this.ensureConnected();
+        return this.kv.get(this.prefixKey(key), "text");
+      }
+      async doSet(key, value, options) {
+        if (options?.ifNotExists || options?.ifExists) {
+          throw new StorageNotSupportedError(
+            "conditional set (ifNotExists/ifExists)",
+            this.backendName,
+            "Cloudflare KV has no compare-and-set; use a Durable Object for atomic conditional writes."
+          );
+        }
+        const putOptions = options?.ttlSeconds !== void 0 ? { expirationTtl: this.toExpirationTtl(options.ttlSeconds, key) } : void 0;
+        await this.kv.put(this.prefixKey(key), value, putOptions);
+      }
+      async delete(key) {
+        this.ensureConnected();
+        const existed = await this.exists(key);
+        await this.kv.delete(this.prefixKey(key));
+        return existed;
+      }
+      async exists(key) {
+        this.ensureConnected();
+        return await this.kv.get(this.prefixKey(key), "text") !== null;
+      }
+      // ── TTL ────────────────────────────────────────────────────────────────
+      async expire(key, ttlSeconds) {
+        this.ensureConnected();
+        const ttl = this.toExpirationTtl(ttlSeconds, key);
+        const value = await this.kv.get(this.prefixKey(key), "text");
+        if (value === null) return false;
+        await this.kv.put(this.prefixKey(key), value, { expirationTtl: ttl });
+        return true;
+      }
+      async ttl(_key) {
+        throw new StorageNotSupportedError(
+          "ttl",
+          this.backendName,
+          "Cloudflare KV does not expose a key's remaining TTL. Track expiry alongside the value if you need it."
+        );
+      }
+      // ── Enumeration ──────────────────────────────────────────────────────────
+      async keys(pattern = "*") {
+        this.ensureConnected();
+        const prefixedPattern = this.prefixKey(pattern);
+        const listPrefix = literalPrefix(prefixedPattern);
+        const out = [];
+        let cursor;
+        do {
+          const page = await this.kv.list({ prefix: listPrefix || void 0, cursor });
+          for (const { name } of page.keys) {
+            if (matchesPattern(name, prefixedPattern)) out.push(this.unprefixKey(name));
+          }
+          cursor = page.list_complete ? void 0 : page.cursor;
+        } while (cursor);
+        return out;
+      }
+      // ── Atomic (unsupported on KV) ───────────────────────────────────────────
+      async incr(key) {
+        return this.incrBy(key, 1);
+      }
+      async decr(key) {
+        return this.incrBy(key, -1);
+      }
+      async incrBy(_key, _amount) {
+        throw new StorageNotSupportedError(
+          "incr/decr/incrBy",
+          this.backendName,
+          "Cloudflare KV has no atomic increment (a get+put is racy under eventual consistency). Use a Durable Object for atomic counters."
+        );
+      }
+      // ── Pub/Sub (unsupported) ────────────────────────────────────────────────
+      getPubSubSuggestion() {
+        return "Cloudflare KV does not support pub/sub. Use a Durable Object (or Queues) for fan-out.";
+      }
+      // ── Helpers ──────────────────────────────────────────────────────────────
+      /** Validate + enforce KV's 60s minimum `expirationTtl`. */
+      toExpirationTtl(ttlSeconds, key) {
+        validateTTL(ttlSeconds);
+        if (ttlSeconds < CF_KV_MIN_TTL_SECONDS) {
+          throw new StorageOperationError(
+            "set",
+            key,
+            `cloudflare-kv: expirationTtl must be >= ${CF_KV_MIN_TTL_SECONDS}s (Cloudflare KV minimum); got ${ttlSeconds}s.`
+          );
+        }
+        return ttlSeconds;
+      }
+      prefixKey(key) {
+        return this.keyPrefix + key;
+      }
+      unprefixKey(key) {
+        return this.keyPrefix && key.startsWith(this.keyPrefix) ? key.slice(this.keyPrefix.length) : key;
+      }
+    };
+  }
+});
+
 // libs/utils/src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -4746,7 +4908,6 @@ function isKnownTarget(value) {
 }
 
 // libs/utils/src/env/provider.ts
-var fs = __toESM(require("node:fs"));
 var cached2;
 function detectProvider() {
   if (cached2) return cached2;
@@ -4766,7 +4927,8 @@ function detectProviderUncached() {
   if (process.env["RENDER"]) return "render";
   if (process.env["RAILWAY_ENVIRONMENT"]) return "railway";
   try {
-    if (fs.existsSync("/.dockerenv")) return "docker";
+    const nodeFs = require("node:fs");
+    if (nodeFs.existsSync("/.dockerenv")) return "docker";
   } catch {
   }
   return "bare";
@@ -4888,6 +5050,9 @@ var NamespacedStorageImpl = class _NamespacedStorageImpl {
     this.prefix = prefix;
     this.root = root;
   }
+  adapter;
+  prefix;
+  root;
   // ============================================
   // Key Prefixing Helpers
   // ============================================
@@ -5061,6 +5226,16 @@ async function createAdapter(type, config) {
       const { UpstashStorageAdapter: UpstashStorageAdapter2 } = await Promise.resolve().then(() => (init_upstash(), upstash_exports));
       return new UpstashStorageAdapter2(config.upstash);
     }
+    case "cloudflare-kv": {
+      if (!config.cloudflareKv) {
+        throw new StorageConfigError(
+          "cloudflare-kv",
+          "cloudflare-kv requires `cloudflareKv: { namespace }` (the KV binding can't be auto-detected)"
+        );
+      }
+      const { CloudflareKvStorageAdapter: CloudflareKvStorageAdapter2 } = await Promise.resolve().then(() => (init_cloudflare_kv(), cloudflare_kv_exports));
+      return new CloudflareKvStorageAdapter2(config.cloudflareKv);
+    }
     case "auto":
       throw new StorageConfigError("auto", "Auto type should be resolved before calling createAdapter");
     default:
@@ -5709,8 +5884,8 @@ function loadMachineIdSync() {
   if (!isDevPersistenceEnabled()) return null;
   const machineIdPath = resolveMachineIdPath();
   try {
-    const fs2 = require("fs");
-    const content = fs2.readFileSync(machineIdPath, "utf8").trim();
+    const fs = require("fs");
+    const content = fs.readFileSync(machineIdPath, "utf8").trim();
     if (/^[0-9a-f-]{32,36}$/i.test(content)) return content;
     console.warn(`[MachineId] Invalid format at ${machineIdPath}, will regenerate`);
     return null;
@@ -5721,7 +5896,7 @@ function loadMachineIdSync() {
     return null;
   }
 }
-function saveMachineIdAsync(machineId2) {
+function saveMachineIdAsync(machineId) {
   if (!isDevPersistenceEnabled()) return;
   const machineIdPath = resolveMachineIdPath();
   const path = require("path");
@@ -5730,13 +5905,13 @@ function saveMachineIdAsync(machineId2) {
     try {
       const fsp = require("fs").promises;
       await fsp.mkdir(dir, { recursive: true, mode: 448 });
-      await fsp.writeFile(machineIdPath, machineId2, { mode: 384 });
+      await fsp.writeFile(machineIdPath, machineId, { mode: 384 });
     } catch (error) {
       console.warn(`[MachineId] Failed to save to ${machineIdPath}: ${error.message}`);
     }
   })();
 }
-var machineId = (() => {
+function computeMachineId() {
   const envMachineId = getEnvDirect("MACHINE_ID");
   if (envMachineId) return envMachineId;
   const deploymentMode = getEnvDirect("FRONTMCP_DEPLOYMENT_MODE");
@@ -5756,10 +5931,15 @@ var machineId = (() => {
   const newId = randomUUID();
   saveMachineIdAsync(newId);
   return newId;
-})();
+}
+var cachedMachineId;
 var machineIdOverride;
 function getMachineId() {
-  return machineIdOverride ?? machineId;
+  if (machineIdOverride !== void 0) return machineIdOverride;
+  if (cachedMachineId === void 0) {
+    cachedMachineId = computeMachineId();
+  }
+  return cachedMachineId;
 }
 function setMachineIdOverride(id) {
   machineIdOverride = id;

package/machine-id/machine-id.d.ts

@@ -22,7 +22,8 @@
  */
 /**
  * Get the current machine ID.
- * Returns the override (if set via `setMachineIdOverride`) or the computed value.
+ * Returns the override (if set via `setMachineIdOverride`) or the lazily
+ * computed-and-memoized value.
  */
 export declare function getMachineId(): string;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.4.0",
+  "version": "1.5.0-rc.1",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -27,14 +27,14 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@noble/hashes": "^2.0.1",
+    "@enclave-vm/ast": "^2.14.1",
     "@noble/ciphers": "^2.1.1",
-    "@enclave-vm/ast": "^2.13.0"
+    "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
+    "@frontmcp/lazy-zod": "1.5.0-rc.1",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
-    "ioredis": "^5.0.0",
-    "@frontmcp/lazy-zod": "1.4.0"
+    "ioredis": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@vercel/kv": {

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

@@ -0,0 +1,26 @@
+import type { CloudflareKvAdapterOptions, SetOptions } from '../types';
+import { BaseStorageAdapter } from './base';
+export declare class CloudflareKvStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "cloudflare-kv";
+    private readonly kv;
+    private readonly keyPrefix;
+    constructor(options: CloudflareKvAdapterOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(_key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(_key: string, _amount: number): Promise<number>;
+    protected getPubSubSuggestion(): string;
+    /** Validate + enforce KV's 60s minimum `expirationTtl`. */
+    private toExpirationTtl;
+    private prefixKey;
+    private unprefixKey;
+}

package/storage/adapters/index.d.ts

@@ -8,6 +8,7 @@ export { MemoryStorageAdapter } from './memory';
 export { RedisStorageAdapter } from './redis';
 export { VercelKvStorageAdapter } from './vercel-kv';
 export { UpstashStorageAdapter } from './upstash';
+export { CloudflareKvStorageAdapter } from './cloudflare-kv';
 export { FileSystemStorageAdapter } from './filesystem';
 export type { FileSystemAdapterOptions } from './filesystem';
 export { LocalStorageAdapter } from './localstorage';

package/storage/types.d.ts

@@ -378,10 +378,44 @@ export interface UpstashAdapterOptions {
      */
     enablePubSub?: boolean;
 }
+/**
+ * Minimal structural subset of the Cloudflare `KVNamespace` binding the
+ * `cloudflare-kv` adapter uses. Declared here rather than importing
+ * `@cloudflare/workers-types` so any runtime exposing this shape works.
+ */
+export interface CloudflareKvNamespace {
+    get(key: string, type?: 'text'): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: {
+            name: string;
+        }[];
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+/**
+ * Cloudflare Workers KV adapter options (when type='cloudflare-kv'). The bound
+ * KV namespace is supplied explicitly (resolved from the Worker `env`), since
+ * bindings don't exist as env vars and can't be auto-detected.
+ */
+export interface CloudflareKvAdapterOptions {
+    /** The bound KV namespace. */
+    namespace: CloudflareKvNamespace;
+    /** Key prefix applied to all keys. @default '' */
+    keyPrefix?: string;
+}
 /**
  * Storage backend type.
  */
-export type StorageType = 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'auto';
+export type StorageType = 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'cloudflare-kv' | 'auto';
 /**
  * Configuration for createStorage factory.
  */
@@ -408,6 +442,10 @@ export interface StorageConfig {
      * Vercel KV adapter options (when type='vercel-kv').
      */
     vercelKv?: VercelKvAdapterOptions;
+    /**
+     * Cloudflare KV adapter options (when type='cloudflare-kv').
+     */
+    cloudflareKv?: CloudflareKvAdapterOptions;
     /**
      * Upstash adapter options (when type='upstash').
      */