fix(config[symlinked-config]) preserve logical config file type

why: Symlinked config entries in `$HOME` or via `-f/--file` can point to
extensionless or differently named targets. Resolving those paths before
format detection changes the suffix that downstream code sees, which can
make vcspull parse or save with the wrong format or reject supported
symlinked dotfile setups outright.
what:
- Add a shared config-path normalizer that expands paths without resolving
  symlinks
- Use the logical config path for home discovery and explicit config path
  handling in add, discover, fmt, and import
- Keep `_atomic_write()` following the real target so writes still update
  the destination file while preserving the symlink entry
- Add regressions for home config discovery, explicit config path
  resolution, and end-to-end `vcspull add` behavior through a symlinked
  home config

Author: tony

src/vcspull/cli/add.py

@@ -22,6 +22,7 @@
     get_pin_reason,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     save_config,
     save_config_json,
     save_config_yaml_with_items,
@@ -508,7 +509,9 @@ def add_repo(
     # Determine config file
     config_file_path: pathlib.Path
     if config_file_path_str:
-        config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+        config_file_path = normalize_config_file_path(
+            pathlib.Path(config_file_path_str)
+        )
     else:
         home_configs = find_home_config_files(filetype=["yaml"])
         if not home_configs:

src/vcspull/cli/discover.py

@@ -22,6 +22,7 @@
     get_pin_reason,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     normalize_workspace_roots,
     save_config,
     workspace_root_label,
@@ -327,7 +328,9 @@ def discover_repos(
 
     config_file_path: pathlib.Path
     if config_file_path_str:
-        config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+        config_file_path = normalize_config_file_path(
+            pathlib.Path(config_file_path_str)
+        )
     else:
         home_configs = find_home_config_files(filetype=["yaml"])
         if not home_configs:

src/vcspull/cli/fmt.py

@@ -19,6 +19,7 @@
     find_home_config_files,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     normalize_workspace_roots,
     save_config,
 )
@@ -570,7 +571,9 @@ def format_config_file(
     else:
         # Format single config file
         if config_file_path_str:
-            config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+            config_file_path = normalize_config_file_path(
+                pathlib.Path(config_file_path_str)
+            )
         else:
             home_configs = find_home_config_files(filetype=["yaml"])
             if not home_configs:

src/vcspull/cli/import_cmd/_common.py

@@ -33,6 +33,7 @@
     get_pin_reason,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     save_config,
     workspace_root_label,
 )
@@ -560,10 +561,10 @@ def _resolve_config_file(config_path_str: str | None) -> pathlib.Path:
     Returns
     -------
     pathlib.Path
-        Resolved config file path
+        Absolute config file path
     """
     if config_path_str:
-        path = pathlib.Path(config_path_str).expanduser().resolve()
+        path = normalize_config_file_path(pathlib.Path(config_path_str))
         if path.suffix.lower() not in {".yaml", ".yml", ".json"}:
             msg = f"Unsupported config file type: {path.suffix}"
             raise ValueError(msg)

src/vcspull/config.py

@@ -54,6 +54,48 @@ def expand_dir(
     return dir_
 
 
+def normalize_config_file_path(
+    path: pathlib.Path,
+    cwd: pathlib.Path | Callable[[], pathlib.Path] = pathlib.Path.cwd,
+) -> pathlib.Path:
+    """Return absolute config file path without resolving symlinks.
+
+    The logical filename determines config format, so this keeps the
+    symlink entry name intact while still expanding ``~`` and relative
+    paths.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Config file path to normalize.
+    cwd : pathlib.Path, optional
+        Current working dir (used to resolve relative paths). Defaults to
+        :py:meth:`pathlib.Path.cwd`.
+
+    Returns
+    -------
+    pathlib.Path
+        Absolute config file path with symlink names preserved.
+
+    Examples
+    --------
+    >>> normalize_config_file_path(pathlib.Path("~/cfg.yaml")).name
+    'cfg.yaml'
+    >>> normalize_config_file_path(
+    ...     pathlib.Path("configs/vcspull.yaml"),
+    ...     cwd=pathlib.Path("/tmp/project"),
+    ... )
+    PosixPath('/tmp/project/configs/vcspull.yaml')
+    """
+    path = pathlib.Path(os.path.expandvars(str(path))).expanduser()
+    if callable(cwd):
+        cwd = cwd()
+
+    if not path.is_absolute():
+        path = (cwd / path).absolute()
+    return path
+
+
 def _validate_worktrees_config(
     worktrees_raw: t.Any,
     repo_name: str,
@@ -351,8 +393,9 @@ def find_home_config_files(
 ) -> list[pathlib.Path]:
     """Return configs of ``.vcspull.{yaml,json}`` in user's home directory.
 
-    Paths are resolved through symlinks so callers receive the real
-    filesystem location, consistent with the ``-f`` flag codepath.
+    The returned path preserves the logical home entry name so callers
+    keep the config type implied by ``.yaml`` or ``.json`` even when the
+    file is a symlink.
 
     Parameters
     ----------
@@ -362,7 +405,7 @@ def find_home_config_files(
     Returns
     -------
     list of pathlib.Path
-        Resolved paths to discovered config files
+        Absolute paths to discovered config files
 
     Examples
     --------
@@ -376,9 +419,9 @@ def find_home_config_files(
     check_yaml = "yaml" in filetype
     check_json = "json" in filetype
 
-    yaml_config = pathlib.Path("~/.vcspull.yaml").expanduser().resolve()
+    yaml_config = normalize_config_file_path(pathlib.Path("~/.vcspull.yaml"))
     has_yaml_config = check_yaml and yaml_config.exists()
-    json_config = pathlib.Path("~/.vcspull.json").expanduser().resolve()
+    json_config = normalize_config_file_path(pathlib.Path("~/.vcspull.json"))
     has_json_config = check_json and json_config.exists()
 
     if not has_yaml_config and not has_json_config:

tests/cli/test_add.py

@@ -330,6 +330,43 @@ def test_add_repo_creates_new_file(
     assert "newrepo" in config["~/"]
 
 
+def test_add_repo_uses_home_symlink_config_without_losing_yaml_suffix(
+    tmp_path: pathlib.Path,
+    monkeypatch: MonkeyPatch,
+) -> None:
+    """Default home config symlinks should still load and save as YAML."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.chdir(tmp_path)
+
+    dotfiles_dir = tmp_path / "dotfiles"
+    dotfiles_dir.mkdir()
+
+    real_config = dotfiles_dir / "vcspull-config"
+    real_config.write_text("~/code/: {}\n", encoding="utf-8")
+
+    symlink = tmp_path / ".vcspull.yaml"
+    symlink.symlink_to(real_config)
+
+    repo_path = tmp_path / "code" / "newrepo"
+    repo_path.mkdir(parents=True)
+
+    add_repo(
+        name="newrepo",
+        url="git+https://github.com/user/newrepo.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()
+
+    config_text = real_config.read_text(encoding="utf-8")
+    assert "newrepo" in config_text
+    assert "git+https://github.com/user/newrepo.git" in config_text
+
+
 def test_add_repo_invalid_config_logs_private_path(
     user_path: pathlib.Path,
     caplog: pytest.LogCaptureFixture,

tests/cli/test_import_repos.py

@@ -188,6 +188,29 @@ def test_resolve_config_file(
     assert result.name == expected_suffix
 
 
+def test_resolve_config_file_preserves_symlink_suffix(
+    tmp_path: pathlib.Path,
+    monkeypatch: MonkeyPatch,
+) -> None:
+    """Explicit config paths should keep symlink suffixes for format detection."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+
+    dotfiles_dir = tmp_path / "dotfiles"
+    dotfiles_dir.mkdir()
+
+    real_config = dotfiles_dir / "vcspull-config"
+    real_config.write_text("~/repos/: {}\n", encoding="utf-8")
+
+    symlink = tmp_path / ".vcspull.yaml"
+    symlink.symlink_to(real_config)
+
+    result = _resolve_config_file(str(symlink))
+
+    assert result == symlink
+    assert result.suffix == ".yaml"
+    assert result.resolve() == real_config.resolve()
+
+
 class ImportReposFixture(t.NamedTuple):
     """Fixture for _run_import test cases."""
 

tests/test_config_file.py

@@ -244,11 +244,13 @@ def test_find_home_config_files_both_types_still_raises(
         config.find_home_config_files()
 
 
-def test_find_home_config_files_resolves_symlink(tmp_path: pathlib.Path) -> None:
-    """Symlinked ~/.vcspull.yaml should be resolved to the real target path."""
+def test_find_home_config_files_preserves_symlink_suffix(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Symlinked home configs should keep the logical suffix for format detection."""
     dotfiles_dir = tmp_path / ".dot-config"
     dotfiles_dir.mkdir()
-    real_file = dotfiles_dir / ".vcspull.yaml"
+    real_file = dotfiles_dir / "vcspull-config"
     real_file.write_text("~/code/: {}\n", encoding="utf-8")
 
     symlink = tmp_path / ".vcspull.yaml"
@@ -259,9 +261,10 @@ def test_find_home_config_files_resolves_symlink(tmp_path: pathlib.Path) -> None
         results = config.find_home_config_files()
 
         assert len(results) == 1
-        # Must be the resolved (real) path, not the symlink
-        assert results[0] == real_file.resolve()
-        assert not results[0].is_symlink()
+        assert results[0] == symlink
+        assert results[0].suffix == ".yaml"
+        assert results[0].is_symlink()
+        assert results[0].resolve() == real_file.resolve()
 
 
 def test_in_dir(