pcd-cli 0.1.0__tar.gz → 0.2.1__tar.gz

{pcd_cli-0.1.0 → pcd_cli-0.2.1}/PKG-INFO

@@ -1,21 +1,23 @@
 Metadata-Version: 2.4
 Name: pcd-cli
-Version: 0.1.0
+Version: 0.2.1
 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
+Requires-Python: >=3.12,<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.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
-Requires-Dist: click (>=8.4.2,<9)
-Requires-Dist: platformdirs (>=4.10,<5)
+Requires-Dist: click (>=8.5.0,<9)
+Requires-Dist: platformdirs (>=4.11.7,<5)
 Requires-Dist: prompt-toolkit (>=3.0.53,<4)
 Requires-Dist: tomlkit (>=0.15.1,<1)
 Description-Content-Type: text/plain
@@ -38,7 +40,9 @@ Supported shells:
 
 INSTALL
 -------
-    pipx install --python python3.14 git+https://github.com/jestenough/pcd.git
+Requires Python 3.12 or newer.
+
+    pipx install git+https://github.com/jestenough/pcd.git
     pcd shell install
 Restart your shell after installing shell integration.
 
@@ -66,7 +70,10 @@ COMMANDS
     pcd refresh                  Rescan roots and rebuild the project cache
 
     pcd list                     List all known projects
-    pcd config-path              Print the configuration file path
+    pcd config path              Print the configuration file path
+    pcd config show              Print the effective configuration
+    pcd config edit              Edit the user configuration
+    pcd config validate          Validate the user configuration
 
     pcd shell install            Install shell integration
     pcd shell status             Show shell integration status
@@ -78,6 +85,7 @@ COMMANDS
 
 * Projects inside registered roots are discovered automatically.
 * You can register multiple scan roots.
+* Set `editor = "nvim"` in the configuration to choose an editor for `pcd config edit`.
 
 
 DEVELOPMENT
@@ -95,10 +103,7 @@ SEE ALSO
         FEATURES.txt
 
     Planned changes:
-        ROADMAP.md
-
-    Changelog:
-        CHANGELOG.md
+        ROADMAP.txt
 
     License:
         MIT

{pcd_cli-0.1.0 → pcd_cli-0.2.1}/README.txt

@@ -16,7 +16,9 @@ Supported shells:
 
 INSTALL
 -------
-    pipx install --python python3.14 git+https://github.com/jestenough/pcd.git
+Requires Python 3.12 or newer.
+
+    pipx install git+https://github.com/jestenough/pcd.git
     pcd shell install
 Restart your shell after installing shell integration.
 
@@ -44,7 +46,10 @@ COMMANDS
     pcd refresh                  Rescan roots and rebuild the project cache
 
     pcd list                     List all known projects
-    pcd config-path              Print the configuration file path
+    pcd config path              Print the configuration file path
+    pcd config show              Print the effective configuration
+    pcd config edit              Edit the user configuration
+    pcd config validate          Validate the user configuration
 
     pcd shell install            Install shell integration
     pcd shell status             Show shell integration status
@@ -56,6 +61,7 @@ COMMANDS
 
 * Projects inside registered roots are discovered automatically.
 * You can register multiple scan roots.
+* Set `editor = "nvim"` in the configuration to choose an editor for `pcd config edit`.
 
 
 DEVELOPMENT
@@ -73,10 +79,7 @@ SEE ALSO
         FEATURES.txt
 
     Planned changes:
-        ROADMAP.md
-
-    Changelog:
-        CHANGELOG.md
+        ROADMAP.txt
 
     License:
         MIT

{pcd_cli-0.1.0 → pcd_cli-0.2.1}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "pcd-cli"
-version = "0.1.0"
+version = "0.2.1"
 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"
+requires-python = ">=3.12,<4"
 keywords = ["cli", "cd", "projects", "navigation", "bash", "zsh", "fish"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -14,12 +14,14 @@ classifiers = [
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Topic :: Utilities",
 ]
 dependencies = [
-    "click>=8.4.2,<9",
-    "platformdirs>=4.10,<5",
+    "click>=8.5.0,<9",
+    "platformdirs>=4.11.7,<5",
     "prompt-toolkit>=3.0.53,<4",
     "tomlkit>=0.15.1,<1",
 ]
@@ -35,14 +37,14 @@ build-backend = "poetry.core.masonry.api"
 packages = [{ include = "pcd_cli", from = "src" }]
 
 [tool.poetry.group.dev.dependencies]
-mypy = "2.3.0"
+mypy = "2.3.1"
 pre-commit = "4.6.2"
 pytest = "9.1.1"
 pytest-cov = "7.1.0"
-ruff = "0.16.3"
+ruff = "0.16.5"
 
 [tool.ruff]
-target-version = "py314"
+target-version = "py312"
 line-length = 100
 src = ["src", "tests", "benchmarks"]
 
@@ -85,7 +87,7 @@ line-ending = "lf"
 docstring-code-format = true
 
 [tool.mypy]
-python_version = "3.14"
+python_version = "3.12"
 strict = true
 warn_unreachable = true
 show_error_codes = true

{pcd_cli-0.1.0 → pcd_cli-0.2.1}/src/pcd_cli/cache.py

@@ -1,7 +1,9 @@
+from __future__ import annotations
+
 import json
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, TypedDict, TypeIs
+from typing import TYPE_CHECKING, TypedDict, TypeGuard
 
 from pcd_cli.filesystem import atomic_write, file_lock
 from pcd_cli.models import Project, ProjectSource
@@ -92,7 +94,7 @@ class ProjectCache:
             raise _CacheReadError("Cannot read cache") from exc
 
 
-def _is_cache_entry(value: object) -> TypeIs[ProjectCacheEntry]:
+def _is_cache_entry(value: object) -> TypeGuard[ProjectCacheEntry]:
     if not isinstance(value, dict):
         return False
 

{pcd_cli-0.1.0 → pcd_cli-0.2.1}/src/pcd_cli/catalog.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dataclasses import dataclass
 from typing import Self, TYPE_CHECKING
 

pcd_cli-0.2.1/src/pcd_cli/cli/__init__.py

@@ -0,0 +1,43 @@
+from pcd_cli.cli.app import cli, main, package_version, ProjectCommandGroup
+from pcd_cli.cli.config import (
+    config_commands,
+    edit_config,
+    print_config_path,
+    show_config,
+    validate_config,
+)
+from pcd_cli.cli.projects import add, init, list_projects, project, refresh, remove, roots, uninit
+from pcd_cli.cli.shell import (
+    install_shell,
+    print_shell_integration,
+    shell_commands,
+    shell_init,
+    shell_status,
+    uninstall_shell,
+)
+
+__all__ = [
+    "ProjectCommandGroup",
+    "add",
+    "cli",
+    "config_commands",
+    "edit_config",
+    "init",
+    "install_shell",
+    "list_projects",
+    "main",
+    "package_version",
+    "print_config_path",
+    "print_shell_integration",
+    "project",
+    "refresh",
+    "remove",
+    "roots",
+    "shell_commands",
+    "shell_init",
+    "shell_status",
+    "show_config",
+    "uninit",
+    "uninstall_shell",
+    "validate_config",
+]

pcd_cli-0.2.1/src/pcd_cli/cli/app.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from importlib import metadata
+from typing import TYPE_CHECKING
+
+import click
+
+from pcd_cli.catalog import ProjectCatalog
+from pcd_cli.cli.config import config_commands
+from pcd_cli.cli.projects import project_commands
+from pcd_cli.cli.shell import shell_commands, shell_init
+from pcd_cli.config import InvalidConfigError
+from pcd_cli.models import ExitCode
+from pcd_cli.navigation import navigate_to_project, project_completions
+from pcd_cli.shell_integration import ShellIntegrationError
+
+if TYPE_CHECKING:
+    from click.shell_completion import CompletionItem
+
+
+class ProjectCommandGroup(click.Group):
+    """Route an unknown first argument to project lookup."""
+
+    def resolve_command(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        candidate = args[0] if args else None
+        if candidate is None or candidate.startswith("-"):
+            return super().resolve_command(ctx, args)
+        if self.get_command(ctx, candidate) is not None:
+            return super().resolve_command(ctx, args)
+
+        project_command = self.get_command(ctx, "project")
+        if project_command is None:
+            return super().resolve_command(ctx, args)
+
+        return "project", project_command, args
+
+    def shell_complete(self, ctx: click.Context, incomplete: str) -> list[CompletionItem]:
+        completions = super().shell_complete(ctx, incomplete)
+        known_values = {item.value for item in completions}
+
+        for completion in project_completions(incomplete):
+            if completion.value not in known_values:
+                completions.append(completion)
+
+        return completions
+
+
+def package_version() -> str:
+    try:
+        return metadata.version("pcd-cli")
+    except metadata.PackageNotFoundError:
+        return "0+unknown"
+
+
+@click.group(cls=ProjectCommandGroup, invoke_without_command=True)
+@click.option(
+    "--project",
+    "project_name",
+    shell_complete=lambda _ctx, _param, value: project_completions(value),
+    help="Resolve a project whose name is reserved by a command.",
+)
+@click.version_option(version=package_version())
+@click.pass_context
+def cli(ctx: click.Context, project_name: str | None) -> None:
+    """Jump to local projects by name."""
+    catalog = ProjectCatalog.create()
+    ctx.obj = catalog
+
+    if project_name is not None and ctx.invoked_subcommand is not None:
+        raise click.UsageError("--project cannot be combined with a command")
+
+    if ctx.invoked_subcommand is not None:
+        return
+
+    if project_name is None:
+        click.echo(ctx.get_help())
+        return
+
+    navigate_to_project(catalog, project_name, exact_only=True)
+
+
+for command in project_commands:
+    cli.add_command(command)
+cli.add_command(config_commands)
+cli.add_command(shell_commands)
+cli.add_command(shell_init)
+
+
+def main() -> None:
+    try:
+        cli.main()
+    except InvalidConfigError as exc:
+        click.echo(f"Config error: {exc}", err=True)
+        raise SystemExit(ExitCode.ERROR) from None
+    except ShellIntegrationError as exc:
+        click.echo(f"Shell integration error: {exc}", err=True)
+        raise SystemExit(ExitCode.ERROR) from None
+    except OSError as exc:
+        click.echo(f"Filesystem error: {exc}", err=True)
+        raise SystemExit(ExitCode.ERROR) from None

pcd_cli-0.2.1/src/pcd_cli/cli/config.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from typing import TYPE_CHECKING
+
+import click
+
+from pcd_cli.config import InvalidConfigError
+
+if TYPE_CHECKING:
+    from pcd_cli.catalog import ProjectCatalog
+
+
+@click.group("config")
+def config_commands() -> None:
+    """User configuration commands."""
+
+
+@config_commands.command("path")
+@click.pass_obj
+def print_config_path(catalog: ProjectCatalog) -> None:
+    """Print the path to the user-editable configuration file."""
+    click.echo(catalog.config.path)
+
+
+@config_commands.command("show")
+@click.pass_obj
+def show_config(catalog: ProjectCatalog) -> None:
+    """Print the effective user configuration."""
+    click.echo(catalog.config.effective_toml(), nl=False)
+
+
+@config_commands.command("edit")
+@click.pass_obj
+def edit_config(catalog: ProjectCatalog) -> None:
+    """Open the user configuration in $VISUAL or $EDITOR."""
+    try:
+        editor = catalog.config.load().editor
+    except InvalidConfigError:
+        editor = None
+    else:
+        editor = editor or os.environ.get("VISUAL") or os.environ.get("EDITOR")
+
+    if editor is None:
+        raise click.UsageError("Set $VISUAL or $EDITOR before running `pcd config edit`")
+
+    try:
+        command = shlex.split(editor)
+    except ValueError as exc:
+        raise click.UsageError(f"Invalid editor command: {exc}") from exc
+    if not command:
+        raise click.UsageError("Set $VISUAL or $EDITOR before running `pcd config edit`")
+
+    catalog.config.ensure_exists()
+
+    result = subprocess.run([*command, str(catalog.config.path)], check=False)
+    if result.returncode:
+        raise click.ClickException(f"Editor exited with status {result.returncode}")
+
+
+@config_commands.command("validate")
+@click.pass_obj
+def validate_config(catalog: ProjectCatalog) -> None:
+    """Validate the user configuration."""
+    try:
+        catalog.config.load()
+    except InvalidConfigError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    click.echo(f"Configuration is valid: {catalog.config.path}")

pcd_cli-0.2.1/src/pcd_cli/cli/projects.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import assert_never, ClassVar, Literal, NamedTuple, TYPE_CHECKING
+
+import click
+
+from pcd_cli.filesystem import canonical_path, format_path
+from pcd_cli.models import ExitCode, Project, ProjectSource
+from pcd_cli.navigation import navigate_to_project, project_completions, select_project
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pcd_cli.catalog import ProjectCatalog
+
+type ProjectSourceLabel = Literal["manual", "scanned"]
+type ProjectStatusLabel = Literal["available", "missing"]
+
+
+class ProjectListRow(NamedTuple):
+    name: str
+    path: str
+    source: ProjectSourceLabel
+    status: ProjectStatusLabel
+
+    @classmethod
+    def from_project(cls, project: Project) -> ProjectListRow:
+        return cls(
+            name=project.name,
+            path=format_path(project.display_path),
+            source=cls._source_label(project.source),
+            status=cls._status_label(project.path),
+        )
+
+    @staticmethod
+    def _source_label(source: ProjectSource) -> ProjectSourceLabel:
+        match source:
+            case ProjectSource.DISCOVERED:
+                return "scanned"
+            case ProjectSource.MANUAL:
+                return "manual"
+            case _:
+                assert_never(source)
+
+    @staticmethod
+    def _status_label(path: Path) -> ProjectStatusLabel:
+        if path.is_dir():
+            return "available"
+        else:
+            return "missing"
+
+
+class ProjectListTable:
+    HEADERS: ClassVar[tuple[str, str, str, str]] = ("NAME", "PATH", "SOURCE", "STATUS")
+
+    _rows: tuple[ProjectListRow, ...]
+
+    def __init__(self, projects: Sequence[Project]) -> None:
+        self._rows = tuple(ProjectListRow.from_project(project) for project in projects)
+
+    def render(self) -> str:
+        if self._rows:
+            return self._render_table()
+        else:
+            return "No projects found."
+
+    def _render_table(self) -> str:
+        table = (self.HEADERS, *self._rows)
+        columns = zip(*table, strict=True)
+        widths = tuple(max(len(value) for value in column) for column in columns)
+
+        return "\n".join(self._render_row(row, widths) for row in table)
+
+    @staticmethod
+    def _render_row(row: tuple[str, ...], widths: tuple[int, ...]) -> str:
+        return "  ".join(
+            value.ljust(width) for value, width in zip(row, widths, strict=True)
+        ).rstrip()
+
+
+@click.command(hidden=True)
+@click.argument("query")
+@click.pass_obj
+def project(catalog: ProjectCatalog, query: str) -> None:
+    """Resolve a project name routed by the root command."""
+    navigate_to_project(catalog, query)
+
+
+@click.command()
+@click.pass_obj
+def init(catalog: ProjectCatalog) -> None:
+    """Register the current directory as a scan root."""
+    current = Path.cwd()
+    parent = catalog.find_parent_root(current)
+    added = catalog.add_scan_root(current)
+
+    if not added:
+        click.echo(f"Already a root: {format_path(current)}")
+        return
+
+    if parent is not None:
+        click.echo(f"Note: root is inside {format_path(parent)}", err=True)
+
+    click.echo(f"Added root: {format_path(current)}")
+
+
+@click.command()
+@click.pass_obj
+def uninit(catalog: ProjectCatalog) -> None:
+    """Remove the current directory from scan roots."""
+    current = Path.cwd()
+    if catalog.remove_scan_root(current):
+        click.echo(f"Removed root: {format_path(current)}")
+        return
+
+    click.echo("Current directory is not a pcd root.", err=True)
+    raise click.exceptions.Exit(ExitCode.ERROR)
+
+
+@click.command()
+@click.argument("path", type=click.Path(path_type=Path, file_okay=False), required=False)
+@click.option("--name", help="Custom name for a manual project.")
+@click.pass_obj
+def add(catalog: ProjectCatalog, path: Path | None, name: str | None) -> None:
+    """Register a directory as a manual project."""
+    if path is None:
+        location = Path.cwd()
+    else:
+        try:
+            location = path.expanduser()
+        except RuntimeError as exc:
+            raise click.BadParameter("Unknown home directory", param_hint="path") from exc
+
+    if not location.is_absolute():
+        location = Path.cwd() / location
+    if not location.is_dir():
+        raise click.BadParameter(f"Directory does not exist: {location}", param_hint="path")
+
+    project_name = location.name if name is None else name.strip()
+    if not project_name:
+        raise click.BadParameter("Project name cannot be empty", param_hint="--name")
+
+    item = Project(
+        name=project_name,
+        path=canonical_path(location),
+        display_path=location,
+        source=ProjectSource.MANUAL,
+    )
+    if catalog.add_project(item):
+        click.echo(f"Added project: {item.name} -> {format_path(item.display_path)}")
+        return
+
+    click.echo(f"Project already exists: {item.name} -> {format_path(item.display_path)}")
+
+
+@click.command()
+@click.argument(
+    "query",
+    shell_complete=lambda _ctx, _param, value: project_completions(value),
+)
+@click.pass_obj
+def remove(catalog: ProjectCatalog, query: str) -> None:
+    """Remove a manual project registration."""
+    matches = catalog.search(query, exact_only=True)
+    if not matches:
+        click.echo(f"Project not found: {query}", err=True)
+        raise click.exceptions.Exit(ExitCode.NOT_FOUND)
+
+    selected = select_project(catalog, matches, query)
+    if selected is None:
+        return
+
+    if selected.source is ProjectSource.DISCOVERED:
+        click.echo(
+            f"{selected.name} is discovered automatically and cannot be removed with pcd remove.",
+            err=True,
+        )
+        raise click.exceptions.Exit(ExitCode.ERROR)
+
+    if catalog.remove_project(selected.path):
+        click.echo(f"Removed project: {selected.name}")
+        return
+
+    click.echo("Project is no longer registered.", err=True)
+    raise click.exceptions.Exit(ExitCode.ERROR)
+
+
+@click.command("list")
+@click.pass_obj
+def list_projects(catalog: ProjectCatalog) -> None:
+    """List all known projects."""
+    table = ProjectListTable(catalog.projects())
+    click.echo(table.render())
+
+
+@click.command()
+@click.pass_obj
+def roots(catalog: ProjectCatalog) -> None:
+    """List registered scan roots."""
+    for root in catalog.config.load().roots:
+        click.echo(format_path(root))
+
+
+@click.command()
+@click.pass_obj
+def refresh(catalog: ProjectCatalog) -> None:
+    """Rescan roots and rebuild the project cache."""
+    click.echo(f"Found {len(catalog.refresh())} projects.")
+
+
+project_commands = (project, init, uninit, add, remove, list_projects, roots, refresh)