git:20251203.970d936 to git:20260725.c9691fc

- # Pre-Edit Backup Skill

-

- Creates and manages file backups before edit operations in agent workflows.

-

- ## Overview

-

- The Pre-Edit Backup Skill safely preserves file content before modifications, enabling safe recovery if edits encounter issues. It maintains a structured backup directory with metadata and verification capabilities.

-

- ## Features

-

- - **Atomic Backup Creation**: Creates timestamped backups with file hash validation

- - **Metadata Storage**: JSON metadata tracks backup timestamp, original path, agent ID, and file stats

- - **Hash Verification**: SHA256 hash generation (8-char truncated) for change detection

- - **Automatic Cleanup**: Removes old backups (24h TTL by default, configurable)

- - **Revert Capability**: Restore files to backed-up state

- - **Concurrent Safety**: Handles parallel backup operations safely

-

- ## Architecture

-

- ### Directory Structure

- ```

- .backups/

- ├── agent-id-1/

- │ ├── 1700000000000_a1b2c3d4/

- │ │ ├── original-file.ts (backed-up file)

- │ │ ├── metadata.json (backup metadata)

- │ │ └── revert.sh (restoration script)

- │ └── 1700000010000_e5f6g7h8/

- │ ├── original-file.ts

- │ ├── metadata.json

- │ └── revert.sh

- └── agent-id-2/

- └── 1700000020000_i9j0k1l2/

- ├── different-file.ts

- ├── metadata.json

- └── revert.sh

- ```

-

- ### Metadata Format

- ```json

- {

- "timestamp": "2024-11-20T10:30:45.123Z",

- "agentId": "backend-dev-123",

- "originalFile": "/absolute/path/to/file.ts",

- "fileHash": "a1b2c3d4",

- "backupPath": "/absolute/path/.backups/agent-id/timestamp_hash",

- "createdAt": "2024-11-20T10:30:45.000Z",

- "fileSize": 2048,

- "lineCount": 42

- }

- ```

-

- ## TypeScript API

-

- ### BackupManager Class

-

- ```typescript

- import { BackupManager, BackupResult } from '@/hooks/backup-manager';

-

- const manager = new BackupManager(projectRoot, {

- retentionHours: 24,

- maxBackups: 10,

- backupDir: '.backups',

- });

-

- // Create backup

- const result: BackupResult = await manager.createBackup(filePath, agentId);

- // Result: {

- // backupPath: "/project/.backups/agent-123/1700000000000_a1b2c3d4",

- // timestamp: "2024-11-20T10:30:45.123Z",

- // fileHash: "a1b2c3d4",

- // originalPath: "/project/src/file.ts",

- // metadata: { ... }

- // }

-

- // List all backups for a file

- const backups = await manager.listBackups(filePath);

- // Returns sorted by most recent first

-

- // Revert to most recent backup

- await manager.revertFile(filePath, agentId);

-

- // Verify backup integrity

- const isValid = await manager.verifyBackup(backupPath);

-

- // Clean old backups

- const deletedCount = await manager.cleanOldBackups(agentId);

- ```

-

- ## CLI Interface

-

- ### Pre-Edit Hook CLI

-

- Creates backup before file edits:

-

- ```bash

- # TypeScript compiled version

- node dist/cli/pre-edit-hook.js /path/to/file.ts --agent-id agent-123

-

- # Output: /project/.backups/agent-123/1700000000000_a1b2c3d4

- ```

-

- ### Bash Wrapper

-

- For agent compatibility, use the bash wrapper:

-

- ```bash

- # Primary wrapper (tries TypeScript, falls back to bash)

- ./.claude/hooks/cfn-invoke-pre-edit-ts.sh /path/to/file.ts --agent-id agent-123

-

- # Legacy bash-only wrapper

- ./.claude/hooks/cfn-invoke-pre-edit.sh /path/to/file.ts --agent-id agent-123

- ```

-

- ## Integration

-

- ### In Agent Prompts

-

- Pre-edit backup is automatically injected into agent prompts via `src/cli/agent-prompt-builder.ts`:

-

- ```bash

- # Before any Edit/Write operation

- BACKUP_PATH=$(./.claude/hooks/cfn-invoke-pre-edit.sh "$FILE_PATH" --agent-id "$AGENT_ID")

-

- # On validation failure, revert

- ./.claude/skills/pre-edit-backup/revert-file.sh "$FILE_PATH" --agent-id "$AGENT_ID"

- ```

-

- ### Configuration

-

- Backup behavior is configured in agent initialization:

-

- ```typescript

- interface BackupConfig {

- retentionHours: number; // Default: 24

- maxBackups: number; // Default: 10

- backupDir: string; // Default: '.backups'

- }

- ```

-

- ## Use Cases

-

- ### 1. Safe File Modifications

-

- ```typescript

- // Create backup before risky edit

- const backup = await manager.createBackup(filePath, agentId);

-

- try {

- // Perform complex transformations

- await modifyFile(filePath, changes);

- } catch (error) {

- // Restore on error

- await manager.revertFile(filePath, agentId);

- throw error;

- }

- ```

-

- ### 2. Change Tracking

-

- ```typescript

- // Get file history for an agent

- const backups = await manager.listBackups(filePath);

-

- backups.forEach((backup) => {

- console.log(`Modified by ${backup.metadata.agentId} at ${backup.timestamp}`);

- console.log(` Size: ${backup.metadata.fileSize} bytes`);

- console.log(` Hash: ${backup.metadata.fileHash}`);

- });

- ```

-

- ### 3. Parallel Agent Safety

-

- ```typescript

- // Multiple agents backing up same file

- const promises = agents.map((agent) =>

- manager.createBackup(filePath, agent.id)

- );

- const results = await Promise.all(promises);

- // Each backup isolated by agent ID

- ```

-

- ## Testing

-

- Run tests with Jest:

-

- ```bash

- npm test tests/backup-manager.test.ts

-

- # With coverage

- npm test tests/backup-manager.test.ts -- --coverage

- ```

-

- Test coverage includes:

- - Backup creation and directory structure

- - Metadata generation and storage

- - File hash generation and consistency

- - Revert functionality

- - List operations and sorting

- - Cleanup (age-based and count-based)

- - Verification and integrity checks

- - Edge cases (empty files, large files, special characters, concurrency)

-

- ## Performance

-

- - **Backup Creation**: <50ms typical (mostly file I/O)

- - **Hash Generation**: <5ms for typical files

- - **Cleanup**: <100ms for 10 backups

- - **List Operations**: Linear in number of backups

- - **Concurrent Backups**: Safe, isolated by agent ID

-

- ## Troubleshooting

-

- ### Backup Creation Fails

-

- ```bash

- # Check file exists and is readable

- ls -lah "$FILE_PATH"

-

- # Check backup directory is writable

- touch .backups/test-write && rm .backups/test-write

-

- # Check disk space

- df -h

- ```

-

- ### Cannot Revert

-

- ```bash

- # List available backups

- node -e "

- const { BackupManager } = require('./dist/hooks/backup-manager.js');

- const m = new BackupManager('.');

- m.listBackups('$FILE_PATH').then(b => console.log(JSON.stringify(b, null, 2)))

- "

-

- # Verify backup integrity

- node -e "

- const { BackupManager } = require('./dist/hooks/backup-manager.js');

- const m = new BackupManager('.');

- m.verifyBackup('$BACKUP_PATH').then(r => console.log(r ? '✅ Valid' : '❌ Corrupted'))

- "

- ```

-

- ### Old Backups Not Cleaning

-

- ```bash

- # Manual cleanup with custom retention

- const manager = new BackupManager('.', { retentionHours: 12 });

- const deleted = await manager.cleanOldBackups(agentId);

- console.log(`Deleted ${deleted} old backups`);

- ```

-

- ## Migration Guide

-

- ### From Bash to TypeScript

-

- The TypeScript implementation maintains compatibility with bash:

-

- 1. **Existing bash hooks continue working** via wrapper scripts

- 2. **TypeScript implementation is opt-in** via environment check in wrappers

- 3. **Gradual rollout**: Use `CFN_USE_TS_HOOKS=true` to enable globally

-

- ```bash

- # Enable TypeScript hooks for new workflows

- export CFN_USE_TS_HOOKS=true

-

- # Old bash API still works

- ./.claude/hooks/cfn-invoke-pre-edit.sh file.ts --agent-id agent-1

- ```

-

- ## References

-

- - **CLI Configuration**: `.claude/hooks/cfn-post-edit.config.json`

- - **Agent Prompt Builder**: `src/cli/agent-prompt-builder.ts`

- - **Tests**: `tests/backup-manager.test.ts`

- - **Hook Wrappers**: `.claude/hooks/cfn-invoke-pre-edit*.sh`