@frontmcp/utils 0.0.1 → 0.7.1

package/esm/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@frontmcp/utils",
+  "version": "0.7.1",
+  "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
+  "author": "AgentFront <info@agentfront.dev>",
+  "license": "Apache-2.0",
+  "keywords": [
+    "utils",
+    "utilities",
+    "uri",
+    "url",
+    "string",
+    "path",
+    "typescript",
+    "mcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git",
+    "directory": "libs/utils"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/utils/README.md",
+  "dependencies": {
+    "@noble/hashes": "^2.0.1",
+    "@noble/ciphers": "^2.1.1",
+    "ast-guard": "^2.4.0"
+  },
+  "type": "module",
+  "main": "../index.js",
+  "module": "./index.mjs",
+  "types": "../index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "../package.json",
+    ".": {
+      "require": {
+        "types": "../index.d.ts",
+        "default": "../index.js"
+      },
+      "import": {
+        "types": "../index.d.ts",
+        "default": "./index.mjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/fs/fs.d.ts

@@ -0,0 +1,254 @@
+/**
+ * File system utilities for common async operations.
+ *
+ * Provides Promise-based wrappers for file system operations.
+ *
+ * **Note:** These functions are Node.js only and will throw an error
+ * if called in a browser environment.
+ */
+/**
+ * Read a file's contents as a string.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to file
+ * @param encoding - Encoding (default 'utf8')
+ * @returns File contents as string
+ *
+ * @example
+ * const content = await readFile('/path/to/file.txt');
+ */
+export declare function readFile(p: string, encoding?: BufferEncoding): Promise<string>;
+/**
+ * Read a file's contents as a Buffer.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to file
+ * @returns File contents as Buffer
+ *
+ * @example
+ * const buffer = await readFileBuffer('/path/to/file.bin');
+ */
+export declare function readFileBuffer(p: string): Promise<Buffer>;
+/**
+ * Write content to a file.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to write to
+ * @param content - Content to write
+ * @param options - Optional mode (permissions)
+ *
+ * @example
+ * await writeFile('/path/to/file.txt', 'hello', { mode: 0o600 });
+ */
+export declare function writeFile(p: string, content: string, options?: {
+    mode?: number;
+}): Promise<void>;
+/**
+ * Create a directory with optional mode (permissions).
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to directory
+ * @param options - Optional recursive and mode settings
+ *
+ * @example
+ * await mkdir('/path/to/dir', { recursive: true, mode: 0o700 });
+ */
+export declare function mkdir(p: string, options?: {
+    recursive?: boolean;
+    mode?: number;
+}): Promise<void>;
+/**
+ * Rename/move a file or directory.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param oldPath - Current path
+ * @param newPath - New path
+ *
+ * @example
+ * await rename('/path/to/old.txt', '/path/to/new.txt');
+ */
+export declare function rename(oldPath: string, newPath: string): Promise<void>;
+/**
+ * Delete a file.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to file to delete
+ *
+ * @example
+ * await unlink('/path/to/file.txt');
+ */
+export declare function unlink(p: string): Promise<void>;
+/**
+ * Check if a file exists asynchronously.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to check
+ * @returns true if file exists, false otherwise
+ *
+ * @example
+ * await fileExists('/path/to/file.txt') // true or false
+ */
+export declare function fileExists(p: string): Promise<boolean>;
+/**
+ * Read and parse a JSON file.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param jsonPath - Path to JSON file
+ * @returns Parsed JSON content, or null if file doesn't exist or is invalid
+ *
+ * @example
+ * const config = await readJSON<Config>('/path/to/config.json');
+ */
+export declare function readJSON<T = unknown>(jsonPath: string): Promise<T | null>;
+/**
+ * Write an object to a JSON file with pretty formatting.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to write to
+ * @param obj - Object to serialize
+ *
+ * @example
+ * await writeJSON('/path/to/output.json', { key: 'value' });
+ */
+export declare function writeJSON(p: string, obj: unknown): Promise<void>;
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to directory
+ *
+ * @example
+ * await ensureDir('/path/to/new/directory');
+ */
+export declare function ensureDir(p: string): Promise<void>;
+/**
+ * Get file/directory stats.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to file or directory
+ * @returns Stats object with isDirectory(), isFile(), etc.
+ *
+ * @example
+ * const stats = await stat('/path/to/file');
+ * if (stats.isDirectory()) { ... }
+ */
+export declare function stat(p: string): Promise<import('fs').Stats>;
+/**
+ * Copy a file.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param src - Source path
+ * @param dest - Destination path
+ *
+ * @example
+ * await copyFile('/path/to/src', '/path/to/dest');
+ */
+export declare function copyFile(src: string, dest: string): Promise<void>;
+/**
+ * Copy a file or directory recursively.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param src - Source path
+ * @param dest - Destination path
+ * @param options - Copy options
+ *
+ * @example
+ * await cp('/path/to/src', '/path/to/dest', { recursive: true });
+ */
+export declare function cp(src: string, dest: string, options?: {
+    recursive?: boolean;
+}): Promise<void>;
+/**
+ * List directory contents.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to directory
+ * @returns Array of file/directory names
+ *
+ * @example
+ * const files = await readdir('/path/to/dir');
+ */
+export declare function readdir(p: string): Promise<string[]>;
+/**
+ * Remove a file or directory recursively.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to remove
+ * @param options - Optional recursive flag
+ *
+ * @example
+ * await rm('/path/to/dir', { recursive: true });
+ */
+export declare function rm(p: string, options?: {
+    recursive?: boolean;
+    force?: boolean;
+}): Promise<void>;
+/**
+ * Check if a directory is empty.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param dir - Path to directory
+ * @returns true if directory is empty or doesn't exist
+ *
+ * @example
+ * await isDirEmpty('/path/to/directory') // true or false
+ */
+export declare function isDirEmpty(dir: string): Promise<boolean>;
+/**
+ * Create a temporary directory with a unique name.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param prefix - Directory prefix
+ * @returns Path to the created directory
+ *
+ * @example
+ * const tmpDir = await mkdtemp('/tmp/myapp-');
+ */
+export declare function mkdtemp(prefix: string): Promise<string>;
+/**
+ * Check if a file or directory is accessible.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param p - Path to check
+ * @param mode - Access mode (default F_OK for existence check)
+ * @throws Error if path is not accessible
+ *
+ * @example
+ * await access('/path/to/file'); // throws if not accessible
+ */
+export declare function access(p: string, mode?: number): Promise<void>;
+/**
+ * Run a command as a child process.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * @param cmd - Command to run
+ * @param args - Command arguments
+ * @param opts - Options including cwd
+ * @returns Promise that resolves when command completes successfully
+ * @throws Error if command exits with non-zero code
+ *
+ * @example
+ * await runCmd('npm', ['install'], { cwd: '/project' });
+ */
+export declare function runCmd(cmd: string, args: string[], opts?: {
+    cwd?: string;
+}): Promise<void>;

package/fs/index.d.ts

@@ -0,0 +1 @@
+export { readFile, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, rm, mkdtemp, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';

package/http/http.d.ts

@@ -0,0 +1,20 @@
+/**
+ * HTTP utilities for URL validation and request handling.
+ *
+ * Provides security-focused validation for URLs and HTTP operations.
+ */
+/**
+ * Validate and normalize a base URL.
+ * Only allows http: and https: protocols to prevent SSRF attacks.
+ *
+ * @param url - URL string to validate
+ * @returns Validated URL object
+ * @throws Error if URL is invalid or uses unsupported protocol
+ *
+ * @example
+ * validateBaseUrl('https://api.example.com') // URL object
+ * validateBaseUrl('http://localhost:3000') // URL object
+ * validateBaseUrl('file:///etc/passwd') // throws Error
+ * validateBaseUrl('javascript:alert(1)') // throws Error
+ */
+export declare function validateBaseUrl(url: string): URL;

package/http/index.d.ts

@@ -0,0 +1 @@
+export { validateBaseUrl } from './http';

package/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @frontmcp/utils
+ *
+ * Shared utility functions for the FrontMCP ecosystem.
+ * Provides generic, protocol-neutral utilities for string manipulation,
+ * URI handling, path operations, content processing, and more.
+ */
+export { NameCase, splitWords, toCase, sepFor, shortHash, ensureMaxLen, idFromString } from './naming';
+export { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate, ParsedUriTemplate, parseUriTemplate, matchUriTemplate, expandUriTemplate, extractTemplateParams, isUriTemplate, } from './uri';
+export { trimSlashes, joinPath } from './path';
+export { sanitizeToJson, inferMimeType } from './content';
+export { validateBaseUrl } from './http';
+export { readFile, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, rm, mkdtemp, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';
+export { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from './escape';
+export { safeStringify } from './serialization';
+export { getCrypto, rsaVerify, jwtAlgToNodeAlg, isRsaPssAlg, randomUUID, randomBytes, sha256, sha256Hex, sha256Base64url, hmacSha256, hkdfSha256, encryptAesGcm, decryptAesGcm, timingSafeEqual, bytesToHex, base64urlEncode, base64urlDecode, isNode, isBrowser, assertNode, CryptoProvider, EncBlob, EncryptedBlob, 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, } from './crypto';
+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, StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, VercelKvStorageAdapter, UpstashStorageAdapter, globToRegex, matchesPattern, validatePattern, escapeGlob, MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './storage';