docs: add AI development playbook and architecture documentation

docs/development-journey.md

@@ -0,0 +1,453 @@
+# cd-browser -- Development Journey (Reconstructed from Chat Session)
+
+Author: Saky\
+Method: AI‑assisted development with OpenCode + ChatGPT\
+Environment: macOS, Python 3.11, zsh terminal
+
+------------------------------------------------------------------------
+
+# Overview
+
+This document reconstructs the full development process of
+**cd-browser**, a terminal directory navigator, built step‑by‑step
+using:
+
+-   a reusable Python development template
+-   OpenCode as an autonomous coding agent
+-   ChatGPT as architectural guidance
+
+The workflow followed a structured pattern:
+
+Specification → Plan → Implementation → Validation → Integration →
+Release
+
+------------------------------------------------------------------------
+
+# Phase 1 --- Creating the Python AI Development Template
+
+## Objective
+
+Create a reusable repository template for AI‑assisted Python projects
+with:
+
+-   clean structure
+-   automated formatting
+-   static analysis
+-   testing
+-   reproducible workflows
+
+## Key decisions
+
+-   Python ≥ 3.11
+-   virtual environment `.venv`
+-   tooling:
+
+  Tool         Purpose
+  ------------ ------------------
+  black        formatting
+  ruff         linting
+  mypy         type checking
+  pytest       testing
+  pre-commit   automated checks
+  make         task automation
+
+## Repository structure
+
+src/ tests/ specs/ scripts/ Makefile pyproject.toml
+instructions-agent.md
+
+## Important file
+
+### instructions-agent.md
+
+Defines how OpenCode should behave:
+
+-   read specs before implementing
+-   keep changes minimal
+-   reuse modules
+-   run validation after changes
+
+This file becomes the AI contract for the repository.
+
+------------------------------------------------------------------------
+
+# Phase 2 --- Creating the Project
+
+## Project Name
+
+cd-browser
+
+Goal:
+
+A terminal directory browser that allows fast navigation and returns a
+directory path to the shell.
+
+------------------------------------------------------------------------
+
+# Phase 3 --- Application Specification
+
+Specification stored in:
+
+specs/cd_browser_spec.md
+
+Key behavior defined:
+
+-   browse directories in terminal
+-   arrow navigation
+-   expandable tree
+-   history support
+-   return selected path to shell
+
+------------------------------------------------------------------------
+
+# Phase 4 --- Preparing the Codebase
+
+Created modules:
+
+src/app/
+
+cli.py\
+filesystem.py\
+history.py\
+navigator.py\
+ui.py\
+main.py
+
+Purpose of each module:
+
+  Module       Responsibility
+  ------------ -----------------------
+  filesystem   filesystem inspection
+  history      navigation history
+  navigator    state machine
+  ui           terminal rendering
+  cli          orchestration
+  main         entrypoint
+
+------------------------------------------------------------------------
+
+# Phase 5 --- Implementation via OpenCode
+
+OpenCode was instructed to implement modules step‑by‑step.
+
+## Step 1 --- Filesystem layer
+
+Prompt summary:
+
+Implement filesystem helpers: - list directories - detect
+subdirectories - return structured entries
+
+### Result
+
+filesystem.py implemented:
+
+-   DirectoryEntry
+-   list_directories()
+-   has_subdirectories()
+
+### Tests added
+
+tests/test_filesystem.py
+
+Validation:
+
+pytest\
+black\
+ruff\
+mypy
+
+All passed.
+
+------------------------------------------------------------------------
+
+# Step 2 --- History module
+
+Prompt summary:
+
+Implement session history manager.
+
+### Result
+
+history.py:
+
+-   visit()
+-   back()
+-   forward()
+-   select()
+
+### Tests
+
+tests/test_history.py
+
+Validation: success.
+
+------------------------------------------------------------------------
+
+# Step 3 --- Navigator (core logic)
+
+Prompt summary:
+
+Implement navigator state model using filesystem + history. Do not
+implement UI yet.
+
+### Result
+
+navigator.py manages:
+
+-   current_path
+-   visible entries
+-   selection index
+-   expand/collapse
+-   parent navigation
+-   history integration
+
+### Tests
+
+tests/test_navigator.py
+
+22 tests passed.
+
+------------------------------------------------------------------------
+
+# Step 4 --- Terminal UI
+
+Prompt summary:
+
+Implement minimal curses UI.
+
+### Result
+
+ui.py:
+
+-   curses interface
+-   path display
+-   selection highlighting
+-   arrow navigation
+-   ESC exit
+
+### Tests
+
+UI-independent logic tested.
+
+------------------------------------------------------------------------
+
+# Step 5 --- CLI integration
+
+Prompt summary:
+
+Create CLI orchestration.
+
+### Result
+
+cli.py
+
+-   initializes navigator
+-   launches UI
+-   returns final path
+
+main.py
+
+-   entrypoint
+-   prints selected path
+
+Validation:
+
+27 tests passed
+
+------------------------------------------------------------------------
+
+# Phase 6 --- Shell Integration
+
+Problem:
+
+A program cannot change the parent shell directory.
+
+Solution:
+
+Create shell wrapper:
+
+cd\_() { local target target="$(cd_browser)"
+  if [ -n "$target" \] && \[ -d "$target" ]; then
+    cd "$target" fi }
+
+Added to:
+
+\~/.zshrc
+
+Now command:
+
+cd\_
+
+opens the navigator and changes directory.
+
+------------------------------------------------------------------------
+
+# Phase 7 --- Critical Bug Encountered
+
+## Issue
+
+Using command substitution:
+
+target="\$(cd_browser)"
+
+broke the curses UI.
+
+Observed behavior:
+
+-   UI not rendering
+-   logging printed to stdout
+
+Example output:
+
+INFO app.main Starting application
+
+### Root cause
+
+-   stdout captured by shell
+-   curses requires real terminal
+-   logging polluted stdout
+
+------------------------------------------------------------------------
+
+# Resolution
+
+Prompt given to OpenCode:
+
+Fix integration so UI uses real terminal while stdout remains clean.
+
+### Fix implemented
+
+1.  UI attached to /dev/tty
+2.  logging redirected to stderr
+3.  stdout reserved for final path
+
+### Files modified
+
+ui.py\
+main.py\
+logging_config.py\
+tests
+
+Validation:
+
+28 tests passed
+
+Problem resolved.
+
+------------------------------------------------------------------------
+
+# Phase 8 --- Packaging
+
+Added console entrypoint in pyproject.toml:
+
+\[project.scripts\] cd_browser = "app.main:main"
+
+Now installable via:
+
+pip install .
+
+Command available:
+
+cd_browser
+
+------------------------------------------------------------------------
+
+# Phase 9 --- Documentation Refactor
+
+Problem:
+
+README from template conflicted with project README.
+
+Solution:
+
+README.md\
+README_TEMPLATE.md
+
+README.md → project documentation\
+README_TEMPLATE.md → original template documentation preserved
+
+------------------------------------------------------------------------
+
+# Phase 10 --- Repository Release Preparation
+
+Checklist performed:
+
+-   formatting
+-   linting
+-   type checking
+-   tests
+
+Commands:
+
+make fix\
+make quality\
+make ci
+
+All passed.
+
+------------------------------------------------------------------------
+
+# Phase 11 --- Final Repository Initialization
+
+Repository prepared for first release.
+
+git add .\
+git commit -m "Initial release: cd-browser v0.1.0"
+
+Then:
+
+git push -u origin main\
+git tag v0.1.0\
+git push origin v0.1.0
+
+------------------------------------------------------------------------
+
+# Current Features
+
+cd-browser provides:
+
+-   interactive terminal directory browsing
+-   expandable directory tree
+-   keyboard navigation
+-   directory history
+-   shell integration
+-   installation via pip
+-   automated testing and quality checks
+
+------------------------------------------------------------------------
+
+# Future Improvements
+
+Planned navigation redesign:
+
+Key model:
+
+→ expand / enter\
+← collapse / go up\
+Enter confirm directory\
+ESC cancel
+
+------------------------------------------------------------------------
+
+# Lessons Learned
+
+AI‑assisted development works best with:
+
+1.  clear specifications
+2.  modular architecture
+3.  strict validation loops
+4.  minimal prompts with clear scope
+
+Critical discovery:
+
+Terminal applications must handle:
+
+stdout\
+stderr\
+/dev/tty
+
+correctly when used inside shell substitution.
+
+------------------------------------------------------------------------
+
+End of document.