projects

package
v2.0.1 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2026 License: BSD-3-Clause Imports: 42 Imported by: 0

Documentation

Overview

Package projects provides utilities for managing Docker Compose projects and their metadata.

Index

Constants

View Source 
const (
	// ArcaneIconLabel is the full reverse-DNS label key for fallback service-level icons.
	ArcaneIconLabel = "com.getarcaneapp.arcane.icon"
	// ArcaneIconLightLabel is the full reverse-DNS label key for light service-level icons.
	ArcaneIconLightLabel = "com.getarcaneapp.arcane.icon-light"
	// ArcaneIconDarkLabel is the full reverse-DNS label key for dark service-level icons.
	ArcaneIconDarkLabel = "com.getarcaneapp.arcane.icon-dark"
)
View Source 
const (
	GlobalEnvFileName    = ".env.global"
	EffectiveEnvFileName = ".env"
	GitSourceEnvFileName = ".env.git"
	OverrideEnvFileName  = "project.env"
)

Variables

View Source 
var ProjectFileCandidates = []string{
	"compose.yaml",
	"compose.yml",
	"docker-compose.yaml",
	"docker-compose.yml",
	"podman-compose.yaml",
	"podman-compose.yml",
	".env",
}

Functions

func BuildAdditiveOverrideEnvContent 

func BuildAdditiveOverrideEnvContent(gitContent, localContent string) (string, error)

BuildAdditiveOverrideEnvContent derives override content from a pre-git local .env file. Like other generated env helpers, the result is normalized and does not preserve comments or original key ordering.

func BuildEffectiveEnvContent 

func BuildEffectiveEnvContent(gitContent, overrideContent string) (string, error)

BuildEffectiveEnvContent merges git and override env sources into the effective .env content written to disk. The output is normalized: comments are dropped, keys are sorted, and values are rewritten with Arcane's formatter.

func BuildOverrideEnvContent 

func BuildOverrideEnvContent(gitContent, effectiveContent string) (string, error)

BuildOverrideEnvContent derives the editable override file from git-backed and effective env content. The generated output is normalized and does not retain comments or original key ordering.

func CleanupRemovedFiles 

func CleanupRemovedFiles(projectsRoot, projectPath string, oldFiles, newFiles []string) error

CleanupRemovedFiles deletes files that were in the old sync but are not in the new sync. It only removes files that were previously synced (tracked in oldFiles). Empty directories are removed after file deletion. This is a best-effort operation - errors are logged but don't cause failure.

func ComposeDown 

func ComposeDown(ctx context.Context, proj *types.Project, removeVolumes bool) error

func ComposeFileCandidates 

func ComposeFileCandidates() []string

ComposeFileCandidates returns the supported compose filenames in Arcane's detection order. A copy is returned so callers can't mutate package state.

func ComposeLogs 

func ComposeLogs(ctx context.Context, projectName string, out io.Writer, follow bool, tail string) error

func ComposePs 

func ComposePs(ctx context.Context, proj *types.Project, services []string, all bool) ([]api.ContainerSummary, error)

func ComposeRestart 

func ComposeRestart(ctx context.Context, proj *types.Project, services []string) error

func ComposeStop 

func ComposeStop(ctx context.Context, proj *types.Project, services []string) error

func ComposeUp 

func ComposeUp(ctx context.Context, proj *types.Project, services []string, removeOrphans bool, forceRecreate bool) error

func CopyDirectoryContents 

func CopyDirectoryContents(srcDir, destDir string) error

func CreateUniqueDir 

func CreateUniqueDir(projectsRoot, basePath, name string, perm os.FileMode) (path, folderName string, err error)

CreateUniqueDir creates a unique directory within the allowed projectsRoot. It validates that the created directory is always within projectsRoot.

func DefaultSwarmStackEnvTemplate 

func DefaultSwarmStackEnvTemplate() string

func DefaultSwarmStackTemplate 

func DefaultSwarmStackTemplate() string

func DetectComposeFile 

func DetectComposeFile(dir string) (string, error)

func DirectorySyncContentsChanged 

func DirectorySyncContentsChanged(projectPath string, syncFiles []SyncFile, oldSyncedFiles []string, composeFileName string) (bool, error)

func EnsureDefaultTemplates 

func EnsureDefaultTemplates(ctx context.Context, configuredTemplatesDir string) error

func EnsureEnvFile 

func EnsureEnvFile(projectsRoot, dirPath string) error

func EnsureTemplateDir 

func EnsureTemplateDir(ctx context.Context, templatesDir, base string) (dir, composePath, envPath string, err error)

func GetProjectsDirectory 

func GetProjectsDirectory(ctx context.Context, projectsDir string) (string, error)

func GetTemplatesDirectory 

func GetTemplatesDirectory(ctx context.Context, templatesDir string) (string, error)

func HasComposeRootKeysInFile 

func HasComposeRootKeysInFile(path string) (bool, error)

func ImageRefsFromComposeConfigs 

func ImageRefsFromComposeConfigs(services []composetypes.ServiceConfig) []string

ImageRefsFromComposeConfigs returns unique, non-empty image references from compose service configs while preserving first-seen order.

func ImageRefsFromComposeServices 

func ImageRefsFromComposeServices(services composetypes.Services) []string

ImageRefsFromComposeServices returns unique, non-empty image references from a compose service map in stable service-name order.

func ImageRefsFromRuntimeServices 

func ImageRefsFromRuntimeServices(services []projecttypes.RuntimeService) []string

ImageRefsFromRuntimeServices returns unique, non-empty image references from runtime service DTOs while preserving first-seen order.

func ImportedComposeDescription 

func ImportedComposeDescription(dir string) string

func IsBinaryProjectFileContent 

func IsBinaryProjectFileContent(content []byte) bool

func IsProjectDirectoryEntry 

func IsProjectDirectoryEntry(entry os.DirEntry, path string, followSymlinks bool) bool

IsProjectDirectoryEntry reports whether a directory entry should be treated as a project directory. Regular directories are always accepted. Symlinked directories are accepted only when enabled.

func IsProjectDirectoryPath 

func IsProjectDirectoryPath(path string, followSymlinks bool) (bool, error)

IsProjectDirectoryPath reports whether an existing path should be treated as a project directory. Regular directories are always accepted. Symlinked directories are accepted only when enabled.

func IsProjectFile 

func IsProjectFile(filename string) bool

IsProjectFile reports whether filename is a known project file or a plausible custom YAML filename worth watching for compose discovery.

func IsSafeSubdirectory 

func IsSafeSubdirectory(baseDir, subdir string) bool

IsSafeSubdirectory returns true if subdir is a subdirectory of baseDir (absolute, normalized)

func IsWindowsDrivePath 

func IsWindowsDrivePath(path string) bool

IsWindowsDrivePath returns true if the path looks like a Windows drive path (e.g., "C:/path")

func ListGlobalComposeContainers 

func ListGlobalComposeContainers(ctx context.Context) ([]container.Summary, error)

func LoadComposeProject 

func LoadComposeProject(ctx context.Context, composeFile, projectName, projectsDirectory string, autoInjectEnv bool, pathMapper *PathMapper) (*composetypes.Project, error)

func LoadComposeProjectFromDir 

func LoadComposeProjectFromDir(ctx context.Context, dir, projectName, projectsDirectory string, autoInjectEnv bool, pathMapper *PathMapper) (*composetypes.Project, string, error)

func LoadComposeProjectLenient 

func LoadComposeProjectLenient(ctx context.Context, composeFile, projectName, projectsDirectory string, autoInjectEnv bool, pathMapper *PathMapper) (*composetypes.Project, error)

LoadComposeProjectLenient loads a compose project tolerating undefined variables. Instead of substituting undefined ${VAR} references with an empty string (which produces invalid volume/bind specs like ":/path"), it replaces them with a placeholder value so structural validation can succeed. This is useful during GitSync validation where a .env file may not yet exist.

func ParseEnvContent 

func ParseEnvContent(content string) []env.Variable

ParseEnvContent parses environment variables from .env file content

func ReadFolderComposeTemplate 

func ReadFolderComposeTemplate(baseDir, folder string) (string, *string, string, bool, error)

func ReadProjectDirectoryFiles 

func ReadProjectDirectoryFiles(projectPath string, shownFiles map[string]bool, maxDepth int, skipDirectories string) ([]project.IncludeFile, error)

func ReadProjectFiles 

func ReadProjectFiles(projectPath, composePath string) (composeContent, envContent string, err error)

func RemoveProjectFile 

func RemoveProjectFile(projectsRoot, dirPath, fileName string) error

func RemoveStaleComposeFiles 

func RemoveStaleComposeFiles(projectPath, composeFileName string, syncedFiles []string) error

func ResolveConfiguredContainerDirectory 

func ResolveConfiguredContainerDirectory(configuredPath, defaultPath string) string

func ResolveDirectoryIdentityInternal 

func ResolveDirectoryIdentityInternal(path string) (string, error)

func ResolveRelativeProjectPaths 

func ResolveRelativeProjectPaths(project *composetypes.Project, workdir string)

func SanitizeProjectName 

func SanitizeProjectName(name string) string

func SaveOrUpdateProjectFiles 

func SaveOrUpdateProjectFiles(projectsRoot, projectPath, composeContent string, envContent *string) error

func Slugify 

func Slugify(in string) string

func ValidateIncludePathForWrite 

func ValidateIncludePathForWrite(projectDir, includePath string) (string, error)

ValidateIncludePathForWrite ensures the include path is safe for write operations Returns the validated absolute path to prevent recomputation after validation Only allows writing within the project directory

func WriteComposeFile 

func WriteComposeFile(projectsRoot, dirPath, content string) error

WriteComposeFile writes a compose file to the specified directory. It detects existing compose file names (docker-compose.yml, compose.yaml, etc.) and uses the existing name if found, otherwise defaults to compose.yaml projectsRoot is the allowed root directory to prevent path traversal attacks

func WriteEnvFile 

func WriteEnvFile(projectsRoot, dirPath, content string) error

WriteEnvFile writes a .env file to the specified directory projectsRoot is the allowed root directory to prevent path traversal attacks

func WriteFileWithPerm 

func WriteFileWithPerm(filePath, content string, perm os.FileMode) error

WriteFileWithPerm is a generic file writer with custom permissions

func WriteIncludeFile 

func WriteIncludeFile(projectDir, includePath, content string) error

WriteIncludeFile writes content to an include file path

func WriteProjectFile 

func WriteProjectFile(projectsRoot, dirPath, fileName, content string) error

func WriteProjectFiles 

func WriteProjectFiles(projectsRoot, dirPath, composeContent string, envContent *string) error

WriteProjectFiles writes both compose and env files to a project directory. An empty .env file is always created to prevent compose-go from failing when the compose file references env_file: .env projectsRoot is the allowed root directory to prevent path traversal attacks

func WriteSyncedDirectory 

func WriteSyncedDirectory(projectsRoot, projectPath string, files []SyncFile) ([]string, error)

WriteSyncedDirectory writes multiple files to a project directory. It validates all paths are within the project directory and creates subdirectories as needed. Returns the list of written file paths.

func WriteTemplateFile 

func WriteTemplateFile(filePath, content string) error

WriteTemplateFile writes a template file (like .compose.template or .env.template)

func WriteTemplateFiles 

func WriteTemplateFiles(composePath, envPath, composeContent, envContent string) (*string, error)

Types

type ArcaneComposeMetadata 

type ArcaneComposeMetadata struct {
	// ProjectIcon contains fallback, light, and dark icon values for the project.
	ProjectIcon IconSet
	// ProjectURLS are additional URLs related to the project (e.g., documentation, homepage).
	ProjectURLS []string
	// ServiceIconSets maps service names to their fallback, light, and dark icon values.
	ServiceIconSets map[string]IconSet
}

ArcaneComposeMetadata represents Arcane-specific configuration extracted from a Compose file.

func ParseArcaneComposeMetadata 

func ParseArcaneComposeMetadata(ctx context.Context, composeFilePath, projectsDirectory string, autoInjectEnv bool) (ArcaneComposeMetadata, error)

ParseArcaneComposeMetadata reads a Docker Compose file and extracts Arcane-specific metadata. When projectsDirectory is set, Arcane's project env loading is used so .env.global is available.

func ParseArcaneComposeMetadataWithEnv 

func ParseArcaneComposeMetadataWithEnv(ctx context.Context, composeFilePath string, envMap map[string]string) (ArcaneComposeMetadata, error)

ParseArcaneComposeMetadataWithEnv reads a Docker Compose file and extracts Arcane-specific metadata using a provided environment.

type Client 

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

func NewClient 

func NewClient(ctx context.Context) (*Client, error)

func (*Client) Close 

func (c *Client) Close() error

type DiscoveredProjectDir 

type DiscoveredProjectDir struct {
	DirName string
	Path    string
}

func DiscoverProjectDirectories 

func DiscoverProjectDirectories(root string, followSymlinks bool, maxDepth int) ([]DiscoveredProjectDir, error)

type EnvLoader 

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

func NewEnvLoader 

func NewEnvLoader(projectsDir, workdir string, autoInjectEnv bool) *EnvLoader

func (*EnvLoader) LoadEnvironment 

func (l *EnvLoader) LoadEnvironment(ctx context.Context) (envMap EnvMap, injectionVars EnvMap, err error)

LoadEnvironment loads and merges environment variables from all sources: 1. Process environment 2. Global .env.global file (from projects directory) 3. Project-specific .env file (from workdir)

type EnvMap 

type EnvMap = map[string]string

func ParseProjectEnvContent 

func ParseProjectEnvContent(content string, contextEnv EnvMap) (EnvMap, error)

ParseProjectEnvContent parses project .env content from a string with variable expansion.

func ParseProjectEnvFile 

func ParseProjectEnvFile(path string, contextEnv EnvMap) (EnvMap, error)

ParseProjectEnvFile parses a project .env file with variable expansion using the provided context map (e.g. process env). Returns nil without error when the file does not exist. Only the specified file is read — global env files are intentionally not loaded here.

type IconSet 

type IconSet = iconcatalog.IconSet

func FindArcaneIconSet 

func FindArcaneIconSet(labels any) IconSet

FindArcaneIconSet attempts to locate Arcane icon labels within service labels. It supports both map[string]string and []string label formats.

type IncludeFile 

type IncludeFile struct {
	Path         string `json:"path"`
	RelativePath string `json:"relative_path"`
	Content      string `json:"content"`
}

func ParseIncludes 

func ParseIncludes(composeFilePath string, envMap EnvMap, includeContent bool) ([]IncludeFile, error)

ParseIncludes reads a compose file and extracts all include directives. envMap is used to expand variables (e.g., ${VAR}) in include paths.

func ParseIncludesFromContent 

func ParseIncludesFromContent(composeFilePath string, content []byte, envMap EnvMap, includeContent bool) ([]IncludeFile, error)

ParseIncludesFromContent extracts include directives from compose content using composeFilePath as the base path.

type PathMapper 

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

PathMapper handles translation between container and host paths

func NewPathMapper 

func NewPathMapper(containerDir, hostDir string) *PathMapper

NewPathMapper creates a new path mapper

func (*PathMapper) ContainerToHost 

func (pm *PathMapper) ContainerToHost(containerPath string) (string, error)

ContainerToHost translates a container path to host path

func (*PathMapper) IsNonMatchingMount 

func (pm *PathMapper) IsNonMatchingMount() bool

func (*PathMapper) TranslateVolumeSources 

func (pm *PathMapper) TranslateVolumeSources(project *composetypes.Project) error

TranslateVolumeSources translates all bind mount sources in a compose project

type ProgressWriterKey 

type ProgressWriterKey struct{}

ProgressWriterKey can be set on a context to enable JSON-line progress updates. The value must be an io.Writer (typically the HTTP response writer).

type ProjectEnvMode 

type ProjectEnvMode string
const (
	ProjectEnvModeDirect   ProjectEnvMode = "direct"
	ProjectEnvModeOverride ProjectEnvMode = "override"
)

type ProjectEnvState 

type ProjectEnvState struct {
	Mode             ProjectEnvMode
	EditableFileName string
	EditableContent  string
	EffectiveContent string
	DirectContent    string
	HasEffective     bool
	GitContent       string
	HasGitSource     bool
	OverrideContent  string
	HasOverride      bool
}

func ReadProjectEnvState 

func ReadProjectEnvState(projectPath string) (ProjectEnvState, error)

type SyncFile 

type SyncFile struct {
	RelativePath string // Path relative to the project directory
	Content      []byte
}

SyncFile represents a file to be written during directory sync

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.