pcd-cli 0.1.0__py3-none-any.whl

pcd_cli/scanner.py

@@ -0,0 +1,116 @@
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pcd_cli.filesystem import canonical_path
+from pcd_cli.models import Project, ProjectSource
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from pcd_cli.models import ProjectSettings
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectScanner:
+    settings: ProjectSettings
+
+    def scan(self) -> Iterator[Project]:
+        for root, display_path in self._scan_roots():
+            yield from self._walk(root, display_path)
+
+    def _scan_roots(self) -> list[tuple[Path, Path]]:
+        roots = sorted(
+            ((canonical_path(root), root.expanduser()) for root in self.settings.roots),
+            key=lambda item: (len(item[0].parts), str(item[0])),
+        )
+        selected: dict[Path, Path] = {}
+
+        for root, display_path in roots:
+            parent = next((item for item in root.parents if item in selected), None)
+            if parent is not None and self._reachable_from_parent(root, parent):
+                continue
+            selected[root] = display_path
+
+        return list(selected.items())
+
+    def _reachable_from_parent(self, root: Path, parent: Path) -> bool:
+        relative = root.relative_to(parent)
+        current = parent
+
+        for part in relative.parts:
+            blocked = part in self.settings.excluded_names
+            hidden = not self.settings.include_hidden and part.startswith(".")
+            if blocked or hidden or _is_git_repository(current):
+                return False
+            current /= part
+
+        return True
+
+    def _walk(self, root: Path, display_path: Path) -> Iterator[Project]:
+        if not root.is_dir():
+            return
+
+        visited = set[tuple[int, int]]() if self.settings.follow_symlinks else None
+
+        for directory, directories, _files in os.walk(
+            root,
+            topdown=True,
+            followlinks=self.settings.follow_symlinks,
+        ):
+            current = Path(directory)
+            active = True if visited is None else _mark_visited(current, visited)
+            if not active:
+                directories.clear()
+                continue
+
+            relative = current.relative_to(root)
+            shown = display_path / relative
+
+            if _is_git_repository(current):
+                directories.clear()
+                path = canonical_path(current) if self.settings.follow_symlinks else current
+                yield Project(current.name, path, shown, ProjectSource.DISCOVERED)
+                continue
+
+            descend_into: list[str] = []
+            for name in directories:
+                child = current / name
+                blocked = name == ".git" or name in self.settings.excluded_names
+                hidden = not self.settings.include_hidden and name.startswith(".")
+                linked = not self.settings.follow_symlinks and child.is_symlink()
+
+                if blocked or hidden:
+                    continue
+                if linked:
+                    if _is_git_repository(child):
+                        yield Project(
+                            name,
+                            canonical_path(child),
+                            shown / name,
+                            ProjectSource.DISCOVERED,
+                        )
+                    continue
+                descend_into.append(name)
+
+            # os.walk descends only into names left in directories when topdown=True.
+            directories[:] = descend_into
+
+
+def _mark_visited(path: Path, visited: set[tuple[int, int]]) -> bool:
+    try:
+        stat = path.stat()
+    except OSError:
+        return False
+
+    key = (stat.st_dev, stat.st_ino)
+    if key in visited:
+        return False
+
+    visited.add(key)
+    return True
+
+
+def _is_git_repository(path: Path) -> bool:
+    return (path / ".git").exists()

pcd_cli/search.py

@@ -0,0 +1,108 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+    from pathlib import Path
+
+    from pcd_cli.models import Project, ProjectUsage
+
+ProjectRank = tuple[int, int, float, int, int, str, str]
+
+EXACT_WEIGHT = 16
+PREFIX_WEIGHT = 12
+SUBSTRING_WEIGHT = 10
+MATCH_POINTS = 4
+BOUNDARY_BONUS = 5
+ADJACENT_BONUS = 3
+MAX_GAP_PENALTY = 4
+
+
+def rank_matches(
+    projects: Iterable[Project],
+    query: str,
+    usage: Mapping[Path, ProjectUsage] | None = None,
+) -> list[Project]:
+    needle = query.casefold()
+    matches: list[tuple[ProjectRank, Project]] = []
+
+    for project in projects:
+        score = _score(needle, project.name.casefold())
+        if score is None:
+            continue
+
+        match_kind, points = score
+        project_usage = None if usage is None else usage.get(project.path)
+        used_at = 0.0 if project_usage is None else project_usage.used_at
+        count = 0 if project_usage is None else project_usage.count
+        rank: ProjectRank = (
+            match_kind,
+            -points,
+            -used_at,
+            -count,
+            len(project.name),
+            project.name.casefold(),
+            str(project.path),
+        )
+        matches.append((rank, project))
+
+    matches.sort(key=lambda item: item[0])
+    return [project for _, project in matches]
+
+
+def rank_recent(
+    projects: Iterable[Project],
+    usage: Mapping[Path, ProjectUsage],
+) -> list[Project]:
+    ranked_projects = list(projects)
+
+    def usage_rank(project: Project) -> tuple[float, int, str, str]:
+        project_usage = usage.get(project.path)
+        return (
+            0.0 if project_usage is None else -project_usage.used_at,
+            0 if project_usage is None else -project_usage.count,
+            project.name.casefold(),
+            str(project.path),
+        )
+
+    ranked_projects.sort(key=usage_rank)
+    return ranked_projects
+
+
+def _score(query: str, name: str) -> tuple[int, int] | None:
+    if name == query:
+        return 0, len(query) * EXACT_WEIGHT
+    if name.startswith(query):
+        return 1, len(query) * PREFIX_WEIGHT - (len(name) - len(query))
+
+    position = name.find(query)
+    if position >= 0:
+        return 2, len(query) * SUBSTRING_WEIGHT - position
+
+    query_index = 0
+    previous = -2
+    points = 0
+
+    for index, char in enumerate(name):
+        if query_index == len(query):
+            break
+        if char != query[query_index]:
+            continue
+
+        points += MATCH_POINTS
+        points += BOUNDARY_BONUS if index == 0 or name[index - 1] in "-_./ " else 0
+
+        if previous >= 0:
+            points += (
+                ADJACENT_BONUS
+                if index == previous + 1
+                else -min(index - previous - 1, MAX_GAP_PENALTY)
+            )
+
+        previous = index
+        query_index += 1
+
+    if query_index != len(query):
+        return None
+
+    penalty = max(len(name) - len(query), 0) // 2
+    return 3, points - penalty

pcd_cli/shell_integration.py

@@ -0,0 +1,264 @@
+"""Generate, install, and inspect shell integration for pcd."""
+
+import os
+import stat
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from textwrap import dedent
+from typing import Self
+
+from pcd_cli.filesystem import atomic_write, file_lock
+
+SHELL_MODE_ENV = "PCD_SHELL"
+# Internal success status: stdout contains the destination path when this is returned.
+SHELL_CD_EXIT_CODE = 10
+_MANAGED_BLOCK_START = "# >>> pcd shell integration >>>"
+_MANAGED_BLOCK_END = "# <<< pcd shell integration <<<"
+
+
+class ShellIntegrationError(Exception):
+    """Persistent shell integration cannot be inspected or managed safely."""
+
+
+class Shell(StrEnum):
+    BASH = "bash"
+    ZSH = "zsh"
+    FISH = "fish"
+
+
+class ShellIntegrationState(StrEnum):
+    ABSENT = "not installed"
+    MANUAL = "configured manually"
+    MANAGED = "installed by pcd"
+
+
+@dataclass(frozen=True, slots=True)
+class ShellIntegration:
+    shell: Shell
+    config_path: Path
+
+    @classmethod
+    def detect(cls) -> Self:
+        return cls.for_shell(detect_shell())
+
+    @classmethod
+    def for_shell(cls, shell: Shell) -> Self:
+        return cls(shell=shell, config_path=shell_config_path(shell))
+
+    def state(self) -> ShellIntegrationState:
+        return _integration_state(self._read(), self.shell)
+
+    def install(self) -> bool:
+        """Install the managed block. Return whether the config changed."""
+        with file_lock(self.config_path):
+            content = self._read()
+            if _integration_state(content, self.shell) is not ShellIntegrationState.ABSENT:
+                return False
+
+            separator = "" if not content or content.endswith("\n") else "\n"
+            self._write(f"{content}{separator}{render_managed_block(self.shell)}")
+            return True
+
+    def uninstall(self) -> bool:
+        """Remove only a pcd-managed block, leaving manual setup untouched."""
+        with file_lock(self.config_path):
+            content = self._read()
+            bounds = _managed_block_bounds(content)
+            if bounds is None:
+                return False
+
+            start, end = bounds
+            self._write(f"{content[:start]}{content[end:]}")
+            return True
+
+    def _read(self) -> str:
+        try:
+            return self.config_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return ""
+        except UnicodeError as exc:
+            raise ShellIntegrationError(
+                f"Shell config is not valid UTF-8: {self.config_path}"
+            ) from exc
+
+    def _write(self, content: str) -> None:
+        target = (
+            self.config_path.resolve(strict=False)
+            if self.config_path.is_symlink()
+            else self.config_path
+        )
+        mode = stat.S_IMODE(target.stat().st_mode) if target.exists() else None
+
+        with atomic_write(target) as stream:
+            stream.write(content)
+
+        if mode is not None:
+            target.chmod(mode)
+
+
+def detect_shell() -> Shell:
+    """Detect the user's login shell from the standard SHELL environment variable."""
+    executable = os.environ.get("SHELL", "")
+    name = Path(executable).name.casefold()
+    try:
+        return Shell(name)
+    except ValueError as exc:
+        supported = ", ".join(shell.value for shell in Shell)
+        raise ShellIntegrationError(
+            f"Cannot detect a supported shell from SHELL={executable!r}; choose one of: {supported}"
+        ) from exc
+
+
+def shell_config_path(shell: Shell) -> Path:
+    """Return the startup file where persistent integration should be installed."""
+    home = Path.home()
+    if shell is Shell.BASH:
+        return home / ".bashrc"
+    if shell is Shell.ZSH:
+        zdotdir = os.environ.get("ZDOTDIR")
+        return (Path(zdotdir).expanduser() if zdotdir else home) / ".zshrc"
+
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    config_home = Path(xdg_config_home).expanduser() if xdg_config_home else home / ".config"
+    return config_home / "fish" / "config.fish"
+
+
+def shell_integration_active() -> bool:
+    return os.environ.get(SHELL_MODE_ENV) == "1"
+
+
+def inactive_shell_message() -> str:
+    """Explain how to activate directory changes when the wrapper is not running."""
+    try:
+        integration = ShellIntegration.detect()
+        state = integration.state()
+    except OSError, ShellIntegrationError:
+        return (
+            "Shell integration is not active, so pcd cannot change this shell's directory. "
+            "If you have not configured it manually, run: pcd shell install"
+        )
+
+    if state is ShellIntegrationState.ABSENT:
+        return (
+            "Shell integration is not installed, so pcd cannot change this shell's directory. "
+            "Install it with: pcd shell install"
+        )
+    return (
+        f"Shell integration is configured in {integration.config_path} but is not active in "
+        f"this shell. Restart it or run: exec {integration.shell.value}"
+    )
+
+
+def render_managed_block(shell: Shell) -> str:
+    """Render the small persistent block written into the shell startup file."""
+    command = (
+        f'eval "$(command pcd shell print {shell.value})"'
+        if shell is not Shell.FISH
+        else f"command pcd shell print {shell.value} | source"
+    )
+    return f"{_MANAGED_BLOCK_START}\n{command}\n{_MANAGED_BLOCK_END}\n"
+
+
+def render_shell_integration(shell: Shell) -> str:
+    """Generate shell integration for directory changes and Click completion."""
+    return _fish() if shell is Shell.FISH else _posix(shell)
+
+
+def _integration_state(content: str, shell: Shell) -> ShellIntegrationState:
+    bounds = _managed_block_bounds(content)
+    if bounds is not None:
+        return ShellIntegrationState.MANAGED
+
+    legacy = f"pcd shell-init {shell.value}"
+    current = f"pcd shell print {shell.value}"
+    if legacy in content or current in content:
+        return ShellIntegrationState.MANUAL
+    return ShellIntegrationState.ABSENT
+
+
+def _managed_block_bounds(content: str) -> tuple[int, int] | None:
+    starts = content.count(_MANAGED_BLOCK_START)
+    ends = content.count(_MANAGED_BLOCK_END)
+    if starts == 0 and ends == 0:
+        return None
+    if starts != 1 or ends != 1:
+        raise ShellIntegrationError(
+            "Shell config contains an invalid pcd-managed integration block"
+        )
+
+    start = content.index(_MANAGED_BLOCK_START)
+    end_marker = content.index(_MANAGED_BLOCK_END)
+    if end_marker < start:
+        raise ShellIntegrationError(
+            "Shell config contains an invalid pcd-managed integration block"
+        )
+
+    end = end_marker + len(_MANAGED_BLOCK_END)
+    if end < len(content) and content[end] == "\n":
+        end += 1
+    return start, end
+
+
+def _posix(shell: Shell) -> str:
+    completion = "bash_source" if shell is Shell.BASH else "zsh_source"
+    return dedent(
+        f"""\
+        pcd() {{
+            if [ -n "${{_PCD_COMPLETE:-}}" ]; then
+                command pcd "$@"
+                return $?
+            fi
+
+            local output code
+            if output="$({SHELL_MODE_ENV}=1 command pcd "$@")"; then
+                code=0
+            else
+                code=$?
+            fi
+
+            if [ "$code" -eq {SHELL_CD_EXIT_CODE} ]; then
+                builtin cd -- "$output"
+                return $?
+            fi
+            if [ "$code" -ne 0 ]; then
+                return "$code"
+            fi
+            if [ -n "$output" ]; then
+                printf '%s\n' "$output"
+            fi
+        }}
+
+        eval "$(_PCD_COMPLETE={completion} command pcd)"
+        """
+    )
+
+
+def _fish() -> str:
+    return dedent(
+        f"""\
+        function pcd
+            if set -q _PCD_COMPLETE
+                command pcd $argv
+                return $status
+            end
+
+            set -l output (env {SHELL_MODE_ENV}=1 command pcd $argv)
+            set -l code $status
+            if test $code -eq {SHELL_CD_EXIT_CODE}
+                cd -- "$output"
+                return $status
+            end
+            if test $code -ne 0
+                return $code
+            end
+            if test -n "$output"
+                printf '%s\n' "$output"
+            end
+        end
+
+        set -lx _PCD_COMPLETE fish_source
+        command pcd | source
+        set -e _PCD_COMPLETE
+        """
+    )

pcd_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: pcd-cli
+Version: 0.1.0
+Summary: Fast project navigator for Bash, Zsh and Fish
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,cd,projects,navigation,bash,zsh,fish
+Author: pcd-cli contributors
+Requires-Python: >=3.14,<4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Dist: click (>=8.4.2,<9)
+Requires-Dist: platformdirs (>=4.10,<5)
+Requires-Dist: prompt-toolkit (>=3.0.53,<4)
+Requires-Dist: tomlkit (>=0.15.1,<1)
+Description-Content-Type: text/plain
+
+Project cd
+==========
+
+pcd (project cd) - Is a fast way to jump between projects from your terminal
+
+Instead of:
+    cd ~/development/github/palantir/backend/pigeon-surveillance
+Just:
+    pcd pigeon-surveillance
+
+Supported shells:
+* Bash
+* Zsh
+* Fish
+
+
+INSTALL
+-------
+    pipx install --python python3.14 git+https://github.com/jestenough/pcd.git
+    pcd shell install
+Restart your shell after installing shell integration.
+
+
+QUICK START
+----------
+    cd <your root folder, e.g. ~/Github/>
+    pcd init
+    pcd <project name from your root folder>
+pcd discovers projects inside registered scan roots.
+
+
+COMMANDS
+--------
+
+    pcd <project>                Jump to a project
+    pcd                          Show help
+
+    pcd add <path>               Add a project manually
+    pcd remove <project>         Remove a manual project
+
+    pcd init                     Add the current directory as a scan root
+    pcd uninit                   Remove the current directory from scan roots
+    pcd roots                    List scan roots
+    pcd refresh                  Rescan roots and rebuild the project cache
+
+    pcd list                     List all known projects
+    pcd config-path              Print the configuration file path
+
+    pcd shell install            Install shell integration
+    pcd shell status             Show shell integration status
+    pcd shell uninstall          Remove shell integration
+
+    pcd --project <project>      Jump to a project whose name matches a command
+    pcd --version                Show version
+    pcd --help                   Show help
+
+* Projects inside registered roots are discovered automatically.
+* You can register multiple scan roots.
+
+
+DEVELOPMENT
+-----------
+    make install
+    make check
+    make build
+See ./dist folder
+You can install *.whl with your python package manager
+
+
+SEE ALSO
+--------
+    Features:
+        FEATURES.txt
+
+    Planned changes:
+        ROADMAP.md
+
+    Changelog:
+        CHANGELOG.md
+
+    License:
+        MIT
+

pcd_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+pcd_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pcd_cli/cache.py,sha256=tVXS4yNc5vKHwjfnpro39Fm9cSQg3qTVHYX4UHfQKo8,3655
+pcd_cli/catalog.py,sha256=kGnR1hOkMmDS_N1AX5PP0PD3NJXCZuffuD2ryFZOg6c,4841
+pcd_cli/cli.py,sha256=91Px-y00OC-K7-6dUKnzXCRlzjVhBgJSXRNspdUJYV8,11469
+pcd_cli/config.py,sha256=U1kT6ehbklI6-YhQjWqmQWftDaskqp9MjVqtI5OmrVo,7519
+pcd_cli/filesystem.py,sha256=FcUJKRm0y9ujd4vB5vRgahcIOJFt5sVTmgpVMywuZfI,2268
+pcd_cli/history.py,sha256=phlefu3isprF-Xo95DRdjPRVAbspI8vZf19C3Ai1IHc,2825
+pcd_cli/models.py,sha256=7oKtD_c3PEEbpXFVABCf62OqMBzvSiaHI5ZTBtm_XBQ,731
+pcd_cli/navigation.py,sha256=Z9zXpMzohDxIGCwoMNAhmZaSDUAB7srIQmozDe70Ysc,2523
+pcd_cli/picker.py,sha256=Jbja0SAH6H6G0nWVsDooXckdlqpA4KjNxMPKcTSYuLw,5163
+pcd_cli/scanner.py,sha256=2a0tgEg-D-sx7q5OsK7yRCSlhssaQXlICmyFaTWhPAw,3869
+pcd_cli/search.py,sha256=cTI7qWc35Y3vTOk9nPVzb1wzikd0fBjUUHMiF4nzWAA,2976
+pcd_cli/shell_integration.py,sha256=1i_-efl4kIqh8YY5hRdLCk55T469Wb9ZGTLVM7NaJTQ,8321
+pcd_cli-0.1.0.dist-info/METADATA,sha256=Oh7vjV2RDsKXDlPT4QbqQai_RbrUlvfnzrDZb3zNnHg,2752
+pcd_cli-0.1.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+pcd_cli-0.1.0.dist-info/entry_points.txt,sha256=3ZMnsucwvrxf64c1yhIJnXmB_Xxz-4ICL74ibZdpjSU,40
+pcd_cli-0.1.0.dist-info/licenses/LICENSE,sha256=X2MjaqUh65CgyVR4rWS1nWM82z1Z6FLV7R8bBaH6590,1077
+pcd_cli-0.1.0.dist-info/RECORD,,

pcd_cli-0.1.0.dist-info/WHEEL

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

pcd_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pcd=pcd_cli.cli:main
+

pcd_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pcd-cli contributors
+
+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.