244 lines
4.5 KiB
Markdown
244 lines
4.5 KiB
Markdown
# Project Overview --- cd-browser
|
|
|
|
Author: Saky
|
|
|
|
This document provides a quick introduction to the **cd-browser**
|
|
project and guides readers through the repository structure,
|
|
documentation, and development workflow.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# What is cd-browser?
|
|
|
|
`cd-browser` is a **terminal-based directory navigator** that allows
|
|
users to browse directories interactively and then change the working
|
|
directory of their shell.
|
|
|
|
It solves a common shell limitation:
|
|
|
|
A program cannot directly change the directory of its parent shell.
|
|
|
|
The solution is:
|
|
|
|
1. The program returns a directory path.
|
|
2. A shell wrapper function performs the actual `cd`.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Example usage
|
|
|
|
``` bash
|
|
cd_
|
|
```
|
|
|
|
The command launches an interactive terminal browser.
|
|
|
|
After navigating and exiting:
|
|
|
|
- the selected directory is returned
|
|
- the shell wrapper changes the working directory.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Key Features
|
|
|
|
- interactive terminal navigation
|
|
- tree-style directory browsing
|
|
- expandable directories
|
|
- keyboard-driven interface
|
|
- directory navigation history
|
|
- clean shell integration
|
|
- installable as a CLI tool
|
|
- tested Python codebase
|
|
- automated formatting and linting
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Repository Structure
|
|
|
|
cd-browser/
|
|
|
|
README.md → main project documentation
|
|
README_TEMPLATE.md → original template documentation
|
|
|
|
docs/
|
|
development-journey.md
|
|
ai-development-playbook.md
|
|
architecture.md
|
|
|
|
specs/
|
|
cd_browser_spec.md
|
|
|
|
src/
|
|
app/
|
|
cli.py
|
|
filesystem.py
|
|
history.py
|
|
navigator.py
|
|
ui.py
|
|
main.py
|
|
|
|
tests/
|
|
|
|
scripts/
|
|
|
|
pyproject.toml
|
|
Makefile
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Documentation Guide
|
|
|
|
The repository includes several documents explaining the project from
|
|
different perspectives.
|
|
|
|
## README.md
|
|
|
|
Quick introduction and installation instructions.
|
|
|
|
## specs/
|
|
|
|
Functional specifications of the application.
|
|
|
|
## docs/development-journey.md
|
|
|
|
Explains how the project was built step-by-step using AI coding agents.
|
|
|
|
## docs/ai-development-playbook.md
|
|
|
|
Reusable methodology for building applications using AI development
|
|
workflows.
|
|
|
|
## docs/architecture.md
|
|
|
|
Technical architecture of the application.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Installation
|
|
|
|
Clone the repository:
|
|
|
|
``` bash
|
|
git clone https://gitea.sakydogalo.es/saky/cd-browser.git
|
|
cd cd-browser
|
|
```
|
|
|
|
Install the tool:
|
|
|
|
``` bash
|
|
pip install .
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Shell Integration
|
|
|
|
Add this function to your shell configuration (`~/.zshrc`):
|
|
|
|
``` bash
|
|
cd_() {
|
|
local target
|
|
target="$(cd_browser)"
|
|
if [ -n "$target" ] && [ -d "$target" ]; then
|
|
cd "$target"
|
|
fi
|
|
}
|
|
```
|
|
|
|
Reload the shell:
|
|
|
|
``` bash
|
|
source ~/.zshrc
|
|
```
|
|
|
|
Now you can run:
|
|
|
|
``` bash
|
|
cd_
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Development Setup
|
|
|
|
For contributors or developers:
|
|
|
|
``` bash
|
|
make dev
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
Run the application:
|
|
|
|
``` bash
|
|
python -m app.main
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Quality and Validation
|
|
|
|
The project uses automated tools to ensure code quality.
|
|
|
|
Tools:
|
|
|
|
- black (formatting)
|
|
- ruff (linting)
|
|
- mypy (type checking)
|
|
- pytest (testing)
|
|
|
|
Commands:
|
|
|
|
``` bash
|
|
make fix
|
|
make quality
|
|
make ci
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# AI-Assisted Development
|
|
|
|
This project was built using a structured **AI-assisted development
|
|
workflow**.
|
|
|
|
Key ideas:
|
|
|
|
- architecture defined by a human
|
|
- AI agents used for focused implementation tasks
|
|
- strict validation loops
|
|
- small scoped prompts
|
|
|
|
More information:
|
|
|
|
docs/ai-development-playbook.md
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Status
|
|
|
|
Current version:
|
|
|
|
v0.1.0
|
|
|
|
The project is stable and functional as a minimal terminal directory
|
|
navigator.
|
|
|
|
Future improvements may include:
|
|
|
|
- improved navigation model
|
|
- fuzzy search
|
|
- bookmarks
|
|
- persistent history
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# License
|
|
|
|
See the LICENSE file.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
End of document.
|