# Winston

> **Self-voicing IDE and productivity environment for blind developers**

Winston is a Python-based framework that provides an accessible, keyboard-driven development environment with integrated speech synthesis, code intelligence, and productivity tools designed specifically for blind users on Windows.

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Platform](https://img.shields.io/badge/platform-Windows-blue.svg)](https://www.microsoft.com/windows)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## ✨ Features

### 🎤 **Self-Voicing IDE**
- Full speech synthesis integration with JAWS and NVDA
- Announce code structure, indentation, and line numbers
- Speech-controlled navigation and editing
- Real-time spoken feedback for all operations

### 🐍 **Python Development**
- **Syntax-aware editor** with code intelligence
- **Live reload** - Edit code and reload without restarting (Control+F5)
- **Integrated debugger** with speech support
- **Code completion** via Jedi
- **Goto definition** across files
- **Type checking** with mypy integration
- **Code folding** for navigating large files

### 🤖 **AI Integration**
- **Claude Code** integration for AI-assisted development
- **GPT** integration for code generation and Q&A
- Natural language programming assistance

### 📅 **Productivity Applets**
- **Google Calendar** - Manage events with full speech support
- **Gmail** - Read and compose emails
- **Google Contacts** - Contact management with autocomplete
- **File Explorer** - Navigate filesystem with speech
- **Console** - Execute shell commands with output capture
- **JSON Editor** - Edit JSON with validation and formatting

### ⚡ **Developer Experience**
- **Hotkey-driven** - Everything accessible via keyboard
- **Modular architecture** - Easy to extend with custom applets
- **Live reload workflow** - Rapid iterative development
- **Comprehensive type hints** - Full mypy static type checking
- **Google-style docstrings** - Self-documenting codebase

## 🚀 Quick Start

### Prerequisites

- **Windows 10/11** (Winston uses Windows COM APIs)
- **Python 3.10+** (modern type hints required)
- **Screen reader** (JAWS or NVDA recommended)

### Installation

#### Option 1: Install from Source (Recommended for Development)

```bash
# Clone repository
git clone https://github.com/chris14257/winston.git
cd winston

# Install in editable mode with all dependencies
pip install -e .

# Run Winston
winston
```

#### Option 2: Quick Development Setup

```bash
# Clone and navigate to repository
git clone https://github.com/chris14257/winston.git
cd winston

# Install dependencies manually
pip install -r requirements.txt

# Run directly from source
python -m winston.churchill
```

**First run:**
- Winston beeps (350Hz, 200ms) on startup
- Root dialog opens with list of available applets
- Navigate with arrow keys, press Control+Return to open

### Basic Usage

**Launch Winston:**
```bash
# If installed via pip
winston

# Or run as module
python -m winston.churchill
```

**Essential Hotkeys:**
- **Control+Alt+E** - Open file explorer
- **Control+Alt+C** - Open Claude Code integration
- **Control+F5** - Reload current module (in pycoder)
- **Control+W** - Close current applet
- **Control+Q** - Quit Winston

See [Getting Started Guide](winston/docs/GETTING_STARTED.md) for detailed instructions.

## 📚 Documentation

- **[Getting Started](winston/docs/GETTING_STARTED.md)** - Installation, configuration, basic usage
- **[Winston Implementation Guide](winston/docs/WINSTON_IMPLEMENTATION.md)** - Type hints, architecture, development workflows
- **[Development Workflow](winston/claude.md)** - Commit practices, testing protocols, WIP features
- **[Pip Installation Plan](winston/docs/PIP_INSTALLATION_PLAN.md)** - Roadmap for pip installability

## 🎯 Core Applets

| Applet | Hotkey | Description |
|--------|--------|-------------|
| **Explorer** | Control+Alt+E | File system navigation and management |
| **Editor** | (auto) | Multi-line text editing with speech |
| **Pycoder** | (auto) | Python IDE with code intelligence |
| **Clauder** | Control+Alt+C | Claude Code AI integration |
| **Diary** | Control+Alt+D | Google Calendar management |
| **Console** | Control+Alt+X | Shell command execution |
| **Debugger** | (context) | Python debugger with speech |

Full list in [GETTING_STARTED.md](winston/docs/GETTING_STARTED.md#essential-applets).

## 🔧 Development Workflow

Winston enables **rapid iterative development** without restarting:

```python
# 1. Edit code in pycoder
@KeyHandler.hotkey("Control+Shift+T")
def command_my_feature(self, modified_name: str) -> None:
    """My new feature."""
    self.say_strings("Feature works!")

# 2. Press Control+F5 to reload
# Winston says "reloaded"

# 3. Test immediately - changes are live!
# Press Control+Shift+T
# Hear: "Feature works!"
```

**What can be reloaded:**
- ✅ All applets (`winston/applets/*.py`)
- ✅ Most utility modules
- ❌ Core framework (requires restart)

See [Control+F5 Workflow](winston/docs/WINSTON_IMPLEMENTATION.md#applet-development-workflow-with-controlf5) for details.

## 🏗️ Architecture

Winston is built on a modular architecture:

```
winston/
├── framework.py         # Core: Anchor, Carousel, COMThread
├── dialog.py            # Base Dialog class with KeyHandler
├── subdialogs.py        # FormDialog, TableDialog, Applet
├── elements.py          # UI element types
├── churchill.py         # Application launcher (entry point)
├── clem.py              # Main event loop (pythoncom)
├── debugging.py         # Debugger, inspector, logger
├── google_api.py        # Google OAuth and API utilities
└── applets/             # Modular functionality
    ├── clauder.py       # Claude Code integration
    ├── explorer.py      # File explorer
    ├── pycoder.py       # Python IDE
    ├── diary.py         # Google Calendar
    └── ...
```

**Key Patterns:**
- **pythoncom main loop** - Windows message pump for COM integration
- **asyncio on threads** - Async I/O without blocking main loop
- **Duck typing validation** - `element_attributes()` instead of ABCs
- **Protocol classes** - Type hints for structural typing
- **Live reload** - Module cache invalidation for hot reloading

See [Architecture Notes](winston/docs/WINSTON_IMPLEMENTATION.md#winston-architecture-notes) for in-depth coverage.

## 🤝 Contributing

Winston is under active development. Contributions welcome!

### Development Setup

```bash
# Clone repository
git clone https://github.com/chris14257/winston.git
cd winston

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Run type checker
python -m mypy winston --config-file=winston/mypy.ini

# Make changes and test with Control+F5
# Commit when working
```

### Contribution Guidelines

1. **Follow typing standards** - See [WINSTON_IMPLEMENTATION.md](winston/docs/WINSTON_IMPLEMENTATION.md)
2. **Add comprehensive docstrings** - Google style required
3. **Test your changes** - Create test scripts in `winston/scratch/`
4. **Run mypy** - Fix all type errors before committing
5. **Commit with attribution** - Use template from [claude.md](winston/claude.md)

See [claude.md](winston/claude.md) for complete development workflow.

## 🎓 Learning Winston

### For New Users
- Start with [Getting Started Guide](winston/docs/GETTING_STARTED.md)
- Explore `winston/applets/template.py` - Demonstrates all key patterns
- Read module docstrings - Winston is self-documenting

### For Developers
- Read [WINSTON_IMPLEMENTATION.md](winston/docs/WINSTON_IMPLEMENTATION.md)
- Study the type hints and docstrings throughout codebase
- Check [claude.md](winston/claude.md) for development practices
- Review recent commits for examples

### For Contributors
- Fork the repository
- Create feature branch
- Follow typing and docstring standards
- Test with Control+F5 workflow
- Submit pull request

## 🌟 Design Philosophy

Winston follows these principles:

1. **Accessibility First** - Every feature designed for screen reader users
2. **Keyboard-Driven** - All functionality accessible via hotkeys
3. **Speech Integrated** - Continuous spoken feedback
4. **Rapid Iteration** - Live reload for fast development cycles
5. **Type Safety** - Comprehensive type hints with mypy validation
6. **Self-Documenting** - Google-style docstrings throughout
7. **Modular** - Applet architecture for extensibility

## 🔮 Future Plans

### Short Term
- [ ] **Pip installability** - `pip install winston-ide` (see [plan](winston/docs/PIP_INSTALLATION_PLAN.md))
- [ ] **Cross-platform test framework** - Test without Windows dependencies
- [ ] **Runtime type checking** - Enable typeguard in development mode
- [ ] **More applets** - Email (mail.py), Jupyter (notebook.py)

### Long Term
- [ ] **Cross-platform support** - macOS and Linux versions
- [ ] **Plugin system** - Third-party applet distribution
- [ ] **Speech synthesis abstraction** - Support multiple TTS engines
- [ ] **Remote debugging** - Debug code on remote systems

See [WIP sections in claude.md](winston/claude.md) for active work.

## 📊 Project Status

**Current Version:** 0.1.0 (Alpha)

**Maturity:**
- ✅ Core framework stable
- ✅ Major applets working (explorer, pycoder, clauder, diary)
- ✅ Type hints complete across codebase
- ⚠️ Some applets incomplete (mail, notebook, souper)
- ⚠️ Windows-only (platform-specific dependencies)
- ⚠️ Not yet pip-installable (manual setup required)

**Type Checking:**
- Total modules: 24 (all typed)
- mypy errors: 257 (down from 546 baseline, 52.9% reduction)
- Most errors are from untyped dependencies or legitimate duck typing

See [mypy progress in claude.md](winston/claude.md) for details.

## 🙏 Acknowledgments

Winston builds on these excellent projects:

- **pywin32** - Windows COM integration
- **Jedi** - Python code intelligence
- **Google APIs** - Calendar, Gmail, Contacts
- **Claude Code** - AI-assisted development
- **JAWS/NVDA** - Screen reader integration

Named after Winston Churchill for resilience and reliability.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🐛 Bug Reports & Questions

- **Issues:** [GitHub Issues](https://github.com/chris14257/winston/issues)
- **Discussions:** [GitHub Discussions](https://github.com/chris14257/winston/discussions)
- **Documentation:** Browse `winston/docs/` directory or source code

## 🚀 Why Winston?

Winston provides blind developers with a **complete development environment** that doesn't compromise on accessibility or functionality:

- **No visual dependencies** - Everything navigable by keyboard and speech
- **Professional-grade tools** - Real debugger, type checking, AI integration
- **Rapid development** - Live reload workflow matches sighted IDEs
- **Extensible** - Easy to add new tools and productivity features
- **Open source** - Customize to your workflow

Join us in making development accessible to everyone! 🎉

---

**Made with ❤️ for the blind developer community**
