cd-browser 0.2.4__tar.gz → 0.2.6__tar.gz

{cd_browser-0.2.4 → cd_browser-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cd-browser
-Version: 0.2.4
+Version: 0.2.6
 Summary: A fast keyboard-driven directory navigator for the terminal.
 Author: Saky
 Classifier: Development Status :: 3 - Alpha
@@ -34,6 +34,8 @@ It lets you explore directory trees visually and jump to any folder instantly.
 
 ![cd-browser demo](https://gitea.sakydogalo.es/saky/cd-browser/raw/branch/main/docs/demo.gif)
 
+Repository (full demo + docs): https://gitea.sakydogalo.es/saky/cd-browser
+
 ## Why cd-browser?
 
 Working in the terminal often means:
@@ -46,14 +48,65 @@ Working in the terminal often means:
 
 ## Features
 
-- 🚀 Fast visual navigation of directory trees
-- ⌨️ Fully keyboard-driven workflow
-- 🌲 Expand and collapse directories
-- 📜 Navigation history inside the session
+- ⌨️ Fully keyboard-driven workflow (`↑` / `↓` / `←` / `→`)
+- 🌲 Expand and collapse directories (`→` to expand/enter, `←` to collapse/back)
+- 📜 Navigation history inside the session (`h` history mode, `b` back, `f` forward)
+- 🔎 Incremental filter mode (`/`, type to filter, `Backspace`, `Esc`)
+- 📄 Toggle file visibility (`a`) to switch between directories-only and mixed view
+- ⚡ Fast jumps in large lists (`PgUp`/`PgDn`, `Home`/`End`, `g`/`G` in normal mode)
+- 🚀 Contextual `open with` menu (`o`) with app detection based on your environment
+- 🔁 Blocking terminal editors restore the UI state when they exit (`nvim`, `nano`, `less`, `bat`)
+- 👀 Toggle hidden entries with `.`
 - 🖥 Native terminal interface
 - 🔁 Works with Bash, Zsh and other shells
-- ⚡ Returns the selected path to the shell
-- 🔎 Press `.` to toggle hidden directories
+- ⚡ Returns the selected path to the shell (`Enter` to confirm, `Esc` to cancel)
+
+## Controls
+
+Normal mode:
+
+- `↑` / `↓`: Move selection
+- `→`: Expand directory, or enter when already expanded
+- `←`: Collapse directory, or go to parent
+- `Enter`: Confirm selected path and exit
+- `Esc`: Cancel and return the original path
+- `h`: Toggle history mode
+- `b` / `f`: Back / forward in navigation history
+- `.`: Toggle hidden entries
+- `a`: Toggle file visibility
+- `/`: Enter filter mode
+- `o`: Open selected entry with an app
+- `PgUp` / `PgDn`: Page jump
+- `Home` / `End`: Jump to first/last entry
+- `g` / `G`: Jump to first/last entry
+
+Filter mode:
+
+- Type text: Filter visible entries in real time (case-insensitive)
+- `↑` / `↓`: Move inside filtered results
+- `Enter`: Apply filter and perform contextual action:
+  - Directory: navigate into it without exiting `cd_`
+  - File: open app selection menu
+- `Esc`: Exit filter mode and clear query
+- `Backspace`: Remove last filter character
+
+History mode:
+
+- `↑` / `↓`: Move through history entries
+- `Enter`: Jump to selected history path
+- `Esc` or `h`: Exit history mode
+- `PgUp` / `PgDn`, `Home` / `End`: Fast history navigation
+
+Open with menu (`o`):
+
+- `↑` / `↓`: Move between app options
+- `Enter`: Launch selected app
+- `Esc`: Cancel
+
+The menu only shows apps available in your system (`PATH`) and context:
+
+- GUI options (when GUI is available): `code`, system `open`/`xdg-open`
+- Terminal options: `antigravity`, `nvim`, `nano`, `less`, `bat` (as applicable)
 
 ## Quick Demo
 
@@ -124,7 +177,14 @@ Then use:
 cd_
 ```
 
-- Dentro de `cd_browser`, presiona `.` para alternar la visualización de carpetas ocultas.
+- Inside `cd_browser`, press `.` to toggle hidden entries.
+
+## Platform Compatibility
+
+Practical conclusion:
+
+- Best current support: **macOS and Linux**
+- **Windows is partially supported**, but still needs real-world validation in Windows terminal environments before being considered fully supported
 
 ## Uninstall
 

cd_browser-0.2.6/README.md

@@ -0,0 +1,200 @@
+# cd-browser
+
+**Stop typing paths. Browse them.**
+
+`cd-browser` is a fast keyboard-driven directory navigator for the terminal.
+It lets you explore directory trees visually and jump to any folder instantly.
+
+![cd-browser demo](https://gitea.sakydogalo.es/saky/cd-browser/raw/branch/main/docs/demo.gif)
+
+Repository (full demo + docs): https://gitea.sakydogalo.es/saky/cd-browser
+
+## Why cd-browser?
+
+Working in the terminal often means:
+
+- typing long directory paths
+- navigating deep folder trees
+- repeating `cd ..` multiple times
+
+`cd-browser` provides an **interactive terminal UI** that allows you to browse directories with the keyboard and return the selected path directly to your shell.
+
+## Features
+
+- ⌨️ Fully keyboard-driven workflow (`↑` / `↓` / `←` / `→`)
+- 🌲 Expand and collapse directories (`→` to expand/enter, `←` to collapse/back)
+- 📜 Navigation history inside the session (`h` history mode, `b` back, `f` forward)
+- 🔎 Incremental filter mode (`/`, type to filter, `Backspace`, `Esc`)
+- 📄 Toggle file visibility (`a`) to switch between directories-only and mixed view
+- ⚡ Fast jumps in large lists (`PgUp`/`PgDn`, `Home`/`End`, `g`/`G` in normal mode)
+- 🚀 Contextual `open with` menu (`o`) with app detection based on your environment
+- 🔁 Blocking terminal editors restore the UI state when they exit (`nvim`, `nano`, `less`, `bat`)
+- 👀 Toggle hidden entries with `.`
+- 🖥 Native terminal interface
+- 🔁 Works with Bash, Zsh and other shells
+- ⚡ Returns the selected path to the shell (`Enter` to confirm, `Esc` to cancel)
+
+## Controls
+
+Normal mode:
+
+- `↑` / `↓`: Move selection
+- `→`: Expand directory, or enter when already expanded
+- `←`: Collapse directory, or go to parent
+- `Enter`: Confirm selected path and exit
+- `Esc`: Cancel and return the original path
+- `h`: Toggle history mode
+- `b` / `f`: Back / forward in navigation history
+- `.`: Toggle hidden entries
+- `a`: Toggle file visibility
+- `/`: Enter filter mode
+- `o`: Open selected entry with an app
+- `PgUp` / `PgDn`: Page jump
+- `Home` / `End`: Jump to first/last entry
+- `g` / `G`: Jump to first/last entry
+
+Filter mode:
+
+- Type text: Filter visible entries in real time (case-insensitive)
+- `↑` / `↓`: Move inside filtered results
+- `Enter`: Apply filter and perform contextual action:
+  - Directory: navigate into it without exiting `cd_`
+  - File: open app selection menu
+- `Esc`: Exit filter mode and clear query
+- `Backspace`: Remove last filter character
+
+History mode:
+
+- `↑` / `↓`: Move through history entries
+- `Enter`: Jump to selected history path
+- `Esc` or `h`: Exit history mode
+- `PgUp` / `PgDn`, `Home` / `End`: Fast history navigation
+
+Open with menu (`o`):
+
+- `↑` / `↓`: Move between app options
+- `Enter`: Launch selected app
+- `Esc`: Cancel
+
+The menu only shows apps available in your system (`PATH`) and context:
+
+- GUI options (when GUI is available): `code`, system `open`/`xdg-open`
+- Terminal options: `antigravity`, `nvim`, `nano`, `less`, `bat` (as applicable)
+
+## Quick Demo
+
+Run:
+
+```bash
+cd_
+```
+
+Browse directories using the arrow keys and press **Enter** to jump directly to the selected folder.
+
+## Documentation
+
+See the documentation index:
+
+```
+docs/index.md
+```
+
+## Installation
+
+Install the project in user mode:
+
+```bash
+pip install cd-browser
+```
+
+**Important**: After installation, run this to set up the `cd_` command:
+
+```bash
+cd_browser_post_install
+```
+
+This interactive script will guide you through enabling `cd_` in your shell.
+
+## Shell Integration For `cd_`
+
+Because a Python subprocess cannot directly change the parent shell directory, use a shell wrapper that captures the final path printed by `cd_browser`.
+
+Bash or Zsh example:
+
+```bash
+cd_() {
+  local target
+  target="$(cd_browser)" || return
+
+  if [ -n "$target" ] && [ -d "$target" ]; then
+    cd "$target"
+  fi
+}
+```
+
+After adding the function to your shell profile, reload it:
+
+```bash
+source ~/.bashrc
+```
+
+Or:
+
+```bash
+source ~/.zshrc
+```
+
+Then use:
+
+```bash
+cd_
+```
+
+- Inside `cd_browser`, press `.` to toggle hidden entries.
+
+## Platform Compatibility
+
+Practical conclusion:
+
+- Best current support: **macOS and Linux**
+- **Windows is partially supported**, but still needs real-world validation in Windows terminal environments before being considered fully supported
+
+## Uninstall
+
+If the project was installed with `pip`, remove it with:
+
+```bash
+pip uninstall cd-browser
+```
+
+**Important**: After uninstalling, remove the `cd_()` function from your shell profile (~/.bashrc or ~/.zshrc) to clean up completely.
+
+## Developer Setup
+
+Recommended setup:
+
+```bash
+make dev
+```
+
+Run the application in development mode:
+
+```bash
+python -m app.main
+```
+
+Useful development commands:
+
+```bash
+make fix
+make quality
+make run
+```
+
+## Template Origin
+
+This project was created from the Python AI Dev Template.
+
+The original template documentation has been preserved in `README_TEMPLATE.md` so the project-specific README can focus on `cd-browser` usage and development.
+
+For the original template setup, conventions, and generic workflow notes, see `README_TEMPLATE.md`.

{cd_browser-0.2.4 → cd_browser-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cd-browser"
-version = "0.2.4"
+version = "0.2.6"
 description = "A fast keyboard-driven directory navigator for the terminal."
 readme = "README.md"
 requires-python = ">=3.8"

{cd_browser-0.2.4 → cd_browser-0.2.6}/src/app/filesystem.py

@@ -13,11 +13,37 @@ class DirectoryEntry:
     has_children: bool
 
 
+@dataclass(frozen=True, slots=True)
+class FileSystemEntry:
+    """Filesystem entry metadata for tree rendering."""
+
+    name: str
+    path: Path
+    is_directory: bool
+    has_children: bool
+
+
 def list_directories(path: Path, show_hidden: bool = False) -> list[DirectoryEntry]:
     """Return direct child directories sorted by name."""
 
+    entries = list_entries(path, show_hidden=show_hidden, include_files=False)
+    return [
+        DirectoryEntry(
+            name=entry.name,
+            path=entry.path,
+            has_children=entry.has_children,
+        )
+        for entry in entries
+    ]
+
+
+def list_entries(
+    path: Path, show_hidden: bool = False, include_files: bool = False
+) -> list[FileSystemEntry]:
+    """Return direct child entries sorted by type and name."""
+
     directory_path = path.expanduser().resolve()
-    entries: list[DirectoryEntry] = []
+    entries: list[FileSystemEntry] = []
 
     try:
         children = list(directory_path.iterdir())
@@ -30,20 +56,28 @@ def list_directories(path: Path, show_hidden: bool = False) -> list[DirectoryEnt
         except OSError:
             continue
 
-        if not is_directory:
+        if not is_directory and not include_files:
             continue
         if not show_hidden and child.name.startswith("."):
             continue
 
         entries.append(
-            DirectoryEntry(
+            FileSystemEntry(
                 name=child.name,
                 path=child,
-                has_children=has_subdirectories(child, show_hidden=show_hidden),
+                is_directory=is_directory,
+                has_children=(
+                    has_subdirectories(child, show_hidden=show_hidden)
+                    if is_directory
+                    else False
+                ),
             )
         )
 
-    return sorted(entries, key=lambda entry: entry.name.casefold())
+    return sorted(
+        entries,
+        key=lambda entry: (not entry.is_directory, entry.name.casefold()),
+    )
 
 
 def has_subdirectories(path: Path, show_hidden: bool = False) -> bool:

{cd_browser-0.2.4 → cd_browser-0.2.6}/src/app/navigator.py

@@ -3,13 +3,13 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from app.filesystem import list_directories
+from app.filesystem import list_entries
 from app.history import SessionHistory
 
 
 @dataclass(frozen=True, slots=True)
 class VisibleEntry:
-    """A directory row visible in the navigator."""
+    """A row visible in the navigator tree."""
 
     name: str
     path: Path
@@ -17,6 +17,7 @@ class VisibleEntry:
     has_children: bool
     is_expanded: bool
     is_parent: bool = False
+    is_file: bool = False
 
 
 @dataclass(slots=True)
@@ -29,6 +30,7 @@ class Navigator:
     selected_index: int = field(init=False, default=0)
     _expanded_paths: set[Path] = field(init=False, default_factory=set)
     show_hidden: bool = False
+    show_files: bool = False
 
     def __post_init__(self) -> None:
         self.current_path = self.start_path.expanduser().resolve()
@@ -69,6 +71,9 @@ class Navigator:
     def enter_selected_directory(self) -> Path:
         """Enter the currently selected directory and record it in history."""
 
+        if self.selected_entry.is_file:
+            return self.current_path
+
         return self._change_directory(self.selected_entry.path)
 
     def go_to_parent_directory(self) -> Path:
@@ -149,6 +154,15 @@ class Navigator:
         """Toggle showing/hiding hidden directory entries."""
 
         self.show_hidden = not self.show_hidden
+        self._reset_view_state()
+
+    def toggle_files(self) -> None:
+        """Toggle showing/hiding file entries."""
+
+        self.show_files = not self.show_files
+        self._reset_view_state()
+
+    def _reset_view_state(self) -> None:
         self.selected_index = 0
         self._expanded_paths.clear()
 
@@ -162,20 +176,25 @@ class Navigator:
     def _build_entries(self, path: Path, depth: int) -> list[VisibleEntry]:
         entries: list[VisibleEntry] = []
 
-        for directory in list_directories(path, show_hidden=self.show_hidden):
-            is_expanded = directory.path in self._expanded_paths
+        for item in list_entries(
+            path, show_hidden=self.show_hidden, include_files=self.show_files
+        ):
+            is_expanded = (
+                item.path in self._expanded_paths if item.is_directory else False
+            )
             entries.append(
                 VisibleEntry(
-                    name=directory.name,
-                    path=directory.path,
+                    name=item.name,
+                    path=item.path,
                     depth=depth,
-                    has_children=directory.has_children,
+                    has_children=item.has_children,
                     is_expanded=is_expanded,
+                    is_file=not item.is_directory,
                 )
             )
 
             if is_expanded:
-                entries.extend(self._build_entries(directory.path, depth=depth + 1))
+                entries.extend(self._build_entries(item.path, depth=depth + 1))
 
         return entries
 

cd_browser-0.2.6/src/app/opener.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+LaunchMode = Literal["background", "blocking"]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenWithOption:
+    """Candidate application command for opening a path."""
+
+    label: str
+    command_template: str
+    executable: str
+    launch_mode: LaunchMode
+    requires_gui: bool = False
+    supports_files: bool = True
+    supports_directories: bool = True
+
+
+def available_openers(path: Path) -> list[OpenWithOption]:
+    """Return available open-with options for a file or directory path."""
+
+    is_directory = path.is_dir()
+    has_gui = _has_gui_session()
+    options: list[OpenWithOption] = []
+
+    for option in _default_options():
+        if is_directory and not option.supports_directories:
+            continue
+        if not is_directory and not option.supports_files:
+            continue
+        if option.requires_gui and not has_gui:
+            continue
+        if not shutil.which(option.executable):
+            continue
+
+        options.append(option)
+
+    return options
+
+
+def launch_background_option(path: Path, option: OpenWithOption) -> tuple[bool, str]:
+    """Launch a non-blocking option and return status/message."""
+
+    command = _command_parts(option.command_template, path)
+    if not command:
+        return False, "Invalid open command"
+
+    try:
+        subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except OSError as error:
+        return False, f"Open failed: {error}"
+
+    return True, f"Opened with {option.label}"
+
+
+def launch_blocking_option(path: Path, option: OpenWithOption) -> tuple[bool, str]:
+    """Launch a blocking terminal option and return status/message."""
+
+    command = _command_parts(option.command_template, path)
+    if not command:
+        return False, "Invalid open command"
+
+    try:
+        result = subprocess.run(command, check=False)
+    except OSError as error:
+        return False, f"Open failed: {error}"
+
+    if result.returncode != 0:
+        return (
+            False,
+            f"Open failed: {option.label} exited with code {result.returncode}",
+        )
+
+    return True, f"Opened with {option.label}"
+
+
+def is_blocking_option(option: OpenWithOption) -> bool:
+    """Return whether the option should block the current terminal session."""
+
+    return option.launch_mode == "blocking"
+
+
+def _default_options() -> tuple[OpenWithOption, ...]:
+    return (
+        OpenWithOption(
+            label="VS Code",
+            command_template="code {path}",
+            executable="code",
+            launch_mode="background",
+            requires_gui=True,
+        ),
+        OpenWithOption(
+            label="Open (system)",
+            command_template=_system_open_template(),
+            executable=_system_open_executable(),
+            launch_mode="background",
+            requires_gui=True,
+            supports_directories=False,
+        ),
+        OpenWithOption(
+            label="Antigravity",
+            command_template="antigravity {path}",
+            executable="antigravity",
+            launch_mode="background",
+        ),
+        OpenWithOption(
+            label="Neovim",
+            command_template="nvim {path}",
+            executable="nvim",
+            launch_mode="blocking",
+        ),
+        OpenWithOption(
+            label="Nano",
+            command_template="nano {path}",
+            executable="nano",
+            launch_mode="blocking",
+            supports_directories=False,
+        ),
+        OpenWithOption(
+            label="Less",
+            command_template="less {path}",
+            executable="less",
+            launch_mode="blocking",
+            supports_directories=False,
+        ),
+        OpenWithOption(
+            label="Bat",
+            command_template="bat {path}",
+            executable="bat",
+            launch_mode="blocking",
+            supports_directories=False,
+        ),
+    )
+
+
+def _has_gui_session() -> bool:
+    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_TTY"):
+        return False
+
+    if sys.platform == "darwin":
+        return True
+
+    if sys.platform.startswith("linux"):
+        return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+    if sys.platform.startswith("win"):
+        return True
+
+    return False
+
+
+def _system_open_template() -> str:
+    if sys.platform == "darwin":
+        return "open {path}"
+
+    if sys.platform.startswith("linux"):
+        return "xdg-open {path}"
+
+    if sys.platform.startswith("win"):
+        return 'cmd /c start "" {path}'
+
+    return "open {path}"
+
+
+def _system_open_executable() -> str:
+    if sys.platform == "darwin":
+        return "open"
+
+    if sys.platform.startswith("linux"):
+        return "xdg-open"
+
+    if sys.platform.startswith("win"):
+        return "cmd"
+
+    return "open"
+
+
+def _command_parts(command_template: str, path: Path) -> list[str]:
+    rendered = command_template.format(path=shlex.quote(str(path)))
+    return shlex.split(rendered)