NAME
Developer::Dashboard::EnvLoader - load layered dashboard env files
SYNOPSIS
use Developer::Dashboard::EnvLoader;
Developer::Dashboard::EnvLoader->load_runtime_layers(paths => $paths);
Developer::Dashboard::EnvLoader->load_skill_layers(skill_layers => \@skill_layers);DESCRIPTION
This module loads plain .env files and executable .env.pl files from the dashboard runtime layer chain and, when a skill command is running, from the participating skill roots as well.
For skill execution the effective order is home runtime files, skill-root files, skill cli/ files, then deeper project runtime files. Thus a skill can override a same-named home default, while a closer project runtime layer still has final precedence among file-based values. Values explicitly inherited from the invoking process have higher precedence than every file layer; files may set unset keys but cannot replace those caller values. The switchboard carries only the names of those inherited keys to helper processes, never their values.
Plain .env files load before .env.pl at every participating directory. The plain-file parser accepts KEY=VALUE lines, ignores blank lines, whole line # comments, whole line // comments, and /* ... */ block comments that can span multiple lines. It expands a leading ~ to $ENV{HOME}, bare $NAME references, ${NAME:-default} expressions, and ${Namespace::function():-default} expressions where the function resolves to one static Perl subroutine. Missing functions, malformed keys, malformed lines, and unterminated block comments fail explicitly instead of being ignored.
PURPOSE
This module is the ordered env-file loader for the dashboard switchboard and skill dispatcher. Read it when you need to understand which env files participate, in what order they load, and how failures become explicit.
WHY IT EXISTS
It exists because env loading is now part of the DD-OOP-LAYERS contract. Keeping the file discovery, parsing, failure handling, and audit recording in one module keeps the public switchboard thin and makes the precedence rules testable.
WHEN TO USE
Use this module when wiring env loading into a runtime entrypoint, when changing the ordered env precedence rules, or when investigating why a command saw a particular env value.
HOW TO USE
Call load_runtime_layers(paths => $paths) from the thin dashboard entrypoint after the command token is known and before helper or custom-command execution. Call load_skill_runtime_layers(paths => $paths, skill_layers => \@layers) inside skill dispatch before executing hooks or the final skill command; it applies the home/skill/project precedence order. Both entrypoints preserve caller-exported values above the files they load.
WHAT USES IT
It is used by bin/dashboard, by the skill dispatcher, by custom commands and hooks that inherit the loaded environment, and by tests that verify precedence and failure behavior.
EXAMPLES
Example 1:
Developer::Dashboard::EnvLoader->load_runtime_layers(paths => $paths);Load every participating plain-directory and runtime-layer env file from root to leaf for one dashboard process.
Example 2:
Developer::Dashboard::EnvLoader->load_skill_runtime_layers(
paths => $paths,
skill_layers => \@skill_layers,
);Load home defaults, participating skill root and CLI env files, and deeper project overrides in precedence order before executing a skill command.
Example 3:
Developer::Dashboard::EnvLoader->load_files(files => \@files);Apply an explicit ordered file list when you already know the participating env files.
Example 4:
ROOT_CACHE=~/cache
API_URL=https://example.test
TOKEN=${ACCESS_TOKEN:-anonymous}
GREETING=${Local::Env::Helper::message():-hello}Show the supported plain .env expansion forms for home-directory expansion, env lookups, defaults, and static Perl functions.