|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +### Build and Development |
| 8 | + |
| 9 | +- `yarn compile` - Compile TypeScript and run lint checks |
| 10 | +- `yarn watch` - Start development with file watching (runs both esbuild and TypeScript compiler) |
| 11 | +- `yarn package` - Build for production (includes type checking and linting) |
| 12 | +- `yarn check-types` - Run TypeScript type checking without emitting files |
| 13 | +- `yarn lint` - Run ESLint on source files |
| 14 | + |
| 15 | +### Testing |
| 16 | + |
| 17 | +- `yarn test` - Run all tests (includes compilation and linting) |
| 18 | +- `yarn compile-tests` - Compile test files only |
| 19 | +- `yarn watch-tests` - Watch and compile tests |
| 20 | + |
| 21 | +### Webview Development |
| 22 | + |
| 23 | +- `yarn dev` - Start both extension watcher and webview dev server with HMR (recommended for development) |
| 24 | +- `yarn serve-webview` - Start webpack dev server for hot reload during webview development |
| 25 | +- `yarn build-webview` - Build webview for production |
| 26 | +- `yarn watch-webview` - Watch and build webview for development (without HMR) |
| 27 | +- `yarn check-types-webview` - Run TypeScript type checking for webview files |
| 28 | + |
| 29 | +### Hot Module Replacement (HMR) |
| 30 | + |
| 31 | +The webview supports hot reloading during development: |
| 32 | + |
| 33 | +1. Run `yarn dev` to start both extension compilation and webview dev server |
| 34 | +2. Launch VS Code extension (F5) - the webview will automatically detect development mode |
| 35 | +3. Edit any webview React components in `src/webview/` - changes will hot reload instantly |
| 36 | +4. The extension uses `context.extensionMode` to detect development vs production |
| 37 | + |
| 38 | +### Extension Packaging |
| 39 | + |
| 40 | +- `yarn build-vsix` - Build production VSIX package |
| 41 | +- `yarn build-vsix-dev` - Build development VSIX without dependencies |
| 42 | +- `yarn publish` - Publish to VS Code marketplace |
| 43 | + |
| 44 | +## Code Architecture |
| 45 | + |
| 46 | +### Extension Structure |
| 47 | + |
| 48 | +This is a VS Code extension that provides intelligent Git checkout functionality with automatic stashing. The extension follows a modular architecture with clear separation of concerns: |
| 49 | + |
| 50 | +**Core Components:** |
| 51 | + |
| 52 | +- `CommandManager` - Centralized command registration and error handling |
| 53 | +- `ConfigurationManager` - Manages VS Code settings and user preferences |
| 54 | +- `StatusBarManager` - Handles the status bar display showing current stash mode |
| 55 | +- `LoggingService` - Centralized logging with configurable output |
| 56 | +- `PrCloneWebViewProvider` - PR Clone webview for GitHub pull request operations |
| 57 | + |
| 58 | +### Command Pattern Implementation |
| 59 | + |
| 60 | +All commands implement the `ICommand` interface and are registered through the `CommandManager`. This provides consistent error handling and makes commands easily testable. Each command is in its own directory under `src/commands/`. |
| 61 | + |
| 62 | +### Configuration System |
| 63 | + |
| 64 | +The extension uses a layered configuration approach: |
| 65 | + |
| 66 | +- VS Code workspace settings via `ConfigurationManager` |
| 67 | +- Real-time configuration updates through `onDidChangeConfiguration` |
| 68 | +- Global configuration persistence for user preferences |
| 69 | + |
| 70 | +### Git Integration |
| 71 | + |
| 72 | +Git operations are abstracted through `GitExecutor` in `src/common/git/`, which provides: |
| 73 | + |
| 74 | +- Promise-based command execution |
| 75 | +- Consistent error handling |
| 76 | +- Type-safe Git operation interfaces |
| 77 | + |
| 78 | +### Stash Modes |
| 79 | + |
| 80 | +The extension supports multiple auto-stash strategies: |
| 81 | + |
| 82 | +- **Manual**: User chooses stash behavior each time |
| 83 | +- **Auto stash in current branch**: Creates branch-specific stashes |
| 84 | +- **Auto stash and pop**: Transfers changes to new branch (destructive) |
| 85 | +- **Auto stash and apply**: Transfers changes while preserving original stash |
| 86 | + |
| 87 | +### WebView Integration |
| 88 | + |
| 89 | +The extension provides two collapsible webviews for PR cloning functionality: |
| 90 | + |
| 91 | +1. **PR Clone WebView** (`PrCloneWebViewProvider`): Main form with branch selection, feature branch name, and description fields. Contains Cancel and Create buttons. |
| 92 | + |
| 93 | +2. **PR Commits WebView** (`PrCommitsWebViewProvider`): Separate webview displaying the list of commits to cherry-pick. Users can select/deselect commits independently. |
| 94 | + |
| 95 | +Both webviews communicate through VS Code commands and message passing. The commits webview has a transparent background to integrate seamlessly with VS Code's theme. The webpack configuration generates separate bundles (`main.js` and `commits.js`) for each webview. |
| 96 | + |
| 97 | +### Build System |
| 98 | + |
| 99 | +Uses esbuild for fast bundling with a custom problem matcher plugin for VS Code integration. The build outputs to `dist/extension.js` as a CommonJS bundle with VS Code as an external dependency. |
| 100 | + |
| 101 | +### Extension Manifest |
| 102 | + |
| 103 | +Key package.json contributions: |
| 104 | + |
| 105 | +- Activity bar container: `git-smart-checkout` |
| 106 | +- PR Clone view: `git-smart-checkout.prClone` (conditionally shown) |
| 107 | +- Commands: checkout, pull-with-stash, switch-mode, clone-pull-request |
| 108 | +- Configuration properties for stash modes and logging |
| 109 | + |
| 110 | +## Important Development Notes |
| 111 | + |
| 112 | +### Command Registration |
| 113 | + |
| 114 | +When adding new commands, register them in `extension.ts` using the `CommandManager` pattern and ensure they implement the `ICommand` interface. |
| 115 | + |
| 116 | +### Configuration Changes |
| 117 | + |
| 118 | +New settings must be added to both `package.json` contributions and the `ExtensionConfig` interface in `src/configuration/extensionConfig.ts`. |
| 119 | + |
| 120 | +### Git Operations |
| 121 | + |
| 122 | +All Git commands should go through `GitExecutor` for consistency. The utility functions in `src/commands/utils/` provide common Git operations like branch listing and stash message formatting. |
| 123 | + |
| 124 | +### WebView Updates |
| 125 | + |
| 126 | +The WebView provider creates HTML with VS Code CSS variables for proper theming. Message handling between WebView and extension happens through `onDidReceiveMessage`. |
| 127 | + |
| 128 | +## React Development Guidelines |
| 129 | + |
| 130 | +- When creating React components, create them in a separate folder along with own CSS module file, and add styles related to this component to neighbour CSS module file, avoid using global CSS file unless it's necessary |
| 131 | +- When adding or editing a React component, order imports in the following order: |
| 132 | + 1. npm dependencies (with 'react' always first, if required by the component) |
| 133 | + 2. Project dependencies (separated by an empty line from npm dependencies) |
| 134 | + 3. Local dependencies from the same or nearby directories (separated by an empty line from project dependencies) |
0 commit comments