# 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.