@frontmcp/utils 1.0.0-beta.9 → 1.0.0-rc.1

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

@@ -0,0 +1,29 @@
+/**
+ * Runtime context detection and entry availability matching (Browser version).
+ *
+ * Returns safe defaults for browser environments.
+ * The isEntryAvailable matcher works identically to the Node version.
+ */
+import { z } from 'zod';
+export interface RuntimeContext {
+    platform: string;
+    runtime: string;
+    deployment: string;
+    env: string;
+}
+export interface EntryAvailability {
+    platform?: string[];
+    runtime?: string[];
+    deployment?: string[];
+    env?: string[];
+}
+export declare const entryAvailabilitySchema: z.ZodObject<{
+    platform: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    runtime: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deployment: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare function isEntryAvailable(availability: EntryAvailability | undefined, ctx: RuntimeContext): boolean;
+export declare function detectRuntimeContext(): RuntimeContext;
+export declare function getRuntimeContext(): RuntimeContext;
+export declare function resetRuntimeContext(): void;

package/env/index.d.ts

@@ -1 +1,3 @@
 export { getEnv, getCwd, isProduction, isDevelopment, getEnvFlag, isDebug, setEnv, isEdgeRuntime, isServerless, supportsAnsi, } from '#env';
+export { getRuntimeContext, resetRuntimeContext, detectRuntimeContext, isEntryAvailable, entryAvailabilitySchema, } from '#runtime-context';
+export type { RuntimeContext, EntryAvailability } from '#runtime-context';

package/env/runtime-context.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Runtime context detection and entry availability matching (Node.js version).
+ *
+ * Provides:
+ * - `RuntimeContext` — snapshot of the current platform, runtime, deployment, and env
+ * - `EntryAvailability` — declarative constraint for when an entry is available
+ * - `getRuntimeContext()` — lazy singleton returning the detected context
+ * - `isEntryAvailable()` — pure matcher: does the constraint match the context?
+ */
+import { z } from 'zod';
+/**
+ * Snapshot of the current runtime environment.
+ * Detected once and cached for the lifetime of the process.
+ */
+export interface RuntimeContext {
+    /** OS platform: 'darwin', 'linux', 'win32', 'freebsd', etc. */
+    platform: string;
+    /** JavaScript runtime: 'node', 'bun', 'deno', 'edge', 'browser' */
+    runtime: string;
+    /** Deployment mode: 'serverless' or 'standalone' */
+    deployment: string;
+    /** NODE_ENV value: 'production', 'development', 'test', etc. */
+    env: string;
+}
+/**
+ * Declarative constraint for entry availability.
+ *
+ * Semantics:
+ * - AND across fields: all specified fields must match
+ * - OR within arrays: at least one value in the array must match
+ * - Omitted field: unconstrained (matches any value)
+ * - Empty array: matches nothing (entry is never available)
+ * - undefined/empty object: always available
+ *
+ * @example macOS only
+ * ```typescript
+ * { platform: ['darwin'] }
+ * ```
+ *
+ * @example Node.js or Bun, production only
+ * ```typescript
+ * { runtime: ['node', 'bun'], env: ['production'] }
+ * ```
+ */
+export interface EntryAvailability {
+    /** OS platform constraint: 'darwin', 'linux', 'win32', etc. */
+    platform?: string[];
+    /** Runtime constraint: 'node', 'browser', 'edge', 'bun', 'deno' */
+    runtime?: string[];
+    /** Deployment constraint: 'serverless', 'standalone' */
+    deployment?: string[];
+    /** Environment constraint: 'production', 'development', 'test', etc. */
+    env?: string[];
+}
+/**
+ * Zod schema for validating EntryAvailability in metadata.
+ */
+export declare const entryAvailabilitySchema: z.ZodObject<{
+    platform: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    runtime: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deployment: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * Check if an entry is available in the given runtime context.
+ *
+ * @param availability - The constraint (undefined = always available)
+ * @param ctx - The current runtime context
+ * @returns true if the entry should be available
+ */
+export declare function isEntryAvailable(availability: EntryAvailability | undefined, ctx: RuntimeContext): boolean;
+/**
+ * Detect the current runtime context from the environment.
+ */
+export declare function detectRuntimeContext(): RuntimeContext;
+/**
+ * Get the current runtime context (lazy singleton).
+ * The context is detected on first call and cached for the process lifetime.
+ */
+export declare function getRuntimeContext(): RuntimeContext;
+/**
+ * Reset the cached runtime context. For testing only.
+ */
+export declare function resetRuntimeContext(): void;

package/esm/index.mjs

@@ -554,9 +554,9 @@ function createSecretData(options) {
 }
 async function getOrCreateSecret(options) {
   const cacheKey = resolveSecretPath(options);
-  const cached = secretCache.get(cacheKey);
-  if (cached) {
-    return cached;
+  const cached2 = secretCache.get(cacheKey);
+  if (cached2) {
+    return cached2;
   }
   const existing = generationPromises.get(cacheKey);
   if (existing) {
@@ -793,8 +793,8 @@ var init_key_persistence = __esm({
        */
       async get(kid) {
         if (this.enableCache) {
-          const cached = this.cache.get(kid);
-          if (cached) return cached;
+          const cached2 = this.cache.get(kid);
+          if (cached2) return cached2;
         }
         const raw = await this.storage.get(kid);
         if (!raw) return null;
@@ -4277,11 +4277,56 @@ import {
   getEnvFlag,
   isDebug,
   setEnv,
-  isEdgeRuntime,
-  isServerless,
+  isEdgeRuntime as isEdgeRuntime2,
+  isServerless as isServerless2,
   supportsAnsi
 } from "#env";
 
+// libs/utils/src/env/runtime-context.ts
+import { z as z3 } from "zod";
+import { isEdgeRuntime, isServerless } from "#env";
+var entryAvailabilitySchema = z3.object({
+  platform: z3.array(z3.string().min(1)).optional(),
+  runtime: z3.array(z3.string().min(1)).optional(),
+  deployment: z3.array(z3.string().min(1)).optional(),
+  env: z3.array(z3.string().min(1)).optional()
+}).strict();
+function isEntryAvailable(availability, ctx) {
+  if (!availability) return true;
+  const fields = ["platform", "runtime", "deployment", "env"];
+  for (const field of fields) {
+    const allowed = availability[field];
+    if (allowed === void 0) continue;
+    if (allowed.length === 0) return false;
+    if (!allowed.includes(ctx[field])) return false;
+  }
+  return true;
+}
+function detectRuntime() {
+  if (typeof globalThis !== "undefined" && "Bun" in globalThis) return "bun";
+  if (typeof globalThis !== "undefined" && "Deno" in globalThis) return "deno";
+  if (isEdgeRuntime()) return "edge";
+  return "node";
+}
+function detectRuntimeContext() {
+  return {
+    platform: process.platform,
+    runtime: detectRuntime(),
+    deployment: isServerless() ? "serverless" : "standalone",
+    env: process.env["NODE_ENV"] || "development"
+  };
+}
+var cached;
+function getRuntimeContext() {
+  if (!cached) {
+    cached = detectRuntimeContext();
+  }
+  return cached;
+}
+function resetRuntimeContext() {
+  cached = void 0;
+}
+
 // libs/utils/src/storage/factory.ts
 init_errors();
 
@@ -5156,12 +5201,14 @@ export {
   deleteSecret,
   deserializeAndDecrypt,
   deserializeBlob,
+  detectRuntimeContext,
   dirname,
   encryptAesGcm,
   encryptAndSerialize,
   encryptValue,
   ensureDir,
   ensureMaxLen,
+  entryAvailabilitySchema,
   escapeGlob,
   escapeHtml,
   escapeHtmlAttr,
@@ -5185,6 +5232,7 @@ export {
   getEnv2 as getEnv,
   getEnvFlag,
   getOrCreateSecret,
+  getRuntimeContext,
   globToRegex,
   hasTemplatePlaceholders,
   hkdfSha256,
@@ -5196,7 +5244,8 @@ export {
   isDebug,
   isDevelopment,
   isDirEmpty,
-  isEdgeRuntime,
+  isEdgeRuntime2 as isEdgeRuntime,
+  isEntryAvailable,
   isExpired,
   isInputLengthSafe,
   isNode,
@@ -5206,7 +5255,7 @@ export {
   isSecretCached,
   isSecretKeyData,
   isSecretPersistenceEnabled,
-  isServerless,
+  isServerless2 as isServerless,
   isSignedData,
   isUriTemplate,
   isValidCodeChallenge,
@@ -5236,6 +5285,7 @@ export {
   readJSON,
   readdir,
   rename,
+  resetRuntimeContext,
   resolveSecretPath,
   rm,
   rsaVerify2 as rsaVerify,

package/index.d.ts

@@ -19,7 +19,8 @@ export { getCrypto, rsaVerify, jwtAlgToNodeAlg, isRsaPssAlg, randomUUID, randomB
 export type { CryptoProvider, EncBlob, EncryptedBlob } from './crypto';
 export { AsyncLocalStorage } from './async-context';
 export { EventEmitter } from './event-emitter';
-export { getEnv, getCwd, isProduction, isDevelopment, getEnvFlag, isDebug, setEnv, isEdgeRuntime, isServerless, supportsAnsi, } from './env';
+export { getEnv, getCwd, isProduction, isDevelopment, getEnvFlag, isDebug, setEnv, isEdgeRuntime, isServerless, supportsAnsi, getRuntimeContext, resetRuntimeContext, detectRuntimeContext, isEntryAvailable, 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, 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, } from './storage';
 export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, } from './storage';

package/index.js

@@ -558,9 +558,9 @@ function createSecretData(options) {
 }
 async function getOrCreateSecret(options) {
   const cacheKey = resolveSecretPath(options);
-  const cached = secretCache.get(cacheKey);
-  if (cached) {
-    return cached;
+  const cached2 = secretCache.get(cacheKey);
+  if (cached2) {
+    return cached2;
   }
   const existing = generationPromises.get(cacheKey);
   if (existing) {
@@ -798,8 +798,8 @@ var init_key_persistence = __esm({
        */
       async get(kid) {
         if (this.enableCache) {
-          const cached = this.cache.get(kid);
-          if (cached) return cached;
+          const cached2 = this.cache.get(kid);
+          if (cached2) return cached2;
         }
         const raw = await this.storage.get(kid);
         if (!raw) return null;
@@ -3783,12 +3783,14 @@ __export(index_exports, {
   deleteSecret: () => deleteSecret,
   deserializeAndDecrypt: () => deserializeAndDecrypt,
   deserializeBlob: () => deserializeBlob,
+  detectRuntimeContext: () => detectRuntimeContext,
   dirname: () => import_path.dirname,
   encryptAesGcm: () => encryptAesGcm,
   encryptAndSerialize: () => encryptAndSerialize,
   encryptValue: () => encryptValue,
   ensureDir: () => ensureDir,
   ensureMaxLen: () => ensureMaxLen,
+  entryAvailabilitySchema: () => entryAvailabilitySchema,
   escapeGlob: () => escapeGlob,
   escapeHtml: () => escapeHtml,
   escapeHtmlAttr: () => escapeHtmlAttr,
@@ -3807,11 +3809,12 @@ __export(index_exports, {
   generatePkcePair: () => generatePkcePair,
   generateSecret: () => generateSecret,
   getCrypto: () => getCrypto,
-  getCwd: () => import_env2.getCwd,
+  getCwd: () => import_env3.getCwd,
   getDetectedStorageType: () => getDetectedStorageType,
-  getEnv: () => import_env2.getEnv,
-  getEnvFlag: () => import_env2.getEnvFlag,
+  getEnv: () => import_env3.getEnv,
+  getEnvFlag: () => import_env3.getEnvFlag,
   getOrCreateSecret: () => getOrCreateSecret,
+  getRuntimeContext: () => getRuntimeContext,
   globToRegex: () => globToRegex,
   hasTemplatePlaceholders: () => hasTemplatePlaceholders,
   hkdfSha256: () => hkdfSha256,
@@ -3820,20 +3823,21 @@ __export(index_exports, {
   inferMimeType: () => inferMimeType,
   isAsymmetricKeyData: () => isAsymmetricKeyData,
   isBrowser: () => isBrowser,
-  isDebug: () => import_env2.isDebug,
-  isDevelopment: () => import_env2.isDevelopment,
+  isDebug: () => import_env3.isDebug,
+  isDevelopment: () => import_env3.isDevelopment,
   isDirEmpty: () => isDirEmpty,
-  isEdgeRuntime: () => import_env2.isEdgeRuntime,
+  isEdgeRuntime: () => import_env3.isEdgeRuntime,
+  isEntryAvailable: () => isEntryAvailable,
   isExpired: () => isExpired,
   isInputLengthSafe: () => isInputLengthSafe,
   isNode: () => isNode,
   isPatternSafe: () => isPatternSafe,
-  isProduction: () => import_env2.isProduction,
+  isProduction: () => import_env3.isProduction,
   isRsaPssAlg: () => isRsaPssAlg,
   isSecretCached: () => isSecretCached,
   isSecretKeyData: () => isSecretKeyData,
   isSecretPersistenceEnabled: () => isSecretPersistenceEnabled,
-  isServerless: () => import_env2.isServerless,
+  isServerless: () => import_env3.isServerless,
   isSignedData: () => isSignedData,
   isUriTemplate: () => isUriTemplate,
   isValidCodeChallenge: () => isValidCodeChallenge,
@@ -3863,6 +3867,7 @@ __export(index_exports, {
   readJSON: () => readJSON,
   readdir: () => readdir,
   rename: () => rename,
+  resetRuntimeContext: () => resetRuntimeContext,
   resolveSecretPath: () => resolveSecretPath,
   rm: () => rm,
   rsaVerify: () => rsaVerify2,
@@ -3879,7 +3884,7 @@ __export(index_exports, {
   secretKeyDataSchema: () => secretKeyDataSchema,
   sepFor: () => sepFor,
   serializeBlob: () => serializeBlob,
-  setEnv: () => import_env2.setEnv,
+  setEnv: () => import_env3.setEnv,
   sha256: () => sha256,
   sha256Base64url: () => sha256Base64url,
   sha256Hex: () => sha256Hex,
@@ -3887,7 +3892,7 @@ __export(index_exports, {
   signData: () => signData,
   splitWords: () => splitWords,
   stat: () => stat,
-  supportsAnsi: () => import_env2.supportsAnsi,
+  supportsAnsi: () => import_env3.supportsAnsi,
   timingSafeEqual: () => timingSafeEqual,
   toCase: () => toCase,
   trimBoth: () => trimBoth,
@@ -4469,7 +4474,52 @@ var import_async_context = require("#async-context");
 var import_event_emitter2 = require("#event-emitter");
 
 // libs/utils/src/env/index.ts
+var import_env3 = require("#env");
+
+// libs/utils/src/env/runtime-context.ts
+var import_zod3 = require("zod");
 var import_env2 = require("#env");
+var entryAvailabilitySchema = import_zod3.z.object({
+  platform: import_zod3.z.array(import_zod3.z.string().min(1)).optional(),
+  runtime: import_zod3.z.array(import_zod3.z.string().min(1)).optional(),
+  deployment: import_zod3.z.array(import_zod3.z.string().min(1)).optional(),
+  env: import_zod3.z.array(import_zod3.z.string().min(1)).optional()
+}).strict();
+function isEntryAvailable(availability, ctx) {
+  if (!availability) return true;
+  const fields = ["platform", "runtime", "deployment", "env"];
+  for (const field of fields) {
+    const allowed = availability[field];
+    if (allowed === void 0) continue;
+    if (allowed.length === 0) return false;
+    if (!allowed.includes(ctx[field])) return false;
+  }
+  return true;
+}
+function detectRuntime() {
+  if (typeof globalThis !== "undefined" && "Bun" in globalThis) return "bun";
+  if (typeof globalThis !== "undefined" && "Deno" in globalThis) return "deno";
+  if ((0, import_env2.isEdgeRuntime)()) return "edge";
+  return "node";
+}
+function detectRuntimeContext() {
+  return {
+    platform: process.platform,
+    runtime: detectRuntime(),
+    deployment: (0, import_env2.isServerless)() ? "serverless" : "standalone",
+    env: process.env["NODE_ENV"] || "development"
+  };
+}
+var cached;
+function getRuntimeContext() {
+  if (!cached) {
+    cached = detectRuntimeContext();
+  }
+  return cached;
+}
+function resetRuntimeContext() {
+  cached = void 0;
+}
 
 // libs/utils/src/storage/factory.ts
 init_errors();
@@ -4631,15 +4681,15 @@ function createNamespacedStorage(adapter, prefix) {
 
 // libs/utils/src/storage/factory.ts
 init_memory();
-var import_env3 = require("#env");
+var import_env4 = require("#env");
 function detectStorageType() {
-  if ((0, import_env3.getEnv)("UPSTASH_REDIS_REST_URL") && (0, import_env3.getEnv)("UPSTASH_REDIS_REST_TOKEN")) {
+  if ((0, import_env4.getEnv)("UPSTASH_REDIS_REST_URL") && (0, import_env4.getEnv)("UPSTASH_REDIS_REST_TOKEN")) {
     return "upstash";
   }
-  if ((0, import_env3.getEnv)("KV_REST_API_URL") && (0, import_env3.getEnv)("KV_REST_API_TOKEN")) {
+  if ((0, import_env4.getEnv)("KV_REST_API_URL") && (0, import_env4.getEnv)("KV_REST_API_TOKEN")) {
     return "vercel-kv";
   }
-  if ((0, import_env3.getEnv)("REDIS_URL") || (0, import_env3.getEnv)("REDIS_HOST")) {
+  if ((0, import_env4.getEnv)("REDIS_URL") || (0, import_env4.getEnv)("REDIS_HOST")) {
     return "redis";
   }
   return "memory";
@@ -4669,10 +4719,10 @@ async function createAdapter(type, config) {
 }
 async function createStorage(config = {}) {
   let type = config.type ?? "auto";
-  const fallback = config.fallback ?? ((0, import_env3.isProduction)() ? "error" : "memory");
+  const fallback = config.fallback ?? ((0, import_env4.isProduction)() ? "error" : "memory");
   if (type === "auto") {
     type = detectStorageType();
-    if (type === "memory" && (0, import_env3.isProduction)()) {
+    if (type === "memory" && (0, import_env4.isProduction)()) {
       console.warn(
         "[storage] Warning: No distributed storage backend detected in production. Using in-memory storage. Set REDIS_URL, UPSTASH_REDIS_REST_URL, or KV_REST_API_URL."
       );
@@ -5346,12 +5396,14 @@ async function processVercel(info, callTool) {
   deleteSecret,
   deserializeAndDecrypt,
   deserializeBlob,
+  detectRuntimeContext,
   dirname,
   encryptAesGcm,
   encryptAndSerialize,
   encryptValue,
   ensureDir,
   ensureMaxLen,
+  entryAvailabilitySchema,
   escapeGlob,
   escapeHtml,
   escapeHtmlAttr,
@@ -5375,6 +5427,7 @@ async function processVercel(info, callTool) {
   getEnv,
   getEnvFlag,
   getOrCreateSecret,
+  getRuntimeContext,
   globToRegex,
   hasTemplatePlaceholders,
   hkdfSha256,
@@ -5387,6 +5440,7 @@ async function processVercel(info, callTool) {
   isDevelopment,
   isDirEmpty,
   isEdgeRuntime,
+  isEntryAvailable,
   isExpired,
   isInputLengthSafe,
   isNode,
@@ -5426,6 +5480,7 @@ async function processVercel(info, callTool) {
   readJSON,
   readdir,
   rename,
+  resetRuntimeContext,
   resolveSecretPath,
   rm,
   rsaVerify,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.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",
@@ -24,7 +24,7 @@
   },
   "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/utils/README.md",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "dependencies": {
     "@noble/hashes": "^2.0.1",
@@ -61,6 +61,10 @@
       "browser": "./env/browser-env.js",
       "default": "./env/node-env.js"
     },
+    "#runtime-context": {
+      "browser": "./env/browser-runtime-context.js",
+      "default": "./env/runtime-context.js"
+    },
     "#path": {
       "browser": "./path/browser-path.js",
       "default": "./path/node-path.js"