/ 
Developer-Dashboard-3.61
/ Developer::Dashboard::EnvLoader

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.

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_layers(skill_layers => \@layers) inside skill dispatch after the base skill env has been prepared and before executing hooks or the final skill command.

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_layers(skill_layers => \@skill_layers);

Load every participating skill env file from the base skill layer to the deepest active skill layer 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.