paths

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package paths provides centralized path resolution for scafctl using the XDG Base Directory Specification (https://specifications.freedesktop.org/basedir/latest/).

This package uses the github.com/adrg/xdg library to provide cross-platform XDG-compliant paths for configuration, data, cache, and state files.

Directory Types

The XDG specification defines several directory types:

  • Config: User-specific configuration files (XDG_CONFIG_HOME)
  • Data: User-specific data files (XDG_DATA_HOME)
  • Cache: User-specific non-essential cached data (XDG_CACHE_HOME)
  • State: User-specific state data like logs and history (XDG_STATE_HOME)

Platform Defaults

When XDG environment variables are not set, platform-specific defaults are used:

Linux:

  • Config: ~/.config/scafctl/
  • Data: ~/.local/share/scafctl/
  • Cache: ~/.cache/scafctl/
  • State: ~/.local/state/scafctl/

macOS:

  • Config: ~/.config/scafctl/
  • Data: ~/.local/share/scafctl/
  • Cache: ~/.cache/scafctl/
  • State: ~/.local/state/scafctl/

Windows:

  • Config: %LOCALAPPDATA%\scafctl\
  • Data: %LOCALAPPDATA%\scafctl\
  • Cache: %LOCALAPPDATA%\cache\scafctl\
  • State: %LOCALAPPDATA%\scafctl\

Environment Variable Overrides

All XDG environment variables are respected:

  • XDG_CONFIG_HOME
  • XDG_DATA_HOME
  • XDG_CACHE_HOME
  • XDG_STATE_HOME

Additionally, SCAFCTL_SECRETS_DIR can override the secrets directory location.

Index

Constants

View Source 
const (
	// ConfigFileName is the default config file name.
	ConfigFileName = "config.yaml"

	// SecretsDirName is the name of the secrets subdirectory.
	SecretsDirName = "secrets"

	// HTTPCacheDirName is the name of the HTTP cache subdirectory.
	HTTPCacheDirName = "http-cache"

	// CatalogDirName is the name of the catalog subdirectory.
	CatalogDirName = "catalog"

	// BuildCacheDirName is the name of the build cache subdirectory.
	BuildCacheDirName = "build-cache"

	// PluginCacheDirName is the name of the plugin cache subdirectory.
	PluginCacheDirName = "plugins"

	// ArtifactCacheDirName is the name of the artifact cache subdirectory.
	ArtifactCacheDirName = "artifact"
)

Variables

View Source 
var SupportedPlatforms = []string{"linux", "darwin", "macos", "windows"}

SupportedPlatforms lists the platforms accepted by IllustrativePaths.

Functions

func AppName 

func AppName() string

AppName returns the current application name used in XDG paths.

func ArtifactCacheDir added in v0.6.0 

func ArtifactCacheDir() string

ArtifactCacheDir returns the default path to the artifact cache directory. Used for caching downloaded catalog artifacts (solutions, providers, auth-handlers) with configurable TTL-based expiration.

Returns: $XDG_CACHE_HOME/scafctl/artifact/

Platform defaults:

  • Linux: ~/.cache/scafctl/artifact/
  • macOS: ~/.cache/scafctl/artifact/
  • Windows: %LOCALAPPDATA%\cache\scafctl\artifact\

func BuildCacheDir added in v0.3.0 

func BuildCacheDir() string

BuildCacheDir returns the default path to the build cache directory.

Returns: $XDG_CACHE_HOME/scafctl/build-cache/

Platform defaults:

  • Linux: ~/.cache/scafctl/build-cache/
  • macOS: ~/.cache/scafctl/build-cache/
  • Windows: %LOCALAPPDATA%\cache\scafctl\build-cache\

func CacheDir 

func CacheDir() string

CacheDir returns the path to the cache directory.

Returns: $XDG_CACHE_HOME/scafctl/

func CatalogDir 

func CatalogDir() string

CatalogDir returns the default path to the local catalog directory.

Returns: $XDG_DATA_HOME/scafctl/catalog/

Platform defaults:

  • Linux: ~/.local/share/scafctl/catalog/
  • macOS: ~/.local/share/scafctl/catalog/
  • Windows: %LOCALAPPDATA%\scafctl\catalog\

func ConfigDir 

func ConfigDir() string

ConfigDir returns the path to the config directory.

Returns: $XDG_CONFIG_HOME/scafctl/

func ConfigFile 

func ConfigFile() (string, error)

ConfigFile returns the path to the config file. Creates parent directories if they don't exist.

Returns: $XDG_CONFIG_HOME/scafctl/config.yaml

Platform defaults:

  • Linux: ~/.config/scafctl/config.yaml
  • macOS: ~/.config/scafctl/config.yaml
  • Windows: %LOCALAPPDATA%\scafctl\config.yaml

func DataDir 

func DataDir() string

DataDir returns the path to the data directory.

Returns: $XDG_DATA_HOME/scafctl/

func ExpandHome added in v0.6.0 

func ExpandHome(path string) (string, error)

ExpandHome expands a leading ~ in the given path to the user's home directory. If the path does not start with ~, it is returned unchanged.

func HTTPCacheDir 

func HTTPCacheDir() string

HTTPCacheDir returns the path to the HTTP cache directory.

Returns: $XDG_CACHE_HOME/scafctl/http-cache/

Platform defaults:

  • Linux: ~/.cache/scafctl/http-cache/
  • macOS: ~/.cache/scafctl/http-cache/
  • Windows: %LOCALAPPDATA%\cache\scafctl\http-cache\

func HomeDir added in v0.6.0 

func HomeDir() (string, error)

HomeDir returns the user's home directory path. This centralizes home directory resolution so callers outside pkg/paths do not call os.UserHomeDir directly.

func PluginCacheDir added in v0.3.0 

func PluginCacheDir() string

PluginCacheDir returns the default path to the plugin cache directory.

Returns: $XDG_CACHE_HOME/scafctl/plugins/

Platform defaults:

  • Linux: ~/.cache/scafctl/plugins/
  • macOS: ~/.cache/scafctl/plugins/
  • Windows: %LOCALAPPDATA%\cache\scafctl\plugins\

func RuntimeDir 

func RuntimeDir() string

RuntimeDir returns the path to the runtime directory. Used for sockets, pipes, and other runtime files.

Returns: $XDG_RUNTIME_DIR/scafctl/

func SearchConfigFile 

func SearchConfigFile() (string, error)

SearchConfigFile searches for the config file in XDG config paths. Does not create any directories.

Search order:

  1. $XDG_CONFIG_HOME/scafctl/config.yaml
  2. $XDG_CONFIG_DIRS/scafctl/config.yaml (each directory in order)

func SecretsDir 

func SecretsDir() (string, error)

SecretsDir returns the path to the secrets directory. Creates parent directories if they don't exist.

Returns: $XDG_DATA_HOME/scafctl/secrets/

Platform defaults:

  • Linux: ~/.local/share/scafctl/secrets/
  • macOS: ~/.local/share/scafctl/secrets/
  • Windows: %LOCALAPPDATA%\scafctl\secrets\

Note: Secrets are stored in DATA_HOME (not CONFIG_HOME) because they are user-specific data that should persist, not configuration settings.

func SecretsDirPath 

func SecretsDirPath() string

SecretsDirPath returns the secrets directory path without creating it.

Returns: $XDG_DATA_HOME/scafctl/secrets/

func SetAppName added in v0.8.0 

func SetAppName(name string)

SetAppName overrides the application name used in all XDG path functions. It must be called once, before any path functions are used (typically during CLI initialization). Subsequent calls are no-ops. An empty name is ignored.

func StateDir 

func StateDir() string

StateDir returns the path to the state directory. Used for logs, history, and session state.

Returns: $XDG_STATE_HOME/scafctl/

Platform defaults:

  • Linux: ~/.local/state/scafctl/
  • macOS: ~/.local/state/scafctl/
  • Windows: %LOCALAPPDATA%\scafctl\

Types

type PathInfo added in v0.5.0 

type PathInfo struct {
	Name        string `json:"name" yaml:"name"`
	Path        string `json:"path" yaml:"path"`
	Description string `json:"description" yaml:"description"`
	XDGVariable string `json:"xdgVariable,omitempty" yaml:"xdgVariable,omitempty"`
}

PathInfo represents information about a path used by scafctl.

func AllPaths added in v0.5.0 

func AllPaths() []PathInfo

AllPaths returns the actual resolved paths for the current platform.

func IllustrativePaths added in v0.5.0 

func IllustrativePaths(platform string) []PathInfo

IllustrativePaths returns illustrative default paths for a given platform. These are the XDG defaults when no environment variables are set.

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.