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

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

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: pcd-cli
-Version: 0.2.3
-Summary: Fast project navigator for Bash, Zsh and Fish
+Version: 0.2.4
+Summary: Fast project navigator for Bash, Zsh, Fish, PowerShell and CMD
 License-Expression: MIT
 License-File: LICENSE
-Keywords: cli,cd,projects,navigation,bash,zsh,fish
+Keywords: cli,cd,projects,navigation,bash,zsh,fish,powershell,cmd
 Author: pcd-cli contributors
 Requires-Python: >=3.12,<4
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -19,6 +20,7 @@ Classifier: Topic :: Utilities
 Requires-Dist: click (>=8.5.0,<9)
 Requires-Dist: platformdirs (>=4.11.7,<5)
 Requires-Dist: prompt-toolkit (>=3.0.53,<4)
+Requires-Dist: shellingham (>=1.5.4,<2) ; sys_platform == "win32"
 Requires-Dist: tomlkit (>=0.15.1,<1)
 Description-Content-Type: text/plain
 
@@ -36,6 +38,10 @@ Supported shells:
 * Bash
 * Zsh
 * Fish
+* PowerShell 7+
+* Windows PowerShell 5.1
+* Command Prompt (cmd)
+* Git Bash on Windows
 
 
 INSTALL

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

@@ -12,6 +12,10 @@ Supported shells:
 * Bash
 * Zsh
 * Fish
+* PowerShell 7+
+* Windows PowerShell 5.1
+* Command Prompt (cmd)
+* Git Bash on Windows
 
 
 INSTALL

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

@@ -1,18 +1,19 @@
 [project]
 name = "pcd-cli"
-version = "0.2.3"
-description = "Fast project navigator for Bash, Zsh and Fish"
+version = "0.2.4"
+description = "Fast project navigator for Bash, Zsh, Fish, PowerShell and CMD"
 readme = { file = "README.txt", content-type = "text/plain" }
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "pcd-cli contributors" }]
 requires-python = ">=3.12,<4"
-keywords = ["cli", "cd", "projects", "navigation", "bash", "zsh", "fish"]
+keywords = ["cli", "cd", "projects", "navigation", "bash", "zsh", "fish", "powershell", "cmd"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -23,6 +24,7 @@ dependencies = [
     "click>=8.5.0,<9",
     "platformdirs>=4.11.7,<5",
     "prompt-toolkit>=3.0.53,<4",
+    "shellingham>=1.5.4,<2; sys_platform == 'win32'",
     "tomlkit>=0.15.1,<1",
 ]
 
@@ -107,5 +109,5 @@ fail_under = 95
 show_missing = true
 skip_covered = true
 exclude_also = [
-    "if TYPE_CHECKING:",
+    "if TYPE_CHECKING",
 ]

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

@@ -68,12 +68,15 @@ def package_version() -> str:
 @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 == "shell":
+        return
+
+    catalog = ProjectCatalog.create()
+    ctx.obj = catalog
+
     if ctx.invoked_subcommand is not None:
         return
 
@@ -103,5 +106,5 @@ def main() -> None:
         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)
+        click.echo(f"I/O error: {exc}", err=True)
         raise SystemExit(ExitCode.ERROR) from None

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

@@ -3,6 +3,7 @@ from __future__ import annotations
 import os
 import shlex
 import subprocess
+import sys
 from typing import TYPE_CHECKING
 
 import click
@@ -55,7 +56,11 @@ def edit_config(catalog: ProjectCatalog) -> None:
 
     catalog.config.ensure_exists()
 
-    result = subprocess.run([*command, str(catalog.config.path)], check=False)
+    arguments = [*command, str(catalog.config.path)]
+    if os.environ.get("PCD_SHELL") == "1":
+        result = subprocess.run(arguments, check=False, stdout=sys.stderr)
+    else:
+        result = subprocess.run(arguments, check=False)
     if result.returncode:
         raise click.ClickException(f"Editor exited with status {result.returncode}")
 

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

@@ -1,3 +1,5 @@
+import sys
+
 import click
 
 from pcd_cli.integrations.shell import (
@@ -24,7 +26,8 @@ def shell_commands() -> None:
 )
 def install_shell(shell: str | None) -> None:
     """Install persistent shell integration into the shell startup file."""
-    integration = _shell_integration(shell)
+    selected = _select_shell(shell, prompt=True)
+    integration = ShellIntegration.for_shell(selected)
     if integration.install():
         click.echo(f"Installed {integration.shell.value} integration in {integration.config_path}")
         click.echo(f"Reload the current shell with: {integration.reload_command()}")
@@ -48,7 +51,7 @@ def install_shell(shell: str | None) -> None:
 )
 def shell_status(shell: str | None) -> None:
     """Show shell configuration and whether this invocation used a wrapper."""
-    integration = _shell_integration(shell)
+    integration = ShellIntegration.for_shell(_select_shell(shell))
     click.echo(f"Shell: {integration.shell.value}")
     click.echo(f"Config: {integration.config_path}")
     click.echo(f"Configured: {integration.state().value}")
@@ -66,7 +69,7 @@ def shell_status(shell: str | None) -> None:
 )
 def uninstall_shell(shell: str | None) -> None:
     """Remove integration installed by `pcd shell install`."""
-    integration = _shell_integration(shell)
+    integration = ShellIntegration.for_shell(_select_shell(shell))
     if integration.uninstall():
         click.echo(f"Removed shell integration from {integration.config_path}")
         return
@@ -85,30 +88,40 @@ def uninstall_shell(shell: str | None) -> None:
     required=False,
     type=click.Choice([item.value for item in Shell], case_sensitive=False),
 )
-@click.pass_context
-def init_shell(ctx: click.Context, shell: str | None) -> None:
+def init_shell(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)
-
+    selected = _select_shell(shell)
+    click.echo(render_shell_integration(selected), nl=False)
 
-def _shell_integration(shell: str | None) -> ShellIntegration:
-    return ShellIntegration.for_shell(_selected_shell(shell))
 
-
-def _selected_shell(shell: str | None) -> Shell:
+def _select_shell(shell: str | None, *, prompt: bool = False) -> Shell:
     if shell is not None:
         return Shell(shell.casefold())
 
     try:
         return detect_shell()
     except ShellIntegrationError as exc:
+        if prompt and sys.platform == "win32":
+            return _prompt_windows_shell()
         raise click.UsageError(str(exc)) from exc
 
 
-def _registered_command_names(ctx: click.Context) -> tuple[str, ...]:
-    root = ctx.find_root()
-    if not isinstance(root.command, click.Group):
-        return ()
+def _prompt_windows_shell() -> Shell:
+    choices = (
+        ("PowerShell 7+", Shell.PWSH),
+        ("Windows PowerShell 5.1", Shell.POWERSHELL),
+        ("Command Prompt (cmd)", Shell.CMD),
+        ("Git Bash", Shell.BASH),
+    )
+
+    click.echo("Select shell:")
+    for index, (label, _shell) in enumerate(choices, start=1):
+        click.echo(f"  {index}. {label}")
+
+    choice = click.prompt(
+        "Enter number",
+        type=click.IntRange(1, len(choices)),
+        show_choices=False,
+    )
 
-    return tuple(root.command.list_commands(root))
+    return choices[choice - 1][1]

{pcd_cli-0.2.3 → pcd_cli-0.2.4}/src/pcd_cli/filesystem.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import fcntl
 import os
 import tempfile
 from contextlib import contextmanager
@@ -10,6 +9,8 @@ from typing import Self, TextIO, TYPE_CHECKING
 
 from platformdirs import PlatformDirs
 
+from pcd_cli.locking import file_lock as file_lock
+
 if TYPE_CHECKING:
     from collections.abc import Generator
 
@@ -48,20 +49,6 @@ def format_path(path: Path) -> str:
     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."""

pcd_cli-0.2.4/src/pcd_cli/integrations/shell.py

@@ -0,0 +1,146 @@
+"""Generate, install, and inspect shell integration for pcd."""
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Self
+
+from pcd_cli.integrations.shells import startup_file
+from pcd_cli.integrations.shells.common import (
+    Shell as Shell,
+    SHELL_CD_EXIT_CODE as SHELL_CD_EXIT_CODE,
+    SHELL_MODE_ENV,
+    SHELL_WRAPPER_ENV,
+    ShellIntegrationError as ShellIntegrationError,
+    ShellIntegrationState as ShellIntegrationState,
+)
+from pcd_cli.integrations.shells.registry import backend_for
+
+
+@dataclass(frozen=True, slots=True)
+class ShellIntegration:
+    shell: Shell
+    config_path: Path
+
+    @classmethod
+    def detect(cls) -> Self:
+        return cls.for_shell(detect_shell())
+
+    @classmethod
+    def for_shell(cls, shell: Shell) -> Self:
+        return cls(shell=shell, config_path=shell_config_path(shell))
+
+    def state(self) -> ShellIntegrationState:
+        if self.shell is Shell.CMD:
+            from pcd_cli.integrations.shells import cmd
+
+            return cmd.state(self.config_path)
+        return startup_file.state(self.config_path, self.shell)
+
+    def reload_command(self) -> str:
+        return backend_for(self.shell).reload_command(self.shell, self.config_path)
+
+    def install(self) -> bool:
+        """Install managed integration. Return whether persistent state changed."""
+        if self.shell is Shell.CMD:
+            from pcd_cli.integrations.shells import cmd
+
+            return cmd.install(self.config_path)
+        command = backend_for(self.shell).startup_command(self.shell)
+        if command is None:
+            raise ShellIntegrationError(f"Shell does not use a startup file: {self.shell}")
+        return startup_file.install(self.config_path, self.shell, command)
+
+    def uninstall(self) -> bool:
+        """Remove only integration installed by pcd, leaving manual setup untouched."""
+        if self.shell is Shell.CMD:
+            from pcd_cli.integrations.shells import cmd
+
+            return cmd.uninstall(self.config_path)
+        return startup_file.uninstall(self.config_path)
+
+
+def detect_shell() -> Shell:
+    """Detect the active wrapper or surrounding shell."""
+    wrapper = invoking_shell()
+    if wrapper is not None:
+        return wrapper
+
+    if sys.platform == "win32":
+        from pcd_cli.integrations.shells import windows_shell
+
+        name = windows_shell.detect_shell()
+        source = "the parent process"
+    else:
+        executable = os.environ.get("SHELL", "")
+        name = Path(executable).name.casefold().removesuffix(".exe")
+        source = f"SHELL={executable!r}"
+
+    try:
+        return Shell(name)
+    except ValueError as exc:
+        supported = ", ".join(shell.value for shell in Shell)
+        raise ShellIntegrationError(
+            f"Cannot detect a supported shell from {source}; choose one of: {supported}"
+        ) from exc
+
+
+def shell_config_path(shell: Shell) -> Path:
+    """Return the persistent integration file for a shell."""
+    return backend_for(shell).config_path(shell, Path.home())
+
+
+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."""
+    install_command = "pcd shell install"
+    if sys.platform == "win32" and invoking_shell() is None:
+        return (
+            "Shell integration is not active, so pcd cannot change this shell's directory. "
+            f"If you have not configured it manually, run: {install_command}"
+        )
+
+    try:
+        integration = ShellIntegration.detect()
+        state = integration.state()
+    except (OSError, ShellIntegrationError):
+        return (
+            "Shell integration is not active, so pcd cannot change this shell's directory. "
+            f"If you have not configured it manually, run: {install_command}"
+        )
+
+    if state is ShellIntegrationState.ABSENT:
+        return (
+            "Shell integration is not installed, so pcd cannot change this shell's directory. "
+            f"Install it with: {install_command}"
+        )
+
+    return (
+        f"Shell integration is configured in {integration.config_path} but is not active in "
+        f"this shell. Reload it with: {integration.reload_command()}"
+    )
+
+
+def render_managed_block(shell: Shell) -> str:
+    """Render the small persistent block written into a shell startup file."""
+    command = backend_for(shell).startup_command(shell)
+    if command is None:
+        raise ValueError(f"Shell does not use a startup file: {shell}")
+    return startup_file.managed_block(command)
+
+
+def render_shell_integration(shell: Shell) -> str:
+    """Generate shell integration for directory changes and completion."""
+    return backend_for(shell).render(shell)

pcd_cli-0.2.4/src/pcd_cli/integrations/shells/__init__.py

@@ -0,0 +1 @@
+"""Shell-specific integration backends."""

pcd_cli-0.2.4/src/pcd_cli/integrations/shells/cmd.py

@@ -0,0 +1,176 @@
+"""CMD wrapper backend and installation lifecycle."""
+
+import os
+import stat
+import sys
+from pathlib import Path
+from textwrap import dedent
+
+from pcd_cli.filesystem import atomic_write, file_lock
+from pcd_cli.integrations.shells import cmd_autorun
+from pcd_cli.integrations.shells.common import (
+    Shell,
+    SHELL_CD_EXIT_CODE,
+    SHELL_MODE_ENV,
+    SHELL_WRAPPER_ENV,
+    ShellIntegrationError,
+    ShellIntegrationState,
+)
+
+_MANAGED_HEADER = "@echo off\nrem Managed by pcd. Changes will be overwritten.\n"
+
+
+def config_path(shell: Shell, home: Path) -> Path:
+    local_app_data = os.environ.get("LOCALAPPDATA")
+    data_home = Path(local_app_data) if local_app_data else home / "AppData" / "Local"
+    return data_home / "pcd-cli" / "cmd" / "pcd.cmd"
+
+
+def reload_command(shell: Shell, wrapper: Path) -> str:
+    return cmd_autorun.doskey_command(wrapper)
+
+
+def startup_command(shell: Shell) -> None:
+    return None
+
+
+def state(wrapper: Path) -> ShellIntegrationState:
+    _require_windows("inspected")
+
+    if not wrapper.exists():
+        if cmd_autorun.configured(wrapper):
+            raise ShellIntegrationError(
+                "CMD integration is incomplete: the registered wrapper is missing"
+            )
+
+        return ShellIntegrationState.ABSENT
+
+    if not _is_managed(_read(wrapper)):
+        return ShellIntegrationState.MANUAL
+
+    if not cmd_autorun.configured(wrapper):
+        raise ShellIntegrationError(
+            "CMD integration is incomplete: AutoRun registration is missing"
+        )
+
+    return ShellIntegrationState.MANAGED
+
+
+def install(wrapper: Path) -> bool:
+    _require_windows("installed")
+
+    content = render(Shell.CMD)
+
+    with file_lock(wrapper):
+        previous = _read(wrapper) if wrapper.exists() else None
+        if previous is not None and not _is_managed(previous):
+            return False
+
+        wrapper_changed = previous != content
+        try:
+            if wrapper_changed:
+                _write(wrapper, content)
+            autorun_changed = cmd_autorun.add(wrapper)
+        except BaseException as error:
+            if wrapper_changed:
+                try:
+                    if previous is None:
+                        wrapper.unlink(missing_ok=True)
+                    else:
+                        _write(wrapper, previous)
+                except OSError as rollback_error:
+                    raise ShellIntegrationError(
+                        f"CMD installation failed: {error}; "
+                        f"could not restore wrapper {wrapper}: {rollback_error}"
+                    ) from error
+            raise
+
+        return wrapper_changed or autorun_changed
+
+
+def uninstall(wrapper: Path) -> bool:
+    _require_windows("uninstalled")
+
+    with file_lock(wrapper):
+        if not wrapper.exists():
+            if not cmd_autorun.configured(wrapper):
+                return False
+
+            cmd_autorun.remove(wrapper)
+            return True
+
+        if not _is_managed(_read(wrapper)):
+            return False
+
+        cmd_autorun.remove(wrapper)
+        try:
+            wrapper.unlink(missing_ok=True)
+        except OSError as error:
+            try:
+                cmd_autorun.add(wrapper)
+            except (OSError, ShellIntegrationError) as rollback_error:
+                raise ShellIntegrationError(
+                    f"Could not remove CMD wrapper {wrapper}: {error}; "
+                    f"could not restore AutoRun: {rollback_error}"
+                ) from error
+            raise
+
+        return True
+
+
+def render(shell: Shell) -> str:
+    return dedent(
+        f"""\
+        @echo off
+        rem Managed by pcd. Changes will be overwritten.
+        setlocal
+        set "{SHELL_WRAPPER_ENV}=cmd"
+        if not defined _PCD_EXECUTABLE set "_PCD_EXECUTABLE=pcd.exe"
+
+        if defined _PCD_COMPLETE goto pcd_direct
+
+        set "{SHELL_MODE_ENV}=1"
+        set "pcd_output=%TEMP%\\pcd-%RANDOM%-%RANDOM%.tmp"
+        call "%_PCD_EXECUTABLE%" %* > "%pcd_output%"
+        set "pcd_code=%ERRORLEVEL%"
+        if "%pcd_code%"=="{SHELL_CD_EXIT_CODE}" goto pcd_change_directory
+        type "%pcd_output%"
+        del /q "%pcd_output%"
+        endlocal & exit /b %pcd_code%
+
+        :pcd_change_directory
+        set /p "pcd_destination=" < "%pcd_output%"
+        del /q "%pcd_output%"
+        endlocal & cd /d "%pcd_destination%"
+        exit /b %ERRORLEVEL%
+
+        :pcd_direct
+        call "%_PCD_EXECUTABLE%" %*
+        exit /b %ERRORLEVEL%
+        """
+    )
+
+
+def _write(path: Path, content: str) -> None:
+    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else None
+    with atomic_write(path) as stream:
+        stream.write(content)
+
+    if mode is not None:
+        path.chmod(mode)
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeError as exc:
+        raise ShellIntegrationError(f"CMD wrapper is not valid UTF-8: {path}") from exc
+
+
+def _is_managed(content: str) -> bool:
+    return content.startswith(_MANAGED_HEADER)
+
+
+def _require_windows(action: str) -> None:
+    if sys.platform != "win32":
+        raise ShellIntegrationError(f"CMD integration can only be {action} on Windows")

pcd_cli-0.2.4/src/pcd_cli/integrations/shells/cmd_autorun.py

@@ -0,0 +1,78 @@
+"""Manage the pcd DOSKEY command in the CMD AutoRun registry value."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import TYPE_CHECKING
+
+from pcd_cli.integrations.shells import windows_registry
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_COMMAND_PROCESSOR_KEY = r"Software\Microsoft\Command Processor"
+
+
+def doskey_command(wrapper: Path) -> str:
+    return f'doskey pcd=call "{wrapper}" $*'
+
+
+def add(wrapper: Path) -> bool:
+    """Add the pcd command, returning whether AutoRun was changed."""
+    value, value_type = _read()
+    managed_command = doskey_command(wrapper)
+
+    if _without_command(value, managed_command) is not None:
+        return False
+
+    separator = "" if not value.strip() else " & "
+    _write(f"{value}{separator}{managed_command}", value_type)
+
+    return True
+
+
+def configured(wrapper: Path) -> bool:
+    value, _value_type = _read()
+    return _without_command(value, doskey_command(wrapper)) is not None
+
+
+def remove(wrapper: Path) -> None:
+    value, value_type = _read()
+    updated = _without_command(value, doskey_command(wrapper))
+    if updated is not None:
+        _write(updated, value_type)
+
+
+def _without_command(value: str, managed_command: str) -> str | None:
+    """Return AutoRun without an exact managed command, wherever it appears."""
+    index = value.casefold().find(managed_command.casefold())
+    if index < 0:
+        return None
+
+    before = value[:index]
+    after = value[index + len(managed_command) :]
+    if before and not before.endswith(" & "):
+        return None
+    if after and not after.startswith(" & "):
+        return None
+
+    if before:
+        return f"{before[:-3]}{after}"
+
+    if after:
+        return after[3:]
+
+    return ""
+
+
+def _read() -> tuple[str, int]:
+    result = windows_registry.read(_COMMAND_PROCESSOR_KEY, "AutoRun")
+    return result if result is not None else ("", windows_registry.string_value_type())
+
+
+def _write(value: str, value_type: int) -> None:
+    if value:
+        windows_registry.write(_COMMAND_PROCESSOR_KEY, "AutoRun", value, value_type)
+    else:
+        with suppress(FileNotFoundError):
+            windows_registry.delete(_COMMAND_PROCESSOR_KEY, "AutoRun")