docs: Add multi-session/LLM continuity references
- Update README.md to prioritize PROJECT_STATE.md for new agents - Add handoff instructions to implementation plan header - Ensure any agent/LLM knows to check current status first - Create clear documentation hierarchy for handoffs - Fix markdown formatting issues This ensures any AI agent or human developer can immediately understand project state and continue work without confusion. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
swanadiva
@@ -0,0 +1,209 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user