write_files_atomic

Instructions

Implementation Reference

• src/handlers/file-handlers.js:15-96 (handler)

  WriteFilesAtomicHandler class - the main handler that executes atomic multi-file writes with backup. Accepts file_operations array (each with path, content, operation) and optional create_backup flag. Creates backups before writing, executes operations (write/append/modify), and supports rollback on failure.

  class WriteFilesAtomicHandler extends BaseHandler {
    async execute(args) {
      const { file_operations, create_backup = true } = args;
  
      if (!file_operations || file_operations.length === 0) {
        throw new Error('file_operations is required');
      }
  
      const results = [];
      const backups = [];
  
      try {
        // Create backups first if requested
        if (create_backup) {
          for (const op of file_operations) {
            try {
              const exists = await fs.access(op.path).then(() => true).catch(() => false);
              if (exists) {
                const content = await fs.readFile(op.path, 'utf8');
                const backupPath = `${op.path}.backup.${Date.now()}`;
                await fs.writeFile(backupPath, content);
                backups.push({ original: op.path, backup: backupPath });
              }
            } catch (e) {
              // File doesn't exist, no backup needed
            }
          }
        }
  
        // Execute all operations
        for (const op of file_operations) {
          const operation = op.operation || 'write';
          const dirPath = path.dirname(op.path);
  
          // Ensure directory exists
          await fs.mkdir(dirPath, { recursive: true });
  
          switch (operation) {
            case 'write':
              await fs.writeFile(op.path, op.content, 'utf8');
              break;
            case 'append':
              await fs.appendFile(op.path, op.content, 'utf8');
              break;
            case 'modify':
              // For modify, content should be the full new content
              await fs.writeFile(op.path, op.content, 'utf8');
              break;
          }
  
          results.push({
            path: op.path,
            operation,
            success: true,
            size: op.content.length
          });
        }
  
        return this.buildSuccessResponse({
          files_written: results.length,
          results,
          backups_created: backups.length,
          backups
        });
  
      } catch (error) {
        // Rollback on failure
        if (create_backup) {
          for (const backup of backups) {
            try {
              const backupContent = await fs.readFile(backup.backup, 'utf8');
              await fs.writeFile(backup.original, backupContent);
              await fs.unlink(backup.backup);
            } catch (e) {
              console.error(`Rollback failed for ${backup.original}: ${e.message}`);
            }
          }
        }
        throw error;
      }
    }
  }

• src/tools/tool-definitions.js:40-66 (schema)

  Tool definition for 'write_files_atomic' including JSON Schema for input validation: file_operations array (items with path, content, operation enum) and create_backup boolean.

  {
    name: 'write_files_atomic',
    description: 'Write multiple files atomically with backup - Enterprise-grade file modification with safety mechanisms',
    handler: 'handleWriteFilesAtomic',
    schema: {
      type: 'object',
      properties: {
        file_operations: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              path: { type: 'string' },
              content: { type: 'string' },
              operation: {
                type: 'string',
                enum: ['write', 'append', 'modify'],
                default: 'write'
              }
            },
            required: ['path', 'content']
          }
        },
        create_backup: { type: 'boolean', default: true }
      },
      required: ['file_operations']
    }

• src/handlers/index.js:40-44 (registration)

  Handler registration mapping 'handleWriteFilesAtomic' string to the WriteFilesAtomicHandler class in the HANDLER_REGISTRY.

  const HANDLER_REGISTRY = {
    // Original handlers
    'handleReview': ReviewHandler,
    'handleAsk': AskHandler,
    'handleWriteFilesAtomic': WriteFilesAtomicHandler,

• src/handlers/index.js:60-65 (registration)

  Export of WriteFilesAtomicHandler class from the handler index module.

    'handleBatchModify': BatchModifyHandler,
    'handleRefactor': RefactorHandler,
  
    // SAB v2.0: Dual Iterate (Internal generate->review->fix loop)
    'handleDualIterate': DualIterateHandler
  };

• src/config/role-templates.js:240-244 (helper)

  Suggested tool 'write_files_atomic' in role templates for writing test files and documentation.

  Use appropriate testing frameworks and follow testing best practices.`,
      suggested_tools: [
        'analyze_file',   // Analyze code to test
        'write_files_atomic', // Write test files
        'ask'             // Test strategy analysis