Skip to content

paths

paths

Platform-aware path resolution for sandbox directories.

Vendored from core.paths — zero internal dependencies. Provides the same XDG / FHS resolution logic so that terok-sandbox works identically whether embedded in terok or used standalone.

config_root()

Base directory for configuration.

Priority: TEROK_SANDBOX_CONFIG_DIR → /etc/terok/sandbox (root) → ~/.config/terok/sandbox.

Source code in src/terok_sandbox/paths.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def config_root() -> Path:
    """Base directory for configuration.

    Priority: ``TEROK_SANDBOX_CONFIG_DIR`` → ``/etc/terok/sandbox`` (root)
    → ``~/.config/terok/sandbox``.
    """
    env = os.getenv("TEROK_SANDBOX_CONFIG_DIR")
    if env:
        return Path(env).expanduser()
    if _is_root():
        return Path("/etc") / _UMBRELLA / _SUBDIR
    if _user_config_dir is not None:
        return Path(_user_config_dir(_UMBRELLA)) / _SUBDIR
    return Path.home() / ".config" / _UMBRELLA / _SUBDIR

state_root()

Writable state root (tasks, tokens, caches).

Priority: TEROK_SANDBOX_STATE_DIR → /var/lib/terok/sandbox (root) → ~/.local/share/terok/sandbox.

Source code in src/terok_sandbox/paths.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def state_root() -> Path:
    """Writable state root (tasks, tokens, caches).

    Priority: ``TEROK_SANDBOX_STATE_DIR`` → ``/var/lib/terok/sandbox`` (root)
    → ``~/.local/share/terok/sandbox``.
    """
    env = os.getenv("TEROK_SANDBOX_STATE_DIR")
    if env:
        return Path(env).expanduser()
    if _is_root():
        return Path("/var/lib") / _UMBRELLA / _SUBDIR
    if _user_data_dir is not None:
        return Path(_user_data_dir(_UMBRELLA)) / _SUBDIR
    xdg = os.getenv("XDG_DATA_HOME")
    if xdg:
        return Path(xdg) / _UMBRELLA / _SUBDIR
    return Path.home() / ".local" / "share" / _UMBRELLA / _SUBDIR

runtime_root()

Transient runtime directory (PID files, sockets).

Priority: TEROK_SANDBOX_RUNTIME_DIR → /run/terok/sandbox (root) → $XDG_RUNTIME_DIR/terok/sandbox → $XDG_STATE_HOME/terok/sandbox → ~/.local/state/terok/sandbox.

Source code in src/terok_sandbox/paths.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def runtime_root() -> Path:
    """Transient runtime directory (PID files, sockets).

    Priority: ``TEROK_SANDBOX_RUNTIME_DIR`` → ``/run/terok/sandbox`` (root) →
    ``$XDG_RUNTIME_DIR/terok/sandbox`` → ``$XDG_STATE_HOME/terok/sandbox`` →
    ``~/.local/state/terok/sandbox``.
    """
    env = os.getenv("TEROK_SANDBOX_RUNTIME_DIR")
    if env:
        return Path(env).expanduser()
    if _is_root():
        return Path("/run") / _UMBRELLA / _SUBDIR
    xdg_runtime = os.getenv("XDG_RUNTIME_DIR")
    if xdg_runtime:
        return Path(xdg_runtime) / _UMBRELLA / _SUBDIR
    xdg_state = os.getenv("XDG_STATE_HOME")
    if xdg_state:
        return Path(xdg_state) / _UMBRELLA / _SUBDIR
    return Path.home() / ".local" / "state" / _UMBRELLA / _SUBDIR

credentials_root()

Shared credentials directory used by all terok ecosystem packages.

Priority: TEROK_CREDENTIALS_DIR → /var/lib/terok/credentials (root) → XDG data dir.

Source code in src/terok_sandbox/paths.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def credentials_root() -> Path:
    """Shared credentials directory used by all terok ecosystem packages.

    Priority: ``TEROK_CREDENTIALS_DIR`` → ``/var/lib/terok/credentials`` (root)
    → XDG data dir.
    """
    env = os.getenv("TEROK_CREDENTIALS_DIR")
    if env:
        return Path(env).expanduser()
    if _is_root():
        return Path("/var/lib") / _UMBRELLA / _CRED_SUBDIR
    if _user_data_dir is not None:
        return Path(_user_data_dir(_UMBRELLA)) / _CRED_SUBDIR
    xdg = os.getenv("XDG_DATA_HOME")
    if xdg:
        return Path(xdg) / _UMBRELLA / _CRED_SUBDIR
    return Path.home() / ".local" / "share" / _UMBRELLA / _CRED_SUBDIR

umbrella_config_root()

Return the top-level terok config root (umbrella, not sandbox-scoped).

Used for cross-package paths like shield profiles that live under the shared ~/.config/terok/ umbrella rather than under any single package's config directory.

Source code in src/terok_sandbox/paths.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def umbrella_config_root() -> Path:
    """Return the top-level terok config root (umbrella, not sandbox-scoped).

    Used for cross-package paths like shield profiles that live under
    the shared ``~/.config/terok/`` umbrella rather than under any single
    package's config directory.
    """
    env = os.getenv("TEROK_CONFIG_DIR")
    if env:
        return Path(env).expanduser()
    if _is_root():
        return Path("/etc") / _UMBRELLA
    if _user_config_dir is not None:
        return Path(_user_config_dir(_UMBRELLA))
    return Path.home() / ".config" / _UMBRELLA