e-pick 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -0,0 +1,339 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+E-Pick is a web-based tool for cherry-picking git commits from Excel/CSV files. It consists of a CLI that starts an Express server serving a single-page application. The tool validates commit hashes from uploaded files, generates cherry-pick commands in chronological order, and shows affected files.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd e-pick
+
+# Install dependencies
+npm install
+
+# Start development server
+epick
+```
+
+The tool will start on http://localhost:7991 and automatically open your browser.
+
+## Development Commands
+
+```bash
+# Start the tool
+epick
+
+# Start with specific repository
+epick /path/to/repo
+epick my-project              # Using saved alias
+
+# Start on custom port
+epick --port 8080
+
+# Don't auto-open browser
+epick --no-open
+
+# Repository management
+epick repo add my-project              # Save current directory
+epick repo add my-project /path/to/repo # Save specific path
+epick repo list                        # List all saved repositories
+epick repo remove my-project           # Remove repository
+
+# Linting
+npm run lint
+npm run lint:fix
+```
+
+## Architecture
+
+### CLI Entry Point (src/cli.js)
+- **CLI name**: `epick` (npm package name: `e-pick`)
+- **Command structure**: Uses Commander.js with subcommands
+  - Main command: `epick [repository]` - starts server with optional repository path/alias
+  - Subcommands: `repo list|add|remove`
+- Validates repository path and ensures it's a git repository using `git rev-parse --git-dir`
+- Manages repository aliases via RepoManager (stored in `~/.e-pick/repos.json`)
+- Starts Express server and passes repository path to AppConfig singleton
+- **Automatically opens browser** using `open` package (unless `--no-open` flag is used)
+- Handles graceful shutdown on SIGINT/SIGTERM
+- Auto-saves repositories when using paths for the first time
+
+### Express Server (src/server.js)
+- Serves static files from `public/` directory (SPA: index.html + CSS + JS)
+- Provides REST API endpoints for commit validation and command generation
+- Port fallback strategy: tries requested port (default 7991), falls back to random port 8000-9000
+- Security: Helmet middleware (CSP disabled for CDN libraries) and CORS enabled
+- Error handling middleware for consistent error responses
+- Validation middleware using Joi schemas
+
+### Configuration Layer
+- **AppConfig** (src/config/app.config.js): Singleton pattern for centralized configuration
+  - Manages server config (port, host)
+  - Stores current repository path
+  - Provides git, CORS, and logging settings
+- **RepoManager** (src/config/repo-manager.js): Repository alias management
+  - Saves/loads/removes repository aliases
+  - Stores in `~/.e-pick/repos.json` in user home directory
+  - Thread-safe file operations with proper error handling
+
+### Services Layer
+- **GitService** (src/services/git.service.js): Abstracts all git operations using execSync
+  - Validates commits exist in repository using `git cat-file -t`
+  - Gets commit info (hash, date, author, message) using `git show`
+  - Sorts commits chronologically by date (critical for cherry-picking)
+  - Generates cherry-pick commands with proper formatting
+  - Lists changed files across commits using `git diff-tree`
+  - All operations use `cwd: repoPath` for correct repository context
+
+- **ValidationService** (src/services/validation.service.js): Orchestrates multi-commit validation
+  - Delegates to commit.validator.js for individual commit validation
+  - Generates summary statistics (total, valid, invalid, canBeIgnored)
+  - Groups validation results by status
+  - Handles batch validation with proper error aggregation
+
+### Controllers
+- **commit.controller.js** (src/controllers/commit.controller.js): Handles all API routes
+  - `POST /api/validate` - Validates array of commit hashes
+  - `POST /api/generate-command` - Generates cherry-pick command with sorted commits
+  - `GET /api/repo-info` - Returns current repository information
+  - `GET /api/check-commit/:commitHash` - Checks if individual commit exists
+  - Uses asyncHandler utility to catch async errors
+  - Returns consistent JSON responses
+
+### Commands (Command Pattern)
+- **CherryPickCommand** (src/commands/cherry-pick.command.js): Encapsulates cherry-pick operation
+  - Sorts commits by date before generating command
+  - Returns commit details, changed files, and warnings for large batches (>50 commits)
+  - Built for future undo functionality
+  - Validates all commits before building command
+
+### Middleware
+- **validation.middleware.js**: Joi schema validation for request bodies
+  - Validates 40-character commit hashes format
+  - Supports ignoredCommits array and options object
+  - Returns 400 errors for invalid requests
+
+- **error.middleware.js**: Centralized error handling
+  - Custom error classes: ValidationError, GitError, NotFoundError
+  - Maps error types to appropriate HTTP status codes
+  - 404 handler for unknown routes
+  - Consistent error response format
+
+### Validators
+- **commit.validator.js** (src/validators/commit.validator.js): Individual commit validation logic
+  - Validates commit hash format (40 hex characters)
+  - Checks if commit exists in repository
+  - Returns validation result with error details
+  - Used by ValidationService
+
+### Frontend (public/)
+- **Single-page application** with 5-step wizard interface
+  1. Upload Excel/CSV file
+  2. Select columns containing commit hashes and descriptions
+  3. Validate commits against repository
+  4. Review results and generate command
+  5. View changed files
+
+- **File parsing**:
+  - SheetJS (xlsx) for Excel file parsing (.xlsx, .xls)
+  - PapaParse for CSV file parsing
+  - Parser Factory pattern for extensibility
+
+- **State management**:
+  - Observer pattern for UI updates
+  - State pattern for wizard step management
+  - Filter strategies for commit filtering
+
+- **Vanilla JavaScript** (no framework)
+  - Modular architecture with separate concerns
+  - API Facade for backend communication
+  - UI Manager for DOM updates
+
+## Key Technical Details
+
+### Commit Hash Validation
+- All commit hashes must be full 40-character SHA-1 hashes
+- Validation uses `git cat-file -t <hash>` to verify commit exists
+- Short hashes are NOT supported in API layer
+- Frontend validates format before sending to backend
+
+### Chronological Sorting
+- **Critical**: Commits are always sorted by commit date before cherry-picking
+- This prevents issues with dependencies between commits
+- Sorting uses `git show -s --format="%ci %H"` to get timestamps
+- Commits sorted in ascending order (oldest first)
+
+### Repository Path Flow
+1. CLI validates path is a git repository using `git rev-parse --git-dir`
+2. Path stored in AppConfig singleton
+3. All services instantiate with repoPath from AppConfig
+4. Git commands execute with `cwd: repoPath` to ensure correct context
+5. Repository aliases stored separately in `~/.e-pick/repos.json`
+
+### Error Handling
+- All git operations wrapped in try-catch blocks
+- Git errors parsed for user-friendly messages
+- Controllers use asyncHandler utility to catch async errors
+- Custom error types map to appropriate HTTP status codes
+- Frontend displays errors with clear messages and suggestions
+
+## Project Structure
+
+```
+e-pick/
+├── src/
+│   ├── cli.js              # CLI entry point with Commander.js
+│   ├── server.js           # Express server setup
+│   ├── config/
+│   │   ├── app.config.js   # Singleton configuration
+│   │   └── repo-manager.js # Repository alias management
+│   ├── controllers/
+│   │   └── commit.controller.js  # API route handlers
+│   ├── services/
+│   │   ├── git.service.js        # Git operations (Repository Pattern)
+│   │   └── validation.service.js # Validation orchestration
+│   ├── middleware/
+│   │   ├── error.middleware.js     # Error handling
+│   │   └── validation.middleware.js # Request validation (Joi)
+│   ├── commands/
+│   │   └── cherry-pick.command.js  # Command pattern
+│   ├── validators/
+│   │   └── commit.validator.js     # Commit validation logic
+│   └── utils/
+│       └── error-handler.js        # Error utilities
+├── public/
+│   ├── index.html          # Main UI (5-step wizard)
+│   ├── css/
+│   │   └── styles.css      # Catppuccin Latte theme
+│   └── js/
+│       ├── app.js                    # Main orchestrator
+│       ├── ui-manager.js             # UI updates
+│       ├── commit-validator.js       # Validation handling
+│       ├── file-parser.js            # File parsing
+│       ├── api-facade.js             # API communication
+│       ├── cherry-pick-builder.js    # Command builder
+│       ├── filter-strategy.js        # Filtering strategies
+│       ├── observable.js             # Observer pattern
+│       ├── stepper-states.js         # State pattern for wizard
+│       └── parsers/                  # File parser implementations
+│           ├── base-parser.js
+│           ├── csv-parser.js
+│           ├── excel-parser.js
+│           └── parser-factory.js
+├── package.json
+├── CLAUDE.md              # This file (developer documentation)
+└── README.md              # User documentation
+```
+
+## Design Patterns
+
+### Singleton Pattern
+- **AppConfig**: Ensures single source of truth for configuration across all services
+- Lazy initialization on first access
+- Provides centralized repository path management
+
+### Repository Pattern
+- **GitService**: Abstracts all git operations, making it easy to mock or swap implementations
+- Encapsulates git command execution
+- Provides clean interface for business logic
+
+### Command Pattern
+- **CherryPickCommand**: Encapsulates cherry-pick operation as an object
+- Enables future undo/redo functionality
+- Separates command construction from execution
+
+### Factory Pattern
+- **ParserFactory**: Creates appropriate parser based on file type
+- Extensible for new file formats
+- Encapsulates parser instantiation logic
+
+### Observer Pattern
+- **Observable**: Frontend event system for UI updates
+- Decouples data changes from UI updates
+- Enables reactive UI behavior
+
+### Service Layer Pattern
+- Services handle business logic
+- Controllers are thin and delegate to services
+- Clear separation of concerns
+
+## Configuration
+
+- **Default Port**: 7991
+- **Fallback Range**: 8000-9000 (if default port is occupied)
+- **Repository Aliases**: Stored in `~/.e-pick/repos.json`
+- **Git Timeout**: 30 seconds for git operations
+- **Max Commits Per Batch**: 100 commits (warning shown above 50)
+- **Node.js**: >= 18.0.0 required
+
+## Code Style
+
+- **ES6 modules**: `type: "module"` in package.json
+- **ESLint**: Airbnb base configuration
+- **File naming**: kebab-case for files, camelCase for variables
+- **Imports**: Prefer explicit imports over default exports
+- **Comments**: JSDoc for public methods and complex logic
+- **Error handling**: Always handle errors explicitly, no silent failures
+
+## Testing Strategy
+
+When writing tests:
+- Mock `execSync` for GitService tests to avoid real git operations
+- Test validation logic with various commit hash formats (short, long, invalid)
+- Test chronological sorting with out-of-order commits
+- Test error scenarios: invalid repo path, missing commits, network failures
+- Test edge cases: empty files, malformed data, large batches
+
+## Common Tasks
+
+### Adding a New API Endpoint
+1. Add route handler in `src/controllers/commit.controller.js`
+2. Add validation schema in `src/middleware/validation.middleware.js`
+3. Implement business logic in appropriate service
+4. Update API Facade in `public/js/api-facade.js`
+
+### Adding Support for New File Format
+1. Create parser class in `public/js/parsers/` extending BaseParser
+2. Register in ParserFactory
+3. Update file input accept attribute in HTML
+4. Test with sample files
+
+### Modifying Git Operations
+1. Update GitService methods in `src/services/git.service.js`
+2. Ensure proper error handling
+3. Test with mock execSync
+4. Update related controller logic if needed
+
+## Environment Variables
+
+- `LOG_LEVEL` - Logging level (default: 'info')
+- `PORT` - Server port (can also use --port flag)
+- No other environment variables required for basic operation
+
+## Dependencies
+
+### Backend
+- **express**: Web server framework
+- **commander**: CLI argument parsing
+- **chalk**: Terminal styling
+- **joi**: Schema validation
+- **helmet**: Security headers
+- **cors**: CORS middleware
+- **open**: Auto-open browser
+
+### Frontend
+- **SheetJS (xlsx)**: Excel file parsing
+- **PapaParse**: CSV file parsing
+- No build step required (vanilla JS)
+
+## Known Limitations
+
+- Short commit hashes not supported (must be full 40-character)
+- Large files (>10MB) may cause browser performance issues
+- Only supports standard git repositories (no submodules)
+- Requires git to be installed and in PATH

package/README.md

@@ -0,0 +1,109 @@
+# E-Pick
+
+> Web-based tool for cherry-picking git commits from Excel/CSV files
+
+E-Pick simplifies the process of cherry-picking multiple git commits by allowing you to manage commit lists in spreadsheet files. Upload an Excel or CSV file containing commit hashes, validate them against your repository, and generate ready-to-use cherry-pick commands.
+
+## Features
+
+- Upload Excel (.xlsx, .xls) or CSV files containing commit information
+- Validates all commits against your repository before cherry-picking
+- Interactive 5-step wizard interface
+- Automatically sorts commits by date to prevent dependency issues
+- Clear error messages for invalid commits
+- Save and reuse repository paths with aliases
+- Preview all files affected by selected commits
+- Generates ready-to-execute cherry-pick commands
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Git repository
+
+## Installation
+
+```bash
+# Install globally (future - when published to npm)
+npm install -g epick
+
+# Or use npx
+npx epick
+```
+
+## Usage
+
+### Start the Tool
+
+```bash
+# In your git repository
+epick
+
+# With specific repository
+epick /path/to/repo
+
+# With saved repository alias
+epick my-project
+
+# Don't auto-open browser
+epick --no-open
+```
+
+The tool will automatically open your browser.
+
+### Save Repositories
+
+```bash
+# Save current directory
+epick repo add my-project
+
+# Save specific path
+epick repo add work-repo /path/to/repo
+
+# List saved repositories
+epick repo list
+
+# Remove repository
+epick repo remove my-project
+```
+
+### Workflow
+
+1. **Upload File**: Drag and drop your Excel/CSV file
+2. **Select Columns**: Choose which columns contain commit hashes and descriptions
+3. **Validate**: The tool validates all commits against your repository
+4. **Review Results**: View valid/invalid commits with clear indicators
+5. **Generate Command**: Get a ready-to-execute cherry-pick command
+6. **Execute**: Copy and run the command in your terminal
+
+### File Format
+
+Your Excel or CSV file should contain commit hashes:
+
+| Commit Hash | Description |
+|-------------|-------------|
+| abc123...   | Fix login bug |
+| def456...   | Add new feature |
+| ghi789...   | Update dependencies |
+
+**Note**: Use full commit hashes (40 characters). Short hashes are not supported.
+
+## Troubleshooting
+
+### "Not a git repository" error
+
+Run the tool in a git repository directory:
+```bash
+epick /path/to/your/repo
+```
+
+### Invalid commit hashes
+
+Make sure your file contains full commit hashes (not shortened versions).
+
+## Development
+
+For technical documentation and development setup, see [CLAUDE.md](./CLAUDE.md).
+
+## License
+
+MIT

package/package.json

@@ -1,18 +1,47 @@
 {
   "name": "e-pick",
-  "version": "2.0.0",
-  "description": "",
-  "scripts": {},
+  "version": "3.0.0",
+  "type": "module",
+  "description": "Web-based tool for cherry-picking git commits from Excel/CSV files",
+  "main": "src/server.js",
   "bin": {
-    "epick": "./cli.js"
+    "epick": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "public/",
+    "CLAUDE.md"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "lint": "eslint src/ public/js/",
+    "lint:fix": "eslint src/ public/js/ --fix"
+  },
+  "keywords": [
+    "git",
+    "cherry-pick",
+    "excel",
+    "csv",
+    "cli",
+    "git-tools",
+    "commit-management"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
   },
-  "keywords": [],
-  "author": "",
-  "type": "module",
   "license": "MIT",
   "dependencies": {
-    "express": "^4.21.0",
-    "joi": "^17.13.3",
-    "meow": "^13.2.0"
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "helmet": "^7.1.0",
+    "joi": "^17.11.0",
+    "open": "^10.2.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.55.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-plugin-import": "^2.29.0"
   }
 }