3.3 KiB
cd-browser Architecture
Author: Saky
This document describes the architecture of the cd-browser terminal
navigation tool.
1. Purpose
cd-browser provides a keyboard‑driven terminal interface to explore
directories and return a selected path to the shell.
It solves a limitation of shells:
A program cannot directly change the parent shell directory.
Instead:
- The application returns a path
- A shell wrapper performs
cd
2. High Level Architecture
The project follows a layered architecture:
CLI Layer ↓ UI Layer ↓ Navigator Layer ↓ Filesystem Layer
History is used by the navigator.
3. Modules
filesystem.py
Responsibilities:
- inspect filesystem
- list directories
- detect children directories
Core structures:
DirectoryEntry
Functions:
list_directories() has_subdirectories()
history.py
Handles navigation history.
Features:
- visit(path)
- back()
- forward()
- select()
Used by navigator.
navigator.py
Core state machine of the application.
Tracks:
- current_path
- visible directory entries
- selected index
- expanded nodes
Handles:
- entering directories
- parent navigation
- tree expansion
- history integration
ui.py
Terminal interface using curses.
Responsibilities:
- render directory list
- highlight selection
- process keyboard input
Keys used:
↑ ↓ navigation → expand ← collapse ESC exit
cli.py
Application orchestrator.
Responsibilities:
- create navigator
- start terminal UI
- capture resulting path
main.py
Entrypoint.
Responsibilities:
- initialize logging
- start CLI flow
- print final path
4. Shell Integration
Shell wrapper function:
cd_() { local target target="$(cd_browser)" if [ -n "$target" ] && [ -d "$target" ]; then cd "$target" fi }
This enables:
cd_
to change the working directory.
5. Terminal Handling
The application attaches its UI to:
/dev/tty
This allows the UI to function even when stdout is captured by shell substitution.
stdout is reserved for:
final directory path
stderr is used for logging.
6. Validation
Quality tools ensure correctness:
black -- formatting
ruff -- linting
mypy -- type checking
pytest -- testing
Commands:
make fix make quality make ci
7. Extensibility
Future improvements:
- enhanced navigation model
- fuzzy search
- bookmark directories
- persistent history
- configuration file