cd-browser 0.2.5__tar.gz → 0.3.0__tar.gz

{cd_browser-0.2.5 → cd_browser-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cd-browser
-Version: 0.2.5
+Version: 0.3.0
 Summary: A fast keyboard-driven directory navigator for the terminal.
 Author: Saky
 Classifier: Development Status :: 3 - Alpha
@@ -50,12 +50,95 @@ Working in the terminal often means:
 
 - ⌨️ 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)
-- ⚡ Returns the selected path to the shell (`Enter` to confirm, `Esc` to cancel)
-- 🔎 Press `.` to toggle hidden directories
+- 📜 Persistent history between sessions (`h` history mode, `b` back, `f` forward)
+- 🔎 Incremental filter mode (`/`, type to filter, `Backspace`, `Esc`)
+- 🧭 History filter mode (`/` inside history) with most-recent-first ordering
+- 📄 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`)
+- 🧩 Configurable app menu via `config.toml` with automatic template creation
+- 🛠 Development snapshot in header + detailed info panel (`i`)
+- 👀 Toggle hidden entries with `.`
 - 🖥 Native terminal interface
 - 🔁 Works with Bash, Zsh and other shells
-- 🚀 Fast visual navigation of directory trees
+- ⚡ 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
+- `i`: Toggle development info panel
+- `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 (most recent at top)
+- `Enter`: Jump to selected history path
+- `Esc` or `h`: Exit history mode
+- `PgUp` / `PgDn`, `Home` / `End`: Fast history navigation
+- `/`: Enter history filter mode
+
+History filter mode:
+
+- Type text: Filter history entries in real time (case-insensitive)
+- `↑` / `↓`: Move inside filtered history results
+- `Enter`: Jump to selected history path
+- `Esc`: Exit history filter mode and clear query
+- `Backspace`: Remove last filter character
+
+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`, `opencode`, `nvim`, `nano`, `less`, `bat` (as applicable)
+
+## Opener Configuration
+
+`cd-browser` reads opener settings from:
+
+- macOS/Linux: `~/.config/cd-browser/config.toml`
+- Windows: `%APPDATA%/cd-browser/config.toml`
+
+If the file does not exist, `cd-browser` creates it automatically with defaults.
+
+Example:
+
+```toml
+[open_with]
+files = ["code", "open", "antigravity", "nvim", "nano", "less", "bat"]
+directories = ["code", "opencode", "antigravity", "nvim"]
+```
+
+You can reorder or remove entries to customize app priority.
 
 ## Quick Demo
 
@@ -126,7 +209,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.3.0/README.md

@@ -0,0 +1,232 @@
+# 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)
+- 📜 Persistent history between sessions (`h` history mode, `b` back, `f` forward)
+- 🔎 Incremental filter mode (`/`, type to filter, `Backspace`, `Esc`)
+- 🧭 History filter mode (`/` inside history) with most-recent-first ordering
+- 📄 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`)
+- 🧩 Configurable app menu via `config.toml` with automatic template creation
+- 🛠 Development snapshot in header + detailed info panel (`i`)
+- 👀 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
+- `i`: Toggle development info panel
+- `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 (most recent at top)
+- `Enter`: Jump to selected history path
+- `Esc` or `h`: Exit history mode
+- `PgUp` / `PgDn`, `Home` / `End`: Fast history navigation
+- `/`: Enter history filter mode
+
+History filter mode:
+
+- Type text: Filter history entries in real time (case-insensitive)
+- `↑` / `↓`: Move inside filtered history results
+- `Enter`: Jump to selected history path
+- `Esc`: Exit history filter mode and clear query
+- `Backspace`: Remove last filter character
+
+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`, `opencode`, `nvim`, `nano`, `less`, `bat` (as applicable)
+
+## Opener Configuration
+
+`cd-browser` reads opener settings from:
+
+- macOS/Linux: `~/.config/cd-browser/config.toml`
+- Windows: `%APPDATA%/cd-browser/config.toml`
+
+If the file does not exist, `cd-browser` creates it automatically with defaults.
+
+Example:
+
+```toml
+[open_with]
+files = ["code", "open", "antigravity", "nvim", "nano", "less", "bat"]
+directories = ["code", "opencode", "antigravity", "nvim"]
+```
+
+You can reorder or remove entries to customize app priority.
+
+## 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.5 → cd_browser-0.3.0}/pyproject.toml

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

{cd_browser-0.2.5 → cd_browser-0.3.0}/src/app/cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
+from app.history import SessionHistory
 from app.navigator import Navigator
 from app.ui import TerminalUI
 
@@ -10,6 +11,6 @@ def run_cli(start_path: Path | None = None, ui: TerminalUI | None = None) -> Pat
     """Run the interactive directory browser and return the selected path."""
 
     initial_path = (start_path or Path.cwd()).expanduser().resolve()
-    navigator = Navigator(initial_path)
+    navigator = Navigator(initial_path, history=SessionHistory.persistent())
     terminal_ui = ui or TerminalUI()
     return terminal_ui.run(navigator)

cd_browser-0.3.0/src/app/devinfo.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class DevSnapshot:
+    """Development context for a path."""
+
+    repo_root: Path | None
+    git_branch: str | None
+    git_dirty: bool
+    last_commit: str | None
+    stack: tuple[str, ...]
+    commands: tuple[str, ...]
+
+    @property
+    def header_summary(self) -> str:
+        git_part = "git:-"
+        if self.git_branch:
+            dirty_marker = "*" if self.git_dirty else ""
+            git_part = f"git:{self.git_branch}{dirty_marker}"
+
+        stack_part = ",".join(self.stack[:2]) if self.stack else "-"
+        return f"{git_part} stack:{stack_part}"
+
+    def detail_lines(self, current_path: Path) -> list[str]:
+        lines = [f"Current path: {current_path}"]
+        if self.repo_root is None:
+            lines.append("Git: not a repository")
+        else:
+            dirty_text = "dirty" if self.git_dirty else "clean"
+            lines.append(f"Git root: {self.repo_root}")
+            lines.append(f"Git branch: {self.git_branch or '-'} ({dirty_text})")
+            if self.last_commit:
+                lines.append(f"Last commit: {self.last_commit}")
+
+        stack_text = ", ".join(self.stack) if self.stack else "-"
+        lines.append(f"Detected stack: {stack_text}")
+
+        if self.commands:
+            lines.append("Suggested commands:")
+            for command in self.commands:
+                lines.append(f"  - {command}")
+
+        return lines
+
+
+class DevInfoCache:
+    """Simple TTL cache for development snapshots."""
+
+    def __init__(self, ttl_seconds: float = 3.0) -> None:
+        self._ttl_seconds = ttl_seconds
+        self._cached_path: Path | None = None
+        self._cached_at: float = 0.0
+        self._cached_snapshot: DevSnapshot | None = None
+
+    def get(self, path: Path) -> DevSnapshot:
+        resolved_path = path.expanduser().resolve()
+        now = time.monotonic()
+        if (
+            self._cached_snapshot is not None
+            and self._cached_path == resolved_path
+            and (now - self._cached_at) <= self._ttl_seconds
+        ):
+            return self._cached_snapshot
+
+        snapshot = collect_dev_snapshot(resolved_path)
+        self._cached_path = resolved_path
+        self._cached_snapshot = snapshot
+        self._cached_at = now
+        return snapshot
+
+
+def collect_dev_snapshot(path: Path) -> DevSnapshot:
+    """Collect git and stack metadata for a path."""
+
+    repo_root = _git_repo_root(path)
+    git_branch: str | None = None
+    git_dirty = False
+    last_commit: str | None = None
+
+    if repo_root is not None:
+        git_branch = _run_command(
+            ["git", "-C", str(repo_root), "rev-parse", "--abbrev-ref", "HEAD"]
+        )
+        status_output = _run_command(
+            ["git", "-C", str(repo_root), "status", "--porcelain"]
+        )
+        git_dirty = bool(status_output)
+        last_commit = _run_command(
+            ["git", "-C", str(repo_root), "log", "-1", "--pretty=format:%h %s"]
+        )
+
+    stack = _detect_stack(path)
+    return DevSnapshot(
+        repo_root=repo_root,
+        git_branch=git_branch,
+        git_dirty=git_dirty,
+        last_commit=last_commit,
+        stack=stack,
+        commands=_suggested_commands(stack, repo_root is not None),
+    )
+
+
+def _git_repo_root(path: Path) -> Path | None:
+    result = _run_command(["git", "-C", str(path), "rev-parse", "--show-toplevel"])
+    if not result:
+        return None
+    return Path(result).expanduser().resolve()
+
+
+def _detect_stack(path: Path) -> tuple[str, ...]:
+    markers = (
+        ("pyproject.toml", "python"),
+        ("requirements.txt", "python"),
+        ("package.json", "node"),
+        ("go.mod", "go"),
+        ("Cargo.toml", "rust"),
+    )
+    found: list[str] = []
+    for marker, stack_name in markers:
+        if (path / marker).exists() and stack_name not in found:
+            found.append(stack_name)
+
+    return tuple(found)
+
+
+def _suggested_commands(stack: tuple[str, ...], has_git: bool) -> tuple[str, ...]:
+    commands: list[str] = []
+    if has_git:
+        commands.append("git status -sb")
+
+    if "python" in stack:
+        commands.extend(["pytest -q", "ruff check src tests"])
+    if "node" in stack:
+        commands.extend(["npm test", "npm run lint"])
+    if "go" in stack:
+        commands.append("go test ./...")
+    if "rust" in stack:
+        commands.append("cargo test")
+
+    return tuple(commands)
+
+
+def _run_command(command: list[str]) -> str | None:
+    try:
+        result = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=0.35,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+    if result.returncode != 0:
+        return None
+
+    output = result.stdout.strip()
+    if not output:
+        return None
+
+    return output

{cd_browser-0.2.5 → cd_browser-0.3.0}/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: