pcd-cli 0.1.0__tar.gz

pcd_cli-0.1.0/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.

pcd_cli-0.1.0/PKG-INFO

@@ -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/README.txt

@@ -0,0 +1,82 @@
+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/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "pcd-cli"
+version = "0.1.0"
+description = "Fast project navigator for Bash, Zsh and Fish"
+readme = { file = "README.txt", content-type = "text/plain" }
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "pcd-cli contributors" }]
+requires-python = ">=3.14,<4"
+keywords = ["cli", "cd", "projects", "navigation", "bash", "zsh", "fish"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.4.2,<9",
+    "platformdirs>=4.10,<5",
+    "prompt-toolkit>=3.0.53,<4",
+    "tomlkit>=0.15.1,<1",
+]
+
+[project.scripts]
+pcd = "pcd_cli.cli:main"
+
+[build-system]
+requires = ["poetry-core==2.4.1"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "pcd_cli", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+mypy = "2.3.0"
+pre-commit = "4.6.2"
+pytest = "9.1.1"
+pytest-cov = "7.1.0"
+ruff = "0.16.3"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+src = ["src", "tests", "benchmarks"]
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "UP",
+    "A",
+    "B",
+    "N",
+    "SIM",
+    "PERF",
+    "PIE",
+    "RUF",
+    "TC",
+    "TID",
+    "ANN",
+]
+
+[tool.ruff.lint.flake8-type-checking]
+strict = true
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"typing.Any".msg = "Use precise types instead of Any."
+"typing.cast".msg = "Narrow types explicitly instead of using cast()."
+
+[tool.ruff.lint.isort]
+known-first-party = ["pcd_cli"]
+combine-as-imports = true
+order-by-type = false
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+warn_unreachable = true
+show_error_codes = true
+pretty = true
+files = ["src", "tests", "benchmarks"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["pcd_cli"]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+skip_covered = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+]

pcd_cli-0.1.0/src/pcd_cli/cache.py

@@ -0,0 +1,118 @@
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, TypedDict, TypeIs
+
+from pcd_cli.filesystem import atomic_write, file_lock
+from pcd_cli.models import Project, ProjectSource
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+
+class _CacheReadError(Exception):
+    """The on-disk cache cannot be read as a valid cache snapshot."""
+
+
+class ProjectCacheEntry(TypedDict):
+    name: str
+    path: str
+    display: str
+    source: str
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectCache:
+    """Disposable JSONL index of known projects."""
+
+    path: Path
+
+    def load(self) -> list[Project] | None:
+        if not self.path.is_file():
+            return None
+
+        try:
+            return [_decode_project(entry) for entry in self._entries()]
+        except _CacheReadError:
+            return None
+
+    def find_exact(self, query: str) -> list[Project] | None:
+        if not self.path.is_file():
+            return None
+
+        needle = query.casefold()
+        try:
+            return [
+                _decode_project(entry)
+                for entry in self._entries()
+                if entry["name"].casefold() == needle
+            ]
+        except _CacheReadError:
+            return None
+
+    def find_prefix(self, query: str) -> list[Project] | None:
+        if not self.path.is_file():
+            return None
+
+        needle = query.casefold()
+        try:
+            return [
+                _decode_project(entry)
+                for entry in self._entries()
+                if entry["name"].casefold().startswith(needle)
+            ]
+        except _CacheReadError:
+            return None
+
+    def save(self, projects: Iterable[Project]) -> None:
+        # JSONL keeps refresh streaming and avoids a second in-memory JSON tree.
+        with file_lock(self.path), atomic_write(self.path) as stream:
+            for project in projects:
+                entry: ProjectCacheEntry = {
+                    "name": project.name,
+                    "path": str(project.path),
+                    "display": str(project.display_path),
+                    "source": project.source.value,
+                }
+                json.dump(entry, stream, ensure_ascii=False, separators=(",", ":"))
+                stream.write("\n")
+
+    def _entries(self) -> Iterator[ProjectCacheEntry]:
+        try:
+            with self.path.open(encoding="utf-8") as stream:
+                for line in stream:
+                    try:
+                        raw: object = json.loads(line)
+                    except json.JSONDecodeError as exc:
+                        raise _CacheReadError("Invalid cache JSON") from exc
+                    if not _is_cache_entry(raw):
+                        raise _CacheReadError("Invalid cache entry")
+                    yield raw
+        except (OSError, UnicodeError) as exc:
+            raise _CacheReadError("Cannot read cache") from exc
+
+
+def _is_cache_entry(value: object) -> TypeIs[ProjectCacheEntry]:
+    if not isinstance(value, dict):
+        return False
+
+    return (
+        isinstance(value.get("name"), str)
+        and isinstance(value.get("path"), str)
+        and isinstance(value.get("display"), str)
+        and isinstance(value.get("source"), str)
+    )
+
+
+def _decode_project(entry: ProjectCacheEntry) -> Project:
+    try:
+        source = ProjectSource(entry["source"])
+    except ValueError as exc:
+        raise _CacheReadError("Invalid project source") from exc
+
+    return Project(
+        name=entry["name"],
+        path=Path(entry["path"]),
+        display_path=Path(entry["display"]),
+        source=source,
+    )

pcd_cli-0.1.0/src/pcd_cli/catalog.py

@@ -0,0 +1,157 @@
+from dataclasses import dataclass
+from typing import Self, TYPE_CHECKING
+
+from pcd_cli.cache import ProjectCache
+from pcd_cli.config import Config
+from pcd_cli.filesystem import ApplicationPaths, canonical_path
+from pcd_cli.history import UsageHistory
+from pcd_cli.scanner import ProjectScanner
+from pcd_cli.search import rank_matches
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from pcd_cli.models import Project
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectCatalog:
+    """Coordinate project configuration, discovery, cache, and usage history."""
+
+    config: Config
+    cache: ProjectCache
+    history: UsageHistory
+
+    @classmethod
+    def create(cls) -> Self:
+        paths = ApplicationPaths.resolve()
+        return cls(
+            config=Config(paths.config),
+            cache=ProjectCache(paths.cache),
+            history=UsageHistory(paths.history),
+        )
+
+    def projects(self) -> list[Project]:
+        if cached := self.cache.load():
+            return cached
+
+        return self.refresh()
+
+    def completion_candidates(self, query: str) -> Iterator[Project]:
+        matches = self.cache.find_prefix(query)
+        if matches is not None:
+            yield from matches
+
+    def search(self, query: str, exact_only: bool = False) -> list[Project]:
+        # The common exact-hit path avoids loading the full cache and history.
+        exact_matches = self.cache.find_exact(query)
+        if exact_matches is None:
+            return self._search_projects(self.refresh(), query, exact_only)
+
+        if exact_matches:
+            if len(exact_matches) == 1:
+                return exact_matches
+            return rank_matches(exact_matches, query, self.history.load())
+
+        if exact_only:
+            return self._search_projects(self.refresh(), query, exact_only=True)
+
+        cached = self.cache.load()
+        if cached is None:
+            return self._search_projects(self.refresh(), query, exact_only=False)
+
+        usage = self.history.load()
+        matches = rank_matches(cached, query, usage)
+        if matches:
+            return matches
+
+        # A miss can mean a repository appeared after the last refresh.
+        return rank_matches(self.refresh(), query, usage)
+
+    def refresh(self) -> list[Project]:
+        settings = self.config.load()
+        projects = list(settings.manual_projects)
+        known_paths = {project.path for project in projects}
+
+        for project in ProjectScanner(settings).scan():
+            if project.path in known_paths:
+                continue
+
+            known_paths.add(project.path)
+            projects.append(project)
+
+        projects.sort(key=lambda project: (project.name.casefold(), str(project.path)))
+        self.cache.save(projects)
+
+        return projects
+
+    def record_usage(self, project: Project) -> None:
+        self.history.record(project.path)
+
+    def add_scan_root(self, root: Path) -> bool:
+        if not self.config.add_root(root):
+            return False
+
+        self.refresh()
+
+        return True
+
+    def remove_scan_root(self, root: Path) -> bool:
+        if not self.config.remove_root(root):
+            return False
+
+        self.refresh()
+
+        return True
+
+    def add_project(self, project: Project) -> bool:
+        # An authoritative scan prevents stale cache data from hiding a repository.
+        if any(item.path == project.path for item in self.refresh()):
+            return False
+
+        if not self.config.add_project(project):
+            return False
+
+        # Rebuild from committed config instead of extending a potentially stale snapshot.
+        self.refresh()
+
+        return True
+
+    def remove_project(self, path: Path) -> bool:
+        if not self.config.remove_project(path):
+            return False
+
+        self.refresh()
+
+        return True
+
+    def find_parent_root(self, path: Path) -> Path | None:
+        target = canonical_path(path)
+        closest_root: Path | None = None
+        closest_depth = -1
+
+        for root in self.config.load().roots:
+            resolved_root = canonical_path(root)
+            if resolved_root == target or not target.is_relative_to(resolved_root):
+                continue
+
+            root_depth = len(resolved_root.parts)
+            if root_depth > closest_depth:
+                closest_root = root
+                closest_depth = root_depth
+
+        return closest_root
+
+    def _search_projects(
+        self,
+        projects: list[Project],
+        query: str,
+        exact_only: bool,
+    ) -> list[Project]:
+        needle = query.casefold()
+        exact_matches = [project for project in projects if project.name.casefold() == needle]
+        if exact_matches or exact_only:
+            return exact_matches
+
+        return rank_matches(projects, query, self.history.load())