fix(config[symlink-format]) prefer target suffix for symlinked configs

why: The first symlink-path fix preserved visible config names, which fixed
extensionless dotfile targets but broke alias paths and mismatched symlinks.
An explicit alias like `vcspull-config -> .vcspull.yaml` was rejected for
having no suffix, and a home link like `.vcspull.yaml -> vcspull.json` could
be rewritten with YAML because later format checks only saw the visible path.
what:
- Add shared config-format detection that prefers a symlink target's
  supported suffix and otherwise falls back to the visible path suffix
- Use that helper for config reads, duplicate-aware YAML loading, save
  dispatch, ordered-item saves, and import config-path validation
- Add regressions for target-format precedence, extensionless alias paths,
  and end-to-end JSON writes through a symlinked home config

Author: tony

src/vcspull/_internal/config_reader.py

@@ -8,6 +8,56 @@
 import yaml
 
 FormatLiteral = t.Literal["json", "yaml"]
+_SUPPORTED_CONFIG_SUFFIXES: dict[str, FormatLiteral] = {
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+}
+
+
+def config_format_from_path(path: pathlib.Path) -> FormatLiteral | None:
+    """Return config format inferred from a path or symlink target.
+
+    The visible path remains the config identity, but symlinks may point
+    at a differently named target. When the target advertises a supported
+    config suffix, prefer that format; otherwise fall back to the visible
+    path suffix.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Path to inspect.
+
+    Returns
+    -------
+    FormatLiteral | None
+        ``"json"`` or ``"yaml"`` when a supported suffix is found,
+        otherwise ``None``.
+
+    Examples
+    --------
+    >>> config_format_from_path(pathlib.Path("config.yaml"))
+    'yaml'
+    >>> import tempfile
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     root = pathlib.Path(tmp)
+    ...     target = root / "config.json"
+    ...     _ = target.write_text("{}", encoding="utf-8")
+    ...     link = root / ".vcspull.yaml"
+    ...     link.symlink_to(target)
+    ...     config_format_from_path(link)
+    'json'
+    """
+    path_format = _SUPPORTED_CONFIG_SUFFIXES.get(path.suffix.lower())
+
+    target_format: FormatLiteral | None = None
+    if path.is_symlink():
+        resolved = path.resolve(strict=False)
+        target_format = _SUPPORTED_CONFIG_SUFFIXES.get(resolved.suffix.lower())
+
+    return target_format or path_format
+
+
 RawConfigData: t.TypeAlias = dict[t.Any, t.Any]
 
 
@@ -117,11 +167,8 @@ def _from_file(cls, path: pathlib.Path) -> dict[str, t.Any]:
         # Revisit once the new ``vcspull add`` flow lands so both commands share
         # the same duplication safeguards.
 
-        if path.suffix in {".yaml", ".yml"}:
-            fmt: FormatLiteral = "yaml"
-        elif path.suffix == ".json":
-            fmt = "json"
-        else:
+        fmt = config_format_from_path(path)
+        if fmt is None:
             msg = f"{path.suffix} not supported in {path}"
             raise NotImplementedError(msg)
 
@@ -335,7 +382,7 @@ def _load_from_path(
         cls,
         path: pathlib.Path,
     ) -> tuple[dict[str, t.Any], dict[str, list[t.Any]], list[tuple[str, t.Any]]]:
-        if path.suffix.lower() in {".yaml", ".yml"}:
+        if config_format_from_path(path) == "yaml":
             content = path.read_text(encoding="utf-8")
             return cls._load_yaml_with_duplicates(content)
 

src/vcspull/cli/add.py

@@ -13,7 +13,10 @@
 
 from colorama import Fore, Style
 
-from vcspull._internal.config_reader import DuplicateAwareConfigReader
+from vcspull._internal.config_reader import (
+    DuplicateAwareConfigReader,
+    config_format_from_path,
+)
 from vcspull._internal.private_path import PrivatePath
 from vcspull.config import (
     canonicalize_workspace_path,
@@ -341,7 +344,7 @@ def _save_ordered_items(
     >>> "~/code/" in data
     True
     """
-    if config_file_path.suffix.lower() == ".json":
+    if config_format_from_path(config_file_path) == "json":
         save_config_json(
             config_file_path,
             _collapse_ordered_items_to_dict(ordered_items),

src/vcspull/cli/import_cmd/_common.py

@@ -14,7 +14,10 @@
 import sys
 import typing as t
 
-from vcspull._internal.config_reader import DuplicateAwareConfigReader
+from vcspull._internal.config_reader import (
+    DuplicateAwareConfigReader,
+    config_format_from_path,
+)
 from vcspull._internal.private_path import PrivatePath
 from vcspull._internal.remotes import (
     AuthenticationError,
@@ -565,7 +568,7 @@ def _resolve_config_file(config_path_str: str | None) -> pathlib.Path:
     """
     if config_path_str:
         path = normalize_config_file_path(pathlib.Path(config_path_str))
-        if path.suffix.lower() not in {".yaml", ".yml", ".json"}:
+        if config_format_from_path(path) is None:
             msg = f"Unsupported config file type: {path.suffix}"
             raise ValueError(msg)
         return path

src/vcspull/config.py

@@ -18,7 +18,11 @@
 from vcspull.validator import is_valid_config
 
 from . import exc
-from ._internal.config_reader import ConfigReader, DuplicateAwareConfigReader
+from ._internal.config_reader import (
+    ConfigReader,
+    DuplicateAwareConfigReader,
+    config_format_from_path,
+)
 from .types import ConfigDict, RawConfigDict, WorktreeConfigDict
 from .util import get_config_dir, update_dict
 
@@ -849,7 +853,7 @@ def save_config(config_file_path: pathlib.Path, data: dict[t.Any, t.Any]) -> Non
     ...     "repo" in p.read_text()
     True
     """
-    if config_file_path.suffix.lower() == ".json":
+    if config_format_from_path(config_file_path) == "json":
         save_config_json(config_file_path, data)
     else:
         save_config_yaml(config_file_path, data)

tests/cli/test_add.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import logging
 import os
 import pathlib
@@ -367,6 +368,44 @@ def test_add_repo_uses_home_symlink_config_without_losing_yaml_suffix(
     assert "git+https://github.com/user/newrepo.git" in config_text
 
 
+def test_add_repo_uses_target_json_format_for_home_symlink(
+    tmp_path: pathlib.Path,
+    monkeypatch: MonkeyPatch,
+) -> None:
+    """Default home symlinks should save using the supported target format."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.chdir(tmp_path)
+
+    dotfiles_dir = tmp_path / "dotfiles"
+    dotfiles_dir.mkdir()
+
+    real_config = dotfiles_dir / "vcspull.json"
+    real_config.write_text("{}\n", encoding="utf-8")
+
+    symlink = tmp_path / ".vcspull.yaml"
+    symlink.symlink_to(real_config)
+
+    repo_path = tmp_path / "code" / "jsonrepo"
+    repo_path.mkdir(parents=True)
+
+    add_repo(
+        name="jsonrepo",
+        url="git+https://github.com/user/jsonrepo.git",
+        config_file_path_str=None,
+        path=str(repo_path),
+        workspace_root_path="~/code/",
+        dry_run=False,
+    )
+
+    assert symlink.is_symlink()
+    assert symlink.resolve() == real_config.resolve()
+
+    data = json.loads(real_config.read_text(encoding="utf-8"))
+    assert data["~/code/"]["jsonrepo"]["repo"] == (
+        "git+https://github.com/user/jsonrepo.git"
+    )
+
+
 def test_add_repo_invalid_config_logs_private_path(
     user_path: pathlib.Path,
     caplog: pytest.LogCaptureFixture,

tests/cli/test_import_repos.py

@@ -188,26 +188,23 @@ def test_resolve_config_file(
     assert result.name == expected_suffix
 
 
-def test_resolve_config_file_preserves_symlink_suffix(
+def test_resolve_config_file_accepts_extensionless_symlink_alias(
     tmp_path: pathlib.Path,
     monkeypatch: MonkeyPatch,
 ) -> None:
-    """Explicit config paths should keep symlink suffixes for format detection."""
+    """Explicit alias paths should inherit a supported target config format."""
     monkeypatch.setenv("HOME", str(tmp_path))
 
-    dotfiles_dir = tmp_path / "dotfiles"
-    dotfiles_dir.mkdir()
-
-    real_config = dotfiles_dir / "vcspull-config"
+    real_config = tmp_path / ".vcspull.yaml"
     real_config.write_text("~/repos/: {}\n", encoding="utf-8")
 
-    symlink = tmp_path / ".vcspull.yaml"
-    symlink.symlink_to(real_config)
+    alias_path = tmp_path / "vcspull-config"
+    alias_path.symlink_to(real_config)
 
-    result = _resolve_config_file(str(symlink))
+    result = _resolve_config_file(str(alias_path))
 
-    assert result == symlink
-    assert result.suffix == ".yaml"
+    assert result == alias_path
+    assert result.suffix == ""
     assert result.resolve() == real_config.resolve()
 
 

tests/test_config_file.py

@@ -9,7 +9,7 @@
 import pytest
 
 from vcspull import config, exc
-from vcspull._internal.config_reader import ConfigReader
+from vcspull._internal.config_reader import ConfigReader, config_format_from_path
 from vcspull.config import expand_dir, extract_repos
 from vcspull.validator import is_valid_config
 
@@ -267,6 +267,19 @@ def test_find_home_config_files_preserves_symlink_suffix(
         assert results[0].resolve() == real_file.resolve()
 
 
+def test_config_format_from_path_prefers_supported_symlink_target(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Symlink targets with supported suffixes should determine the config format."""
+    real_json = tmp_path / "vcspull.json"
+    real_json.write_text("{}\n", encoding="utf-8")
+
+    mismatch = tmp_path / ".vcspull.yaml"
+    mismatch.symlink_to(real_json)
+
+    assert config_format_from_path(mismatch) == "json"
+
+
 def test_in_dir(
     config_path: pathlib.Path,
     yaml_config: pathlib.Path,