Module config

Expand description

Layered configuration schema, loading, and resolution. Configuration exists so the app can answer three questions consistently: what keys are legal, which source wins, and what file edits are allowed.

The mental model is:

crate::config::LoaderPipeline materializes source layers from files, environment, and in-memory overrides.
crate::config::ConfigResolver applies source precedence, scope precedence, interpolation, and schema adaptation.
crate::config::RuntimeConfig lowers the resolved config into the smaller runtime view used by the app and REPL.
crate::config::set_scoped_value_in_toml edits TOML-backed config files while preserving the same schema and scope rules used at runtime.

Quick starts:

In-memory or test-only config resolution:

use osp_cli::config::{ConfigLayer, LoaderPipeline, ResolveOptions, StaticLayerLoader};

let mut defaults = ConfigLayer::default();
defaults.set("profile.default", "default");
defaults.set("theme.name", "dracula");

let resolved = LoaderPipeline::new(StaticLayerLoader::new(defaults))
    .resolve(ResolveOptions::new().with_terminal("cli"))
    .unwrap();

assert_eq!(resolved.terminal(), Some("cli"));
assert_eq!(resolved.get_string("theme.name"), Some("dracula"));

Host-style bootstrap with runtime defaults plus standard path discovery:

use osp_cli::config::{
    ResolveOptions, RuntimeConfig, RuntimeConfigPaths, RuntimeDefaults,
    RuntimeLoadOptions, build_runtime_pipeline,
};

let defaults = RuntimeDefaults::from_process_env("dracula", "osp> ").to_layer();
let paths = RuntimeConfigPaths::discover();
let presentation = None;
let cli = None;
let session = None;

let resolved = build_runtime_pipeline(
    defaults,
    presentation,
    &paths,
    RuntimeLoadOptions::default(),
    cli,
    session,
)
.resolve(ResolveOptions::new().with_terminal("cli"))?;

let runtime = RuntimeConfig::from_resolved(&resolved);
assert_eq!(runtime.active_profile, resolved.active_profile());

On-disk config mutation:

use crate::config::set_scoped_value_in_toml and crate::config::unset_scoped_value_in_toml instead of editing TOML by hand
use crate::config::ConfigResolver::explain_key when the main question is “why did this value win?”

Broad-strokes flow:

files / env / session overrides
       │
       ▼ [ LoaderPipeline ]
   ConfigLayer values + scope metadata
       │
       ▼ [ ConfigResolver ]
   precedence + interpolation + type adaptation
       │
       ├── ResolvedConfig  (full provenance-aware map)
       ├── RuntimeConfig   (smaller runtime view used by the host)
       └── config explain  (why this winner won)

Read this module when you need to answer “where did this config value come from?”, “why did this value win?”, or “what writes are legal for this key?”.

Most callers should not be assembling bespoke config logic. The normal path is:

load layers through crate::config::LoaderPipeline
resolve once through crate::config::ConfigResolver
consume the result as crate::config::ResolvedConfig or crate::config::RuntimeConfig
for host-style startup, prefer crate::config::RuntimeDefaults, crate::config::RuntimeConfigPaths, and crate::config::build_runtime_pipeline over hand-rolled file/env discovery

The same discipline should hold for writes. File edits belong through the store helpers here so config set, runtime resolution, and config explain stay aligned. A hand-rolled file edit path almost always creates drift.

Contract:

source precedence and scope precedence are defined here, not in callers
schema validation and config-store editing should stay aligned
other modules should not hand-roll config merging or scope filtering

Structs§

BootstrapConfigExplain: Human-readable explanation of bootstrap resolution for a single key.
BootstrapKeySpec: Bootstrap metadata derived from a schema entry.
ChainedLoader: Loader that merges multiple loaders in the order they are added.
ConfigExplain: Human-readable explanation of runtime resolution for a single key.
ConfigLayer: Ordered collection of config entries from one source layer.
ConfigResolver: Resolves layered config input into the runtime view seen by the rest of the application.
ConfigSchema: Config schema used for validation, parsing, and runtime filtering.
EnvSecretsLoader: Loader for OSP_SECRET__... environment variables.
EnvVarLoader: Loader for OSP__... environment variables.
ExplainCandidate: Candidate entry considered while explaining a key.
ExplainInterpolation: Interpolation trace for a resolved string value.
ExplainInterpolationStep: Single placeholder expansion step captured by config explain.
ExplainLayer: Per-layer explanation for a resolved or bootstrap key.
LayerEntry: Single entry stored inside a config layer.
LoadedLayers: Materialized config layers grouped by source priority.
LoaderPipeline: Builder for the standard multi-source config loading pipeline.
ResolveOptions: Options that affect profile and terminal selection during resolution.
ResolvedConfig: Final resolved configuration view used at runtime.
ResolvedValue: Fully resolved value together with selection metadata.
RuntimeConfig: Minimal runtime-derived config that callers often need directly.
RuntimeConfigPaths: Discovered filesystem paths for runtime config inputs.
RuntimeDefaults: Built-in default values seeded before user-provided config is loaded.
RuntimeLoadOptions: Source-loading policy for runtime config bootstrap.
SchemaEntry: Schema definition for a single config key.
Scope: Scope selector used when storing or resolving config entries.
SecretValue: Secret config value that redacts its display and debug output.
SecretsTomlLoader: Loader for TOML secrets files whose values are marked secret.
StaticLayerLoader: Loader that returns a prebuilt config layer.
TomlEditResult: Result details for an in-place TOML edit operation.
TomlFileLoader: Loader for ordinary TOML config files.
TomlStoreEditOptions: Options that control how TOML-backed config edits are applied.

Enums§

ActiveProfileSource: Source used to determine the active profile.
BootstrapPhase: Bootstrap stage in which a key must be resolved.
BootstrapScopeRule: Scope restriction for bootstrap-only keys.
BootstrapValueRule: Additional validation rule for bootstrap values.
ConfigError: Error type returned by config parsing, validation, and resolution code.
ConfigSource: Origin of a resolved configuration value.
ConfigValue: Typed value stored in config layers and resolved output.
RuntimeBootstrapMode: Options that control which runtime config sources are included.
SchemaValueType: Schema-level type used for parsing and validation.
TomlSecretPermissions: Permission policy used for temp files created during atomic TOML writes.
TomlStoreEditMode: Whether a TOML store edit should be written to disk or treated as a dry run.

Constants§

DEFAULT_DEBUG_LEVEL: Default debug verbosity level.
DEFAULT_LOG_FILE_ENABLED: Default toggle for file logging.
DEFAULT_LOG_FILE_LEVEL: Default log level used for file logging.
DEFAULT_PROFILE_NAME: Default logical profile name used when no profile override is active.
DEFAULT_REPL_HISTORY_DEDUPE: Default toggle for deduplicating REPL history entries.
DEFAULT_REPL_HISTORY_ENABLED: Default toggle for persistent REPL history.
DEFAULT_REPL_HISTORY_MAX_ENTRIES: Default maximum number of REPL history entries to keep.
DEFAULT_REPL_HISTORY_MENU_ROWS: Default maximum number of rows shown in the REPL history search menu.
DEFAULT_REPL_HISTORY_PROFILE_SCOPED: Default toggle for profile-scoped REPL history storage.
DEFAULT_REPL_INTRO: Default REPL intro mode.
DEFAULT_SESSION_CACHE_MAX_RESULTS: Default upper bound for cached session results.
DEFAULT_UI_CHROME_FRAME: Default section chrome frame style.
DEFAULT_UI_CHROME_RULE_POLICY: Default rule-sharing policy for sibling section chrome.
DEFAULT_UI_COLUMN_WEIGHT: Default adaptive grid column weight.
DEFAULT_UI_GRID_PADDING: Default grid column padding.
DEFAULT_UI_GUIDE_DEFAULT_FORMAT: Default semantic guide-format preference.
DEFAULT_UI_INDENT: Default indentation width for nested output.
DEFAULT_UI_MARGIN: Default left margin for rendered output.
DEFAULT_UI_MEDIUM_LIST_MAX: Default threshold for rendering medium lists before expanding further.
DEFAULT_UI_MESSAGES_LAYOUT: Default grouped-message layout mode.
DEFAULT_UI_MREG_STACK_MIN_COL_WIDTH: Default minimum width before MREG output stacks columns.
DEFAULT_UI_MREG_STACK_OVERFLOW_RATIO: Default threshold for stacked MREG overflow behavior.
DEFAULT_UI_PRESENTATION: Default presentation preset name.
DEFAULT_UI_SHORT_LIST_MAX: Default threshold for rendering short lists compactly.
DEFAULT_UI_TABLE_BORDER: Default table border style.
DEFAULT_UI_TABLE_OVERFLOW: Default table overflow strategy.
DEFAULT_UI_WIDTH: Default render width hint.

Traits§

ConfigLoader: Loads a single config layer from some backing source.

Functions§

bootstrap_key_spec: Looks up bootstrap-time metadata for a canonical config key.
build_runtime_pipeline: Assembles the runtime loader precedence stack for CLI startup.
default_cache_root_dir: Resolves the default platform cache root from the current process environment.
default_config_root_dir: Resolves the default platform config root from the current process environment.
default_home_dir: Resolves the current user’s home directory from the running platform.
default_state_root_dir: Resolves the default platform state root from the current process environment.
is_alias_key: Reports whether key belongs to the alias.* namespace.
is_bootstrap_only_key: Reports whether key is consumed during bootstrap but not exposed as a normal runtime-resolved config key.
secret_file_mode: Returns the Unix permission bits for a secrets file.
set_scoped_value_in_toml: Writes one scoped key into a TOML-backed config store.
unset_scoped_value_in_toml: Removes one scoped key from a TOML-backed config store.
validate_bootstrap_value: Validates bootstrap-only value constraints for a key.
validate_key_scope: Validates that a key can be written in the provided scope.

Module config

Module config Copy item path

Structs§

Enums§

Constants§

Traits§

Functions§

Module config