@hyperfrontend/versioning 0.1.0

package/git/index.cjs.js

@@ -0,0 +1,2863 @@
+'use strict';
+
+var node_child_process = require('node:child_process');
+
+/**
+ * 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);
+}
+/**
+ * Checks if two commits are the same based on their hash.
+ *
+ * @param a - First commit
+ * @param b - Second commit
+ * @returns True if commits have the same hash
+ */
+function isSameCommit(a, b) {
+    return a.hash === b.hash;
+}
+/**
+ * Checks if a commit is a merge commit (has multiple parents).
+ *
+ * @param commit - Commit to check
+ * @returns True if commit has more than one parent
+ */
+function isMergeCommit(commit) {
+    return commit.parents.length > 1;
+}
+/**
+ * Checks if a commit is a root commit (has no parents).
+ *
+ * @param commit - Commit to check
+ * @returns True if commit has no parents
+ */
+function isRootCommit(commit) {
+    return commit.parents.length === 0;
+}
+/**
+ * Extracts the scope from a commit subject if it follows conventional commit format.
+ * Uses character-by-character parsing (no regex).
+ *
+ * @param subject - Commit subject line
+ * @returns Scope string or undefined if no scope found
+ *
+ * @example
+ * extractScope('feat(lib-versioning): add git support') // 'lib-versioning'
+ * extractScope('fix: resolve issue') // undefined
+ */
+function extractScope(subject) {
+    // Look for pattern: type(scope): or type(scope)!:
+    let i = 0;
+    // Skip type characters (a-z)
+    while (i < subject.length) {
+        const code = subject.charCodeAt(i);
+        if (code >= 97 && code <= 122) {
+            // a-z
+            i++;
+        }
+        else {
+            break;
+        }
+    }
+    // Must find opening parenthesis
+    if (i >= subject.length || subject[i] !== '(') {
+        return undefined;
+    }
+    // Skip '('
+    i++;
+    const scopeStart = i;
+    // Find closing parenthesis
+    while (i < subject.length && subject[i] !== ')') {
+        i++;
+    }
+    if (i >= subject.length) {
+        return undefined;
+    }
+    const scope = subject.slice(scopeStart, i);
+    return scope || undefined;
+}
+/**
+ * Extracts the type from a commit subject if it follows conventional commit format.
+ * Uses character-by-character parsing (no regex).
+ *
+ * @param subject - Commit subject line
+ * @returns Type string or undefined if no valid type found
+ *
+ * @example
+ * extractType('feat(lib-versioning): add git support') // 'feat'
+ * extractType('fix: resolve issue') // 'fix'
+ * extractType('random message') // undefined
+ */
+function extractType(subject) {
+    let i = 0;
+    // Collect type characters (a-z)
+    while (i < subject.length) {
+        const code = subject.charCodeAt(i);
+        if (code >= 97 && code <= 122) {
+            // a-z
+            i++;
+        }
+        else {
+            break;
+        }
+    }
+    if (i === 0) {
+        return undefined;
+    }
+    const type = subject.slice(0, i);
+    // Next character must be '(' , '!' or ':'
+    if (i >= subject.length) {
+        return undefined;
+    }
+    const next = subject[i];
+    if (next === '(' || next === ':' || next === '!') {
+        return type;
+    }
+    return undefined;
+}
+
+/**
+ * Safe copies of Math built-in methods.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/math
+ */
+// Capture references at module initialization time
+const _Math = globalThis.Math;
+// ============================================================================
+// Min/Max
+// ============================================================================
+/**
+ * (Safe copy) Returns the larger of zero or more numbers.
+ */
+const max = _Math.max;
+
+/**
+ * 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,
+    };
+}
+/**
+ * Checks if a tag is annotated.
+ *
+ * @param tag - Tag to check
+ * @returns True if tag is annotated
+ */
+function isAnnotatedTag(tag) {
+    return tag.type === 'annotated';
+}
+/**
+ * Checks if a tag is lightweight.
+ *
+ * @param tag - Tag to check
+ * @returns True if tag is lightweight
+ */
+function isLightweightTag(tag) {
+    return tag.type === 'lightweight';
+}
+/**
+ * Extracts version from tag name.
+ * Handles common formats: v1.2.3, `@scope/package@1.2.3`, package@1.2.3
+ * Uses character-by-character parsing (no regex).
+ *
+ * @param tagName - Tag name to parse
+ * @returns The extracted version string or undefined if no version found
+ *
+ * @example
+ * extractVersionFromTag('v1.2.3') // '1.2.3'
+ * extractVersionFromTag('@scope/pkg@1.2.3') // '1.2.3'
+ * extractVersionFromTag('release-1.2.3') // '1.2.3'
+ */
+function extractVersionFromTag(tagName) {
+    // Strategy: Find last occurrence of '@' followed by version, or 'v' followed by version
+    // Version starts with digit and contains digits, dots, and possibly prerelease identifiers
+    // First, try to find @version pattern (for scoped packages)
+    let i = tagName.length - 1;
+    // Find last '@'
+    while (i >= 0 && tagName[i] !== '@') {
+        i--;
+    }
+    if (i >= 0) {
+        // Found '@', check if followed by version
+        const afterAt = tagName.slice(i + 1);
+        const version = parseVersionPart(afterAt);
+        if (version) {
+            return version;
+        }
+    }
+    // Try to find 'v' followed by version
+    i = 0;
+    while (i < tagName.length) {
+        if ((tagName[i] === 'v' || tagName[i] === 'V') && i + 1 < tagName.length) {
+            const nextCode = tagName.charCodeAt(i + 1);
+            if (nextCode >= 48 && nextCode <= 57) {
+                // 0-9
+                const version = parseVersionPart(tagName.slice(i + 1));
+                if (version) {
+                    return version;
+                }
+            }
+        }
+        i++;
+    }
+    // Try to find digit sequence after common separators (-, _)
+    i = 0;
+    while (i < tagName.length) {
+        const char = tagName[i];
+        if (char === '-' || char === '_') {
+            const afterSep = tagName.slice(i + 1);
+            const code = afterSep.charCodeAt(0);
+            if (code >= 48 && code <= 57) {
+                // 0-9
+                const version = parseVersionPart(afterSep);
+                if (version) {
+                    return version;
+                }
+            }
+        }
+        i++;
+    }
+    // Last resort: if entire string is a version
+    return parseVersionPart(tagName);
+}
+/**
+ * Parses a version-like string from the start of input.
+ * Uses character-by-character parsing (no regex).
+ *
+ * @param input - String to parse
+ * @returns Version string or undefined
+ */
+function parseVersionPart(input) {
+    if (!input)
+        return undefined;
+    // Must start with digit
+    const firstCode = input.charCodeAt(0);
+    if (firstCode < 48 || firstCode > 57) {
+        return undefined;
+    }
+    // Collect version characters: digits, dots, hyphens, plus, letters (for prerelease)
+    let i = 0;
+    let dotCount = 0;
+    while (i < input.length) {
+        const code = input.charCodeAt(i);
+        if (code >= 48 && code <= 57) {
+            // 0-9
+            i++;
+        }
+        else if (code === 46) {
+            // .
+            dotCount++;
+            i++;
+        }
+        else if (code === 45) {
+            // -
+            i++;
+        }
+        else if (code === 43) {
+            // +
+            i++;
+        }
+        else if ((code >= 97 && code <= 122) || (code >= 65 && code <= 90)) {
+            // a-z, A-Z
+            i++;
+        }
+        else {
+            break;
+        }
+    }
+    // Must have at least one dot (e.g., 1.0)
+    if (dotCount === 0) {
+        return undefined;
+    }
+    const version = input.slice(0, i);
+    // Basic validation: must contain at least two parts separated by dots
+    if (!version.includes('.')) {
+        return undefined;
+    }
+    return version;
+}
+/**
+ * Extracts package name from tag name.
+ * Handles formats like: `@scope/package@1.2.3`, package@1.2.3, package-v1.2.3
+ * Uses character-by-character parsing (no regex).
+ *
+ * @param tagName - Tag name to parse
+ * @returns The extracted package name or undefined if not found
+ *
+ * @example
+ * extractPackageFromTag('@scope/pkg@1.2.3') // '@scope/pkg'
+ * extractPackageFromTag('lib-utils@1.2.3') // 'lib-utils'
+ * extractPackageFromTag('v1.2.3') // undefined
+ */
+function extractPackageFromTag(tagName) {
+    // Find the last '@' that's followed by a version number
+    let lastVersionAt = -1;
+    let i = tagName.length - 1;
+    while (i >= 0) {
+        if (tagName[i] === '@') {
+            // Check if followed by a digit
+            if (i + 1 < tagName.length) {
+                const nextCode = tagName.charCodeAt(i + 1);
+                if (nextCode >= 48 && nextCode <= 57) {
+                    // 0-9
+                    lastVersionAt = i;
+                    break;
+                }
+            }
+        }
+        i--;
+    }
+    if (lastVersionAt > 0) {
+        return tagName.slice(0, lastVersionAt);
+    }
+    // Check for -v or _v pattern
+    i = tagName.length - 1;
+    while (i > 0) {
+        if (tagName[i] === 'v' || tagName[i] === 'V') {
+            const prev = tagName[i - 1];
+            if (prev === '-' || prev === '_') {
+                // Check if followed by digit
+                if (i + 1 < tagName.length) {
+                    const nextCode = tagName.charCodeAt(i + 1);
+                    if (nextCode >= 48 && nextCode <= 57) {
+                        return tagName.slice(0, i - 1);
+                    }
+                }
+            }
+        }
+        i--;
+    }
+    return undefined;
+}
+/**
+ * Builds a tag name from package name and version.
+ *
+ * @param packageName - Package name (e.g., '@scope/package' or 'package')
+ * @param version - Version string (e.g., '1.2.3')
+ * @param format - Tag format template, uses ${package} and ${version} placeholders
+ * @returns Formatted tag name
+ *
+ * @example
+ * buildTagName('@scope/pkg', '1.2.3') // '@scope/pkg@1.2.3'
+ * buildTagName('utils', '1.0.0', 'v${version}') // 'v1.0.0'
+ * buildTagName('pkg', '2.0.0', '${package}-v${version}') // 'pkg-v2.0.0'
+ */
+function buildTagName(packageName, version, format = '${package}@${version}') {
+    // Simple character-by-character replacement (no regex)
+    let result = '';
+    let i = 0;
+    while (i < format.length) {
+        if (i + 9 < format.length && format.slice(i, i + 10) === '${package}') {
+            result += packageName;
+            i += 10;
+        }
+        else if (i + 9 < format.length && format.slice(i, i + 10) === '${version}') {
+            result += version;
+            i += 10;
+        }
+        else {
+            result += format[i];
+            i++;
+        }
+    }
+    return result;
+}
+/**
+ * Compares two tags by version (newest first).
+ * Useful for sorting tags.
+ *
+ * @param a - First tag
+ * @param b - Second tag
+ * @returns Comparison result (-1, 0, or 1)
+ */
+function compareTagsByVersion(a, b) {
+    const versionA = extractVersionFromTag(a.name);
+    const versionB = extractVersionFromTag(b.name);
+    if (!versionA && !versionB)
+        return 0;
+    if (!versionA)
+        return 1;
+    if (!versionB)
+        return -1;
+    return compareVersionStrings(versionB, versionA); // Descending order
+}
+/**
+ * Simple version string comparison.
+ * Compares major.minor.patch numerically.
+ *
+ * @param a - First version
+ * @param b - Second version
+ * @returns Comparison result (-1, 0, or 1)
+ */
+function compareVersionStrings(a, b) {
+    const partsA = a.split('.');
+    const partsB = b.split('.');
+    const maxLen = max(partsA.length, partsB.length);
+    for (let i = 0; i < maxLen; i++) {
+        const numA = parseNumericPart(partsA[i]);
+        const numB = parseNumericPart(partsB[i]);
+        if (numA < numB)
+            return -1;
+        if (numA > numB)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Parses numeric part of version segment.
+ *
+ * @param part - Version part to parse
+ * @returns Numeric value
+ */
+function parseNumericPart(part) {
+    if (!part)
+        return 0;
+    // Extract leading digits only
+    let num = 0;
+    for (let i = 0; i < part.length; i++) {
+        const code = part.charCodeAt(i);
+        if (code >= 48 && code <= 57) {
+            num = num * 10 + (code - 48);
+        }
+        else {
+            break;
+        }
+    }
+    return num;
+}
+
+/**
+ * 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;
+}
+/**
+ * Checks if a reference is a branch.
+ *
+ * @param ref - Reference to check
+ * @returns True if reference is a branch
+ */
+function isBranchRef(ref) {
+    return ref.type === 'branch';
+}
+/**
+ * Checks if a reference is a tag.
+ *
+ * @param ref - Reference to check
+ * @returns True if reference is a tag
+ */
+function isTagRef(ref) {
+    return ref.type === 'tag';
+}
+/**
+ * Checks if a reference is a remote tracking branch.
+ *
+ * @param ref - Reference to check
+ * @returns True if reference is a remote
+ */
+function isRemoteRef(ref) {
+    return ref.type === 'remote';
+}
+/**
+ * Checks if a reference points to the current HEAD.
+ *
+ * @param ref - Reference to check
+ * @returns True if reference is HEAD
+ */
+function isHeadRef(ref) {
+    return ref.type === 'head' || ref.isHead === true;
+}
+/**
+ * Gets the tracking remote for a reference.
+ *
+ * @param ref - Reference to check
+ * @returns Remote name or undefined
+ */
+function getRemote(ref) {
+    return ref.remote;
+}
+/**
+ * Builds a full reference name from type and name.
+ *
+ * @param type - Reference type
+ * @param name - Reference name
+ * @param remote - Remote name (for remote type)
+ * @returns Full reference name
+ *
+ * @example
+ * buildRefName('branch', 'main') // 'refs/heads/main'
+ * buildRefName('tag', 'v1.0.0') // 'refs/tags/v1.0.0'
+ * buildRefName('remote', 'main', 'origin') // 'refs/remotes/origin/main'
+ */
+function buildRefName(type, name, remote) {
+    switch (type) {
+        case 'branch':
+            return `refs/heads/${name}`;
+        case 'tag':
+            return `refs/tags/${name}`;
+        case 'remote':
+            return remote ? `refs/remotes/${remote}/${name}` : `refs/remotes/${name}`;
+        case 'head':
+            return 'HEAD';
+        case 'stash':
+            return `refs/stash`;
+        default:
+            return name;
+    }
+}
+/**
+ * Compares two references by name (alphabetically).
+ *
+ * @param a - First reference
+ * @param b - Second reference
+ * @returns Comparison result (-1, 0, or 1)
+ */
+function compareRefsByName(a, b) {
+    if (a.name < b.name)
+        return -1;
+    if (a.name > b.name)
+        return 1;
+    return 0;
+}
+/**
+ * Filters references by type.
+ *
+ * @param refs - References to filter
+ * @param type - Type to filter by
+ * @returns Filtered references
+ */
+function filterRefsByType(refs, type) {
+    const result = [];
+    for (const ref of refs) {
+        if (ref.type === type) {
+            result.push(ref);
+        }
+    }
+    return result;
+}
+/**
+ * Filters references by remote.
+ *
+ * @param refs - References to filter
+ * @param remote - Remote name to filter by
+ * @returns Filtered references
+ */
+function filterRefsByRemote(refs, remote) {
+    const result = [];
+    for (const ref of refs) {
+        if (ref.remote === remote) {
+            result.push(ref);
+        }
+    }
+    return result;
+}
+
+/**
+ * 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$1 = globalThis.Reflect;
+/**
+ * (Safe copy) Creates a new Error using the captured Error constructor.
+ * Use this instead of `new Error()`.
+ *
+ * @param message - Optional error message.
+ * @param options - Optional error options.
+ * @returns A new Error instance.
+ */
+const createError = (message, options) => _Reflect$1.construct(_Error, [message, options]);
+
+/**
+ * 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 = node_child_process.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 {
+        node_child_process.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('');
+}
+
+/**
+ * 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 = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+
+/**
+ * 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;
+
+/**
+ * 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 = node_child_process.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 = node_child_process.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 = node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.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 });
+}
+/**
+ * Amends the last commit without changing the message.
+ * Useful for adding staged changes to the previous commit.
+ *
+ * @param options - Configuration for the commit operation
+ * @returns GitCommit object representing the amended commit
+ *
+ * @example
+ * stage(['extra-file.ts'])
+ * amendCommitNoEdit() // adds staged files to last commit
+ */
+function amendCommitNoEdit(options = {}) {
+    return commit('', { ...options, amend: true, noEdit: 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('');
+}
+
+/**
+ * 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 {
+        node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.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;
+    }
+}
+
+/**
+ * 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 node_child_process.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 = node_child_process.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 = node_child_process.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;
+    }
+}
+
+/**
+ * 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 = node_child_process.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 {
+        node_child_process.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 node_child_process.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 node_child_process.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 node_child_process.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 = node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.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 {
+        node_child_process.execSync(`git ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout * 3,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+exports.DEFAULT_COMMIT_OPTIONS = DEFAULT_COMMIT_OPTIONS;
+exports.DEFAULT_GIT_CLIENT_CONFIG = DEFAULT_GIT_CLIENT_CONFIG;
+exports.DEFAULT_LOG_OPTIONS = DEFAULT_LOG_OPTIONS;
+exports.DEFAULT_STATUS_OPTIONS = DEFAULT_STATUS_OPTIONS;
+exports.DEFAULT_TAG_OPTIONS = DEFAULT_TAG_OPTIONS;
+exports.amendCommit = amendCommit;
+exports.amendCommitNoEdit = amendCommitNoEdit;
+exports.buildRefName = buildRefName;
+exports.buildTagName = buildTagName;
+exports.commit = commit;
+exports.commitExists = commitExists;
+exports.compareRefsByName = compareRefsByName;
+exports.compareTagsByVersion = compareTagsByVersion;
+exports.createAnnotatedTag = createAnnotatedTag;
+exports.createEmptyCommit = createEmptyCommit;
+exports.createGitClient = createGitClient;
+exports.createGitCommit = createGitCommit;
+exports.createGitRef = createGitRef;
+exports.createLightweightTag = createLightweightTag;
+exports.createTag = createTag;
+exports.deleteTag = deleteTag;
+exports.escapeAuthor = escapeAuthor;
+exports.escapeFilePath = escapeFilePath;
+exports.escapeGitArg = escapeGitArg;
+exports.escapeGitMessage = escapeGitMessage;
+exports.escapeGitPath = escapeGitPath;
+exports.escapeGitRef = escapeGitRef;
+exports.escapeGitTagPattern = escapeGitTagPattern;
+exports.extractPackageFromTag = extractPackageFromTag;
+exports.extractScope = extractScope;
+exports.extractType = extractType;
+exports.extractVersionFromTag = extractVersionFromTag;
+exports.filterRefsByRemote = filterRefsByRemote;
+exports.filterRefsByType = filterRefsByType;
+exports.getAheadCount = getAheadCount;
+exports.getBehindCount = getBehindCount;
+exports.getCommit = getCommit;
+exports.getCommitLog = getCommitLog;
+exports.getCommitsBetween = getCommitsBetween;
+exports.getCommitsSince = getCommitsSince;
+exports.getCurrentBranch = getCurrentBranch;
+exports.getHead = getHead;
+exports.getHeadHash = getHeadHash;
+exports.getHeadShortHash = getHeadShortHash;
+exports.getLatestTag = getLatestTag;
+exports.getModifiedFiles = getModifiedFiles;
+exports.getRemote = getRemote;
+exports.getRepositoryRoot = getRepositoryRoot;
+exports.getShortHash = getShortHash;
+exports.getStagedFiles = getStagedFiles;
+exports.getStatus = getStatus;
+exports.getTag = getTag;
+exports.getTags = getTags;
+exports.getTagsForPackage = getTagsForPackage;
+exports.getUntrackedFiles = getUntrackedFiles;
+exports.hasConflicts = hasConflicts;
+exports.hasStagedChanges = hasStagedChanges;
+exports.hasUnstagedChanges = hasUnstagedChanges;
+exports.hasUntrackedFiles = hasUntrackedFiles;
+exports.isAnnotatedTag = isAnnotatedTag;
+exports.isBranchRef = isBranchRef;
+exports.isClean = isClean;
+exports.isGitRepository = isGitRepository;
+exports.isHeadRef = isHeadRef;
+exports.isLightweightTag = isLightweightTag;
+exports.isMergeCommit = isMergeCommit;
+exports.isRemoteRef = isRemoteRef;
+exports.isRootCommit = isRootCommit;
+exports.isSameCommit = isSameCommit;
+exports.isTagRef = isTagRef;
+exports.needsPull = needsPull;
+exports.needsPush = needsPush;
+exports.pushTag = pushTag;
+exports.stage = stage;
+exports.stageAll = stageAll;
+exports.tagExists = tagExists;
+exports.unstage = unstage;
+//# sourceMappingURL=index.cjs.js.map