@hyperfrontend/project-scope 0.2.1 → 0.2.2

package/core/fs/index.esm.js

@@ -1,379 +1,14 @@
-import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync, lstatSync, readdirSync, rmSync } from 'node:fs';
-import { dirname, join as join$1, resolve, parse as parse$1 } from 'node:path';
-
-/**
- * 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$1 = 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$1.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 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 = 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.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;
-};
-
-/* 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 { existsSync, readFileSync, statSync, lstatSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join as join$1, resolve, parse as parse$1, dirname } from 'node:path';
+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 { freeze, 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 { createLogger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { createError } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { getFileStat, isFile, isDirectory, isSymlink, exists } from '../../_shared/core/fs/stat/index.esm.js';
+import { join } from '../../_shared/core/path/join/index.esm.js';
 
 /**
  * Global log level registry.
@@ -413,6 +48,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) {
@@ -463,7 +105,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')
@@ -500,7 +142,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'
  *
@@ -518,6 +160,15 @@ const fsLogger = createScopedLogger('project-scope:fs');
  * @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);
@@ -535,7 +186,7 @@ function createFileSystemError(message, code, context) {
  * @returns File contents as string
  * @throws {Error} If file doesn't exist or can't be read
  *
- * @example
+ * @example Reading file contents
  * ```typescript
  * import { readFileContent } from '@hyperfrontend/project-scope'
  *
@@ -562,6 +213,12 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * @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 (!existsSync(filePath)) {
@@ -580,6 +237,14 @@ 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)) {
@@ -601,7 +266,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'
  *
@@ -644,196 +309,26 @@ function readJsonFile(filePath, options) {
  *
  * @param filePath - Path to JSON file
  * @returns Parsed JSON object or null if file doesn't exist or is invalid
- */
-function readJsonFileIfExists(filePath) {
-    if (!existsSync(filePath)) {
-        return null;
-    }
-    try {
-        const content = readFileSync(filePath, { encoding: 'utf-8' });
-        return parse(content);
-    }
-    catch {
-        return null;
-    }
-}
-
-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 });
-    }
-}
-/**
- * Write string content to file.
- * Creates parent directories if needed.
- *
- * @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
- * ```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
+ * @example Reading JSON file if it exists
  * ```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 })
+ * interface UserSettings { theme: string }
+ * const settings = readJsonFileIfExists<UserSettings>('./user-settings.json')
+ * const theme = settings?.theme ?? 'default'
  * ```
  */
-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) {
+function readJsonFileIfExists(filePath) {
     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,
-        };
+        const content = readFileSync(filePath, { encoding: 'utf-8' });
+        return parse(content);
     }
     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');
 /**
@@ -843,7 +338,7 @@ const fsDirLogger = createScopedLogger('project-scope:fs:dir');
  * @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 { readDirectory } from '@hyperfrontend/project-scope'
  *
@@ -890,7 +385,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'
  *
@@ -951,6 +446,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;
@@ -964,6 +468,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 });
@@ -973,17 +486,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);
-}
-
 const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
 /**
  * Generic upward directory traversal.
@@ -992,6 +494,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 });
@@ -1017,6 +528,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 });
@@ -1032,11 +554,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 fsWriteLogger = createScopedLogger('project-scope:fs:write');
+/**
+ * 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)
+ * ```
+ */
+function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
+        mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Write string content to file.
+ * Creates parent directories if needed.
+ *
+ * @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 Writing text content to file
+ * ```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
+ *
+ * @example Writing binary buffer to file
+ * ```typescript
+ * const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47])
+ * writeFileBuffer('./output/image.png', imageBuffer)
+ * ```
+ */
+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 Writing JSON data to file
+ * ```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,
+        });
+    }
+}
+
 export { createDirectory, createFileSystemError, ensureDir, exists, findUpwardWhere, getFileStat, isDirectory, isFile, isSymlink, locateByMarkers, readDirectory, readDirectoryRecursive, readFileBuffer, readFileContent, readFileIfExists, readJsonFile, readJsonFileIfExists, removeDirectory, traverseUpward, writeFileBuffer, writeFileContent, writeJsonFile };
-//# sourceMappingURL=index.esm.js.map