Implement CLI skeleton with cobra and fx dependency injection

- Set up cobra CLI with all commands (backup, restore, prune, verify, fetch) - Integrate uber/fx for dependency injection and lifecycle management - Add globals package with build-time variables (Version, Commit) - Implement config loading from YAML with validation - Create core data models (FileInfo, ChunkInfo, BlobInfo, Snapshot) - Add Makefile with build, test, lint, and clean targets - Include minimal test suite for compilation verification - Update documentation with --quick flag for verify command - Fix markdown numbering in implementation TODO
2025-07-20 09:34:14 +02:00
parent 0df07790ba
commit 3e8b98dec6
20 changed files with 1043 additions and 115 deletions
--- a/internal/cli/backup.go
+++ b/internal/cli/backup.go
@@ -0,0 +1,72 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	"git.eeqj.de/sneak/vaultik/internal/config"
+	"git.eeqj.de/sneak/vaultik/internal/globals"
+	"github.com/spf13/cobra"
+	"go.uber.org/fx"
+)
+
+// BackupOptions contains options for the backup command
+type BackupOptions struct {
+	ConfigPath string
+	Daemon     bool
+	Cron       bool
+}
+
+// NewBackupCommand creates the backup command
+func NewBackupCommand() *cobra.Command {
+	opts := &BackupOptions{}
+
+	cmd := &cobra.Command{
+		Use:   "backup <config.yaml>",
+		Short: "Perform incremental backup",
+		Long:  `Backup configured directories using incremental deduplication and encryption`,
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.ConfigPath = args[0]
+			return runBackup(cmd.Context(), opts)
+		},
+	}
+
+	cmd.Flags().BoolVar(&opts.Daemon, "daemon", false, "Run in daemon mode with inotify monitoring")
+	cmd.Flags().BoolVar(&opts.Cron, "cron", false, "Run in cron mode (silent unless error)")
+
+	return cmd
+}
+
+func runBackup(ctx context.Context, opts *BackupOptions) error {
+	app := fx.New(
+		fx.Supply(config.ConfigPath(opts.ConfigPath)),
+		fx.Provide(globals.New),
+		config.Module,
+		// Additional modules will be added here
+		fx.Invoke(func(g *globals.Globals, cfg *config.Config) error {
+			// TODO: Implement backup logic
+			fmt.Printf("Running backup with config: %s\n", opts.ConfigPath)
+			fmt.Printf("Version: %s, Commit: %s\n", g.Version, g.Commit)
+			if opts.Daemon {
+				fmt.Println("Running in daemon mode")
+			}
+			if opts.Cron {
+				fmt.Println("Running in cron mode")
+			}
+			return nil
+		}),
+		fx.NopLogger,
+	)
+
+	if err := app.Start(ctx); err != nil {
+		return fmt.Errorf("failed to start backup: %w", err)
+	}
+	defer func() {
+		if err := app.Stop(ctx); err != nil {
+			fmt.Printf("error stopping app: %v\n", err)
+		}
+	}()
+
+	return nil
+}
--- a/internal/cli/entry.go
+++ b/internal/cli/entry.go
@@ -0,0 +1,13 @@
+package cli
+
+import (
+	"os"
+)
+
+// CLIEntry is the main entry point for the CLI application
+func CLIEntry() {
+	rootCmd := NewRootCommand()
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
--- a/internal/cli/entry_test.go
+++ b/internal/cli/entry_test.go
@@ -0,0 +1,34 @@
+package cli
+
+import (
+	"testing"
+)
+
+// TestCLIEntry ensures the CLI can be imported and basic initialization works
+func TestCLIEntry(t *testing.T) {
+	// This test primarily serves as a compilation test
+	// to ensure all imports resolve correctly
+	cmd := NewRootCommand()
+	if cmd == nil {
+		t.Fatal("NewRootCommand() returned nil")
+	}
+	
+	if cmd.Use != "vaultik" {
+		t.Errorf("Expected command use to be 'vaultik', got '%s'", cmd.Use)
+	}
+	
+	// Verify all subcommands are registered
+	expectedCommands := []string{"backup", "restore", "prune", "verify", "fetch"}
+	for _, expected := range expectedCommands {
+		found := false
+		for _, cmd := range cmd.Commands() {
+			if cmd.Use == expected || cmd.Name() == expected {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected command '%s' not found", expected)
+		}
+	}
+}
--- a/internal/cli/fetch.go
+++ b/internal/cli/fetch.go
@@ -0,0 +1,71 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"git.eeqj.de/sneak/vaultik/internal/globals"
+	"github.com/spf13/cobra"
+	"go.uber.org/fx"
+)
+
+// FetchOptions contains options for the fetch command
+type FetchOptions struct {
+	Bucket     string
+	Prefix     string
+	SnapshotID string
+	FilePath   string
+	Target     string
+}
+
+// NewFetchCommand creates the fetch command
+func NewFetchCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "fetch <bucket> <prefix> <snapshot_id> <filepath> <target>",
+		Short: "Extract single file from backup",
+		Long:  `Download and decrypt a single file from a backup snapshot`,
+		Args:  cobra.ExactArgs(5),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts := &FetchOptions{
+				Bucket:     args[0],
+				Prefix:     args[1],
+				SnapshotID: args[2],
+				FilePath:   args[3],
+				Target:     args[4],
+			}
+			return runFetch(cmd.Context(), opts)
+		},
+	}
+
+	return cmd
+}
+
+func runFetch(ctx context.Context, opts *FetchOptions) error {
+	if os.Getenv("VAULTIK_PRIVATE_KEY") == "" {
+		return fmt.Errorf("VAULTIK_PRIVATE_KEY environment variable must be set")
+	}
+
+	app := fx.New(
+		fx.Supply(opts),
+		fx.Provide(globals.New),
+		// Additional modules will be added here
+		fx.Invoke(func(g *globals.Globals) error {
+			// TODO: Implement fetch logic
+			fmt.Printf("Fetching %s from snapshot %s to %s\n", opts.FilePath, opts.SnapshotID, opts.Target)
+			return nil
+		}),
+		fx.NopLogger,
+	)
+
+	if err := app.Start(ctx); err != nil {
+		return fmt.Errorf("failed to start fetch: %w", err)
+	}
+	defer func() {
+		if err := app.Stop(ctx); err != nil {
+			fmt.Printf("error stopping app: %v\n", err)
+		}
+	}()
+
+	return nil
+}
--- a/internal/cli/prune.go
+++ b/internal/cli/prune.go
@@ -0,0 +1,71 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"git.eeqj.de/sneak/vaultik/internal/globals"
+	"github.com/spf13/cobra"
+	"go.uber.org/fx"
+)
+
+// PruneOptions contains options for the prune command
+type PruneOptions struct {
+	Bucket string
+	Prefix string
+	DryRun bool
+}
+
+// NewPruneCommand creates the prune command
+func NewPruneCommand() *cobra.Command {
+	opts := &PruneOptions{}
+
+	cmd := &cobra.Command{
+		Use:   "prune <bucket> <prefix>",
+		Short: "Remove unreferenced blobs",
+		Long:  `Delete blobs that are no longer referenced by any snapshot`,
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.Bucket = args[0]
+			opts.Prefix = args[1]
+			return runPrune(cmd.Context(), opts)
+		},
+	}
+
+	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "Show what would be deleted without actually deleting")
+
+	return cmd
+}
+
+func runPrune(ctx context.Context, opts *PruneOptions) error {
+	if os.Getenv("VAULTIK_PRIVATE_KEY") == "" {
+		return fmt.Errorf("VAULTIK_PRIVATE_KEY environment variable must be set")
+	}
+
+	app := fx.New(
+		fx.Supply(opts),
+		fx.Provide(globals.New),
+		// Additional modules will be added here
+		fx.Invoke(func(g *globals.Globals) error {
+			// TODO: Implement prune logic
+			fmt.Printf("Pruning bucket %s with prefix %s\n", opts.Bucket, opts.Prefix)
+			if opts.DryRun {
+				fmt.Println("Running in dry-run mode")
+			}
+			return nil
+		}),
+		fx.NopLogger,
+	)
+
+	if err := app.Start(ctx); err != nil {
+		return fmt.Errorf("failed to start prune: %w", err)
+	}
+	defer func() {
+		if err := app.Stop(ctx); err != nil {
+			fmt.Printf("error stopping app: %v\n", err)
+		}
+	}()
+
+	return nil
+}
--- a/internal/cli/restore.go
+++ b/internal/cli/restore.go
@@ -0,0 +1,69 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"git.eeqj.de/sneak/vaultik/internal/globals"
+	"github.com/spf13/cobra"
+	"go.uber.org/fx"
+)
+
+// RestoreOptions contains options for the restore command
+type RestoreOptions struct {
+	Bucket     string
+	Prefix     string
+	SnapshotID string
+	TargetDir  string
+}
+
+// NewRestoreCommand creates the restore command
+func NewRestoreCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "restore <bucket> <prefix> <snapshot_id> <target_dir>",
+		Short: "Restore files from backup",
+		Long:  `Download and decrypt files from a backup snapshot`,
+		Args:  cobra.ExactArgs(4),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts := &RestoreOptions{
+				Bucket:     args[0],
+				Prefix:     args[1],
+				SnapshotID: args[2],
+				TargetDir:  args[3],
+			}
+			return runRestore(cmd.Context(), opts)
+		},
+	}
+
+	return cmd
+}
+
+func runRestore(ctx context.Context, opts *RestoreOptions) error {
+	if os.Getenv("VAULTIK_PRIVATE_KEY") == "" {
+		return fmt.Errorf("VAULTIK_PRIVATE_KEY environment variable must be set")
+	}
+
+	app := fx.New(
+		fx.Supply(opts),
+		fx.Provide(globals.New),
+		// Additional modules will be added here
+		fx.Invoke(func(g *globals.Globals) error {
+			// TODO: Implement restore logic
+			fmt.Printf("Restoring snapshot %s to %s\n", opts.SnapshotID, opts.TargetDir)
+			return nil
+		}),
+		fx.NopLogger,
+	)
+
+	if err := app.Start(ctx); err != nil {
+		return fmt.Errorf("failed to start restore: %w", err)
+	}
+	defer func() {
+		if err := app.Stop(ctx); err != nil {
+			fmt.Printf("error stopping app: %v\n", err)
+		}
+	}()
+
+	return nil
+}
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -0,0 +1,28 @@
+package cli
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// NewRootCommand creates the root cobra command
+func NewRootCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "vaultik",
+		Short: "Secure incremental backup tool with asymmetric encryption",
+		Long: `vaultik is a secure incremental backup daemon that encrypts data using age
+public keys and uploads to S3-compatible storage. No private keys are needed
+on the source system.`,
+		SilenceUsage: true,
+	}
+
+	// Add subcommands
+	cmd.AddCommand(
+		NewBackupCommand(),
+		NewRestoreCommand(),
+		NewPruneCommand(),
+		NewVerifyCommand(),
+		NewFetchCommand(),
+	)
+
+	return cmd
+}
--- a/internal/cli/verify.go
+++ b/internal/cli/verify.go
@@ -0,0 +1,81 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"git.eeqj.de/sneak/vaultik/internal/globals"
+	"github.com/spf13/cobra"
+	"go.uber.org/fx"
+)
+
+// VerifyOptions contains options for the verify command
+type VerifyOptions struct {
+	Bucket     string
+	Prefix     string
+	SnapshotID string
+	Quick      bool
+}
+
+// NewVerifyCommand creates the verify command
+func NewVerifyCommand() *cobra.Command {
+	opts := &VerifyOptions{}
+
+	cmd := &cobra.Command{
+		Use:   "verify <bucket> <prefix> [<snapshot_id>]",
+		Short: "Verify backup integrity",
+		Long:  `Check that all referenced blobs exist and verify metadata integrity`,
+		Args:  cobra.RangeArgs(2, 3),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.Bucket = args[0]
+			opts.Prefix = args[1]
+			if len(args) > 2 {
+				opts.SnapshotID = args[2]
+			}
+			return runVerify(cmd.Context(), opts)
+		},
+	}
+
+	cmd.Flags().BoolVar(&opts.Quick, "quick", false, "Perform quick verification by checking blob existence and S3 content hashes without downloading")
+
+	return cmd
+}
+
+func runVerify(ctx context.Context, opts *VerifyOptions) error {
+	if os.Getenv("VAULTIK_PRIVATE_KEY") == "" {
+		return fmt.Errorf("VAULTIK_PRIVATE_KEY environment variable must be set")
+	}
+
+	app := fx.New(
+		fx.Supply(opts),
+		fx.Provide(globals.New),
+		// Additional modules will be added here
+		fx.Invoke(func(g *globals.Globals) error {
+			// TODO: Implement verify logic
+			if opts.SnapshotID == "" {
+				fmt.Printf("Verifying latest snapshot in bucket %s with prefix %s\n", opts.Bucket, opts.Prefix)
+			} else {
+				fmt.Printf("Verifying snapshot %s in bucket %s with prefix %s\n", opts.SnapshotID, opts.Bucket, opts.Prefix)
+			}
+			if opts.Quick {
+				fmt.Println("Performing quick verification")
+			} else {
+				fmt.Println("Performing deep verification")
+			}
+			return nil
+		}),
+		fx.NopLogger,
+	)
+
+	if err := app.Start(ctx); err != nil {
+		return fmt.Errorf("failed to start verify: %w", err)
+	}
+	defer func() {
+		if err := app.Stop(ctx); err != nil {
+			fmt.Printf("error stopping app: %v\n", err)
+		}
+	}()
+
+	return nil
+}
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -0,0 +1,149 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"time"
+
+	"go.uber.org/fx"
+	"gopkg.in/yaml.v3"
+)
+
+// Config represents the application configuration
+type Config struct {
+	AgeRecipient      string        `yaml:"age_recipient"`
+	BackupInterval    time.Duration `yaml:"backup_interval"`
+	BlobSizeLimit     int64         `yaml:"blob_size_limit"`
+	ChunkSize         int64         `yaml:"chunk_size"`
+	Exclude           []string      `yaml:"exclude"`
+	FullScanInterval  time.Duration `yaml:"full_scan_interval"`
+	Hostname          string        `yaml:"hostname"`
+	IndexPath         string        `yaml:"index_path"`
+	IndexPrefix       string        `yaml:"index_prefix"`
+	MinTimeBetweenRun time.Duration `yaml:"min_time_between_run"`
+	S3                S3Config      `yaml:"s3"`
+	SourceDirs        []string      `yaml:"source_dirs"`
+	CompressionLevel  int           `yaml:"compression_level"`
+}
+
+// S3Config represents S3 storage configuration
+type S3Config struct {
+	Endpoint        string `yaml:"endpoint"`
+	Bucket          string `yaml:"bucket"`
+	Prefix          string `yaml:"prefix"`
+	AccessKeyID     string `yaml:"access_key_id"`
+	SecretAccessKey string `yaml:"secret_access_key"`
+	Region          string `yaml:"region"`
+	UseSSL          bool   `yaml:"use_ssl"`
+	PartSize        int64  `yaml:"part_size"`
+}
+
+// ConfigPath wraps the config file path for fx injection
+type ConfigPath string
+
+// New creates a new Config instance
+func New(path ConfigPath) (*Config, error) {
+	if path == "" {
+		return nil, fmt.Errorf("config path not provided")
+	}
+
+	cfg, err := Load(string(path))
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	return cfg, nil
+}
+
+// Load reads and parses the configuration file
+func Load(path string) (*Config, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read config file: %w", err)
+	}
+
+	cfg := &Config{
+		// Set defaults
+		BlobSizeLimit:     10 * 1024 * 1024 * 1024, // 10GB
+		ChunkSize:         10 * 1024 * 1024,        // 10MB
+		BackupInterval:    1 * time.Hour,
+		FullScanInterval:  24 * time.Hour,
+		MinTimeBetweenRun: 15 * time.Minute,
+		IndexPath:         "/var/lib/vaultik/index.sqlite",
+		IndexPrefix:       "index/",
+		CompressionLevel:  3,
+	}
+
+	if err := yaml.Unmarshal(data, cfg); err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+
+	// Get hostname if not set
+	if cfg.Hostname == "" {
+		hostname, err := os.Hostname()
+		if err != nil {
+			return nil, fmt.Errorf("failed to get hostname: %w", err)
+		}
+		cfg.Hostname = hostname
+	}
+
+	// Set default S3 settings
+	if cfg.S3.Region == "" {
+		cfg.S3.Region = "us-east-1"
+	}
+	if cfg.S3.PartSize == 0 {
+		cfg.S3.PartSize = 5 * 1024 * 1024 // 5MB
+	}
+
+	if err := cfg.Validate(); err != nil {
+		return nil, fmt.Errorf("invalid config: %w", err)
+	}
+
+	return cfg, nil
+}
+
+// Validate checks if the configuration is valid
+func (c *Config) Validate() error {
+	if c.AgeRecipient == "" {
+		return fmt.Errorf("age_recipient is required")
+	}
+
+	if len(c.SourceDirs) == 0 {
+		return fmt.Errorf("at least one source directory is required")
+	}
+
+	if c.S3.Endpoint == "" {
+		return fmt.Errorf("s3.endpoint is required")
+	}
+
+	if c.S3.Bucket == "" {
+		return fmt.Errorf("s3.bucket is required")
+	}
+
+	if c.S3.AccessKeyID == "" {
+		return fmt.Errorf("s3.access_key_id is required")
+	}
+
+	if c.S3.SecretAccessKey == "" {
+		return fmt.Errorf("s3.secret_access_key is required")
+	}
+
+	if c.ChunkSize < 1024*1024 { // 1MB minimum
+		return fmt.Errorf("chunk_size must be at least 1MB")
+	}
+
+	if c.BlobSizeLimit < c.ChunkSize {
+		return fmt.Errorf("blob_size_limit must be at least chunk_size")
+	}
+
+	if c.CompressionLevel < 1 || c.CompressionLevel > 19 {
+		return fmt.Errorf("compression_level must be between 1 and 19")
+	}
+
+	return nil
+}
+
+// Module exports the config module for fx
+var Module = fx.Module("config",
+	fx.Provide(New),
+)
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -0,0 +1,47 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestConfigLoad ensures the config package can be imported and basic functionality works
+func TestConfigLoad(t *testing.T) {
+	// Create a temporary config file
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "test-config.yaml")
+	
+	configContent := `age_recipient: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+source_dirs:
+  - /tmp/test
+s3:
+  endpoint: https://s3.example.com
+  bucket: test-bucket
+  access_key_id: test-key
+  secret_access_key: test-secret
+`
+	
+	if err := os.WriteFile(configPath, []byte(configContent), 0644); err != nil {
+		t.Fatalf("Failed to write test config: %v", err)
+	}
+	
+	// Test loading the config
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Failed to load config: %v", err)
+	}
+	
+	// Basic validation
+	if cfg.AgeRecipient != "age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" {
+		t.Errorf("Expected age recipient to be set, got '%s'", cfg.AgeRecipient)
+	}
+	
+	if len(cfg.SourceDirs) != 1 || cfg.SourceDirs[0] != "/tmp/test" {
+		t.Errorf("Expected source dirs to be ['/tmp/test'], got %v", cfg.SourceDirs)
+	}
+	
+	if cfg.S3.Bucket != "test-bucket" {
+		t.Errorf("Expected S3 bucket to be 'test-bucket', got '%s'", cfg.S3.Bucket)
+	}
+}
--- a/internal/globals/globals.go
+++ b/internal/globals/globals.go
@@ -0,0 +1,39 @@
+package globals
+
+import (
+	"context"
+	"time"
+
+	"go.uber.org/fx"
+)
+
+// these get populated from main() and copied into the Globals object.
+var (
+	Appname string = "vaultik"
+	Version string = "dev"
+	Commit  string = "unknown"
+)
+
+type Globals struct {
+	Appname   string
+	Version   string
+	Commit    string
+	StartTime time.Time
+}
+
+func New(lc fx.Lifecycle) (*Globals, error) {
+	n := &Globals{
+		Appname: Appname,
+		Version: Version,
+		Commit:  Commit,
+	}
+	
+	lc.Append(fx.Hook{
+		OnStart: func(ctx context.Context) error {
+			n.StartTime = time.Now()
+			return nil
+		},
+	})
+	
+	return n, nil
+}
--- a/internal/globals/globals_test.go
+++ b/internal/globals/globals_test.go
@@ -0,0 +1,36 @@
+package globals
+
+import (
+	"testing"
+	
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+)
+
+// TestGlobalsNew ensures the globals package initializes correctly
+func TestGlobalsNew(t *testing.T) {
+	app := fxtest.New(t,
+		fx.Provide(New),
+		fx.Invoke(func(g *Globals) {
+			if g == nil {
+				t.Fatal("Globals instance is nil")
+			}
+			
+			if g.Appname != "vaultik" {
+				t.Errorf("Expected Appname to be 'vaultik', got '%s'", g.Appname)
+			}
+			
+			// Version and Commit will be "dev" and "unknown" by default
+			if g.Version == "" {
+				t.Error("Version should not be empty")
+			}
+			
+			if g.Commit == "" {
+				t.Error("Commit should not be empty")
+			}
+		}),
+	)
+	
+	app.RequireStart()
+	app.RequireStop()
+}
--- a/internal/models/models.go
+++ b/internal/models/models.go
@@ -0,0 +1,73 @@
+package models
+
+import (
+	"time"
+)
+
+// FileInfo represents a file in the backup system
+type FileInfo struct {
+	Path  string
+	MTime time.Time
+	Size  int64
+}
+
+// ChunkInfo represents a content-addressed chunk
+type ChunkInfo struct {
+	Hash   string // SHA256 hash
+	Size   int64
+	Offset int64 // Offset within source file
+}
+
+// ChunkRef represents a reference to a chunk in a blob or file
+type ChunkRef struct {
+	ChunkHash string
+	Offset    int64
+	Length    int64
+}
+
+// BlobInfo represents an encrypted blob containing multiple chunks
+type BlobInfo struct {
+	Hash       string    // Hash of encrypted blob
+	FinalHash  string    // Hash after compression and encryption
+	CreatedAt  time.Time
+	Size       int64
+	ChunkCount int
+}
+
+// Snapshot represents a backup snapshot
+type Snapshot struct {
+	ID           string    // ISO8601 timestamp
+	Hostname     string
+	Version      string
+	CreatedAt    time.Time
+	FileCount    int64
+	ChunkCount   int64
+	BlobCount    int64
+	TotalSize    int64
+	MetadataSize int64
+}
+
+// SnapshotMetadata contains the full metadata for a snapshot
+type SnapshotMetadata struct {
+	Snapshot   *Snapshot
+	Files      map[string]*FileInfo
+	Chunks     map[string]*ChunkInfo
+	Blobs      map[string]*BlobInfo
+	FileChunks map[string][]*ChunkRef // path -> chunks
+	BlobChunks map[string][]*ChunkRef // blob hash -> chunks
+}
+
+// Chunk represents a data chunk for processing
+type Chunk struct {
+	Data   []byte
+	Hash   string
+	Offset int64
+	Length int64
+}
+
+// DirtyPath represents a path marked for backup by inotify
+type DirtyPath struct {
+	Path      string
+	MarkedAt  time.Time
+	EventType string // "create", "modify", "delete"
+}
--- a/internal/models/models_test.go
+++ b/internal/models/models_test.go
@@ -0,0 +1,55 @@
+package models
+
+import (
+	"testing"
+	"time"
+)
+
+// TestModelsCompilation ensures all model types can be instantiated
+func TestModelsCompilation(t *testing.T) {
+	// This test primarily serves as a compilation test
+	// to ensure all types are properly defined
+	
+	// Test FileInfo
+	fi := &FileInfo{
+		Path:  "/test/file.txt",
+		MTime: time.Now(),
+		Size:  1024,
+	}
+	if fi.Path != "/test/file.txt" {
+		t.Errorf("FileInfo.Path not set correctly")
+	}
+	
+	// Test ChunkInfo
+	ci := &ChunkInfo{
+		Hash:   "abc123",
+		Size:   512,
+		Offset: 0,
+	}
+	if ci.Hash != "abc123" {
+		t.Errorf("ChunkInfo.Hash not set correctly")
+	}
+	
+	// Test BlobInfo
+	bi := &BlobInfo{
+		Hash:       "blob123",
+		FinalHash:  "final123",
+		CreatedAt:  time.Now(),
+		Size:       1024,
+		ChunkCount: 2,
+	}
+	if bi.Hash != "blob123" {
+		t.Errorf("BlobInfo.Hash not set correctly")
+	}
+	
+	// Test Snapshot
+	s := &Snapshot{
+		ID:        "2024-01-01T00:00:00Z",
+		Hostname:  "test-host",
+		Version:   "1.0.0",
+		CreatedAt: time.Now(),
+	}
+	if s.ID != "2024-01-01T00:00:00Z" {
+		t.Errorf("Snapshot.ID not set correctly")
+	}
+}