​

Rollback System

​

Overview

• Snapshot creation - Capturing current file state before restoration
• Rollback triggers - Automatic reversion when errors occur
• Snapshot management - Maintaining a history of up to 10 snapshots
• Cross-platform support - Works on Windows, macOS, and Linux

​

How Snapshots Work

​

Snapshot Structure

interface RollbackSnapshot {
  id: string;                    // Unique identifier
  timestamp: string;             // ISO 8601 timestamp
  createdAt: Date;               // Creation date
  files: RollbackFile[];         // Array of captured files
  cwd: string;                   // Working directory
}

​

File Information Captured

• File existence - Whether the file existed at snapshot time
• File content - Full content (if file is ≤1MB)
• File permissions - Unix-style permissions (on Linux/macOS)
• File stats - Size, modification time, and other metadata

​

Creating Snapshots

​

Automatic Pre-Restore Snapshots

env-twin restore --create-rollback

• includeContent: true - Stores full file content for reliable restoration
• includePermissions: true - Preserves Unix file permissions
• maxSize: 1048576 - Maximum file size of 1MB per file
• compress: false - Content stored uncompressed for speed

​

Manual Snapshot Creation

import { RollbackManager } from './modules/rollback-manager';

const rollbackMgr = new RollbackManager();
const snapshot = await rollbackMgr.createSnapshot(
  ['.env', '.env.local', '.env.production'],
  {
    includeContent: true,
    includePermissions: true,
    maxSize: 1024 * 1024, // 1MB
  }
);

console.log(`Snapshot created: ${snapshot.id}`);

​

Rollback Process

​

When Rollback is Triggered

1. Restoration fails during file writing
2. File validation fails
3. Permission errors prevent file updates
4. Any error occurs during the restore process

​

How Rollback Works

1. Loads snapshot metadata from .env-twin/rollbacks/{snapshotId}/metadata.json
2. Validates snapshot - Ensures all required files exist
3. Restores each file:
   • If file existed: Restore content and permissions from snapshot
   • If file didn’t exist: Remove any new files created
4. Reports results - List of successfully rolled back files

// From rollback-manager.ts:212-302
async rollbackToSnapshot(snapshotId: string): Promise<RollbackResult> {
  // Load snapshot metadata
  const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
  
  // Restore each file
  for (const fileInfo of metadata.files) {
    const filePath = path.join(this.cwd, fileInfo.fileName);
    
    if (fileInfo.exists && fileInfo.hasContent) {
      // Restore file from snapshot
      const content = fs.readFileSync(contentPath, 'utf-8');
      fs.writeFileSync(filePath, content, 'utf-8');
      
      // Restore permissions (Unix only)
      if (fileInfo.permissions && process.platform !== 'win32') {
        fs.chmodSync(filePath, fileInfo.permissions);
      }
    } else if (!fileInfo.exists) {
      // File didn't exist, remove it
      if (fs.existsSync(filePath)) {
        fs.unlinkSync(filePath);
      }
    }
  }
}

​

Snapshot Management

​

Listing Snapshots

const snapshots = rollbackMgr.listSnapshots();

snapshots.forEach(snapshot => {
  console.log(`ID: ${snapshot.id}`);
  console.log(`Created: ${snapshot.createdAt}`);
  console.log(`Files: ${snapshot.files.length}`);
});

​

Automatic Cleanup

// Cleanup happens automatically after creating a new snapshot
cleanupOldSnapshots(): void {
  const snapshots = this.listSnapshots();
  
  if (snapshots.length <= this.maxSnapshots) {
    return;
  }
  
  const snapshotsToDelete = snapshots.slice(this.maxSnapshots);
  
  for (const snapshot of snapshotsToDelete) {
    this.deleteSnapshot(snapshot.id);
  }
}

​

Manual Snapshot Deletion

const deleted = rollbackMgr.deleteSnapshot('rollback-1234567890-abc123');
console.log(deleted ? 'Deleted' : 'Not found');

​

Security Features

​

Path Traversal Prevention

private isPathSafe(fileName: string): boolean {
  const targetPath = path.resolve(this.cwd, fileName);
  const relative = path.relative(this.cwd, targetPath);
  return !relative.startsWith('..') && !path.isAbsolute(relative);
}

​

Secure Permissions

• Directories: 0o700 (rwx------) - Only owner can access
• Files: 0o600 (rw-------) - Only owner can read/write

​

Advanced Usage

​

Snapshot Validation

const { isValid, changedFiles } = rollbackMgr.isSnapshotValid(snapshotId);

if (!isValid) {
  console.warn(`Snapshot is invalid. Changed files:`);
  changedFiles.forEach(file => console.log(`  - ${file}`));
}

• File existence matches snapshot
• File size hasn’t changed
• Modification time within 1 second tolerance

​

Snapshot Size Information

const { totalSize, fileCount } = rollbackMgr.getSnapshotSize(snapshotId);
console.log(`Snapshot uses ${totalSize} bytes across ${fileCount} files`);

​

Atomic File Operations

import { RollbackUtils } from './modules/rollback-manager';

// Replace file atomically with automatic rollback on failure
const { success, rollbackPath } = RollbackUtils.atomicFileReplace(
  '.env',
  'NEW_KEY=new_value\n'
);

if (!success && rollbackPath) {
  // Rollback to previous content
  RollbackUtils.rollbackAtomicOperation('.env', rollbackPath);
}

​

Best Practices

1. Enable rollback for critical operations:
   env-twin restore --create-rollback --preserve-permissions
   
2. Monitor snapshot storage:
   • Each snapshot can use significant disk space
   • Default limit of 10 snapshots prevents excessive storage use
   • Large files (>1MB) are tracked but not fully stored
3. Validate before rollback:
   # Use --dry-run to preview changes
   env-twin restore --dry-run --create-rollback
   
4. Test rollback in development:
   • Create test snapshots
   • Verify rollback works correctly
   • Understand timing and performance implications

​

Troubleshooting

​

Snapshot Creation Fails

• Check disk space in .env-twin/rollbacks/
• Verify write permissions on working directory
• Ensure files are smaller than 1MB (or increase maxSize)

​

Rollback Not Available

# Check if rollback directory exists and is accessible
ls -la .env-twin/rollbacks/

# Verify permissions
chmod 700 .env-twin/rollbacks/

​

Snapshot Validation Fails

env-twin restore --create-rollback --force

​

Related Topics

• File Preservation - How permissions and timestamps are preserved
• Restore Command - Using the restore command with rollback
• CI/CD Integration - Rollback strategies for automated environments