fix(init): harden preview staging filesystem checks

Reject Windows junctions across supported Python versions and skip unreadable unmanaged staging entries while preserving failures for managed artifacts.

Author: darion-yaphet

src/specify_cli/commands/init.py

@@ -825,25 +825,119 @@ def _remap_in_project_symlinks(project_root: Path, staged_root: Path) -> None:
     raise RuntimeError("staged symlink isolation did not converge")
 
 
-def _ignore_special_files(directory: str, names: list[str]) -> set[str]:
-    """Skip sockets, devices, and other non-file tree entries during staging."""
+def _windows_path_is_junction(path: Path) -> bool:
+    """Detect a Windows junction using Python 3.11-compatible reparse data."""
+    try:
+        path_stat = path.lstat()
+    except FileNotFoundError:
+        return False
+    except OSError as exc:
+        raise ValueError(
+            f"Cannot determine whether preview path is a junction: {path}: {exc}"
+        ) from exc
+
+    reparse_tag = getattr(path_stat, "st_reparse_tag", None)
+    if reparse_tag is None:
+        raise ValueError(
+            f"Cannot determine whether preview path is a junction: {path}"
+        )
+    mount_point_tag = getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", 0xA0000003)
+    return reparse_tag == mount_point_tag
+
+
+def _path_is_junction(path: Path) -> bool:
+    """Return whether *path* is a Windows directory junction."""
+    checker = getattr(path, "is_junction", None)
+    if callable(checker):
+        try:
+            return checker()
+        except OSError as exc:
+            raise ValueError(
+                f"Cannot determine whether preview path is a junction: {path}: {exc}"
+            ) from exc
+    if os.name == "nt":
+        return _windows_path_is_junction(path)
+    return False
+
+
+def _preview_path_is_managed(path: Path, copy_root: Path) -> bool:
+    """Return whether an unreadable path may affect initialization behavior."""
+    try:
+        relative = path.relative_to(copy_root)
+    except ValueError:
+        return True
+    parts = (copy_root.name, *relative.parts)
+    if copy_root.name == ".specify" and relative.parts:
+        return relative.parts[0] in {
+            ".gitignore",
+            "extensions",
+            "extensions.yml",
+            "init-options.json",
+            "integration.json",
+            "integrations",
+            "memory",
+            "presets",
+            "scripts",
+            "templates",
+            "workflows",
+        }
+    return any(part.startswith(("speckit-", "speckit.")) for part in parts)
+
+
+def _path_is_readable_for_staging(path: Path) -> bool:
+    """Probe whether copytree can read a regular file or enumerate a directory."""
+    try:
+        if path.is_file():
+            with path.open("rb"):
+                pass
+        elif path.is_dir():
+            with os.scandir(path):
+                pass
+        return True
+    except OSError:
+        return False
+
+
+def _ignore_special_files(
+    directory: str,
+    names: list[str],
+    *,
+    copy_root: Path | None = None,
+) -> set[str]:
+    """Skip inaccessible unrelated entries and unsupported filesystem nodes."""
     ignored: set[str] = set()
+    root = copy_root or Path(directory)
     for name in names:
         candidate = Path(directory) / name
         try:
+            if _path_is_junction(candidate):
+                raise ValueError(
+                    f"Preview staging refuses Windows directory junction: {candidate}"
+                )
             if (
                 not candidate.is_symlink()
                 and not candidate.is_file()
                 and not candidate.is_dir()
             ):
                 ignored.add(name)
+                continue
+            if (
+                not candidate.is_symlink()
+                and not _path_is_readable_for_staging(candidate)
+                and not _preview_path_is_managed(candidate, root)
+            ):
+                ignored.add(name)
         except OSError:
             ignored.add(name)
     return ignored
 
 
 def _copy_staged_path(source: Path, destination: Path) -> None:
     """Copy one selected path without following symlinks."""
+    if _path_is_junction(source):
+        raise ValueError(
+            f"Preview staging refuses Windows directory junction: {source}"
+        )
     if source.is_symlink():
         if os.path.lexists(destination):
             return
@@ -857,7 +951,9 @@ def _copy_staged_path(source: Path, destination: Path) -> None:
             destination,
             symlinks=True,
             dirs_exist_ok=True,
-            ignore=_ignore_special_files,
+            ignore=lambda directory, names: _ignore_special_files(
+                directory, names, copy_root=source
+            ),
         )
     elif source.is_file():
         destination.parent.mkdir(parents=True, exist_ok=True)
@@ -875,6 +971,10 @@ def _copy_selected_staged_path(
         current /= part
         source = project_path / current
         destination = staged_root / current
+        if _path_is_junction(source):
+            raise ValueError(
+                f"Preview staging refuses Windows directory junction: {source}"
+            )
         if source.is_symlink():
             _copy_staged_path(source, destination)
             return
@@ -925,7 +1025,9 @@ def _stage_project_copy(
             project_path,
             staged_root,
             symlinks=True,
-            ignore=_ignore_special_files,
+            ignore=lambda directory, names: _ignore_special_files(
+                directory, names, copy_root=project_path
+            ),
         )
     else:
         staged_root.mkdir(parents=True, exist_ok=True)
@@ -1069,21 +1171,26 @@ def _preview_init(
         staged_root = Path(tmp_dir) / "project"
         staged_home = Path(tmp_dir) / "home"
         staged_home.mkdir()
-        _seed_preview_home(staged_home, real_home)
-        if home_seed_paths:
-            _stage_project_copy(real_home, staged_home, home_seed_paths)
-        if project_path.exists():
-            _stage_project_copy(
-                project_path,
-                staged_root,
-                _preview_seed_paths(
-                    selected_integration,
-                    integration_options,
-                    script_type,
-                ),
-            )
-        else:
-            staged_root.mkdir()
+        try:
+            _seed_preview_home(staged_home, real_home)
+            if home_seed_paths:
+                _stage_project_copy(real_home, staged_home, home_seed_paths)
+            if project_path.exists():
+                _stage_project_copy(
+                    project_path,
+                    staged_root,
+                    _preview_seed_paths(
+                        selected_integration,
+                        integration_options,
+                        script_type,
+                    ),
+                )
+            else:
+                staged_root.mkdir()
+        except (OSError, RuntimeError, ValueError, shutil.Error) as exc:
+            payload["error"] = f"failed to stage preview inputs: {exc}"
+            _emit_dry_run_preview(payload, json_output=json_output)
+            raise typer.Exit(1) from None
 
         initial_project_files = _snapshot_files(staged_root)
         initial_home_files = _snapshot_files(staged_home)

tests/test_init_dry_run.py

@@ -5,8 +5,10 @@
 import json
 import os
 import shutil
+import stat
 import subprocess
 from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
 from typer.testing import CliRunner
@@ -24,6 +26,7 @@
     _snapshot_tree_entries,
     _stage_project_copy,
     _strip_windows_extended_prefix,
+    _windows_path_is_junction,
 )
 
 _PROVENANCE_CATEGORIES = {"core", "integration", "preset", "workflow", "extension"}
@@ -1368,6 +1371,169 @@ def test_dry_run_ignores_unreadable_unmanaged_file(tmp_path: Path) -> None:
     )
 
 
+@pytest.mark.skipif(os.name == "nt", reason="chmod does not remove read access on Windows")
+def test_dry_run_ignores_unreadable_unmanaged_file_in_selected_root(
+    tmp_path: Path,
+) -> None:
+    target = tmp_path / "unreadable-selected-root"
+    unrelated = target / ".github" / "skills" / "private" / "secret.txt"
+    unrelated.parent.mkdir(parents=True)
+    unrelated.write_text("not managed by Spec Kit\n", encoding="utf-8")
+    unrelated.chmod(0)
+
+    try:
+        result = CliRunner().invoke(
+            app,
+            [
+                "init",
+                str(target),
+                "--force",
+                "--dry-run",
+                "--json",
+                "--integration",
+                "copilot",
+                "--script",
+                "sh",
+                "--ignore-agent-tools",
+            ],
+            catch_exceptions=False,
+        )
+    finally:
+        unrelated.chmod(0o600)
+
+    assert result.exit_code == 0, result.output
+    assert all(
+        action["path"] != ".github/skills/private/secret.txt"
+        for action in json.loads(result.output)["actions"]
+    )
+    assert unrelated.read_text(encoding="utf-8") == "not managed by Spec Kit\n"
+
+
+@pytest.mark.skipif(os.name == "nt", reason="chmod does not remove read access on Windows")
+def test_dry_run_reports_unreadable_managed_file_in_selected_root(
+    tmp_path: Path,
+) -> None:
+    target = tmp_path / "unreadable-managed-output"
+    managed = target / ".github" / "skills" / "speckit-plan" / "SKILL.md"
+    managed.parent.mkdir(parents=True)
+    managed.write_text("managed but unreadable\n", encoding="utf-8")
+    managed.chmod(0)
+
+    try:
+        result = CliRunner().invoke(
+            app,
+            [
+                "init",
+                str(target),
+                "--force",
+                "--dry-run",
+                "--json",
+                "--integration",
+                "copilot",
+                "--script",
+                "sh",
+                "--ignore-agent-tools",
+            ],
+            catch_exceptions=False,
+        )
+    finally:
+        managed.chmod(0o600)
+
+    assert result.exit_code == 1, result.output
+    payload = json.loads(result.output)
+    assert "failed to stage preview inputs" in payload["error"]
+    assert "Permission denied" in payload["error"]
+    assert managed.read_text(encoding="utf-8") == "managed but unreadable\n"
+
+
+def test_dry_run_rejects_selected_directory_junction_before_copy(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    target = tmp_path / "junction-preview"
+    selected_root = target / ".github" / "skills"
+    selected_root.mkdir(parents=True)
+    (selected_root / "keep.txt").write_text("external-like\n", encoding="utf-8")
+    real_is_junction = getattr(Path, "is_junction", None)
+
+    def fake_is_junction(path: Path) -> bool:
+        return path == selected_root or bool(
+            real_is_junction and real_is_junction(path)
+        )
+
+    monkeypatch.setattr(Path, "is_junction", fake_is_junction, raising=False)
+
+    result = CliRunner().invoke(
+        app,
+        [
+            "init",
+            str(target),
+            "--force",
+            "--dry-run",
+            "--json",
+            "--integration",
+            "copilot",
+            "--script",
+            "sh",
+            "--ignore-agent-tools",
+        ],
+        catch_exceptions=False,
+    )
+
+    assert result.exit_code == 1, result.output
+    payload = json.loads(result.output)
+    assert "junction" in payload["error"].lower()
+    assert (selected_root / "keep.txt").read_text(encoding="utf-8") == "external-like\n"
+
+
+def test_windows_junction_fallback_uses_reparse_tag(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    mount_point_tag = getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", 0xA0000003)
+    monkeypatch.setattr(
+        Path,
+        "lstat",
+        lambda _path: SimpleNamespace(st_reparse_tag=mount_point_tag),
+    )
+
+    assert _windows_path_is_junction(tmp_path)
+
+
+@pytest.mark.skipif(os.name != "nt", reason="Windows junction behavior")
+def test_dry_run_rejects_real_windows_junction_before_copy(tmp_path: Path) -> None:
+    target = tmp_path / "real-junction-preview"
+    external = tmp_path / "external-skills"
+    external.mkdir()
+    selected_root = target / ".github" / "skills"
+    selected_root.parent.mkdir(parents=True)
+    subprocess.run(
+        ["cmd", "/c", "mklink", "/J", str(selected_root), str(external)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    result = CliRunner().invoke(
+        app,
+        [
+            "init",
+            str(target),
+            "--force",
+            "--dry-run",
+            "--json",
+            "--integration",
+            "copilot",
+            "--script",
+            "ps",
+            "--ignore-agent-tools",
+        ],
+        catch_exceptions=False,
+    )
+
+    assert result.exit_code == 1, result.output
+    assert "junction" in json.loads(result.output)["error"].lower()
+    assert list(external.iterdir()) == []
+
+
 def test_remap_in_project_absolute_symlinks_points_at_staged_copy(
     tmp_path: Path,
 ) -> None: