@frontmcp/utils 1.3.0 → 1.4.1

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

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

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

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

package/esm/crypto/browser.mjs

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

package/esm/env/browser-env.mjs

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

package/esm/env/node-env.mjs

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

package/esm/index.mjs

@@ -1,3 +1,5 @@
+import { createRequire as __frontmcpCreateRequire } from 'module';
+const require = __frontmcpCreateRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -65,6 +67,9 @@ function getSpawn() {
   }
   return _spawn;
 }
+function getSpawnFn() {
+  return getSpawn();
+}
 async function readFile(p, encoding = "utf8") {
   const fsp = getFsp();
   return fsp.readFile(p, encoding);
@@ -85,6 +90,10 @@ async function mkdir(p, options) {
   const fsp = getFsp();
   await fsp.mkdir(p, options);
 }
+function ensureDirSync(p) {
+  const fs2 = getFs();
+  fs2.mkdirSync(p, { recursive: true });
+}
 async function rename(oldPath, newPath) {
   const fsp = getFsp();
   await fsp.rename(oldPath, newPath);
@@ -177,6 +186,20 @@ function runCmd(cmd, args, opts = {}) {
     child.on("error", reject);
   });
 }
+function watchFile(p, onChange, options) {
+  const fs2 = getFs();
+  const watcher = fs2.watch(p, { persistent: false, recursive: options?.recursive === true }, (eventType, filename) => {
+    onChange(eventType, filename);
+  });
+  return {
+    close() {
+      watcher.close();
+    },
+    onError(handler) {
+      watcher.on("error", handler);
+    }
+  };
+}
 var _fsp, _fs, _spawn, F_OK;
 var init_fs = __esm({
   "libs/utils/src/fs/fs.ts"() {
@@ -4188,7 +4211,7 @@ function joinPath(...parts) {
 }
 
 // libs/utils/src/path/node-path.ts
-import { resolve, join, basename, dirname, extname, isAbsolute } from "path";
+import { resolve, join, basename, dirname, extname, isAbsolute, sep } from "path";
 import { pathToFileURL } from "url";
 
 // libs/utils/src/content/content.ts
@@ -5597,6 +5620,7 @@ export {
   encryptAndSerialize,
   encryptValue,
   ensureDir,
+  ensureDirSync,
   ensureMaxLen,
   entryAvailabilitySchema,
   escapeGlob,
@@ -5627,6 +5651,7 @@ export {
   getMachineId,
   getOrCreateSecret,
   getRuntimeContext,
+  getSpawnFn,
   globToRegex,
   hasTemplatePlaceholders,
   hkdfSha256,
@@ -5704,6 +5729,7 @@ export {
   saveSecret,
   secretDataSchema,
   secretKeyDataSchema,
+  sep,
   sepFor,
   serializeBlob,
   setEnv,
@@ -5738,6 +5764,7 @@ export {
   verifyCodeChallenge,
   verifyData,
   verifyOrParseData,
+  watchFile,
   writeFile,
   writeJSON
 };

package/fs/fs.d.ts

@@ -6,6 +6,16 @@
  * **Note:** These functions are Node.js only and will throw an error
  * if called in a browser environment.
  */
+/**
+ * Lazily resolve `child_process.spawn` for callers that need to spawn a
+ * detached worker (CLI task runners, dev-server supervisors, etc.). Throws
+ * via `assertNode` on non-Node runtimes.
+ *
+ * **Node.js only.** Exposed because consumers (e.g. `CliTaskRunner` in the
+ * SDK) need a single place to reach `spawn` without a top-level
+ * `import 'node:child_process'` that V8 isolates would choke on.
+ */
+export declare function getSpawnFn(): typeof import('child_process').spawn;
 /**
  * Read a file's contents as a string.
  *
@@ -77,6 +87,21 @@ export declare function mkdir(p: string, options?: {
     recursive?: boolean;
     mode?: number;
 }): Promise<void>;
+/**
+ * Ensure a directory exists, creating it recursively if needed (synchronous).
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * Use this only when async operations are not possible (e.g., a synchronous
+ * constructor that must open a file path before the first I/O). Prefer the
+ * async `ensureDir` in most cases.
+ *
+ * @param p - Path to directory
+ *
+ * @example
+ * ensureDirSync('/path/to/new/directory');
+ */
+export declare function ensureDirSync(p: string): void;
 /**
  * Rename/move a file or directory.
  *
@@ -313,3 +338,34 @@ export declare function runCmd(cmd: string, args: string[], opts?: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;
+/**
+ * Handle returned by {@link watchFile}. `close()` stops the watch and is safe
+ * to call multiple times. `onError` registers an error handler — useful for
+ * platforms (Linux watch-count limits, network filesystems) that surface
+ * mid-stream failures.
+ */
+export interface FileWatcherHandle {
+    close(): void;
+    onError(handler: (err: Error) => void): void;
+}
+/** Options for {@link watchFile}. Mirrors a subset of Node `fs.watch`. */
+export interface WatchFileOptions {
+    /** Watch a directory recursively. Node-specific; default false. */
+    recursive?: boolean;
+}
+/** Callback fired on each filesystem change event. */
+export type WatchFileListener = (eventType: 'rename' | 'change', filename: string | null) => void;
+/**
+ * Watch a file or directory for changes. Returns a handle the caller closes
+ * to stop watching.
+ *
+ * Accepts either a no-arg listener (the simple case) or one that receives
+ * the Node-shaped `(eventType, filename)` pair — both are tolerated so
+ * shallow callers stay terse while filesystem-walking callers get the full
+ * signal.
+ *
+ * **Node.js only** — calls `assertNode` at invocation time. Build-time env
+ * selection (`frontmcp build --target <env>`) keeps this off non-Node
+ * targets; runtime callers in V8 isolates will hit the assertion.
+ */
+export declare function watchFile(p: string, onChange: WatchFileListener | (() => void), options?: WatchFileOptions): FileWatcherHandle;

package/fs/index.d.ts

@@ -1 +1,2 @@
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';
+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 type { FileWatcherHandle } from './fs';

package/index.d.ts

@@ -9,11 +9,12 @@ export { splitWords, toCase, sepFor, shortHash, ensureMaxLen, idFromString } fro
 export type { NameCase } from './naming';
 export { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate, parseUriTemplate, matchUriTemplate, expandUriTemplate, extractTemplateParams, isUriTemplate, } from './uri';
 export type { ParsedUriTemplate } from './uri';
-export { trimSlashes, joinPath, pathResolve, pathJoin, basename, dirname, extname, isAbsolute, pathToFileURL, } from './path';
+export { trimSlashes, joinPath, pathResolve, pathJoin, basename, dirname, extname, isAbsolute, pathToFileURL, sep, } from './path';
 export { sanitizeToJson, inferMimeType, findNonFiniteNumber } from './content';
 export { validateBaseUrl, buildSetCookie, parseCookies, getCookie, isLocalhost, isSecureRequest } from './http';
 export type { CookieOptions, SecureDetectionRequest } from './http';
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';
+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 type { FileWatcherHandle } from './fs';
 export { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from './escape';
 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';

package/index.js

@@ -70,6 +70,9 @@ function getSpawn() {
   }
   return _spawn;
 }
+function getSpawnFn() {
+  return getSpawn();
+}
 async function readFile(p, encoding = "utf8") {
   const fsp = getFsp();
   return fsp.readFile(p, encoding);
@@ -90,6 +93,10 @@ async function mkdir(p, options) {
   const fsp = getFsp();
   await fsp.mkdir(p, options);
 }
+function ensureDirSync(p) {
+  const fs2 = getFs();
+  fs2.mkdirSync(p, { recursive: true });
+}
 async function rename(oldPath, newPath) {
   const fsp = getFsp();
   await fsp.rename(oldPath, newPath);
@@ -182,6 +189,20 @@ function runCmd(cmd, args, opts = {}) {
     child.on("error", reject);
   });
 }
+function watchFile(p, onChange, options) {
+  const fs2 = getFs();
+  const watcher = fs2.watch(p, { persistent: false, recursive: options?.recursive === true }, (eventType, filename) => {
+    onChange(eventType, filename);
+  });
+  return {
+    close() {
+      watcher.close();
+    },
+    onError(handler) {
+      watcher.on("error", handler);
+    }
+  };
+}
 var _fsp, _fs, _spawn, F_OK;
 var init_fs = __esm({
   "libs/utils/src/fs/fs.ts"() {
@@ -3863,6 +3884,7 @@ __export(index_exports, {
   encryptAndSerialize: () => encryptAndSerialize,
   encryptValue: () => encryptValue,
   ensureDir: () => ensureDir,
+  ensureDirSync: () => ensureDirSync,
   ensureMaxLen: () => ensureMaxLen,
   entryAvailabilitySchema: () => entryAvailabilitySchema,
   escapeGlob: () => escapeGlob,
@@ -3893,6 +3915,7 @@ __export(index_exports, {
   getMachineId: () => getMachineId,
   getOrCreateSecret: () => getOrCreateSecret,
   getRuntimeContext: () => getRuntimeContext,
+  getSpawnFn: () => getSpawnFn,
   globToRegex: () => globToRegex,
   hasTemplatePlaceholders: () => hasTemplatePlaceholders,
   hkdfSha256: () => hkdfSha256,
@@ -3970,6 +3993,7 @@ __export(index_exports, {
   saveSecret: () => saveSecret,
   secretDataSchema: () => secretDataSchema,
   secretKeyDataSchema: () => secretKeyDataSchema,
+  sep: () => import_path.sep,
   sepFor: () => sepFor,
   serializeBlob: () => serializeBlob,
   setEnv: () => import_env3.setEnv,
@@ -4004,6 +4028,7 @@ __export(index_exports, {
   verifyCodeChallenge: () => verifyCodeChallenge,
   verifyData: () => verifyData,
   verifyOrParseData: () => verifyOrParseData,
+  watchFile: () => watchFile,
   writeFile: () => writeFile,
   writeJSON: () => writeJSON
 });
@@ -5810,6 +5835,7 @@ function setMachineIdOverride(id) {
   encryptAndSerialize,
   encryptValue,
   ensureDir,
+  ensureDirSync,
   ensureMaxLen,
   entryAvailabilitySchema,
   escapeGlob,
@@ -5840,6 +5866,7 @@ function setMachineIdOverride(id) {
   getMachineId,
   getOrCreateSecret,
   getRuntimeContext,
+  getSpawnFn,
   globToRegex,
   hasTemplatePlaceholders,
   hkdfSha256,
@@ -5917,6 +5944,7 @@ function setMachineIdOverride(id) {
   saveSecret,
   secretDataSchema,
   secretKeyDataSchema,
+  sep,
   sepFor,
   serializeBlob,
   setEnv,
@@ -5951,6 +5979,7 @@ function setMachineIdOverride(id) {
   verifyCodeChallenge,
   verifyData,
   verifyOrParseData,
+  watchFile,
   writeFile,
   writeJSON
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.3.0",
+  "version": "1.4.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.13.0",
     "@noble/ciphers": "^2.1.1",
-    "@enclave-vm/ast": "^2.13.0"
+    "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
+    "@frontmcp/lazy-zod": "1.4.1",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
-    "ioredis": "^5.0.0",
-    "@frontmcp/lazy-zod": "1.3.0"
+    "ioredis": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@vercel/kv": {

package/path/browser-path.d.ts

@@ -5,3 +5,9 @@ export declare function dirname(_p: string): string;
 export declare function extname(p: string): string;
 export declare function isAbsolute(p: string): boolean;
 export declare function pathToFileURL(_p: string): URL;
+/**
+ * Platform-specific path separator. In browser/Worker builds we mirror POSIX
+ * (`/`) — these targets never read a real filesystem so the value is only
+ * used for string parsing, and POSIX matches the runtime's URL conventions.
+ */
+export declare const sep = "/";

package/path/index.d.ts

@@ -1,2 +1,2 @@
 export { trimSlashes, joinPath } from './path';
-export { resolve as pathResolve, join as pathJoin, basename, dirname, extname, isAbsolute, pathToFileURL } from '#path';
+export { resolve as pathResolve, join as pathJoin, basename, dirname, extname, isAbsolute, pathToFileURL, sep, } from '#path';

package/path/node-path.d.ts

@@ -1,2 +1,2 @@
-export { resolve, join, basename, dirname, extname, isAbsolute } from 'path';
+export { resolve, join, basename, dirname, extname, isAbsolute, sep } from 'path';
 export { pathToFileURL } from 'url';