cdf-shell 0.1.0__py3-none-any.whl

cdf/__main__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+
+from cdf.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

cdf/app.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import itertools
+import os
+from collections.abc import Collection
+from pathlib import Path
+
+from cdf.errors import NoCandidatesError
+from cdf.picker import Picker
+from cdf.walker import DirectoryWalker
+
+
+def resolve(
+    term: str,
+    root: Path,
+    *,
+    git_only: bool,
+    include_hidden: bool,
+    ignore: Collection[str],
+    max_depth: int | None = None,
+    one_file_system: bool = False,
+    walker: DirectoryWalker,
+    picker: Picker,
+) -> Path | None:
+    candidates = walker.walk(
+        root,
+        git_only=git_only,
+        include_hidden=include_hidden,
+        ignore=ignore,
+        max_depth=max_depth,
+        one_file_system=one_file_system,
+    )
+    # Peek at the first candidate so an empty tree gets a clear message instead
+    # of an empty picker; the rest keeps streaming lazily into the picker.
+    first = next(candidates, None)
+    if first is None:
+        raise NoCandidatesError(_no_candidates_message(root, git_only=git_only))
+    return picker.pick(itertools.chain([first], candidates), term, root=root)
+
+
+def _enclosing_repo(root: Path) -> Path | None:
+    # os.path.exists never raises (Path.exists can, on Python < 3.14, for an
+    # unsearchable ancestor); this only picks the wording of a message.
+    return next((path for path in (root, *root.parents) if os.path.exists(path / ".git")), None)
+
+
+def _no_candidates_message(root: Path, *, git_only: bool) -> str:
+    if not git_only:
+        return f"no directories found under {root}"
+    # The walk skips the root itself, so running inside a repo only finds
+    # repos nested in it; say so rather than implying there are none at all.
+    repo = _enclosing_repo(root)
+    if repo is not None:
+        return (
+            f"no nested git repositories found under {root}, which is inside the "
+            f"repository {repo} (try --no-git)"
+        )
+    return f"no git repositories found under {root} (try --no-git)"

cdf/cli.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from importlib import resources
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from cdf.app import resolve
+from cdf.config import default_config_paths, resolve_config
+from cdf.display import printable
+from cdf.errors import CdfError, NoCandidatesError
+from cdf.picker import FzfPicker, Picker
+from cdf.walker import DirectoryWalker, FilesystemWalker
+
+_EXIT_SELECTED = 0
+_EXIT_NO_SELECTION = 1
+_EXIT_ERROR = 2
+_EXIT_INTERRUPTED = 130
+# bash and zsh share one POSIX-style wrapper; fish needs its own.
+_INIT_SCRIPTS = {"bash": "cdf.sh", "zsh": "cdf.sh", "fish": "cdf.fish"}
+
+
+def create_walker() -> DirectoryWalker:
+    return FilesystemWalker()
+
+
+def create_picker() -> Picker:
+    return FzfPicker()
+
+
+def _package_version() -> str:
+    try:
+        return version("cdf-shell")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _resolve_config_path(cli_config: Path | None) -> Path | None:
+    if cli_config is not None:
+        return cli_config
+    env_config = os.environ.get("CDF_CONFIG_PATH")
+    return Path(env_config) if env_config else None
+
+
+def _non_negative_int(text: str) -> int:
+    try:
+        value = int(text)
+    except ValueError:
+        value = -1
+    if value < 0:
+        raise argparse.ArgumentTypeError(f"expected a non-negative integer, got {text!r}")
+    return value
+
+
+def shell_init_script(shell: str) -> str:
+    script = resources.files("cdf").joinpath("shell", _INIT_SCRIPTS[shell])
+    return script.read_text(encoding="utf-8")
+
+
+def _write_stdout(data: bytes) -> bool:
+    """Write raw bytes to stdout; False if the reader has already gone away."""
+    try:
+        sys.stdout.flush()
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+    except BrokenPipeError:
+        # Point stdout at /dev/null so the interpreter's own flush at exit
+        # doesn't raise (and print a traceback) a second time.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        os.close(devnull)
+        return False
+    return True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cdf",
+        description="Interactively find a directory below a path and print it.",
+        epilog=(
+            "This binary only prints the resolved path; it never changes your shell's "
+            'working directory itself. Add `eval "$(command cdf --init bash)"` (or zsh) '
+            "to your shell rc, or `command cdf --init fish | source` to config.fish: it "
+            "defines a `cdf` shell function (which takes priority "
+            "over this binary and calls it internally via `command cdf`) that actually "
+            "cds into the result.\n\n"
+            "Defaults shown below can also be set in the config file (-c/--config); "
+            "CLI flags always win.\n\n"
+            "Exit codes: 0 = a directory was selected, 1 = nothing was selected "
+            "(cancelled or no matches), 2 = an error occurred (see stderr)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        # No "--ver" for "--version" etc.: the shell wrappers recognise the
+        # informational flags by their exact spelling.
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "term", nargs="*", default=[], help="initial fuzzy filter text (words are joined)"
+    )
+    parser.add_argument(
+        "-p",
+        "--path",
+        type=Path,
+        default=None,
+        help="root to search from (default: cwd)",
+    )
+    parser.add_argument(
+        "--git",
+        dest="git",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="only match git repository roots (default: on)",
+    )
+    parser.add_argument(
+        "-a",
+        "--all",
+        dest="hidden",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="include hidden/dot directories (default: off)",
+    )
+    parser.add_argument(
+        "-d",
+        "--max-depth",
+        type=_non_negative_int,
+        default=None,
+        metavar="N",
+        help="only look N levels below the root; 0 = no limit (default: no limit)",
+    )
+    parser.add_argument(
+        "-x",
+        "--one-file-system",
+        dest="one_file_system",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="list mount points but don't descend into them (default: off)",
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        default=None,
+        help=(
+            "config file path (default: $CDF_CONFIG_PATH, else first existing of "
+            + (", ".join(str(path) for path in default_config_paths()) or "none")
+            + ")"
+        ),
+    )
+    parser.add_argument(
+        "--init",
+        choices=tuple(_INIT_SCRIPTS),
+        default=None,
+        metavar="SHELL",
+        help=f"print the shell integration for SHELL ({', '.join(_INIT_SCRIPTS)}) and exit",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {_package_version()}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.init is not None:
+        written = _write_stdout(shell_init_script(args.init).encode())
+        return _EXIT_SELECTED if written else _EXIT_ERROR
+
+    try:
+        config = resolve_config(
+            config_path=_resolve_config_path(args.config),
+            cli_path=args.path,
+            cli_git=args.git,
+            cli_hidden=args.hidden,
+            cli_max_depth=args.max_depth,
+            cli_one_file_system=args.one_file_system,
+        )
+        target = resolve(
+            " ".join(args.term),
+            config.path,
+            git_only=config.git,
+            include_hidden=config.hidden,
+            ignore=config.ignore,
+            max_depth=config.max_depth,
+            one_file_system=config.one_file_system,
+            walker=create_walker(),
+            picker=create_picker(),
+        )
+    except KeyboardInterrupt:
+        return _EXIT_INTERRUPTED
+    except NoCandidatesError as exc:
+        # Messages can embed directory names; never echo control characters.
+        print(printable(str(exc)), file=sys.stderr)
+        return _EXIT_NO_SELECTION
+    except CdfError as exc:
+        print(printable(str(exc)), file=sys.stderr)
+        return _EXIT_ERROR
+
+    if target is None:
+        return _EXIT_NO_SELECTION
+
+    # Raw bytes: a non-UTF-8 name can't go through the text layer under a
+    # strict locale (e.g. en_US.UTF-8), and the shell needs the exact bytes.
+    # If nobody read the path, it wasn't delivered: report that, not success.
+    written = _write_stdout(os.fsencode(target) + b"\n")
+    return _EXIT_SELECTED if written else _EXIT_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cdf/config.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from cdf.errors import CdfError
+
+DEFAULT_IGNORE = ("node_modules", "__pycache__", ".venv")
+_KNOWN_KEYS = {"path", "git", "hidden", "ignore", "max_depth", "one_file_system"}
+
+
+@dataclass(frozen=True)
+class Config:
+    path: Path
+    git: bool = True
+    hidden: bool = False
+    ignore: tuple[str, ...] = field(default=DEFAULT_IGNORE)
+    max_depth: int | None = None
+    one_file_system: bool = False
+
+
+def _home() -> Path | None:
+    # Path.home() raises when $HOME is unset and the user has no passwd entry
+    # (e.g. an arbitrary UID in a container); treat that as "no home".
+    try:
+        return Path.home()
+    except RuntimeError:
+        return None
+
+
+def default_config_paths() -> tuple[Path, ...]:
+    home = _home()
+    paths: list[Path] = []
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    # The XDG spec says to ignore a relative XDG_CONFIG_HOME.
+    if xdg_config_home and Path(xdg_config_home).is_absolute():
+        paths.append(Path(xdg_config_home) / "cdf" / "cdf.conf")
+    elif home is not None:
+        paths.append(home / ".config" / "cdf" / "cdf.conf")
+    if home is not None:
+        paths.append(home / "cdf.conf")
+    return tuple(paths)
+
+
+def _first_existing_default(paths: tuple[Path, ...]) -> Path | None:
+    # os.path.isfile, not Path.exists: on Python < 3.14 the latter raises
+    # PermissionError when a parent (e.g. ~/.config) can't be searched, and a
+    # file nobody can reach can't be the one the user meant.
+    return next((path for path in paths if os.path.isfile(path)), None)
+
+
+def _absolute(path: Path | None) -> Path:
+    # Always hand an absolute root to the walker, so every printed result is
+    # absolute and the shell's `cd` never consults CDPATH or sees a leading "-".
+    # abspath (not resolve) keeps symlinked directories as the user wrote them.
+    try:
+        return Path(os.path.abspath(path)) if path is not None else Path.cwd()
+    except FileNotFoundError as exc:
+        raise CdfError(
+            "the current directory no longer exists; cd somewhere else or pass -p/--path"
+        ) from exc
+
+
+def load_config_file(config_path: Path) -> dict[str, object]:
+    try:
+        with config_path.open("rb") as config_file:
+            data = tomllib.load(config_file)
+    except FileNotFoundError as exc:
+        # Default locations are only ever passed in when they exist, so a
+        # missing file here is always one the user named (-c or $CDF_CONFIG_PATH).
+        raise CdfError(f"config file not found: {config_path}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise CdfError(f"invalid config file {config_path}: {exc}") from exc
+    except OSError as exc:
+        raise CdfError(f"cannot read config file {config_path}: {exc}") from exc
+
+    unknown = set(data) - _KNOWN_KEYS
+    if unknown:
+        raise CdfError(f"unknown key(s) in {config_path}: {', '.join(sorted(unknown))}")
+    return data
+
+
+def _file_overrides(file_data: dict[str, object], config_path: Path) -> dict[str, Any]:
+    overrides: dict[str, Any] = {}
+
+    if "path" in file_data:
+        raw_path = file_data["path"]
+        if not isinstance(raw_path, str):
+            type_name = type(raw_path).__name__
+            raise CdfError(f"{config_path}: 'path' must be a string, got {type_name}")
+        # A relative path in the file means relative to the file, not to
+        # wherever cdf happens to be run from.
+        try:
+            expanded = Path(raw_path).expanduser()
+        except RuntimeError as exc:
+            raise CdfError(f"{config_path}: cannot expand '~' in 'path': {exc}") from exc
+        overrides["path"] = config_path.parent / expanded
+
+    for key in ("git", "hidden", "one_file_system"):
+        if key in file_data:
+            value = file_data[key]
+            if not isinstance(value, bool):
+                type_name = type(value).__name__
+                raise CdfError(f"{config_path}: '{key}' must be a boolean, got {type_name}")
+            overrides[key] = value
+
+    if "max_depth" in file_data:
+        value = file_data["max_depth"]
+        # bool is a subclass of int, so `max_depth = true` needs its own check.
+        if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+            raise CdfError(f"{config_path}: 'max_depth' must be a non-negative integer")
+        overrides["max_depth"] = value
+
+    if "ignore" in file_data:
+        patterns = file_data["ignore"]
+        if not isinstance(patterns, list) or not all(isinstance(p, str) for p in patterns):
+            raise CdfError(f"{config_path}: 'ignore' must be a list of strings")
+        # Patterns are matched against one directory name at a time, so one
+        # with a "/" could never match; say so instead of silently ignoring it.
+        with_slash = [pattern for pattern in patterns if "/" in pattern]
+        if with_slash:
+            raise CdfError(
+                f"{config_path}: 'ignore' patterns match single directory names and "
+                f"can't contain '/': {', '.join(with_slash)}"
+            )
+        overrides["ignore"] = tuple(patterns)
+
+    return overrides
+
+
+def _cli_overrides(
+    cli_path: Path | None,
+    cli_git: bool | None,
+    cli_hidden: bool | None,
+    cli_max_depth: int | None,
+    cli_one_file_system: bool | None,
+) -> dict[str, Any]:
+    candidates = {
+        "path": cli_path,
+        "git": cli_git,
+        "hidden": cli_hidden,
+        "max_depth": cli_max_depth,
+        "one_file_system": cli_one_file_system,
+    }
+    return {key: value for key, value in candidates.items() if value is not None}
+
+
+def resolve_config(
+    *,
+    config_path: Path | None = None,
+    cli_path: Path | None = None,
+    cli_git: bool | None = None,
+    cli_hidden: bool | None = None,
+    cli_max_depth: int | None = None,
+    cli_one_file_system: bool | None = None,
+) -> Config:
+    resolved_config_path = config_path or _first_existing_default(default_config_paths())
+    file_overrides: dict[str, Any] = {}
+    if resolved_config_path is not None:
+        file_data = load_config_file(resolved_config_path)
+        file_overrides = _file_overrides(file_data, resolved_config_path)
+    cli_overrides = _cli_overrides(
+        cli_path, cli_git, cli_hidden, cli_max_depth, cli_one_file_system
+    )
+    overrides = {**file_overrides, **cli_overrides}
+    root = _absolute(overrides.pop("path", None))
+    # 0 means "no limit", so a CLI flag can lift a limit set in the file.
+    if overrides.get("max_depth") == 0:
+        overrides["max_depth"] = None
+    config = Config(path=root, **overrides)
+
+    if not config.path.is_dir():
+        raise CdfError(f"search root does not exist or is not a directory: {config.path}")
+
+    return config

cdf/display.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+# Unicode category Cc is exactly C0 (U+0000-U+001F), DEL and C1 (U+007F-U+009F).
+# Any of them in a directory name could move the cursor, retitle the window or
+# worse when echoed to a terminal, so they are shown as "?" instead.
+_CONTROL_CHARS = {code: "?" for code in (*range(0x00, 0x20), *range(0x7F, 0xA0))}
+
+
+def printable(text: str) -> str:
+    """Return `text` with terminal control characters replaced by "?".
+
+    Undecodable bytes (surrogate escapes) are left alone, so
+    `os.fsencode(printable(name))` still round-trips every other byte.
+    """
+    return text.translate(_CONTROL_CHARS)

cdf/errors.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class CdfError(Exception):
+    pass
+
+
+class NoCandidatesError(CdfError):
+    """The walk found nothing to pick from; not a failure, just an empty result."""

cdf/picker.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import threading
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Protocol
+
+from cdf.display import printable
+from cdf.errors import CdfError
+
+_EXIT_MATCHED = 0
+_EXIT_NO_MATCH = 1
+_EXIT_INTERRUPTED = 130
+
+
+class Picker(Protocol):
+    def pick(self, candidates: Iterable[Path], term: str, *, root: Path) -> Path | None: ...
+
+
+def _display(path: Path, root: Path) -> bytes:
+    # What fzf shows and matches: the path relative to the search root (so the
+    # root's own components don't match every query), with control characters
+    # (escape sequences, newlines, tabs) neutralised. Never used to resolve the
+    # pick except as a fallback; the index maps back to the exact original Path.
+    try:
+        shown = path.relative_to(root)
+    except ValueError:
+        shown = path
+    return os.fsencode(printable(os.fspath(shown)))
+
+
+def _feed(
+    process: subprocess.Popen[bytes],
+    candidates: Iterable[Path],
+    root: Path,
+    seen: list[Path],
+    errors: list[Exception],
+) -> None:
+    # Each entry is "<index>\t<display>". fzf only shows/matches the display
+    # (see --with-nth) but echoes the whole entry back, so the index maps the
+    # pick to the exact original Path even when fzf can't round-trip its bytes
+    # (fzf replaces non-UTF-8 bytes in names). fzf closes its end as soon as the
+    # user picks something; a still-running walk then hits a broken pipe,
+    # which just means "stop feeding".
+    stdin = process.stdin
+    assert stdin is not None
+    try:
+        for candidate in candidates:
+            seen.append(candidate)
+            stdin.write(b"%d\t%s\0" % (len(seen) - 1, _display(candidate, root)))
+    except BrokenPipeError:
+        pass
+    except Exception as exc:
+        # Don't leave fzf showing a silently truncated list: stop it (before
+        # closing its input, so it can't finish normally) and let pick()
+        # report what went wrong.
+        errors.append(exc)
+        process.kill()
+    finally:
+        stdin.close()
+
+
+def _parse_selection(output: bytes, seen: list[Path], root: Path) -> Path | None:
+    # FZF_DEFAULT_OPTS may add --print-query/--expect/--multi, which put extra
+    # NUL-delimited entries in the output. The selection is the last entry.
+    entries = [entry for entry in output.split(b"\0") if entry]
+    if not entries:
+        return None
+    entry = entries[-1]
+    selected = _by_index(entry, seen) or _by_display(entry, seen, root)
+    if selected is None:
+        raise CdfError(f"unexpected output from fzf: {entry!r}")
+    if not selected.is_dir():
+        raise CdfError(f"selected directory no longer exists: {selected}")
+    return selected
+
+
+def _by_index(entry: bytes, seen: list[Path]) -> Path | None:
+    index, tab, _ = entry.partition(b"\t")
+    if not tab or not index.isdigit() or int(index) >= len(seen):
+        return None
+    return seen[int(index)]
+
+
+def _by_display(entry: bytes, seen: list[Path], root: Path) -> Path | None:
+    # Fallback for an --accept-nth in FZF_DEFAULT_OPTS that prints only the
+    # display field. (Overriding it with --accept-nth ourselves would break
+    # fzf < 0.60, which rejects the option.) Displays never contain a tab, so
+    # this can't be confused with the index form; ambiguity is refused.
+    matches = [path for path in seen if _display(path, root) == entry]
+    return matches[0] if len(matches) == 1 else None
+
+
+class FzfPicker:
+    def pick(self, candidates: Iterable[Path], term: str, *, root: Path) -> Path | None:
+        # Run exactly the fzf that was found, rather than searching PATH again.
+        fzf = shutil.which("fzf")
+        if fzf is None:
+            raise CdfError("fzf not found on PATH. Install it: https://github.com/junegunn/fzf")
+
+        # Unbuffered stdin so each candidate reaches fzf as soon as the walker
+        # finds it; stderr is inherited so fzf's own error messages show up.
+        process = subprocess.Popen(
+            [
+                fzf,
+                "--read0",
+                "--print0",
+                "--delimiter",
+                "\t",
+                "--with-nth",
+                "2..",
+                "--query",
+                term,
+            ],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            bufsize=0,
+        )
+        assert process.stdin is not None and process.stdout is not None
+        seen: list[Path] = []
+        errors: list[Exception] = []
+        # Daemon thread: once fzf exits we return without waiting for the walk.
+        feeder = threading.Thread(
+            target=_feed, args=(process, candidates, root, seen, errors), daemon=True
+        )
+        feeder.start()
+
+        try:
+            output = process.stdout.read()
+            returncode = process.wait()
+        except BaseException:
+            process.kill()
+            process.wait()
+            raise
+
+        if returncode == _EXIT_MATCHED:
+            return _parse_selection(output, seen, root)
+        if errors:
+            raise CdfError(f"directory walk failed: {errors[0]}") from errors[0]
+        if returncode in (_EXIT_NO_MATCH, _EXIT_INTERRUPTED):
+            return None
+        raise CdfError(f"fzf exited with status {returncode}")

cdf/shell/cdf.fish

@@ -0,0 +1,30 @@
+# cdf shell integration for fish. Load it with:
+#   command cdf --init fish | source
+function cdf --description 'Interactively find a directory below here and cd into it'
+    for arg in $argv
+        switch $arg
+            case '--'
+                # Everything after it is search text.
+                break
+            case --help -h --version --init '--init=*'
+                command cdf $argv
+                return
+        end
+    end
+    set -l lines (command cdf $argv)
+    or return
+    # Command substitution splits on newlines and drops only the final one
+    # (the one cdf prints). Rejoin with variable operations: `string join` and
+    # `string collect` would add or trim newlines that belong to the name.
+    set -l target $lines[1]
+    for line in $lines[2..-1]
+        set target "$target"\n"$line"
+    end
+    # Only ever cd into a real directory; anything else (e.g. help text from
+    # combined short flags like -ah) is printed instead.
+    if test -d "$target"
+        cd -- $target
+    else if test -n "$target"
+        printf '%s\n' $target
+    end
+end

cdf/shell/cdf.sh

@@ -0,0 +1,33 @@
+# cdf shell integration for bash and zsh. Load it with:
+#   eval "$(command cdf --init bash)"   # or: --init zsh
+cdf() {
+  # Look at each argument on its own (not "$*", which depends on IFS and would
+  # also match a quoted search term like "foo -h bar"); stop at "--", after
+  # which everything is search text.
+  local arg
+  for arg in "$@"; do
+    case $arg in
+      --) break ;;
+      --help | -h | --version | --init | --init=*)
+        command cdf "$@"
+        return
+        ;;
+    esac
+  done
+  local target
+  # $(...) strips *all* trailing newlines, including ones that are part of
+  # the directory name, so append a "." and then remove it plus the single
+  # newline cdf prints after the path.
+  target="$(command cdf "$@" && printf .)" || return
+  target="${target%.}"
+  target="${target%?}"
+  # Only ever cd into a real directory; anything else (e.g. help text from
+  # combined short flags like -ah) is printed instead.
+  if [ -d "$target" ]; then
+    # \cd: bash/zsh expand aliases when this function is defined, so a plain
+    # `cd` would run e.g. `alias cd=z`. A cd *function* (hooks) still applies.
+    \cd -- "$target"
+  elif [ -n "$target" ]; then
+    printf '%s\n' "$target"
+  fi
+}

cdf/walker.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Collection, Iterator
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Protocol
+
+from cdf.errors import CdfError
+
+
+class DirectoryWalker(Protocol):
+    def walk(
+        self,
+        root: Path,
+        *,
+        git_only: bool,
+        include_hidden: bool,
+        ignore: Collection[str],
+        max_depth: int | None = None,
+        one_file_system: bool = False,
+    ) -> Iterator[Path]: ...
+
+
+def _is_pruned(name: str, *, include_hidden: bool, ignore: Collection[str]) -> bool:
+    if not include_hidden and name.startswith("."):
+        return True
+    return any(fnmatchcase(name, pattern) for pattern in ignore)
+
+
+def _device(entry: os.DirEntry[str]) -> int:
+    return entry.stat(follow_symlinks=False).st_dev
+
+
+class FilesystemWalker:
+    """Depth-first, sorted walk built directly on os.scandir.
+
+    scandir's DirEntry reports symlinks and directory-ness from the directory
+    listing itself, so unlike os.walk plus a per-directory lstat, detecting
+    symlinked directories costs no extra system calls.
+
+    `max_depth` counts levels below the root (1 = only its direct children).
+    With `one_file_system`, mount points below the root are listed but not
+    entered, like `find -xdev`; that costs one stat per kept subdirectory.
+    """
+
+    def walk(
+        self,
+        root: Path,
+        *,
+        git_only: bool,
+        include_hidden: bool,
+        ignore: Collection[str],
+        max_depth: int | None = None,
+        one_file_system: bool = False,
+    ) -> Iterator[Path]:
+        root_device: int | None = None
+        if one_file_system:
+            try:
+                root_device = os.stat(root).st_dev
+            except OSError as exc:
+                raise CdfError(f"cannot read search root {root}: {exc.strerror}") from exc
+        stack = [(root, 0)]
+        while stack:
+            current, depth = stack.pop()
+            # One cheap pass over the listing: is_dir(follow_symlinks=False) and
+            # is_symlink() come from the directory entry itself, so files (the
+            # vast majority) are dismissed without a syscall, prune check or sort.
+            is_repo = False
+            subdirs: list[os.DirEntry[str]] = []
+            links: list[os.DirEntry[str]] = []
+            try:
+                with os.scandir(current) as listing:
+                    for entry in listing:
+                        if entry.name == ".git":
+                            # Marks a repo; never listed or descended into,
+                            # whatever --all or the ignore patterns say.
+                            is_repo = True
+                            continue
+                        try:
+                            if entry.is_dir(follow_symlinks=False):
+                                subdirs.append(entry)
+                            elif entry.is_symlink():
+                                links.append(entry)
+                        except OSError:
+                            # Only this entry is unreadable (e.g. a file system
+                            # without entry types, needing a stat that fails);
+                            # keep its siblings.
+                            continue
+            except OSError as exc:
+                # Unreadable subdirectories are skipped (they can't be cd'd
+                # into anyway), but an unreadable root would otherwise
+                # masquerade as an empty tree.
+                if current == root:
+                    raise CdfError(f"cannot read search root {root}: {exc.strerror}") from exc
+                continue
+
+            if current != root:
+                if git_only and is_repo:
+                    yield current
+                    continue
+                if not git_only:
+                    yield current
+
+            if max_depth is not None and depth >= max_depth:
+                continue
+
+            kept = self._kept(subdirs, include_hidden=include_hidden, ignore=ignore)
+            leaves = self._kept(links, include_hidden=include_hidden, ignore=ignore)
+            if root_device is not None:
+                kept, mounts = self._split_mounts(kept, root_device)
+                leaves = sorted([*leaves, *mounts], key=lambda entry: entry.name)
+
+            for entry in leaves:
+                # Symlinks (so no loops) and, with one_file_system, mount points:
+                # never descended into, but still valid places to cd into, so
+                # offer them as leaves. is_dir() follows links, so broken links
+                # and links to files drop out.
+                path = Path(entry.path)
+                try:
+                    if entry.is_dir() and (not git_only or (path / ".git").exists()):
+                        yield path
+                except OSError:
+                    continue
+
+            # Reversed so the alphabetically first subdirectory is popped next.
+            stack.extend((Path(entry.path), depth + 1) for entry in reversed(kept))
+
+    @staticmethod
+    def _split_mounts(
+        entries: list[os.DirEntry[str]], root_device: int
+    ) -> tuple[list[os.DirEntry[str]], list[os.DirEntry[str]]]:
+        same: list[os.DirEntry[str]] = []
+        mounts: list[os.DirEntry[str]] = []
+        for entry in entries:
+            try:
+                (same if _device(entry) == root_device else mounts).append(entry)
+            except OSError:
+                continue
+        return same, mounts
+
+    @staticmethod
+    def _kept(
+        entries: list[os.DirEntry[str]], *, include_hidden: bool, ignore: Collection[str]
+    ) -> list[os.DirEntry[str]]:
+        kept = [
+            entry
+            for entry in entries
+            if not _is_pruned(entry.name, include_hidden=include_hidden, ignore=ignore)
+        ]
+        kept.sort(key=lambda entry: entry.name)
+        return kept

cdf_shell-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: cdf-shell
+Version: 0.1.0
+Summary: Interactive git-project cd/find
+Author-email: Felipe Ruhland <pypi@feliperuhland.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# cdf
+
+`cdf` ("cd" + "find") interactively searches the directory tree below your
+current working directory for a term, and `cd`s into the directory you
+select.
+
+- Search scope is always the current working directory downward — never the
+  whole filesystem, never a cached/global index.
+- By default it only matches git repository roots and stops descending once
+  it finds one (pass `--no-git` to walk every directory instead).
+- Symlinked directories are listed (in git mode, only if they point at a
+  repository) but never descended into, so symlink loops can't hang the walk.
+- Selection is powered by [`fzf`](https://github.com/junegunn/fzf) 0.44 or
+  newer, which must be on `PATH`. Your `FZF_DEFAULT_OPTS` (theme, layout,
+  `--print-query`, `--accept-nth`, ...) are respected.
+- Results are shown (and fuzzy-matched) relative to the search root, so the
+  root's own path doesn't match every query.
+- Directory names are shown with terminal control characters (escape
+  sequences, newlines, tabs) replaced by `?`, so a hostile name in a cloned
+  repo can't mess with your terminal; the directory you pick is still the
+  exact one on disk.
+
+## Install
+
+### From source
+
+```sh
+uv sync
+```
+
+This installs the `cdf` console script into `.venv/bin/`.
+
+### Arch Linux
+
+A `PKGBUILD` is provided at the repo root, sourcing the tarball from this
+repo's own `v*.*.*` git tags:
+
+```sh
+makepkg -si
+```
+
+`cdf` (the binary) only *resolves* a path and prints it to stdout — a Python
+process can't change its parent shell's working directory. Load the shell
+integration so the `cdf` command actually `cd`s for you:
+
+```sh
+# ~/.bashrc
+eval "$(command cdf --init bash)"
+# ~/.zshrc
+eval "$(command cdf --init zsh)"
+```
+
+```fish
+# ~/.config/fish/config.fish
+command cdf --init fish | source
+```
+
+This defines a shell function also named `cdf`, which takes priority over
+the binary in your shell and calls it internally via `command cdf`. Make
+sure the `cdf` binary itself is on `PATH` (e.g. via `uv tool install .`, or
+by adding `.venv/bin` to `PATH`).
+
+## Usage
+
+```sh
+cdf [term ...] [-p/--path ROOT] [--git/--no-git] [-a/--all|--no-all] [-d/--max-depth N]
+    [-x/--one-file-system|--no-one-file-system] [-c/--config FILE]
+cdf --init {bash,zsh,fish}
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `term ...` | `""` | initial fuzzy filter text passed to `fzf` (several words are joined with spaces) |
+| `-p, --path` | cwd | root to search from |
+| `--git` / `--no-git` | `--git` | only match git repository roots |
+| `-a, --all` / `--no-all` | `--no-all` | include hidden/dot directories |
+| `-d, --max-depth N` | no limit | only look `N` levels below the root (`0` = no limit, to lift a limit set in the config file) |
+| `-x, --one-file-system` / `--no-one-file-system` | off | list mount points but don't descend into them, like `find -xdev` |
+| `-c, --config` | `$CDF_CONFIG_PATH`, else first existing default | config file path |
+| `--init SHELL` | | print the shell integration for `bash`, `zsh` or `fish` and exit |
+
+Run `cdf --help` for the full reference, or `cdf --version` (the shell
+function special-cases `--help`/`-h`/`--version`/`--init` to pass them straight
+through instead of attempting to `cd` into their output).
+
+### Exit codes
+
+- `0` — a directory was selected
+- `1` — nothing was selected (cancelled in `fzf`, or no candidates found, in
+  which case a hint is printed on stderr)
+- `2` — an error occurred (message on stderr) — e.g. `fzf` missing, an
+  unreadable search root, or a bad config file
+- `130` — interrupted with Ctrl-C
+
+## Config file
+
+The config file path is resolved in this order:
+
+1. `-c/--config FILE` — must exist, or it's an error.
+2. `$CDF_CONFIG_PATH` — must exist, or it's an error.
+3. Otherwise, the first of these that exists (silently skipped if none do):
+   `$XDG_CONFIG_HOME/cdf/cdf.conf` (default `~/.config/cdf/cdf.conf`), then
+   `~/cdf.conf`.
+
+All keys are optional (TOML syntax, despite the `.conf` extension):
+
+```toml
+path = "~/projects"  # string, expanded with ~; relative paths are relative to this file
+git = true            # boolean
+hidden = false        # boolean
+ignore = ["node_modules", "__pycache__", ".venv"]  # glob patterns of directory names to skip
+max_depth = 0        # non-negative integer, 0 = no limit
+one_file_system = false  # boolean
+```
+
+`ignore` replaces the default list shown above (set `ignore = []` to skip
+nothing). Patterns match one directory name at a time, so they can't contain
+`/`. `.git` directories are never descended into regardless.
+
+`one_file_system` is off by default because btrfs subvolumes (and some other
+setups) report their own device IDs, so turning it on would hide those
+directories. Turn it on if you run `cdf --no-git` from places like `/` or `~`
+that have network or FUSE mounts below them, which can be slow or hang.
+
+Unknown keys, and values of the wrong type (e.g. `git = "false"` instead of
+`git = false`), are rejected with an error, to catch typos early.
+
+## Development
+
+```sh
+make run    # uv run python -m cdf
+make test   # pytest + ruff + ruff-format + mypy (strict) + coverage, gated at 100%
+make lint   # uv run ruff check .
+make build  # sdist + wheel, with the build backend pinned by hash (build-constraints.txt)
+make build-constraints  # re-lock build-constraints.txt after editing build-constraints.in
+```
+
+Supported Python: 3.11 through 3.14; CI runs the full `make test` gate on
+each, with the bash/zsh/fish wrapper tests running against pinned zsh 5.9
+and fish 4.9.3.

cdf_shell-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+cdf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cdf/__main__.py,sha256=FJykmAcI0-ihJECRdNvnp75UI77f2MbqclG_g7-efVM,122
+cdf/app.py,sha256=-BPLXJlmFrt5pmuwUskcP-fJvf-kY3FSd3Mx-gks24M,1954
+cdf/cli.py,sha256=RxRkMSuL5QZB9i4ScddGLh37RPGfKRnxYoT4HGHNSW4,6968
+cdf/config.py,sha256=aV7K_8fdV6wRaGVXHy1ltWHNukfcKwDdQnO6Wps-Zt4,6832
+cdf/display.py,sha256=QZ0iIp9soeHQnofy86qi7ZTLkqCr7gKYxrAEJYQEG4U,636
+cdf/errors.py,sha256=9x2Y9BX_5Terv6z71CqA4OVtVb-hU1Y2ZicMdw_F6zY,194
+cdf/picker.py,sha256=UaZ1qrasepiuojKCgqXSCSFg8LsTzDrLDxMMjH9GeEM,5287
+cdf/walker.py,sha256=JhGeWDSUaN42RY_5AhGrocjx__qeJ-CAj-_4kilJGsw,5873
+cdf/shell/cdf.fish,sha256=YjiUEp_yS5hx4Z8qX20OG_b2mmKEyU2146x3vZk3GGU,1079
+cdf/shell/cdf.sh,sha256=bWc930bnaxeVBvbvkdrejxtDbi1QR3tWAvS6Uy5laqQ,1204
+cdf_shell-0.1.0.dist-info/METADATA,sha256=p0m8xZniungDMYZUQsdOm-6aMmPiFW8EpZv7auQpPwI,5767
+cdf_shell-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+cdf_shell-0.1.0.dist-info/entry_points.txt,sha256=ATccqID3dNdUxHOL9n2GS8jhLrxzaFOXLoZ-dwnAYmY,37
+cdf_shell-0.1.0.dist-info/licenses/LICENSE,sha256=BME5hjhre9DaiLMUNKMsZEguxSTq48svKM-U4-opgIo,1071
+cdf_shell-0.1.0.dist-info/RECORD,,

cdf_shell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

cdf_shell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cdf = cdf.cli:main

cdf_shell-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Ruhland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.