Initial release: cd-browser v0.1.0

specs/cd_browser_spec.md

@@ -0,0 +1,305 @@
+# 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.