@ebowwa/claude-code-config-mcp 1.0.0

package/src/utils/errors.ts

@@ -0,0 +1,210 @@
+// ============================================================================
+// Error Handling - Categorization, retry logic, and user-friendly messages
+// ============================================================================
+
+export enum ErrorCategory {
+  TRANSIENT = 'TRANSIENT',
+  PERMISSION = 'PERMISSION',
+  VALIDATION = 'VALIDATION',
+  SYSTEM = 'SYSTEM',
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * Categorize an error for appropriate handling
+ */
+export function categorizeError(error: Error | unknown): ErrorCategory {
+  if (!(error instanceof Error)) {
+    return ErrorCategory.UNKNOWN;
+  }
+
+  const message = error.message.toLowerCase();
+
+  // Permission errors
+  if (
+    message.includes('eacces') ||
+    message.includes('eperm') ||
+    message.includes('permission denied')
+  ) {
+    return ErrorCategory.PERMISSION;
+  }
+
+  // File not found (validation)
+  if (message.includes('enoent') || message.includes('no such file')) {
+    return ErrorCategory.VALIDATION;
+  }
+
+  // Transient errors (retryable)
+  if (
+    message.includes('eagain') ||
+    message.includes('etimedout') ||
+    message.includes('econnreset') ||
+    message.includes('econnrefused') ||
+    message.includes('timeout') ||
+    message.includes('temporary failure')
+  ) {
+    return ErrorCategory.TRANSIENT;
+  }
+
+  // System errors
+  if (
+    message.includes('enospc') ||
+    message.includes('disk full') ||
+    message.includes('eisdir') ||
+    message.includes('enotdir')
+  ) {
+    return ErrorCategory.SYSTEM;
+  }
+
+  return ErrorCategory.UNKNOWN;
+}
+
+/**
+ * Get user-friendly action message for an error
+ */
+export function getUserAction(category: ErrorCategory): string | null {
+  switch (category) {
+    case ErrorCategory.PERMISSION:
+      return 'Check file permissions and ensure Claude Code has access to the config directory';
+    case ErrorCategory.VALIDATION:
+      return 'Verify the file path and try again';
+    case ErrorCategory.SYSTEM:
+      return 'Check system resources and Claude Code configuration';
+    case ErrorCategory.TRANSIENT:
+      return 'The operation failed temporarily. Please try again';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Check if an error is retryable
+ */
+export function isRetryable(error: Error | unknown): boolean {
+  return categorizeError(error) === ErrorCategory.TRANSIENT;
+}
+
+/**
+ * Retry configuration
+ */
+export interface RetryOptions {
+  maxAttempts: number;
+  baseDelay: number;
+  maxDelay: number;
+  jitter: boolean;
+}
+
+const DEFAULT_RETRY_OPTIONS: RetryOptions = {
+  maxAttempts: 3,
+  baseDelay: 1000,
+  maxDelay: 10000,
+  jitter: true,
+};
+
+/**
+ * Retry an operation with exponential backoff
+ */
+export async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions = DEFAULT_RETRY_OPTIONS
+): Promise<T> {
+  let lastError: Error;
+
+  for (let attempt = 0; attempt < options.maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error as Error;
+
+      // Don't retry if not retryable
+      if (!isRetryable(error)) {
+        throw error;
+      }
+
+      // Calculate delay with exponential backoff
+      const delay = Math.min(
+        options.baseDelay * Math.pow(2, attempt),
+        options.maxDelay
+      );
+
+      // Add jitter to prevent thundering herd
+      const finalDelay = options.jitter
+        ? delay + Math.random() * 1000
+        : delay;
+
+      // Wait before retry
+      await new Promise(resolve => setTimeout(resolve, finalDelay));
+    }
+  }
+
+  throw lastError!;
+}
+
+/**
+ * Create a standardized error response
+ */
+export interface MCPError {
+  success: false;
+  error: {
+    category: ErrorCategory;
+    message: string;
+    retryable: boolean;
+    userAction: string | null;
+  };
+}
+
+export function createMCPError(error: Error | unknown): MCPError {
+  const category = categorizeError(error);
+  const message = error instanceof Error ? error.message : 'Unknown error';
+
+  return {
+    success: false,
+    error: {
+      category,
+      message,
+      retryable: category === ErrorCategory.TRANSIENT,
+      userAction: getUserAction(category),
+    },
+  };
+}
+
+/**
+ * Error codes for different scenarios
+ */
+export enum ErrorCode {
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  INVALID_JSON = 'INVALID_JSON',
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+  PATH_TRAVERSAL = 'PATH_TRAVERSAL',
+  DISK_FULL = 'DISK_FULL',
+  LOCKED = 'LOCKED',
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * Get error code from error
+ */
+export function getErrorCode(error: Error | unknown): ErrorCode {
+  const category = categorizeError(error);
+
+  switch (category) {
+    case ErrorCategory.VALIDATION:
+      if (error instanceof Error && error.message.includes('JSON')) {
+        return ErrorCode.INVALID_JSON;
+      }
+      return ErrorCode.FILE_NOT_FOUND;
+    case ErrorCategory.PERMISSION:
+      return ErrorCode.PERMISSION_DENIED;
+    case ErrorCategory.SYSTEM:
+      if (error instanceof Error && error.message.includes('enospc')) {
+        return ErrorCode.DISK_FULL;
+      }
+      if (error instanceof Error && error.message.includes('etxtbsy')) {
+        return ErrorCode.LOCKED;
+      }
+      return ErrorCode.UNKNOWN;
+    default:
+      return ErrorCode.UNKNOWN;
+  }
+}

package/src/utils/file.js

@@ -0,0 +1,251 @@
+"use strict";
+// ============================================================================
+// Atomic File Operations - Safe config file writes with backup support
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomicWrite = atomicWrite;
+exports.safeReadFile = safeReadFile;
+exports.isFileWritable = isFileWritable;
+exports.normalizeLineEndings = normalizeLineEndings;
+exports.stripBOM = stripBOM;
+exports.formatJSON = formatJSON;
+exports.safeJSONParse = safeJSONParse;
+var promises_1 = require("node:fs/promises");
+var node_fs_1 = require("node:fs");
+var node_path_1 = require("node:path");
+var node_os_1 = require("node:os");
+var node_crypto_1 = require("node:crypto");
+/**
+ * Atomic write implementation
+ * Writes to a temporary file, then renames over the target
+ * This is safe against crashes and concurrent access
+ */
+function atomicWrite(filePath_1, content_1) {
+    return __awaiter(this, arguments, void 0, function (filePath, content, options) {
+        var _a, createBackup, backupDir, _b, encoding, parentDir, tempDir, tempFileName, tempFilePath, error_1, _c, _d;
+        if (options === void 0) { options = {}; }
+        return __generator(this, function (_e) {
+            switch (_e.label) {
+                case 0:
+                    _a = options.createBackup, createBackup = _a === void 0 ? true : _a, backupDir = options.backupDir, _b = options.encoding, encoding = _b === void 0 ? 'utf8' : _b;
+                    parentDir = (0, node_path_1.dirname)(filePath);
+                    return [4 /*yield*/, (0, promises_1.mkdir)(parentDir, { recursive: true })];
+                case 1:
+                    _e.sent();
+                    if (!(createBackup && (0, node_fs_1.existsSync)(filePath))) return [3 /*break*/, 3];
+                    return [4 /*yield*/, createBackupFile(filePath, backupDir)];
+                case 2:
+                    _e.sent();
+                    _e.label = 3;
+                case 3: return [4 /*yield*/, (0, promises_1.mkdtemp)((0, node_path_1.join)(getTempDir(), 'mcp-atomic-'))];
+                case 4:
+                    tempDir = _e.sent();
+                    tempFileName = "".concat((0, node_crypto_1.randomBytes)(16).toString('hex'), ".tmp");
+                    tempFilePath = (0, node_path_1.join)(tempDir, tempFileName);
+                    _e.label = 5;
+                case 5:
+                    _e.trys.push([5, 8, 13, 17]);
+                    // Write to temp file
+                    return [4 /*yield*/, (0, promises_1.writeFile)(tempFilePath, content, { encoding: encoding, mode: 420 })];
+                case 6:
+                    // Write to temp file
+                    _e.sent();
+                    // Atomic rename (overwrites target if exists)
+                    return [4 /*yield*/, (0, promises_1.rename)(tempFilePath, filePath)];
+                case 7:
+                    // Atomic rename (overwrites target if exists)
+                    _e.sent();
+                    return [3 /*break*/, 17];
+                case 8:
+                    error_1 = _e.sent();
+                    _e.label = 9;
+                case 9:
+                    _e.trys.push([9, 11, , 12]);
+                    return [4 /*yield*/, (0, promises_1.unlink)(tempFilePath)];
+                case 10:
+                    _e.sent();
+                    return [3 /*break*/, 12];
+                case 11:
+                    _c = _e.sent();
+                    return [3 /*break*/, 12];
+                case 12: throw error_1;
+                case 13:
+                    _e.trys.push([13, 15, , 16]);
+                    return [4 /*yield*/, (0, promises_1.unlink)(tempDir).catch(function () { })];
+                case 14:
+                    _e.sent();
+                    return [3 /*break*/, 16];
+                case 15:
+                    _d = _e.sent();
+                    return [3 /*break*/, 16];
+                case 16: return [7 /*endfinally*/];
+                case 17: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Create a backup of a file
+ */
+function createBackupFile(filePath, backupDir) {
+    return __awaiter(this, void 0, void 0, function () {
+        var timestamp, backupFileName, backupPath, backupDirPath, content;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                    backupFileName = "".concat(basename(filePath), ".backup.").concat(timestamp);
+                    backupPath = backupDir
+                        ? (0, node_path_1.join)(backupDir, backupFileName)
+                        : "".concat(filePath, ".backup");
+                    backupDirPath = (0, node_path_1.dirname)(backupPath);
+                    return [4 /*yield*/, (0, promises_1.mkdir)(backupDirPath, { recursive: true })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, (0, promises_1.readFile)(filePath)];
+                case 2:
+                    content = _a.sent();
+                    return [4 /*yield*/, (0, promises_1.writeFile)(backupPath, content)];
+                case 3:
+                    _a.sent();
+                    return [2 /*return*/, backupPath];
+            }
+        });
+    });
+}
+/**
+ * Get temp directory
+ */
+function getTempDir() {
+    return (0, node_os_1.tmpdir)();
+}
+/**
+ * Get file basename without extension
+ */
+function basename(filePath) {
+    return filePath.split('/').pop() || filePath;
+}
+/**
+ * Safe file read with encoding detection
+ */
+function safeReadFile(filePath_1) {
+    return __awaiter(this, arguments, void 0, function (filePath, encoding) {
+        var content, error_2;
+        if (encoding === void 0) { encoding = 'utf8'; }
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _a.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, (0, promises_1.readFile)(filePath, { encoding: encoding })];
+                case 1:
+                    content = _a.sent();
+                    // Remove BOM if present
+                    if (content.charCodeAt(0) === 0xFEFF) {
+                        return [2 /*return*/, content.slice(1)];
+                    }
+                    return [2 /*return*/, content];
+                case 2:
+                    error_2 = _a.sent();
+                    throw new Error("Failed to read file ".concat(filePath, ": ").concat(error_2.message));
+                case 3: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Check if file is writable
+ */
+function isFileWritable(filePath) {
+    return __awaiter(this, void 0, void 0, function () {
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    _b.trys.push([0, 3, , 4]);
+                    return [4 /*yield*/, (0, promises_1.writeFile)(filePath, '', { flag: node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_CREAT })];
+                case 1:
+                    _b.sent();
+                    return [4 /*yield*/, (0, promises_1.unlink)(filePath)];
+                case 2:
+                    _b.sent();
+                    return [2 /*return*/, true];
+                case 3:
+                    _a = _b.sent();
+                    return [2 /*return*/, false];
+                case 4: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Normalize line endings to LF
+ */
+function normalizeLineEndings(content) {
+    return content.replace(/\r\n/g, '\n');
+}
+/**
+ * Detect and strip BOM
+ */
+function stripBOM(content) {
+    if (content.charCodeAt(0) === 0xFEFF) {
+        return content.slice(1);
+    }
+    return content;
+}
+/**
+ * Format JSON with proper indentation
+ */
+function formatJSON(obj, indent) {
+    if (indent === void 0) { indent = 2; }
+    return JSON.stringify(obj, null, indent) + '\n';
+}
+/**
+ * Parse JSON with error reporting
+ */
+function safeJSONParse(content, filePath) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        var message = error.message;
+        var match = message.match(/position (\d+)/);
+        var position = match ? match[1] : 'unknown';
+        throw new Error("Invalid JSON in ".concat(filePath, " at position ").concat(position, ": ").concat(message));
+    }
+}

package/src/utils/file.ts

@@ -0,0 +1,174 @@
+// ============================================================================
+// Atomic File Operations - Safe config file writes with backup support
+// ============================================================================
+
+import { writeFile, rename, unlink, readFile, mkdir, mkdtemp } from 'node:fs/promises';
+import { existsSync, constants } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import type { AtomicWriteOptions } from '../types.js';
+
+/**
+ * Atomic write implementation
+ * Writes to a temporary file, then renames over the target
+ * This is safe against crashes and concurrent access
+ */
+export async function atomicWrite(
+  filePath: string,
+  content: string,
+  options: AtomicWriteOptions = {}
+): Promise<void> {
+  const {
+    createBackup = true,
+    backupDir,
+    encoding = 'utf8',
+  } = options;
+
+  // Create parent directory if it doesn't exist
+  const parentDir = dirname(filePath);
+  await mkdir(parentDir, { recursive: true });
+
+  // Create backup if requested and file exists
+  if (createBackup && existsSync(filePath)) {
+    await createBackupFile(filePath, backupDir);
+  }
+
+  // Create temp file in OS temp directory (same filesystem for atomic rename)
+  const tempDir = await mkdtemp(join(getTempDir(), 'mcp-atomic-'));
+  const tempFileName = `${randomBytes(16).toString('hex')}.tmp`;
+  const tempFilePath = join(tempDir, tempFileName);
+
+  try {
+    // Write to temp file
+    await writeFile(tempFilePath, content, { encoding, mode: 0o644 });
+
+    // Atomic rename (overwrites target if exists)
+    await rename(tempFilePath, filePath);
+  } catch (error) {
+    // Clean up temp file if rename failed
+    try {
+      await unlink(tempFilePath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw error;
+  } finally {
+    // Clean up temp directory
+    try {
+      await unlink(tempDir).catch(() => {});
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Create a backup of a file
+ */
+async function createBackupFile(filePath: string, backupDir?: string): Promise<string> {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupFileName = `${basename(filePath)}.backup.${timestamp}`;
+  const backupPath = backupDir
+    ? join(backupDir, backupFileName)
+    : `${filePath}.backup`;
+
+  // Ensure backup directory exists
+  const backupDirPath = dirname(backupPath);
+  await mkdir(backupDirPath, { recursive: true });
+
+  // Copy file to backup location
+  const content = await readFile(filePath);
+  await writeFile(backupPath, content);
+
+  return backupPath;
+}
+
+/**
+ * Get temp directory
+ */
+function getTempDir(): string {
+  return tmpdir();
+}
+
+/**
+ * Get file basename without extension
+ */
+function basename(filePath: string): string {
+  return filePath.split('/').pop() || filePath;
+}
+
+/**
+ * Safe file read with encoding detection
+ */
+export async function safeReadFile(
+  filePath: string,
+  encoding: BufferEncoding = 'utf8'
+): Promise<string> {
+  try {
+    const content = await readFile(filePath, { encoding });
+
+    // Remove BOM if present
+    if (content.charCodeAt(0) === 0xFEFF) {
+      return content.slice(1);
+    }
+
+    return content;
+  } catch (error) {
+    throw new Error(`Failed to read file ${filePath}: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Check if file is writable
+ */
+export async function isFileWritable(filePath: string): Promise<boolean> {
+  try {
+    await writeFile(filePath, '', { flag: constants.O_WRONLY | constants.O_CREAT });
+    await unlink(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalize line endings to LF
+ */
+export function normalizeLineEndings(content: string): string {
+  return content.replace(/\r\n/g, '\n');
+}
+
+/**
+ * Detect and strip BOM
+ */
+export function stripBOM(content: string): string {
+  if (content.charCodeAt(0) === 0xFEFF) {
+    return content.slice(1);
+  }
+  return content;
+}
+
+/**
+ * Format JSON with proper indentation
+ */
+export function formatJSON(obj: unknown, indent: number = 2): string {
+  return JSON.stringify(obj, null, indent) + '\n';
+}
+
+/**
+ * Parse JSON with error reporting
+ */
+export function safeJSONParse<T>(content: string, filePath: string): T {
+  try {
+    return JSON.parse(content) as T;
+  } catch (error) {
+    const message = (error as Error).message;
+    const match = message.match(/position (\d+)/);
+    const position = match ? match[1] : 'unknown';
+
+    throw new Error(
+      `Invalid JSON in ${filePath} at position ${position}: ${message}`
+    );
+  }
+}