git-env 0.1.0__py3-none-any.whl

git_env/discovery.py

@@ -0,0 +1,204 @@
+"""File discovery: walk the primary worktree and find env files to sync.
+
+Implements the "File discovery" rules from spec.md: match configured
+patterns against the primary worktree, ignore `.gitignore` entirely, honor
+an opt-out `.envsyncignore` (gitignore syntax), skip symlinks unless
+configured otherwise, skip oversized files with a warning, and never
+traverse into submodules.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import SyncConfig
+
+#: Directory name that always marks a repository root; never descend into a
+#: nested one (submodule) other than the primary worktree's own root.
+_GIT_ENTRY = ".git"
+
+
+@dataclass(frozen=True)
+class DiscoveredFile:
+    """A file in the primary worktree that matches the sync patterns."""
+
+    relative_path: Path
+    """Path relative to the primary worktree root."""
+
+    absolute_path: Path
+    """Absolute path to the file (symlink target if followed)."""
+
+    size: int
+
+    is_symlink: bool
+
+
+@dataclass(frozen=True)
+class DiscoveryWarning:
+    """A non-fatal issue encountered while discovering files."""
+
+    relative_path: Path
+    message: str
+
+
+class _IgnoreMatcher:
+    """Minimal gitignore-syntax matcher for `.envsyncignore`."""
+
+    def __init__(self, lines: list[str]) -> None:
+        self._rules: list[tuple[re.Pattern[str], bool, bool]] = []
+        for raw in lines:
+            line = raw.rstrip("\n")
+            if not line.strip() or line.startswith("#"):
+                continue
+            negate = line.startswith("!")
+            if negate:
+                line = line[1:]
+            line = line.rstrip()
+            if not line:
+                continue
+            dir_only = line.endswith("/")
+            if dir_only:
+                line = line[:-1]
+            anchored = line.startswith("/")
+            if anchored:
+                line = line[1:]
+            pattern = re.compile(self._translate(line, anchored))
+            self._rules.append((pattern, negate, dir_only))
+
+    @staticmethod
+    def _translate(pattern: str, anchored: bool) -> str:
+        i = 0
+        n = len(pattern)
+        out: list[str] = ["^" if anchored else "^(?:.*/)?"]
+        while i < n:
+            ch = pattern[i]
+            if ch == "*":
+                if pattern[i : i + 2] == "**":
+                    if pattern[i : i + 3] == "**/":
+                        out.append("(?:.*/)?")
+                        i += 3
+                        continue
+                    out.append(".*")
+                    i += 2
+                    continue
+                out.append("[^/]*")
+                i += 1
+                continue
+            if ch == "?":
+                out.append("[^/]")
+                i += 1
+                continue
+            out.append(re.escape(ch))
+            i += 1
+        out.append("$")
+        return "".join(out)
+
+    def matches(self, relative_posix: str, *, is_dir: bool) -> bool:
+        ignored = False
+        for pattern, negate, dir_only in self._rules:
+            if dir_only and not is_dir:
+                continue
+            if pattern.match(relative_posix):
+                ignored = not negate
+        return ignored
+
+    @property
+    def empty(self) -> bool:
+        return not self._rules
+
+
+def _load_ignore_matcher(primary_root: Path) -> _IgnoreMatcher:
+    ignore_file = primary_root / ".envsyncignore"
+    if not ignore_file.is_file():
+        return _IgnoreMatcher([])
+    return _IgnoreMatcher(ignore_file.read_text().splitlines())
+
+
+def _matches_any(name: str, patterns: tuple[str, ...]) -> bool:
+    return any(fnmatch.fnmatch(name, pattern) for pattern in patterns)
+
+
+def discover_env_files(
+    primary_root: Path, config: SyncConfig
+) -> tuple[list[DiscoveredFile], list[DiscoveryWarning]]:
+    """Walk `primary_root` and return matching files plus any warnings."""
+    primary_root = primary_root.resolve()
+    ignore = _load_ignore_matcher(primary_root)
+
+    files: list[DiscoveredFile] = []
+    warnings: list[DiscoveryWarning] = []
+
+    for dirpath, dirnames, filenames in os.walk(
+        primary_root, followlinks=config.follow_symlinks
+    ):
+        dir_path = Path(dirpath)
+        rel_dir = dir_path.relative_to(primary_root)
+
+        kept_dirnames = []
+        for dirname in dirnames:
+            child = dir_path / dirname
+            rel_child = (rel_dir / dirname) if str(rel_dir) != "." else Path(dirname)
+            rel_child_posix = rel_child.as_posix()
+
+            if dirname == _GIT_ENTRY:
+                continue
+            # Nested repo (submodule): a directory with its own .git entry,
+            # other than the primary root itself.
+            if (child / _GIT_ENTRY).exists():
+                continue
+            if child.is_symlink() and not config.follow_symlinks:
+                continue
+            if not ignore.empty and ignore.matches(rel_child_posix, is_dir=True):
+                continue
+            kept_dirnames.append(dirname)
+        dirnames[:] = kept_dirnames
+
+        for filename in filenames:
+            abs_path = dir_path / filename
+            rel_path = (rel_dir / filename) if str(rel_dir) != "." else Path(filename)
+            rel_posix = rel_path.as_posix()
+
+            if not _matches_any(filename, config.patterns):
+                continue
+            if _matches_any(filename, config.exclude):
+                continue
+            if not ignore.empty and ignore.matches(rel_posix, is_dir=False):
+                continue
+
+            is_symlink = abs_path.is_symlink()
+            if is_symlink and not config.follow_symlinks:
+                continue
+
+            try:
+                stat_result = abs_path.stat()
+            except OSError as exc:
+                warnings.append(
+                    DiscoveryWarning(rel_path, f"could not stat file: {exc}")
+                )
+                continue
+
+            if stat_result.st_size > config.max_file_size:
+                warnings.append(
+                    DiscoveryWarning(
+                        rel_path,
+                        f"skipped: {stat_result.st_size} bytes exceeds "
+                        f"env.sync.maxFileSize ({config.max_file_size})",
+                    )
+                )
+                continue
+
+            files.append(
+                DiscoveredFile(
+                    relative_path=rel_path,
+                    absolute_path=abs_path,
+                    size=stat_result.st_size,
+                    is_symlink=is_symlink,
+                )
+            )
+
+    files.sort(key=lambda f: f.relative_path.as_posix())
+    return files, warnings

git_env/output.py

@@ -0,0 +1,34 @@
+"""Minimal stdout/stderr printer used by sync until colorized output lands
+(see "Implement output formatting and color" todo).
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+class Reporter:
+    """Routes sync messages to stdout/stderr according to -v/-q."""
+
+    def __init__(self, *, verbose: bool = False, quiet: bool = False) -> None:
+        self.verbose = verbose
+        self.quiet = quiet
+
+    def info(self, message: str) -> None:
+        """Always-shown progress, e.g. "synced .env". Suppressed by --quiet."""
+        if not self.quiet:
+            print(message)
+
+    def detail(self, message: str) -> None:
+        """Verbose-only progress, e.g. skipped/unchanged files."""
+        if self.verbose and not self.quiet:
+            print(message)
+
+    def warn(self, message: str) -> None:
+        """Non-fatal warnings (conflicts, oversized files): always shown, on stderr."""
+        if not self.quiet:
+            print(f"warning: {message}", file=sys.stderr)
+
+    def error(self, message: str) -> None:
+        """Fatal errors: always shown, even under --quiet."""
+        print(f"error: {message}", file=sys.stderr)

git_env/repo.py

@@ -0,0 +1,156 @@
+"""Repository detection: locate the primary worktree and reject unsupported layouts."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class RepoError(Exception):
+    """Raised when the current location is not a usable linked worktree.
+
+    Always corresponds to exit code 2 per the spec's repository detection rules.
+    """
+
+
+@dataclass(frozen=True)
+class Repository:
+    """The repository context for the current invocation."""
+
+    git_dir: Path
+    """Absolute path to the current worktree's git dir."""
+
+    git_common_dir: Path
+    """Absolute path to the shared git dir (inside the primary worktree's .git)."""
+
+    primary_root: Path
+    """Absolute path to the primary worktree's root directory."""
+
+    worktree_root: Path
+    """Absolute path to the current (linked) worktree's root directory."""
+
+
+def _git(*args: str, cwd: Path | None = None) -> str:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise RepoError("git executable not found on PATH") from exc
+    return result.stdout.strip()
+
+
+def _git_ok(*args: str, cwd: Path | None = None) -> tuple[bool, str]:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise RepoError("git executable not found on PATH") from exc
+    return result.returncode == 0, result.stdout.strip()
+
+
+def detect_repository(cwd: Path | None = None) -> Repository:
+    """Detect the repository context for `cwd` (defaults to the process cwd).
+
+    Raises RepoError (exit code 2) for any of:
+      - not inside a git worktree
+      - inside a bare repository
+      - inside the primary worktree (sync only runs from a linked worktree)
+    """
+    cwd = (cwd or Path.cwd()).resolve()
+
+    inside_ok, inside_out = _git_ok("rev-parse", "--is-inside-work-tree", cwd=cwd)
+    bare_ok, bare_out = _git_ok("rev-parse", "--is-bare-repository", cwd=cwd)
+
+    # A bare repo has no work tree, so --is-inside-work-tree reports "false" (not
+    # an error) even when we *are* inside a git dir. Check bare-ness first so that
+    # case gets its own message instead of the generic "not inside a worktree" one.
+    if bare_ok and bare_out == "true":
+        raise RepoError("bare repositories are not supported")
+
+    if not inside_ok or inside_out != "true":
+        raise RepoError("not inside a git worktree")
+
+    git_dir = Path(_git("rev-parse", "--path-format=absolute", "--git-dir", cwd=cwd))
+    git_common_dir = Path(
+        _git("rev-parse", "--path-format=absolute", "--git-common-dir", cwd=cwd)
+    )
+
+    if git_dir.resolve() == git_common_dir.resolve():
+        primary_root = git_common_dir.resolve().parent
+        raise RepoError(
+            f"git env sync runs from a linked worktree; you appear to be in the "
+            f"primary at {primary_root}"
+        )
+
+    primary_root = git_common_dir.resolve().parent
+    worktree_root = Path(
+        _git("rev-parse", "--path-format=absolute", "--show-toplevel", cwd=cwd)
+    ).resolve()
+
+    _check_pwd_within_worktree(worktree_root)
+
+    return Repository(
+        git_dir=git_dir.resolve(),
+        git_common_dir=git_common_dir.resolve(),
+        primary_root=primary_root,
+        worktree_root=worktree_root,
+    )
+
+
+def _check_pwd_within_worktree(worktree_root: Path) -> None:
+    """Paranoid check (spec: "Safety rails") that the shell-reported `$PWD`
+    is actually inside the worktree we just resolved. Catches weird
+    invocations (e.g. a symlinked directory pointing somewhere else) where
+    the shell's notion of cwd has diverged from the real one.
+
+    Skipped if `$PWD` isn't set, since not every caller sets it.
+    """
+    pwd = os.environ.get("PWD")
+    if not pwd:
+        return
+    resolved_pwd = Path(pwd).resolve()
+    if resolved_pwd != worktree_root and worktree_root not in resolved_pwd.parents:
+        raise RepoError(
+            f"$PWD ({pwd}) is not within the current worktree at {worktree_root}"
+        )
+
+
+def check_primary_clean(
+    primary_root: Path, patterns: tuple[str, ...], exclude: tuple[str, ...]
+) -> list[str]:
+    """Return relative paths of tracked env files with uncommitted changes
+    in `primary_root` (spec: "Safety rails" — don't propagate half-edits on
+    a tracked template). Empty list means the primary is clean.
+    """
+    result = subprocess.run(
+        ["git", "diff", "--name-only", "HEAD", "--no-renames"],
+        cwd=primary_root,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return []
+
+    dirty: list[str] = []
+    for line in result.stdout.splitlines():
+        path = line.strip()
+        if not path:
+            continue
+        name = Path(path).name
+        if not any(fnmatch.fnmatch(name, pattern) for pattern in patterns):
+            continue
+        if any(fnmatch.fnmatch(name, pattern) for pattern in exclude):
+            continue
+        dirty.append(path)
+    return dirty

git_env/shell_completions.py

@@ -0,0 +1,91 @@
+"""Shell completion scripts and the `git env --install-completions` helper.
+
+The completion scripts themselves live in `git_env/completions/` (package
+data, so they ship inside the installed wheel) and are shipped under their
+target filenames (`git-env.bash`, `_git-env`, `git-env.fish`) per spec.md
+"Tab completion".
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+SUPPORTED_SHELLS = ("bash", "zsh", "fish")
+
+_PACKAGE_FILENAMES = {
+    "bash": "git-env.bash",
+    "zsh": "_git-env",
+    "fish": "git-env.fish",
+}
+
+
+@dataclass(frozen=True)
+class CompletionTarget:
+    """Where a shell's completion file is installed, and how to enable it."""
+
+    install_path: Path
+    enable_snippet: str
+
+
+def _xdg_data_home() -> Path:
+    return Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share")
+
+
+def completion_target(shell: str) -> CompletionTarget:
+    """Resolve the standard user-level install path and rc snippet for `shell`."""
+    home = Path.home()
+    if shell == "bash":
+        path = _xdg_data_home() / "bash-completion" / "completions" / "git-env"
+        snippet = f'source "{path}"'
+    elif shell == "zsh":
+        path = home / ".zsh" / "completions" / "_git-env"
+        snippet = f'fpath=("{path.parent}" $fpath)\nautoload -Uz compinit && compinit'
+    elif shell == "fish":
+        path = home / ".config" / "fish" / "completions" / "git-env.fish"
+        snippet = f"# fish loads completions from {path.parent} automatically, nothing else to do"
+    else:
+        raise ValueError(f"unsupported shell: {shell!r}")
+    return CompletionTarget(install_path=path, enable_snippet=snippet)
+
+
+def completion_source(shell: str) -> str:
+    """Return the packaged completion script content for `shell`."""
+    filename = _PACKAGE_FILENAMES[shell]
+    return resources.files("git_env.completions").joinpath(filename).read_text()
+
+
+def install_completions(shell: str, *, write: bool) -> str:
+    """
+    Print an rc snippet plus the completion script for `shell`, or write the
+    script to its standard location with `write=True`.
+
+    Returns the message to print to the user. Raises ValueError for an
+    unsupported shell.
+    """
+    if shell not in SUPPORTED_SHELLS:
+        raise ValueError(
+            f"unsupported shell {shell!r}, expected one of {', '.join(SUPPORTED_SHELLS)}"
+        )
+
+    source = completion_source(shell)
+    target = completion_target(shell)
+
+    if not write:
+        return (
+            f"{source}\n"
+            f"# add this to your shell rc file to enable completions:\n"
+            f"# {target.enable_snippet}"
+        )
+
+    target.install_path.parent.mkdir(parents=True, exist_ok=True)
+    target.install_path.write_text(source)
+    message = f"installed {shell} completions to {target.install_path}"
+    if shell != "fish":
+        message += (
+            "\nadd this to your shell rc file if not already present:\n"
+            f"{target.enable_snippet}"
+        )
+    return message