HostKeeper/README.md

# Hostkeeper 🔐

> **Cross-platform SSH/SFTP management tool with secure credential storage**

**🚨 IMPORTANT**: If you're an AI agent or joining this project mid-development, **[read PROJECT_STATE.md first](PROJECT_STATE.md)** for current status and handoff instructions.

---

## 📋 Project Status

**Current Phase**: Planning Complete → Ready for Implementation  
**Progress**: 0% implementation, 100% planning  
**Estimated Timeline**: 3-4 weeks to MVP

### Quick Links

- 📊 **[PROJECT_STATE.md](PROJECT_STATE.md)** - **START HERE** - Current status & handoff guide
- 🏗️ **[Design Document](docs/plans/2024-06-22-hostkeeper-design.md)** - Architecture & technical decisions
- 📝 **[Implementation Plan](docs/plans/2024-06-22-hostkeeper-implementation.md)** - Detailed development tasks
- 📚 **Documentation Index** - All project documentation

---

## ✨ What is Hostkeeper?

Hostkeeper is a comprehensive SSH/SFTP management tool inspired by [Termius](https://termius.com/), built with Go for maximum cross-platform compatibility.

### Key Features

- 🔐 **Secure credential management** - Safe SSH key and password storage
- 📁 **SFTP file operations** - Built-in file transfer capabilities  
- 🔑 **SSH key management** - Generate, import, organize keys
- 📤 **Cross-device sync** - Export/import credentials between devices
- 🖥️ **Cross-platform** - Linux, macOS, Windows, Termux (Android)
- 🎨 **TUI interface** - Interactive terminal user interface
- ⚡ **Fast CLI** - Quick commands for power users

---

## 🚀 Quick Start (For Users)

**Note**: This project is currently in early development. Not yet ready for production use.

### Installation (when ready)

```bash
# From source
go install github.com/yourusername/hostkeeper/cmd/hostkeeper@latest

# Or build from source
git clone https://github.com/username/hostkeeper.git
cd hostkeeper
make build
```

### Usage (planned)

```bash
# Add your first host
hostkeeper add

# List all hosts  
hostkeeper list

# Connect to host
hostkeeper connect myserver

# Launch TUI interface
hostkeeper tui
```

---

## 🛠️ Development

### For Developers

**👋 If you're joining development:**
1. **[Read PROJECT_STATE.md first](PROJECT_STATE.md)** - This shows current progress
2. Check [Implementation Plan](docs/plans/2024-06-22-hostkeeper-implementation.md) - See what needs doing
3. Pick up next incomplete task and follow TDD approach

### Getting Started

```bash
# Clone repository
git clone https://github.com/username/hostkeeper.git
cd hostkeeper

# Install dependencies  
go mod download

# Run tests
make test

# Build project
make build

# Run application
./build/hostkeeper --help
```

### Tech Stack

- **Language**: Go 1.21+
- **CLI Framework**: [Cobra](https://github.com/spf13/cobra)
- **TUI Framework**: [Bubble Tea](https://github.com/charmbracelet/bubbletea)
- **SSH Library**: [golang.org/x/crypto/ssh](https://pkg.go.dev/golang.org/x/crypto/ssh)

---

## 📚 Documentation Structure

```
docs/
├── plans/
│   ├── 2024-06-22-hostkeeper-design.md           # Architecture & design decisions
│   └── 2024-06-22-hostkeeper-implementation.md  # Step-by-step implementation guide
├── INSTALLATION.md                                # Installation guide (to be created)
├── USAGE.md                                      # User documentation (to be created)
└── ARCHITECTURE.md                                # Technical architecture (to be created)
```

### Recommended Reading Order

1. **[PROJECT_STATE.md](PROJECT_STATE.md)** ⭐ *Start here for current status*
2. **[Design Document](docs/plans/2024-06-22-hostkeeper-design.md)** - Understanding the system
3. **[Implementation Plan](docs/plans/2024-06-22-hostkeeper-implementation.md)** - How to build it

---

## 🎯 Development Roadmap

### MVP (Current Focus)
- ✅ Complete planning and design
- 🔲 Core SSH connection management
- 🔲 Host CRUD operations
- 🔲 Basic TUI interface
- 🔲 Export/import functionality
- 🔲 Cross-platform builds

### Phase 2 (Enhanced Features)
- 🔳 Encrypted credential storage
- 🔳 SFTP TUI browser
- 🔳 SSH key generation
- 🔳 Connection snippets

### Phase 3 (Advanced Features)
- 🔳 Cloud sync
- 🔳 Custom terminal emulator
- 🔳 Web interface
- 🔳 Plugin system

---

## 🤝 Contributing

**For new contributors and AI agents:**

1. **[Read PROJECT_STATE.md](PROJECT_STATE.md)** first to understand current progress
2. Check [implementation plan](docs/plans/2024-06-22-hostkeeper-implementation.md) for next tasks
3. Follow TDD approach (test → code → refactor)
4. Update PROJECT_STATE.md after completing work

### Development Setup

See [PROJECT_STATE.md](PROJECT_STATE.md) for detailed development workflow and handoff procedures.

---

## 📊 Current Status

| Component | Status |
|-----------|--------|
| Planning & Design | ✅ Complete |
| Implementation | 🔲 Not Started |
| Testing | 🔲 Not Started |
| Documentation | ✅ Complete (technical docs) |

**Next Steps**: Start implementation following the [implementation plan](docs/plans/2024-06-22-hostkeeper-implementation.md)

---

## 📞 Support

- 📖 **[Documentation](docs/)**
- 🐛 [Issue Tracker](https://github.com/username/hostkeeper/issues)  
- 💬 [Discussions](https://github.com/username/hostkeeper/discussions)

---

## 📄 License

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

---

## 🙏 Acknowledgments

- Inspired by [Termius](https://termius.com/)
- Reference implementation: [tamagosh](https://github.com/Candratama/tamagosh)
- Built with excellent open-source tools:
  - [Cobra](https://github.com/spf13/cobra) - CLI framework
  - [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
  - [golang.org/x/crypto/ssh](https://pkg.go.dev/golang.org/x/crypto/ssh) - SSH library

---

**📌 Remember**: If you're continuing development work, always check [PROJECT_STATE.md](PROJECT_STATE.md) first to see what's been done and what needs to happen next!