configuration

Configuration Management Skill

Overview

This skill provides guidance for implementing safe configuration file management including backup systems, atomic updates, and recovery mechanisms. For US-4 (MCP Uninstaller), this skill covers:

• Creating timestamped configuration backups
• Atomic JSON file updates
• Configuration validation
• Backup restoration and cleanup

Core Capabilities

• Atomic File Operations: Write-then-rename pattern for safe file updates
• Backup Management: Create, restore, and clean up timestamped backups
• JSON Manipulation: Safe parsing, modification, and validation of JSON config files
• Error Recovery: Automatic rollback on failures
• Metadata Tracking: Include metadata in backups for audit trail
• Cleanup Policies: Implement retention policies (e.g., keep last 10 backups)

Input Requirements

Required:

• Configuration file path
• Operation type (backup, update, restore)
• Backup directory path

Optional:

• Retention policy (number of backups to keep)
• Validation schema
• Metadata to include in backup

Output Format

Returns:

• Operation result (success/failure)
• Backup file path (for backup operations)
• Validation results
• Error messages if applicable

Dependencies

• fs-extra: Enhanced file system operations
• JSON schema validator (optional): For config validation
• TypeScript 5.x: For type-safe config handling

Workflow

Step 1: Define Configuration Interfaces

Create TypeScript interfaces for config structure:

// src/interfaces/config.interface.ts
export interface ClaudeConfig {
  mcpServers?: Record<string, MCPServerConfig>;
  [key: string]: any;
}

export interface MCPServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

export interface BackupMetadata {
  timestamp: string;
  originalPath: string;
  reason: string;
  mcpName?: string;
}

Step 2: Implement Backup Service

Create backup with metadata:

// src/services/config-backup.ts
import * as fs from 'fs-extra';
import * as path from 'path';

export class ConfigBackup {
  private backupDir: string;
  private maxBackups: number;

  constructor(backupDir: string = '.claude/backups', maxBackups: number = 10) {
    this.backupDir = backupDir;
    this.maxBackups = maxBackups;
  }

  async createBackup(configPath: string, reason: string, mcpName?: string): Promise<string> {
    // Ensure backup directory exists
    await fs.ensureDir(this.backupDir);

    // Generate timestamp
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    const backupFileName = `config-backup-${timestamp}.json`;
    const backupPath = path.join(this.backupDir, backupFileName);

    // Read original config
    const config = await fs.readJson(configPath);

    // Create backup with metadata
    const backup = {
      metadata: {
        timestamp: new Date().toISOString(),
        originalPath: configPath,
        reason,
        mcpName
      },
      config
    };

    // Write backup atomically
    await this.atomicWrite(backupPath, JSON.stringify(backup, null, 2));

    // Verify backup
    if (!await fs.pathExists(backupPath)) {
      throw new Error('Backup verification failed');
    }

    // Clean up old backups
    await this.cleanupOldBackups();

    return backupPath;
  }

  private async atomicWrite(filePath: string, content: string): Promise<void> {
    const tempPath = `${filePath}.tmp`;
    await fs.writeFile(tempPath, content, 'utf-8');
    await fs.rename(tempPath, filePath);
  }

  private async cleanupOldBackups(): Promise<void> {
    const files = await fs.readdir(this.backupDir);
    const backupFiles = files
      .filter(f => f.startsWith('config-backup-'))
      .sort()
      .reverse();

    // Keep only the most recent maxBackups
    const filesToDelete = backupFiles.slice(this.maxBackups);
    for (const file of filesToDelete) {
      await fs.remove(path.join(this.backupDir, file));
    }
  }

  async restore(backupPath: string, targetPath: string): Promise<void> {
    const backup = await fs.readJson(backupPath);

    if (!backup.config) {
      throw new Error('Invalid backup file: missing config data');
    }

    // Write config atomically
    await this.atomicWrite(targetPath, JSON.stringify(backup.config, null, 2));
  }
}