backup

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 25, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package backup provides configuration backup and restore capabilities for aix.

This package implements a backup strategy for AI assistant platform configurations, allowing users to safely back up, restore, and manage configuration snapshots before making changes.

Backup Strategy

The backup system uses a directory-based approach where each backup is stored in a timestamped directory containing:

  • manifest.json: Metadata about the backup including file hashes for integrity
  • Copied files: Original configuration files with preserved permissions

Backup locations follow this hierarchy: 

~/.config/aix/backups/
`--- {platform}/
    `--- {timestamp}/
        |-- manifest.json
        `--- {copied files...}

Creating Backups

Use Manager.Backup to create a new backup of platform configuration files: 

mgr := backup.NewManager()
manifest, err := mgr.Backup("claude", []string{
    "~/.claude/config.json",
    "~/.claude/agents/",
})

The backup captures file contents, permissions, and generates SHA256 checksums for integrity verification during restore.

Restoring Backups

Use Manager.Restore to restore a previous backup: 

err := mgr.Restore("claude", "20260123T100712")

Before restoring, the current configuration is backed up automatically to prevent data loss. The restore operation verifies file integrity using stored checksums.

Retention Management

The Manager.Prune method removes old backups beyond the configured retention count: 

err := mgr.Prune("claude", 5) // Keep 5 most recent backups

The default retention count is 5 backups per platform.

Listing Backups

Use Manager.List to retrieve available backups sorted by date (newest first): 

manifests, err := mgr.List("claude")
for _, m := range manifests {
    fmt.Printf("%s: %d files\n", m.CreatedAt.Format(time.RFC3339), len(m.Files))
}

Backup Manifest

Each backup includes a BackupManifest containing:

  • Version: Manifest format version for forward compatibility
  • CreatedAt: Timestamp when the backup was created
  • Platform: The AI assistant platform (claude, opencode, etc.)
  • Files: List of backed up files with paths, hashes, and permissions
  • AIXVersion: Version of aix that created the backup

Integrity Verification

File integrity is verified using SHA256 checksums stored in the manifest. If a backup file's hash doesn't match during restore, ErrBackupCorrupted is returned.

Error Handling

The package defines several sentinel errors for specific failure conditions:

Index

Constants

View Source 
const (
	// DefaultRetentionCount is the default number of backups to retain per platform.
	DefaultRetentionCount = 5
)

Default configuration values.

View Source 
const ManifestVersion = 1

Manifest format version for forward compatibility.

Variables

View Source 
var (
	// ErrNoBackupsFound indicates no backups exist for the specified platform.
	ErrNoBackupsFound = errors.New("no backups found")

	// ErrBackupCorrupted indicates backup file integrity verification failed.
	// This occurs when a file's SHA256 hash doesn't match the manifest.
	ErrBackupCorrupted = errors.New("backup corrupted")

	// ErrRestoreConflict indicates the target file has been modified since the backup.
	// This prevents accidental overwrites of user changes.
	ErrRestoreConflict = errors.New("restore conflict")
)

Sentinel errors for backup operations.

View Source 
var Version = "dev"

Version is set at build time via ldflags.

Functions

func BackupDir 

func BackupDir() string

BackupDir returns the root backup directory for aix. Returns ~/.config/aix/backups/

func BackupPath 

func BackupPath(platform, timestamp string) string

BackupPath returns the full path to a specific backup directory. Returns ~/.config/aix/backups/{platform}/{timestamp}/

func EnsureBackedUp 

func EnsureBackedUp(platformName string, paths []string) error

EnsureBackedUp ensures a backup exists for the platform before modification. Uses sync.Once pattern to ensure only one backup is created per platform per session.

The function is safe for concurrent calls and will only create one backup per platform regardless of how many times it's called.

Returns nil if:

  • A backup was just created successfully
  • A backup was already created in this session (no-op)
  • No paths are provided (nothing to back up)

Returns an error if:

  • The backup creation fails

func PlatformBackupDir 

func PlatformBackupDir(platform string) string

PlatformBackupDir returns the backup directory for a specific platform. Returns ~/.config/aix/backups/{platform}/

func ResetBackupState 

func ResetBackupState()

ResetBackupState clears the backup state for all platforms. This is primarily useful for testing to reset state between tests.

func ResetPlatformBackupState 

func ResetPlatformBackupState(platformName string)

ResetPlatformBackupState clears the backup state for a specific platform. This allows a new backup to be created for the platform on the next call to EnsureBackedUp.

Types

type BackupConfig 

type BackupConfig struct {
	// RetentionCount is the number of backups to retain per platform.
	// When exceeded, older backups are pruned.
	// Defaults to DefaultRetentionCount (5).
	RetentionCount int

	// BackupDir is the root directory for storing backups.
	// Defaults to ~/.config/aix/backups/
	BackupDir string
}

BackupConfig holds configuration for the backup manager.

type BackupFile 

type BackupFile struct {
	// OriginalPath is the absolute path where the file was located.
	OriginalPath string `json:"original_path"`

	// RelPath is the relative path within the backup directory.
	RelPath string `json:"rel_path"`

	// SHA256Hash is the hex-encoded SHA256 hash of the file contents.
	SHA256Hash string `json:"sha256_hash"`

	// Mode is the file's permission bits.
	Mode fs.FileMode `json:"mode"`
}

BackupFile contains metadata for a single backed up file.

type BackupManifest 

type BackupManifest struct {
	// Version is the manifest format version for forward compatibility.
	Version int `json:"version"`

	// CreatedAt is when the backup was created.
	CreatedAt time.Time `json:"created_at"`

	// Platform is the AI assistant platform (claude, opencode, etc.).
	Platform string `json:"platform"`

	// Files contains metadata for each backed up file.
	Files []BackupFile `json:"files"`

	// AIXVersion is the version of aix that created this backup.
	AIXVersion string `json:"aix_version"`

	// ID is the backup identifier (timestamp format: 20260123T100712).
	// This field is populated when loading from disk but not stored in JSON.
	ID string `json:"-"`
}

BackupManifest contains metadata about a backup. It is stored as manifest.json in each backup directory.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager handles backup creation, restoration, and management.

func NewManager 

func NewManager(opts ...Option) *Manager

NewManager creates a new backup Manager with the given options.

func (*Manager) Backup 

func (m *Manager) Backup(platform string, paths []string) (*BackupManifest, error)

func (*Manager) Get 

func (m *Manager) Get(platform, backupID string) (*BackupManifest, error)

Get returns the manifest for a specific backup.

func (*Manager) List 

func (m *Manager) List(platform string) ([]BackupManifest, error)

List returns all available backups for a platform, sorted by date (newest first).

func (*Manager) Prune 

func (m *Manager) Prune(platform string, keep int) error

Prune removes old backups beyond the specified retention count. Keeps the most recent 'keep' backups for the platform.

func (*Manager) Restore 

func (m *Manager) Restore(platform, backupID string) error

Restore restores files from a backup to their original locations. The backupID should be in timestamp format (e.g., "20260123T100712").

type Option 

type Option func(*Manager)

Option configures a Manager.

func WithBackupDir 

func WithBackupDir(dir string) Option

WithBackupDir sets the root backup directory.

func WithRetentionCount 

func WithRetentionCount(n int) Option

WithRetentionCount sets the number of backups to retain per platform.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.