std/cli/paths

Application-scoped config, data, and cache directory helpers for CLI subcommand scripts.

The module is pure .harn; it reads environment variables through harness.env and never creates directories.

import {
  xdg_cache_home,
  xdg_config_home,
  xdg_data_home,
} from "std/cli/paths"

let config_dir = xdg_config_home("harn")
let data_dir = xdg_data_home("harn")
let cache_dir = xdg_cache_home("harn")

Surface

Function	Returns
xdg_config_home(app_name)	App-specific config directory
xdg_data_home(app_name)	App-specific data directory
xdg_cache_home(app_name)	App-specific cache directory

app_name must be one path segment. Empty names, dot segments, and names containing / or \ throw rather than allowing a caller to escape the app-specific directory.

Resolution

The helpers honor absolute XDG environment variables first, then fall back to platform conventions. Relative XDG values are ignored, matching the XDG Base Directory Specification. Fallbacks resolve the user home from harness.env.get("HOME"), then harness.env.get("USERPROFILE"); if neither is set to an absolute path, the helper throws.

Helper	XDG env	macOS fallback	Other fallback
xdg_config_home("harn")	$XDG_CONFIG_HOME/harn	~/Library/Application Support/harn	$HOME/.config/harn
xdg_data_home("harn")	$XDG_DATA_HOME/harn	~/Library/Application Support/harn	$HOME/.local/share/harn
xdg_cache_home("harn")	$XDG_CACHE_HOME/harn	~/Library/Caches/harn	$HOME/.cache/harn

The macOS locations follow Apple's user-domain guidance for application support files and discardable cache files.

These helpers only resolve paths. Call harness.fs.mkdir(path) when a script actually needs to create the directory.