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

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

@@ -1,21 +1,23 @@
 Metadata-Version: 2.4
 Name: pcd-cli
-Version: 0.1.0
+Version: 0.2.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
+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

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/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

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

@@ -1,12 +1,12 @@
 [project]
 name = "pcd-cli"
-version = "0.1.0"
+version = "0.2.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"
+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.0}/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.0}/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.0/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.0/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.0/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.0/src/pcd_cli/cli/projects.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import 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 pcd_cli.catalog import ProjectCatalog
+
+
+@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 = matches[0] if len(matches) == 1 else 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."""
+    projects = catalog.projects()
+    if not projects:
+        click.echo("No projects found.")
+        return
+
+    name_width = max(len(project.name) for project in projects)
+    for item in projects:
+        status = "ok" if item.path.is_dir() else "missing"
+        click.echo(
+            f"{item.name:<{name_width}}  {format_path(item.display_path)}  {item.source.value:<10}  {status}"
+        )
+
+
+@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)

pcd_cli-0.2.0/src/pcd_cli/cli/shell.py

@@ -0,0 +1,111 @@
+import click
+
+from pcd_cli.shell_integration import (
+    detect_shell,
+    render_shell_integration,
+    Shell,
+    shell_integration_active,
+    ShellIntegration,
+    ShellIntegrationError,
+    ShellIntegrationState,
+)
+
+
+@click.group("shell")
+def shell_commands() -> None:
+    """Install and manage shell integration."""
+
+
+@shell_commands.command("install")
+@click.argument(
+    "shell",
+    required=False,
+    type=click.Choice([item.value for item in Shell], case_sensitive=False),
+)
+def install_shell(shell: str | None) -> None:
+    """Install persistent shell integration into the shell startup file."""
+    integration = _shell_integration(shell)
+    if integration.install():
+        click.echo(f"Installed {integration.shell.value} integration in {integration.config_path}")
+        click.echo(f"Restart the shell or run: exec {integration.shell.value}")
+        return
+
+    state = integration.state()
+    if state is ShellIntegrationState.MANAGED:
+        click.echo(f"Shell integration is already installed in {integration.config_path}")
+        return
+
+    click.echo(
+        f"Shell integration is already configured manually in {integration.config_path}; left unchanged."
+    )
+
+
+@shell_commands.command("status")
+@click.argument(
+    "shell",
+    required=False,
+    type=click.Choice([item.value for item in Shell], case_sensitive=False),
+)
+def shell_status(shell: str | None) -> None:
+    """Show whether shell integration is configured and active."""
+    integration = _shell_integration(shell)
+    click.echo(f"Shell: {integration.shell.value}")
+    click.echo(f"Config: {integration.config_path}")
+    click.echo(f"Configured: {integration.state().value}")
+
+    active = shell_integration_active()
+    click.echo(f"Active in current shell: {'yes' if active else 'no'}")
+
+
+@shell_commands.command("uninstall")
+@click.argument(
+    "shell",
+    required=False,
+    type=click.Choice([item.value for item in Shell], case_sensitive=False),
+)
+def uninstall_shell(shell: str | None) -> None:
+    """Remove integration installed by `pcd shell install`."""
+    integration = _shell_integration(shell)
+    if integration.uninstall():
+        click.echo(f"Removed shell integration from {integration.config_path}")
+        return
+
+    state = integration.state()
+    if state is ShellIntegrationState.MANUAL:
+        click.echo(f"Integration in {integration.config_path} is managed manually; left unchanged.")
+        return
+
+    click.echo(f"Shell integration is not installed in {integration.config_path}")
+
+
+@shell_commands.command("print")
+@click.argument(
+    "shell",
+    required=False,
+    type=click.Choice([item.value for item in Shell], case_sensitive=False),
+)
+def print_shell_integration(shell: str | None) -> None:
+    """Print shell integration for manual dotfile management."""
+    selected = _selected_shell(shell)
+    click.echo(render_shell_integration(selected), nl=False)
+
+
+@click.command("shell-init", hidden=True)
+@click.argument("shell", type=click.Choice([item.value for item in Shell], case_sensitive=False))
+def shell_init(shell: str) -> None:
+    """Backward-compatible alias for `pcd shell print`."""
+    click.echo(render_shell_integration(Shell(shell.casefold())), nl=False)
+
+
+def _shell_integration(shell: str | None) -> ShellIntegration:
+    return ShellIntegration.for_shell(_selected_shell(shell))
+
+
+def _selected_shell(shell: str | None) -> Shell:
+    if shell is not None:
+        return Shell(shell.casefold())
+
+    try:
+        return detect_shell()
+    except ShellIntegrationError as exc:
+        raise click.UsageError(str(exc)) from exc

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/config.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, TypeIs
+from typing import TYPE_CHECKING, TypeGuard
 
 import tomlkit
 
@@ -12,7 +14,7 @@ if TYPE_CHECKING:
 
     from tomlkit import TOMLDocument
 
-ROOT_KEYS = frozenset({"roots", "scan", "projects"})
+ROOT_KEYS = frozenset({"roots", "scan", "projects", "editor"})
 SCAN_KEYS = frozenset({"hidden", "follow_symlinks", "exclude"})
 PROJECT_KEYS = frozenset({"name", "path"})
 
@@ -42,6 +44,25 @@ class Config:
     def load(self) -> ProjectSettings:
         return _decode_settings(self._read().unwrap())
 
+    def effective_toml(self) -> str:
+        settings = self.load()
+        document = _default_document()
+        document["roots"] = [str(item) for item in settings.roots]
+        document["scan"]["hidden"] = settings.include_hidden
+        document["scan"]["follow_symlinks"] = settings.follow_symlinks
+        document["scan"]["exclude"] = sorted(settings.excluded_names)
+        if settings.editor is not None:
+            document["editor"] = settings.editor
+        document["projects"] = [
+            {"name": item.name, "path": str(item.display_path)} for item in settings.manual_projects
+        ]
+        return tomlkit.dumps(document)
+
+    def ensure_exists(self) -> None:
+        with file_lock(self.path):
+            if not self.path.exists():
+                self._write(_default_document())
+
     def add_root(self, root: Path) -> bool:
         display_path = root.expanduser()
         target = canonical_path(display_path)
@@ -107,11 +128,14 @@ class Config:
         if not self.path.is_file():
             return _default_document()
 
-        text = self.path.read_text(encoding="utf-8")
+        try:
+            text = self.path.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise InvalidConfigError(f"Config is not valid UTF-8: {self.path}") from exc
         try:
             return tomlkit.parse(text)
         except tomlkit.exceptions.ParseError as exc:
-            raise InvalidConfigError(f"Invalid TOML in {self.path}") from exc
+            raise InvalidConfigError(f"Invalid TOML in {self.path}: {exc}") from exc
 
     def _write(self, document: TOMLDocument) -> None:
         with atomic_write(self.path) as stream:
@@ -152,6 +176,7 @@ def _decode_settings(value: object) -> ProjectSettings:
             "scan.exclude",
         )
     )
+    editor = _text(config["editor"], "editor") if "editor" in config else None
 
     if len({canonical_path(root) for root in roots}) != len(roots):
         raise InvalidConfigError("Config contains duplicate roots")
@@ -164,6 +189,7 @@ def _decode_settings(value: object) -> ProjectSettings:
         include_hidden=include_hidden,
         follow_symlinks=follow_symlinks,
         excluded_names=excluded_names,
+        editor=editor,
     )
 
 
@@ -186,7 +212,7 @@ def _table(value: object, message: str) -> Mapping[str, object]:
     return value
 
 
-def _is_table(value: object) -> TypeIs[Mapping[str, object]]:
+def _is_table(value: object) -> TypeGuard[Mapping[str, object]]:
     return isinstance(value, dict) and all(isinstance(key, str) for key in value)
 
 

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/filesystem.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import fcntl
 import os
 import tempfile

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/history.py

@@ -1,8 +1,10 @@
+from __future__ import annotations
+
 import json
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TypedDict, TypeIs
+from typing import TypedDict, TypeGuard
 
 from pcd_cli.filesystem import atomic_write, file_lock
 from pcd_cli.models import ProjectUsage
@@ -29,7 +31,7 @@ class UsageHistory:
         try:
             with self.path.open(encoding="utf-8") as stream:
                 raw: object = json.load(stream)
-        except OSError, UnicodeError, json.JSONDecodeError:
+        except (OSError, UnicodeError, json.JSONDecodeError):
             return {}
 
         return _decode_usage(raw)
@@ -61,13 +63,13 @@ def _decode_usage(value: object) -> dict[Path, ProjectUsage]:
     }
 
 
-def _is_usage_mapping(value: object) -> TypeIs[dict[str, UsageHistoryEntry]]:
+def _is_usage_mapping(value: object) -> TypeGuard[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]:
+def _is_usage_entry(value: object) -> TypeGuard[UsageHistoryEntry]:
     if not isinstance(value, dict):
         return False
 

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/models.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dataclasses import dataclass
 from enum import IntEnum, StrEnum
 from typing import TYPE_CHECKING
@@ -31,6 +33,7 @@ class ProjectSettings:
     include_hidden: bool
     follow_symlinks: bool
     excluded_names: frozenset[str]
+    editor: str | None = None
 
 
 @dataclass(frozen=True, slots=True)

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/navigation.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 import click

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/picker.py

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

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/scanner.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 from dataclasses import dataclass
 from pathlib import Path

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/search.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:

{pcd_cli-0.1.0 → pcd_cli-0.2.0}/src/pcd_cli/shell_integration.py

@@ -133,7 +133,7 @@ def inactive_shell_message() -> str:
     try:
         integration = ShellIntegration.detect()
         state = integration.state()
-    except OSError, ShellIntegrationError:
+    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"

pcd_cli-0.1.0/src/pcd_cli/cli.py

@@ -1,341 +0,0 @@
-from importlib import metadata
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-import click
-
-from pcd_cli.catalog import ProjectCatalog
-from pcd_cli.config import InvalidConfigError
-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
-from pcd_cli.shell_integration import (
-    detect_shell,
-    render_shell_integration,
-    Shell,
-    shell_integration_active,
-    ShellIntegration,
-    ShellIntegrationError,
-    ShellIntegrationState,
-)
-
-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
-
-    if ctx.invoked_subcommand is None:
-        navigate_to_project(catalog, project_name, exact_only=project_name is not None)
-
-    navigate_to_project(catalog, project_name, exact_only=True)
-
-
-@cli.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)
-
-
-@cli.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)}")
-
-
-@cli.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)
-
-
-@cli.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)}")
-
-
-@cli.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 = matches[0] if len(matches) == 1 else 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)
-
-
-@cli.command("list")
-@click.pass_obj
-def list_projects(catalog: ProjectCatalog) -> None:
-    """List all known projects."""
-    projects = catalog.projects()
-    if not projects:
-        click.echo("No projects found.")
-        return
-
-    name_width = max(len(project.name) for project in projects)
-    for item in projects:
-        status = "ok" if item.path.is_dir() else "missing"
-        click.echo(
-            f"{item.name:<{name_width}}  {format_path(item.display_path)}  {item.source.value:<10}  {status}"
-        )
-
-
-@cli.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))
-
-
-@cli.command()
-@click.pass_obj
-def refresh(catalog: ProjectCatalog) -> None:
-    """Rescan roots and rebuild the project cache."""
-    click.echo(f"Found {len(catalog.refresh())} projects.")
-
-
-@cli.command("config-path")
-@click.pass_obj
-def config_path(catalog: ProjectCatalog) -> None:
-    """Print the path to the user-editable configuration file."""
-    click.echo(catalog.config.path)
-
-
-@cli.group("shell")
-def shell_commands() -> None:
-    """Install and manage shell integration."""
-
-
-@shell_commands.command("install")
-@click.argument(
-    "shell",
-    required=False,
-    type=click.Choice([item.value for item in Shell], case_sensitive=False),
-)
-def install_shell(shell: str | None) -> None:
-    """Install persistent shell integration into the shell startup file."""
-    integration = _shell_integration(shell)
-    if integration.install():
-        click.echo(f"Installed {integration.shell.value} integration in {integration.config_path}")
-        click.echo(f"Restart the shell or run: exec {integration.shell.value}")
-        return
-
-    state = integration.state()
-    if state is ShellIntegrationState.MANAGED:
-        click.echo(f"Shell integration is already installed in {integration.config_path}")
-        return
-    click.echo(
-        f"Shell integration is already configured manually in {integration.config_path}; left unchanged."
-    )
-
-
-@shell_commands.command("status")
-@click.argument(
-    "shell",
-    required=False,
-    type=click.Choice([item.value for item in Shell], case_sensitive=False),
-)
-def shell_status(shell: str | None) -> None:
-    """Show whether shell integration is configured and active."""
-    integration = _shell_integration(shell)
-    click.echo(f"Shell: {integration.shell.value}")
-    click.echo(f"Config: {integration.config_path}")
-    click.echo(f"Configured: {integration.state().value}")
-    active = shell_integration_active()
-    click.echo(f"Active in current shell: {'yes' if active else 'no'}")
-
-
-@shell_commands.command("uninstall")
-@click.argument(
-    "shell",
-    required=False,
-    type=click.Choice([item.value for item in Shell], case_sensitive=False),
-)
-def uninstall_shell(shell: str | None) -> None:
-    """Remove integration installed by `pcd shell install`."""
-    integration = _shell_integration(shell)
-    if integration.uninstall():
-        click.echo(f"Removed shell integration from {integration.config_path}")
-        return
-
-    state = integration.state()
-    if state is ShellIntegrationState.MANUAL:
-        click.echo(f"Integration in {integration.config_path} is managed manually; left unchanged.")
-        return
-    click.echo(f"Shell integration is not installed in {integration.config_path}")
-
-
-@shell_commands.command("print")
-@click.argument(
-    "shell",
-    required=False,
-    type=click.Choice([item.value for item in Shell], case_sensitive=False),
-)
-def print_shell_integration(shell: str | None) -> None:
-    """Print shell integration for manual dotfile management."""
-    selected = _selected_shell(shell)
-    click.echo(render_shell_integration(selected), nl=False)
-
-
-@cli.command("shell-init", hidden=True)
-@click.argument("shell", type=click.Choice([item.value for item in Shell], case_sensitive=False))
-def shell_init(shell: str) -> None:
-    """Backward-compatible alias for `pcd shell print`."""
-    click.echo(render_shell_integration(Shell(shell.casefold())), nl=False)
-
-
-def _shell_integration(shell: str | None) -> ShellIntegration:
-    return ShellIntegration.for_shell(_selected_shell(shell))
-
-
-def _selected_shell(shell: str | None) -> Shell:
-    if shell is not None:
-        return Shell(shell.casefold())
-    try:
-        return detect_shell()
-    except ShellIntegrationError as exc:
-        raise click.UsageError(str(exc)) from exc
-
-
-def main() -> None:
-    """Console-script boundary for application-specific failures."""
-    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