306 lines
3.8 KiB
Markdown
306 lines
3.8 KiB
Markdown
# cd_ — Terminal Directory Navigator
|
|
|
|
## Overview
|
|
|
|
`cd_` is an interactive terminal utility designed to make directory navigation faster and more intuitive directly from the command line.
|
|
|
|
Instead of manually typing `cd` commands, users can browse directories using a keyboard-driven interface.
|
|
|
|
The tool behaves like a **lightweight directory browser inside the terminal**.
|
|
|
|
---
|
|
|
|
# Goals
|
|
|
|
The utility should provide:
|
|
|
|
- fast directory navigation
|
|
- keyboard-driven interface
|
|
- minimal latency
|
|
- intuitive exploration of directory trees
|
|
- ability to preview folder structure without entering directories
|
|
|
|
The tool must remain **lightweight and terminal-native**.
|
|
|
|
---
|
|
|
|
# Execution
|
|
|
|
The tool is executed from the terminal:
|
|
|
|
```bash
|
|
cd_
|
|
```
|
|
|
|
When executed, it opens an **interactive terminal navigation interface**.
|
|
|
|
---
|
|
|
|
# Interface Behavior
|
|
|
|
The interface displays:
|
|
|
|
- the current working directory
|
|
- a list of subdirectories
|
|
- a special entry:
|
|
|
|
```
|
|
..
|
|
```
|
|
|
|
which navigates to the parent directory.
|
|
|
|
Example:
|
|
|
|
```
|
|
/home/user/projects
|
|
|
|
▶ backend
|
|
▶ scripts
|
|
docs
|
|
..
|
|
```
|
|
|
|
---
|
|
|
|
# Directory Indicators
|
|
|
|
Directories must visually indicate whether they contain subdirectories.
|
|
|
|
Recommended symbols:
|
|
|
|
| Symbol | Meaning |
|
|
|------|------|
|
|
| ▶ | collapsed directory containing subdirectories |
|
|
| ▼ | expanded directory |
|
|
| space | directory without subdirectories |
|
|
|
|
Example:
|
|
|
|
```
|
|
▶ backend
|
|
▼ scripts
|
|
build
|
|
deploy
|
|
docs
|
|
```
|
|
|
|
---
|
|
|
|
# Navigation Controls
|
|
|
|
## Arrow Up / Arrow Down
|
|
|
|
Move selection between entries.
|
|
|
|
---
|
|
|
|
## Enter
|
|
|
|
Enter the selected directory.
|
|
|
|
If `..` is selected, navigate to the parent directory.
|
|
|
|
---
|
|
|
|
## ESC
|
|
|
|
Exit interactive mode.
|
|
|
|
The shell should remain in the directory currently selected.
|
|
|
|
---
|
|
|
|
# Tree Expansion
|
|
|
|
Users should be able to explore directory structure without entering directories.
|
|
|
|
## Arrow Right
|
|
|
|
Expand the selected directory.
|
|
|
|
Example:
|
|
|
|
Before:
|
|
|
|
```
|
|
▶ scripts
|
|
```
|
|
|
|
After pressing →:
|
|
|
|
```
|
|
▼ scripts
|
|
build
|
|
deploy
|
|
tools
|
|
```
|
|
|
|
---
|
|
|
|
## Arrow Left
|
|
|
|
Collapse expanded directory.
|
|
|
|
---
|
|
|
|
# Navigation History
|
|
|
|
The application maintains a session navigation history.
|
|
|
|
---
|
|
|
|
## h
|
|
|
|
Display navigation history.
|
|
|
|
The user can select a previous directory from the list.
|
|
|
|
---
|
|
|
|
## b
|
|
|
|
Navigate backward in history.
|
|
|
|
---
|
|
|
|
## f
|
|
|
|
Navigate forward in history.
|
|
|
|
---
|
|
|
|
# UI Principles
|
|
|
|
The interface must be:
|
|
|
|
- responsive
|
|
- minimal
|
|
- keyboard-focused
|
|
- easy to understand visually
|
|
|
|
---
|
|
|
|
# Future Extensions
|
|
|
|
These features are optional and may be added later.
|
|
|
|
## Search Mode
|
|
|
|
Activated by pressing:
|
|
|
|
```
|
|
/
|
|
```
|
|
|
|
Allows filtering directories by name.
|
|
|
|
---
|
|
|
|
## Favorites
|
|
|
|
Mark current directory:
|
|
|
|
```
|
|
m
|
|
```
|
|
|
|
Open favorites:
|
|
|
|
```
|
|
F
|
|
```
|
|
|
|
---
|
|
|
|
# Technical Constraints
|
|
|
|
The implementation must:
|
|
|
|
- be written in Python
|
|
- follow the repository coding standards
|
|
- pass formatting, linting, typing, and tests
|
|
|
|
Validation commands:
|
|
|
|
```
|
|
make fix
|
|
make quality
|
|
```
|
|
|
|
---
|
|
|
|
# Installation Requirements
|
|
|
|
The tool must support two usage modes.
|
|
|
|
## Developer Mode
|
|
|
|
Clone repository and run:
|
|
|
|
```
|
|
make dev
|
|
```
|
|
|
|
Then execute:
|
|
|
|
```
|
|
python -m app.main
|
|
```
|
|
|
|
---
|
|
|
|
## User Mode (Installable CLI)
|
|
|
|
The tool should be installable as a CLI command.
|
|
|
|
Example:
|
|
|
|
```
|
|
pip install .
|
|
```
|
|
|
|
After installation, users should be able to run:
|
|
|
|
```
|
|
cd_
|
|
```
|
|
|
|
directly from the terminal.
|
|
|
|
---
|
|
|
|
# Shell Integration Constraint
|
|
|
|
Because a subprocess cannot change the parent shell directory, the tool must output the selected directory path.
|
|
|
|
Shell integration should be implemented using a wrapper function.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
cd_() {
|
|
cd "$(cd_browser)"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# MVP Scope
|
|
|
|
The first version must include:
|
|
|
|
- directory navigation
|
|
- tree expansion
|
|
- keyboard controls
|
|
- session history
|
|
- terminal interface
|
|
|
|
Advanced features are optional.
|
|
|
|
---
|
|
|
|
# Summary
|
|
|
|
`cd_` is a terminal-native interactive directory navigator designed to accelerate filesystem navigation while remaining lightweight and keyboard-focused.
|