feat(_internal[settings]) Add TOML-based user settings

why: Allow users to set a default config_style in settings.toml so they
don't need to pass --style on every command invocation.
what:
- Add settings.toml loader using tomllib (3.11+) with tomli fallback
- Add VcspullSettings dataclass with config_style field
- Add resolve_style() for CLI-flag-overrides-settings priority chain
- Add tomli>=1.0 conditional dependency for Python <3.11
- Add 11 tests covering TOML parsing, fallbacks, and resolution

Author: tony

pyproject.toml

@@ -55,7 +55,8 @@ homepage = "https://vcspull.git-pull.com"
 dependencies = [
   "libvcs~=0.39.0",
   "colorama>=0.3.9",
-  "PyYAML>=6.0"
+  "PyYAML>=6.0",
+  "tomli>=1.0; python_version < '3.11'"
 ]
 
 [project-urls]

src/vcspull/_internal/settings.py

@@ -0,0 +1,131 @@
+"""User settings for vcspull.
+
+Reads optional ``settings.toml`` from the vcspull config directory
+(see :func:`vcspull.util.get_config_dir`) and provides typed access to
+user preferences.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+
+from vcspull.types import ConfigStyle
+from vcspull.util import get_config_dir
+
+try:
+    import tomllib  # type: ignore[import-not-found]
+except ModuleNotFoundError:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+log = logging.getLogger(__name__)
+
+SETTINGS_FILENAME = "settings.toml"
+
+
+@dataclasses.dataclass
+class VcspullSettings:
+    """Parsed vcspull user settings.
+
+    Examples
+    --------
+    >>> VcspullSettings()
+    VcspullSettings(config_style=<ConfigStyle.STANDARD: 'standard'>)
+    """
+
+    config_style: ConfigStyle = ConfigStyle.STANDARD
+
+
+def load_settings() -> VcspullSettings:
+    """Load settings from the vcspull config directory.
+
+    Returns the default settings when no ``settings.toml`` exists or
+    when parsing fails.
+
+    Returns
+    -------
+    VcspullSettings
+        Parsed settings (or defaults on error).
+
+    Examples
+    --------
+    >>> settings = load_settings()
+    >>> isinstance(settings, VcspullSettings)
+    True
+    """
+    config_dir = get_config_dir()
+    settings_path = config_dir / SETTINGS_FILENAME
+
+    if not settings_path.is_file():
+        return VcspullSettings()
+
+    try:
+        with settings_path.open("rb") as f:
+            data = tomllib.load(f)
+    except Exception:
+        log.warning(
+            "Failed to parse %s; using default settings",
+            settings_path,
+            exc_info=True,
+        )
+        return VcspullSettings()
+
+    style_value = data.get("config_style")
+    if style_value is not None:
+        try:
+            style = ConfigStyle(style_value)
+        except ValueError:
+            log.warning(
+                "Unknown config_style '%s' in %s; using default 'standard'",
+                style_value,
+                settings_path,
+            )
+            style = ConfigStyle.STANDARD
+    else:
+        style = ConfigStyle.STANDARD
+
+    return VcspullSettings(config_style=style)
+
+
+def resolve_style(
+    cli_style: str | None,
+    settings: VcspullSettings | None = None,
+) -> ConfigStyle:
+    """Resolve the effective config style from CLI flag and user settings.
+
+    The CLI ``--style`` flag overrides the ``settings.toml`` value, which
+    itself overrides the built-in default (``standard``).
+
+    Parameters
+    ----------
+    cli_style : str | None
+        Value from ``--style`` CLI flag, or ``None`` if not specified.
+    settings : VcspullSettings | None
+        Pre-loaded settings; loaded lazily when ``None``.
+
+    Returns
+    -------
+    ConfigStyle
+        The resolved config style.
+
+    Examples
+    --------
+    >>> from vcspull.types import ConfigStyle
+    >>> resolve_style("concise")
+    <ConfigStyle.CONCISE: 'concise'>
+    >>> resolve_style(None, VcspullSettings(config_style=ConfigStyle.VERBOSE))
+    <ConfigStyle.VERBOSE: 'verbose'>
+    >>> resolve_style(None)  # doctest: +ELLIPSIS
+    <ConfigStyle.STANDARD: 'standard'>
+    """
+    if cli_style is not None:
+        try:
+            return ConfigStyle(cli_style)
+        except ValueError:
+            log.warning("Unknown --style '%s'; falling back to 'standard'", cli_style)
+            return ConfigStyle.STANDARD
+
+    if settings is None:
+        settings = load_settings()
+
+    return settings.config_style

tests/_internal/test_settings.py

@@ -0,0 +1,136 @@
+"""Tests for vcspull._internal.settings."""
+
+from __future__ import annotations
+
+import pathlib
+import typing as t
+
+import pytest
+
+from vcspull._internal.settings import (
+    SETTINGS_FILENAME,
+    VcspullSettings,
+    load_settings,
+    resolve_style,
+)
+from vcspull.types import ConfigStyle
+
+
+class SettingsFixture(t.NamedTuple):
+    """Fixture for settings loading test cases."""
+
+    test_id: str
+    toml_content: str | None  # None = no file
+    expected_style: ConfigStyle
+
+
+SETTINGS_FIXTURES: list[SettingsFixture] = [
+    SettingsFixture(
+        "no-file-uses-default",
+        None,
+        ConfigStyle.STANDARD,
+    ),
+    SettingsFixture(
+        "explicit-standard",
+        'config_style = "standard"\n',
+        ConfigStyle.STANDARD,
+    ),
+    SettingsFixture(
+        "explicit-concise",
+        'config_style = "concise"\n',
+        ConfigStyle.CONCISE,
+    ),
+    SettingsFixture(
+        "explicit-verbose",
+        'config_style = "verbose"\n',
+        ConfigStyle.VERBOSE,
+    ),
+    SettingsFixture(
+        "invalid-value-falls-back",
+        'config_style = "invalid"\n',
+        ConfigStyle.STANDARD,
+    ),
+    SettingsFixture(
+        "empty-file-uses-default",
+        "",
+        ConfigStyle.STANDARD,
+    ),
+    SettingsFixture(
+        "no-style-key-uses-default",
+        'other_key = "value"\n',
+        ConfigStyle.STANDARD,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(SettingsFixture._fields),
+    SETTINGS_FIXTURES,
+    ids=[f.test_id for f in SETTINGS_FIXTURES],
+)
+def test_load_settings(
+    test_id: str,
+    toml_content: str | None,
+    expected_style: ConfigStyle,
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """load_settings should parse TOML correctly or fall back to defaults."""
+    del test_id
+
+    config_dir = tmp_path / "vcspull"
+    config_dir.mkdir()
+
+    if toml_content is not None:
+        settings_file = config_dir / SETTINGS_FILENAME
+        settings_file.write_text(toml_content, encoding="utf-8")
+
+    monkeypatch.setattr("vcspull._internal.settings.get_config_dir", lambda: config_dir)
+
+    settings = load_settings()
+    assert settings.config_style == expected_style
+
+
+def test_load_settings_invalid_toml(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Malformed TOML should fall back to defaults without crashing."""
+    config_dir = tmp_path / "vcspull"
+    config_dir.mkdir()
+    settings_file = config_dir / SETTINGS_FILENAME
+    settings_file.write_text("this is not valid toml [[[", encoding="utf-8")
+
+    monkeypatch.setattr("vcspull._internal.settings.get_config_dir", lambda: config_dir)
+
+    settings = load_settings()
+    assert settings.config_style == ConfigStyle.STANDARD
+
+
+def test_resolve_style_cli_overrides_settings() -> None:
+    """CLI --style flag should take precedence over settings."""
+    settings = VcspullSettings(config_style=ConfigStyle.VERBOSE)
+    assert resolve_style("concise", settings=settings) == ConfigStyle.CONCISE
+
+
+def test_resolve_style_uses_settings_when_cli_none() -> None:
+    """When no CLI flag, settings value should be used."""
+    settings = VcspullSettings(config_style=ConfigStyle.VERBOSE)
+    assert resolve_style(None, settings=settings) == ConfigStyle.VERBOSE
+
+
+def test_resolve_style_default_when_both_none(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """When no CLI flag and no settings file, default to standard."""
+    config_dir = tmp_path / "vcspull"
+    config_dir.mkdir()
+    monkeypatch.setattr("vcspull._internal.settings.get_config_dir", lambda: config_dir)
+
+    assert resolve_style(None) == ConfigStyle.STANDARD
+
+
+def test_resolve_style_invalid_cli_value() -> None:
+    """Invalid CLI value should fall back to standard."""
+    assert resolve_style("nonexistent") == ConfigStyle.STANDARD