Expand ref config CLI management commands

[lewisjared]

Description

Adds a fuller ref config management surface for onboarding and day-to-day configuration edits:

• ref config init creates a supported ref.toml template, with overwrite protection and --no-defaults support.
• ref config get, set, and unset support dotted scalar keys and environment override warnings.
• ref config validate validates the config file with text or JSON output and works even when the file is missing or malformed.
• ref config edit opens the active config file and reports post-edit validation issues.
• Updates configuration docs and getting-started onboarding to use ref config init / validate.

Validation performed:

• uv run pytest packages/climate-ref/tests/unit/cli/test_config.py -q
• uv run pytest packages/climate-ref/tests/unit/cli -q
• uv run pytest packages/climate-ref/tests/unit/test_config.py -q
• uv run ruff check
• uv run ruff format --check
• make mypy
• Manual smoke test for init, validate, set, get, and invalid-file validation.

Note: uv run mkdocs build currently fails on an existing notebook execution error in docs/how-to-guides/running-diagnostics-locally.py, unrelated to these changes.

Checklist

Please confirm that this pull request has done the following:

• Tests added
• Documentation added (where applicable)
• Changelog item added to changelog/

Summary by CodeRabbit

• New Features
  • Added ref config CLI commands to initialise, view (get), change (set), reset (unset), edit (edit), and validate configuration (validate).
  • Added validate output options, including JSON suitable for scripting.
• Bug Fixes
  • Improved handling when configuration is missing or invalid, so more CLI commands fail gracefully.
  • Added clearer diagnostics for unknown keys/invalid edits and better visibility of environment-variable overrides.
• Documentation
  • Updated configuration guides with the new CLI workflow and validation steps.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0e3a6ef2-5f10-43e3-9971-34ba9389f1b0

📥 Commits

Reviewing files that changed from the base of the PR and between 35b279c and 4d154e3.

📒 Files selected for processing (4)

• packages/climate-ref/src/climate_ref/cli/_config_access.py
• packages/climate-ref/src/climate_ref/cli/config.py
• packages/climate-ref/src/climate_ref/config.py
• packages/climate-ref/tests/unit/cli/test_config.py

🚧 Files skipped from review as they are similar to previous changes (4)

• packages/climate-ref/src/climate_ref/config.py
• packages/climate-ref/tests/unit/cli/test_config.py
• packages/climate-ref/src/climate_ref/cli/_config_access.py
• packages/climate-ref/src/climate_ref/cli/config.py

---

📝 Walkthrough

Walkthrough

Adds ref config init, get, set, unset, edit, and validate commands, with dotted-key config access, tolerant bootstrap loading, validation error collection, and updated tests and docs.

Changes

Config CLI Expansion

Layer / File(s)	Summary
Dotted-key access helpers packages/climate-ref/src/climate_ref/cli/_config_access.py	New module provides ConfigKeyError, resolve_key(), env_var_for(), coerce_value(), is_structured(), default_value(), and available_keys() for attrs-based config objects.
Config validation method packages/climate-ref/src/climate_ref/config.py	Adds Config.collect_validation_errors() to parse TOML, inject a missing ignore_datasets_file, and return transformed validation errors.
Tolerant config loading and CLIContext wiring packages/climate-ref/src/climate_ref/cli/__init__.py	Adds bootstrap-command detection, tolerant config loading, and new CLI context fields for the configuration directory and load error.
config subcommands and helpers packages/climate-ref/src/climate_ref/cli/config.py	Adds ValidationFormat, helper functions for config file handling and rendering, updates config list, and implements config init, get, set, unset, edit, and validate.
Tests and documentation packages/climate-ref/tests/unit/cli/test_config.py, docs/configuration.md, docs/getting-started/01-configure.md, changelog/768.feature.md	Adds unit coverage for the new config commands and access helpers, and updates configuration, getting-started, and changelog documentation.

Possibly related PRs

• Climate-REF/climate-ref#765: Both PRs touch packages/climate-ref/src/climate_ref/cli/config.py and adjust ref config list output handling, while this PR also adds the new ref config subcommands.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 19.23% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarises the main change to the ref config CLI.
Description check	✅ Passed	The description matches the template and includes the required summary plus tests, docs, and changelog checklist items.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cli-config-uplift

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 86.57534% with 49 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/climate-ref/src/climate_ref/cli/config.py	87.44%	19 Missing and 9 partials ⚠️
.../climate-ref/src/climate_ref/cli/_config_access.py	77.89%	12 Missing and 9 partials ⚠️

Flag	Coverage Δ
core	92.28% <86.57%> (-0.34%)	⬇️
providers	85.49% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ckages/climate-ref/src/climate_ref/cli/__init__.py	92.18% <100.00%> (-2.87%)	⬇️
packages/climate-ref/src/climate_ref/config.py	97.36% <100.00%> (-0.79%)	⬇️
.../climate-ref/src/climate_ref/cli/_config_access.py	77.89% <77.89%> (ø)
packages/climate-ref/src/climate_ref/cli/config.py	88.23% <87.44%> (-11.77%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (2)

packages/climate-ref/tests/unit/cli/test_config.py (1)

287-292: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Tighten the invalid-literal assertion.

pytest.raises(Exception) is too broad here and can hide unrelated failures in coerce_value(). Please verify the concrete exception type for bad literals and assert that instead.

docs/configuration.md (1)

64-90: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document ref config edit here as well.

This section covers the other config subcommands, but it skips edit, which is part of the new management surface. A short note would make the feature easier to discover.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3822eeec-c5af-4518-9db2-6da6d6418c7c

📥 Commits

Reviewing files that changed from the base of the PR and between d5dc936 and 35b279c.

📒 Files selected for processing (8)

• changelog/768.feature.md
• docs/configuration.md
• docs/getting-started/01-configure.md
• packages/climate-ref/src/climate_ref/cli/__init__.py
• packages/climate-ref/src/climate_ref/cli/_config_access.py
• packages/climate-ref/src/climate_ref/cli/config.py
• packages/climate-ref/src/climate_ref/config.py
• packages/climate-ref/tests/unit/cli/test_config.py