Add config layering system with user and project defaults

[httpdss]

Issue

Fixes #98

Description

This PR implements a comprehensive config layering system that allows users to set defaults at multiple levels, reducing CLI verbosity and providing a flexible configuration hierarchy.

Key Features

1. Multi-layer Configuration Support

   • Built-in defaults (hard-coded baseline values)
   • User config at ~/.config/struct/config.yaml for personal global defaults
   • Project config via .struct.yaml or --config-file flag
   • CLI arguments (highest priority)

2. Config Precedence Order

   CLI args > Project config > User config > Built-in defaults
   

3. New structkit config print Command

   • Display the effective configuration after all layers are merged
   • Support for both YAML (default) and JSON output formats
   • Shows which config sources were loaded

Implementation Details

New Files:

• structkit/config.py - Core config layering logic with functions for loading, merging, and applying configurations
• structkit/commands/config.py - Config command with print subcommand
• tests/test_config_layering.py - Comprehensive tests for config layering (15 tests)
• tests/test_config_command.py - Tests for config command (6 tests)
• examples/config-layering/ - Complete example with README and sample configs

Modified Files:

• structkit/main.py - Integrated layered config loading into main CLI flow
• docs/configuration.md - Added comprehensive documentation for config layering

Supported Config Options

All of the following can be set in config files:

• structures_path - Path to custom structure definitions
• source - Named source for structure definitions
• input_store - Path to the input store file
• file_strategy - Strategy for handling existing files
• backup - Path to backup folder
• global_system_prompt - Global system prompt for OpenAI
• non_interactive - Run in non-interactive mode
• output - Output mode (file/console)
• log - Logging level
• log_file - Path to log file

Example Usage

Create a user config:

mkdir -p ~/.config/struct
cat > ~/.config/struct/config.yaml << 'EOF'
file_strategy: backup
input_store: ~/.cache/structkit/input.json
structures_path: ~/my-structures
log: WARNING
EOF

View effective config:

structkit config print

Override with CLI args:

structkit config print --log DEBUG -c my-project-config.yaml

See examples/config-layering/ for more comprehensive examples and use cases.

Checklist

• I have read the contributing guidelines.
• My code follows the code style of this project.
• I have performed a self-review of my own code.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have updated the documentation accordingly.

Screenshots (if applicable)

Example output of structkit config print:

file_strategy: backup
input_store: /home/user/.cache/structkit/input.json
log: WARNING
non_interactive: false
output: file
structures_path: /home/user/my-structures

Configuration sources:
  1. Built-in defaults: always loaded
  2. User config: /home/user/.config/struct/config.yaml (exists)
  3. Project config: none specified
  4. CLI arguments: highest priority

Additional Comments

• All 272 existing tests pass, including 21 new tests for this feature
• Pre-commit hooks pass (trailing-whitespace, end-of-file-fixer, check-yaml)
• Backward compatible with existing config loading via --config-file
• The implementation respects the CLI style and patterns used throughout the codebase
• Does NOT include hook-safety work from PR Add hook safety controls for structkit #190 / issue Pre/Post hooks safety controls #100 as instructed
• Includes comprehensive examples in examples/config-layering/ with user and project config templates