project

type BuildOptions struct {
	Services []string
	Provider string
	Push     *bool
	Load     *bool
}

type ComposeCache[T any] interface {
	Get(projectID, fingerprint string) (T, bool)
	Set(projectID, fingerprint, projectPath, projectsDirectory, composePath string, composeFiles, envFiles []string, value T) error
	Invalidate(projectID string)
}

type ComposeCommands struct {
	Stop   func(context.Context, *composetypes.Project, []string) error
	Up     func(context.Context, *composetypes.Project, []string, bool, bool, bool, map[string]registry.AuthConfig, time.Duration) error
	Create func(context.Context, *composetypes.Project, []string, map[string]registry.AuthConfig) error
}

type ComposeContentOptions struct {
	ProjectName     string
	ComposeContent  string
	OverrideContent string
	EnvContent      string
	WorkingDir      string
	PathMapper      VolumeSourcePathMapper
}

type ComposeCoordinator interface {
	Deploy(ctx context.Context, request ComposeDeployment) (*composetypes.Project, error)
	UpdateServices(ctx context.Context, request ComposeServiceUpdate) error
	PullServices(ctx context.Context, model *composetypes.Project, services []string, operations ComposeImageOperations, progress io.Writer) error
	EnsureImagesPresent(ctx context.Context, model *composetypes.Project, progress io.Writer, operations ComposeImageOperations) error
	BuildServices(ctx context.Context, projectID string, model *composetypes.Project, options BuildOptions, progress io.Writer, operations ComposeImageOperations) error
}

type ComposeDependencies struct {
	EnvFiles []string
}

type ComposeDeployment struct {
	ProjectID         string
	ProjectPath       string
	Options           *DeployOptions
	DefaultPullPolicy string
	GitOpsManaged     bool
	WaitTimeout       time.Duration
	AuthConfigs       map[string]registry.AuthConfig
	Progress          io.Writer
	PreDeploy         func(context.Context) error
	Load              func(context.Context) (*composetypes.Project, error)
	ResolveImages     func(context.Context) (ComposeImageOperations, error)
	Recover           func(context.Context)
}

type ComposeImageOperations struct {
	Exists        func(context.Context, string) (bool, error)
	LastTagged    func(context.Context, string) (time.Time, error)
	Pull          func(context.Context, string, io.Writer) error
	Build         func(context.Context, buildtypes.BuildRequest, io.Writer, string) error
	BuildProvider string
}

type ComposeServiceUpdate struct {
	Project  *composetypes.Project
	Services []string
	// Dependents are recreated alongside Services because they share a member's
	// namespace or volumes; they are never pulled. StoppedDependents are
	// recreated without being started so an operator's stop is preserved.
	Dependents            []string
	StoppedDependents     []string
	Images                ComposeImageOperations
	Progress              io.Writer
	AuthConfigs           map[string]registry.AuthConfig
	WaitTimeout           time.Duration
	RestoreBeforeMutation func(context.Context)
	Recover               func(context.Context)
}

type ConfigurationError struct {
	// Code identifies the configuration problem.
	//
	// Required: true
	Code string `json:"code"`

	// Path is the offending file path.
	//
	// Required: true
	Path string `json:"path"`

	// UID is the effective user id of the Arcane runtime.
	//
	// Required: true
	UID int `json:"uid"`

	// GID is the effective group id of the Arcane runtime.
	//
	// Required: true
	GID int `json:"gid"`

	// BlocksOperations indicates whether the problem prevents project operations.
	//
	// Required: true
	BlocksOperations bool `json:"blocksOperations"`
}

type CreateProject struct {
	// Name of the project.
	//
	// Required: true
	Name string `json:"name" binding:"required"`

	// ComposeContent is the Docker Compose file content.
	//
	// Required: true
	ComposeContent string `json:"composeContent" binding:"required"`

	// EnvContent is the environment file content.
	//
	// Required: false
	EnvContent *string `json:"envContent,omitempty"`

	// Tags are UI-managed tags to attach to the new project.
	//
	// Required: false
	Tags []string `json:"tags,omitempty"`

	// TagColors maps normalized UI-managed tag names to their display colors.
	//
	// Required: false
	TagColors map[string]TagColor `json:"tagColors,omitempty"`
}

type CreateProjectWorkspaceManifest struct {
	FileChanges []WorkspaceFileChange `json:"fileChanges" binding:"required" maxItems:"500"`
}

type CreateReponse struct {
	// ID is the unique identifier of the project.
	//
	// Required: true
	ID string `json:"id"`

	// Name of the project.
	//
	// Required: true
	Name string `json:"name"`

	// DirName is the directory name where the project is stored.
	//
	// Required: false
	DirName string `json:"dirName,omitempty"`

	// RelativePath is the path to the project directory relative to the configured projects root.
	//
	// Required: false
	RelativePath string `json:"relativePath,omitempty"`

	// Path is the file path to the project.
	//
	// Required: true
	Path string `json:"path"`

	// Status is the current status of the project.
	//
	// Required: true
	Status string `json:"status"`

	// StatusReason provides additional information about the status.
	//
	// Required: false
	StatusReason *string `json:"statusReason,omitempty"`

	// ServiceCount is the total number of services in the project.
	//
	// Required: true
	ServiceCount int `json:"serviceCount"`

	// RunningCount is the number of running services in the project.
	//
	// Required: true
	RunningCount int `json:"runningCount"`

	// GitOpsManagedBy is the ID of the GitOps sync managing this project (if any).
	//
	// Required: false
	GitOpsManagedBy *string `json:"gitOpsManagedBy,omitempty"`

	// IsArchived indicates whether the project is hidden from the default project list.
	//
	// Required: true
	IsArchived bool `json:"isArchived"`

	// ArchivedAt is the date and time when the project was archived.
	//
	// Required: false
	ArchivedAt *time.Time `json:"archivedAt,omitempty"`

	// CreatedAt is the date and time when the project was created.
	//
	// Required: true
	CreatedAt string `json:"createdAt"`

	// UpdatedAt is the date and time when the project was last updated.
	//
	// Required: true
	UpdatedAt string `json:"updatedAt"`

	// ActivityID is the activity created by the project action.
	//
	// Required: false
	ActivityID *string `json:"activityId,omitempty"`

	// Tags are the effective UI and Compose tags for the project.
	Tags []Tag `json:"tags"`
}

type DeployOptions struct {
	// PullPolicy overrides the image pull policy used during deploy.
	//
	// Required: false
	PullPolicy string `json:"pullPolicy,omitempty" binding:"omitempty,oneof=missing always never"`

	// ForceRecreate forces compose to recreate containers even when unchanged.
	//
	// Required: false
	ForceRecreate bool `json:"forceRecreate,omitempty"`

	// RemoveOrphans removes containers for services not defined in the compose file.
	//
	// Required: false
	RemoveOrphans bool `json:"removeOrphans,omitempty"`

	// RecreateVolumes allows compose to recreate volumes whose configuration
	// diverged from the compose file. The volume's data is lost.
	//
	// Required: false
	RecreateVolumes bool `json:"recreateVolumes,omitempty"`
}

type Destroy struct {
	// RemoveFiles indicates if project files should be removed. Defaults to true when omitted.
	// When false and the project is stored under the projects directory, files are renamed
	// to a hidden .arcane-trash-* directory so filesystem discovery does not re-import them.
	//
	// Required: false
	RemoveFiles *bool `json:"removeFiles,omitempty"`

	// RemoveVolumes indicates if project volumes should be removed.
	//
	// Required: false
	RemoveVolumes bool `json:"removeVolumes,omitempty"`
}

type Details struct {
	// Tags are the effective UI and Compose tags for the project.
	Tags []Tag `json:"tags"`

	// StatusReason provides additional information about the status.
	//
	// Required: false
	StatusReason *string `json:"statusReason,omitempty"`

	// ActivityID is the activity created by the project action.
	//
	// Required: false
	ActivityID *string `json:"activityId,omitempty"`

	// LastSyncCommit is the last commit synced from Git (if GitOps managed).
	//
	// Required: false
	LastSyncCommit *string `json:"lastSyncCommit,omitempty"`

	// GitOpsManagedBy is the ID of the GitOps sync managing this project (if any).
	//
	// Required: false
	GitOpsManagedBy *string `json:"gitOpsManagedBy,omitempty"`

	// UpdateInfo contains aggregated image update status for the project.
	//
	// Required: false
	UpdateInfo *UpdateInfo `json:"updateInfo,omitempty"`

	// ArchivedAt is the date and time when the project was archived.
	//
	// Required: false
	ArchivedAt *time.Time `json:"archivedAt,omitempty"`

	// Status is the current status of the project.
	//
	// Required: true
	Status string `json:"status"`

	// DirName is the directory name where the project is stored.
	//
	// Required: false
	DirName string `json:"dirName,omitempty"`

	// ComposeContent is the Docker Compose file content.
	//
	// Required: false
	ComposeContent string `json:"composeContent,omitempty"`

	// ComposeFileName is the detected compose file name for the project.
	//
	// Required: false
	ComposeFileName string `json:"composeFileName,omitempty"`

	// ComposeFiles is the ordered project-relative list of compose files selected
	// by a COMPOSE_FILE entry in the project's .env. It is populated only when
	// COMPOSE_FILE selects more than one file; otherwise it is empty and
	// ComposeFileName is authoritative.
	//
	// Required: false
	ComposeFiles []string `json:"composeFiles,omitempty"`

	// EnvContent is the environment file content.
	//
	// Required: false
	EnvContent string `json:"envContent,omitempty"`

	// OverrideContent is the Docker Compose override file content, when present.
	//
	// Required: false
	OverrideContent string `json:"overrideContent,omitempty"`

	// OverrideFileName is the detected compose override file name, when present.
	//
	// Required: false
	OverrideFileName string `json:"overrideFileName,omitempty"`

	// Name of the project.
	//
	// Required: true
	Name string `json:"name"`

	// GitRepositoryURL is the URL of the Git repository (if GitOps managed).
	//
	// Required: false
	GitRepositoryURL string `json:"gitRepositoryURL,omitempty"`

	// IconLightURL is the optional light stack icon URL for dark themes.
	//
	// Required: false
	IconLightURL string `json:"iconLightUrl,omitempty"`

	// RelativePath is the path to the project directory relative to the configured projects root.
	//
	// Required: false
	RelativePath string `json:"relativePath,omitempty"`
	// ID is the unique identifier of the project.
	//
	// Required: true
	ID string `json:"id"`

	// IconDarkURL is the optional dark stack icon URL for light themes.
	//
	// Required: false
	IconDarkURL string `json:"iconDarkUrl,omitempty"`

	// Path is the file path to the project.
	//
	// Required: true
	Path string `json:"path"`

	// UpdatedAt is the date and time when the project was last updated.
	//
	// Required: true
	UpdatedAt string `json:"updatedAt"`

	// CreatedAt is the date and time when the project was created.
	//
	// Required: true
	CreatedAt string `json:"createdAt"`

	// RuntimeServices contains live container status information for each service.
	//
	// Required: false
	RuntimeServices []RuntimeService `json:"runtimeServices,omitempty"`

	// Services is a list of services defined in the Docker Compose file.
	//
	// Required: false
	Services []composetypes.ServiceConfig `json:"services,omitempty"`

	// URLs are optional custom stack URLs from compose metadata.
	//
	// Required: false
	URLs []string `json:"urls,omitempty"`

	// IncludeFiles is a list of included files in the project.
	//
	// Required: false
	IncludeFiles []IncludeFile `json:"includeFiles,omitempty"`

	// RunningCount is the number of running services in the project.
	//
	// Required: true
	RunningCount int `json:"runningCount"`

	// ServiceCount is the total number of services in the project.
	//
	// Required: true
	ServiceCount int `json:"serviceCount"`

	// IsDiscovered indicates whether this row was derived from runtime Compose labels instead of an Arcane project record.
	//
	// Required: false
	IsDiscovered bool `json:"isDiscovered,omitempty"`

	// IsArchived indicates whether the project is hidden from the default project list.
	//
	// Required: true
	IsArchived bool `json:"isArchived"`

	// HasBuildDirective indicates whether any Compose service defines a build directive.
	//
	// Required: false
	HasBuildDirective bool `json:"hasBuildDirective,omitempty"`

	// RedeployDisabled indicates whether redeploy actions are disabled for this project.
	//
	// Required: false
	RedeployDisabled bool `json:"redeployDisabled,omitempty"`

	// ConfigurationError reports a filesystem-level configuration problem detected for this project.
	//
	// Required: false
	ConfigurationError *ConfigurationError `json:"configurationError,omitempty"`
}

type DetailsOptions struct {
	IncludeComposeContent  bool
	IncludeEnvState        bool
	IncludeIncludeFiles    bool
	IncludeServiceConfigs  bool
	IncludeRuntimeServices bool
	IncludeUpdateInfo      bool
}

type ImagePullRequest struct {
	// Credentials is a list of container registry credentials for pulling images.
	//
	// Required: false
	Credentials []containerregistry.Credential `json:"credentials,omitempty"`
}

type IncludeFile struct {
	// Path is the absolute path to the include file.
	//
	// Required: true
	Path string `json:"path"`

	// RelativePath is the path to the include file relative to the project.
	//
	// Required: true
	RelativePath string `json:"relativePath"`

	// Content is the file content.
	//
	// Required: false
	Content string `json:"content,omitempty"`
}

type RenameJournal struct {
	ProjectID  string                      `json:"projectId"`
	OldName    string                      `json:"oldName"`
	NewName    string                      `json:"newName"`
	OldPath    string                      `json:"oldPath"`
	NewPath    string                      `json:"newPath"`
	OldDirName *string                     `json:"oldDirName,omitempty"`
	NewDirName string                      `json:"newDirName"`
	Phase      string                      `json:"phase"`
	Volumes    []volumetypes.JournalVolume `json:"volumes,omitempty"`
	UpdatedAt  time.Time                   `json:"updatedAt"`
}

type RenameRecoveryOperations struct {
	Docker               func(context.Context, bool) (*client.Client, error)
	WriteJournal         func(context.Context, *RenameJournal, string) error
	ClearJournal         func(context.Context, string) error
	ClearRollbackCleanup func(context.Context, string) error
	RestoreState         func(context.Context, *RenameJournal) error
	WriteRollbackCleanup func(context.Context, *RenameJournal) error
}

type RenameRollbackCleanup struct {
	ProjectID string                      `json:"projectId"`
	OldName   string                      `json:"oldName"`
	OldPath   string                      `json:"oldPath"`
	NewName   string                      `json:"newName"`
	NewPath   string                      `json:"newPath"`
	Volumes   []volumetypes.JournalVolume `json:"volumes,omitempty"`
	UpdatedAt time.Time                   `json:"updatedAt"`
}

type RuntimeService struct {
	// ContainerLabels carries runtime policy inputs for server-side update aggregation.
	ContainerLabels map[string]string `json:"-"`

	// ImageID is the runtime image ID used to match image-level update checks.
	ImageID string `json:"-"`

	// Name is the service name from the compose file.
	//
	// Required: true
	Name string `json:"name"`

	// Image is the Docker image used by the service.
	//
	// Required: true
	Image string `json:"image"`

	// Status is the current status of the container (running, stopped, etc.).
	//
	// Required: true
	Status string `json:"status"`

	// ContainerID is the Docker container ID.
	//
	// Required: false
	ContainerID string `json:"containerId,omitempty"`

	// ContainerName is the Docker container name.
	//
	// Required: false
	ContainerName string `json:"containerName,omitempty"`

	// Ports is a list of port mappings for the container.
	//
	// Required: false
	Ports []string `json:"ports,omitempty"`

	// Health is the health status of the container.
	//
	// Required: false
	Health *string `json:"health,omitempty"`

	// IconLightURL is an optional light icon URL for dark themes.
	//
	// Required: false
	IconLightURL string `json:"iconLightUrl,omitempty"`

	// IconDarkURL is an optional dark icon URL for light themes.
	//
	// Required: false
	IconDarkURL string `json:"iconDarkUrl,omitempty"`

	// ServiceConfig is the configuration of the service from the compose file.
	//
	// Required: false
	ServiceConfig *composetypes.ServiceConfig `json:"serviceConfig,omitempty"`

	// RedeployDisabled indicates whether redeploy actions are disabled for this runtime service.
	//
	// Required: false
	RedeployDisabled bool `json:"redeployDisabled,omitempty"`
}

type ServiceUpdateInfo struct {
	ImageRef   string                 `json:"imageRef"`
	UpdateInfo *imagetypes.UpdateInfo `json:"updateInfo,omitempty"`
}

type StatusCounts struct {
	// RunningProjects is the number of running projects.
	//
	// Required: true
	RunningProjects int `json:"runningProjects"`

	// StoppedProjects is the number of stopped projects.
	//
	// Required: true
	StoppedProjects int `json:"stoppedProjects"`

	// TotalProjects is the total number of projects.
	//
	// Required: true
	TotalProjects int `json:"totalProjects"`

	// ArchivedProjects is the number of archived projects.
	//
	// Required: true
	ArchivedProjects int `json:"archivedProjects"`
}

type Tag struct {
	Name    string      `json:"name"`
	Color   TagColor    `json:"color"`
	Sources []TagSource `json:"sources"`
}

type TagColor string

type TagOption struct {
	Name  string   `json:"name"`
	Color TagColor `json:"color"`
}

type TagSource string

type UpdateInfo struct {
	ServiceUpdates map[string]ServiceUpdateInfo `json:"serviceUpdates,omitempty"`
	// Status is the aggregate update status for the project.
	//
	// Values: has_update | up_to_date | not_pulled | unknown | error
	// Required: true
	Status string `json:"status"`

	// HasUpdate indicates whether any project image has an available update.
	//
	// Required: true
	HasUpdate bool `json:"hasUpdate"`

	// ImageCount is the total number of unique checkable image references in the project.
	//
	// Required: true
	ImageCount int `json:"imageCount"`

	// CheckedImageCount is the number of project image references with persisted update-check results.
	//
	// Required: true
	CheckedImageCount int `json:"checkedImageCount"`

	// ImagesWithUpdates is the number of project image references with available updates.
	//
	// Required: true
	ImagesWithUpdates int `json:"imagesWithUpdates"`

	// ImagesNotPulled is the number of project image references not present locally.
	//
	// Required: true
	ImagesNotPulled int `json:"imagesNotPulled"`

	// ErrorCount is the number of project image references whose latest check failed.
	//
	// Required: true
	ErrorCount int `json:"errorCount"`

	// ErrorMessage is the first available error message from the latest project image checks.
	//
	// Required: false
	ErrorMessage *string `json:"errorMessage,omitempty"`

	// ImageRefs is the list of unique image references detected for the project.
	//
	// Required: false
	ImageRefs []string `json:"imageRefs,omitempty"`

	// UpdatedImageRefs is the subset of project image references with available updates.
	//
	// Required: false
	UpdatedImageRefs []string `json:"updatedImageRefs,omitempty"`

	// NotPulledImageRefs is the subset of project image references not present locally.
	//
	// Required: false
	NotPulledImageRefs []string `json:"notPulledImageRefs,omitempty"`

	// UpdateInfoByRef contains the latest persisted per-image update result keyed by image reference.
	//
	// Required: false
	UpdateInfoByRef map[string]imagetypes.UpdateInfo `json:"updateInfoByRef,omitempty"`

	// LastCheckedAt is the latest successful or failed image update check time for this project.
	//
	// Required: false
	LastCheckedAt *time.Time `json:"lastCheckedAt,omitempty"`
}

type UpdateProject struct {
	// Name of the project.
	//
	// Required: false
	Name *string `json:"name,omitzero"`

	// ComposeContent is the Docker Compose file content.
	//
	// Required: false
	ComposeContent *string `json:"composeContent,omitzero"`

	// EnvContent is the environment file content.
	//
	// Required: false
	EnvContent *string `json:"envContent,omitzero"`

	// OverrideContent is the Docker Compose override file content merged on top of
	// the base compose file at deploy. Its tri-state controls the on-disk override:
	// nil leaves any existing override untouched (it still participates in
	// validation of a base-compose edit); a non-nil blank string deletes the
	// override file; a non-nil non-empty string writes it.
	//
	// Required: false
	OverrideContent *string `json:"overrideContent,omitzero"`
}

type UpdateTag struct {
	Name     string   `json:"name"`
	Attached bool     `json:"attached"`
	Color    TagColor `json:"color,omitempty"`
}

type UpdateTagResponse struct {
	Tags       []Tag   `json:"tags"`
	ActivityID *string `json:"activityId,omitempty"`
}

type VolumeSourcePathMapper interface {
	TranslateVolumeSources(project *composetypes.Project, translateFileResources bool) error
	// ContainerToHost translates a single container-side path to its host-side
	// equivalent. mapped is false when the path is outside every mounted
	// directory, in which case the path is returned unchanged; a path inside an
	// identity mount is also unchanged but reports mapped as true. Needed to
	// re-resolve relative Compose paths that escape the projects mount, where
	// prefix translation has nothing to match.
	ContainerToHost(containerPath string) (hostPath string, mapped bool, err error)
}

type WorkspaceFileChange = workspacetypes.FileChange

type WorkspaceUpdateManifest struct {
	FileTreeRevision string                `json:"fileTreeRevision" binding:"required"`
	FileChanges      []WorkspaceFileChange `json:"fileChanges" binding:"required" minItems:"1" maxItems:"500"`
}