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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pcd-cli
-Version: 0.2.1
+Version: 0.2.3
 Summary: Fast project navigator for Bash, Zsh and Fish
 License-Expression: MIT
 License-File: LICENSE
@@ -69,13 +69,14 @@ COMMANDS
     pcd roots                    List scan roots
     pcd refresh                  Rescan roots and rebuild the project cache
 
-    pcd list                     List all known projects
+    pcd list [options]           List and filter known projects
     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 init <shell>       Print shell integration code
     pcd shell status             Show shell integration status
     pcd shell uninstall          Remove shell integration
 
@@ -85,6 +86,8 @@ COMMANDS
 
 * Projects inside registered roots are discovered automatically.
 * You can register multiple scan roots.
+* Filter `pcd list` with `--manual`, `--discovered`, or `--missing`.
+* Use `pcd list --json` for machine-readable output.
 * Set `editor = "nvim"` in the configuration to choose an editor for `pcd config edit`.
 
 

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

@@ -45,13 +45,14 @@ COMMANDS
     pcd roots                    List scan roots
     pcd refresh                  Rescan roots and rebuild the project cache
 
-    pcd list                     List all known projects
+    pcd list [options]           List and filter known projects
     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 init <shell>       Print shell integration code
     pcd shell status             Show shell integration status
     pcd shell uninstall          Remove shell integration
 
@@ -61,6 +62,8 @@ COMMANDS
 
 * Projects inside registered roots are discovered automatically.
 * You can register multiple scan roots.
+* Filter `pcd list` with `--manual`, `--discovered`, or `--missing`.
+* Use `pcd list --json` for machine-readable output.
 * Set `editor = "nvim"` in the configuration to choose an editor for `pcd config edit`.
 
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "pcd-cli"
-version = "0.2.1"
+version = "0.2.3"
 description = "Fast project navigator for Bash, Zsh and Fish"
 readme = { file = "README.txt", content-type = "text/plain" }
 license = "MIT"

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

@@ -35,7 +35,7 @@ class ProjectCatalog:
         )
 
     def projects(self) -> list[Project]:
-        if cached := self.cache.load():
+        if (cached := self.cache.load()) is not None:
             return cached
 
         return self.refresh()

{pcd_cli-0.2.1 → pcd_cli-0.2.3}/src/pcd_cli/cli/__init__.py

@@ -6,12 +6,12 @@ from pcd_cli.cli.config import (
     show_config,
     validate_config,
 )
-from pcd_cli.cli.projects import add, init, list_projects, project, refresh, remove, roots, uninit
+from pcd_cli.cli.projects import add, list_projects, project, remove
+from pcd_cli.cli.roots import init, refresh, roots, uninit
 from pcd_cli.cli.shell import (
+    init_shell,
     install_shell,
-    print_shell_integration,
     shell_commands,
-    shell_init,
     shell_status,
     uninstall_shell,
 )
@@ -23,18 +23,17 @@ __all__ = [
     "config_commands",
     "edit_config",
     "init",
+    "init_shell",
     "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",

{pcd_cli-0.2.1 → pcd_cli-0.2.3}/src/pcd_cli/cli/app.py

@@ -8,11 +8,12 @@ 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.cli.roots import root_commands
+from pcd_cli.cli.shell import shell_commands
 from pcd_cli.config import InvalidConfigError
+from pcd_cli.integrations.shell import ShellIntegrationError
 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
@@ -83,11 +84,13 @@ def cli(ctx: click.Context, project_name: str | None) -> None:
     navigate_to_project(catalog, project_name, exact_only=True)
 
 
-for command in project_commands:
+for command in (
+    *project_commands,
+    *root_commands,
+    config_commands,
+    shell_commands,
+):
     cli.add_command(command)
-cli.add_command(config_commands)
-cli.add_command(shell_commands)
-cli.add_command(shell_init)
 
 
 def main() -> None:

{pcd_cli-0.2.1 → pcd_cli-0.2.3}/src/pcd_cli/cli/config.py

@@ -40,8 +40,8 @@ def edit_config(catalog: ProjectCatalog) -> None:
         editor = catalog.config.load().editor
     except InvalidConfigError:
         editor = None
-    else:
-        editor = editor or os.environ.get("VISUAL") or os.environ.get("EDITOR")
+
+    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`")

{pcd_cli-0.2.1 → pcd_cli-0.2.3}/src/pcd_cli/cli/projects.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import json
+from enum import StrEnum
 from pathlib import Path
 from typing import assert_never, ClassVar, Literal, NamedTuple, TYPE_CHECKING
 
@@ -15,14 +17,18 @@ if TYPE_CHECKING:
     from pcd_cli.catalog import ProjectCatalog
 
 type ProjectSourceLabel = Literal["manual", "scanned"]
-type ProjectStatusLabel = Literal["available", "missing"]
+
+
+class ProjectStatus(StrEnum):
+    AVAILABLE = "available"
+    MISSING = "missing"
 
 
 class ProjectListRow(NamedTuple):
     name: str
     path: str
     source: ProjectSourceLabel
-    status: ProjectStatusLabel
+    status: ProjectStatus
 
     @classmethod
     def from_project(cls, project: Project) -> ProjectListRow:
@@ -44,11 +50,11 @@ class ProjectListRow(NamedTuple):
                 assert_never(source)
 
     @staticmethod
-    def _status_label(path: Path) -> ProjectStatusLabel:
+    def _status_label(path: Path) -> ProjectStatus:
         if path.is_dir():
-            return "available"
+            return ProjectStatus.AVAILABLE
         else:
-            return "missing"
+            return ProjectStatus.MISSING
 
 
 class ProjectListTable:
@@ -59,6 +65,12 @@ class ProjectListTable:
     def __init__(self, projects: Sequence[Project]) -> None:
         self._rows = tuple(ProjectListRow.from_project(project) for project in projects)
 
+    @classmethod
+    def from_rows(cls, rows: Sequence[ProjectListRow]) -> ProjectListTable:
+        table = cls(())
+        table._rows = tuple(rows)
+        return table
+
     def render(self) -> str:
         if self._rows:
             return self._render_table()
@@ -87,37 +99,6 @@ def project(catalog: ProjectCatalog, query: str) -> None:
     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.")
@@ -187,26 +168,50 @@ def remove(catalog: ProjectCatalog, query: str) -> None:
 
 
 @click.command("list")
+@click.option("--manual", is_flag=True, help="Show manually registered projects.")
+@click.option("--discovered", is_flag=True, help="Show automatically discovered projects.")
+@click.option("--missing", is_flag=True, help="Show projects whose directories are missing.")
+@click.option("--json", "as_json", is_flag=True, help="Print projects as JSON.")
 @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))
-
+def list_projects(
+    catalog: ProjectCatalog,
+    manual: bool,
+    discovered: bool,
+    missing: bool,
+    as_json: bool,
+) -> None:
+    """List and filter known projects."""
+    entries: list[tuple[Project, ProjectListRow]] = []
+    for project in catalog.projects():
+        source_matches = (
+            not (manual or discovered)
+            or (manual and project.source is ProjectSource.MANUAL)
+            or (discovered and project.source is ProjectSource.DISCOVERED)
+        )
+        if not source_matches:
+            continue
+
+        row = ProjectListRow.from_project(project)
+        if missing and row.status is not ProjectStatus.MISSING:
+            continue
+
+        entries.append((project, row))
+
+    if as_json:
+        items = [
+            {
+                "name": project.name,
+                "path": str(project.display_path),
+                "source": project.source.value,
+                "status": row.status,
+            }
+            for project, row in entries
+        ]
+        click.echo(json.dumps(items, indent=2))
+        return
 
-@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.")
+    table = ProjectListTable.from_rows(tuple(row for _, row in entries))
+    click.echo(table.render())
 
 
-project_commands = (project, init, uninit, add, remove, list_projects, roots, refresh)
+project_commands = (project, add, remove, list_projects)

pcd_cli-0.2.3/src/pcd_cli/cli/roots.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import ClassVar, Literal, NamedTuple, TYPE_CHECKING
+
+import click
+
+from pcd_cli.filesystem import canonical_path, format_path
+from pcd_cli.models import ExitCode, ProjectSource
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pcd_cli.catalog import ProjectCatalog
+    from pcd_cli.models import Project
+
+type RootStatusLabel = Literal["available", "missing"]
+
+
+class RootListRow(NamedTuple):
+    path: str
+    projects: str
+    status: RootStatusLabel
+
+    @classmethod
+    def from_root(cls, root: Path, projects: Sequence[Project]) -> RootListRow:
+        resolved_root = canonical_path(root)
+        project_count = sum(
+            project.path.is_relative_to(resolved_root)
+            for project in projects
+            if project.source is ProjectSource.DISCOVERED
+        )
+
+        return cls(
+            path=format_path(root),
+            projects=str(project_count),
+            status="available" if root.is_dir() else "missing",
+        )
+
+
+class RootListTable:
+    HEADERS: ClassVar[tuple[str, str, str]] = ("PATH", "PROJECTS", "STATUS")
+
+    _rows: tuple[RootListRow, ...]
+
+    def __init__(self, roots: Sequence[Path], projects: Sequence[Project]) -> None:
+        self._rows = tuple(RootListRow.from_root(root, projects) for root in roots)
+
+    def render(self) -> str:
+        if not self._rows:
+            return "No roots found."
+
+        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()
+@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.pass_obj
+def roots(catalog: ProjectCatalog) -> None:
+    """List registered scan roots with project counts and status."""
+    settings = catalog.config.load()
+    table = RootListTable(settings.roots, catalog.projects())
+    click.echo(table.render())
+
+
+@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.")
+
+
+root_commands = (init, uninit, roots, refresh)

{pcd_cli-0.2.1 → pcd_cli-0.2.3}/src/pcd_cli/cli/shell.py

@@ -1,10 +1,10 @@
 import click
 
-from pcd_cli.shell_integration import (
+from pcd_cli.integrations.shell import (
     detect_shell,
+    invoking_shell,
     render_shell_integration,
     Shell,
-    shell_integration_active,
     ShellIntegration,
     ShellIntegrationError,
     ShellIntegrationState,
@@ -27,7 +27,7 @@ def install_shell(shell: str | None) -> None:
     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}")
+        click.echo(f"Reload the current shell with: {integration.reload_command()}")
         return
 
     state = integration.state()
@@ -47,14 +47,15 @@ def install_shell(shell: str | None) -> None:
     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."""
+    """Show shell configuration and whether this invocation used a wrapper."""
     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'}")
+    wrapper: Shell | None = invoking_shell()
+    invoked = "no" if wrapper is None else f"yes ({wrapper.value})"
+    click.echo(f"Invoked through wrapper: {invoked}")
 
 
 @shell_commands.command("uninstall")
@@ -78,30 +79,19 @@ def uninstall_shell(shell: str | None) -> None:
     click.echo(f"Shell integration is not installed in {integration.config_path}")
 
 
-@shell_commands.command("print")
+@shell_commands.command("init")
 @click.argument(
     "shell",
     required=False,
     type=click.Choice([item.value for item in Shell], case_sensitive=False),
 )
 @click.pass_context
-def print_shell_integration(ctx: click.Context, shell: str | None) -> None:
+def init_shell(ctx: click.Context, shell: str | None) -> None:
     """Print shell integration for manual dotfile management."""
     selected = _selected_shell(shell)
     click.echo(render_shell_integration(selected, _registered_command_names(ctx)), nl=False)
 
 
-@click.command("shell-init", hidden=True)
-@click.argument("shell", type=click.Choice([item.value for item in Shell], case_sensitive=False))
-@click.pass_context
-def shell_init(ctx: click.Context, shell: str) -> None:
-    """Backward-compatible alias for `pcd shell print`."""
-    click.echo(
-        render_shell_integration(Shell(shell.casefold()), _registered_command_names(ctx)),
-        nl=False,
-    )
-
-
 def _shell_integration(shell: str | None) -> ShellIntegration:
     return ShellIntegration.for_shell(_selected_shell(shell))
 

pcd_cli-0.2.3/src/pcd_cli/integrations/__init__.py

@@ -0,0 +1 @@
+"""External environment integrations."""

pcd_cli-0.2.1/src/pcd_cli/shell_integration.py → pcd_cli-0.2.3/src/pcd_cli/integrations/shell.py

@@ -1,6 +1,7 @@
 """Generate, install, and inspect shell integration for pcd."""
 
 import os
+import shlex
 import stat
 from dataclasses import dataclass
 from enum import StrEnum
@@ -11,6 +12,7 @@ from typing import Literal, Self
 from pcd_cli.filesystem import atomic_write, file_lock
 
 SHELL_MODE_ENV = "PCD_SHELL"
+SHELL_WRAPPER_ENV = "PCD_WRAPPER"
 # Internal success status: stdout contains the destination path when this is returned.
 SHELL_CD_EXIT_CODE = 10
 _MANAGED_BLOCK_START = "# >>> pcd shell integration >>>"
@@ -49,6 +51,9 @@ class ShellIntegration:
     def state(self) -> ShellIntegrationState:
         return _integration_state(self._read(), self.shell)
 
+    def reload_command(self) -> str:
+        return f"source {shlex.quote(str(self.config_path))}"
+
     def install(self) -> bool:
         """Install the managed block. Return whether the config changed."""
         with file_lock(self.config_path):
@@ -128,6 +133,14 @@ def shell_integration_active() -> bool:
     return os.environ.get(SHELL_MODE_ENV) == "1"
 
 
+def invoking_shell() -> Shell | None:
+    """Identify the wrapper for this invocation, not the parent shell's state."""
+    try:
+        return Shell(os.environ.get(SHELL_WRAPPER_ENV, ""))
+    except ValueError:
+        return None
+
+
 def inactive_shell_message() -> str:
     """Explain how to activate directory changes when the wrapper is not running."""
     try:
@@ -146,16 +159,16 @@ def inactive_shell_message() -> str:
         )
     return (
         f"Shell integration is configured in {integration.config_path} but is not active in "
-        f"this shell. Restart it or run: exec {integration.shell.value}"
+        f"this shell. Reload it with: {integration.reload_command()}"
     )
 
 
 def render_managed_block(shell: Shell) -> str:
     """Render the small persistent block written into the shell startup file."""
     command = (
-        f'eval "$(command pcd shell print {shell.value})"'
+        f'eval "$(command pcd shell init {shell.value})"'
         if shell is not Shell.FISH
-        else f"command pcd shell print {shell.value} | source"
+        else f"command pcd shell init {shell.value} | source"
     )
     return f"{_MANAGED_BLOCK_START}\n{command}\n{_MANAGED_BLOCK_END}\n"
 
@@ -179,9 +192,8 @@ def _integration_state(content: str, shell: Shell) -> ShellIntegrationState:
     if bounds is not None:
         return ShellIntegrationState.MANAGED
 
-    legacy = f"pcd shell-init {shell.value}"
-    current = f"pcd shell print {shell.value}"
-    if legacy in content or current in content:
+    current = f"pcd shell init {shell.value}"
+    if current in content:
         return ShellIntegrationState.MANUAL
     return ShellIntegrationState.ABSENT
 
@@ -214,6 +226,7 @@ def _posix(completion: Literal["bash_source", "zsh_source"], commands: tuple[str
     return dedent(
         f"""\
         pcd() {{
+            local -x {SHELL_WRAPPER_ENV}={completion.removesuffix("_source")}
             if [ -n "${{_PCD_COMPLETE:-}}" ]; then
                 command pcd "$@"
                 return $?
@@ -260,6 +273,7 @@ def _fish(commands: tuple[str, ...]) -> str:
     return dedent(
         f"""\
         function pcd
+            set -lx {SHELL_WRAPPER_ENV} fish
             if set -q _PCD_COMPLETE
                 command pcd $argv
                 return $status
@@ -277,7 +291,10 @@ def _fish(commands: tuple[str, ...]) -> str:
                     return $status
             end
 
-            set -l output (env {SHELL_MODE_ENV}=1 command pcd $argv)
+            set -l output (begin
+                set -lx {SHELL_MODE_ENV} 1
+                command pcd $argv
+            end)
             set -l code $status
             if test $code -eq {SHELL_CD_EXIT_CODE}
                 cd -- "$output"

{pcd_cli-0.2.1 → pcd_cli-0.2.3}/src/pcd_cli/navigation.py

@@ -7,12 +7,12 @@ 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 (
+from pcd_cli.integrations.shell import (
     inactive_shell_message,
     SHELL_CD_EXIT_CODE,
     shell_integration_active,
 )
+from pcd_cli.models import ExitCode, ProjectSource
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -65,7 +65,10 @@ def project_completions(value: str) -> list[CompletionItem]:
 
 def _open_project(catalog: ProjectCatalog, project: Project) -> None:
     if project.path.is_dir():
-        catalog.record_usage(project)
+        try:
+            catalog.record_usage(project)
+        except OSError as exc:
+            click.echo(f"Warning: could not write usage history: {exc}", err=True)
     elif project.source is ProjectSource.MANUAL:
         click.echo(
             f"Project path no longer exists: {format_path(project.display_path)}",