|
| 1 | +# Git Commit Helper - AI Coding Instructions |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +A **uTools plugin** built with Vue 3 + Vite that helps generate standardized git commit messages with emoji icons. The app runs inside uTools desktop application and provides two views: main commit generator and configuration panel. |
| 6 | + |
| 7 | +## Architecture & Key Concepts |
| 8 | + |
| 9 | +### uTools Plugin Integration |
| 10 | + |
| 11 | +- **Entry point**: `public/plugin.json` defines plugin metadata, features, and entry commands |
| 12 | +- **Development mode**: Uses `http://localhost:5173` (configured in `plugin.json`) |
| 13 | +- **Production**: Serves from `index.html` after build |
| 14 | +- **Preload script**: `public/preload/services.js` injects Node.js capabilities into renderer process via `window.services` |
| 15 | +- **Plugin lifecycle**: App uses `window.utools.onPluginEnter()` and `window.utools.onPluginOut()` for navigation |
| 16 | +- **Feature codes**: `commit` (main view) and `config` (settings) trigger different views in `App.vue` |
| 17 | + |
| 18 | +### Data Persistence |
| 19 | + |
| 20 | +- **Storage**: Uses `utools.dbStorage` API wrapped in `src/utils/store.js` |
| 21 | +- **No backend**: All settings stored locally in uTools database |
| 22 | +- **Config keys**: `useIcon`, `isCustomType`, `isCustomIcon`, `isKill`, `customFileUrl`, `customIconUrl`, `hideTip` |
| 23 | + |
| 24 | +### Custom Data Sources |
| 25 | + |
| 26 | +Users can override default commit types and icons via remote JSON URLs: |
| 27 | + |
| 28 | +- Default data: `src/data/commitTypes.json` and `src/data/iconOptions.json` |
| 29 | +- Custom URLs fetched at runtime if enabled in config |
| 30 | +- Expected format: Array of `{value, label, icon}` objects |
| 31 | + |
| 32 | +## Development Workflow |
| 33 | + |
| 34 | +### Commands |
| 35 | + |
| 36 | +- **Dev server**: `pnpm dev` - Starts Vite on port 5173 |
| 37 | +- **Build**: `pnpm build` - Creates production bundle in `dist/` |
| 38 | +- **Test in uTools**: Run dev server, then trigger plugin with keywords like "feat", "commit", "fix" |
| 39 | + |
| 40 | +### Path Aliasing |
| 41 | + |
| 42 | +- `@` resolves to `src/` directory (configured in `vite.config.js`) |
| 43 | +- Use `@/utils/store` instead of `../utils/store` |
| 44 | + |
| 45 | +### Debugging |
| 46 | + |
| 47 | +- **Vue DevTools**: Integrated via `vite-plugin-vue-devtools` |
| 48 | +- **Console logging**: Check browser DevTools when running in uTools |
| 49 | +- **Entry action payload**: `props.enterAction.payload` contains the keyword used to trigger plugin |
| 50 | + |
| 51 | +## Project-Specific Patterns |
| 52 | + |
| 53 | +### Component Communication |
| 54 | + |
| 55 | +- **Props-based routing**: `App.vue` passes `enterAction` prop to child components |
| 56 | +- **No Vue Router**: Simple conditional rendering based on `route.value` from uTools plugin code |
| 57 | +- **Payload initialization**: `HomeView` uses `enterAction.payload` to pre-select commit type |
| 58 | + |
| 59 | +### UI Framework |
| 60 | + |
| 61 | +- **Ant Design Vue 4.x**: Use `<a-select>`, `<a-input>`, `<a-textarea>`, `<a-switch>`, etc. |
| 62 | +- **Icons**: Import from `@ant-design/icons-vue` (e.g., `SettingFilled`) |
| 63 | +- **Messages**: Use `message.success()` for toast notifications |
| 64 | +- **Copy interaction**: `<a-typography-paragraph :copyable="...">` with `onCopy` callback |
| 65 | + |
| 66 | +### State Management |
| 67 | + |
| 68 | +- **Composition API**: All components use `<script setup>` |
| 69 | +- **Reactive state**: Use `ref()` for all mutable state |
| 70 | +- **Computed values**: `generatedCommitMessage` and `generatedGitCommitMessage` auto-update |
| 71 | +- **Config defaults**: Use `getData(key) ?? defaultValue` pattern in `ConfigView.vue` |
| 72 | + |
| 73 | +### Commit Message Format |
| 74 | + |
| 75 | +Generated format: `{icon} {type}({scope}): {message}` or `{type}({scope}): {message}` |
| 76 | + |
| 77 | +- Example with icon: `✨ feat(ui): add new button component` |
| 78 | +- Example without: `feat(api): add user endpoint` |
| 79 | +- Git command output: `git commit -m"{generated message}"` |
| 80 | + |
| 81 | +## Key Files Reference |
| 82 | + |
| 83 | +- `src/App.vue` - Plugin lifecycle and view routing |
| 84 | +- `src/components/HomeView.vue` - Main commit generator (200+ lines) |
| 85 | +- `src/components/ConfigView.vue` - Settings panel |
| 86 | +- `public/plugin.json` - uTools plugin manifest |
| 87 | +- `public/preload/services.js` - Node.js API bridge |
| 88 | +- `src/utils/store.js` - uTools storage wrapper |
| 89 | + |
| 90 | +## Common Pitfalls |
| 91 | + |
| 92 | +1. **Don't use Vue Router** - uTools plugins use custom routing via `onPluginEnter()` |
| 93 | +2. **Don't forget `window.utools` prefix** - All uTools APIs require `window.` or global scope |
| 94 | +3. **Base path matters** - Set `base: './'` in Vite config for proper asset loading |
| 95 | +4. **Preload script limitations** - Can't use ES modules, must use CommonJS (`require`) |
| 96 | +5. **Plugin exit behavior** - Respect `isKill` config when copying (controls auto-hide) |
| 97 | + |
| 98 | +## Testing Plugin Changes |
| 99 | + |
| 100 | +1. Start dev server: `pnpm dev` |
| 101 | +2. Open uTools (usually Alt+Space) |
| 102 | +3. Type trigger keywords: "feat", "commit", "fix", etc. |
| 103 | +4. Plugin should load from `localhost:5173` |
| 104 | +5. For config: Type "git commit config" |
0 commit comments