backup_restore
Create, list, restore, and cleanup timestamped backups of files modified by write operations. Restore overwrites a file with a specific backup, and cleanup deletes old backups based on age or count.
Instructions
Manage the timestamped backup files produced by modify_file and write_files_atomic. Four actions: create (manually snapshot a file before a risky native edit), list (enumerate known backups, optionally filtered to one file), restore (overwrite a file with a specific backup_id), cleanup (delete old backups per the policy in cleanup_options). The cleanup policy applies BOTH thresholds — a backup is deleted only when it exceeds max_age_days OR when its file already has more than max_count_per_file newer backups. Use dry_run to preview before applying. ⚠️ DESTRUCTIVE: restore overwrites the current file (the prior state is auto-snapshotted to <path>.pre_restore_<timestamp>, so the restore itself is reversible); cleanup permanently deletes backup files from disk. create and list are read-only. Returns: { success, action, ...action-specific fields }. create→{backup_id, backup_path, original_path, size}. restore→{backup_id, restored_to, pre_restore_backup}. list→{file_path, backups:[{path, backup_id, size, created, metadata}]}. cleanup→{dry_run, backups_deleted, deleted:[{path, reason:'age'|'count'}]}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Required. Operation to perform on the backup store. | |
| file_path | No | For `create`: file to snapshot (required). For `list`: optional filter to one file. Ignored for `restore` (use backup_id) and `cleanup` (operates on the whole store). | |
| backup_id | No | Identifier of the backup to restore (timestamp from `<path>.backup.<timestamp>`). Required for `restore`, ignored for other actions. | |
| metadata | No | Optional tags and description attached to a `create` snapshot for later identification via `list`. | |
| cleanup_options | No | Policy controls for the `cleanup` action. Ignored by other actions. |