Configuration System

Project-Scoped

Separate packaged defaults, project ownership, effective-value resolution, and subsystem-specific models.

Command.config/custy/config.toml

Quick Command

packaged template -> project file -> loader -> resolver -> consumer

TOMLConfigLoaderinitializationprecedence

Packaged Source

app/templates/config.toml

Project File

.config/custy/config.toml

Runtime Root

tool.custy

Shared Lifetime

One load per process

Overview

Custy separates the configuration shipped with the application from the copy owned by each initialized project. Runtime command resolvers consume values below [tool.custy], usually applying explicit CLI values first, then project settings, then a built-in fallback.

Configuration Lifecycle

Workflow Timeline

Package resources

app/templates/config.toml and changelog/changelog.j2 ship with the Python package.

completed

Build initialization plan

InitBuilder selects FileRegistry and DirRegistry entries for the requested mode.

completed

Create project resources

ScaffoldGenerator writes missing or approved replacement files beneath .config/custy.

completed

Load project TOML

ConfigLoader parses the file and exposes the mapping beneath tool.custy.

current

Resolve effective values

Command or subsystem resolvers select CLI, configuration, and fallback values.

pending

Apply behavior

Workflow, Git, logging, changelog, initialization, backup, cleanup, and path consumers use the resolved values.

pending

Runtime Loader Contract

Properties

Property	Type	Description	Default	Required
`get(*keys, default=...)`	Optional nested access	Returns the nested value or fallback when the path is absent or stops being a mapping.	-	No
`require(*keys)`	Required access	Raises ConfigurationError when the complete path has no value.	-	No
`get_section(*keys)`	Mapping access	Returns a dictionary for a subsystem table or an empty mapping.	-	No
`resolve(cli_value, config_keys, default)`	Precedence	Uses explicit CLI, then the project file, then the built-in default; optional flags alter false and required handling.	-	No
`get_config()`	Shared instance	Creates ConfigLoader lazily and reuses it for the current process.	-	No

Runtime namespace

toml

[tool.custy]

[tool.custy.cli.execution]
dry_run = false

[tool.custy.git]
default_remote = "origin"

Configuration Dependencies

Command Resolution

Typer option→CliArgs

Represent explicit or omitted user input.

CliArgs and ConfigLoader→command resolver

Choose an effective value for each supported property.

resolved dataclass→WorkflowEngineBuilder

Transport the command's supported values into WorkflowConfig.

WorkflowConfig→WorkflowEngine

Construct services and runtime behavior from immutable input intent.

Subsystem Resolution

ConfigLoader→ChangelogConfigResolver

Convert changelog tables into nested typed dataclasses and enums.

ConfigLoader→GitService

Resolve remote and tag-sorting policy when needed.

ConfigLoader→logging setup

Configure Rich console output and rotating file handlers.

ConfigLoader→path resolver

Resolve and validate project-source paths relative to the working directory.

Typed Changelog Configuration

The changelog subsystem does not pass arbitrary nested dictionaries throughout its processing stages. ChangelogConfigResolver loads core, pending-commit, cleaning, release, release behavior, links, render, breaking, scope mapping, type mapping, and advanced tables into one ChangelogConfig object. It also normalizes selected enum, mapping, and non-negative integer values.

This resolver creates its own ConfigLoader when the generator is constructed, while most command paths reuse the shared loader from get_config().

Import-Time and Process Boundaries

Missing project configuration produces an empty mapping and a warning; consumers may continue when they define fallbacks.
Invalid TOML raises ConfigurationError during loading.
The shared loader does not watch the filesystem; a new CLI process reloads edits.
app/constants/resolver.py resolves TARGET_PROJECT_SOURCE at import time and validates that the configured directory exists.
Relative filesystem settings are generally evaluated from the process's current working directory.
The project configuration should not store repository credentials or other secrets.

Continue

Related Commands

Commands commonly used together with this command.

Configuration Overview

Navigate every project-owned namespace and property.

Configuration File

Review ownership and initialization replacement rules.

Resolution and Status

Understand precedence and implementation status.

Extending Configuration

Carry a new setting through every active layer.

Overview​

Overview