@frontmcp/utils 1.9.3 → 1.9.5

package/class-brand/class-brand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Class identity shared by every copy of a package loaded in one process.
+ *
+ * A process can hold two copies of a FrontMCP package: in an ES-module project `@frontmcp/sdk`'s ESM
+ * build loads `@frontmcp/observability` with `require()`, which resolves observability's CommonJS
+ * build, which in turn loads the CommonJS builds of the SDK and of its dependencies. Each copy has its
+ * own classes, so a plain `instanceof` in one copy does not recognise an instance made by the other:
+ * an error the client was answered with as a `PublicMcpError` was recorded as an internal error with
+ * a new id (#802).
+ *
+ * A branded class answers `instanceof` for its own instances as usual, and also for an instance of
+ * the class with the same brand from another copy. The brand is an own property of the class, so a
+ * subclass is recognised only through a brand of its own: an unbranded subclass keeps the plain
+ * check, and never matches a different subclass that happens to share a branded parent.
+ *
+ * @example
+ * ```ts
+ * export class GuardError extends Error {
+ *   static override [Symbol.hasInstance](value: unknown): boolean {
+ *     return isBrandedInstance(this, value);
+ *   }
+ * }
+ * brandClass(GuardError, '@frontmcp/guard:GuardError');
+ * ```
+ */
+/**
+ * Give `klass` a process-wide brand. The same class in another copy of its package carries the same
+ * brand, so each recognises the other's instances through {@link isBrandedInstance}. Namespace the
+ * brand with the package name (`'@frontmcp/sdk:McpError'`).
+ */
+export declare function brandClass(klass: object, brand: string): void;
+/**
+ * `value instanceof klass`, also true when `value` is an instance of the class that carries `klass`'s
+ * own brand in another copy of the package. Meant as the `static [Symbol.hasInstance]` of a branded
+ * class (subclasses inherit it, and match through their own brand or the plain check).
+ */
+export declare function isBrandedInstance(klass: object, value: unknown): boolean;

package/class-brand/index.d.ts

@@ -0,0 +1 @@
+export { brandClass, isBrandedInstance } from './class-brand';

package/esm/index.mjs

@@ -117,6 +117,9 @@ async function fileExists(p) {
     return false;
   }
 }
+function fileExistsSync(p) {
+  return getFs().existsSync(p);
+}
 async function readJSON(jsonPath) {
   try {
     const fsp = getFsp();
@@ -4883,6 +4886,30 @@ function safeJsonForScript(value) {
   }
 }
 
+// libs/utils/src/class-brand/class-brand.ts
+var CLASS_BRAND = /* @__PURE__ */ Symbol.for("@frontmcp/class-brand");
+var ordinaryHasInstance = Function.prototype[Symbol.hasInstance];
+function ownBrandOf(klass) {
+  if (typeof klass !== "function" || !Object.prototype.hasOwnProperty.call(klass, CLASS_BRAND)) return void 0;
+  return klass[CLASS_BRAND];
+}
+function classOfPrototype(proto) {
+  return Object.getOwnPropertyDescriptor(proto, "constructor")?.value;
+}
+function brandClass(klass, brand) {
+  Object.defineProperty(klass, CLASS_BRAND, { value: brand, enumerable: false, writable: false, configurable: false });
+}
+function isBrandedInstance(klass, value) {
+  if (ordinaryHasInstance.call(klass, value)) return true;
+  if (typeof value !== "object" || value === null) return false;
+  const brand = ownBrandOf(klass);
+  if (brand === void 0) return false;
+  for (let proto = Object.getPrototypeOf(value); proto !== null; proto = Object.getPrototypeOf(proto)) {
+    if (ownBrandOf(classOfPrototype(proto)) === brand) return true;
+  }
+  return false;
+}
+
 // libs/utils/src/serialization/serialization.ts
 function safeStringify(value, space) {
   const seen = /* @__PURE__ */ new WeakSet();
@@ -4942,7 +4969,10 @@ import {
 } from "#runtime-context";
 
 // libs/utils/src/storage/factory.ts
+init_memory();
 init_errors();
+import { getEnv as getEnv3, isProduction as isProduction2 } from "#env";
+import { getRuntimeContext as getRuntimeContext2 } from "#runtime-context";
 
 // libs/utils/src/storage/namespace.ts
 init_errors();
@@ -5110,8 +5140,14 @@ function createNamespacedStorage(adapter, prefix) {
 }
 
 // libs/utils/src/storage/factory.ts
-init_memory();
-import { getEnv as getEnv3, isProduction as isProduction2 } from "#env";
+var noDistributedStorageWarned = false;
+function warnNoDistributedStorage() {
+  if (noDistributedStorageWarned || getRuntimeContext2().runtime === "browser") return;
+  noDistributedStorageWarned = true;
+  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."
+  );
+}
 function detectStorageType() {
   if (getEnv3("UPSTASH_REDIS_REST_URL") && getEnv3("UPSTASH_REDIS_REST_TOKEN")) {
     return "upstash";
@@ -5162,11 +5198,7 @@ async function createStorage(config = {}) {
   const fallback = config.fallback ?? (isProduction2() ? "error" : "memory");
   if (type === "auto") {
     type = detectStorageType();
-    if (type === "memory" && isProduction2()) {
-      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."
-      );
-    }
+    if (type === "memory" && isProduction2()) warnNoDistributedStorage();
   }
   let adapter;
   try {
@@ -5828,6 +5860,14 @@ function saveMachineIdAsync(machineId) {
     }
   })();
 }
+function getHostname() {
+  if (!isNode()) return void 0;
+  try {
+    return __require("os").hostname();
+  } catch {
+    return void 0;
+  }
+}
 function computeMachineId() {
   const envMachineId = getEnvDirect("MACHINE_ID");
   if (envMachineId) return envMachineId;
@@ -5907,6 +5947,7 @@ export {
   base64urlDecode,
   base64urlEncode,
   basename,
+  brandClass,
   buildPrefix,
   buildSetCookie,
   bytesToHex,
@@ -5957,6 +5998,7 @@ export {
   extractTemplateParams,
   extractUriScheme,
   fileExists,
+  fileExistsSync,
   findNonFiniteNumber,
   generateCodeChallenge,
   generateCodeVerifier,
@@ -5970,6 +6012,7 @@ export {
   getDetectedStorageType,
   getEnv2 as getEnv,
   getEnvFlag,
+  getHostname,
   getMachineId,
   getNodeEnv,
   getOrCreateSecret,
@@ -5983,6 +6026,7 @@ export {
   inferMimeType,
   isAbsolute,
   isAsymmetricKeyData,
+  isBrandedInstance,
   isBrowser,
   isDebug,
   isDevelopment,

package/fs/fs.d.ts

@@ -137,6 +137,21 @@ export declare function unlink(p: string): Promise<void>;
  * await fileExists('/path/to/file.txt') // true or false
  */
 export declare function fileExists(p: string): Promise<boolean>;
+/**
+ * Check whether a file or directory exists, synchronously.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * Use this only where async is not possible (e.g. resolving a command line
+ * before a synchronous `spawn`). Prefer {@link fileExists} otherwise.
+ *
+ * @param p - Path to check
+ * @returns true if the path exists, false otherwise
+ *
+ * @example
+ * fileExistsSync('/path/to/file.txt') // true or false
+ */
+export declare function fileExistsSync(p: string): boolean;
 /**
  * Read and parse a JSON file.
  *
@@ -239,13 +254,16 @@ export declare function copyFile(src: string, dest: string): Promise<void>;
  *
  * @param src - Source path
  * @param dest - Destination path
- * @param options - Copy options
+ * @param options - Copy options; `dereference` copies the files symlinks point to instead of the links,
+ *   and `filter` returns false for a path to leave it (and, for a folder, its contents) out
  *
  * @example
  * await cp('/path/to/src', '/path/to/dest', { recursive: true });
  */
 export declare function cp(src: string, dest: string, options?: {
     recursive?: boolean;
+    dereference?: boolean;
+    filter?: (source: string, destination: string) => boolean | Promise<boolean>;
 }): Promise<void>;
 /**
  * List directory contents.
@@ -343,6 +361,11 @@ export declare function access(p: string, mode?: number): Promise<void>;
 export declare function runCmd(cmd: string, args: string[], opts?: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Pass `args` to the child unquoted (Windows only). Set it when the arguments
+     * are already quoted for `cmd.exe /d /s /c`; ignored on other platforms.
+     */
+    windowsVerbatimArguments?: boolean;
 }): Promise<void>;
 /**
  * Handle returned by {@link watchFile}. `close()` stops the watch and is safe

package/fs/index.d.ts

@@ -1,2 +1,2 @@
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
+export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, fileExistsSync, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
 export type { FileWatcherHandle, SymlinkType } from './fs';

package/index.d.ts

@@ -15,9 +15,10 @@ export { validateBaseUrl, buildSetCookie, parseCookies, getCookie, isLocalhost,
 export type { CookieOptions, SecureDetectionRequest } from './http';
 export { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, parseIpv4, isRedirectResponse } from './net';
 export type { IpAddressClassification, IpAddressRange, SpecialPurposeIpRange, RedirectCandidate } from './net';
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
+export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, fileExistsSync, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
 export type { FileWatcherHandle } from './fs';
 export { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from './escape';
+export { brandClass, isBrandedInstance } from './class-brand';
 export { safeStringify } from './serialization';
 export { getCrypto, rsaVerify, rsaVerifySync, pemToPublicJwk, generateRsaKeyPair, rsaSignBase64Url, type RsaJwk, type RsaKeyPair, jwtAlgToNodeAlg, isRsaPssAlg, randomUUID, randomBytes, sha256, sha256Hex, sha256Base64url, hmacSha256, hkdfSha256, encryptAesGcm, decryptAesGcm, timingSafeEqual, bytesToHex, base64urlEncode, base64urlDecode, base64Encode, base64Decode, isNode, isBrowser, assertNode, EncryptedBlobError, encryptValue, decryptValue, tryDecryptValue, serializeBlob, deserializeBlob, tryDeserializeBlob, isValidEncryptedBlob, encryptAndSerialize, deserializeAndDecrypt, tryDeserializeAndDecrypt, generateCodeVerifier, generateCodeChallenge, verifyCodeChallenge, generatePkcePair, isValidCodeVerifier, isValidCodeChallenge, MIN_CODE_VERIFIER_LENGTH, MAX_CODE_VERIFIER_LENGTH, DEFAULT_CODE_VERIFIER_LENGTH, PkceError, type PkcePair, type SecretData, type SecretPersistenceOptions, type SecretValidationResult, secretDataSchema, validateSecretData, parseSecretData, isSecretPersistenceEnabled, resolveSecretPath, loadSecret, saveSecret, deleteSecret, generateSecret, createSecretData, getOrCreateSecret, clearCachedSecret, isSecretCached, type SignedData, type HmacSigningConfig, signData, verifyData, isSignedData, verifyOrParseData, type BaseKeyData, type SecretKeyData, type AsymmetricKeyData, type AnyKeyData, type KeyPersistenceOptions, type CreateKeyPersistenceOptions, type CreateSecretOptions, type CreateAsymmetricOptions, type KeyValidationResult, asymmetricAlgSchema, secretKeyDataSchema, asymmetricKeyDataSchema, anyKeyDataSchema, validateKeyData, parseKeyData, isSecretKeyData, isAsymmetricKeyData, KeyPersistence, createKeyPersistence, createKeyPersistenceWithStorage, } from './crypto';
 export type { CryptoProvider, EncBlob, EncryptedBlob } from './crypto';
@@ -30,4 +31,4 @@ export { createStorage, createMemoryStorage, getDetectedStorageType, NamespacedS
 export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, RedisHostConnectionConfig, RedisUrlConnectionConfig, RedisUrlFillInConfig, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, RedisErrorListenerOptions, RedisUrlConnection, 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';
+export { getHostname, getMachineId, setMachineIdOverride } from './machine-id';

package/index.js

@@ -119,6 +119,9 @@ async function fileExists(p) {
     return false;
   }
 }
+function fileExistsSync(p) {
+  return getFs().existsSync(p);
+}
 async function readJSON(jsonPath) {
   try {
     const fsp = getFsp();
@@ -4134,6 +4137,7 @@ __export(index_exports, {
   base64urlDecode: () => base64urlDecode,
   base64urlEncode: () => base64urlEncode,
   basename: () => import_path2.basename,
+  brandClass: () => brandClass,
   buildPrefix: () => buildPrefix,
   buildSetCookie: () => buildSetCookie,
   bytesToHex: () => bytesToHex,
@@ -4184,6 +4188,7 @@ __export(index_exports, {
   extractTemplateParams: () => extractTemplateParams,
   extractUriScheme: () => extractUriScheme,
   fileExists: () => fileExists,
+  fileExistsSync: () => fileExistsSync,
   findNonFiniteNumber: () => findNonFiniteNumber,
   generateCodeChallenge: () => generateCodeChallenge,
   generateCodeVerifier: () => generateCodeVerifier,
@@ -4197,6 +4202,7 @@ __export(index_exports, {
   getDetectedStorageType: () => getDetectedStorageType,
   getEnv: () => import_env2.getEnv,
   getEnvFlag: () => import_env2.getEnvFlag,
+  getHostname: () => getHostname,
   getMachineId: () => getMachineId,
   getNodeEnv: () => import_env2.getNodeEnv,
   getOrCreateSecret: () => getOrCreateSecret,
@@ -4210,6 +4216,7 @@ __export(index_exports, {
   inferMimeType: () => inferMimeType,
   isAbsolute: () => import_path2.isAbsolute,
   isAsymmetricKeyData: () => isAsymmetricKeyData,
+  isBrandedInstance: () => isBrandedInstance,
   isBrowser: () => isBrowser,
   isDebug: () => import_env2.isDebug,
   isDevelopment: () => import_env2.isDevelopment,
@@ -5114,6 +5121,30 @@ function safeJsonForScript(value) {
   }
 }
 
+// libs/utils/src/class-brand/class-brand.ts
+var CLASS_BRAND = /* @__PURE__ */ Symbol.for("@frontmcp/class-brand");
+var ordinaryHasInstance = Function.prototype[Symbol.hasInstance];
+function ownBrandOf(klass) {
+  if (typeof klass !== "function" || !Object.prototype.hasOwnProperty.call(klass, CLASS_BRAND)) return void 0;
+  return klass[CLASS_BRAND];
+}
+function classOfPrototype(proto) {
+  return Object.getOwnPropertyDescriptor(proto, "constructor")?.value;
+}
+function brandClass(klass, brand) {
+  Object.defineProperty(klass, CLASS_BRAND, { value: brand, enumerable: false, writable: false, configurable: false });
+}
+function isBrandedInstance(klass, value) {
+  if (ordinaryHasInstance.call(klass, value)) return true;
+  if (typeof value !== "object" || value === null) return false;
+  const brand = ownBrandOf(klass);
+  if (brand === void 0) return false;
+  for (let proto = Object.getPrototypeOf(value); proto !== null; proto = Object.getPrototypeOf(proto)) {
+    if (ownBrandOf(classOfPrototype(proto)) === brand) return true;
+  }
+  return false;
+}
+
 // libs/utils/src/serialization/serialization.ts
 function safeStringify(value, space) {
   const seen = /* @__PURE__ */ new WeakSet();
@@ -5148,6 +5179,9 @@ var import_env2 = require("#env");
 var import_runtime_context = require("#runtime-context");
 
 // libs/utils/src/storage/factory.ts
+var import_env3 = require("#env");
+var import_runtime_context2 = require("#runtime-context");
+init_memory();
 init_errors();
 
 // libs/utils/src/storage/namespace.ts
@@ -5316,8 +5350,14 @@ function createNamespacedStorage(adapter, prefix) {
 }
 
 // libs/utils/src/storage/factory.ts
-init_memory();
-var import_env3 = require("#env");
+var noDistributedStorageWarned = false;
+function warnNoDistributedStorage() {
+  if (noDistributedStorageWarned || (0, import_runtime_context2.getRuntimeContext)().runtime === "browser") return;
+  noDistributedStorageWarned = true;
+  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."
+  );
+}
 function detectStorageType() {
   if ((0, import_env3.getEnv)("UPSTASH_REDIS_REST_URL") && (0, import_env3.getEnv)("UPSTASH_REDIS_REST_TOKEN")) {
     return "upstash";
@@ -5368,11 +5408,7 @@ async function createStorage(config = {}) {
   const fallback = config.fallback ?? ((0, import_env3.isProduction)() ? "error" : "memory");
   if (type === "auto") {
     type = detectStorageType();
-    if (type === "memory" && (0, import_env3.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."
-      );
-    }
+    if (type === "memory" && (0, import_env3.isProduction)()) warnNoDistributedStorage();
   }
   let adapter;
   try {
@@ -6034,6 +6070,14 @@ function saveMachineIdAsync(machineId) {
     }
   })();
 }
+function getHostname() {
+  if (!isNode()) return void 0;
+  try {
+    return require("os").hostname();
+  } catch {
+    return void 0;
+  }
+}
 function computeMachineId() {
   const envMachineId = getEnvDirect("MACHINE_ID");
   if (envMachineId) return envMachineId;
@@ -6114,6 +6158,7 @@ function setMachineIdOverride(id) {
   base64urlDecode,
   base64urlEncode,
   basename,
+  brandClass,
   buildPrefix,
   buildSetCookie,
   bytesToHex,
@@ -6164,6 +6209,7 @@ function setMachineIdOverride(id) {
   extractTemplateParams,
   extractUriScheme,
   fileExists,
+  fileExistsSync,
   findNonFiniteNumber,
   generateCodeChallenge,
   generateCodeVerifier,
@@ -6177,6 +6223,7 @@ function setMachineIdOverride(id) {
   getDetectedStorageType,
   getEnv,
   getEnvFlag,
+  getHostname,
   getMachineId,
   getNodeEnv,
   getOrCreateSecret,
@@ -6190,6 +6237,7 @@ function setMachineIdOverride(id) {
   inferMimeType,
   isAbsolute,
   isAsymmetricKeyData,
+  isBrandedInstance,
   isBrowser,
   isDebug,
   isDevelopment,

package/machine-id/index.d.ts

@@ -1 +1 @@
-export { getMachineId, setMachineIdOverride } from './machine-id';
+export { getHostname, getMachineId, setMachineIdOverride } from './machine-id';

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

@@ -20,6 +20,8 @@
  *   2. File persistence at `.frontmcp/machine-id` (dev mode)
  *   3. Random UUID (production)
  */
+/** This host's name (`os.hostname()`), read when called; `undefined` outside Node. */
+export declare function getHostname(): string | undefined;
 /**
  * Get the current machine ID.
  * Returns the override (if set via `setMachineIdOverride`) or the lazily

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "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.3",
+    "@frontmcp/lazy-zod": "1.9.5",
     "@upstash/redis": "^1.34.0",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"

package/storage/factory.d.ts

@@ -3,7 +3,7 @@
  *
  * Factory function to create storage adapters with auto-detection.
  */
-import type { StorageConfig, StorageType, RootStorage } from './types';
+import type { RootStorage, StorageConfig, StorageType } from './types';
 /**
  * Create a storage instance.
  *