192 lines
3.3 KiB
Markdown
192 lines
3.3 KiB
Markdown
# 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:
|
||
|
||
1. The application returns a path
|
||
2. 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
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# End
|