hackages

# Hackages CLI > 🎯 Learn software development concepts through test-driven development Hackages is an interactive CLI tool that helps developers learn new concepts by generating personalized coding exercises using AI-powered test-driven development. ## ✨ Features - 🤖 **AI-Powered Exercise Generation** - Creates custom learning exercises based on your goals - 🧪 **Test-Driven Learning** - Learn by making tests pass, not by reading tutorials - 🎯 **Personalized Content** - Adapts to your skill level and preferred programming language - 🔍 **Smart Technology Detection** - Automatically detects technology from your learning goal - ✅ **Technology Confirmation** - Always confirms your technology choice for clarity - 📋 **Smart Code Review** - Get feedback on your implementations - ⚡ **Interactive CLI** - Modern interface with arrow key navigation - 🔄 **Iterative Learning** - Run tests and get feedback in a continuous loop - 📦 **Repository Templates** - Clones technology-specific templates with proper project structure - 🎉 **Onboarding Experience** - New users get a guided introduction with 3 simple options ## 🚀 Installation Install globally via npm: ```bash npm install -g hackages ``` or ```bash npx hackages ``` ## 📖 Quick Start ### For New Users (First Time) After installation, simply run: ```bash hackages ``` You'll see a welcoming introduction explaining what Hackages is about, followed by 3 simple options: 1. **JavaScript Array Methods** - Learn how to use map, filter, and reduce 2. **TypeScript Functions** - Learn function types and interfaces 3. **Surprise Me!** - Let Hackages pick something fun for you Choose one and get your first exercise instantly - no authentication required! **Example Onboarding Flow:** ```bash $ hackages 🎉 Welcome to Hackages! 🎉 ================================================== 🚀 Learn software development through hands-on coding challenges 🧪 Write code, run tests, get instant review and feedback 🎯 Master concepts by doing, not just reading ================================================== ✨ What you'll get: • A coding challenge with clear instructions • Test cases that guide your implementation • AI-powered feedback on your code • A fun, interactive learning experience 🎯 Ready to try? Pick one: ? Choose your first exercise: › 1. JavaScript Array Methods 🎉 Great choice! You'll be learning: JavaScript Array Methods 🔄 Generating your first exercise... 🎉 Your first exercise is ready! ================================================== 📁 Files created: ✓ tests/exercise.spec.js (Your test cases) ✓ src/exercise.js (Your implementation file) 🚀 Next steps: 1. Read the instructions and test file to understand what to implement 2. Open src/exercise.js and start coding 3. Run 'npx hackages test' to validate your implementation 4. Run 'npx hackages review' to get feedback on your code 💡 Want to continue learning? Run 'npx hackages' again to create more exercises and track your progress! ``` ### For Returning Users If you've used Hackages before and are logged in, you'll get the full personalized experience with custom learning goals and progress tracking. ### Available Commands ```bash # Start learning (default) - creates new exercise hackages # Continue working on existing exercise (interactive mode) hackages continue # Run tests for your current exercise hackages test # Get code review and feedback hackages review # Login with GitHub account hackages login # Logout from your account hackages logout # Show help hackages --help ``` ## 🎮 How It Works ### 1. Start Learning Run `hackages` and answer a few questions: - What concept do you want to learn? (e.g., "JavaScript arrays", "recursion", "async/await") - Confirm your technology choice (even if detected from your goal) - What's your skill level? (Beginner/Intermediate/Advanced) - What's your motivation? - How much time do you have? - Login with GitHub account (automatic after goal collection) ### 2. Repository Template Cloning Hackages automatically detects your preferred technology and clones the appropriate template repository: - **TypeScript**: `git@github.com:hackages/ts-template.git` (SSH) or `https://github.com/hackages/ts-template.git` (HTTPS) - **JavaScript**: `git@github.com:hackages/js-template.git` (SSH) or `https://github.com/hackages/js-template.git` (HTTPS) - **GoLang**: `git@github.com:hackages/go-template.git` (SSH) or `https://github.com/hackages/go-template.git` (HTTPS) - **Python**: `git@github.com:hackages/python-template.git` (SSH) or `https://github.com/hackages/python-template.git` (HTTPS) The system detects your Git protocol preference (SSH vs HTTPS) and uses the appropriate URL. ### 3. Exercise Files Hackages creates exercise files in the cloned repository: - `tests/exercise-1.spec.ts` - Test cases that define what to build - `src/exercise-1.ts` - Empty implementation file for you to code - `instructions/exercise-1.mdx` - Detailed instructions and learning objectives ### 4. Test-Driven Development 1. Navigate to your exercise directory: `cd <exercise-name>` 2. Read the instructions and tests files to understand requirements 3. Write code to make tests pass 4. Run `npx hackages test` to check your progress 5. Get feedback with `npx hackages review` ### 5. Continue Learning Use `hackages continue` to access the interactive menu: - **🧪 Run Tests**: Validate your implementation - **📋 Code Review**: Get feedback and suggestions - **🚀 Next Learning**: Continue with recommended learning steps (appears after code review) - **👋 Exit**: End your learning session The "Next Learning" option only appears if you have previous feedback from a code review, and it shows up to 3 AI-recommended learning steps plus an option to write your own goal. ## 🎯 Example Learning Session ```bash $ hackages 🎯 Hackages Lab ================================================== ✔ 💡 What software development concept would you like to learn today? › TypeScript map function ✅ Detected language: TypeScript ✔ 🛠️ Please confirm your technology choice: › TypeScript (Your selection) ✔ 📊 Select your skill level: › Beginner 🔐 You'll be logging in with your GitHub account to track your progress. Press Enter to continue... 📥 Cloning TypeScript template repository... ✅ Repository template cloned to: typescript-map-function 🎉 Your learning exercise is ready! 📁 Repository cloned: ✓ typescript-map-function/ (Your exercise directory) ✓ typescript-map-function/tests/exercise-1.spec.ts (Your test cases) ✓ typescript-map-function/src/exercise-1.ts (Your implementation file) ✓ typescript-map-function/instructions/exercise-1.mdx (Exercise instructions) 🚀 Next steps: 1. cd typescript-map-function (navigate to your exercise directory) 2. Read the instructions and test file to understand what to implement 3. Open src/exercise-1.ts and start coding 4. Run 'npx hackages test' to validate your implementation 5. Run 'npx hackages review' to get feedback on your code $ cd typescript-map-function $ npx hackages test 🧪 Running tests... 📁 Running tests in: typescript-map-function ❌ 2 tests failed $ hackages review 📋 Code Review ================================================== 📁 Files to be reviewed: ✓ exercise-1.ts ✓ utils.ts Great start! Here's some feedback... 🎉 Code review completed! 📝 Feedback saved to: feedback/exercise-1.mdx 🌐 HTML page generated: feedback-exercise-1.html 💡 Opening feedback page in browser... ================================================== 🚀 Continue Your Learning Journey ================================================== Choose your next learning step: 1. Explore Different Number Types 2. Learn About Function Overloading 3. Error Handling 4. Generic Functions 5. Advanced TypeScript Features 6. Write your next learning goal 🔄 Generating your next exercise... 🎉 Your next exercise is ready! 📁 Next exercise created: ✓ tests/exercise-2.spec.ts (Your test cases) ✓ src/exercise-2.ts (Your implementation file) ✓ instructions/exercise-2.mdx (Exercise instructions) ``` ## 📋 Smart Code Review Get feedback on your implementations with multiple output formats: - **Multi-File Review**: Reviews all files in the `src/` directory automatically - **Terminal Display**: Beautiful formatted feedback in the terminal - **Template Storage**: Feedback saved to `feedback/exercise-1.mdx` in your exercise directory - **HTML Page**: Beautiful web page generated as `feedback-exercise-1.html` - **Backup Storage**: Feedback also saved to `~/.hackages/` for safekeeping - **Learning Continuation**: Hackages suggests next learning steps and generates the next exercise ## 🛠️ Supported Technologies - **JavaScript** - Full support with Vitest - **TypeScript** - Full support with type checking - **Python** - Coming soon - **Java** - Coming soon ## 📦 Repository Templates Hackages uses technology-specific repository templates that provide: - **Proper project structure** with `src/` and `tests/` directories - **Pre-configured testing framework** (Vitest for JS/TS) - **TypeScript configuration** (for TypeScript projects) - **Package.json** with necessary dependencies - **Git ignore files** and other project setup ### Template Repositories - **TypeScript**: [hackages/ts-template](https://github.com/hackages/ts-template) - **JavaScript**: [hackages/js-template](https://github.com/hackages/js-template) The system automatically detects your Git protocol preference: - **SSH**: Uses `git@github.com:hackages/<template>.git` - **HTTPS**: Uses `https://github.com/hackages/<template>.git` ## ⚙️ Requirements - Node.js 18+ - npm or yarn - Git (for repository cloning) - [Anthropic API Key](https://console.anthropic.com/) (for AI features) - GitHub account (for authentication) ### Authentication Hackages uses GitHub OAuth for user authentication: ```bash # Login with GitHub (opens browser) hackages login # Check if you're logged in hackages --help # Shows your username if logged in # Logout hackages logout ``` This enables personalized learning experiences and progress tracking. ## 🎨 CLI Interface Hackages features a modern CLI interface with: - 🎯 Arrow key navigation (like Vitest) - 🎨 Colored output and clear formatting - 📝 Interactive prompts with validation - ⚡ Fast and responsive design ## 📄 License © [Hackages](https://hackages.com) --- **Happy Learning! 🚀** _Built with ❤️ by the Hackages team_ ---