@hyperfrontend/versioning 0.1.0

package/flow/executor/index.esm.js

@@ -0,0 +1,4398 @@
+import 'node:util';
+import { join, normalize, sep, isAbsolute as isAbsolute$1, relative, resolve, dirname } from 'node:path';
+import { existsSync, mkdirSync, statSync, lstatSync, readdirSync, readFileSync, readlinkSync, unlinkSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import 'node:os';
+import { execSync } from 'node:child_process';
+
+/**
+ * Safe copies of Date built-in via factory function and static methods.
+ *
+ * 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/date
+ */
+// Capture references at module initialization time
+const _Date = globalThis.Date;
+const _Reflect$3 = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect$3.construct(_Date, args);
+}
+/**
+ * (Safe copy) Returns the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC.
+ */
+const dateNow = _Date.now;
+
+/**
+ * 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
+ */
+// Capture references at module initialization time
+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
+ */
+// Capture references at module initialization time
+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 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
+ */
+// Capture references at module initialization time
+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] : []);
+
+/**
+ * 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
+ */
+// Capture references at module initialization time
+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;
+
+const registeredClasses = [];
+
+/**
+ * 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
+ */
+// Capture references at module initialization time
+const _Array = globalThis.Array;
+/**
+ * (Safe copy) Determines whether the passed value is an Array.
+ */
+const isArray = _Array.isArray;
+/**
+ * (Safe copy) Creates an array from an array-like or iterable object.
+ */
+const from = _Array.from;
+
+/**
+ * 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
+ */
+// Capture references at module initialization time
+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] : []);
+
+/* 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`;
+}
+
+/**
+ * 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
+ */
+// Capture references at module initialization time
+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);
+
+const logger = createLogger(error, warn, log, info, debug);
+
+/**
+ * Global log level registry.
+ * Tracks all created scoped loggers to allow global log level changes.
+ */
+const loggerRegistry = createSet();
+/** Redacted placeholder for sensitive values */
+const REDACTED = '[REDACTED]';
+/**
+ * Patterns that indicate a sensitive key name.
+ * Keys containing these patterns will have their values sanitized.
+ */
+const SENSITIVE_KEY_PATTERNS = [
+    /token/i,
+    /key/i,
+    /password/i,
+    /secret/i,
+    /credential/i,
+    /auth/i,
+    /bearer/i,
+    /api[_-]?key/i,
+    /private/i,
+    /passphrase/i,
+];
+/**
+ * Checks if a key name indicates sensitive data.
+ *
+ * @param key - Key name to check
+ * @returns True if the key indicates sensitive data
+ */
+function isSensitiveKey(key) {
+    return SENSITIVE_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+/**
+ * Sanitizes an object by replacing sensitive values with REDACTED.
+ * This function recursively processes nested objects and arrays.
+ *
+ * @param obj - Object to sanitize
+ * @returns New object with sensitive values redacted
+ */
+function sanitize(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (isArray(obj)) {
+        return obj.map((item) => sanitize(item));
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of entries(obj)) {
+            if (isSensitiveKey(key)) {
+                result[key] = REDACTED;
+            }
+            else if (typeof value === 'object' && value !== null) {
+                result[key] = sanitize(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Formats a log message with optional metadata.
+ *
+ * @param namespace - Logger namespace prefix
+ * @param message - Log message
+ * @param meta - Optional metadata object
+ * @returns Formatted log string
+ */
+function formatMessage(namespace, message, meta) {
+    const prefix = `[${namespace}]`;
+    if (meta && keys(meta).length > 0) {
+        const sanitizedMeta = sanitize(meta);
+        return `${prefix} ${message} ${stringify(sanitizedMeta)}`;
+    }
+    return `${prefix} ${message}`;
+}
+/**
+ * Creates a scoped logger with namespace prefix and optional secret sanitization.
+ * All log messages will be prefixed with [namespace] and sensitive metadata
+ * values will be automatically redacted.
+ *
+ * @param namespace - Logger namespace (e.g., 'project-scope', 'analyze')
+ * @param options - Logger configuration options
+ * @returns A configured scoped logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createScopedLogger('project-scope')
+ * logger.setLogLevel('debug')
+ *
+ * // Basic logging
+ * logger.info('Starting analysis', { path: './project' })
+ *
+ * // Sensitive data is automatically redacted
+ * logger.debug('Config loaded', { apiKey: 'secret123' })
+ * // Output: [project-scope] Config loaded {"apiKey":"[REDACTED]"}
+ * ```
+ */
+function createScopedLogger(namespace, options = {}) {
+    const { level = 'error', sanitizeSecrets = true } = options;
+    // Create wrapper functions that add namespace prefix and sanitization
+    const createLogFn = (baseFn) => (message, meta) => {
+        const processedMeta = sanitizeSecrets && meta ? sanitize(meta) : meta;
+        baseFn(formatMessage(namespace, message, processedMeta));
+    };
+    // Create base logger with wrapped functions
+    const baseLogger = createLogger(createLogFn(error), createLogFn(warn), createLogFn(log), createLogFn(info), createLogFn(debug));
+    // Set initial log level (use global override if set)
+    baseLogger.setLogLevel(level);
+    const scopedLogger = freeze({
+        error: (message, meta) => baseLogger.error(message, meta),
+        warn: (message, meta) => baseLogger.warn(message, meta),
+        log: (message, meta) => baseLogger.log(message, meta),
+        info: (message, meta) => baseLogger.info(message, meta),
+        debug: (message, meta) => baseLogger.debug(message, meta),
+        setLogLevel: baseLogger.setLogLevel,
+        getLogLevel: baseLogger.getLogLevel,
+    });
+    // Register logger for global level management
+    loggerRegistry.add(scopedLogger);
+    return scopedLogger;
+}
+/**
+ * Default logger instance for the project-scope library.
+ * Use this for general logging within the library.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@hyperfrontend/project-scope/core'
+ *
+ * logger.setLogLevel('debug')
+ * logger.debug('Analyzing project', { path: './src' })
+ * ```
+ */
+createScopedLogger('project-scope');
+
+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
+ */
+function createFileSystemError(message, code, context) {
+    const error = createError(message);
+    defineProperties(error, {
+        code: { value: code, enumerable: true },
+        context: { value: context, enumerable: true },
+    });
+    return error;
+}
+
+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 });
+    }
+}
+
+/**
+ * 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 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'
+ *
+ * const entries = readDirectory('./src')
+ * for (const entry of entries) {
+ *   console.log(entry.name, entry.isFile ? 'file' : 'directory')
+ * }
+ * ```
+ */
+function readDirectory(dirPath) {
+    fsDirLogger.debug('Reading directory', { path: dirPath });
+    if (!existsSync(dirPath)) {
+        fsDirLogger.debug('Directory not found', { path: dirPath });
+        throw createFileSystemError(`Directory not found: ${dirPath}`, 'FS_NOT_FOUND', { path: dirPath, operation: 'readdir' });
+    }
+    if (!isDirectory(dirPath)) {
+        fsDirLogger.debug('Path is not a directory', { path: dirPath });
+        throw createFileSystemError(`Not a directory: ${dirPath}`, 'FS_NOT_A_DIRECTORY', { path: dirPath, operation: 'readdir' });
+    }
+    try {
+        const entries = readdirSync(dirPath, { withFileTypes: true });
+        fsDirLogger.debug('Directory read complete', { path: dirPath, entryCount: entries.length });
+        return entries.map((entry) => ({
+            name: entry.name,
+            path: join(dirPath, entry.name),
+            isFile: entry.isFile(),
+            isDirectory: entry.isDirectory(),
+            isSymlink: entry.isSymbolicLink(),
+        }));
+    }
+    catch (error) {
+        fsDirLogger.warn('Failed to read directory', { path: dirPath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to read directory: ${dirPath}`, 'FS_READ_ERROR', {
+            path: dirPath,
+            operation: 'readdir',
+            cause: error,
+        });
+    }
+}
+
+/**
+ * Normalize path separators to forward slashes.
+ *
+ * @param filePath - Path to normalize
+ * @returns Normalized path with forward slashes
+ */
+function normalizePath(filePath) {
+    if (!filePath)
+        return '';
+    // Normalize path and convert backslashes to forward slashes
+    const normalized = normalize(filePath);
+    return sep === '\\' ? normalized.replace(/\\/g, '/') : normalized;
+}
+/**
+ * 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);
+}
+
+/**
+ * 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));
+}
+/**
+ * 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(...segments));
+}
+/**
+ * Check if path is absolute.
+ *
+ * @param filePath - Path to check
+ * @returns True if path is absolute
+ */
+function isAbsolute(filePath) {
+    return isAbsolute$1(filePath);
+}
+
+/**
+ * Get directory name of path.
+ *
+ * @param filePath - Path to extract directory from
+ * @returns Directory name
+ */
+function getDirname(filePath) {
+    return normalizePath(dirname(filePath));
+}
+
+createScopedLogger('project-scope:fs:traversal');
+
+createScopedLogger('project-scope:project:package');
+
+createScopedLogger('project-scope:heuristics:deps');
+
+/**
+ * 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)
+ *
+ * @param options - Cache configuration options
+ * @returns Cache instance
+ *
+ * @example
+ * ```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
+ * })
+ * ```
+ */
+function createCache$1(options) {
+    const { ttl, maxSize } = options ?? {};
+    const store = createMap();
+    // Track insertion order for FIFO eviction
+    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);
+        }
+    }
+    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 key exists, remove from order first
+            if (store.has(key)) {
+                removeFromOrder(key);
+            }
+            else {
+                // Evict if needed before adding new entry
+                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];
+        },
+    };
+    // Register cache for global operations
+    cacheRegistry.add(cache);
+    return freeze(cache);
+}
+
+createScopedLogger('project-scope:project:walk');
+
+createScopedLogger('project-scope:project:search');
+
+createScopedLogger('project-scope:heuristics:entry-points');
+/**
+ * Cache for entry point discovery results.
+ * TTL: 60 seconds (entry points are relatively stable)
+ */
+createCache$1({ ttl: 60000, maxSize: 50 });
+
+createScopedLogger('project-scope:tech');
+/**
+ * Cache for tech detection results.
+ * TTL: 60 seconds (tech stack can change during active development)
+ */
+createCache$1({ ttl: 60000, maxSize: 50 });
+
+createScopedLogger('project-scope:heuristics:project-type');
+
+createScopedLogger('project-scope:root');
+
+createScopedLogger('project-scope:nx');
+
+createScopedLogger('project-scope:nx:devkit');
+
+createScopedLogger('project-scope:nx:config');
+
+createScopedLogger('project-scope:config');
+/**
+ * Cache for config detection results.
+ * TTL: 30 seconds (configs can change frequently during setup)
+ */
+createCache$1({ ttl: 30000, maxSize: 50 });
+
+/**
+ * Safe copies of Number built-in methods and constants.
+ *
+ * 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/number
+ */
+// Capture references at module initialization time
+const _parseInt = globalThis.parseInt;
+const _isNaN = globalThis.isNaN;
+// ============================================================================
+// Parsing
+// ============================================================================
+/**
+ * (Safe copy) Parses a string and returns an integer.
+ */
+const parseInt = _parseInt;
+// ============================================================================
+// Global Type Checking (legacy, less strict)
+// ============================================================================
+/**
+ * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
+ */
+const globalIsNaN = _isNaN;
+
+/** Logger for analysis operations */
+createScopedLogger('project-scope:analyze');
+
+/** Logger for CLI operations */
+createScopedLogger('project-scope:cli');
+
+createScopedLogger('project-scope:encoding');
+
+createScopedLogger('project-scope:encoding:convert');
+
+createScopedLogger('project-scope:heuristics:framework');
+/**
+ * Cache for framework identification results.
+ * TTL: 60 seconds (frameworks are stable but can change during development)
+ */
+createCache$1({ ttl: 60000, maxSize: 50 });
+
+/**
+ * Write mode for file operations.
+ */
+const Mode = freeze({
+    /** Overwrite existing files */
+    Overwrite: 'overwrite',
+    /** Fail if file exists */
+    ExclusiveCreate: 'exclusive',
+    /** Skip if file exists */
+    SkipIfExists: 'skip',
+});
+
+const fsTreeLogger = createScopedLogger('project-scope:vfs:tree');
+/**
+ * Create a file system-backed tree implementation.
+ *
+ * Supports transactional modifications - all changes are buffered
+ * in memory and can be committed atomically or rolled back.
+ *
+ * @param root - Absolute path to the workspace root directory
+ * @param options - Configuration for verbose logging
+ * @returns A Tree instance
+ */
+function createFsTree(root, options) {
+    const _root = removeTrailingSlash(normalizePath(root));
+    const _changes = createMap();
+    const _isVerbose = false;
+    const _followSymlinks = true;
+    fsTreeLogger.debug('Creating VFS tree', { root: _root, verbose: _isVerbose, followSymlinks: _followSymlinks });
+    /**
+     * Normalize path to be relative from root.
+     *
+     * @param filePath - Path to normalize
+     * @returns Normalized relative path
+     * @throws {Error} if path traverses outside the tree root
+     */
+    function normalizeFilePath(filePath) {
+        const normalized = isAbsolute(filePath) ? relativePath(_root, filePath) : normalizePath(filePath);
+        const absoluteResolved = resolvePath(_root, normalized);
+        if (!absoluteResolved.startsWith(_root + '/') && absoluteResolved !== _root) {
+            throw createError(`Path escapes tree root: ${filePath}`);
+        }
+        return normalized;
+    }
+    /**
+     * Get absolute path on disk.
+     *
+     * @param filePath - Relative path from root
+     * @returns Absolute path on disk
+     */
+    function absolutePath(filePath) {
+        return joinPath(_root, normalizeFilePath(filePath));
+    }
+    /**
+     * Check if a normalized path is a symbolic link.
+     *
+     * @param normalPath - Already normalized path
+     * @returns True if path is a symlink
+     */
+    function isSymlinkNormalizedPath(normalPath) {
+        const absPath = absolutePath(normalPath);
+        try {
+            const stats = lstatSync(absPath);
+            return stats.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Validate that a symlink target stays within tree bounds.
+     *
+     * @param normalPath - Already normalized path to symlink
+     * @throws {Error} If symlink target escapes tree root or followSymlinks is disabled
+     */
+    function validateSymlink(normalPath) {
+        const absPath = absolutePath(normalPath);
+        if (!isSymlinkNormalizedPath(normalPath)) {
+            return;
+        }
+        try {
+            const target = readlinkSync(absPath);
+            let targetAbsolute;
+            if (isAbsolute(target)) {
+                targetAbsolute = target;
+            }
+            else {
+                const symlinkDir = getDirname(absPath);
+                targetAbsolute = resolvePath(symlinkDir, target);
+            }
+            const normalizedTarget = normalizePath(targetAbsolute);
+            if (!normalizedTarget.startsWith(_root + '/') && normalizedTarget !== _root) {
+                throw createError(`Symlink target escapes tree root: ${normalPath} -> ${target}`);
+            }
+        }
+        catch (error) {
+            /* istanbul ignore else -- other errors are rare edge cases (e.g., permission denied) */
+            if (error instanceof Error && error.message.includes('Symlink target escapes')) {
+                throw error;
+            }
+            if (error instanceof Error && error.message.includes('followSymlinks is disabled')) {
+                throw error;
+            }
+            throw createError(`Failed to validate symlink: ${normalPath}`);
+        }
+    }
+    /**
+     * Check if path exists on disk (not considering buffered changes).
+     *
+     * @param normalPath - Normalized path to check
+     * @returns True if exists on disk
+     */
+    function existsOnDisk(normalPath) {
+        const absPath = absolutePath(normalPath);
+        return exists(absPath);
+    }
+    /**
+     * Read from disk (not considering buffered changes).
+     *
+     * @param normalPath - Normalized path to read
+     * @returns File content or null
+     */
+    function readFromDisk(normalPath) {
+        validateSymlink(normalPath);
+        const absPath = absolutePath(normalPath);
+        if (!isFile(absPath)) {
+            return null;
+        }
+        try {
+            return readFileSync(absPath);
+        }
+        catch {
+            return null;
+        }
+    }
+    const tree = {
+        get root() {
+            return _root;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        read(filePath, encoding) {
+            const normalPath = normalizeFilePath(filePath);
+            const change = _changes.get(normalPath);
+            if (change) {
+                if (change.type === 'DELETE') {
+                    return null;
+                }
+                if (change.content !== null) {
+                    return encoding ? change.content.toString(encoding) : change.content;
+                }
+            }
+            validateSymlink(normalPath);
+            const absPath = absolutePath(normalPath);
+            if (!exists(absPath)) {
+                return null;
+            }
+            if (!isFile(absPath)) {
+                return null;
+            }
+            try {
+                const content = readFileSync(absPath);
+                return encoding ? content.toString(encoding) : content;
+            }
+            catch {
+                return null;
+            }
+        },
+        write(filePath, content, options) {
+            const normalPath = normalizeFilePath(filePath);
+            const buffer = typeof content === 'string' ? Buffer.from(content, 'utf-8') : content;
+            fsTreeLogger.debug('write', { path: normalPath, size: buffer.length, mode: options?.mode ?? 'Overwrite' });
+            const mode = options?.mode ?? Mode.Overwrite;
+            if (mode === Mode.ExclusiveCreate && this.exists(normalPath)) {
+                throw createError(`File already exists: ${normalPath}`);
+            }
+            if (mode === Mode.SkipIfExists && this.exists(normalPath)) {
+                return;
+            }
+            const existingChange = _changes.get(normalPath);
+            const diskExists = existsOnDisk(normalPath);
+            let changeType;
+            let originalContent = null;
+            if (existingChange?.type === 'CREATE' || (!diskExists && !existingChange)) {
+                changeType = 'CREATE';
+            }
+            else {
+                changeType = 'UPDATE';
+                originalContent = existingChange?.originalContent ?? readFromDisk(normalPath);
+            }
+            _changes.set(normalPath, {
+                type: changeType,
+                content: buffer,
+                originalContent,
+                permissions: options?.permissions,
+            });
+        },
+        exists(filePath) {
+            const normalPath = normalizeFilePath(filePath);
+            const change = _changes.get(normalPath);
+            if (change) {
+                return change.type !== 'DELETE';
+            }
+            for (const [changedPath, record] of _changes) {
+                if (record.type !== 'DELETE' && changedPath.startsWith(normalPath + '/')) {
+                    return true;
+                }
+            }
+            return existsOnDisk(normalPath);
+        },
+        delete(filePath) {
+            const normalPath = normalizeFilePath(filePath);
+            fsTreeLogger.debug('delete', { path: normalPath });
+            const existingChange = _changes.get(normalPath);
+            if (existingChange?.type === 'CREATE') {
+                _changes.delete(normalPath);
+                return;
+            }
+            if (!existsOnDisk(normalPath)) {
+                return;
+            }
+            _changes.set(normalPath, {
+                type: 'DELETE',
+                content: null,
+                originalContent: readFromDisk(normalPath),
+            });
+        },
+        rename(from, to) {
+            const content = this.read(from);
+            if (content === null) {
+                throw createError(`Source file not found: ${from}`);
+            }
+            this.write(to, content);
+            this.delete(from);
+        },
+        isFile(filePath) {
+            const normalPath = normalizeFilePath(filePath);
+            const change = _changes.get(normalPath);
+            if (change) {
+                return change.type !== 'DELETE';
+            }
+            const absPath = absolutePath(normalPath);
+            return isFile(absPath);
+        },
+        isDirectory(filePath) {
+            const normalPath = normalizeFilePath(filePath);
+            for (const [changedPath, change] of _changes) {
+                if (change.type !== 'DELETE' && changedPath.startsWith(normalPath + '/')) {
+                    return true;
+                }
+            }
+            const absPath = absolutePath(normalPath);
+            return isDirectory(absPath);
+        },
+        isSymlink(filePath) {
+            const normalPath = normalizeFilePath(filePath);
+            return isSymlinkNormalizedPath(normalPath);
+        },
+        children(dirPath) {
+            const normalPath = normalizeFilePath(dirPath);
+            const childSet = createSet();
+            const absPath = absolutePath(normalPath);
+            try {
+                if (exists(absPath) && isDirectory(absPath)) {
+                    const entries = readDirectory(absPath);
+                    for (const entry of entries) {
+                        childSet.add(entry.name);
+                    }
+                }
+            }
+            catch {
+                // Directory doesn't exist on disk
+            }
+            const prefix = normalPath === '.' || normalPath === '' ? '' : normalPath + '/';
+            for (const [changedPath, change] of _changes) {
+                // Handle root-level files
+                if (prefix === '') {
+                    const childName = changedPath.split('/')[0];
+                    if (change.type === 'DELETE' && !changedPath.includes('/')) {
+                        childSet.delete(childName);
+                    }
+                    else if (change.type !== 'DELETE') {
+                        childSet.add(childName);
+                    }
+                    continue;
+                }
+                if (!changedPath.startsWith(prefix)) {
+                    continue;
+                }
+                const relativePath = changedPath.slice(prefix.length);
+                const childName = relativePath.split('/')[0];
+                if (change.type === 'DELETE') {
+                    // Only remove if it's a direct child being deleted
+                    if (!relativePath.includes('/')) {
+                        childSet.delete(childName);
+                    }
+                }
+                else {
+                    childSet.add(childName);
+                }
+            }
+            return from(childSet).sort();
+        },
+        listChanges() {
+            const changes = [];
+            for (const [path, record] of _changes) {
+                changes.push({
+                    path,
+                    type: record.type,
+                    content: record.content ?? undefined,
+                    originalContent: record.originalContent ?? undefined,
+                    mode: record.permissions,
+                });
+            }
+            return changes.sort((a, b) => a.path.localeCompare(b.path));
+        },
+        changePermissions(filePath, mode) {
+            const normalPath = normalizeFilePath(filePath);
+            if (!this.exists(normalPath)) {
+                throw createError(`File not found: ${normalPath}`);
+            }
+            const existingChange = _changes.get(normalPath);
+            if (existingChange) {
+                existingChange.permissions = mode;
+            }
+            else {
+                const content = readFromDisk(normalPath);
+                _changes.set(normalPath, {
+                    type: 'UPDATE',
+                    content,
+                    originalContent: content,
+                    permissions: mode,
+                });
+            }
+        },
+        changeFile(filePath, transform) {
+            const content = this.read(filePath);
+            if (content === null) {
+                throw createError(`File not found: ${filePath}`);
+            }
+            const newContent = transform(content);
+            this.write(filePath, newContent);
+        },
+        clearChanges() {
+            _changes.clear();
+        },
+    };
+    return tree;
+}
+
+const factoryLogger = createScopedLogger('project-scope:vfs:factory');
+/**
+ * Create a virtual file system tree.
+ *
+ * @param root - Root directory path
+ * @param options - Tree creation options
+ * @returns A new Tree instance
+ * @throws {Error} If root doesn't exist or isn't a directory
+ *
+ * @example
+ * ```typescript
+ * import { createTree } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('./my-project')
+ *
+ * // Read files from tree
+ * const content = tree.read('src/index.ts', 'utf-8')
+ *
+ * // Make changes (buffered in memory)
+ * tree.write('src/new-file.ts', 'export const x = 1')
+ *
+ * // List pending changes
+ * console.log(tree.listChanges())
+ * ```
+ */
+function createTree(root, options) {
+    const normalizedRoot = normalizePath(root);
+    factoryLogger.debug('createTree', { root: normalizedRoot });
+    // Validate root exists
+    if (!exists(normalizedRoot)) {
+        factoryLogger.warn('createTree failed: root does not exist', { root: normalizedRoot });
+        throw createError(`Root directory does not exist: ${normalizedRoot}`);
+    }
+    // Validate root is a directory
+    if (!isDirectory(normalizedRoot)) {
+        factoryLogger.warn('createTree failed: root is not a directory', { root: normalizedRoot });
+        throw createError(`Root path is not a directory: ${normalizedRoot}`);
+    }
+    return createFsTree(normalizedRoot);
+}
+
+const vfsLogger = createScopedLogger('project-scope:vfs');
+/**
+ * Commit buffered changes to disk.
+ *
+ * @param tree - Virtual file system tree with pending modifications
+ * @param options - Configuration for dry-run and verbosity
+ * @returns Result of the commit operation
+ *
+ * @example
+ * ```typescript
+ * import { createTree, commitChanges } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('./my-project')
+ * tree.write('src/new-file.ts', 'export const hello = "world"')
+ *
+ * // Preview changes without writing
+ * const preview = commitChanges(tree, { dryRun: true })
+ * console.log('Would create:', preview.created, 'files')
+ *
+ * // Actually commit changes
+ * const result = commitChanges(tree)
+ * console.log('Created:', result.created, 'Updated:', result.updated)
+ * ```
+ */
+function commitChanges(tree, options) {
+    const changes = tree.listChanges();
+    const appliedChanges = [];
+    // Set log level based on verbose option
+    if (options?.verbose) {
+        vfsLogger.setLogLevel('debug');
+    }
+    vfsLogger.debug('Committing changes', { changeCount: changes.length, dryRun: options?.dryRun });
+    const result = {
+        created: 0,
+        updated: 0,
+        deleted: 0,
+        changes: [],
+        dryRun: options?.dryRun ?? false,
+    };
+    // Dry run - just count changes without writing
+    if (options?.dryRun) {
+        for (const change of changes) {
+            switch (change.type) {
+                case 'CREATE':
+                    result.created++;
+                    break;
+                case 'UPDATE':
+                    result.updated++;
+                    break;
+                case 'DELETE':
+                    result.deleted++;
+                    break;
+            }
+        }
+        result.changes = changes;
+        return result;
+    }
+    // Sort changes: deletes first (to free names), then creates, then updates
+    const sortedChanges = [...changes].sort((a, b) => {
+        const order = { DELETE: 0, CREATE: 1, UPDATE: 2 };
+        return order[a.type] - order[b.type];
+    });
+    for (const change of sortedChanges) {
+        const absPath = join(tree.root, change.path);
+        try {
+            switch (change.type) {
+                case 'CREATE':
+                case 'UPDATE':
+                    /* istanbul ignore if -- content is always defined for CREATE/UPDATE from tree.write() */
+                    if (change.content !== undefined) {
+                        // Ensure directory exists
+                        const dir = dirname(absPath);
+                        ensureDir(dir);
+                        writeFileSync(absPath, change.content);
+                        // Apply permissions if specified
+                        if (change.mode !== undefined) {
+                            chmodSync(absPath, change.mode);
+                        }
+                        if (change.type === 'CREATE') {
+                            result.created++;
+                        }
+                        else {
+                            result.updated++;
+                        }
+                    }
+                    break;
+                case 'DELETE':
+                    if (exists(absPath)) {
+                        try {
+                            unlinkSync(absPath);
+                        }
+                        catch {
+                            // Try recursive delete for directories
+                            rmSync(absPath, { recursive: true });
+                        }
+                    }
+                    result.deleted++;
+                    break;
+            }
+            appliedChanges.push(change);
+            if (options?.verbose) {
+                const prefix = change.type === 'CREATE' ? '+' : change.type === 'DELETE' ? '-' : '~';
+                vfsLogger.info(`${prefix} ${change.path}`);
+            }
+        }
+        catch (error) {
+            // On error, throw with context
+            vfsLogger.error('Commit failed', { path: change.path, type: change.type });
+            const message = error instanceof Error
+                ? `Failed to ${change.type.toLowerCase()} ${change.path}: ${error.message}`
+                : `Failed to ${change.type.toLowerCase()} ${change.path}`;
+            throw createError(message);
+        }
+    }
+    result.changes = appliedChanges;
+    // Clear the tree's pending changes after successful commit
+    tree.clearChanges();
+    return result;
+}
+
+createScopedLogger('project-scope:vfs:diff');
+
+/**
+ * Creates a git reference from full name.
+ * Parses the reference type from the full name.
+ *
+ * @param options - Reference creation options
+ * @returns A new GitRef object
+ *
+ * @example
+ * const ref = createGitRef({
+ *   fullName: 'refs/heads/main',
+ *   commitHash: 'abc123...',
+ * })
+ */
+function createGitRef(options) {
+    const { type, name, remote } = parseRefName(options.fullName);
+    return {
+        fullName: options.fullName,
+        name,
+        type,
+        commitHash: options.commitHash,
+        remote,
+        isHead: options.isHead,
+    };
+}
+/**
+ * Parses a full reference name into its components.
+ * Uses character-by-character parsing (no regex).
+ *
+ * @param fullName - Full reference name
+ * @returns Parsed components
+ *
+ * @example
+ * parseRefName('refs/heads/main') // { type: 'branch', name: 'main' }
+ * parseRefName('refs/remotes/origin/main') // { type: 'remote', name: 'main', remote: 'origin' }
+ */
+function parseRefName(fullName) {
+    // Handle HEAD specially
+    if (fullName === 'HEAD') {
+        return { type: 'head', name: 'HEAD' };
+    }
+    // Split by '/' character
+    const parts = splitByChar(fullName, '/');
+    // refs/heads/... -> branch
+    if (parts.length >= 3 && parts[0] === 'refs' && parts[1] === 'heads') {
+        return {
+            type: 'branch',
+            name: parts.slice(2).join('/'),
+        };
+    }
+    // refs/tags/... -> tag
+    if (parts.length >= 3 && parts[0] === 'refs' && parts[1] === 'tags') {
+        return {
+            type: 'tag',
+            name: parts.slice(2).join('/'),
+        };
+    }
+    // refs/remotes/origin/... -> remote
+    if (parts.length >= 4 && parts[0] === 'refs' && parts[1] === 'remotes') {
+        return {
+            type: 'remote',
+            name: parts.slice(3).join('/'),
+            remote: parts[2],
+        };
+    }
+    // refs/stash -> stash
+    if (parts.length >= 2 && parts[0] === 'refs' && parts[1] === 'stash') {
+        return {
+            type: 'stash',
+            name: parts.slice(1).join('/'),
+        };
+    }
+    // Default to branch for unknown patterns
+    return {
+        type: 'branch',
+        name: fullName,
+    };
+}
+/**
+ * Splits a string by a character.
+ * Character-by-character implementation (no regex).
+ *
+ * @param str - String to split
+ * @param char - Character to split by
+ * @returns Array of parts
+ */
+function splitByChar(str, char) {
+    const parts = [];
+    let current = '';
+    for (let i = 0; i < str.length; i++) {
+        if (str[i] === char) {
+            parts.push(current);
+            current = '';
+        }
+        else {
+            current += str[i];
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+
+/**
+ * Creates a git commit model.
+ *
+ * @param options - Commit creation options
+ * @returns A new GitCommit object
+ *
+ * @example
+ * const commit = createGitCommit({
+ *   hash: 'abc123...',
+ *   authorName: 'John Doe',
+ *   authorEmail: 'john@example.com',
+ *   authorDate: '2026-03-12T10:00:00Z',
+ *   subject: 'feat: add new feature',
+ * })
+ */
+function createGitCommit(options) {
+    const body = options.body ?? '';
+    const subject = options.subject;
+    return {
+        hash: options.hash,
+        shortHash: getShortHash(options.hash),
+        authorName: options.authorName,
+        authorEmail: options.authorEmail,
+        authorDate: options.authorDate,
+        committerName: options.committerName ?? options.authorName,
+        committerEmail: options.committerEmail ?? options.authorEmail,
+        commitDate: options.commitDate ?? options.authorDate,
+        subject,
+        body,
+        message: body ? `${subject}\n\n${body}` : subject,
+        parents: options.parents ?? [],
+        refs: options.refs ?? [],
+    };
+}
+/**
+ * Gets a short hash (7 characters) from a full commit hash.
+ *
+ * @param hash - Full commit hash
+ * @returns Short hash (7 characters)
+ */
+function getShortHash(hash) {
+    return hash.slice(0, 7);
+}
+
+/**
+ * Default log options.
+ */
+const DEFAULT_LOG_OPTIONS = {
+    maxCount: 100,
+    includeMerges: true,
+    timeout: 30000,
+};
+/**
+ * Git log format string for structured output.
+ * Uses ASCII delimiters that won't appear in commit messages.
+ */
+const LOG_FORMAT = [
+    '%H', // full hash
+    '%an', // author name
+    '%ae', // author email
+    '%aI', // author date (ISO 8601)
+    '%cn', // committer name
+    '%ce', // committer email
+    '%cI', // commit date (ISO 8601)
+    '%s', // subject
+    '%b', // body
+    '%P', // parent hashes
+    '%D', // refs
+].join('%x00'); // NUL separator
+/**
+ * Record separator for commit entries.
+ */
+const RECORD_SEPARATOR = '\x1e'; // ASCII Record Separator
+/**
+ * Gets the commit log from a git repository.
+ *
+ * @param options - Configuration for retrieving the commit log
+ * @returns Array of GitCommit objects
+ *
+ * @example
+ * const commits = getCommitLog({ maxCount: 10 })
+ * const recentChanges = getCommitLog({ from: 'v1.0.0', to: 'HEAD' })
+ */
+function getCommitLog(options = {}) {
+    const opts = { ...DEFAULT_LOG_OPTIONS, ...options };
+    const args = ['log', `--format=${RECORD_SEPARATOR}${LOG_FORMAT}`];
+    // Add options
+    if (opts.maxCount !== undefined && opts.maxCount > 0) {
+        args.push(`-n${opts.maxCount}`);
+    }
+    if (!opts.includeMerges) {
+        args.push('--no-merges');
+    }
+    if (opts.author) {
+        const safeAuthor = escapeGitArg(opts.author);
+        args.push(`--author=${safeAuthor}`);
+    }
+    // Add range
+    if (opts.from && opts.to) {
+        const safeFrom = escapeGitRef(opts.from);
+        const safeTo = escapeGitRef(opts.to);
+        args.push(`${safeFrom}..${safeTo}`);
+    }
+    else if (opts.from) {
+        const safeFrom = escapeGitRef(opts.from);
+        args.push(`${safeFrom}..HEAD`);
+    }
+    else if (opts.to) {
+        const safeTo = escapeGitRef(opts.to);
+        args.push(safeTo);
+    }
+    // Add path filter
+    if (opts.path) {
+        const safePath = escapeGitPath(opts.path);
+        args.push('--', safePath);
+    }
+    try {
+        const output = execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 50 * 1024 * 1024, // 50MB
+        });
+        return parseCommitLog(output);
+    }
+    catch (error) {
+        // Check if error is due to no commits
+        if (error instanceof Error && error.message.includes('does not have any commits')) {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Gets commits between two references.
+ *
+ * @param from - Starting reference (exclusive)
+ * @param to - Ending reference (inclusive, default: HEAD)
+ * @param options - Additional options
+ * @returns Array of GitCommit objects
+ *
+ * @example
+ * const commits = getCommitsBetween('v1.0.0', 'v1.1.0')
+ */
+function getCommitsBetween(from, to = 'HEAD', options = {}) {
+    return getCommitLog({ ...options, from, to });
+}
+/**
+ * Gets commits since a specific tag or reference.
+ *
+ * @param since - Reference to start from (exclusive)
+ * @param options - Additional options
+ * @returns Array of GitCommit objects
+ *
+ * @example
+ * const commits = getCommitsSince('v1.0.0')
+ */
+function getCommitsSince(since, options = {}) {
+    return getCommitLog({ ...options, from: since });
+}
+/**
+ * Gets a single commit by its hash.
+ *
+ * @param hash - Commit hash (full or short)
+ * @param options - Additional options
+ * @returns GitCommit or null if not found
+ *
+ * @example
+ * const commit = getCommit('abc1234')
+ */
+function getCommit(hash, options = {}) {
+    const safeHash = escapeGitRef(hash);
+    try {
+        const commits = getCommitLog({
+            ...options,
+            to: safeHash,
+            maxCount: 1,
+        });
+        return commits[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Checks if a commit exists in the repository.
+ *
+ * @param hash - Commit hash to check
+ * @param options - Additional options
+ * @returns True if commit exists
+ */
+function commitExists(hash, options = {}) {
+    const safeHash = escapeGitRef(hash);
+    try {
+        execSync(`git cat-file -t ${safeHash}`, {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout ?? 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parses raw git log output into GitCommit objects.
+ *
+ * @param output - Raw git log output
+ * @returns Array of GitCommit objects
+ */
+function parseCommitLog(output) {
+    const commits = [];
+    if (!output.trim()) {
+        return commits;
+    }
+    // Split by record separator
+    const records = splitByDelimiter(output, RECORD_SEPARATOR);
+    for (const record of records) {
+        const trimmed = record.trim();
+        if (!trimmed)
+            continue;
+        // Split by NUL character
+        const fields = splitByDelimiter(trimmed, '\x00');
+        if (fields.length < 10)
+            continue;
+        const [hash, authorName, authorEmail, authorDate, committerName, committerEmail, commitDate, subject, body, parentsStr, refsStr] = fields;
+        // Parse parents (space-separated hashes)
+        const parents = parentsStr ? splitByDelimiter(parentsStr, ' ').filter((p) => p.trim()) : [];
+        // Parse refs (comma-separated, may have prefixes like 'HEAD -> ')
+        const refs = parseRefs(refsStr || '');
+        commits.push(createGitCommit({
+            hash,
+            authorName,
+            authorEmail,
+            authorDate,
+            committerName,
+            committerEmail,
+            commitDate,
+            subject,
+            body: body || undefined,
+            parents,
+            refs,
+        }));
+    }
+    return commits;
+}
+/**
+ * Parses ref string from git log.
+ *
+ * @param refsStr - Raw refs string from git log
+ * @returns Array of ref names
+ */
+function parseRefs(refsStr) {
+    if (!refsStr.trim()) {
+        return [];
+    }
+    const refs = [];
+    const parts = splitByDelimiter(refsStr, ',');
+    for (const part of parts) {
+        let ref = part.trim();
+        // Handle 'HEAD -> branch' format
+        const arrowIndex = findSubstring(ref, ' -> ');
+        if (arrowIndex !== -1) {
+            refs.push('HEAD');
+            ref = ref.slice(arrowIndex + 4);
+        }
+        // Handle 'tag: tagname' format
+        if (startsWithPrefix$2(ref, 'tag: ')) {
+            ref = ref.slice(5);
+        }
+        if (ref) {
+            refs.push(ref);
+        }
+    }
+    return refs;
+}
+/**
+ * Splits string by delimiter (no regex).
+ *
+ * @param str - String to split
+ * @param delimiter - Delimiter to split by
+ * @returns Array of parts
+ */
+function splitByDelimiter(str, delimiter) {
+    const parts = [];
+    let current = '';
+    let i = 0;
+    while (i < str.length) {
+        if (matchesAt(str, i, delimiter)) {
+            parts.push(current);
+            current = '';
+            i += delimiter.length;
+        }
+        else {
+            current += str[i];
+            i++;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+/**
+ * Checks if string matches at position.
+ *
+ * @param str - String to check
+ * @param pos - Position to check at
+ * @param pattern - Pattern to match
+ * @returns True if matches
+ */
+function matchesAt(str, pos, pattern) {
+    if (pos + pattern.length > str.length)
+        return false;
+    for (let i = 0; i < pattern.length; i++) {
+        if (str[pos + i] !== pattern[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Finds substring position (no regex).
+ *
+ * @param str - String to search
+ * @param pattern - Pattern to find
+ * @returns Position or -1 if not found
+ */
+function findSubstring(str, pattern) {
+    for (let i = 0; i <= str.length - pattern.length; i++) {
+        if (matchesAt(str, i, pattern)) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Checks if string starts with prefix (no regex).
+ *
+ * @param str - String to check
+ * @param prefix - Prefix to check for
+ * @returns True if starts with prefix
+ */
+function startsWithPrefix$2(str, prefix) {
+    return matchesAt(str, 0, prefix);
+}
+// ============================================================================
+// Security helpers - character-by-character validation (no regex)
+// ============================================================================
+/**
+ * Maximum allowed git reference length.
+ */
+const MAX_REF_LENGTH = 256;
+/**
+ * Escapes a git reference for safe use in shell commands.
+ *
+ * @param ref - Reference to escape
+ * @returns Safe reference string
+ * @throws {Error} If reference contains invalid characters
+ */
+function escapeGitRef(ref) {
+    if (!ref || typeof ref !== 'string') {
+        throw createError('Git reference is required');
+    }
+    if (ref.length > MAX_REF_LENGTH) {
+        throw createError(`Git reference exceeds maximum length of ${MAX_REF_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < ref.length; i++) {
+        const code = ref.charCodeAt(i);
+        // Allow: a-z, A-Z, 0-9, /, -, _, ., ~, ^, @, {, }
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 47 || // /
+            code === 45 || // -
+            code === 95 || // _
+            code === 46 || // .
+            code === 126 || // ~
+            code === 94 || // ^
+            code === 64 || // @
+            code === 123 || // {
+            code === 125 // }
+        ) {
+            safe.push(ref[i]);
+        }
+        else {
+            throw createError(`Invalid character in git reference at position ${i}: "${ref[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+/**
+ * Maximum allowed git path length.
+ */
+const MAX_PATH_LENGTH$1 = 4096;
+/**
+ * Escapes a file path for safe use in git commands.
+ *
+ * @param path - Path to escape
+ * @returns Safe path string
+ * @throws {Error} If path contains invalid characters
+ */
+function escapeGitPath(path) {
+    if (!path || typeof path !== 'string') {
+        throw createError('Path is required');
+    }
+    if (path.length > MAX_PATH_LENGTH$1) {
+        throw createError(`Path exceeds maximum length of ${MAX_PATH_LENGTH$1}`);
+    }
+    const safe = [];
+    for (let i = 0; i < path.length; i++) {
+        const code = path.charCodeAt(i);
+        // Allow: a-z, A-Z, 0-9, /, \, -, _, ., space
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 47 || // /
+            code === 92 || // \
+            code === 45 || // -
+            code === 95 || // _
+            code === 46 || // .
+            code === 32 // space
+        ) {
+            safe.push(path[i]);
+        }
+        else {
+            throw createError(`Invalid character in path at position ${i}: "${path[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+/**
+ * Maximum allowed argument length.
+ */
+const MAX_ARG_LENGTH = 1000;
+/**
+ * Escapes a general git argument for safe use in shell commands.
+ *
+ * @param arg - Argument to escape
+ * @returns Safe argument string
+ * @throws {Error} If argument contains invalid characters
+ */
+function escapeGitArg(arg) {
+    if (!arg || typeof arg !== 'string') {
+        throw createError('Argument is required');
+    }
+    if (arg.length > MAX_ARG_LENGTH) {
+        throw createError(`Argument exceeds maximum length of ${MAX_ARG_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < arg.length; i++) {
+        const code = arg.charCodeAt(i);
+        // Allow: a-z, A-Z, 0-9, space, @, ., -, _, <, >, +
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 32 || // space
+            code === 64 || // @
+            code === 46 || // .
+            code === 45 || // -
+            code === 95 || // _
+            code === 60 || // <
+            code === 62 || // >
+            code === 43 // +
+        ) {
+            safe.push(arg[i]);
+        }
+        else {
+            throw createError(`Invalid character in argument at position ${i}: "${arg[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+
+/**
+ * Creates a lightweight git tag.
+ *
+ * @param options - Tag creation options
+ * @returns A new GitTag object
+ *
+ * @example
+ * const tag = createLightweightTag({
+ *   name: 'v1.0.0',
+ *   commitHash: 'abc123...',
+ * })
+ */
+function createLightweightTag(options) {
+    return {
+        name: options.name,
+        commitHash: options.commitHash,
+        type: 'lightweight',
+    };
+}
+/**
+ * Creates an annotated git tag.
+ *
+ * @param options - Tag creation options
+ * @returns A new GitTag object
+ *
+ * @example
+ * const tag = createAnnotatedTag({
+ *   name: 'v1.0.0',
+ *   commitHash: 'abc123...',
+ *   message: 'Release v1.0.0',
+ *   taggerName: 'John Doe',
+ *   taggerEmail: 'john@example.com',
+ *   tagDate: '2026-03-12T10:00:00Z',
+ * })
+ */
+function createAnnotatedTag(options) {
+    return {
+        name: options.name,
+        commitHash: options.commitHash,
+        type: 'annotated',
+        message: options.message,
+        taggerName: options.taggerName,
+        taggerEmail: options.taggerEmail,
+        tagDate: options.tagDate,
+    };
+}
+
+/**
+ * Default tag options.
+ */
+const DEFAULT_TAG_OPTIONS = {
+    timeout: 10000,
+};
+/**
+ * Gets all tags from the repository.
+ *
+ * @param options - Tag listing options
+ * @returns Array of GitTag objects
+ *
+ * @example
+ * const tags = getTags()
+ * const versionTags = getTags({ pattern: 'v' })
+ */
+function getTags(options = {}) {
+    const opts = { ...DEFAULT_TAG_OPTIONS, ...options };
+    const args = ['tag', '-l', '--sort=-creatordate'];
+    if (opts.pattern) {
+        const safePattern = escapeGitTagPattern(opts.pattern);
+        args.push(safePattern + '*');
+    }
+    try {
+        const output = execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const tagNames = output
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        // Limit results if requested
+        const limitedNames = opts.maxCount ? tagNames.slice(0, opts.maxCount) : tagNames;
+        // Get details for each tag
+        const tags = [];
+        for (const name of limitedNames) {
+            const tag = getTagDetails(name, opts);
+            if (tag) {
+                tags.push(tag);
+            }
+        }
+        return tags;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Gets detailed information about a specific tag.
+ *
+ * @param name - The tag name to look up
+ * @param options - Configuration for the tag operation
+ * @returns GitTag or null if not found
+ *
+ * @example
+ * const tag = getTag('v1.0.0')
+ */
+function getTag(name, options = {}) {
+    return getTagDetails(name, { ...DEFAULT_TAG_OPTIONS, ...options });
+}
+/**
+ * Gets tag details including type and commit hash.
+ *
+ * @param name - The tag name to retrieve details for
+ * @param options - Configuration for the tag operation
+ * @returns GitTag or null
+ */
+function getTagDetails(name, options) {
+    const safeName = escapeGitRef(name);
+    try {
+        // Get the commit hash the tag points to
+        const commitHash = execSync(`git rev-list -1 ${safeName}`, {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // Check if it's an annotated tag by trying to get tag message
+        try {
+            const tagInfo = execSync(`git cat-file tag ${safeName}`, {
+                encoding: 'utf-8',
+                cwd: options.cwd,
+                timeout: options.timeout,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            // Parse annotated tag info
+            const parsed = parseAnnotatedTagInfo(tagInfo);
+            return createAnnotatedTag({
+                name,
+                commitHash,
+                message: parsed.message,
+                taggerName: parsed.taggerName,
+                taggerEmail: parsed.taggerEmail,
+                tagDate: parsed.tagDate,
+            });
+        }
+        catch {
+            // Not an annotated tag, it's lightweight
+            return createLightweightTag({
+                name,
+                commitHash,
+            });
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parses annotated tag info from git cat-file output.
+ *
+ * @param info - Raw tag info
+ * @returns Parsed info
+ */
+function parseAnnotatedTagInfo(info) {
+    const lines = info.split('\n');
+    let taggerName = '';
+    let taggerEmail = '';
+    let tagDate = '';
+    let messageStart = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (startsWithPrefix$1(line, 'tagger ')) {
+            const taggerLine = line.slice(7);
+            const parsed = parseTaggerLine(taggerLine);
+            taggerName = parsed.name;
+            taggerEmail = parsed.email;
+            tagDate = parsed.date;
+        }
+        // Empty line marks start of message
+        if (line === '' && messageStart === -1) {
+            messageStart = i + 1;
+            break;
+        }
+    }
+    const message = messageStart >= 0 ? lines.slice(messageStart).join('\n').trim() : '';
+    return {
+        message,
+        taggerName,
+        taggerEmail,
+        tagDate,
+    };
+}
+/**
+ * Parses tagger line from annotated tag.
+ * Format: Name <email> timestamp timezone
+ *
+ * @param line - Raw tagger line from git output
+ * @returns Parsed tagger info with name, email, and date
+ */
+function parseTaggerLine(line) {
+    let name = '';
+    let email = '';
+    let date = '';
+    // Find email in angle brackets
+    let emailStart = -1;
+    let emailEnd = -1;
+    for (let i = 0; i < line.length; i++) {
+        if (line[i] === '<') {
+            emailStart = i + 1;
+        }
+        else if (line[i] === '>' && emailStart !== -1) {
+            emailEnd = i;
+            break;
+        }
+    }
+    if (emailStart !== -1 && emailEnd !== -1) {
+        name = line.slice(0, emailStart - 1).trim();
+        email = line.slice(emailStart, emailEnd);
+        // Rest is timestamp and timezone
+        const rest = line.slice(emailEnd + 1).trim();
+        const parts = rest.split(' ');
+        if (parts.length >= 1) {
+            // Convert Unix timestamp to ISO 8601
+            const timestamp = parseInt(parts[0], 10);
+            if (!globalIsNaN(timestamp)) {
+                date = createDate(timestamp * 1000).toISOString();
+            }
+        }
+    }
+    return { name, email, date };
+}
+/**
+ * Checks if a tag exists.
+ *
+ * @param name - The tag name to verify
+ * @param options - Configuration for the tag operation
+ * @returns True if tag exists
+ *
+ * @example
+ * if (tagExists('v1.0.0')) { ... }
+ */
+function tagExists(name, options = {}) {
+    const opts = { ...DEFAULT_TAG_OPTIONS, ...options };
+    const safeName = escapeGitRef(name);
+    try {
+        execSync(`git rev-parse ${safeName}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gets the latest tag (by creation date).
+ *
+ * @param options - Tag options with optional pattern
+ * @returns Latest GitTag or null
+ *
+ * @example
+ * const latest = getLatestTag()
+ * const latestVersion = getLatestTag({ pattern: 'v' })
+ */
+function getLatestTag(options = {}) {
+    const tags = getTags({ ...options, maxCount: 1 });
+    return tags[0] ?? null;
+}
+/**
+ * Gets tags that match a package name.
+ *
+ * @param packageName - Package name to match
+ * @param options - Tag options
+ * @returns Array of matching tags
+ *
+ * @example
+ * const tags = getTagsForPackage('@scope/pkg')
+ */
+function getTagsForPackage(packageName, options = {}) {
+    // Common patterns: @scope/pkg@version, pkg@version, pkg-vversion
+    const allTags = getTags(options);
+    return allTags.filter((tag) => {
+        // Check if tag starts with package name followed by @ or -v
+        const name = tag.name;
+        // Pattern: package@version
+        if (startsWithPrefix$1(name, packageName + '@')) {
+            return true;
+        }
+        // Pattern: package-v
+        if (startsWithPrefix$1(name, packageName + '-v')) {
+            return true;
+        }
+        return false;
+    });
+}
+// ============================================================================
+// Helper functions
+// ============================================================================
+/**
+ * Checks if string starts with prefix (no regex).
+ *
+ * @param str - The string to check
+ * @param prefix - The prefix to look for
+ * @returns True if str starts with the given prefix
+ */
+function startsWithPrefix$1(str, prefix) {
+    if (prefix.length > str.length)
+        return false;
+    for (let i = 0; i < prefix.length; i++) {
+        if (str[i] !== prefix[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Maximum tag pattern length.
+ */
+const MAX_PATTERN_LENGTH = 256;
+/**
+ * Escapes a tag pattern for safe use in git commands.
+ *
+ * @param pattern - Pattern to escape
+ * @returns Safe pattern string
+ */
+function escapeGitTagPattern(pattern) {
+    if (!pattern || typeof pattern !== 'string') {
+        throw createError('Pattern is required');
+    }
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        throw createError(`Pattern exceeds maximum length of ${MAX_PATTERN_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < pattern.length; i++) {
+        const code = pattern.charCodeAt(i);
+        // Allow: a-z, A-Z, 0-9, /, -, _, ., @
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 47 || // /
+            code === 45 || // -
+            code === 95 || // _
+            code === 46 || // .
+            code === 64 // @
+        ) {
+            safe.push(pattern[i]);
+        }
+        else {
+            throw createError(`Invalid character in pattern at position ${i}: "${pattern[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+
+/**
+ * Creates a new tag.
+ *
+ * @param name - The name for the new tag
+ * @param options - Configuration including optional message for annotated tags
+ * @returns Created GitTag
+ *
+ * @example
+ * // Create lightweight tag
+ * const tag = createTag('v1.0.0')
+ *
+ * // Create annotated tag
+ * const tag = createTag('v1.0.0', { message: 'Release v1.0.0' })
+ */
+function createTag(name, options = {}) {
+    const opts = { ...DEFAULT_TAG_OPTIONS, ...options };
+    const safeName = escapeGitRef(name);
+    const args = ['tag'];
+    if (opts.force) {
+        args.push('-f');
+    }
+    if (opts.message) {
+        // Annotated tag
+        args.push('-a');
+        args.push(safeName);
+        args.push('-m');
+        args.push(`"${escapeGitMessage(opts.message)}"`);
+    }
+    else {
+        // Lightweight tag
+        args.push(safeName);
+    }
+    if (opts.target) {
+        args.push(escapeGitRef(opts.target));
+    }
+    try {
+        execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Get the created tag
+        const tag = getTag(name, opts);
+        if (!tag) {
+            throw createError(`Failed to retrieve created tag: ${name}`);
+        }
+        return tag;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw createError(`Failed to create tag ${name}: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Deletes a tag.
+ *
+ * @param name - The tag name to delete
+ * @param options - Configuration for the tag operation
+ * @returns True if deleted
+ *
+ * @example
+ * const deleted = deleteTag('v1.0.0')
+ */
+function deleteTag(name, options = {}) {
+    const opts = { ...DEFAULT_TAG_OPTIONS, ...options };
+    const safeName = escapeGitRef(name);
+    try {
+        execSync(`git tag -d ${safeName}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pushes a tag to a remote.
+ *
+ * @param name - The tag to push to the remote
+ * @param remote - Remote name (defaults to 'origin')
+ * @param options - Configuration for the tag operation
+ * @returns True if pushed successfully
+ *
+ * @example
+ * pushTag('v1.0.0')
+ * pushTag('v1.0.0', 'upstream')
+ */
+function pushTag(name, remote = 'origin', options = {}) {
+    const opts = { ...DEFAULT_TAG_OPTIONS, ...options };
+    const safeName = escapeGitRef(name);
+    const safeRemote = escapeGitRef(remote);
+    try {
+        execSync(`git push ${safeRemote} ${safeName}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout * 3, // Allow more time for network
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Security helpers
+// ============================================================================
+/**
+ * Maximum message length.
+ */
+const MAX_MESSAGE_LENGTH = 10000;
+/**
+ * Escapes a message for safe use in git commands.
+ *
+ * @param message - Message to escape
+ * @returns Safe message string
+ */
+function escapeGitMessage(message) {
+    if (!message || typeof message !== 'string') {
+        throw createError('Message is required');
+    }
+    if (message.length > MAX_MESSAGE_LENGTH) {
+        throw createError(`Message exceeds maximum length of ${MAX_MESSAGE_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < message.length; i++) {
+        const char = message[i];
+        const code = message.charCodeAt(i);
+        // Escape double quotes and backslashes
+        if (char === '"' || char === '\\') {
+            safe.push('\\');
+            safe.push(char);
+        }
+        // Allow printable ASCII and common whitespace
+        else if ((code >= 32 && code <= 126) || // Printable ASCII
+            code === 10 || // newline
+            code === 13 || // carriage return
+            code === 9 // tab
+        ) {
+            safe.push(char);
+        }
+        // Skip other control characters
+    }
+    return safe.join('');
+}
+
+/**
+ * Default commit options.
+ */
+const DEFAULT_COMMIT_OPTIONS = {
+    timeout: 30000,
+};
+/**
+ * Creates a new commit.
+ *
+ * @param message - Commit message (subject line)
+ * @param options - Create options
+ * @returns Created GitCommit
+ *
+ * @example
+ * const commit = createCommit('feat: add new feature')
+ * const commit = createCommit('fix: resolve bug', { body: 'Detailed description' })
+ */
+function commit(message, options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    // noEdit is only valid when amending - reuse existing commit message
+    const isNoEditAmend = opts.amend && opts.noEdit;
+    if (!isNoEditAmend && (!message || typeof message !== 'string')) {
+        throw createError('Commit message is required');
+    }
+    const args = ['commit'];
+    if (isNoEditAmend) {
+        // Amend without changing the message
+        args.push('--amend', '--no-edit');
+    }
+    else {
+        const safeMessage = escapeGitMessage(message);
+        // Build message with optional body
+        let fullMessage = safeMessage;
+        if (opts.body) {
+            const safeBody = escapeGitMessage(opts.body);
+            fullMessage = `${safeMessage}\n\n${safeBody}`;
+        }
+        args.push('-m', `"${fullMessage}"`);
+        if (opts.amend) {
+            args.push('--amend');
+        }
+    }
+    if (opts.allowEmpty) {
+        args.push('--allow-empty');
+    }
+    if (opts.sign) {
+        args.push('-S');
+    }
+    if (opts.noVerify) {
+        args.push('--no-verify');
+    }
+    if (opts.author) {
+        const safeAuthor = escapeAuthor(opts.author);
+        args.push(`--author="${safeAuthor}"`);
+    }
+    // Add specific files if provided
+    if (opts.files && opts.files.length > 0) {
+        args.push('--');
+        for (const file of opts.files) {
+            args.push(escapeFilePath(file));
+        }
+    }
+    try {
+        execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Get the created commit
+        const commit = getCommit('HEAD', opts);
+        if (!commit) {
+            throw createError('Failed to retrieve created commit');
+        }
+        return commit;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw createError(`Failed to create commit: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Amends the last commit with new message.
+ *
+ * @param message - The new commit message to use
+ * @param options - Configuration for the commit operation
+ * @returns GitCommit object representing the amended commit
+ *
+ * @example
+ * const commit = amendCommit('feat: improved feature')
+ */
+function amendCommit(message, options = {}) {
+    return commit(message, { ...options, amend: true });
+}
+/**
+ * Creates an empty commit (useful for CI triggers).
+ *
+ * @param message - Text for the empty commit
+ * @param options - Configuration for the commit operation
+ * @returns GitCommit object representing the new empty commit
+ *
+ * @example
+ * const commit = createEmptyCommit('chore: trigger CI')
+ */
+function createEmptyCommit(message, options = {}) {
+    return commit(message, { ...options, allowEmpty: true });
+}
+// ============================================================================
+// Security helpers - character-by-character validation (no regex)
+// ============================================================================
+/**
+ * Maximum file path length.
+ */
+const MAX_PATH_LENGTH = 4096;
+/**
+ * Escapes a file path for safe use in git commands.
+ *
+ * @param path - Path to escape
+ * @returns Safe path string
+ */
+function escapeFilePath(path) {
+    if (!path || typeof path !== 'string') {
+        throw createError('File path is required');
+    }
+    if (path.length > MAX_PATH_LENGTH) {
+        throw createError(`Path exceeds maximum length of ${MAX_PATH_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < path.length; i++) {
+        const code = path.charCodeAt(i);
+        // Allow: a-z, A-Z, 0-9, /, \, -, _, ., space
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 47 || // /
+            code === 92 || // \
+            code === 45 || // -
+            code === 95 || // _
+            code === 46 || // .
+            code === 32 // space
+        ) {
+            safe.push(path[i]);
+        }
+        else {
+            throw createError(`Invalid character in path at position ${i}: "${path[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+/**
+ * Maximum author length.
+ */
+const MAX_AUTHOR_LENGTH = 500;
+/**
+ * Escapes an author string for safe use in git commands.
+ * Format: "Name <email>"
+ *
+ * @param author - Author to escape
+ * @returns Safe author string
+ */
+function escapeAuthor(author) {
+    if (!author || typeof author !== 'string') {
+        throw createError('Author is required');
+    }
+    if (author.length > MAX_AUTHOR_LENGTH) {
+        throw createError(`Author exceeds maximum length of ${MAX_AUTHOR_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < author.length; i++) {
+        const code = author.charCodeAt(i);
+        // Allow: a-z, A-Z, 0-9, space, @, ., -, _, <, >
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 32 || // space
+            code === 64 || // @
+            code === 46 || // .
+            code === 45 || // -
+            code === 95 || // _
+            code === 60 || // <
+            code === 62 // >
+        ) {
+            safe.push(author[i]);
+        }
+        else {
+            throw createError(`Invalid character in author at position ${i}: "${author[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+
+/**
+ * Gets the current HEAD commit hash.
+ *
+ * @param options - Git operation configuration
+ * @returns HEAD commit hash or null
+ *
+ * @example
+ * const head = getHead()
+ */
+function getHead(options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    try {
+        return execSync('git rev-parse HEAD', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets the current branch name.
+ *
+ * @param options - Configuration for the operation
+ * @returns Branch name or null if detached
+ *
+ * @example
+ * const branch = getCurrentBranch()
+ */
+function getCurrentBranch(options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    try {
+        const result = execSync('git symbolic-ref --short HEAD', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return result || null;
+    }
+    catch {
+        // Detached HEAD or not a git repo
+        return null;
+    }
+}
+/**
+ * Checks if there are untracked files.
+ *
+ * @param options - Configuration for the operation
+ * @returns True if there are untracked files in the working directory
+ */
+function hasUntrackedFiles(options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    try {
+        const result = execSync('git ls-files --others --exclude-standard', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return result.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * Stages files for commit.
+ *
+ * @param files - Array of file paths relative to working directory
+ * @param options - Configuration for the staging operation
+ * @returns True if staging succeeded
+ *
+ * @example
+ * stage(['package.json', 'CHANGELOG.md'])
+ * stage(['.'], { all: true })
+ */
+function stage(files, options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    const args = ['add'];
+    if (opts.all) {
+        args.push('-A');
+    }
+    else if (opts.update) {
+        args.push('-u');
+    }
+    if (opts.force) {
+        args.push('-f');
+    }
+    // Add files
+    for (const file of files) {
+        args.push(escapeFilePath(file));
+    }
+    try {
+        execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Unstages files.
+ *
+ * @param files - Array of file paths to remove from staging area
+ * @param options - Configuration for the unstage operation
+ * @returns True if unstaging succeeded
+ *
+ * @example
+ * unstage(['package.json'])
+ */
+function unstage(files, options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    const args = ['reset', 'HEAD', '--'];
+    for (const file of files) {
+        args.push(escapeFilePath(file));
+    }
+    try {
+        execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Stages all changes (tracked and untracked).
+ *
+ * @param options - Configuration for the staging operation
+ * @returns True if all changes were successfully added to the index
+ *
+ * @example
+ * stageAll() // stages all tracked and untracked changes
+ */
+function stageAll(options = {}) {
+    return stage(['.'], { ...options, all: true });
+}
+/**
+ * Checks if there are staged changes.
+ *
+ * @param options - Configuration for the operation
+ * @returns True if there are staged changes ready to commit
+ *
+ * @example
+ * if (hasStagedChanges()) { createCommit('...') }
+ */
+function hasStagedChanges(options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    try {
+        execSync('git diff --cached --quiet', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Exit code 0 means no changes
+        return false;
+    }
+    catch {
+        // Exit code 1 means there are changes
+        return true;
+    }
+}
+/**
+ * Checks if there are unstaged changes (working tree dirty).
+ *
+ * @param options - Configuration for the operation
+ * @returns True if there are unstaged changes in the working tree
+ *
+ * @example
+ * if (hasUnstagedChanges()) { stage(['.']) }
+ */
+function hasUnstagedChanges(options = {}) {
+    const opts = { ...DEFAULT_COMMIT_OPTIONS, ...options };
+    try {
+        execSync('git diff --quiet', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Exit code 0 means no changes
+        return false;
+    }
+    catch {
+        // Exit code 1 means there are changes
+        return true;
+    }
+}
+
+/**
+ * Default status options.
+ */
+const DEFAULT_STATUS_OPTIONS = {
+    timeout: 10000,
+};
+/**
+ * Gets the full repository status.
+ *
+ * @param options - Configuration for the status query
+ * @returns Comprehensive repository status information
+ *
+ * @example
+ * const status = getStatus()
+ * if (!status.clean) {
+ *   console.log('Working tree has changes')
+ * }
+ */
+function getStatus(options = {}) {
+    const opts = { ...DEFAULT_STATUS_OPTIONS, ...options };
+    // Get porcelain status with branch info
+    const output = execSync('git status --porcelain=v2 --branch', {
+        encoding: 'utf-8',
+        cwd: opts.cwd,
+        timeout: opts.timeout,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return parseStatus(output);
+}
+/**
+ * Parses git status porcelain v2 output.
+ *
+ * @param output - Raw status output
+ * @returns Parsed status
+ */
+function parseStatus(output) {
+    const lines = output.split('\n');
+    let branch = null;
+    let detached = false;
+    let upstream;
+    let ahead = 0;
+    let behind = 0;
+    const staged = [];
+    const modified = [];
+    const untracked = [];
+    let hasConflicts = false;
+    for (const line of lines) {
+        if (!line)
+            continue;
+        // Branch headers
+        if (startsWithPrefix(line, '# branch.head ')) {
+            const branchName = line.slice(14);
+            if (branchName === '(detached)') {
+                detached = true;
+            }
+            else {
+                branch = branchName;
+            }
+        }
+        else if (startsWithPrefix(line, '# branch.upstream ')) {
+            upstream = line.slice(18);
+        }
+        else if (startsWithPrefix(line, '# branch.ab ')) {
+            const ab = parseAheadBehind(line.slice(12));
+            ahead = ab.ahead;
+            behind = ab.behind;
+        }
+        // Changed entries (ordinary changed)
+        else if (line[0] === '1') {
+            const entry = parseChangedEntry(line);
+            if (entry) {
+                if (entry.indexStatus) {
+                    staged.push(entry);
+                }
+                if (entry.workTreeStatus && entry.workTreeStatus !== 'untracked') {
+                    modified.push(entry);
+                }
+            }
+        }
+        // Renamed/copied entries
+        else if (line[0] === '2') {
+            const entry = parseRenamedEntry(line);
+            if (entry) {
+                if (entry.indexStatus) {
+                    staged.push(entry);
+                }
+                if (entry.workTreeStatus) {
+                    modified.push(entry);
+                }
+            }
+        }
+        // Unmerged entries
+        else if (line[0] === 'u') {
+            hasConflicts = true;
+            const entry = parseUnmergedEntry(line);
+            if (entry) {
+                staged.push(entry);
+            }
+        }
+        // Untracked entries
+        else if (line[0] === '?') {
+            const path = line.slice(2);
+            untracked.push(path);
+        }
+    }
+    const clean = staged.length === 0 && modified.length === 0 && untracked.length === 0 && !hasConflicts;
+    return {
+        branch,
+        detached,
+        upstream,
+        ahead,
+        behind,
+        staged,
+        modified,
+        untracked,
+        clean,
+        hasConflicts,
+    };
+}
+/**
+ * Parses ahead/behind string.
+ *
+ * @param str - String like "+5 -2"
+ * @returns Parsed values
+ */
+function parseAheadBehind(str) {
+    let ahead = 0;
+    let behind = 0;
+    const parts = str.split(' ');
+    for (const part of parts) {
+        if (part[0] === '+') {
+            ahead = parseInt(part.slice(1), 10) || 0;
+        }
+        else if (part[0] === '-') {
+            behind = parseInt(part.slice(1), 10) || 0;
+        }
+    }
+    return { ahead, behind };
+}
+/**
+ * Parses a changed entry line.
+ *
+ * @param line - Status line starting with '1'
+ * @returns Parsed entry or null
+ */
+function parseChangedEntry(line) {
+    // Format: 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+    const parts = line.split(' ');
+    if (parts.length < 9)
+        return null;
+    const xy = parts[1];
+    const path = parts.slice(8).join(' ');
+    const indexStatus = statusFromChar(xy[0]);
+    const workTreeStatus = statusFromChar(xy[1]);
+    return {
+        path,
+        indexStatus,
+        workTreeStatus,
+    };
+}
+/**
+ * Parses a renamed entry line.
+ *
+ * @param line - Status line starting with '2'
+ * @returns Parsed entry or null
+ */
+function parseRenamedEntry(line) {
+    // Format: 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><tab><origPath>
+    const parts = line.split(' ');
+    if (parts.length < 10)
+        return null;
+    const xy = parts[1];
+    const pathPart = parts.slice(9).join(' ');
+    // Split by tab
+    const tabIndex = pathPart.indexOf('\t');
+    const path = tabIndex >= 0 ? pathPart.slice(0, tabIndex) : pathPart;
+    const origPath = tabIndex >= 0 ? pathPart.slice(tabIndex + 1) : undefined;
+    const indexStatus = statusFromChar(xy[0]);
+    const workTreeStatus = statusFromChar(xy[1]);
+    return {
+        path,
+        indexStatus,
+        workTreeStatus,
+        origPath,
+    };
+}
+/**
+ * Parses an unmerged entry line.
+ *
+ * @param line - Status line starting with 'u'
+ * @returns Parsed entry or null
+ */
+function parseUnmergedEntry(line) {
+    // Format: u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+    const parts = line.split(' ');
+    if (parts.length < 11)
+        return null;
+    const path = parts.slice(10).join(' ');
+    return {
+        path,
+        indexStatus: 'unmerged',
+        workTreeStatus: 'unmerged',
+    };
+}
+/**
+ * Converts status character to FileStatus.
+ *
+ * @param char - Status character
+ * @returns FileStatus or null
+ */
+function statusFromChar(char) {
+    switch (char) {
+        case 'M':
+            return 'modified';
+        case 'T':
+            return 'modified'; // Type change
+        case 'A':
+            return 'added';
+        case 'D':
+            return 'deleted';
+        case 'R':
+            return 'renamed';
+        case 'C':
+            return 'copied';
+        case 'U':
+            return 'unmerged';
+        case '?':
+            return 'untracked';
+        case '!':
+            return 'ignored';
+        case '.':
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Checks if string starts with prefix (no regex).
+ *
+ * @param str - The string to check
+ * @param prefix - The prefix to look for
+ * @returns True if str starts with the given prefix
+ */
+function startsWithPrefix(str, prefix) {
+    if (prefix.length > str.length)
+        return false;
+    for (let i = 0; i < prefix.length; i++) {
+        if (str[i] !== prefix[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Checks if the working tree is clean (no changes).
+ *
+ * @param options - Configuration for the status check
+ * @returns True if working tree is clean with no uncommitted changes
+ *
+ * @example
+ * if (!isClean()) {
+ *   throw new Error('Working tree has changes')
+ * }
+ */
+function isClean(options = {}) {
+    const status = getStatus(options);
+    return status.clean;
+}
+/**
+ * Checks if the directory is a git repository.
+ *
+ * @param options - Status options
+ * @returns True if in a git repository
+ *
+ * @example
+ * if (!isGitRepository()) {
+ *   throw new Error('Not a git repository')
+ * }
+ */
+function isGitRepository(options = {}) {
+    const opts = { ...DEFAULT_STATUS_OPTIONS, ...options };
+    try {
+        execSync('git rev-parse --is-inside-work-tree', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gets the repository root directory.
+ *
+ * @param options - Status options
+ * @returns Root directory path or null
+ *
+ * @example
+ * const root = getRepositoryRoot()
+ */
+function getRepositoryRoot(options = {}) {
+    const opts = { ...DEFAULT_STATUS_OPTIONS, ...options };
+    try {
+        return execSync('git rev-parse --show-toplevel', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets the current commit hash (HEAD).
+ *
+ * @param options - Status options
+ * @returns Commit hash or null
+ */
+function getHeadHash(options = {}) {
+    const opts = { ...DEFAULT_STATUS_OPTIONS, ...options };
+    try {
+        return execSync('git rev-parse HEAD', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets the short current commit hash.
+ *
+ * @param options - Status options
+ * @returns Short hash or null
+ */
+function getHeadShortHash(options = {}) {
+    const opts = { ...DEFAULT_STATUS_OPTIONS, ...options };
+    try {
+        return execSync('git rev-parse --short HEAD', {
+            encoding: 'utf-8',
+            cwd: opts.cwd,
+            timeout: opts.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Checks if there are merge conflicts.
+ *
+ * @param options - Status options
+ * @returns True if there are conflicts
+ */
+function hasConflicts(options = {}) {
+    const status = getStatus(options);
+    return status.hasConflicts;
+}
+/**
+ * Gets the number of commits ahead of upstream.
+ *
+ * @param options - Status options
+ * @returns Number of commits ahead
+ */
+function getAheadCount(options = {}) {
+    const status = getStatus(options);
+    return status.ahead;
+}
+/**
+ * Gets the number of commits behind upstream.
+ *
+ * @param options - Status options
+ * @returns Number of commits behind
+ */
+function getBehindCount(options = {}) {
+    const status = getStatus(options);
+    return status.behind;
+}
+/**
+ * Checks if the repository needs to be pushed.
+ *
+ * @param options - Status options
+ * @returns True if there are unpushed commits
+ */
+function needsPush(options = {}) {
+    return getAheadCount(options) > 0;
+}
+/**
+ * Checks if the repository needs to be pulled.
+ *
+ * @param options - Status options
+ * @returns True if there are commits to pull
+ */
+function needsPull(options = {}) {
+    return getBehindCount(options) > 0;
+}
+/**
+ * Gets list of staged file paths.
+ *
+ * @param options - Status options
+ * @returns Array of staged file paths
+ */
+function getStagedFiles(options = {}) {
+    const status = getStatus(options);
+    return status.staged.map((e) => e.path);
+}
+/**
+ * Gets list of modified file paths (unstaged).
+ *
+ * @param options - Status options
+ * @returns Array of modified file paths
+ */
+function getModifiedFiles(options = {}) {
+    const status = getStatus(options);
+    return status.modified.map((e) => e.path);
+}
+/**
+ * Gets list of untracked file paths.
+ *
+ * @param options - Status options
+ * @returns Array of untracked file paths
+ */
+function getUntrackedFiles(options = {}) {
+    const status = getStatus(options);
+    return status.untracked;
+}
+
+/**
+ * Default git client configuration.
+ */
+const DEFAULT_GIT_CLIENT_CONFIG = {
+    cwd: process.cwd(),
+    timeout: 30000,
+    throwOnError: true,
+};
+/**
+ * Creates a git client for a specific working directory.
+ *
+ * @param config - Client configuration
+ * @returns GitClient instance
+ *
+ * @example
+ * const git = createGitClient({ cwd: '/path/to/repo' })
+ * const status = git.getStatus()
+ * const commits = git.getCommitsSince('v1.0.0')
+ */
+function createGitClient(config = {}) {
+    const cwd = config.cwd ?? process.cwd();
+    const timeout = config.timeout ?? DEFAULT_GIT_CLIENT_CONFIG.timeout;
+    const opts = { cwd, timeout };
+    return {
+        cwd,
+        timeout,
+        // Log operations
+        getCommitLog: (options) => getCommitLog({ ...opts, ...options }),
+        getCommitsBetween: (from, to, options) => getCommitsBetween(from, to, { ...opts, ...options }),
+        getCommitsSince: (since, options) => getCommitsSince(since, { ...opts, ...options }),
+        getCommit: (hash) => getCommit(hash, opts),
+        commitExists: (hash) => commitExists(hash, opts),
+        // Tag operations
+        getTags: (options) => getTags({ ...opts, ...options }),
+        getTag: (name) => getTag(name, opts),
+        createTag: (name, options) => createTag(name, { ...opts, ...options }),
+        deleteTag: (name) => deleteTag(name, opts),
+        tagExists: (name) => tagExists(name, opts),
+        getLatestTag: (options) => getLatestTag({ ...opts, ...options }),
+        getTagsForPackage: (packageName, options) => getTagsForPackage(packageName, { ...opts, ...options }),
+        pushTag: (name, remote) => pushTag(name, remote, opts),
+        // Commit operations
+        createCommit: (message, options) => commit(message, { ...opts, ...options }),
+        stage: (files, options) => stage(files, { ...opts, ...options }),
+        unstage: (files) => unstage(files, opts),
+        stageAll: () => stageAll(opts),
+        amendCommit: (message, options) => amendCommit(message, { ...opts, ...options }),
+        createEmptyCommit: (message, options) => createEmptyCommit(message, { ...opts, ...options }),
+        getHead: () => getHead(opts),
+        getCurrentBranch: () => getCurrentBranch(opts),
+        hasStagedChanges: () => hasStagedChanges(opts),
+        hasUnstagedChanges: () => hasUnstagedChanges(opts),
+        hasUntrackedFiles: () => hasUntrackedFiles(opts),
+        // Status operations
+        getStatus: () => getStatus(opts),
+        isClean: () => isClean(opts),
+        isGitRepository: () => isGitRepository(opts),
+        getRepositoryRoot: () => getRepositoryRoot(opts),
+        getHeadHash: () => getHeadHash(opts),
+        getHeadShortHash: () => getHeadShortHash(opts),
+        hasConflicts: () => hasConflicts(opts),
+        getAheadCount: () => getAheadCount(opts),
+        getBehindCount: () => getBehindCount(opts),
+        needsPush: () => needsPush(opts),
+        needsPull: () => needsPull(opts),
+        getStagedFiles: () => getStagedFiles(opts),
+        getModifiedFiles: () => getModifiedFiles(opts),
+        getUntrackedFiles: () => getUntrackedFiles(opts),
+        // Ref operations
+        getRefs: () => getRefs(opts),
+        getBranches: () => getBranches(opts),
+        getRemoteBranches: (remote) => getRemoteBranches(opts, remote),
+        fetch: (remote, options) => fetch(opts, remote, options),
+        pull: (remote, branch) => pull(opts, remote, branch),
+        push: (remote, branch, options) => push(opts, remote, branch, options),
+    };
+}
+// ============================================================================
+// Additional ref operations used by the client
+// ============================================================================
+/**
+ * Gets all refs from the repository.
+ *
+ * @param options - Configuration object containing cwd and timeout
+ * @param options.cwd - Working directory for the git command
+ * @param options.timeout - Command timeout in milliseconds
+ * @returns Array of GitRef objects representing all refs in the repository
+ */
+function getRefs(options) {
+    try {
+        const output = execSync('git show-ref', {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const refs = [];
+        const lines = output.split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            // Format: <hash> <refname>
+            const spaceIndex = trimmed.indexOf(' ');
+            if (spaceIndex === -1)
+                continue;
+            const hash = trimmed.slice(0, spaceIndex);
+            const fullName = trimmed.slice(spaceIndex + 1);
+            refs.push(createGitRef({ fullName, commitHash: hash }));
+        }
+        return refs;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Gets local branches.
+ *
+ * @param options - Configuration object containing cwd and timeout
+ * @param options.cwd - Working directory for the git command
+ * @param options.timeout - Command timeout in milliseconds
+ * @returns Array of GitRef objects representing local branches
+ */
+function getBranches(options) {
+    const refs = getRefs(options);
+    return refs.filter((ref) => ref.type === 'branch');
+}
+/**
+ * Gets remote branches.
+ *
+ * @param options - Configuration object containing cwd and timeout
+ * @param options.cwd - Working directory for the git command
+ * @param options.timeout - Command timeout in milliseconds
+ * @param remote - Optional remote name to filter branches by
+ * @returns Array of GitRef objects representing remote branches
+ */
+function getRemoteBranches(options, remote) {
+    const refs = getRefs(options);
+    return refs.filter((ref) => {
+        if (ref.type !== 'remote')
+            return false;
+        if (remote && ref.remote !== remote)
+            return false;
+        return true;
+    });
+}
+/**
+ * Fetches from remote.
+ *
+ * @param options - Configuration object containing cwd and timeout
+ * @param options.cwd - Working directory for the git command
+ * @param options.timeout - Command timeout in milliseconds
+ * @param remote - Remote name to fetch from (defaults to 'origin')
+ * @param fetchOptions - Additional fetch configuration
+ * @param fetchOptions.prune - Whether to prune deleted remote branches
+ * @param fetchOptions.tags - Whether to fetch tags
+ * @returns True if fetch succeeded
+ */
+function fetch(options, remote = 'origin', fetchOptions) {
+    const args = ['fetch', remote];
+    if (fetchOptions?.prune) {
+        args.push('--prune');
+    }
+    if (fetchOptions?.tags) {
+        args.push('--tags');
+    }
+    try {
+        execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout * 3, // Allow more time for network
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pulls from remote.
+ *
+ * @param options - Configuration object containing cwd and timeout
+ * @param options.cwd - Working directory for the git command
+ * @param options.timeout - Command timeout in milliseconds
+ * @param remote - Remote name to pull from (defaults to 'origin')
+ * @param branch - Optional branch name to pull
+ * @returns True if pull succeeded
+ */
+function pull(options, remote = 'origin', branch) {
+    const args = ['pull', remote];
+    if (branch) {
+        args.push(branch);
+    }
+    try {
+        execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout * 3,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pushes to remote.
+ *
+ * @param options - Configuration object containing cwd and timeout
+ * @param options.cwd - Working directory for the git command
+ * @param options.timeout - Command timeout in milliseconds
+ * @param remote - Remote name to push to (defaults to 'origin')
+ * @param branch - Optional branch name to push
+ * @param pushOptions - Additional push configuration
+ * @param pushOptions.force - Whether to force push
+ * @param pushOptions.setUpstream - Whether to set upstream tracking
+ * @returns True if push succeeded
+ */
+function push(options, remote = 'origin', branch, pushOptions) {
+    const args = ['push', remote];
+    if (branch) {
+        args.push(branch);
+    }
+    if (pushOptions?.force) {
+        args.push('--force');
+    }
+    if (pushOptions?.setUpstream) {
+        args.push('--set-upstream');
+    }
+    try {
+        execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout * 3,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * Creates a new cache instance.
+ *
+ * @param ttl - Time-to-live in milliseconds (default: 60000 = 1 minute)
+ * @returns A new Cache instance
+ */
+function createCache(ttl = 60000) {
+    const entries = createMap();
+    return {
+        get(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return undefined;
+            const now = dateNow();
+            if (now - entry.timestamp > ttl) {
+                entries.delete(key);
+                return undefined;
+            }
+            return entry.data;
+        },
+        set(key, value) {
+            entries.set(key, { data: value, timestamp: dateNow() });
+        },
+        delete(key) {
+            entries.delete(key);
+        },
+        clear() {
+            entries.clear();
+        },
+        size() {
+            return entries.size;
+        },
+    };
+}
+
+/**
+ * Creates an npm registry client.
+ *
+ * @param config - Registry configuration
+ * @returns A Registry implementation for npm
+ *
+ * @example
+ * const registry = createNpmRegistry()
+ * const version = await registry.getLatestVersion('@hyperfrontend/utils')
+ */
+function createNpmRegistry(config = {}) {
+    const state = {
+        config: {
+            url: config.url ?? 'https://registry.npmjs.org',
+            timeout: config.timeout ?? 10000,
+            cacheTtl: config.cacheTtl ?? 60000,
+            authToken: config.authToken,
+        },
+        cache: createCache(config.cacheTtl ?? 60000),
+    };
+    return {
+        name: 'npm',
+        url: state.config.url,
+        getLatestVersion: (packageName) => getLatestVersion(state, packageName),
+        isVersionPublished: (packageName, version) => isVersionPublished(state, packageName, version),
+        getPackageInfo: (packageName) => getPackageInfo(state, packageName),
+        getVersionInfo: (packageName, version) => getVersionInfo(state, packageName, version),
+        listVersions: (packageName) => listVersions(state, packageName),
+    };
+}
+/**
+ * Gets the latest published version of a package.
+ *
+ * @param state - Internal registry client state
+ * @param packageName - Name of the package to query
+ * @returns The latest version string, or null if not found
+ */
+async function getLatestVersion(state, packageName) {
+    const cacheKey = `latest:${packageName}`;
+    const cached = state.cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const safeName = escapePackageName(packageName);
+        const result = execSync(`npm view ${safeName} version`, {
+            encoding: 'utf-8',
+            timeout: state.config.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        const version = result || null;
+        state.cache.set(cacheKey, version);
+        return version;
+    }
+    catch {
+        state.cache.set(cacheKey, null);
+        return null;
+    }
+}
+/**
+ * Checks if a specific version is published.
+ *
+ * @param state - Internal registry client state
+ * @param packageName - Name of the package to check
+ * @param version - Semver version string to verify
+ * @returns True if the version is published
+ */
+async function isVersionPublished(state, packageName, version) {
+    const cacheKey = `published:${packageName}@${version}`;
+    const cached = state.cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const safeName = escapePackageName(packageName);
+        const safeVersion = escapeVersion(version);
+        const result = execSync(`npm view ${safeName}@${safeVersion} version`, {
+            encoding: 'utf-8',
+            timeout: state.config.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        const published = result === version;
+        state.cache.set(cacheKey, published);
+        return published;
+    }
+    catch {
+        state.cache.set(cacheKey, false);
+        return false;
+    }
+}
+/**
+ * Gets full package information.
+ *
+ * @param state - Internal registry client state
+ * @param packageName - Name of the package to query
+ * @returns Package info, or null if not found
+ */
+async function getPackageInfo(state, packageName) {
+    const cacheKey = `info:${packageName}`;
+    const cached = state.cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const safeName = escapePackageName(packageName);
+        const result = execSync(`npm view ${safeName} --json`, {
+            encoding: 'utf-8',
+            timeout: state.config.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 10 * 1024 * 1024, // 10MB
+        });
+        const data = parse(result);
+        const info = {
+            name: data.name,
+            description: data.description,
+            latestVersion: data.version,
+            versions: isArray(data.versions) ? data.versions : [data.version],
+            license: data.license,
+            repository: extractRepoUrl(data.repository),
+            homepage: data.homepage,
+            maintainers: (data.maintainers ?? []).map((m) => {
+                if (typeof m === 'string') {
+                    return { name: m };
+                }
+                return { name: m.name ?? '', email: m.email };
+            }),
+            keywords: data.keywords,
+            lastModified: data.time?.modified,
+        };
+        state.cache.set(cacheKey, info);
+        return info;
+    }
+    catch {
+        state.cache.set(cacheKey, null);
+        return null;
+    }
+}
+/**
+ * Gets version-specific information.
+ *
+ * @param state - Internal registry client state
+ * @param packageName - Name of the package to query
+ * @param version - Semver version string to look up
+ * @returns Version info, or null if not found
+ */
+async function getVersionInfo(state, packageName, version) {
+    const cacheKey = `versionInfo:${packageName}@${version}`;
+    const cached = state.cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const safeName = escapePackageName(packageName);
+        const safeVersion = escapeVersion(version);
+        const result = execSync(`npm view ${safeName}@${safeVersion} --json`, {
+            encoding: 'utf-8',
+            timeout: state.config.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 5 * 1024 * 1024, // 5MB
+        });
+        const data = parse(result);
+        const info = {
+            version: data.version,
+            publishedAt: data.time ?? createDate().toISOString(),
+            tarball: data.dist?.tarball ?? '',
+            integrity: data.dist?.integrity,
+            dependencies: data.dependencies,
+            devDependencies: data.devDependencies,
+            peerDependencies: data.peerDependencies,
+            optionalDependencies: data.optionalDependencies,
+            engines: data.engines,
+            nodeVersion: data._nodeVersion,
+            npmVersion: data._npmVersion,
+        };
+        state.cache.set(cacheKey, info);
+        return info;
+    }
+    catch {
+        state.cache.set(cacheKey, null);
+        return null;
+    }
+}
+/**
+ * Lists all published versions.
+ *
+ * @param state - Internal registry client state
+ * @param packageName - Name of the package to query
+ * @returns Array of version strings
+ */
+async function listVersions(state, packageName) {
+    const cacheKey = `versions:${packageName}`;
+    const cached = state.cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const safeName = escapePackageName(packageName);
+        const result = execSync(`npm view ${safeName} versions --json`, {
+            encoding: 'utf-8',
+            timeout: state.config.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const versions = parse(result);
+        const versionList = isArray(versions) ? versions : [versions];
+        state.cache.set(cacheKey, versionList);
+        return versionList;
+    }
+    catch {
+        state.cache.set(cacheKey, []);
+        return [];
+    }
+}
+// ============================================================================
+// Security helpers - character-by-character validation (no regex)
+// ============================================================================
+/**
+ * Maximum allowed package name length (npm limit).
+ */
+const MAX_PACKAGE_NAME_LENGTH = 214;
+/**
+ * Escapes a package name for safe use in shell commands.
+ * Uses character-by-character validation to prevent injection.
+ *
+ * @param name - Package name to escape
+ * @returns Safe package name
+ * @throws {Error} If package name contains invalid characters
+ */
+function escapePackageName(name) {
+    if (!name || typeof name !== 'string') {
+        throw createError('Package name is required');
+    }
+    if (name.length > MAX_PACKAGE_NAME_LENGTH) {
+        throw createError(`Package name exceeds maximum length of ${MAX_PACKAGE_NAME_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < name.length; i++) {
+        const code = name.charCodeAt(i);
+        // Allow: a-z, A-Z, 0-9, @, /, -, _, .
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 64 || // @
+            code === 47 || // /
+            code === 45 || // -
+            code === 95 || // _
+            code === 46 // .
+        ) {
+            safe.push(name[i]);
+        }
+        else {
+            throw createError(`Invalid character in package name at position ${i}: "${name[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+/**
+ * Maximum allowed version string length.
+ */
+const MAX_VERSION_LENGTH = 256;
+/**
+ * Escapes a version string for safe use in shell commands.
+ *
+ * @param version - Version string to escape
+ * @returns Safe version string
+ * @throws {Error} If version contains invalid characters
+ */
+function escapeVersion(version) {
+    if (!version || typeof version !== 'string') {
+        throw createError('Version is required');
+    }
+    if (version.length > MAX_VERSION_LENGTH) {
+        throw createError(`Version exceeds maximum length of ${MAX_VERSION_LENGTH}`);
+    }
+    const safe = [];
+    for (let i = 0; i < version.length; i++) {
+        const code = version.charCodeAt(i);
+        // Allow: 0-9, ., -, +, a-z, A-Z
+        if ((code >= 48 && code <= 57) || // 0-9
+            (code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            code === 46 || // .
+            code === 45 || // -
+            code === 43 // +
+        ) {
+            safe.push(version[i]);
+        }
+        else {
+            throw createError(`Invalid character in version at position ${i}: "${version[i]}"`);
+        }
+    }
+    return safe.join('');
+}
+/**
+ * Extracts repository URL from npm package repository field.
+ *
+ * @param repository - Repository field from package.json (string or object)
+ * @returns Repository URL, or undefined if not found
+ */
+function extractRepoUrl(repository) {
+    if (typeof repository === 'string')
+        return repository;
+    if (repository && typeof repository === 'object') {
+        const repo = repository;
+        if (repo.url) {
+            // Clean up git+ prefix and .git suffix
+            let url = repo.url;
+            if (url.startsWith('git+')) {
+                url = url.slice(4);
+            }
+            if (url.endsWith('.git')) {
+                url = url.slice(0, -4);
+            }
+            return url;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Creates a registry client.
+ *
+ * @param type - Type of registry to create
+ * @param config - Registry configuration
+ * @returns A Registry instance
+ *
+ * @example
+ * const registry = createRegistry('npm')
+ * const version = await registry.getLatestVersion('lodash')
+ */
+function createRegistry(type = 'npm', config = {}) {
+    switch (type) {
+        case 'npm':
+            return createNpmRegistry(config);
+        default:
+            throw createError(`Unknown registry type: ${type}`);
+    }
+}
+
+/**
+ * Default flow configuration values.
+ */
+const DEFAULT_FLOW_CONFIG = {
+    preset: 'conventional',
+    releaseTypes: ['feat', 'fix', 'perf', 'revert'],
+    minorTypes: ['feat'],
+    patchTypes: ['fix', 'perf', 'revert'],
+    skipGit: false,
+    skipTag: false,
+    skipChangelog: false,
+    dryRun: false,
+    commitMessage: 'chore(${projectName}): release version ${version}',
+    tagFormat: '${projectName}@${version}',
+    trackDeps: false,
+    releaseBranch: 'main',
+    firstReleaseVersion: '0.1.0',
+    allowPrerelease: false,
+    prereleaseId: 'alpha',
+    releaseAs: undefined,
+};
+
+/**
+ * Resolves the project root path from workspace root and project name.
+ *
+ * For now, uses a simple convention: libs/{projectName} or apps/{projectName}
+ * In a real implementation, this would query the workspace configuration.
+ *
+ * @param workspaceRoot - Workspace root path
+ * @param projectName - Project name (e.g., 'lib-versioning')
+ * @returns Absolute path to project root
+ */
+function resolveProjectRoot(workspaceRoot, projectName) {
+    // Remove 'lib-' or 'app-' prefix to get the folder name
+    let folderName = projectName;
+    let prefix = 'libs';
+    if (projectName.startsWith('lib-')) {
+        folderName = projectName.slice(4);
+        prefix = 'libs';
+    }
+    else if (projectName.startsWith('app-')) {
+        folderName = projectName.slice(4);
+        prefix = 'apps';
+    }
+    return `${workspaceRoot}/${prefix}/${folderName}`;
+}
+/**
+ * Resolves the package name from the project root.
+ *
+ * @param tree - Virtual file system tree
+ * @param projectRoot - Project root path
+ * @returns Package name from package.json
+ */
+function resolvePackageName(tree, projectRoot) {
+    const packageJsonPath = `${projectRoot}/package.json`;
+    try {
+        const content = tree.read(packageJsonPath, 'utf-8');
+        if (!content) {
+            return 'unknown';
+        }
+        const pkg = parse(content);
+        return pkg.name ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Builds a summary message from flow results.
+ *
+ * @param status - The overall flow status
+ * @param steps - Array of step results
+ * @param state - Final flow state
+ * @param duration - Execution duration in milliseconds
+ * @returns Human-readable summary string
+ */
+function buildSummary(status, steps, state, duration) {
+    const completed = steps.filter((s) => s.status === 'success').length;
+    const skipped = steps.filter((s) => s.status === 'skipped').length;
+    const failed = steps.filter((s) => s.status === 'failed').length;
+    let summary = `Flow ${status} in ${duration}ms: `;
+    summary += `${completed} completed, ${skipped} skipped, ${failed} failed`;
+    if (state.nextVersion) {
+        summary += `. Version: ${state.currentVersion ?? '?.?.?'} → ${state.nextVersion}`;
+    }
+    else if (status === 'success' && state.bumpType === 'none') {
+        summary += '. No release needed';
+    }
+    return summary;
+}
+/**
+ * Merges flow config with defaults.
+ *
+ * @param flowConfig - Base flow configuration
+ * @param overrides - Optional configuration overrides
+ * @returns Merged configuration
+ */
+function mergeConfig(flowConfig, overrides) {
+    return {
+        ...DEFAULT_FLOW_CONFIG,
+        ...flowConfig,
+        ...overrides,
+    };
+}
+/**
+ * Executes a version flow.
+ *
+ * This is the main entry point for running a versioning workflow.
+ * Steps are executed in order, with state accumulated between steps.
+ *
+ * @param flow - The version flow to execute
+ * @param projectName - Name of the project to version (e.g., 'lib-versioning')
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param options - Execution options
+ * @returns Flow execution result
+ *
+ * @example
+ * ```typescript
+ * import { createConventionalFlow, executeFlow } from '@hyperfrontend/versioning'
+ *
+ * const flow = createConventionalFlow({ dryRun: true })
+ * const result = await executeFlow(flow, 'lib-utils', '/path/to/workspace')
+ *
+ * console.log(result.summary)
+ * // "Flow success in 234ms: 8 completed, 0 skipped, 0 failed. Version: 1.2.3 → 1.3.0"
+ * ```
+ */
+async function executeFlow(flow, projectName, workspaceRoot, options = {}) {
+    const startTime = dateNow();
+    const flowLogger = options.logger ?? logger;
+    // Set log level based on verbose option
+    flowLogger.setLogLevel(options.verbose ? 'debug' : 'error');
+    // Merge configs
+    const config = mergeConfig(flow.config, {
+        dryRun: options.dryRun ?? flow.config.dryRun,
+    });
+    // Initialize services
+    const tree = options.tree ?? createTree(workspaceRoot);
+    const registry = options.registry ?? createRegistry('npm');
+    const git = options.git ?? createGitClient({ ...DEFAULT_GIT_CLIENT_CONFIG, cwd: workspaceRoot });
+    // Resolve paths
+    const projectRoot = resolveProjectRoot(workspaceRoot, projectName);
+    const packageName = resolvePackageName(tree, projectRoot);
+    // Initialize context
+    const context = {
+        workspaceRoot,
+        projectName,
+        projectRoot,
+        packageName,
+        tree,
+        registry,
+        git,
+        logger: flowLogger,
+        config,
+        state: {},
+    };
+    const stepResults = [];
+    let failed = false;
+    flowLogger.info(`Executing flow: ${flow.name}`);
+    flowLogger.info(`Project: ${projectName} (${packageName})`);
+    // Execute steps in order
+    for (const step of flow.steps) {
+        // Check dependencies
+        if (step.dependsOn?.length) {
+            const depsMet = step.dependsOn.every((depId) => {
+                const depResult = stepResults.find((r) => r.stepId === depId);
+                return depResult && depResult.status === 'success';
+            });
+            if (!depsMet) {
+                flowLogger.debug(`Skipping step "${step.name}": dependencies not met`);
+                stepResults.push({
+                    stepId: step.id,
+                    stepName: step.name,
+                    status: 'skipped',
+                    message: 'Dependencies not met',
+                });
+                continue;
+            }
+        }
+        // Check skip condition
+        if (step.skipIf?.(context)) {
+            flowLogger.debug(`Skipping step "${step.name}": skip condition met`);
+            stepResults.push({
+                stepId: step.id,
+                stepName: step.name,
+                status: 'skipped',
+                message: 'Skipped by condition',
+            });
+            continue;
+        }
+        // Execute step
+        try {
+            flowLogger.info(`Executing step: ${step.name}`);
+            const result = await step.execute(context);
+            // Apply state updates
+            if (result.stateUpdates) {
+                context.state = { ...context.state, ...result.stateUpdates };
+            }
+            stepResults.push({
+                stepId: step.id,
+                stepName: step.name,
+                ...result,
+            });
+            if (result.status === 'success') {
+                flowLogger.debug(`Step "${step.name}" succeeded: ${result.message ?? 'OK'}`);
+            }
+            else if (result.status === 'skipped') {
+                flowLogger.debug(`Step "${step.name}" skipped: ${result.message ?? 'No reason'}`);
+            }
+            else if (result.status === 'failed') {
+                flowLogger.error(`Step "${step.name}" failed: ${result.message ?? result.error?.message ?? 'Unknown error'}`);
+                if (!step.continueOnError) {
+                    failed = true;
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            const errorObj = error instanceof Error ? error : createError(String(error));
+            flowLogger.error(`Step "${step.name}" threw: ${errorObj.message}`);
+            stepResults.push({
+                stepId: step.id,
+                stepName: step.name,
+                status: 'failed',
+                error: errorObj,
+                message: errorObj.message,
+            });
+            if (!step.continueOnError) {
+                failed = true;
+                break;
+            }
+        }
+    }
+    // Commit VFS changes if not dry run and not failed
+    if (!config.dryRun && !failed) {
+        try {
+            commitChanges(tree, { verbose: options.verbose });
+            flowLogger.info('File changes committed to disk');
+        }
+        catch (error) {
+            flowLogger.error(`Failed to commit file changes: ${error}`);
+        }
+    }
+    else if (config.dryRun) {
+        flowLogger.info('Dry run mode - no changes written to disk');
+    }
+    const duration = dateNow() - startTime;
+    // Determine overall status
+    const status = failed
+        ? 'failed'
+        : stepResults.some((r) => r.status === 'failed')
+            ? 'partial'
+            : stepResults.every((r) => r.status === 'skipped')
+                ? 'skipped'
+                : 'success';
+    const summary = buildSummary(status, stepResults, context.state, duration);
+    flowLogger.info(summary);
+    return {
+        status,
+        steps: stepResults,
+        state: context.state,
+        duration,
+        summary,
+    };
+}
+/**
+ * Executes a flow in dry-run mode.
+ *
+ * Convenience wrapper that sets dryRun: true.
+ *
+ * @param flow - The version flow to execute
+ * @param projectName - Name of the project to version
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param options - Execution options (dryRun forced to true)
+ * @returns Flow execution result (no actual changes made)
+ */
+async function dryRun(flow, projectName, workspaceRoot, options = {}) {
+    return executeFlow(flow, projectName, workspaceRoot, {
+        ...options,
+        dryRun: true,
+    });
+}
+/**
+ * Validates a flow before execution.
+ *
+ * Checks for:
+ * - Duplicate step IDs
+ * - Invalid dependency references
+ * - Circular dependencies
+ *
+ * @param flow - The flow to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+function validateFlow(flow) {
+    const errors = [];
+    const stepIds = createSet();
+    // Check for duplicate IDs
+    for (const step of flow.steps) {
+        if (stepIds.has(step.id)) {
+            errors.push(`Duplicate step ID: "${step.id}"`);
+        }
+        stepIds.add(step.id);
+    }
+    // Check for valid dependency references
+    for (const step of flow.steps) {
+        if (step.dependsOn) {
+            for (const depId of step.dependsOn) {
+                if (!stepIds.has(depId)) {
+                    errors.push(`Step "${step.id}" depends on unknown step "${depId}"`);
+                }
+            }
+        }
+    }
+    // Check for circular dependencies (simple DFS)
+    const visited = createSet();
+    const visiting = createSet();
+    /**
+     * Recursively visits a step to detect circular dependencies.
+     *
+     * @param stepId - The step ID to check
+     * @returns True if no cycle detected, false otherwise
+     */
+    function visit(stepId) {
+        if (visiting.has(stepId)) {
+            return false; // Cycle detected
+        }
+        if (visited.has(stepId)) {
+            return true; // Already checked
+        }
+        visiting.add(stepId);
+        const step = flow.steps.find((s) => s.id === stepId);
+        if (step?.dependsOn) {
+            for (const depId of step.dependsOn) {
+                if (!visit(depId)) {
+                    errors.push(`Circular dependency detected involving step "${stepId}"`);
+                    return false;
+                }
+            }
+        }
+        visiting.delete(stepId);
+        visited.add(stepId);
+        return true;
+    }
+    for (const step of flow.steps) {
+        visit(step.id);
+    }
+    return errors;
+}
+
+export { dryRun, executeFlow, validateFlow };
+//# sourceMappingURL=index.esm.js.map