pcd-cli 0.1.0__py3-none-any.whl

pcd_cli/config.py

@@ -0,0 +1,226 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeIs
+
+import tomlkit
+
+from pcd_cli.filesystem import atomic_write, canonical_path, file_lock
+from pcd_cli.models import Project, ProjectSettings, ProjectSource
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from tomlkit import TOMLDocument
+
+ROOT_KEYS = frozenset({"roots", "scan", "projects"})
+SCAN_KEYS = frozenset({"hidden", "follow_symlinks", "exclude"})
+PROJECT_KEYS = frozenset({"name", "path"})
+
+DEFAULT_EXCLUDED_NAMES = frozenset(
+    {
+        ".cache",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        "target",
+        "vendor",
+        "venv",
+    }
+)
+
+
+class InvalidConfigError(RuntimeError):
+    """The configuration exists but cannot be interpreted safely."""
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    path: Path
+
+    def load(self) -> ProjectSettings:
+        return _decode_settings(self._read().unwrap())
+
+    def add_root(self, root: Path) -> bool:
+        display_path = root.expanduser()
+        target = canonical_path(display_path)
+
+        with file_lock(self.path):
+            document = self._read()
+            settings = _decode_settings(document.unwrap())
+            if any(canonical_path(item) == target for item in settings.roots):
+                return False
+
+            document["roots"] = [str(item) for item in (*settings.roots, display_path)]
+            self._write(document)
+            return True
+
+    def remove_root(self, root: Path) -> bool:
+        target = canonical_path(root)
+
+        with file_lock(self.path):
+            document = self._read()
+            settings = _decode_settings(document.unwrap())
+            roots = tuple(item for item in settings.roots if canonical_path(item) != target)
+            if len(roots) == len(settings.roots):
+                return False
+
+            document["roots"] = [str(item) for item in roots]
+            self._write(document)
+            return True
+
+    def add_project(self, project: Project) -> bool:
+        if project.source is not ProjectSource.MANUAL:
+            raise ValueError("Only manual projects belong in the config")
+
+        with file_lock(self.path):
+            document = self._read()
+            settings = _decode_settings(document.unwrap())
+            if any(item.path == project.path for item in settings.manual_projects):
+                return False
+
+            document["projects"] = [
+                {"name": item.name, "path": str(item.display_path)}
+                for item in (*settings.manual_projects, project)
+            ]
+            self._write(document)
+            return True
+
+    def remove_project(self, path: Path) -> bool:
+        target = canonical_path(path)
+
+        with file_lock(self.path):
+            document = self._read()
+            settings = _decode_settings(document.unwrap())
+            projects = tuple(item for item in settings.manual_projects if item.path != target)
+            if len(projects) == len(settings.manual_projects):
+                return False
+
+            document["projects"] = [
+                {"name": item.name, "path": str(item.display_path)} for item in projects
+            ]
+            self._write(document)
+            return True
+
+    def _read(self) -> TOMLDocument:
+        if not self.path.is_file():
+            return _default_document()
+
+        text = self.path.read_text(encoding="utf-8")
+        try:
+            return tomlkit.parse(text)
+        except tomlkit.exceptions.ParseError as exc:
+            raise InvalidConfigError(f"Invalid TOML in {self.path}") from exc
+
+    def _write(self, document: TOMLDocument) -> None:
+        with atomic_write(self.path) as stream:
+            stream.write(tomlkit.dumps(document))
+
+
+def _default_document() -> TOMLDocument:
+    document = tomlkit.document()
+    document.add(tomlkit.comment("pcd-cli configuration"))
+    document["roots"] = []
+
+    scan = tomlkit.table()
+    scan["hidden"] = True
+    scan["follow_symlinks"] = False
+    scan["exclude"] = sorted(DEFAULT_EXCLUDED_NAMES)
+    document["scan"] = scan
+    document["projects"] = tomlkit.aot()
+    return document
+
+
+def _decode_settings(value: object) -> ProjectSettings:
+    config = _table(value, "Config root must be a table")
+    _validate_keys(config, ROOT_KEYS, "config")
+    roots = tuple(
+        _absolute_path(item, "root path") for item in _array(config.get("roots", []), "roots")
+    )
+    manual_projects = tuple(
+        _decode_manual_project(item) for item in _array(config.get("projects", []), "projects")
+    )
+    scan = _table(config.get("scan", {}), "scan must be a table")
+    _validate_keys(scan, SCAN_KEYS, "scan")
+    include_hidden = _boolean(scan.get("hidden", True), "scan.hidden")
+    follow_symlinks = _boolean(scan.get("follow_symlinks", False), "scan.follow_symlinks")
+    excluded_names = frozenset(
+        _text(item, "scan.exclude item")
+        for item in _array(
+            scan.get("exclude", list(DEFAULT_EXCLUDED_NAMES)),
+            "scan.exclude",
+        )
+    )
+
+    if len({canonical_path(root) for root in roots}) != len(roots):
+        raise InvalidConfigError("Config contains duplicate roots")
+    if len({project.path for project in manual_projects}) != len(manual_projects):
+        raise InvalidConfigError("Config contains duplicate manual projects")
+
+    return ProjectSettings(
+        roots=roots,
+        manual_projects=manual_projects,
+        include_hidden=include_hidden,
+        follow_symlinks=follow_symlinks,
+        excluded_names=excluded_names,
+    )
+
+
+def _decode_manual_project(value: object) -> Project:
+    project = _table(value, "project entries must be tables")
+    _validate_keys(project, PROJECT_KEYS, "project")
+    name = _text(project.get("name"), "project name")
+    display_path = _absolute_path(project.get("path"), "project path")
+    return Project(
+        name=name,
+        path=canonical_path(display_path),
+        display_path=display_path,
+        source=ProjectSource.MANUAL,
+    )
+
+
+def _table(value: object, message: str) -> Mapping[str, object]:
+    if not _is_table(value):
+        raise InvalidConfigError(message)
+    return value
+
+
+def _is_table(value: object) -> TypeIs[Mapping[str, object]]:
+    return isinstance(value, dict) and all(isinstance(key, str) for key in value)
+
+
+def _validate_keys(table: Mapping[str, object], allowed: frozenset[str], name: str) -> None:
+    unknown = sorted(set(table) - allowed)
+    if unknown:
+        joined = ", ".join(unknown)
+        raise InvalidConfigError(f"Unknown {name} key(s): {joined}")
+
+
+def _array(value: object, name: str) -> list[object]:
+    if not isinstance(value, list):
+        raise InvalidConfigError(f"{name} must be an array")
+    return value
+
+
+def _text(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise InvalidConfigError(f"{name} must be a non-empty string")
+    return value
+
+
+def _absolute_path(value: object, name: str) -> Path:
+    try:
+        path = Path(_text(value, name)).expanduser()
+    except RuntimeError as exc:
+        raise InvalidConfigError(f"{name} contains an unknown home directory") from exc
+
+    if not path.is_absolute():
+        raise InvalidConfigError(f"{name} must be absolute or start with ~")
+    return path
+
+
+def _boolean(value: object, name: str) -> bool:
+    if not isinstance(value, bool):
+        raise InvalidConfigError(f"{name} must be a boolean")
+    return value

pcd_cli/filesystem.py

@@ -0,0 +1,79 @@
+import fcntl
+import os
+import tempfile
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Self, TextIO, TYPE_CHECKING
+
+from platformdirs import PlatformDirs
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+APP_NAME = "pcd-cli"
+CONFIG_FILENAME = "config.toml"
+CACHE_FILENAME = "projects.jsonl"
+HISTORY_FILENAME = "history.json"
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationPaths:
+    config: Path
+    cache: Path
+    history: Path
+
+    @classmethod
+    def resolve(cls) -> Self:
+        directories = PlatformDirs(APP_NAME, appauthor=False)
+        return cls(
+            config=directories.user_config_path / CONFIG_FILENAME,
+            cache=directories.user_cache_path / CACHE_FILENAME,
+            history=directories.user_state_path / HISTORY_FILENAME,
+        )
+
+
+def canonical_path(path: Path) -> Path:
+    return path.expanduser().resolve(strict=False)
+
+
+def format_path(path: Path) -> str:
+    home = Path.home()
+    if not path.is_relative_to(home):
+        return str(path)
+
+    relative = path.relative_to(home)
+    return "~" if not relative.parts else f"~/{relative}"
+
+
+@contextmanager
+def file_lock(path: Path) -> Generator[None]:
+    """Prevent concurrent writers from overwriting each other's changes."""
+    lock_path = path.with_name(f".{path.name}.lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with lock_path.open("a+", encoding="utf-8") as stream:
+        fcntl.flock(stream.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(stream.fileno(), fcntl.LOCK_UN)
+
+
+@contextmanager
+def atomic_write(path: Path) -> Generator[TextIO]:
+    """Write through a temporary file so readers never observe partial data."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary_path = Path(temporary_name)
+
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            yield stream
+            stream.flush()
+            os.fsync(stream.fileno())
+
+        os.replace(temporary_path, path)
+    except BaseException:
+        temporary_path.unlink(missing_ok=True)
+        raise

pcd_cli/history.py

@@ -0,0 +1,95 @@
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypedDict, TypeIs
+
+from pcd_cli.filesystem import atomic_write, file_lock
+from pcd_cli.models import ProjectUsage
+
+DEFAULT_HISTORY_LIMIT = 2048
+
+
+class UsageHistoryEntry(TypedDict):
+    used_at: int | float
+    count: int
+
+
+@dataclass(frozen=True, slots=True)
+class UsageHistory:
+    """Bounded usage history used as a tie-breaker during search."""
+
+    path: Path
+    limit: int = DEFAULT_HISTORY_LIMIT
+
+    def load(self) -> dict[Path, ProjectUsage]:
+        if not self.path.is_file():
+            return {}
+
+        try:
+            with self.path.open(encoding="utf-8") as stream:
+                raw: object = json.load(stream)
+        except OSError, UnicodeError, json.JSONDecodeError:
+            return {}
+
+        return _decode_usage(raw)
+
+    def record(self, path: Path) -> None:
+        with file_lock(self.path):
+            usage = self.load()
+            previous = usage.get(path)
+            count = 1 if previous is None else previous.count + 1
+            usage[path] = ProjectUsage(used_at=time.time(), count=count)
+            retained = _retain_recent(usage, self.limit)
+
+            payload: dict[str, UsageHistoryEntry] = {
+                str(project_path): {"used_at": item.used_at, "count": item.count}
+                for project_path, item in retained.items()
+            }
+            with atomic_write(self.path) as stream:
+                json.dump(payload, stream, ensure_ascii=False, separators=(",", ":"))
+                stream.write("\n")
+
+
+def _decode_usage(value: object) -> dict[Path, ProjectUsage]:
+    if not _is_usage_mapping(value):
+        return {}
+
+    return {
+        Path(path): ProjectUsage(float(entry["used_at"]), entry["count"])
+        for path, entry in value.items()
+    }
+
+
+def _is_usage_mapping(value: object) -> TypeIs[dict[str, UsageHistoryEntry]]:
+    return isinstance(value, dict) and all(
+        isinstance(path, str) and _is_usage_entry(entry) for path, entry in value.items()
+    )
+
+
+def _is_usage_entry(value: object) -> TypeIs[UsageHistoryEntry]:
+    if not isinstance(value, dict):
+        return False
+
+    used_at = value.get("used_at")
+    count = value.get("count")
+    valid_time = not isinstance(used_at, bool) and isinstance(used_at, int | float)
+    valid_count = not isinstance(count, bool) and isinstance(count, int) and count > 0
+    return valid_time and valid_count
+
+
+def _retain_recent(
+    usage: dict[Path, ProjectUsage],
+    limit: int,
+) -> dict[Path, ProjectUsage]:
+    if limit <= 0:
+        return {}
+    if len(usage) <= limit:
+        return usage
+
+    newest = sorted(
+        usage.items(),
+        key=lambda item: (item[1].used_at, item[1].count, str(item[0])),
+        reverse=True,
+    )[:limit]
+    return dict(newest)

pcd_cli/models.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from enum import IntEnum, StrEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ProjectSource(StrEnum):
+    DISCOVERED = "discovered"
+    MANUAL = "manual"
+
+
+class ExitCode(IntEnum):
+    ERROR = 1
+    NOT_FOUND = 3
+
+
+@dataclass(frozen=True, slots=True)
+class Project:
+    name: str
+    path: Path
+    display_path: Path
+    source: ProjectSource
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectSettings:
+    roots: tuple[Path, ...]
+    manual_projects: tuple[Project, ...]
+    include_hidden: bool
+    follow_symlinks: bool
+    excluded_names: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectUsage:
+    used_at: float
+    count: int

pcd_cli/navigation.py

@@ -0,0 +1,80 @@
+from typing import TYPE_CHECKING
+
+import click
+from click.shell_completion import CompletionItem
+
+from pcd_cli.catalog import ProjectCatalog
+from pcd_cli.filesystem import format_path
+from pcd_cli.models import ExitCode, ProjectSource
+from pcd_cli.shell_integration import (
+    inactive_shell_message,
+    SHELL_CD_EXIT_CODE,
+    shell_integration_active,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pcd_cli.models import Project
+
+
+def navigate_to_project(
+    catalog: ProjectCatalog,
+    query: str | None = None,
+    exact_only: bool = False,
+) -> None:
+    matches = catalog.projects() if query is None else catalog.search(query, exact_only=exact_only)
+    if not matches:
+        suffix = "" if query is None else f": {query}"
+        click.echo(f"Project not found{suffix}", err=True)
+        raise click.exceptions.Exit(ExitCode.NOT_FOUND)
+
+    selected = matches[0] if len(matches) == 1 else select_project(catalog, matches, query or "")
+    if selected is not None:
+        _open_project(catalog, selected)
+
+
+def select_project(
+    catalog: ProjectCatalog,
+    projects: Sequence[Project],
+    query: str = "",
+) -> Project | None:
+    # Import lazily so shell completion never initializes terminal UI machinery.
+    from pcd_cli.picker import ProjectPicker
+
+    return ProjectPicker(projects, catalog.history.load(), query).run()
+
+
+def project_completions(value: str) -> list[CompletionItem]:
+    names: set[str] = set()
+    completions: list[CompletionItem] = []
+
+    for project in ProjectCatalog.create().completion_candidates(value):
+        if project.name in names:
+            continue
+        names.add(project.name)
+        completions.append(CompletionItem(project.name, help=format_path(project.display_path)))
+
+    return completions
+
+
+def _open_project(catalog: ProjectCatalog, project: Project) -> None:
+    if project.path.is_dir():
+        catalog.record_usage(project)
+    elif project.source is ProjectSource.MANUAL:
+        click.echo(
+            f"Project path no longer exists: {format_path(project.display_path)}",
+            err=True,
+        )
+        raise click.exceptions.Exit(ExitCode.ERROR)
+    else:
+        catalog.refresh()
+        click.echo("Selected project no longer exists.", err=True)
+        raise click.exceptions.Exit(ExitCode.ERROR)
+
+    if shell_integration_active():
+        click.echo(project.path)
+        raise click.exceptions.Exit(SHELL_CD_EXIT_CODE)
+
+    click.echo(project.path)
+    click.echo(inactive_shell_message(), err=True)

pcd_cli/picker.py

@@ -0,0 +1,140 @@
+import sys
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from prompt_toolkit import Application
+from prompt_toolkit.buffer import Buffer
+from prompt_toolkit.document import Document
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.layout import HSplit, Layout, Window
+from prompt_toolkit.layout.controls import BufferControl, FormattedTextControl
+from prompt_toolkit.layout.processors import BeforeInput
+from prompt_toolkit.output.defaults import create_output
+
+from pcd_cli.filesystem import format_path
+from pcd_cli.search import rank_matches, rank_recent
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+    from prompt_toolkit.formatted_text import StyleAndTextTuples
+    from prompt_toolkit.input.base import Input
+    from prompt_toolkit.key_binding import KeyPressEvent
+    from prompt_toolkit.output import Output
+
+    from pcd_cli.models import Project, ProjectUsage
+
+
+PAGE_SIZE = 12
+
+
+@dataclass(slots=True)
+class ProjectPicker:
+    """Project-specific interactive picker built on prompt-toolkit primitives."""
+
+    projects: Sequence[Project]
+    usage: Mapping[Path, ProjectUsage]
+    query: str = ""
+    input_stream: Input | None = None
+    output: Output | None = None
+
+    matches: list[Project] = field(default_factory=list, init=False)
+    selected_index: int = field(default=0, init=False)
+    application: Application[Project | None] | None = field(default=None, init=False)
+
+    def run(self) -> Project | None:
+        self.matches = self._matching_projects(self.query)
+        buffer = Buffer(
+            document=Document(self.query, cursor_position=len(self.query)),
+            multiline=False,
+            on_text_changed=self._filter,
+        )
+        bindings = KeyBindings()
+        bindings.add("up")(self._move_up)
+        bindings.add("down")(self._move_down)
+        bindings.add("enter")(self._select)
+        bindings.add("escape")(self._cancel)
+        bindings.add("c-c")(self._cancel)
+
+        search = Window(
+            BufferControl(buffer=buffer, input_processors=[BeforeInput("Search: ")]),
+            height=1,
+        )
+        results = Window(content=FormattedTextControl(self._render), dont_extend_height=True)
+        output = self.output if self.output is not None else create_output(stdout=sys.stderr)
+        application: Application[Project | None] = Application(
+            layout=Layout(HSplit([search, results]), focused_element=search),
+            key_bindings=bindings,
+            full_screen=False,
+            erase_when_done=True,
+            input=self.input_stream,
+            output=output,
+        )
+        self.application = application
+
+        try:
+            return application.run()
+        finally:
+            self.application = None
+
+    def _matching_projects(self, query: str) -> list[Project]:
+        if query:
+            return rank_matches(self.projects, query, self.usage)
+        return rank_recent(self.projects, self.usage)
+
+    def _filter(self, buffer: Buffer) -> None:
+        selected_path = self.matches[self.selected_index].path if self.matches else None
+        self.matches = self._matching_projects(buffer.text)
+        selected_index = next(
+            (index for index, project in enumerate(self.matches) if project.path == selected_path),
+            None,
+        )
+        self.selected_index = 0 if selected_index is None else selected_index
+
+        if self.application is not None:
+            self.application.invalidate()
+
+    def _move_up(self, event: KeyPressEvent) -> None:
+        self._move(event, -1)
+
+    def _move_down(self, event: KeyPressEvent) -> None:
+        self._move(event, 1)
+
+    def _move(self, event: KeyPressEvent, step: int) -> None:
+        self.selected_index = (
+            (self.selected_index + step) % len(self.matches) if self.matches else 0
+        )
+        event.app.invalidate()
+
+    def _select(self, event: KeyPressEvent) -> None:
+        selected = self.matches[self.selected_index] if self.matches else None
+        event.app.exit(result=selected)
+
+    def _cancel(self, event: KeyPressEvent) -> None:
+        event.app.exit(result=None)
+
+    def _render(self) -> StyleAndTextTuples:
+        if self.matches:
+            return self._lines()
+
+        return [("italic", "\nNo matching projects\n")]
+
+    def _lines(self) -> StyleAndTextTuples:
+        start = max(0, self.selected_index - PAGE_SIZE // 2)
+        stop = min(len(self.matches), start + PAGE_SIZE)
+        if stop - start < PAGE_SIZE:
+            start = max(0, stop - PAGE_SIZE)
+
+        lines: StyleAndTextTuples = [("", "\n")]
+        for index, project in enumerate(self.matches[start:stop], start=start):
+            selected = index == self.selected_index
+            marker = "> " if selected else "  "
+            style = "reverse" if selected else ""
+            lines.append(
+                (style, f"{marker}{project.name:<24} {format_path(project.display_path)}\n")
+            )
+
+        if len(self.matches) > PAGE_SIZE:
+            lines.append(("dim", f"\n{self.selected_index + 1}/{len(self.matches)}\n"))
+        return lines