sync

type ActionState struct {
	Name string `json:"name"`
	ID   string `json:"id"`
}

type ComponentState struct {
	Name     string                  `json:"name"`
	ID       string                  `json:"id"`
	ConfigID string                  `json:"config_id"`
	Type     models.AppComponentType `json:"type"`
	Checksum string                  `json:"checksum"`
}

type InstallSyncResult struct {
	InstallID   string     `json:"install_id"`
	InstallName string     `json:"install_name"`
	Created     bool       `json:"created"`
	Changed     bool       `json:"changed"`
	Diff        *diff.Diff `json:"diff,omitempty"`
}

type Result struct {
	ComponentsScheduled []ComponentState `json:"components_scheduled,omitempty"`

	// Orphaned* map name to ID for resources dropped since the previous config.
	OrphanedComponents map[string]string `json:"orphaned_components,omitempty"`
	OrphanedActions    map[string]string `json:"orphaned_actions,omitempty"`
	OrphanedRunbooks   map[string]string `json:"orphaned_runbooks,omitempty"`
}

type RunbookState struct {
	Name string `json:"name"`
	ID   string `json:"id"`
}

type State struct {
	Version string `json:"version"`

	CfgID           string           `json:"config_id"`
	AppID           string           `json:"app_id"`
	InstallerID     string           `json:"installer_id"`
	RunnerConfigID  string           `json:"runner_config_id"`
	SandboxConfigID string           `json:"sandbox_config_id"`
	InputConfigID   string           `json:"input_config_id"`
	Components      []ComponentState `json:"components"`
	Actions         []ActionState    `json:"actions"`
	Runbooks        []RunbookState   `json:"runbooks"`

	Result *Result `json:"result,omitempty"`
}

type SyncAPIErr struct {
	Resource string
	Err      error
}

type SyncErr struct {
	Resource    string
	Description string
}

type SyncInternalErr struct {
	Description string
	Err         error
}

type Syncer interface {
	// Sync performs the full synchronization operation, creating or updating
	// app configs, components, and their configurations.
	//
	// The context must contain org and account information set via cctx.SetOrgContext()
	// and cctx.SetAccountContext() before calling this method.
	//
	// Returns an error if the sync operation fails at any step.
	Sync(ctx context.Context) error

	// GetAppConfigID returns the ID of the app config that was created or updated
	// during the most recent sync operation.
	//
	// This should only be called after a successful Sync() operation.
	GetAppConfigID() string

	// GetComponentStateIds returns the IDs of all components that were synced
	// during the most recent sync operation.
	//
	// This should only be called after a successful Sync() operation.
	GetComponentStateIds() []string

	// GetActionStateIds returns the IDs of all actions that were synced
	// during the most recent sync operation.
	//
	// This should only be called after a successful Sync() operation.
	GetActionStateIds() []string

	// GetComponentsScheduled returns the components that need a build as a
	// result of the most recent sync — those whose config changed. It is empty
	// unless the sync was configured to own build scheduling.
	//
	// The set is persisted in State.Result so the CLI, which only sees the app
	// config it polls, can wait on those builds.
	// This should only be called after a successful Sync() operation.
	GetComponentsScheduled() []ComponentState

	// OrphanedComponents returns a map of component names to IDs for components
	// that existed in the previous config but are no longer in the current config.
	//
	// This allows consumers to notify users about removed components.
	// This should only be called after a successful Sync() operation.
	OrphanedComponents() map[string]string

	// OrphanedActions returns a map of action names to IDs for actions that
	// existed in the previous config but are no longer in the current config.
	//
	// This allows consumers to notify users about removed actions.
	// This should only be called after a successful Sync() operation.
	OrphanedActions() map[string]string

	// GetRunbookStateIds returns the IDs of all runbooks that were synced
	// during the most recent sync operation.
	//
	// This should only be called after a successful Sync() operation.
	GetRunbookStateIds() []string

	// OrphanedRunbooks returns a map of runbook names to IDs for runbooks that
	// existed in the previous config but are no longer in the current config.
	//
	// This allows consumers to notify users about removed runbooks.
	// This should only be called after a successful Sync() operation.
	OrphanedRunbooks() map[string]string

	// SyncInstall syncs a single install config to the database.
	// If the install does not exist, it is created. If it exists and has
	// changed, it is updated (inputs, labels, config, component toggles).
	SyncInstall(ctx context.Context, install *config.Install) (*InstallSyncResult, error)
}