@hyperfrontend/project-scope 0.2.1 → 0.2.3

package/core/index.esm.js

@@ -1,420 +1,26 @@
-import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync, lstatSync, readdirSync, rmSync, realpathSync, mkdtempSync, unlinkSync, rmdirSync } from 'node:fs';
-import { dirname, join as join$1, posix, normalize, sep, isAbsolute as isAbsolute$1, relative, resolve, basename, extname, parse as parse$1 } from 'node:path';
+import { createMap } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js';
+import { freeze, defineProperty, entries, keys, defineProperties } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import { createSet } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
+import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { isArray } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
+import { error, warn, log, info, debug } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.esm.js';
+import { stringify, parse } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
+import { createLogger } from '../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { min } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
+import { existsSync, readFileSync, statSync, lstatSync, mkdirSync, readdirSync, rmSync, realpathSync, writeFileSync, mkdtempSync, unlinkSync, rmdirSync } from 'node:fs';
+import { join as join$1, normalize, sep, posix, isAbsolute as isAbsolute$1, relative, resolve, basename, dirname, extname, parse as parse$1 } from 'node:path';
 import { tmpdir, platform, arch } from 'node:os';
-
-/**
- * Safe copies of Error built-ins via factory functions.
- *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides factory functions that use Reflect.construct internally.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
- */
-const _Error = globalThis.Error;
-const _Reflect$2 = globalThis.Reflect;
-/**
- * (Safe copy) Creates a new Error using the captured Error constructor.
- * Use this instead of `new Error()`.
- *
- * @param message - Optional error message.
- * @param options - Optional error options.
- * @returns A new Error instance.
- */
-const createError = (message, options) => _Reflect$2.construct(_Error, [message, options]);
-
-/**
- * Safe copies of JSON built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/json
- */
-const _JSON = globalThis.JSON;
-/**
- * (Safe copy) Converts a JavaScript Object Notation (JSON) string into an object.
- */
-const parse = _JSON.parse;
-/**
- * (Safe copy) Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
- */
-const stringify = _JSON.stringify;
-
-/**
- * Safe copies of Object built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
- */
-const _Object = globalThis.Object;
-/**
- * (Safe copy) Prevents modification of existing property attributes and values,
- * and prevents the addition of new properties.
- */
-const freeze = _Object.freeze;
-/**
- * (Safe copy) Returns the names of the enumerable string properties and methods of an object.
- */
-const keys = _Object.keys;
-/**
- * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
- */
-const entries = _Object.entries;
-/**
- * (Safe copy) Adds a property to an object, or modifies attributes of an existing property.
- */
-const defineProperty = _Object.defineProperty;
-/**
- * (Safe copy) Adds one or more properties to an object, and/or modifies attributes of existing properties.
- */
-const defineProperties = _Object.defineProperties;
-
-/**
- * Safe copies of Array built-in static methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/array
- */
-const _Array = globalThis.Array;
-/**
- * (Safe copy) Determines whether the passed value is an Array.
- */
-const isArray = _Array.isArray;
-
-/**
- * Safe copies of Console built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/console
- */
-const _console = globalThis.console;
-/**
- * (Safe copy) Outputs a message to the console.
- */
-const log = _console.log.bind(_console);
-/**
- * (Safe copy) Outputs a warning message to the console.
- */
-const warn = _console.warn.bind(_console);
-/**
- * (Safe copy) Outputs an error message to the console.
- */
-const error = _console.error.bind(_console);
-/**
- * (Safe copy) Outputs an informational message to the console.
- */
-const info = _console.info.bind(_console);
-/**
- * (Safe copy) Outputs a debug message to the console.
- */
-const debug = _console.debug.bind(_console);
-/**
- * (Safe copy) Outputs a stack trace to the console.
- */
-_console.trace.bind(_console);
-/**
- * (Safe copy) Displays an interactive listing of the properties of a specified object.
- */
-_console.dir.bind(_console);
-/**
- * (Safe copy) Displays tabular data as a table.
- */
-_console.table.bind(_console);
-/**
- * (Safe copy) Writes an error message to the console if the assertion is false.
- */
-_console.assert.bind(_console);
-/**
- * (Safe copy) Clears the console.
- */
-_console.clear.bind(_console);
-/**
- * (Safe copy) Logs the number of times that this particular call to count() has been called.
- */
-_console.count.bind(_console);
-/**
- * (Safe copy) Resets the counter used with console.count().
- */
-_console.countReset.bind(_console);
-/**
- * (Safe copy) Creates a new inline group in the console.
- */
-_console.group.bind(_console);
-/**
- * (Safe copy) Creates a new inline group in the console that is initially collapsed.
- */
-_console.groupCollapsed.bind(_console);
-/**
- * (Safe copy) Exits the current inline group.
- */
-_console.groupEnd.bind(_console);
-/**
- * (Safe copy) Starts a timer with a name specified as an input parameter.
- */
-_console.time.bind(_console);
-/**
- * (Safe copy) Stops a timer that was previously started.
- */
-_console.timeEnd.bind(_console);
-/**
- * (Safe copy) Logs the current value of a timer that was previously started.
- */
-_console.timeLog.bind(_console);
-
-/**
- * Safe copies of Set built-in via factory function.
- *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides a factory function that uses Reflect.construct internally.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/set
- */
-const _Set = globalThis.Set;
-const _Reflect$1 = globalThis.Reflect;
-/**
- * (Safe copy) Creates a new Set using the captured Set constructor.
- * Use this instead of `new Set()`.
- *
- * @param iterable - Optional iterable of values.
- * @returns A new Set instance.
- */
-const createSet = (iterable) => _Reflect$1.construct(_Set, iterable ? [iterable] : []);
-
-const registeredClasses = [];
-
-/**
- * Returns the data type of the target.
- * Uses native `typeof` operator, however, makes distinction between `null`, `array`, and `object`.
- * Also, when classes are registered via `registerClass`, it checks if objects are instance of any known registered class.
- *
- * @param target - The target to get the data type of.
- * @returns The data type of the target.
- */
-const getType = (target) => {
-    if (target === null)
-        return 'null';
-    const nativeDataType = typeof target;
-    if (nativeDataType === 'object') {
-        if (isArray(target))
-            return 'array';
-        for (const registeredClass of registeredClasses) {
-            if (target instanceof registeredClass)
-                return registeredClass.name;
-        }
-    }
-    return nativeDataType;
-};
-
-/**
- * Safe copies of Map built-in via factory function.
- *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides a factory function that uses Reflect.construct internally.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/map
- */
-const _Map = globalThis.Map;
-const _Reflect = globalThis.Reflect;
-/**
- * (Safe copy) Creates a new Map using the captured Map constructor.
- * Use this instead of `new Map()`.
- *
- * @param iterable - Optional iterable of key-value pairs.
- * @returns A new Map instance.
- */
-const createMap = (iterable) => _Reflect.construct(_Map, iterable ? [iterable] : []);
-
-/**
- * Safe copies of Math built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/math
- */
-const _Math = globalThis.Math;
-/**
- * (Safe copy) Returns the smaller of zero or more numbers.
- */
-const min = _Math.min;
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Creates a wrapper function that only executes the wrapped function if the condition function returns true.
- *
- * @param func - The function to be conditionally executed.
- * @param conditionFunc - A function that returns a boolean, determining if `func` should be executed.
- * @returns A wrapped version of `func` that executes conditionally.
- */
-function createConditionalExecutionFunction(func, conditionFunc) {
-    return function (...args) {
-        if (conditionFunc()) {
-            return func(...args);
-        }
-    };
-}
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Creates a wrapper function that silently ignores any errors thrown by the wrapped void function.
- * This function is specifically for wrapping functions that do not return a value (void functions).
- * Exceptions are swallowed without any logging or handling.
- *
- * @param func - The void function to be wrapped.
- * @returns A wrapped version of the input function that ignores errors.
- */
-function createErrorIgnoringFunction(func) {
-    return function (...args) {
-        try {
-            func(...args);
-        }
-        catch {
-            // Deliberately swallowing/ignoring the exception
-        }
-    };
-}
-
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/**
- * A no-operation function (noop) that does nothing regardless of the arguments passed.
- * It is designed to be as permissive as possible in its typing without using the `Function` keyword.
- *
- * @param args - Any arguments passed to the function (ignored)
- */
-const noop = (...args) => {
-    // Intentionally does nothing
-};
-
-const logLevels = ['none', 'error', 'warn', 'log', 'info', 'debug'];
-const priority = {
-    error: 4,
-    warn: 3,
-    log: 2,
-    info: 1,
-    debug: 0,
-};
-/**
- * Validates whether a given string is a valid log level.
- *
- * @param level - The log level to validate
- * @returns True if the level is valid, false otherwise
- */
-function isValidLogLevel(level) {
-    return logLevels.includes(level);
-}
-/**
- * Creates a log level configuration manager for controlling logging behavior.
- * Provides methods to get, set, and evaluate log levels based on priority.
- *
- * @param level - The initial log level (defaults to 'error')
- * @returns A configuration object with log level management methods
- * @throws {Error} When the provided level is not a valid log level
- */
-function createLogLevelConfig(level = 'error') {
-    if (!isValidLogLevel(level)) {
-        throw createError('Cannot create log level configuration with a valid default log level');
-    }
-    const state = { level };
-    const getLogLevel = () => state.level;
-    const setLogLevel = (level) => {
-        if (!isValidLogLevel(level)) {
-            throw createError(`Cannot set value '${level}' level. Expected levels are ${logLevels}.`);
-        }
-        state.level = level;
-    };
-    const shouldLog = (level) => {
-        if (state.level === 'none' || level === 'none' || !isValidLogLevel(level)) {
-            return false;
-        }
-        return priority[level] >= priority[state.level];
-    };
-    return freeze({
-        getLogLevel,
-        setLogLevel,
-        shouldLog,
-    });
-}
-
-/**
- * Creates a logger instance with configurable log level filtering.
- * Each log function is wrapped to respect the current log level setting.
- *
- * @param error - Function to handle error-level logs (required)
- * @param warn - Function to handle warning-level logs (optional, defaults to noop)
- * @param log - Function to handle standard logs (optional, defaults to noop)
- * @param info - Function to handle info-level logs (optional, defaults to noop)
- * @param debug - Function to handle debug-level logs (optional, defaults to noop)
- * @returns A frozen logger object with log methods and level control
- * @throws {ErrorLevelFn} When any provided log function is invalid
- */
-function createLogger(error, warn = noop, log = noop, info = noop, debug = noop) {
-    if (notValidLogFn(error)) {
-        throw createError(notFnMsg('error'));
-    }
-    if (notValidLogFn(warn)) {
-        throw createError(notFnMsg('warn'));
-    }
-    if (notValidLogFn(log)) {
-        throw createError(notFnMsg('log'));
-    }
-    if (notValidLogFn(info)) {
-        throw createError(notFnMsg('info'));
-    }
-    if (notValidLogFn(debug)) {
-        throw createError(notFnMsg('debug'));
-    }
-    const { setLogLevel, getLogLevel, shouldLog } = createLogLevelConfig();
-    const wrapLogFn = (fn, level) => {
-        if (fn === noop)
-            return fn;
-        const condition = () => shouldLog(level);
-        return createConditionalExecutionFunction(createErrorIgnoringFunction(fn), condition);
-    };
-    return freeze({
-        error: wrapLogFn(error, 'error'),
-        warn: wrapLogFn(warn, 'warn'),
-        log: wrapLogFn(log, 'log'),
-        info: wrapLogFn(info, 'info'),
-        debug: wrapLogFn(debug, 'debug'),
-        setLogLevel,
-        getLogLevel,
-    });
-}
-/**
- * Validates whether a given value is a valid log function.
- *
- * @param fn - The value to validate
- * @returns True if the value is not a function (invalid), false if it is valid
- */
-function notValidLogFn(fn) {
-    return getType(fn) !== 'function' && fn !== noop;
-}
-/**
- * Generates an error message for invalid log function parameters.
- *
- * @param label - The name of the log function that failed validation
- * @returns A formatted error message string
- */
-function notFnMsg(label) {
-    return `Cannot create a logger when ${label} is not a function`;
-}
-
-createLogger(error, warn, log, info, debug);
+import { isSafePath } from '../_shared/core/fs/guard/index.esm.js';
+import { getFileStat, isFile, isDirectory, isSymlink, exists } from '../_shared/core/fs/stat/index.esm.js';
+import { normalizePath, normalizeToForwardSlashes, normalizeToNative, removeTrailingSlash, ensureTrailingSlash } from '../_shared/core/path/normalize/index.esm.js';
+import { join, joinPosix } from '../_shared/core/path/join/index.esm.js';
+import { resolvePath, resolveFromWorkspace, resolveRealPath, relativePath, joinPath, isAbsolute, offsetFromRoot } from '../_shared/core/path/resolve/index.esm.js';
+import { pathSegments, getBasename, getDirname, getExtension, getFileNameWithoutExtension, parsePath } from '../_shared/core/path/segments/index.esm.js';
+import { createStructuredError, createConfigError, createFsError, createParseError, createValidationError } from '../_shared/core/errors/structured-errors/index.esm.js';
+import { createCache, clearAllCaches, getCacheCount, unregisterCache, memoize } from '../_shared/core/cache/index.esm.js';
+import { matchGlobPattern, matchesAnyPattern, matchesExact } from '../_shared/core/patterns/glob/index.esm.js';
+import { detectCaseSensitivity, isCaseSensitiveFs, getPlatformInfo, detectPlatform, isWindows } from '../_shared/core/platform/detect/index.esm.js';
+import { LF, CRLF, getLineEnding, getPathSeparator, normalizeLineEndings, detectLineEnding, pathsEqual } from '../_shared/core/platform/line-endings/index.esm.js';
 
 /**
  * Global log level registry.
@@ -432,7 +38,7 @@ let globalLogLevel = null;
  *
  * @param level - The log level to set globally
  *
- * @example
+ * @example Enabling debug logging globally
  * ```typescript
  * import { setGlobalLogLevel } from '@hyperfrontend/project-scope/core'
  *
@@ -450,6 +56,13 @@ function setGlobalLogLevel(level) {
  * Get the current global log level.
  *
  * @returns The global log level, or null if not set
+ *
+ * @example Getting current log level
+ * ```typescript
+ * setGlobalLogLevel('debug')
+ * const level = getGlobalLogLevel()
+ * // => 'debug'
+ * ```
  */
 function getGlobalLogLevel() {
     return globalLogLevel;
@@ -457,6 +70,14 @@ function getGlobalLogLevel() {
 /**
  * Reset the global log level override.
  * Each logger will retain its current level but new loggers will use their default.
+ *
+ * @example Resetting the global log level
+ * ```typescript
+ * setGlobalLogLevel('debug')
+ * // ... perform debugging ...
+ * resetGlobalLogLevel()
+ * // Global override removed, loggers use individual levels
+ * ```
  */
 function resetGlobalLogLevel() {
     globalLogLevel = null;
@@ -494,6 +115,13 @@ function isSensitiveKey(key) {
  *
  * @param obj - Object to sanitize
  * @returns New object with sensitive values redacted
+ *
+ * @example Sanitizing sensitive data
+ * ```typescript
+ * const config = { apiKey: 'secret123', endpoint: 'https://api.example.com' }
+ * const safe = sanitize(config)
+ * // => { apiKey: '[REDACTED]', endpoint: 'https://api.example.com' }
+ * ```
  */
 function sanitize(obj) {
     if (obj === null || obj === undefined) {
@@ -544,7 +172,7 @@ function formatMessage(namespace, message, meta) {
  * @param options - Logger configuration options
  * @returns A configured scoped logger instance
  *
- * @example
+ * @example Creating a scoped logger
  * ```typescript
  * const logger = createScopedLogger('project-scope')
  * logger.setLogLevel('debug')
@@ -581,7 +209,7 @@ function createScopedLogger(namespace, options = {}) {
  * Default logger instance for the project-scope library.
  * Use this for general logging within the library.
  *
- * @example
+ * @example Using the default logger
  * ```typescript
  * import { logger } from '@hyperfrontend/project-scope/core'
  *
@@ -591,60 +219,330 @@ function createScopedLogger(namespace, options = {}) {
  */
 const logger = createScopedLogger('project-scope');
 
-const fsLogger = createScopedLogger('project-scope:fs');
+const encodingLogger = createScopedLogger('project-scope:encoding');
+/** UTF-8 BOM bytes */
+const UTF8_BOM_BYTES = [0xef, 0xbb, 0xbf];
+/** UTF-16 LE BOM bytes */
+const UTF16_LE_BOM_BYTES = [0xff, 0xfe];
+/** UTF-16 BE BOM bytes */
+const UTF16_BE_BOM_BYTES = [0xfe, 0xff];
+/** UTF-8 BOM string */
+const UTF8_BOM = '\uFEFF';
 /**
- * Create a file system error with code and context.
- *
- * @param message - The error message describing what went wrong
- * @param code - The category code for this type of filesystem failure
- * @param context - Additional context including path, operation, and cause
- * @returns A configured Error object with code and context properties
+ * Common binary file signatures.
  */
-function createFileSystemError(message, code, context) {
-    const error = createError(message);
-    defineProperties(error, {
-        code: { value: code, enumerable: true },
-        context: { value: context, enumerable: true },
-    });
-    return error;
-}
+const BINARY_SIGNATURES = [
+    { signature: [0x89, 0x50, 0x4e, 0x47], description: 'PNG' },
+    { signature: [0xff, 0xd8, 0xff], description: 'JPEG' },
+    { signature: [0x47, 0x49, 0x46, 0x38], description: 'GIF' },
+    { signature: [0x50, 0x4b, 0x03, 0x04], description: 'ZIP' },
+    { signature: [0x1f, 0x8b], description: 'GZIP' },
+    { signature: [0x42, 0x5a, 0x68], description: 'BZIP2' },
+    { signature: [0x7f, 0x45, 0x4c, 0x46], description: 'ELF' },
+    { signature: [0x4d, 0x5a], description: 'EXE' },
+    { signature: [0x25, 0x50, 0x44, 0x46], description: 'PDF' },
+];
 /**
- * Read file contents as string.
+ * Detect if content is likely text or binary with encoding information.
  *
- * @param filePath - Path to file
- * @param encoding - File encoding (default: utf-8)
- * @returns File contents as string
- * @throws {Error} If file doesn't exist or can't be read
+ * @param buffer - Buffer to analyze
+ * @returns Encoding information
  *
- * @example
+ * @example Detecting encoding and BOM info
  * ```typescript
- * import { readFileContent } from '@hyperfrontend/project-scope'
- *
- * const content = readFileContent('./package.json')
- * console.log(content) // JSON string
+ * const buffer = readFileSync('./document.txt')
+ * const info = detectEncodingInfo(buffer)
+ * if (info.type === 'text') {
+ *   console.log(`Encoding: ${info.encoding}, BOM: ${info.hasBom}`)
+ * }
  * ```
  */
-function readFileContent(filePath, encoding = 'utf-8') {
-    if (!existsSync(filePath)) {
-        fsLogger.debug('File not found', { path: filePath });
-        throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
-    }
-    try {
-        return readFileSync(filePath, { encoding });
+function detectEncodingInfo(buffer) {
+    encodingLogger.debug('Detecting encoding info', { bufferSize: buffer.length });
+    if (buffer.length >= 3) {
+        if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
+            encodingLogger.debug('Detected UTF-8 BOM');
+            return { type: 'text', encoding: 'utf-8', hasBom: true };
+        }
     }
-    catch (error) {
-        fsLogger.warn('Failed to read file', { path: filePath });
-        throw createFileSystemError(`Failed to read file: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read', cause: error });
+    if (buffer.length >= 2) {
+        if (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1]) {
+            encodingLogger.debug('Detected UTF-16 BE BOM');
+            return { type: 'text', encoding: 'utf16le', hasBom: true };
+        }
+        if (buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) {
+            encodingLogger.debug('Detected UTF-16 LE BOM');
+            return { type: 'text', encoding: 'utf16le', hasBom: true };
+        }
     }
-}
+    for (const { signature, description } of BINARY_SIGNATURES) {
+        if (buffer.length >= signature.length) {
+            let matches = true;
+            for (let i = 0; i < signature.length; i++) {
+                if (buffer[i] !== signature[i]) {
+                    matches = false;
+                    break;
+                }
+            }
+            if (matches) {
+                encodingLogger.debug('Detected binary format by signature', { format: description });
+                return { type: 'binary', format: description };
+            }
+        }
+    }
+    const sampleSize = min(buffer.length, 8000);
+    for (let i = 0; i < sampleSize; i++) {
+        if (buffer[i] === 0) {
+            encodingLogger.debug('Detected binary content (null byte found)', { position: i });
+            return { type: 'binary' };
+        }
+    }
+    encodingLogger.debug('Detected text content (UTF-8 default)');
+    return { type: 'text', encoding: 'utf-8', hasBom: false };
+}
+/**
+ * Detect file encoding from BOM or content analysis.
+ *
+ * @param buffer - Buffer to analyze
+ * @returns Detected encoding, defaults to 'utf-8'
+ *
+ * @example Detecting encoding from buffer
+ * ```typescript
+ * const buffer = readFileSync('./data.txt')
+ * const encoding = detectEncoding(buffer)
+ * const content = buffer.toString(encoding)
+ * ```
+ */
+function detectEncoding(buffer) {
+    if (buffer.length >= 3) {
+        if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
+            return 'utf-8';
+        }
+    }
+    if (buffer.length >= 2) {
+        if (buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) {
+            return 'utf16le';
+        }
+        if (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1]) {
+            return 'utf16le';
+        }
+    }
+    return 'utf-8';
+}
+/**
+ * Check if buffer starts with a BOM.
+ *
+ * @param buffer - Buffer to check
+ * @returns True if buffer has a BOM
+ *
+ * @example Checking if buffer has BOM
+ * ```typescript
+ * const buffer = readFileSync('./file.txt')
+ * if (hasBom(buffer)) {
+ *   // Strip BOM before processing
+ * }
+ * ```
+ */
+function hasBom(buffer) {
+    if (buffer.length >= 3) {
+        if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
+            return true;
+        }
+    }
+    if (buffer.length >= 2) {
+        if ((buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) ||
+            (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1])) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if buffer represents text content.
+ *
+ * @param buffer - Buffer to check
+ * @returns True if the buffer appears to be text
+ *
+ * @example Checking if content is text
+ * ```typescript
+ * const buffer = readFileSync('./unknown-file')
+ * if (isTextFile(buffer)) {
+ *   const content = buffer.toString('utf-8')
+ * }
+ * ```
+ */
+function isTextFile(buffer) {
+    return detectEncodingInfo(buffer).type === 'text';
+}
+
+const convertLogger = createScopedLogger('project-scope:encoding:convert');
+/**
+ * Convert content to UTF-8 string.
+ *
+ * @param content - Buffer or string content
+ * @param sourceEncoding - Source encoding (auto-detected if not provided)
+ * @returns UTF-8 string
+ *
+ * @example Converting a buffer to UTF-8 string
+ * ```typescript
+ * const buffer = Buffer.from('Hello', 'utf-8')
+ * const text = toUtf8(buffer)
+ * // => 'Hello'
+ * ```
+ */
+function toUtf8(content, sourceEncoding = 'utf-8') {
+    if (typeof content === 'string') {
+        return content;
+    }
+    return content.toString(sourceEncoding);
+}
+/**
+ * Convert buffer to string with encoding detection.
+ *
+ * @param content - Buffer to convert
+ * @param encoding - Optional encoding override (auto-detected if not provided)
+ * @returns Converted string
+ * @throws {Error} If content is binary and cannot be converted
+ *
+ * @example Converting file buffer to string with auto-detection
+ * ```typescript
+ * const fileBuffer = readFileSync('./config.json')
+ * const content = bufferToString(fileBuffer)
+ * // => '{"key": "value"}'
+ * ```
+ */
+function bufferToString(content, encoding) {
+    convertLogger.debug('Converting buffer to string', { bufferSize: content.length, providedEncoding: encoding });
+    if (encoding) {
+        convertLogger.debug('Using provided encoding', { encoding });
+        return content.toString(encoding);
+    }
+    const info = detectEncodingInfo(content);
+    if (info.type === 'text') {
+        let offset = 0;
+        if (info.hasBom) {
+            offset = info.encoding === 'utf-8' ? 3 : 2;
+            convertLogger.debug('Stripping BOM from buffer', { encoding: info.encoding, bomOffset: offset });
+        }
+        return content.subarray(offset).toString(info.encoding);
+    }
+    convertLogger.warn('Cannot convert binary content to string', { format: info.type === 'binary' ? info.format : undefined });
+    throw createError('Cannot convert binary content to string');
+}
+/**
+ * Strip BOM from start of string if present.
+ *
+ * @param content - String that may have BOM
+ * @returns String without BOM
+ *
+ * @example Stripping BOM from a string
+ * ```typescript
+ * const withBom = '\ufeffHello World'
+ * const clean = stripBom(withBom)
+ * // => 'Hello World'
+ * ```
+ */
+function stripBom(content) {
+    if (content.charCodeAt(0) === 0xfeff) {
+        return content.slice(1);
+    }
+    return content;
+}
+/**
+ * Add UTF-8 BOM to string if not present.
+ *
+ * @param content - String to add BOM to
+ * @returns String with BOM
+ *
+ * @example Adding UTF-8 BOM to content
+ * ```typescript
+ * const content = 'Hello World'
+ * const withBom = addBom(content)
+ * // => '\ufeffHello World'
+ * ```
+ */
+function addBom(content) {
+    if (content.charCodeAt(0) === 0xfeff) {
+        return content;
+    }
+    return UTF8_BOM + content;
+}
+
+const fsLogger = createScopedLogger('project-scope:fs');
+/**
+ * Create a file system error with code and context.
+ *
+ * @param message - The error message describing what went wrong
+ * @param code - The category code for this type of filesystem failure
+ * @param context - Additional context including path, operation, and cause
+ * @returns A configured Error object with code and context properties
+ *
+ * @example Creating a file system error
+ * ```typescript
+ * throw createFileSystemError(
+ *   'Cannot read file',
+ *   'FS_READ_ERROR',
+ *   { path: './missing.txt', operation: 'read' }
+ * )
+ * ```
+ */
+function createFileSystemError(message, code, context) {
+    const error = createError(message);
+    defineProperties(error, {
+        code: { value: code, enumerable: true },
+        context: { value: context, enumerable: true },
+    });
+    return error;
+}
+/**
+ * Read file contents as string.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents as string
+ * @throws {Error} If file doesn't exist or can't be read
+ *
+ * @example Reading file contents
+ * ```typescript
+ * import { readFileContent } from '@hyperfrontend/project-scope'
+ *
+ * const content = readFileContent('./package.json')
+ * console.log(content) // JSON string
+ * ```
+ */
+function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
+    if (!existsSync(filePath)) {
+        fsLogger.debug('File not found', { path: filePath });
+        throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
+    }
+    try {
+        return readFileSync(filePath, { encoding });
+    }
+    catch (error) {
+        fsLogger.warn('Failed to read file', { path: filePath });
+        throw createFileSystemError(`Failed to read file: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read', cause: error });
+    }
+}
 /**
  * Read file contents as Buffer.
  *
  * @param filePath - Path to file
  * @returns File contents as Buffer
  * @throws {Error} If file doesn't exist or can't be read
+ *
+ * @example Reading file as buffer
+ * ```typescript
+ * const buffer = readFileBuffer('./image.png')
+ * console.log(buffer.length) // File size in bytes
+ * ```
  */
 function readFileBuffer(filePath) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
     }
@@ -661,9 +559,17 @@ function readFileBuffer(filePath) {
  * @param filePath - Path to file
  * @param encoding - File encoding (default: utf-8)
  * @returns File contents or null if file doesn't exist
+ *
+ * @example Reading file if it exists
+ * ```typescript
+ * const content = readFileIfExists('./optional-config.json')
+ * if (content) {
+ *   // File existed, use content
+ * }
+ * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {
@@ -682,7 +588,7 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
  * @returns Parsed JSON object
  * @throws {Error} If file doesn't exist (when no default provided) or contains invalid JSON
  *
- * @example
+ * @example Reading JSON file
  * ```typescript
  * import { readJsonFile } from '@hyperfrontend/project-scope'
  *
@@ -695,6 +601,9 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
  * ```
  */
 function readJsonFile(filePath, options) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         if (options && 'default' in options) {
             fsLogger.debug('JSON file not found, using default', { path: filePath });
@@ -725,9 +634,16 @@ function readJsonFile(filePath, options) {
  *
  * @param filePath - Path to JSON file
  * @returns Parsed JSON object or null if file doesn't exist or is invalid
+ *
+ * @example Reading JSON file if it exists
+ * ```typescript
+ * interface UserSettings { theme: string }
+ * const settings = readJsonFileIfExists<UserSettings>('./user-settings.json')
+ * const theme = settings?.theme ?? 'default'
+ * ```
  */
 function readJsonFileIfExists(filePath) {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {
@@ -739,194 +655,17 @@ function readJsonFileIfExists(filePath) {
     }
 }
 
-const fsWriteLogger = createScopedLogger('project-scope:fs:write');
-/**
- * Ensure directory exists, create recursively if not.
- *
- * @param dirPath - Directory path to ensure exists
- */
-function ensureDir(dirPath) {
-    if (!existsSync(dirPath)) {
-        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
-        mkdirSync(dirPath, { recursive: true });
-    }
-}
+const fsDirLogger = createScopedLogger('project-scope:fs:dir');
 /**
- * Write string content to file.
- * Creates parent directories if needed.
+ * List immediate contents of a directory.
  *
- * @param filePath - Absolute or relative path to the target file
- * @param content - String content to write to the file
- * @param options - Optional write configuration (encoding, mode)
- * @throws {Error} If write fails
+ * @param dirPath - Absolute or relative path to the directory
+ * @returns Array of entries with metadata for each file/directory
+ * @throws {Error} If directory doesn't exist or isn't a directory
  *
- * @example
+ * @example Listing directory contents
  * ```typescript
- * import { writeFileContent } from '@hyperfrontend/project-scope'
- *
- * // Write a simple text file
- * writeFileContent('./output/data.txt', 'Hello, World!')
- *
- * // Write with custom encoding
- * writeFileContent('./output/data.txt', 'Content', { encoding: 'utf-8' })
- * ```
- */
-function writeFileContent(filePath, content, options) {
-    try {
-        fsWriteLogger.debug('Writing file content', { path: filePath, size: content.length, encoding: options?.encoding ?? 'utf-8' });
-        ensureDir(dirname(filePath));
-        writeFileSync(filePath, content, {
-            encoding: options?.encoding ?? 'utf-8',
-            mode: options?.mode,
-        });
-        fsWriteLogger.debug('File written successfully', { path: filePath });
-    }
-    catch (error) {
-        fsWriteLogger.warn('Failed to write file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
-        throw createFileSystemError(`Failed to write file: ${filePath}`, 'FS_WRITE_ERROR', { path: filePath, operation: 'write', cause: error });
-    }
-}
-/**
- * Write Buffer to file.
- * Creates parent directories if needed.
- *
- * @param filePath - Absolute or relative path to the target file
- * @param content - Buffer containing binary data to write
- * @param options - Optional write configuration (mode)
- * @throws {Error} If write fails
- */
-function writeFileBuffer(filePath, content, options) {
-    try {
-        fsWriteLogger.debug('Writing file buffer', { path: filePath, size: content.length });
-        ensureDir(dirname(filePath));
-        writeFileSync(filePath, content, { mode: options?.mode });
-        fsWriteLogger.debug('Buffer written successfully', { path: filePath });
-    }
-    catch (error) {
-        fsWriteLogger.warn('Failed to write buffer', { path: filePath, error: error instanceof Error ? error.message : String(error) });
-        throw createFileSystemError(`Failed to write file: ${filePath}`, 'FS_WRITE_ERROR', { path: filePath, operation: 'write', cause: error });
-    }
-}
-/**
- * Write JSON data to file with formatting.
- * Creates parent directories if needed.
- *
- * @param filePath - Absolute or relative path to the target JSON file
- * @param data - Object or value to serialize as JSON
- * @param options - Optional write configuration (indent, encoding, mode)
- * @throws {Error} If write fails
- *
- * @example
- * ```typescript
- * import { writeJsonFile } from '@hyperfrontend/project-scope'
- *
- * // Write object to JSON file
- * writeJsonFile('./config.json', { port: 3000, debug: true })
- *
- * // Write with custom indentation
- * writeJsonFile('./config.json', data, { indent: 4 })
- * ```
- */
-function writeJsonFile(filePath, data, options) {
-    try {
-        fsWriteLogger.debug('Writing JSON file', { path: filePath, indent: options?.indent ?? 2 });
-        const indent = options?.indent ?? 2;
-        const content = stringify(data, null, indent) + '\n';
-        writeFileContent(filePath, content, options);
-        fsWriteLogger.debug('JSON file written successfully', { path: filePath });
-    }
-    catch (error) {
-        if (error?.code === 'FS_WRITE_ERROR') {
-            throw error;
-        }
-        fsWriteLogger.warn('Failed to write JSON file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
-        throw createFileSystemError(`Failed to write JSON file: ${filePath}`, 'FS_WRITE_ERROR', {
-            path: filePath,
-            operation: 'write',
-            cause: error,
-        });
-    }
-}
-
-/**
- * Get file stats with error handling.
- *
- * @param filePath - Path to file
- * @param followSymlinks - Whether to follow symlinks (default: true)
- * @returns File stats or null if path doesn't exist
- */
-function getFileStat(filePath, followSymlinks = true) {
-    if (!existsSync(filePath)) {
-        return null;
-    }
-    try {
-        const stat = followSymlinks ? statSync(filePath) : lstatSync(filePath);
-        return {
-            isFile: stat.isFile(),
-            isDirectory: stat.isDirectory(),
-            isSymlink: stat.isSymbolicLink(),
-            size: stat.size,
-            created: stat.birthtime,
-            modified: stat.mtime,
-            accessed: stat.atime,
-            mode: stat.mode,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Check if path is a file.
- *
- * @param filePath - Path to check
- * @returns True if path is a file
- */
-function isFile(filePath) {
-    const stats = getFileStat(filePath);
-    return stats?.isFile ?? false;
-}
-/**
- * Check if path is a directory.
- *
- * @param dirPath - Path to check
- * @returns True if path is a directory
- */
-function isDirectory(dirPath) {
-    const stats = getFileStat(dirPath);
-    return stats?.isDirectory ?? false;
-}
-/**
- * Check if path is a symbolic link.
- *
- * @param linkPath - Path to check
- * @returns True if path is a symlink
- */
-function isSymlink(linkPath) {
-    const stats = getFileStat(linkPath, false);
-    return stats?.isSymlink ?? false;
-}
-/**
- * Check if path exists.
- *
- * @param filePath - Path to check
- * @returns True if path exists
- */
-function exists(filePath) {
-    return existsSync(filePath);
-}
-
-const fsDirLogger = createScopedLogger('project-scope:fs:dir');
-/**
- * List immediate contents of a directory.
- *
- * @param dirPath - Absolute or relative path to the directory
- * @returns Array of entries with metadata for each file/directory
- * @throws {Error} If directory doesn't exist or isn't a directory
- *
- * @example
- * ```typescript
- * import { readDirectory } from '@hyperfrontend/project-scope'
+ * import { readDirectory } from '@hyperfrontend/project-scope'
  *
  * const entries = readDirectory('./src')
  * for (const entry of entries) {
@@ -971,7 +710,7 @@ function readDirectory(dirPath) {
  * @param options - Configuration for depth limit, hidden files, and symlinks
  * @returns Flat array of all entries found during traversal
  *
- * @example
+ * @example Recursive directory listing with options
  * ```typescript
  * import { readDirectoryRecursive } from '@hyperfrontend/project-scope'
  *
@@ -1032,6 +771,15 @@ function readDirectoryRecursive(dirPath, options) {
  * @param dirPath - Path where the directory should be created
  * @param options - Creation options
  * @param options.recursive - Create parent directories if missing (default: true)
+ *
+ * @example Creating directories
+ * ```typescript
+ * // Create nested directories
+ * createDirectory('./output/reports/2024')
+ *
+ * // Create single directory without parents
+ * createDirectory('./logs', { recursive: false })
+ * ```
  */
 function createDirectory(dirPath, options) {
     const recursive = options?.recursive ?? true;
@@ -1045,6 +793,15 @@ function createDirectory(dirPath, options) {
  * @param options - Removal configuration
  * @param options.recursive - Delete directory contents recursively
  * @param options.force - Ignore errors if directory doesn't exist
+ *
+ * @example Removing directories
+ * ```typescript
+ * // Remove directory and all contents
+ * removeDirectory('./temp', { recursive: true })
+ *
+ * // Safe removal (no error if missing)
+ * removeDirectory('./cache', { recursive: true, force: true })
+ * ```
  */
 function removeDirectory(dirPath, options) {
     fsDirLogger.debug('Removing directory', { path: dirPath, recursive: options?.recursive, force: options?.force });
@@ -1054,227 +811,6 @@ function removeDirectory(dirPath, options) {
     });
 }
 
-/**
- * Join path segments.
- * Uses platform-specific separators (e.g., / or \).
- *
- * @param paths - Path segments to join
- * @returns Joined path
- */
-function join(...paths) {
-    return join$1(...paths);
-}
-/**
- * Join path segments using POSIX separators (/).
- * Always uses forward slashes regardless of platform.
- *
- * @param paths - Path segments to join
- * @returns Joined path with forward slashes
- */
-function joinPosix(...paths) {
-    return posix.join(...paths);
-}
-
-/**
- * Normalize path separators to forward slashes.
- *
- * @param filePath - Path to normalize
- * @returns Normalized path with forward slashes
- */
-function normalizePath(filePath) {
-    if (!filePath)
-        return '';
-    const normalized = normalize(filePath);
-    return sep === '\\' ? normalized.replace(/\\/g, '/') : normalized;
-}
-/**
- * Convert path separators to forward slashes using POSIX style.
- * Resolves `.` and `..` segments for cross-platform configuration.
- *
- * @param filePath - The input path to convert
- * @returns Path with forward slashes and resolved segments
- */
-function normalizeToForwardSlashes(filePath) {
-    if (!filePath)
-        return '';
-    return normalize(filePath).split(sep).join('/');
-}
-/**
- * Convert path to use the operating system's native separator.
- *
- * @param filePath - The input path to convert
- * @returns Path with native separators (backslash on Windows, forward slash elsewhere)
- */
-function normalizeToNative(filePath) {
-    if (!filePath)
-        return '';
-    return normalize(filePath.replace(/[/\\]/g, sep));
-}
-/**
- * Strip any trailing forward or back slashes from a path.
- *
- * @param filePath - Path that may have trailing slashes
- * @returns Path with trailing slashes removed
- */
-function removeTrailingSlash(filePath) {
-    let i = filePath.length;
-    while (i > 0 && (filePath[i - 1] === '/' || filePath[i - 1] === '\\')) {
-        i--;
-    }
-    return filePath.slice(0, i);
-}
-/**
- * Append a forward slash to the path if not already present.
- *
- * @param filePath - Path to process
- * @returns Path with trailing forward slash
- */
-function ensureTrailingSlash(filePath) {
-    const normalized = removeTrailingSlash(filePath);
-    return normalized + '/';
-}
-
-/**
- * Resolve path segments to an absolute path.
- *
- * @param segments - Path segments to resolve
- * @returns Resolved absolute path with normalized separators
- */
-function resolvePath(...segments) {
-    return normalizePath(resolve(...segments));
-}
-/**
- * Resolve path relative to workspace root.
- *
- * @param workspaceRoot - Workspace root directory
- * @param segments - Path segments relative to workspace
- * @returns Resolved absolute path with normalized separators
- */
-function resolveFromWorkspace(workspaceRoot, ...segments) {
-    return normalizePath(resolve(workspaceRoot, ...segments));
-}
-/**
- * Resolve symlinks to real path.
- *
- * @param filePath - Path to resolve
- * @returns Real path or null if path doesn't exist
- */
-function resolveRealPath(filePath) {
-    if (!exists(filePath)) {
-        return null;
-    }
-    try {
-        return normalizePath(realpathSync(filePath));
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Compute the normalized path from source directory to target.
- *
- * @param from - Source path (base directory)
- * @param to - Target path to reach
- * @returns Relative path from source to target with forward slashes
- */
-function relativePath(from, to) {
-    return normalizePath(relative(from, to));
-}
-/**
- * Join path segments.
- *
- * @param segments - Path segments to join
- * @returns Joined path with normalized separators
- */
-function joinPath(...segments) {
-    return normalizePath(join$1(...segments));
-}
-/**
- * Check if path is absolute.
- *
- * @param filePath - Path to check
- * @returns True if path is absolute
- */
-function isAbsolute(filePath) {
-    return isAbsolute$1(filePath);
-}
-/**
- * Calculate offset from root (e.g., "../../../").
- *
- * @param filePath - Path to calculate offset for
- * @returns Relative offset path (e.g., "../../")
- */
-function offsetFromRoot(filePath) {
-    const segments = normalizePath(filePath).split('/').filter(Boolean);
-    if (segments.length === 0)
-        return '';
-    return segments.map(() => '..').join('/') + '/';
-}
-
-/**
- * Split path into segments.
- *
- * @param filePath - Path to split
- * @returns Array of path segments
- */
-function pathSegments(filePath) {
-    return filePath.split(/[/\\]/).filter((segment) => segment.length > 0);
-}
-/**
- * Get basename of path.
- *
- * @param filePath - Path to extract basename from
- * @param ext - Optional extension to strip
- * @returns Basename of path
- */
-function getBasename(filePath, ext) {
-    return basename(filePath, ext);
-}
-/**
- * Get directory name of path.
- *
- * @param filePath - Path to extract directory from
- * @returns Directory name
- */
-function getDirname(filePath) {
-    return normalizePath(dirname(filePath));
-}
-/**
- * Get file extension (including dot).
- *
- * @param filePath - Path to extract extension from
- * @returns Extension including dot (e.g., '.ts')
- */
-function getExtension(filePath) {
-    return extname(filePath);
-}
-/**
- * Get filename without extension.
- *
- * @param filePath - Path to extract name from
- * @returns Filename without extension
- */
-function getFileNameWithoutExtension(filePath) {
-    const parsed = parse$1(filePath);
-    return parsed.name;
-}
-/**
- * Parse path into components.
- *
- * @param filePath - Path to parse
- * @returns Parsed path components
- */
-function parsePath(filePath) {
-    const parsed = parse$1(filePath);
-    return {
-        root: parsed.root,
-        dir: normalizePath(parsed.dir),
-        base: parsed.base,
-        ext: parsed.ext,
-        name: parsed.name,
-    };
-}
-
 const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
 /**
  * Generic upward directory traversal.
@@ -1283,6 +819,15 @@ const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
  * @param startPath - Starting directory
  * @param predicate - Function to test each directory
  * @returns First matching directory or null
+ *
+ * @example Finding directory containing README
+ * ```typescript
+ * // Find first directory containing a README
+ * const readmeDir = traverseUpward('./src/utils', (dir) =>
+ *   existsSync(join(dir, 'README.md'))
+ * )
+ * // => '/project' or null
+ * ```
  */
 function traverseUpward(startPath, predicate) {
     fsTraversalLogger.debug('Starting upward traversal', { startPath });
@@ -1308,6 +853,17 @@ function traverseUpward(startPath, predicate) {
  * @param startPath - Starting directory
  * @param markers - Array of marker file names to search for
  * @returns First directory containing any marker, or null
+ *
+ * @example Finding project root by marker files
+ * ```typescript
+ * // Find project root by looking for common marker files
+ * const projectRoot = locateByMarkers('./src/components', [
+ *   'package.json',
+ *   'nx.json',
+ *   'tsconfig.base.json'
+ * ])
+ * // => '/workspace/my-project'
+ * ```
  */
 function locateByMarkers(startPath, markers) {
     fsTraversalLogger.debug('Locating by markers', { startPath, markers });
@@ -1323,912 +879,139 @@ function locateByMarkers(startPath, markers) {
  * @param startPath - Starting directory
  * @param test - Function to test if directory matches criteria
  * @returns Matching directory path or null
+ *
+ * @example Finding directory with specific config
+ * ```typescript
+ * // Find directory with a specific config
+ * const configDir = findUpwardWhere('./deep/nested/path', (dir) =>
+ *   existsSync(join(dir, '.eslintrc.js'))
+ * )
+ * ```
  */
 function findUpwardWhere(startPath, test) {
     fsTraversalLogger.debug('Finding upward where condition met', { startPath });
     return traverseUpward(startPath, test);
 }
 
-const encodingLogger = createScopedLogger('project-scope:encoding');
-/** UTF-8 BOM bytes */
-const UTF8_BOM_BYTES = [0xef, 0xbb, 0xbf];
-/** UTF-16 LE BOM bytes */
-const UTF16_LE_BOM_BYTES = [0xff, 0xfe];
-/** UTF-16 BE BOM bytes */
-const UTF16_BE_BOM_BYTES = [0xfe, 0xff];
-/** UTF-8 BOM string */
-const UTF8_BOM = '\uFEFF';
+const fsWriteLogger = createScopedLogger('project-scope:fs:write');
 /**
- * Common binary file signatures.
+ * Ensure directory exists, create recursively if not.
+ *
+ * @param dirPath - Directory path to ensure exists
+ *
+ * @example Ensuring directory exists
+ * ```typescript
+ * ensureDir('./output/reports')
+ * // Directory now exists (created if missing)
+ * ```
  */
-const BINARY_SIGNATURES = [
-    { signature: [0x89, 0x50, 0x4e, 0x47], description: 'PNG' },
-    { signature: [0xff, 0xd8, 0xff], description: 'JPEG' },
-    { signature: [0x47, 0x49, 0x46, 0x38], description: 'GIF' },
-    { signature: [0x50, 0x4b, 0x03, 0x04], description: 'ZIP' },
-    { signature: [0x1f, 0x8b], description: 'GZIP' },
-    { signature: [0x42, 0x5a, 0x68], description: 'BZIP2' },
-    { signature: [0x7f, 0x45, 0x4c, 0x46], description: 'ELF' },
-    { signature: [0x4d, 0x5a], description: 'EXE' },
-    { signature: [0x25, 0x50, 0x44, 0x46], description: 'PDF' },
-];
-/**
- * Detect if content is likely text or binary with encoding information.
- *
- * @param buffer - Buffer to analyze
- * @returns Encoding information
- */
-function detectEncodingInfo(buffer) {
-    encodingLogger.debug('Detecting encoding info', { bufferSize: buffer.length });
-    if (buffer.length >= 3) {
-        if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
-            encodingLogger.debug('Detected UTF-8 BOM');
-            return { type: 'text', encoding: 'utf-8', hasBom: true };
-        }
-    }
-    if (buffer.length >= 2) {
-        if (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1]) {
-            encodingLogger.debug('Detected UTF-16 BE BOM');
-            return { type: 'text', encoding: 'utf16le', hasBom: true };
-        }
-        if (buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) {
-            encodingLogger.debug('Detected UTF-16 LE BOM');
-            return { type: 'text', encoding: 'utf16le', hasBom: true };
-        }
-    }
-    for (const { signature, description } of BINARY_SIGNATURES) {
-        if (buffer.length >= signature.length) {
-            let matches = true;
-            for (let i = 0; i < signature.length; i++) {
-                if (buffer[i] !== signature[i]) {
-                    matches = false;
-                    break;
-                }
-            }
-            if (matches) {
-                encodingLogger.debug('Detected binary format by signature', { format: description });
-                return { type: 'binary', format: description };
-            }
-        }
-    }
-    const sampleSize = min(buffer.length, 8000);
-    for (let i = 0; i < sampleSize; i++) {
-        if (buffer[i] === 0) {
-            encodingLogger.debug('Detected binary content (null byte found)', { position: i });
-            return { type: 'binary' };
-        }
-    }
-    encodingLogger.debug('Detected text content (UTF-8 default)');
-    return { type: 'text', encoding: 'utf-8', hasBom: false };
-}
-/**
- * Detect file encoding from BOM or content analysis.
- *
- * @param buffer - Buffer to analyze
- * @returns Detected encoding, defaults to 'utf-8'
- */
-function detectEncoding(buffer) {
-    if (buffer.length >= 3) {
-        if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
-            return 'utf-8';
-        }
-    }
-    if (buffer.length >= 2) {
-        if (buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) {
-            return 'utf16le';
-        }
-        if (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1]) {
-            return 'utf16le';
-        }
-    }
-    return 'utf-8';
-}
-/**
- * Check if buffer starts with a BOM.
- *
- * @param buffer - Buffer to check
- * @returns True if buffer has a BOM
- */
-function hasBom(buffer) {
-    if (buffer.length >= 3) {
-        if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
-            return true;
-        }
-    }
-    if (buffer.length >= 2) {
-        if ((buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) ||
-            (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1])) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Check if buffer represents text content.
- *
- * @param buffer - Buffer to check
- * @returns True if the buffer appears to be text
- */
-function isTextFile(buffer) {
-    return detectEncodingInfo(buffer).type === 'text';
-}
-/**
- * Check if buffer represents binary content.
- *
- * @param buffer - Buffer to check
- * @returns True if the buffer appears to be binary
- */
-function isBinaryFile(buffer) {
-    return detectEncodingInfo(buffer).type === 'binary';
-}
-
-const convertLogger = createScopedLogger('project-scope:encoding:convert');
-/**
- * Convert content to UTF-8 string.
- *
- * @param content - Buffer or string content
- * @param sourceEncoding - Source encoding (auto-detected if not provided)
- * @returns UTF-8 string
- */
-function toUtf8(content, sourceEncoding = 'utf-8') {
-    if (typeof content === 'string') {
-        return content;
-    }
-    return content.toString(sourceEncoding);
-}
-/**
- * Convert buffer to string with encoding detection.
- *
- * @param content - Buffer to convert
- * @param encoding - Optional encoding override (auto-detected if not provided)
- * @returns Converted string
- * @throws {Error} If content is binary and cannot be converted
- */
-function bufferToString(content, encoding) {
-    convertLogger.debug('Converting buffer to string', { bufferSize: content.length, providedEncoding: encoding });
-    if (encoding) {
-        convertLogger.debug('Using provided encoding', { encoding });
-        return content.toString(encoding);
-    }
-    const info = detectEncodingInfo(content);
-    if (info.type === 'text') {
-        let offset = 0;
-        if (info.hasBom) {
-            offset = info.encoding === 'utf-8' ? 3 : 2;
-            convertLogger.debug('Stripping BOM from buffer', { encoding: info.encoding, bomOffset: offset });
-        }
-        return content.subarray(offset).toString(info.encoding);
-    }
-    convertLogger.warn('Cannot convert binary content to string', { format: info.type === 'binary' ? info.format : undefined });
-    throw createError('Cannot convert binary content to string');
-}
-/**
- * Strip BOM from start of string if present.
- *
- * @param content - String that may have BOM
- * @returns String without BOM
- */
-function stripBom(content) {
-    if (content.charCodeAt(0) === 0xfeff) {
-        return content.slice(1);
-    }
-    return content;
-}
-/**
- * Add UTF-8 BOM to string if not present.
- *
- * @param content - String to add BOM to
- * @returns String with BOM
- */
-function addBom(content) {
-    if (content.charCodeAt(0) === 0xfeff) {
-        return content;
-    }
-    return UTF8_BOM + content;
-}
-
-/**
- * Cached platform info (computed once).
- */
-let cachedPlatformInfo = null;
-/**
- * Cached case sensitivity result.
- */
-let cachedCaseSensitive = null;
-/**
- * Detect if file system is case sensitive.
- *
- * @returns True if file system is case-sensitive
- */
-function detectCaseSensitivity() {
-    if (cachedCaseSensitive !== null) {
-        return cachedCaseSensitive;
-    }
-    if (process.platform === 'win32') {
-        cachedCaseSensitive = false;
-        return false;
-    }
-    if (process.platform === 'darwin') {
-        cachedCaseSensitive = false;
-        return false;
-    }
-    let secureTestDir = null;
-    try {
-        secureTestDir = mkdtempSync(join$1(tmpdir(), 'case-sensitivity-test-'));
-        const testFile = join$1(secureTestDir, 'A');
-        const testFileLower = join$1(secureTestDir, 'a');
-        writeFileSync(testFile, '');
-        cachedCaseSensitive = !existsSync(testFileLower);
-        unlinkSync(testFile);
-    }
-    catch {
-        cachedCaseSensitive = true;
-    }
-    finally {
-        if (secureTestDir) {
-            try {
-                rmdirSync(secureTestDir);
-            }
-            catch {
-                // Ignore cleanup errors
-            }
-        }
-    }
-    return cachedCaseSensitive;
-}
-/**
- * Check if file system is case-sensitive.
- *
- * @returns True if file system is case-sensitive
- */
-function isCaseSensitiveFs() {
-    return detectCaseSensitivity();
-}
-/**
- * Get comprehensive platform information.
- *
- * @returns Platform information object (cached after first call)
- */
-function getPlatformInfo() {
-    if (cachedPlatformInfo) {
-        return cachedPlatformInfo;
-    }
-    const os = platform();
-    const archInfo = arch();
-    let osName;
-    switch (os) {
-        case 'win32':
-            osName = 'win32';
-            break;
-        case 'darwin':
-            osName = 'darwin';
-            break;
-        case 'linux':
-            osName = 'linux';
-            break;
-        case 'freebsd':
-            osName = 'freebsd';
-            break;
-        case 'sunos':
-            osName = 'sunos';
-            break;
-        case 'aix':
-            osName = 'aix';
-            break;
-        default:
-            osName = 'other';
-    }
-    cachedPlatformInfo = {
-        os: osName,
-        arch: archInfo,
-        nodeVersion: process.versions.node,
-        isWindows: osName === 'win32',
-        isMac: osName === 'darwin',
-        isLinux: osName === 'linux',
-        caseSensitive: detectCaseSensitivity(),
-        pathSeparator: osName === 'win32' ? '\\' : '/',
-        lineEnding: osName === 'win32' ? '\r\n' : '\n',
-    };
-    return cachedPlatformInfo;
-}
-/**
- * Detect current platform.
- *
- * @returns Platform information object
- */
-function detectPlatform() {
-    return getPlatformInfo();
-}
-/**
- * Check if running on Windows.
- *
- * @returns True if running on Windows
- */
-function isWindows() {
-    return process.platform === 'win32';
-}
-/**
- * Check if running on macOS.
- *
- * @returns True if running on macOS
- */
-function isMac() {
-    return process.platform === 'darwin';
-}
-/**
- * Check if running on Linux.
- *
- * @returns True if running on Linux
- */
-function isLinux() {
-    return process.platform === 'linux';
-}
-
-/** Unix line ending */
-const LF = '\n';
-/** Windows line ending */
-const CRLF = '\r\n';
-/**
- * Get platform-appropriate line ending.
- *
- * @returns Line ending for current platform
- */
-function getLineEnding() {
-    return isWindows() ? CRLF : LF;
-}
-/**
- * Get platform-appropriate path separator.
- *
- * @returns Path separator for current platform
- */
-function getPathSeparator() {
-    return isWindows() ? '\\' : '/';
-}
-/**
- * Normalize line endings in content.
- *
- * @param content - Content to normalize
- * @param style - Target line ending style ('lf', 'crlf', or 'auto' for platform default)
- * @returns Content with normalized line endings
- */
-function normalizeLineEndings(content, style = 'lf') {
-    let target;
-    if (style === 'auto') {
-        target = isWindows() ? CRLF : LF;
-    }
-    else {
-        target = style === 'crlf' ? CRLF : LF;
-    }
-    const normalized = content.replace(/\r\n/g, LF).replace(/\r/g, LF);
-    if (target === LF) {
-        return normalized;
-    }
-    return normalized.replace(/\n/g, target);
-}
-/**
- * Detect line ending style used in content.
- *
- * @param content - Content to analyze
- * @returns Detected line ending style
- */
-function detectLineEnding(content) {
-    const hasCRLF = content.includes(CRLF);
-    const hasLFOnly = content.includes('\n') && content.replace(/\r\n/g, '').includes('\n');
-    if (hasCRLF && hasLFOnly)
-        return 'mixed';
-    if (hasCRLF)
-        return 'crlf';
-    if (content.includes('\n'))
-        return 'lf';
-    return 'none';
-}
-/**
- * Compare paths with case sensitivity awareness.
- *
- * @param path1 - First path
- * @param path2 - Second path
- * @returns True if paths are equal (respecting case sensitivity)
- */
-function pathsEqual(path1, path2) {
-    const caseSensitive = detectCaseSensitivity();
-    if (caseSensitive) {
-        return path1 === path2;
+function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
+        mkdirSync(dirPath, { recursive: true });
     }
-    return path1.toLowerCase() === path2.toLowerCase();
 }
-
 /**
- * Create a structured error with code and optional context.
+ * Write string content to file.
+ * Creates parent directories if needed.
  *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information about the error
- * @returns Structured error instance with code and context properties
+ * @param filePath - Absolute or relative path to the target file
+ * @param content - String content to write to the file
+ * @param options - Optional write configuration (encoding, mode)
+ * @throws {Error} If write fails
  *
- * @example
+ * @example Writing text content to file
  * ```typescript
- * import { createStructuredError } from '@hyperfrontend/project-scope'
- *
- * throw createStructuredError(
- *   'Configuration file not found',
- *   'CONFIG_NOT_FOUND',
- *   { path: './config.json', searched: ['./config.json', './settings.json'] }
- * )
- * ```
- */
-function createStructuredError(message, code, context) {
-    const error = createError(message);
-    error.code = code;
-    error.context = context ?? {};
-    return error;
-}
-/**
- * Create a configuration-related error.
- *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information (e.g., file path, config key)
- * @returns Structured error instance tagged with type 'config'
- */
-function createConfigError(message, code, context) {
-    return createStructuredError(message, code, { ...context, type: 'config' });
-}
-/**
- * Create a filesystem-related error.
- *
- * @param message - The human-readable error message
- * @param code - The filesystem error code (e.g., ENOENT for not found, EACCES for access denied)
- * @param context - Additional contextual information (e.g., file path, operation attempted)
- * @returns Structured error instance tagged with type 'fs'
- */
-function createFsError(message, code, context) {
-    return createStructuredError(message, code, { ...context, type: 'fs' });
-}
-/**
- * Create a parsing-related error.
- *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information (e.g., file path, line/column numbers, expected format)
- * @returns Structured error instance tagged with type 'parse'
- */
-function createParseError(message, code, context) {
-    return createStructuredError(message, code, { ...context, type: 'parse' });
-}
-/**
- * Create a validation-related error.
- *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information (e.g., field name, actual vs expected values)
- * @returns Structured error instance tagged with type 'validation'
- */
-function createValidationError(message, code, context) {
-    return createStructuredError(message, code, { ...context, type: 'validation' });
-}
-
-/**
- * Match path against glob pattern using safe character iteration.
- * Avoids regex to prevent ReDoS attacks.
- *
- * Supported patterns:
- * - * matches any characters except /
- * - ** matches any characters including /
- * - ? matches exactly one character except /
- * - {a,b,c} matches any of the alternatives
- *
- * @param path - The filesystem path to test against the pattern
- * @param pattern - The glob pattern to match against
- * @returns True if path matches pattern
+ * import { writeFileContent } from '@hyperfrontend/project-scope'
  *
- * @example
- * ```typescript
- * import { matchGlobPattern } from '@hyperfrontend/project-scope'
+ * // Write a simple text file
+ * writeFileContent('./output/data.txt', 'Hello, World!')
  *
- * matchGlobPattern('src/utils/helper.ts', '\*\*\/*.ts')     // true
- * matchGlobPattern('test.spec.ts', '\*.spec.ts')          // true
- * matchGlobPattern('config.json', '\*.{json,yaml}')       // true
- * matchGlobPattern('src/index.ts', 'src/\*.ts')           // true
+ * // Write with custom encoding
+ * writeFileContent('./output/data.txt', 'Content', { encoding: 'utf-8' })
  * ```
  */
-function matchGlobPattern(path, pattern) {
-    return matchSegments(path.split('/'), pattern.split('/'), 0, 0);
-}
-/**
- * Internal recursive function to match path segments against pattern segments.
- *
- * @param pathParts - Array of path segments split by '/'
- * @param patternParts - Array of pattern segments split by '/'
- * @param pathIdx - Current index in pathParts being examined
- * @param patternIdx - Current index in patternParts being examined
- * @returns True if remaining segments match
- */
-function matchSegments(pathParts, patternParts, pathIdx, patternIdx) {
-    if (pathIdx === pathParts.length && patternIdx === patternParts.length) {
-        return true;
-    }
-    if (patternIdx >= patternParts.length) {
-        return false;
-    }
-    const patternPart = patternParts[patternIdx];
-    if (patternPart === '**') {
-        for (let i = pathIdx; i <= pathParts.length; i++) {
-            if (matchSegments(pathParts, patternParts, i, patternIdx + 1)) {
-                return true;
-            }
-        }
-        return false;
-    }
-    if (pathIdx >= pathParts.length) {
-        return false;
-    }
-    const pathPart = pathParts[pathIdx];
-    if (matchSegment(pathPart, patternPart)) {
-        return matchSegments(pathParts, patternParts, pathIdx + 1, patternIdx + 1);
-    }
-    return false;
-}
-/**
- * Match a single path segment against a pattern segment.
- * Handles *, ?, and {a,b,c} patterns.
- *
- * @param text - The path segment text to match
- * @param pattern - The pattern segment to match against
- * @returns True if the text matches the pattern
- */
-function matchSegment(text, pattern) {
-    let textIdx = 0;
-    let patternIdx = 0;
-    while (patternIdx < pattern.length) {
-        const char = pattern[patternIdx];
-        if (char === '*') {
-            patternIdx++;
-            if (patternIdx === pattern.length) {
-                return true;
-            }
-            for (let i = textIdx; i <= text.length; i++) {
-                if (matchSegmentFrom(text, i, pattern, patternIdx)) {
-                    return true;
-                }
-            }
-            return false;
-        }
-        else if (char === '?') {
-            if (textIdx >= text.length) {
-                return false;
-            }
-            textIdx++;
-            patternIdx++;
-        }
-        else if (char === '{') {
-            const closeIdx = findClosingBrace(pattern, patternIdx);
-            if (closeIdx === -1) {
-                if (textIdx >= text.length || text[textIdx] !== char) {
-                    return false;
-                }
-                textIdx++;
-                patternIdx++;
-            }
-            else {
-                const alternatives = extractAlternatives(pattern.slice(patternIdx + 1, closeIdx));
-                for (const alt of alternatives) {
-                    if (matchSegmentFrom(text, textIdx, text.slice(0, textIdx) + alt + pattern.slice(closeIdx + 1), textIdx)) {
-                        return true;
-                    }
-                }
-                return false;
-            }
-        }
-        else {
-            if (textIdx >= text.length || text[textIdx] !== char) {
-                return false;
-            }
-            textIdx++;
-            patternIdx++;
-        }
-    }
-    return textIdx === text.length;
-}
-/**
- * Helper to match from a specific position.
- *
- * @param text - The full text being matched
- * @param textIdx - The starting index in text to match from
- * @param pattern - The full pattern being matched
- * @param patternIdx - The starting index in pattern to match from
- * @returns True if the text matches the pattern from the given positions
- */
-function matchSegmentFrom(text, textIdx, pattern, patternIdx) {
-    const remainingText = text.slice(textIdx);
-    const remainingPattern = pattern.slice(patternIdx);
-    return matchSegment(remainingText, remainingPattern);
-}
-/**
- * Find closing brace for {a,b,c} pattern.
- *
- * @param pattern - The pattern string to search within
- * @param startIdx - The index of the opening brace
- * @returns The index of the matching closing brace, or -1 if not found
- */
-function findClosingBrace(pattern, startIdx) {
-    let depth = 0;
-    for (let i = startIdx; i < pattern.length; i++) {
-        if (pattern[i] === '{') {
-            depth++;
-        }
-        else if (pattern[i] === '}') {
-            depth--;
-            if (depth === 0) {
-                return i;
-            }
-        }
-    }
-    return -1;
-}
-/**
- * Extract alternatives from {a,b,c} pattern content.
- *
- * @param content - The content between braces (without the braces themselves)
- * @returns Array of alternative strings split by commas at depth 0
- */
-function extractAlternatives(content) {
-    const alternatives = [];
-    let current = '';
-    let depth = 0;
-    for (let i = 0; i < content.length; i++) {
-        const char = content[i];
-        if (char === '{') {
-            depth++;
-            current += char;
-        }
-        else if (char === '}') {
-            depth--;
-            current += char;
-        }
-        else if (char === ',' && depth === 0) {
-            alternatives.push(current);
-            current = '';
-        }
-        else {
-            current += char;
-        }
+function writeFileContent(filePath, content, options) {
+    try {
+        fsWriteLogger.debug('Writing file content', { path: filePath, size: content.length, encoding: options?.encoding ?? 'utf-8' });
+        ensureDir(dirname(filePath));
+        writeFileSync(filePath, content, {
+            encoding: options?.encoding ?? 'utf-8',
+            mode: options?.mode,
+        });
+        fsWriteLogger.debug('File written successfully', { path: filePath });
     }
-    if (current) {
-        alternatives.push(current);
+    catch (error) {
+        fsWriteLogger.warn('Failed to write file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write file: ${filePath}`, 'FS_WRITE_ERROR', { path: filePath, operation: 'write', cause: error });
     }
-    return alternatives;
 }
 /**
- * Test if path matches any of the patterns.
- *
- * @param path - Path to test
- * @param patterns - Array of glob patterns
- * @returns True if path matches any pattern
- */
-function matchesAnyPattern(path, patterns) {
-    return patterns.some((pattern) => matchGlobPattern(path, pattern));
-}
-/**
- * Test if path exactly matches the pattern (no glob).
- *
- * @param path - Path to test
- * @param pattern - Exact pattern to match
- * @returns True if path equals pattern
- */
-function matchesExact(path, pattern) {
-    return path === pattern;
-}
-
-/**
- * Global registry of all caches for bulk operations.
- */
-const cacheRegistry = createSet();
-/**
- * Create a cache with optional TTL and size limits.
- *
- * The cache provides a simple key-value store with:
- * - Optional TTL (time-to-live) for automatic expiration
- * - Optional maxSize for limiting cache size with FIFO eviction
- * - Lazy expiration (entries are checked on access)
+ * Write Buffer to file.
+ * Creates parent directories if needed.
  *
- * @param options - Cache configuration options
- * @returns Cache instance
+ * @param filePath - Absolute or relative path to the target file
+ * @param content - Buffer containing binary data to write
+ * @param options - Optional write configuration (mode)
+ * @throws {Error} If write fails
  *
- * @example
+ * @example Writing binary buffer to file
  * ```typescript
- * // Basic cache
- * const cache = createCache<string, number>()
- * cache.set('answer', 42)
- * cache.get('answer') // 42
- *
- * // Cache with TTL (expires after 60 seconds)
- * const ttlCache = createCache<string, object>({ ttl: 60000 })
- *
- * // Cache with max size (evicts oldest when full)
- * const lruCache = createCache<string, object>({ maxSize: 100 })
- *
- * // Combined options
- * const configCache = createCache<string, object>({
- *   ttl: 30000,
- *   maxSize: 50
- * })
+ * const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47])
+ * writeFileBuffer('./output/image.png', imageBuffer)
  * ```
  */
-function createCache(options) {
-    const { ttl, maxSize } = options ?? {};
-    const store = createMap();
-    const insertionOrder = [];
-    /**
-     * Check if an entry is expired.
-     *
-     * @param entry - Cache entry to check
-     * @returns True if entry is expired
-     */
-    function isExpired(entry) {
-        if (ttl === undefined)
-            return false;
-        // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
-        return Date.now() - entry.timestamp > ttl;
-    }
-    /**
-     * Evict oldest entries to make room for new ones.
-     */
-    function evictIfNeeded() {
-        if (maxSize === undefined)
-            return;
-        while (store.size >= maxSize && insertionOrder.length > 0) {
-            const oldestKey = insertionOrder.shift();
-            if (oldestKey !== undefined) {
-                store.delete(oldestKey);
-            }
-        }
-    }
-    /**
-     * Remove key from insertion order tracking.
-     *
-     * @param key - Key to remove from order tracking
-     */
-    function removeFromOrder(key) {
-        const index = insertionOrder.indexOf(key);
-        if (index !== -1) {
-            insertionOrder.splice(index, 1);
-        }
+function writeFileBuffer(filePath, content, options) {
+    try {
+        fsWriteLogger.debug('Writing file buffer', { path: filePath, size: content.length });
+        ensureDir(dirname(filePath));
+        writeFileSync(filePath, content, { mode: options?.mode });
+        fsWriteLogger.debug('Buffer written successfully', { path: filePath });
     }
-    const cache = {
-        get(key) {
-            const entry = store.get(key);
-            if (!entry)
-                return undefined;
-            if (isExpired(entry)) {
-                store.delete(key);
-                removeFromOrder(key);
-                return undefined;
-            }
-            return entry.value;
-        },
-        set(key, value) {
-            if (store.has(key)) {
-                removeFromOrder(key);
-            }
-            else {
-                evictIfNeeded();
-            }
-            // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
-            store.set(key, { value, timestamp: Date.now() });
-            insertionOrder.push(key);
-        },
-        has(key) {
-            const entry = store.get(key);
-            if (!entry)
-                return false;
-            if (isExpired(entry)) {
-                store.delete(key);
-                removeFromOrder(key);
-                return false;
-            }
-            return true;
-        },
-        delete(key) {
-            removeFromOrder(key);
-            return store.delete(key);
-        },
-        clear() {
-            store.clear();
-            insertionOrder.length = 0;
-        },
-        size() {
-            return store.size;
-        },
-        keys() {
-            return [...insertionOrder];
-        },
-    };
-    cacheRegistry.add(cache);
-    return freeze(cache);
-}
-/**
- * Clear all registered caches.
- *
- * Useful for testing or when a global state reset is needed.
- * This clears all caches created via `createCache()`.
- *
- * @example
- * ```typescript
- * // In tests
- * afterEach(() => {
- *   clearAllCaches()
- * })
- * ```
- */
-function clearAllCaches() {
-    for (const cache of cacheRegistry) {
-        cache.clear();
+    catch (error) {
+        fsWriteLogger.warn('Failed to write buffer', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write file: ${filePath}`, 'FS_WRITE_ERROR', { path: filePath, operation: 'write', cause: error });
     }
 }
 /**
- * Get the number of registered caches.
- *
- * Primarily used for testing.
- *
- * @returns Number of registered caches
- */
-function getCacheCount() {
-    return cacheRegistry.size;
-}
-/**
- * Unregister a cache from the global registry.
- *
- * Useful for cleanup in tests or when a cache is no longer needed.
- *
- * @param cache - Cache to unregister
- * @returns True if cache was unregistered
- */
-function unregisterCache(cache) {
-    return cacheRegistry.delete(cache);
-}
-/**
- * Create a memoized version of a function with caching.
- *
- * The memoized function caches results based on the first argument (key).
- * If additional arguments are needed, use the options.keyFn parameter.
+ * Write JSON data to file with formatting.
+ * Creates parent directories if needed.
  *
- * @param fn - Function to memoize
- * @param options - Cache options for the underlying cache
- * @returns Memoized function with cache control methods
+ * @param filePath - Absolute or relative path to the target JSON file
+ * @param data - Object or value to serialize as JSON
+ * @param options - Optional write configuration (indent, encoding, mode)
+ * @throws {Error} If write fails
  *
- * @example
+ * @example Writing JSON data to file
  * ```typescript
- * // Memoize a detection function
- * const detectTechStackMemo = memoize(
- *   (path: string) => expensiveDetection(path),
- *   { ttl: 60000 }
- * )
+ * import { writeJsonFile } from '@hyperfrontend/project-scope'
  *
- * const result1 = detectTechStackMemo('/path/to/project')
- * const result2 = detectTechStackMemo('/path/to/project') // Returns cached
+ * // Write object to JSON file
+ * writeJsonFile('./config.json', { port: 3000, debug: true })
  *
- * // Clear the cache
- * detectTechStackMemo.cache.clear()
+ * // Write with custom indentation
+ * writeJsonFile('./config.json', data, { indent: 4 })
  * ```
  */
-function memoize(fn, options) {
-    const cache = createCache(options);
-    const memoized = (key) => {
-        const cached = cache.get(key);
-        if (cached !== undefined) {
-            return cached;
+function writeJsonFile(filePath, data, options) {
+    try {
+        fsWriteLogger.debug('Writing JSON file', { path: filePath, indent: options?.indent ?? 2 });
+        const indent = options?.indent ?? 2;
+        const content = stringify(data, null, indent) + '\n';
+        writeFileContent(filePath, content, options);
+        fsWriteLogger.debug('JSON file written successfully', { path: filePath });
+    }
+    catch (error) {
+        if (error?.code === 'FS_WRITE_ERROR') {
+            throw error;
         }
-        const result = fn(key);
-        cache.set(key, result);
-        return result;
-    };
-    defineProperty(memoized, 'cache', {
-        value: cache,
-        writable: false,
-        enumerable: true,
-    });
-    return memoized;
+        fsWriteLogger.warn('Failed to write JSON file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write JSON file: ${filePath}`, 'FS_WRITE_ERROR', {
+            path: filePath,
+            operation: 'write',
+            cause: error,
+        });
+    }
 }
 
-export { BINARY_SIGNATURES, CRLF, LF, UTF16_BE_BOM_BYTES, UTF16_LE_BOM_BYTES, UTF8_BOM, UTF8_BOM_BYTES, addBom, bufferToString, clearAllCaches, createCache, createConfigError, createDirectory, createFileSystemError, createFsError, createParseError, createScopedLogger, createStructuredError, createValidationError, detectCaseSensitivity, detectEncoding, detectEncodingInfo, detectLineEnding, detectPlatform, ensureDir, ensureTrailingSlash, exists, findUpwardWhere, getBasename, getCacheCount, getDirname, getExtension, getFileNameWithoutExtension, getFileStat, getGlobalLogLevel, getLineEnding, getPathSeparator, getPlatformInfo, hasBom, isAbsolute, isBinaryFile, isCaseSensitiveFs, isDirectory, isFile, isLinux, isMac, isSymlink, isTextFile, isWindows, join, joinPath, joinPosix, locateByMarkers, logger, matchGlobPattern, matchesAnyPattern, matchesExact, memoize, normalizeLineEndings, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, pathsEqual, readDirectory, readDirectoryRecursive, readFileBuffer, readFileContent, readFileIfExists, readJsonFile, readJsonFileIfExists, relativePath, removeDirectory, removeTrailingSlash, resetGlobalLogLevel, resolveFromWorkspace, resolvePath, resolveRealPath, sanitize, setGlobalLogLevel, stripBom, toUtf8, traverseUpward, unregisterCache, writeFileBuffer, writeFileContent, writeJsonFile };
-//# sourceMappingURL=index.esm.js.map
+export { BINARY_SIGNATURES, CRLF, LF, UTF16_BE_BOM_BYTES, UTF16_LE_BOM_BYTES, UTF8_BOM, UTF8_BOM_BYTES, addBom, bufferToString, clearAllCaches, createCache, createConfigError, createDirectory, createFileSystemError, createFsError, createParseError, createScopedLogger, createStructuredError, createValidationError, detectCaseSensitivity, detectEncoding, detectEncodingInfo, detectLineEnding, detectPlatform, ensureDir, ensureTrailingSlash, exists, findUpwardWhere, getBasename, getCacheCount, getDirname, getExtension, getFileNameWithoutExtension, getFileStat, getGlobalLogLevel, getLineEnding, getPathSeparator, getPlatformInfo, hasBom, isAbsolute, isCaseSensitiveFs, isDirectory, isFile, isSymlink, isTextFile, isWindows, join, joinPath, joinPosix, locateByMarkers, logger, matchGlobPattern, matchesAnyPattern, matchesExact, memoize, normalizeLineEndings, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, pathsEqual, readDirectory, readDirectoryRecursive, readFileBuffer, readFileContent, readFileIfExists, readJsonFile, readJsonFileIfExists, relativePath, removeDirectory, removeTrailingSlash, resetGlobalLogLevel, resolveFromWorkspace, resolvePath, resolveRealPath, sanitize, setGlobalLogLevel, stripBom, toUtf8, traverseUpward, unregisterCache, writeFileBuffer, writeFileContent, writeJsonFile };