cd-browser 0.1.1__tar.gz

cd_browser-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

cd_browser-0.1.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: cd-browser
+Version: 0.1.1
+Summary: A fast keyboard-driven directory navigator for the terminal.
+Author: Saky
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: pre-commit>=3.7.0; extra == "dev"
+Dynamic: license-file
+
+# 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](docs/demo.gif)
+
+## 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
+
+- 🚀 Fast visual navigation of directory trees
+- ⌨️ Fully keyboard-driven workflow
+- 🌲 Expand and collapse directories
+- 📜 Navigation history inside the session
+- 🖥 Native terminal interface
+- 🔁 Works with Bash, Zsh and other shells
+- ⚡ Returns the selected path to the shell
+- 🔎 Press `.` to toggle hidden directories
+
+## 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 .
+```
+
+For editable local development:
+
+```bash
+pip install -e '.[dev]'
+```
+
+After installation, the application command is:
+
+```bash
+cd_browser
+```
+
+When the interactive session exits, the program prints the final selected directory path.
+
+## 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_
+```
+
+- Dentro de `cd_browser`, presiona `.` para alternar la visualización de carpetas ocultas.
+
+## Uninstall
+
+If the project was installed with `pip`, remove it with:
+
+```bash
+pip uninstall cd-browser
+```
+
+If you also added the `cd_` shell wrapper, remove that function from your shell profile and reload the shell configuration.
+
+## 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.1.1/README.md

@@ -0,0 +1,146 @@
+# 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](docs/demo.gif)
+
+## 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
+
+- 🚀 Fast visual navigation of directory trees
+- ⌨️ Fully keyboard-driven workflow
+- 🌲 Expand and collapse directories
+- 📜 Navigation history inside the session
+- 🖥 Native terminal interface
+- 🔁 Works with Bash, Zsh and other shells
+- ⚡ Returns the selected path to the shell
+- 🔎 Press `.` to toggle hidden directories
+
+## 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 .
+```
+
+For editable local development:
+
+```bash
+pip install -e '.[dev]'
+```
+
+After installation, the application command is:
+
+```bash
+cd_browser
+```
+
+When the interactive session exits, the program prints the final selected directory path.
+
+## 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_
+```
+
+- Dentro de `cd_browser`, presiona `.` para alternar la visualización de carpetas ocultas.
+
+## Uninstall
+
+If the project was installed with `pip`, remove it with:
+
+```bash
+pip uninstall cd-browser
+```
+
+If you also added the `cd_` shell wrapper, remove that function from your shell profile and reload the shell configuration.
+
+## 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.1.1/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cd-browser"
+version = "0.1.1"
+description = "A fast keyboard-driven directory navigator for the terminal."
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+  { name = "Saky" }
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+cd_browser = "app.main:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "black>=24.0",
+  "ruff>=0.3.0",
+  "mypy>=1.8.0",
+  "pre-commit>=3.7.0"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

cd_browser-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cd_browser-0.1.1/src/app/cli.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from app.navigator import Navigator
+from app.ui import TerminalUI
+
+
+def run_cli(start_path: Path | None = None, ui: TerminalUI | None = None) -> Path:
+    """Run the interactive directory browser and return the selected path."""
+
+    initial_path = (start_path or Path.cwd()).expanduser().resolve()
+    navigator = Navigator(initial_path)
+    terminal_ui = ui or TerminalUI()
+    return terminal_ui.run(navigator)

cd_browser-0.1.1/src/app/config.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class AppConfig:
+    """Application configuration."""
+
+    app_name: str = "Python AI Dev Template"
+    debug: bool = False

cd_browser-0.1.1/src/app/filesystem.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class DirectoryEntry:
+    """Directory metadata used by the navigator layer."""
+
+    name: str
+    path: Path
+    has_children: bool
+
+
+def list_directories(path: Path, show_hidden: bool = False) -> list[DirectoryEntry]:
+    """Return direct child directories sorted by name."""
+
+    directory_path = path.expanduser().resolve()
+    entries: list[DirectoryEntry] = []
+
+    for child in directory_path.iterdir():
+        if not child.is_dir():
+            continue
+        if not show_hidden and child.name.startswith("."):
+            continue
+
+        entries.append(
+            DirectoryEntry(
+                name=child.name,
+                path=child,
+                has_children=has_subdirectories(child, show_hidden=show_hidden),
+            )
+        )
+
+    return sorted(entries, key=lambda entry: entry.name.casefold())
+
+
+def has_subdirectories(path: Path, show_hidden: bool = False) -> bool:
+    """Return whether the directory contains at least one subdirectory."""
+
+    directory_path = path.expanduser().resolve()
+
+    for child in directory_path.iterdir():
+        if not child.is_dir():
+            continue
+
+        if not show_hidden and child.name.startswith("."):
+            continue
+
+        return True
+
+    return False

cd_browser-0.1.1/src/app/history.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class SessionHistory:
+    """In-memory session history for visited directories."""
+
+    _entries: list[Path] = field(default_factory=list)
+    _index: int = -1
+
+    def visit(self, path: Path) -> Path:
+        """Record a directory visit and discard forward history when needed."""
+
+        resolved_path = path.expanduser().resolve()
+
+        if self.current == resolved_path:
+            return resolved_path
+
+        if self._index < len(self._entries) - 1:
+            self._entries = self._entries[: self._index + 1]
+
+        self._entries.append(resolved_path)
+        self._index = len(self._entries) - 1
+        return resolved_path
+
+    @property
+    def current(self) -> Path | None:
+        """Return the current history entry."""
+
+        if self._index == -1:
+            return None
+
+        return self._entries[self._index]
+
+    def back(self) -> Path | None:
+        """Move backward in history when possible."""
+
+        if self._index <= 0:
+            return None
+
+        self._index -= 1
+        return self._entries[self._index]
+
+    def forward(self) -> Path | None:
+        """Move forward in history when possible."""
+
+        if self._index == -1 or self._index >= len(self._entries) - 1:
+            return None
+
+        self._index += 1
+        return self._entries[self._index]
+
+    def select(self, index: int) -> Path:
+        """Jump to a previously visited directory by history index."""
+
+        if index < 0 or index >= len(self._entries):
+            raise IndexError("History index out of range")
+
+        self._index = index
+        return self._entries[self._index]
+
+    def entries(self) -> tuple[Path, ...]:
+        """Return the full history as an immutable sequence."""
+
+        return tuple(self._entries)

cd_browser-0.1.1/src/app/logging_config.py

@@ -0,0 +1,11 @@
+import logging
+import sys
+
+
+def setup_logging() -> None:
+    """Configure application logging."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        stream=sys.stderr,
+    )

cd_browser-0.1.1/src/app/main.py

@@ -0,0 +1,16 @@
+import sys
+
+from app.cli import run_cli
+from app.logging_config import setup_logging
+
+
+def main() -> None:
+    """Run the application entry point."""
+    setup_logging()
+
+    final_path = run_cli()
+    sys.stdout.write(f"{final_path}\n")
+
+
+if __name__ == "__main__":
+    main()