@cyanheads/git-mcp-server 1.2.4 → 2.0.2

package/dist/mcp-server/tools/gitAdd/logic.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { promisify } from 'util';
+import { exec } from 'child_process';
+import { logger } from '../../../utils/logger.js';
+import { McpError, BaseErrorCode } from '../../../types-global/errors.js';
+import { sanitization } from '../../../utils/sanitization.js';
+const execAsync = promisify(exec);
+// Define the input schema for the git_add tool using Zod
+export const GitAddInputSchema = z.object({
+    path: z.string().min(1).optional().default('.').describe("Path to the Git repository. Defaults to the session's working directory if set via `git_set_working_dir`, otherwise defaults to the server's current working directory (`.`)."),
+    files: z.union([
+        z.string().min(1),
+        z.array(z.string().min(1))
+    ]).default('.').describe('Files or patterns to stage, defaults to all changes (\'.\')'),
+});
+/**
+ * Executes the 'git add' command and returns structured JSON output.
+ *
+ * @param {GitAddInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitAddResult>} A promise that resolves with the structured add result.
+ * @throws {McpError} Throws an McpError if path resolution or validation fails, or if the git command fails unexpectedly.
+ */
+export async function addGitFiles(input, context // Add getter to context
+) {
+    const operation = 'addGitFiles';
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve the target path
+        if (input.path && input.path !== '.') {
+            targetPath = input.path;
+            logger.debug(`Using provided path: ${targetPath}`, { ...context, operation });
+        }
+        else {
+            const workingDir = context.getWorkingDirectory();
+            if (!workingDir) {
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, "No path provided and no working directory set for the session.", { context, operation });
+            }
+            targetPath = workingDir;
+            logger.debug(`Using session working directory: ${targetPath}`, { ...context, operation, sessionId: context.sessionId });
+        }
+        // Sanitize the resolved path
+        const sanitizedPath = sanitization.sanitizePath(targetPath);
+        logger.debug('Sanitized repository path', { ...context, operation, sanitizedPath });
+        targetPath = sanitizedPath; // Use the sanitized path going forward
+    }
+    catch (error) {
+        logger.error('Path resolution or sanitization failed', { ...context, operation, error });
+        if (error instanceof McpError) {
+            throw error;
+        }
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid path: ${error instanceof Error ? error.message : String(error)}`, { context, operation, originalError: error });
+    }
+    // Prepare the files argument for the command, ensuring proper quoting
+    let filesArg;
+    const filesToStage = input.files; // Keep original for reporting
+    try {
+        if (Array.isArray(filesToStage)) {
+            if (filesToStage.length === 0) {
+                logger.warning('Empty array provided for files, defaulting to staging all changes.', { ...context, operation });
+                filesArg = '.'; // Default to staging all if array is empty
+            }
+            else {
+                // Quote each file path individually
+                filesArg = filesToStage.map(file => {
+                    const sanitizedFile = file.startsWith('-') ? `./${file}` : file; // Prefix with './' if it starts with a dash
+                    return `"${sanitizedFile.replace(/"/g, '\\"')}"`; // Escape quotes within path
+                }).join(' ');
+            }
+        }
+        else { // Single string case
+            const sanitizedFile = filesToStage.startsWith('-') ? `./${filesToStage}` : filesToStage; // Prefix with './' if it starts with a dash
+            filesArg = `"${sanitizedFile.replace(/"/g, '\\"')}"`;
+        }
+    }
+    catch (err) {
+        logger.error('File path validation/quoting failed', { ...context, operation, files: filesToStage, error: err });
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid file path/pattern provided: ${err instanceof Error ? err.message : String(err)}`, { context, operation, originalError: err });
+    }
+    // This check should ideally not be needed now due to the logic above
+    if (!filesArg) {
+        logger.error('Internal error: filesArg is unexpectedly empty after processing.', { ...context, operation });
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, 'Internal error preparing git add command.', { context, operation });
+    }
+    try {
+        // Use the resolved targetPath
+        const command = `git -C "${targetPath}" add -- ${filesArg}`;
+        logger.debug(`Executing command: ${command}`, { ...context, operation });
+        const { stdout, stderr } = await execAsync(command);
+        if (stderr) {
+            // Log stderr as warning, as 'git add' can produce warnings but still succeed.
+            logger.warning(`Git add command produced stderr`, { ...context, operation, stderr });
+        }
+        logger.info(`${operation} executed successfully`, { ...context, operation, path: targetPath, files: filesToStage });
+        const filesAddedDesc = Array.isArray(filesToStage) ? filesToStage.join(', ') : filesToStage;
+        const reminder = "Remember to write clear, concise commit messages using the Conventional Commits format (e.g., 'feat(scope): subject').";
+        // Use statusMessage and add reminder
+        return {
+            success: true,
+            statusMessage: `Successfully staged: ${filesAddedDesc}. ${reminder}`,
+            filesStaged: filesToStage
+        };
+    }
+    catch (error) {
+        logger.error(`Failed to execute git add command`, { ...context, operation, path: targetPath, error: error.message, stderr: error.stderr });
+        const errorMessage = error.stderr || error.message || '';
+        if (errorMessage.toLowerCase().includes('not a git repository')) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Path is not a Git repository: ${targetPath}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.toLowerCase().includes('did not match any files')) {
+            // Still throw an error, but return structured info in the catch block of the registration
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Specified files/patterns did not match any files in ${targetPath}: ${filesArg}`, { context, operation, originalError: error, filesStaged: filesToStage });
+        }
+        // Throw generic error for other cases
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to stage files for path: ${targetPath}. Error: ${errorMessage}`, { context, operation, originalError: error, filesStaged: filesToStage });
+    }
+}

package/dist/mcp-server/tools/gitAdd/registration.js

@@ -0,0 +1,73 @@
+import { logger } from '../../../utils/logger.js';
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+// Import the result type along with the function and input schema
+import { addGitFiles, GitAddInputSchema } from './logic.js';
+import { BaseErrorCode } from '../../../types-global/errors.js'; // Import BaseErrorCode
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the tool registration.
+ * This should be called once during server setup.
+ * @param getWdFn - Function to get the working directory for a session.
+ * @param getSidFn - Function to get the session ID from context.
+ */
+export function initializeGitAddStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_add tool registration.');
+}
+const TOOL_NAME = 'git_add';
+const TOOL_DESCRIPTION = 'Stages changes in the Git repository for the next commit by adding file contents to the index (staging area). Can stage specific files/patterns or all changes (default: \'.\'). Returns the result as a JSON object.';
+/**
+ * Registers the git_add tool with the MCP server.
+ * Uses the high-level server.tool() method for registration, schema validation, and routing.
+ *
+ * @param {McpServer} server - The McpServer instance to register the tool with.
+ * @returns {Promise<void>}
+ * @throws {Error} If registration fails or state accessors are not initialized.
+ */
+export const registerGitAddTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_add must be initialized before registration.');
+    }
+    const operation = 'registerGitAddTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitAddInputSchema.shape, // Provide the Zod schema shape
+        async (validatedArgs, callContext) => {
+            const toolOperation = 'tool:git_add';
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            const sessionId = _getSessionId(requestContext);
+            const getWorkingDirectoryForSession = () => {
+                return _getWorkingDirectory(sessionId);
+            };
+            const logicContext = {
+                ...requestContext,
+                sessionId: sessionId,
+                getWorkingDirectory: getWorkingDirectoryForSession,
+            };
+            logger.info(`Executing tool: ${TOOL_NAME}`, logicContext);
+            return await ErrorHandler.tryCatch(async () => {
+                // Call the core logic function which now returns a GitAddResult object
+                const addResult = await addGitFiles(validatedArgs, logicContext);
+                // Format the successful result as a JSON string within TextContent
+                const resultContent = {
+                    type: 'text',
+                    // Stringify the JSON object for the response content
+                    text: JSON.stringify(addResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json',
+                };
+                logger.info(`Tool ${TOOL_NAME} executed successfully, returning JSON`, logicContext);
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: logicContext,
+                input: validatedArgs,
+                errorCode: BaseErrorCode.INTERNAL_ERROR, // Default error code
+                // Let the logic function throw specific errors like NOT_FOUND
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true });
+};

package/dist/mcp-server/tools/gitBranch/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the git_branch tool.
+ * Exports the registration function and state accessor initialization function.
+ */
+export { registerGitBranchTool, initializeGitBranchStateAccessors } from './registration.js';
+// Export types if needed elsewhere, e.g.:
+// export type { GitBranchInput, GitBranchResult } from './logic.js';

package/dist/mcp-server/tools/gitBranch/logic.js

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import { promisify } from 'util';
+import { exec } from 'child_process';
+import { logger } from '../../../utils/logger.js';
+import { McpError, BaseErrorCode } from '../../../types-global/errors.js';
+import { sanitization } from '../../../utils/sanitization.js';
+const execAsync = promisify(exec);
+// Define the BASE input schema for the git_branch tool using Zod
+export const GitBranchBaseSchema = z.object({
+    path: z.string().min(1).optional().default('.').describe("Path to the local Git repository. If omitted, defaults to the path set by `git_set_working_dir` for the current session, or the server's CWD if no session path is set."),
+    mode: z.enum(['list', 'create', 'delete', 'rename', 'show-current']).describe("The branch operation to perform: 'list', 'create', 'delete', 'rename', 'show-current'."),
+    branchName: z.string().min(1).optional().describe("The name of the branch. Required for 'create', 'delete', 'rename' modes."),
+    newBranchName: z.string().min(1).optional().describe("The new name for the branch. Required for 'rename' mode."),
+    startPoint: z.string().min(1).optional().describe("Optional commit hash, tag, or existing branch name to start the new branch from. Used only in 'create' mode. Defaults to HEAD."),
+    force: z.boolean().default(false).describe("Force the operation. Use -D for delete, -M for rename, -f for create (if branch exists). Use with caution, as forcing operations can lead to data loss."),
+    all: z.boolean().default(false).describe("List both local and remote-tracking branches. Used only in 'list' mode."),
+    remote: z.boolean().default(false).describe("Act on remote-tracking branches. Used with 'list' (-r) or 'delete' (-r)."),
+});
+// Apply refinements and export the FINAL schema for validation within the handler
+export const GitBranchInputSchema = GitBranchBaseSchema.refine(data => !(data.mode === 'create' && !data.branchName), {
+    message: "A 'branchName' is required for 'create' mode.", path: ["branchName"],
+}).refine(data => !(data.mode === 'delete' && !data.branchName), {
+    message: "A 'branchName' is required for 'delete' mode.", path: ["branchName"],
+}).refine(data => !(data.mode === 'rename' && (!data.branchName || !data.newBranchName)), {
+    message: "Both 'branchName' (old name) and 'newBranchName' are required for 'rename' mode.", path: ["branchName", "newBranchName"],
+});
+/**
+ * Executes git branch commands based on the specified mode.
+ *
+ * @param {GitBranchInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitBranchResult>} A promise that resolves with the structured result.
+ * @throws {McpError} Throws an McpError for path resolution/validation failures or unexpected errors.
+ */
+export async function gitBranchLogic(input, context) {
+    const operation = `gitBranchLogic:${input.mode}`;
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve and sanitize the target path
+        const workingDir = context.getWorkingDirectory();
+        targetPath = (input.path && input.path !== '.')
+            ? input.path
+            : workingDir ?? '.';
+        if (targetPath === '.' && !workingDir) {
+            logger.warning("Executing git branch in server's CWD as no path provided and no session WD set.", { ...context, operation });
+            targetPath = process.cwd();
+        }
+        else if (targetPath === '.' && workingDir) {
+            targetPath = workingDir;
+            logger.debug(`Using session working directory: ${targetPath}`, { ...context, operation, sessionId: context.sessionId });
+        }
+        else {
+            logger.debug(`Using provided path: ${targetPath}`, { ...context, operation });
+        }
+        targetPath = sanitization.sanitizePath(targetPath);
+        logger.debug('Sanitized path', { ...context, operation, sanitizedPath: targetPath });
+    }
+    catch (error) {
+        logger.error('Path resolution or sanitization failed', { ...context, operation, error });
+        if (error instanceof McpError)
+            throw error;
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid path: ${error instanceof Error ? error.message : String(error)}`, { context, operation, originalError: error });
+    }
+    try {
+        let command;
+        let result;
+        switch (input.mode) {
+            case 'list':
+                command = `git -C "${targetPath}" branch --list --no-color`; // Start with basic list
+                if (input.all)
+                    command += ' -a'; // Add -a if requested
+                else if (input.remote)
+                    command += ' -r'; // Add -r if requested (exclusive with -a)
+                command += ' --verbose'; // Add verbose for commit info
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: listStdout } = await execAsync(command);
+                const branches = listStdout.trim().split('\n')
+                    .filter(line => line && !line.match(/^\s*->\s*/)) // Filter out HEAD pointer lines if any
+                    .map(line => {
+                    const isCurrent = line.startsWith('* ');
+                    const trimmedLine = line.replace(/^\*?\s+/, ''); // Remove leading '*' and spaces
+                    const parts = trimmedLine.split(/\s+/);
+                    const name = parts[0];
+                    const isRemote = name.startsWith('remotes/');
+                    const commitHash = parts[1] || undefined; // Verbose gives hash
+                    const commitSubject = parts.slice(2).join(' ') || undefined; // Verbose gives subject
+                    return { name, isCurrent, isRemote, commitHash, commitSubject };
+                });
+                const currentBranch = branches.find(b => b.isCurrent)?.name;
+                result = { success: true, mode: 'list', branches, currentBranch };
+                break;
+            case 'create':
+                // branchName is validated by Zod refine
+                command = `git -C "${targetPath}" branch `;
+                if (input.force)
+                    command += '-f ';
+                command += `"${input.branchName}"`; // branchName is guaranteed by refine
+                if (input.startPoint)
+                    command += ` "${input.startPoint}"`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                await execAsync(command);
+                result = { success: true, mode: 'create', branchName: input.branchName, message: `Branch '${input.branchName}' created successfully.` };
+                break;
+            case 'delete':
+                // branchName is validated by Zod refine
+                command = `git -C "${targetPath}" branch `;
+                if (input.remote)
+                    command += '-r ';
+                command += input.force ? '-D ' : '-d ';
+                command += `"${input.branchName}"`; // branchName is guaranteed by refine
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: deleteStdout } = await execAsync(command);
+                result = { success: true, mode: 'delete', branchName: input.branchName, wasRemote: input.remote, message: deleteStdout.trim() || `Branch '${input.branchName}' deleted successfully.` };
+                break;
+            case 'rename':
+                // branchName and newBranchName validated by Zod refine
+                command = `git -C "${targetPath}" branch `;
+                command += input.force ? '-M ' : '-m ';
+                command += `"${input.branchName}" "${input.newBranchName}"`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                await execAsync(command);
+                result = { success: true, mode: 'rename', oldBranchName: input.branchName, newBranchName: input.newBranchName, message: `Branch '${input.branchName}' renamed to '${input.newBranchName}' successfully.` };
+                break;
+            case 'show-current':
+                command = `git -C "${targetPath}" branch --show-current`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                try {
+                    const { stdout: currentStdout } = await execAsync(command);
+                    const currentBranchName = currentStdout.trim();
+                    result = { success: true, mode: 'show-current', currentBranch: currentBranchName || null, message: currentBranchName ? `Current branch is '${currentBranchName}'.` : 'Currently in detached HEAD state.' };
+                }
+                catch (showError) {
+                    // Handle detached HEAD state specifically if command fails
+                    if (showError.stderr?.includes('HEAD detached')) {
+                        result = { success: true, mode: 'show-current', currentBranch: null, message: 'Currently in detached HEAD state.' };
+                    }
+                    else {
+                        throw showError; // Re-throw other errors
+                    }
+                }
+                break;
+            default:
+                // Should not happen due to Zod validation
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid mode: ${input.mode}`, { context, operation });
+        }
+        logger.info(`${operation} executed successfully`, { ...context, operation, path: targetPath });
+        return result;
+    }
+    catch (error) {
+        const errorMessage = error.stderr || error.stdout || error.message || ''; // stdout might contain error messages too
+        logger.error(`Failed to execute git branch command`, { ...context, operation, path: targetPath, error: errorMessage, stderr: error.stderr, stdout: error.stdout });
+        // Specific error handling
+        if (errorMessage.toLowerCase().includes('not a git repository')) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Path is not a Git repository: ${targetPath}`, { context, operation, originalError: error });
+        }
+        if (input.mode === 'create' && errorMessage.includes('already exists')) {
+            return { success: false, mode: 'create', message: `Failed to create branch: Branch '${input.branchName}' already exists. Use force=true to overwrite.`, error: errorMessage };
+        }
+        if (input.mode === 'delete' && errorMessage.includes('not found')) {
+            return { success: false, mode: 'delete', message: `Failed to delete branch: Branch '${input.branchName}' not found.`, error: errorMessage };
+        }
+        if (input.mode === 'delete' && errorMessage.includes('not fully merged')) {
+            return { success: false, mode: 'delete', message: `Failed to delete branch: Branch '${input.branchName}' is not fully merged. Use force=true to delete.`, error: errorMessage };
+        }
+        if (input.mode === 'rename' && errorMessage.includes('already exists')) {
+            return { success: false, mode: 'rename', message: `Failed to rename branch: Branch '${input.newBranchName}' already exists. Use force=true to overwrite.`, error: errorMessage };
+        }
+        if (input.mode === 'rename' && errorMessage.includes('not found')) {
+            return { success: false, mode: 'rename', message: `Failed to rename branch: Branch '${input.branchName}' not found.`, error: errorMessage };
+        }
+        // Return structured failure for other git errors
+        return {
+            success: false,
+            mode: input.mode,
+            message: `Git branch ${input.mode} failed for path: ${targetPath}.`,
+            error: errorMessage
+        };
+    }
+}

package/dist/mcp-server/tools/gitBranch/registration.js

@@ -0,0 +1,72 @@
+import { logger } from '../../../utils/logger.js';
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+import { gitBranchLogic, GitBranchBaseSchema } from './logic.js';
+import { BaseErrorCode } from '../../../types-global/errors.js';
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the git_branch tool registration.
+ * @param getWdFn - Function to get the working directory for a session.
+ * @param getSidFn - Function to get the session ID from context.
+ */
+export function initializeGitBranchStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_branch tool registration.');
+}
+const TOOL_NAME = 'git_branch';
+const TOOL_DESCRIPTION = 'Manages Git branches. Supports listing (local, remote, all), creating, deleting (with force), renaming (with force), and showing the current branch. Returns results as a JSON object.';
+/**
+ * Registers the git_branch tool with the MCP server.
+ *
+ * @param {McpServer} server - The McpServer instance to register the tool with.
+ * @returns {Promise<void>}
+ * @throws {Error} If registration fails or state accessors are not initialized.
+ */
+export const registerGitBranchTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_branch must be initialized before registration.');
+    }
+    const operation = 'registerGitBranchTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        // Register using the BASE schema shape
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitBranchBaseSchema.shape, 
+        // SDK validates against the full GitBranchInputSchema before calling this handler
+        async (validatedArgs, callContext) => {
+            const toolInput = validatedArgs; // Cast for use
+            const toolOperation = `tool:${TOOL_NAME}:${toolInput.mode}`;
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            const sessionId = _getSessionId(requestContext);
+            const getWorkingDirectoryForSession = () => _getWorkingDirectory(sessionId);
+            const logicContext = {
+                ...requestContext,
+                sessionId: sessionId,
+                getWorkingDirectory: getWorkingDirectoryForSession,
+            };
+            logger.info(`Executing tool: ${TOOL_NAME} (mode: ${toolInput.mode})`, logicContext);
+            return await ErrorHandler.tryCatch(async () => {
+                const branchResult = await gitBranchLogic(toolInput, logicContext);
+                const resultContent = {
+                    type: 'text',
+                    text: JSON.stringify(branchResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json',
+                };
+                if (branchResult.success) {
+                    logger.info(`Tool ${TOOL_NAME} (mode: ${toolInput.mode}) executed successfully, returning JSON`, logicContext);
+                }
+                else {
+                    logger.warning(`Tool ${TOOL_NAME} (mode: ${toolInput.mode}) failed: ${branchResult.message}`, { ...logicContext, errorDetails: branchResult.error });
+                }
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: logicContext,
+                input: validatedArgs,
+                errorCode: BaseErrorCode.INTERNAL_ERROR,
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true });
+};

package/dist/mcp-server/tools/gitCheckout/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the gitCheckout tool.
+ */
+export { registerGitCheckoutTool, initializeGitCheckoutStateAccessors } from './registration.js';
+// Export types if needed elsewhere, e.g.:
+// export type { GitCheckoutInput, GitCheckoutResult } from './logic.js';

package/dist/mcp-server/tools/gitCheckout/logic.js

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { promisify } from 'util';
+import { exec } from 'child_process';
+import { logger } from '../../../utils/logger.js';
+import { McpError, BaseErrorCode } from '../../../types-global/errors.js';
+import { sanitization } from '../../../utils/sanitization.js';
+const execAsync = promisify(exec);
+// Define the input schema for the git_checkout tool using Zod
+export const GitCheckoutInputSchema = z.object({
+    path: z.string().min(1).optional().default('.').describe("Path to the Git repository. Defaults to the session's working directory if set."),
+    branchOrPath: z.string().min(1).describe("The branch name, commit hash, tag, or file path(s) to checkout."),
+    newBranch: z.string().optional().describe("Create a new branch named <new_branch> and start it at <branchOrPath>."),
+    force: z.boolean().optional().default(false).describe("Force checkout even if there are uncommitted changes (use with caution, discards local changes)."),
+    // Add other relevant git checkout options as needed (e.g., --track, -b for new branch shorthand)
+});
+/**
+ * Executes the 'git checkout' command and returns structured JSON output.
+ * Handles switching branches, creating new branches, and restoring files.
+ *
+ * @param {GitCheckoutInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitCheckoutResult>} A promise that resolves with the structured checkout result.
+ * @throws {McpError} Throws an McpError if path resolution, validation, or the git command fails unexpectedly.
+ */
+export async function checkoutGit(input, context) {
+    const operation = 'checkoutGit';
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve and sanitize the target path
+        if (input.path && input.path !== '.') {
+            targetPath = input.path;
+        }
+        else {
+            const workingDir = context.getWorkingDirectory();
+            if (!workingDir) {
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, "No path provided and no working directory set for the session.", { context, operation });
+            }
+            targetPath = workingDir;
+        }
+        targetPath = sanitization.sanitizePath(targetPath);
+        logger.debug('Sanitized path', { ...context, operation, sanitizedPath: targetPath });
+    }
+    catch (error) {
+        logger.error('Path resolution or sanitization failed', { ...context, operation, error });
+        if (error instanceof McpError)
+            throw error;
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid path: ${error instanceof Error ? error.message : String(error)}`, { context, operation, originalError: error });
+    }
+    // Basic sanitization for branch/path argument
+    const safeBranchOrPath = input.branchOrPath.replace(/[`$&;*()|<>]/g, ''); // Remove potentially dangerous characters
+    try {
+        // Construct the git checkout command
+        let command = `git -C "${targetPath}" checkout`;
+        if (input.force) {
+            command += ' --force';
+        }
+        if (input.newBranch) {
+            const safeNewBranch = input.newBranch.replace(/[^a-zA-Z0-9_.\-/]/g, ''); // Sanitize new branch name
+            command += ` -b ${safeNewBranch}`;
+        }
+        command += ` ${safeBranchOrPath}`; // Add the target branch/path
+        logger.debug(`Executing command: ${command}`, { ...context, operation });
+        // Execute command. Checkout often uses stderr for status messages.
+        const { stdout, stderr } = await execAsync(command);
+        logger.info(`Git checkout stdout: ${stdout}`, { ...context, operation });
+        logger.info(`Git checkout stderr: ${stderr}`, { ...context, operation }); // Log stderr as info
+        // Analyze stderr primarily, fallback to stdout
+        let message = stderr.trim() || stdout.trim();
+        let success = true;
+        let previousBranch = undefined;
+        let currentBranch = undefined;
+        let newBranchCreated = !!input.newBranch;
+        let filesRestored = undefined;
+        // Extract previous branch if available
+        const prevBranchMatch = stderr.match(/Switched to.*? from ['"]?(.*?)['"]?/);
+        if (prevBranchMatch) {
+            previousBranch = prevBranchMatch[1];
+        }
+        // Extract current branch/state
+        if (stderr.includes('Switched to branch')) {
+            const currentBranchMatch = stderr.match(/Switched to branch ['"]?(.*?)['"]?/);
+            if (currentBranchMatch)
+                currentBranch = currentBranchMatch[1];
+            message = `Switched to branch '${currentBranch || input.branchOrPath}'.`;
+        }
+        else if (stderr.includes('Switched to a new branch')) {
+            const currentBranchMatch = stderr.match(/Switched to a new branch ['"]?(.*?)['"]?/);
+            if (currentBranchMatch)
+                currentBranch = currentBranchMatch[1];
+            message = `Switched to new branch '${currentBranch || input.newBranch}'.`;
+            newBranchCreated = true; // Confirm creation
+        }
+        else if (stderr.includes('Already on')) {
+            const currentBranchMatch = stderr.match(/Already on ['"]?(.*?)['"]?/);
+            if (currentBranchMatch)
+                currentBranch = currentBranchMatch[1];
+            message = `Already on '${currentBranch || input.branchOrPath}'.`;
+        }
+        else if (stderr.includes('Updated N path') || stdout.includes('Updated N path')) { // Checking out files
+            message = `Restored path(s): ${input.branchOrPath}`;
+            // Potentially list the files if input.branchOrPath was specific enough
+            // Assume input.branchOrPath contains file paths separated by newlines
+            filesRestored = input.branchOrPath.split('\n').filter(p => p.trim().length > 0); // Split by newline and filter out empty entries
+            // Try to get current branch after file checkout
+            try {
+                const statusResult = await execAsync(`git -C "${targetPath}" branch --show-current`);
+                currentBranch = statusResult.stdout.trim();
+            }
+            catch (statusError) {
+                logger.warning('Could not determine current branch after file checkout', { ...context, operation, statusError });
+            }
+        }
+        else if (stderr.includes('Previous HEAD position was') && stderr.includes('HEAD is now at')) { // Detached HEAD
+            message = `Checked out commit ${input.branchOrPath} (Detached HEAD state).`;
+            currentBranch = 'Detached HEAD'; // Indicate detached state
+        }
+        else if (stderr.includes('Note: switching to')) { // Another detached HEAD message variant
+            message = `Checked out ${input.branchOrPath} (Detached HEAD state).`;
+            currentBranch = 'Detached HEAD';
+        }
+        else if (message.includes('fatal:')) {
+            success = false;
+            message = `Checkout failed: ${message}`;
+            logger.error(`Git checkout command indicated failure: ${message}`, { ...context, operation, stdout, stderr });
+        }
+        else if (!message && !stdout && !stderr) {
+            message = 'Checkout command executed, but no output received.';
+            logger.warning(message, { ...context, operation });
+            // Attempt to get current branch as confirmation
+            try {
+                const statusResult = await execAsync(`git -C "${targetPath}" branch --show-current`);
+                currentBranch = statusResult.stdout.trim();
+                message += ` Current branch is '${currentBranch}'.`;
+            }
+            catch (statusError) {
+                logger.warning('Could not determine current branch after silent checkout', { ...context, operation, statusError });
+            }
+        }
+        logger.info(`${operation} completed`, { ...context, operation, path: targetPath, success, message });
+        return { success, message, previousBranch, currentBranch, newBranchCreated, filesRestored };
+    }
+    catch (error) {
+        logger.error(`Failed to execute git checkout command`, { ...context, operation, path: targetPath, error: error.message, stderr: error.stderr, stdout: error.stdout });
+        const errorMessage = error.stderr || error.stdout || error.message || '';
+        // Handle specific error cases
+        if (errorMessage.toLowerCase().includes('not a git repository')) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Path is not a Git repository: ${targetPath}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.match(/pathspec '.*?' did not match any file\(s\) known to git/)) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Branch or pathspec not found: ${input.branchOrPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.includes('already exists')) { // e.g., trying -b with existing branch name
+            throw new McpError(BaseErrorCode.CONFLICT, `Cannot create new branch '${input.newBranch}': it already exists. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.includes('Your local changes to the following files would be overwritten by checkout')) {
+            throw new McpError(BaseErrorCode.CONFLICT, `Checkout failed due to uncommitted local changes that would be overwritten. Please commit or stash them first, or use --force. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.includes('invalid reference')) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid branch name or reference: ${input.branchOrPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        // Generic internal error for other failures
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to checkout for path: ${targetPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+    }
+}