NAME
Developer::Dashboard::PathRegistry - logical directory registry
SYNOPSIS
my $paths = Developer::Dashboard::PathRegistry->new(home => $ENV{HOME});
my $root = $paths->current_project_root;DESCRIPTION
This module provides the central logical directory registry used across the dashboard runtime, shell helpers, and background services.
METHODS
new
Construct the path registry.
resolve_dir, resolve_any, locate_projects, locate_dirs_under, current_project_root, project_root_for
Resolve and discover project-related directories.
current_working_directory, cwd
Report the effective working directory: the explicit constructor cwd when one was supplied, otherwise a live in-process getcwd lookup that follows later chdir calls without forking an external pwd process (undef when the directory is unavailable). cwd is the public compatibility alias consumed by the file registry.
validated_path_segments
Package function that splits one untrusted relative path into its separator-delimited segments and rejects any shape able to escape the directory it will be joined onto: missing or empty paths, NUL or other control bytes, backslash separators, absolute paths, Windows drive prefixes, and empty, current-directory, or parent-directory segments. Returns the validated segment list (segment count in scalar context) or an empty list (undef in scalar context) on rejection. skill_layers requires exactly one validated segment for a skill name, and the skill dispatcher and web layer reuse this guard for every skill-namespaced route, ajax, and static asset path.
runtime_root, cache_root, home_runtime_root, home_cache_root
Report the layered runtime directories. runtime_root and cache_root follow the deepest discovered layer, which is the write target for layered runtime state. home_runtime_root and home_cache_root stay pinned to the home layer, for per-user artifacts that a fixed external consumer reads from one well-known path - the generated shell-startup caches a login profile dot-sources are the motivating case, because a project-layer copy of those would be a cache no refresh ever rewrites.
PURPOSE
This module is the authoritative path model for the runtime. It discovers the layered runtime roots from home to the current project, resolves standard runtime directories, manages named path aliases, and performs project and directory searches such as the regex-based narrowing used by cdr.
WHY IT EXISTS
It exists because DD-OOP-LAYERS is a cross-runtime contract, not a convenience helper. One path registry has to own how home and project runtimes participate, which layer is writable, and how named paths and directory searches behave on top of that model.
WHEN TO USE
Use this file when changing layered runtime discovery, the writable runtime root, named alias behavior, project lookup, or directory-search semantics used by shell navigation helpers.
HOW TO USE
Construct it with the current home and cwd context, then ask it for runtime roots, named paths, or search results. Avoid rebuilding runtime path math elsewhere; other modules should consume this registry instead.
WHAT USES IT
It is used throughout the runtime by file, config, page, collector, prompt, shell-bootstrap, and CLI path logic, plus the tests that verify layered runtime behavior.
EXAMPLES
Example 1:
perl -Ilib -MDeveloper::Dashboard::PathRegistry -e 1Do a direct compile-and-load check against the module from a source checkout.
Example 2:
prove -lv t/07-core-units.t t/21-refactor-coverage.tRun the focused regression tests that most directly exercise this module's behavior.
Example 3:
HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr tRecheck the module under the repository coverage gate rather than relying on a load-only probe.
Example 4:
prove -lr tPut any module-level change back through the entire repository suite before release.