Summary
DreamCLI already provides deterministic, first-match configuration discovery, but its default search is limited to the current working directory and one runtime-resolved user configuration directory. Expand the default discovery model to cover conventional project-local .config/ files, parent projects, platform-native user locations, and system-level fallbacks while keeping the core runtime-agnostic.
Current behavior
Default discovery currently supports:
- an explicit
--config <path> override, which skips discovery;
./.{appName}.{ext};./{appName}.config.{ext};{configDir}/{appName}/config.{ext};$XDG_CONFIG_HOME with ~/.config fallback on non-Windows platforms;%APPDATA% with %USERPROFILE%\\AppData\\Roaming fallback on Windows;- JSON out of the box and additional formats through registered loaders;
- caller-supplied search paths; and
- deterministic first-match behavior without merging.
Gaps
- No walk from a configurable starting directory up to the filesystem root.
- No project-level
<dir>/.config/{appName}.{ext} candidate.
- macOS is treated like other non-Windows platforms, so there is no
~/Library/Application Support/{appName}/config.{ext} fallback.
- No system-level candidate such as
/etc/{appName}/config.{ext} on Linux.
- Discovery is anchored only to
cwd; consumers such as editor integrations cannot anchor it to the directory of a specific file without constructing their own path list.
- No supported mechanism for extracting an app-specific section from a host configuration file. If this belongs in the generic framework, it should likely be an explicit extractor/source hook rather than a hard-coded package or file format.
Proposed behavior
- Preserve explicit
--config as the highest-priority exact-path override.
- Accept a discovery base directory, defaulting to
cwd.
- Starting at that directory, probe each directory up to the filesystem root, nearest first:
.{appName}.{ext}{appName}.config.{ext}.config/{appName}.{ext}
- If no project configuration is found, probe platform-appropriate user locations.
- If no user configuration is found, probe supported system locations.
- Keep first-match/no-merge semantics and document precedence across both locations and registered formats.
- Keep filesystem and platform behavior behind
RuntimeAdapter; src/core/ must remain runtime-agnostic.
The embedded-section/source-hook question can be split into a follow-up if it would make this change too broad.
Acceptance criteria
References
Summary
DreamCLI already provides deterministic, first-match configuration discovery, but its default search is limited to the current working directory and one runtime-resolved user configuration directory. Expand the default discovery model to cover conventional project-local
.config/files, parent projects, platform-native user locations, and system-level fallbacks while keeping the core runtime-agnostic.Current behavior
Default discovery currently supports:
--config <path>override, which skips discovery;./.{appName}.{ext};./{appName}.config.{ext};{configDir}/{appName}/config.{ext};$XDG_CONFIG_HOMEwith~/.configfallback on non-Windows platforms;%APPDATA%with%USERPROFILE%\\AppData\\Roamingfallback on Windows;Gaps
<dir>/.config/{appName}.{ext}candidate.~/Library/Application Support/{appName}/config.{ext}fallback./etc/{appName}/config.{ext}on Linux.cwd; consumers such as editor integrations cannot anchor it to the directory of a specific file without constructing their own path list.Proposed behavior
--configas the highest-priority exact-path override.cwd..{appName}.{ext}{appName}.config.{ext}.config/{appName}.{ext}RuntimeAdapter;src/core/must remain runtime-agnostic.The embedded-section/source-hook question can be split into a follow-up if it would make this change too broad.
Acceptance criteria
.config/{appName}.{ext}works at each project level.References