sync

type DependencyDecision uint8

type DependencyDecisionHandler func(context.Context, sources.ID, sources.Dependency, bool) (DependencyDecision, error)

type Option func(*Options)

type Options struct {
	// Orchestration control
	DryRun  bool          // Show changes without applying them
	Timeout time.Duration // Timeout for the entire sync operation

	// Source selection
	Sources    []sources.ID         // Which sources to use (empty means default providers/local/models.dev HTTP)
	ProviderID *catalogs.ProviderID // Filter for specific provider

	// Output control (used AFTER merging)
	OutputPath string // Where to save final catalog (empty means default location)

	// Source behavior control
	Fresh              bool   // Delete existing models and fetch fresh from APIs (destructive)
	CleanModelsDevRepo bool   // Remove temporary models.dev repository after update
	Reformat           bool   // Reformat providers.yaml file even without changes
	SourcesDir         string // Directory for external source data (models.dev cache/git)
	ModelsDevGitCommit string // Exact models.dev commit required by Git verification

	// Dependency control
	AutoInstallDeps   bool // Automatically install missing dependencies without prompting
	SkipDepPrompts    bool // Skip dependency prompts and continue without optional dependencies
	RequireAllSources bool // Require all sources to succeed (fail if any dependencies are missing)

	// DependencyDecisionHandler is supplied by an interactive adapter. It is nil
	// for library, server, scheduler, and other noninteractive callers.
	DependencyDecisionHandler DependencyDecisionHandler
}

type ProviderResult struct {
	ProviderID catalogs.ProviderID  // The provider that was synced
	Added      []catalogs.Model     // New models not in catalog
	Updated    []differ.ModelUpdate // Existing models with changes
	Removed    []catalogs.Model     // Models in catalog but not in API (informational only)

	// Summary counts
	AddedCount   int // Number of models added
	UpdatedCount int // Number of models updated
	RemovedCount int // Number of models removed from API (not deleted from catalog)

	// Metadata
	APIModelsCount      int // Total models fetched from API
	ExistingModelsCount int // Total models that existed in catalog
	EnhancedCount       int // Number of models enhanced with models.dev data
}

type Result struct {
	// Overall statistics
	TotalChanges     int                                     // Total number of changes across all providers
	ProvidersChanged int                                     // Number of providers with changes
	ProviderResults  map[catalogs.ProviderID]*ProviderResult // Results per provider

	// Operation metadata
	DryRun    bool   // Whether this was a dry run
	Fresh     bool   // Whether this was a fresh sync
	OutputDir string // Where files were written (empty means default)
	Sources   []sources.ID
	// SourceObservations contains caller-owned freshness/audit projections from
	// every source used by this attempt, including no-change synchronizations.
	SourceObservations []catalogs.SourceObservationLink
	GenerationID       string // Durable generation activated by a non-dry sync
	SyncRunID          string // Correlation ID for the synchronization attempt
}