ai-changelog-generator-extension 0.4.0

package/DEVELOPMENT.md

@@ -0,0 +1,266 @@
+# VS Code Extension Development Guide
+
+## Project Overview
+
+This VS Code extension provides AI-powered git commit and changelog generation by leveraging the core `@entro314labs/ai-changelog-generator` npm package.
+
+## Architecture
+
+```
+Extension (TypeScript) → Core Package (Node.js) → AI Providers
+```
+
+**Key Components:**
+- `src/extension.ts` - Entry point, registers commands and views
+- `src/views/` - Webview providers for sidebar UI
+- `src/services/ExtensionConfigurationManager.ts` - Config bridge between VS Code and core
+- `src/commands/` - Command handlers
+- `src/types/core.d.ts` - Type definitions for core package
+
+## Development Setup
+
+### Prerequisites
+- Node.js >= 22.21.1
+- pnpm >= 10.27.0
+- VS Code >= 1.96.0
+
+### Initial Setup
+
+```bash
+# Install dependencies
+pnpm install
+
+# Compile TypeScript
+pnpm run compile
+
+# Or watch mode for development
+pnpm run watch
+```
+
+### Running the Extension
+
+1. Press `F5` in VS Code (or Run → Start Debugging)
+2. This opens a new "Extension Development Host" window
+3. Open any git repository
+4. Look for "AI Changelog" icon in the Activity Bar
+
+### Debugging
+
+- **Breakpoints:** Set in TypeScript files (they map to compiled JS)
+- **Console:** Use `console.log()` - output appears in Debug Console
+- **Reload:** Press `Ctrl+R` (Cmd+R on Mac) in Extension Host window
+
+### Testing Changes
+
+1. Make changes to TypeScript files
+2. Save (if watch mode is running, it auto-compiles)
+3. Reload Extension Host window (Cmd/Ctrl+R)
+4. Test your changes
+
+## Project Structure
+
+```
+vscode-extension/
+├── src/
+│   ├── extension.ts              # Main entry point
+│   ├── types/core.d.ts          # Type definitions for core package
+│   ├── commands/
+│   │   └── configureProvider.ts # API key configuration
+│   ├── services/
+│   │   └── ExtensionConfigurationManager.ts  # Config management
+│   └── views/
+│       ├── CommitSidebarProvider.ts  # Commit UI
+│       └── ReleaseSidebarProvider.ts # Release UI
+├── .vscode/
+│   ├── launch.json              # Debug configuration
+│   └── tasks.json               # Build tasks
+├── package.json                 # Extension manifest
+└── tsconfig.json                # TypeScript config
+```
+
+## How It Works
+
+### 1. Configuration Management
+
+The extension extends the core `ConfigurationManager` to bridge VS Code settings and secrets:
+
+```typescript
+// VS Code Settings → Core Config
+config.AI_PROVIDER = vscode.workspace.getConfiguration('aiChangelog').get('provider')
+
+// Secrets (async) → Core Config (sync)
+const apiKey = await secretStorage.get('OPENAI_API_KEY')
+configManager.set('OPENAI_API_KEY', apiKey)
+```
+
+### 2. Commit Message Generation
+
+```mermaid
+User clicks "Generate"
+  → Extension reads git status
+  → Core GitService analyzes changes
+  → Core ApplicationService calls AI
+  → Extension shows suggestions in QuickPick
+  → User selects → Extension populates SCM input
+```
+
+### 3. Changelog Generation
+
+```mermaid
+User enters version
+  → Extension calls ApplicationService
+  → Core analyzes commits since last tag
+  → AI generates structured changelog
+  → Extension opens in new editor
+```
+
+## Key Integration Points
+
+### Git Extension Integration
+
+```typescript
+const gitExtension = vscode.extensions.getExtension('vscode.git')
+const git = gitExtension.exports.getAPI(1)
+const repo = git.repositories[0]
+repo.inputBox.value = commitMessage  // Populate commit input
+```
+
+### Secret Storage
+
+```typescript
+// Store API key securely
+await context.secrets.store('OPENAI_API_KEY', apiKey)
+
+// Retrieve
+const apiKey = await context.secrets.get('OPENAI_API_KEY')
+```
+
+### Webview Communication
+
+```typescript
+// Extension → Webview
+webview.postMessage({ type: 'update', files: [...] })
+
+// Webview → Extension
+webview.onDidReceiveMessage(data => {
+  if (data.type === 'generate') {
+    generateCommitMessage()
+  }
+})
+```
+
+## Building for Production
+
+```bash
+# Compile
+pnpm run compile
+
+# Package extension
+pnpm run package
+
+# Creates: ai-changelog-generator-extension-0.1.0.vsix
+```
+
+## Publishing
+
+```bash
+# First time: Get Personal Access Token from Azure DevOps
+# https://dev.azure.com/[your-org]/_usersSettings/tokens
+
+# Login
+vsce login entro314labs
+
+# Publish
+pnpm run publish
+```
+
+## Common Tasks
+
+### Add New Command
+
+1. Define in `package.json`:
+```json
+{
+  "command": "ai-changelog.newCommand",
+  "title": "My New Command"
+}
+```
+
+2. Register in `extension.ts`:
+```typescript
+context.subscriptions.push(
+  vscode.commands.registerCommand('ai-changelog.newCommand', () => {
+    // Implementation
+  })
+)
+```
+
+### Add Configuration Setting
+
+1. Define in `package.json`:
+```json
+"aiChangelog.newSetting": {
+  "type": "string",
+  "default": "value",
+  "description": "My setting"
+}
+```
+
+2. Read in code:
+```typescript
+const value = vscode.workspace.getConfiguration('aiChangelog').get('newSetting')
+```
+
+### Update Core Package
+
+```bash
+# Get latest version
+pnpm update @entro314labs/ai-changelog-generator
+
+# Update types if API changed
+# Edit: src/types/core.d.ts
+```
+
+## Troubleshooting
+
+### "Cannot find module '@entro314labs/ai-changelog-generator'"
+- Run: `pnpm install`
+- Verify: `node_modules/@entro314labs/ai-changelog-generator` exists
+
+### "Extension doesn't activate"
+- Check Debug Console for errors
+- Verify `activationEvents` in package.json
+- Ensure workspace has a git repository
+
+### "API Key not found"
+- Run command: "AI Changelog: Configure AI Provider"
+- Keys are stored in VS Code Secret Storage
+- Check: `configManager.getApiKey(provider)` returns value
+
+### TypeScript errors
+- Run: `pnpm run compile` and check output
+- Verify `src/types/core.d.ts` matches core package API
+- Update `@types/vscode` if VS Code API changed
+
+## Best Practices
+
+1. **Always pre-load secrets** before calling core services (they're async)
+2. **Handle multi-root workspaces** - don't assume `workspaceFolders[0]`
+3. **Show progress notifications** for long AI operations
+4. **Catch and display errors** user-friendly (no stack traces in UI)
+5. **Use workspace configuration** for repo-specific settings
+6. **Test with large repositories** (performance matters)
+
+## Resources
+
+- [VS Code Extension API](https://code.visualstudio.com/api)
+- [Webview Guide](https://code.visualstudio.com/api/extension-guides/webview)
+- [Core Package Docs](https://github.com/entro314-labs/AI-changelog-generator)
+- [Publishing Guide](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)
+
+## Next Steps
+
+See the main project [README.md](./README.md) for user-facing documentation.
+
+For issues and feature requests, visit:
+https://github.com/entro314-labs/ai-changelog-generator-vscode/issues

package/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,240 @@
+# VS Code Extension - Implementation Summary
+
+## ✅ Completed Tasks
+
+### 1. **Module System Fixed**
+- ❌ Removed `src/core/` folder (was causing import issues)
+- ✅ Updated `package.json` to use npm package: `@entro314labs/ai-changelog-generator: ^3.7.1`
+- ✅ All imports now reference the published package
+- ✅ Type definitions in `src/types/core.d.ts` provide TypeScript support
+
+### 2. **Development Environment Setup**
+- ✅ Created `.vscode/launch.json` for debugging extension
+- ✅ Created `.vscode/tasks.json` for build automation
+- ✅ Created `.vscode/settings.json` for editor configuration
+- ✅ Added `.gitignore` with proper exclusions
+- ✅ Dependencies installed successfully
+
+### 3. **Configuration Management Enhanced**
+- ✅ `ExtensionConfigurationManager` extends core `ConfigurationManager`
+- ✅ Async secret loading with `initialize()` method
+- ✅ Bridges VS Code settings → Core config
+- ✅ Secure API key storage via Secret Storage
+
+### 4. **Error Handling & Validation**
+- ✅ Workspace validation before operations
+- ✅ User-friendly error messages
+- ✅ Progress notifications for long operations
+- ✅ Graceful fallbacks
+
+### 5. **Build System**
+- ✅ TypeScript compilation working (`pnpm run compile`)
+- ✅ Watch mode available (`pnpm run watch`)
+- ✅ Output directory: `out/`
+- ✅ Source maps generated for debugging
+
+### 6. **Documentation**
+- ✅ `README.md` - User-facing documentation
+- ✅ `CHANGELOG.md` - Version history
+- ✅ `DEVELOPMENT.md` - Developer guide
+- ✅ `package.json` - Comprehensive metadata
+
+## 🏗️ Architecture Overview
+
+```
+VS Code Extension (Standalone Repo)
+│
+├── Uses npm package: @entro314labs/ai-changelog-generator
+│   └── Imports from node_modules (not bundled)
+│
+├── Extension Components
+│   ├── CommitSidebarProvider → Shows changed files
+│   ├── ReleaseSidebarProvider → Shows tags
+│   ├── ExtensionConfigurationManager → Config bridge
+│   └── Commands → User actions
+│
+└── VS Code Integration
+    ├── Secret Storage → API keys
+    ├── Git Extension API → SCM input
+    └── Webview → Rich UI
+```
+
+## 📦 Package Structure
+
+```
+vscode-extension/
+├── src/
+│   ├── extension.ts                    ✅ Entry point
+│   ├── types/core.d.ts                 ✅ Type definitions
+│   ├── commands/
+│   │   └── configureProvider.ts       ✅ API key setup
+│   ├── services/
+│   │   └── ExtensionConfigurationManager.ts  ✅ Config bridge
+│   └── views/
+│       ├── CommitSidebarProvider.ts   ✅ Commit UI (enhanced)
+│       └── ReleaseSidebarProvider.ts  ✅ Release UI (enhanced)
+│
+├── .vscode/                            ✅ Debug & build config
+├── out/                                ✅ Compiled JS (generated)
+├── package.json                        ✅ Updated with npm dep
+├── tsconfig.json                       ✅ TypeScript config
+├── README.md                           ✅ User docs
+├── CHANGELOG.md                        ✅ Version history
+└── DEVELOPMENT.md                      ✅ Dev guide
+```
+
+## 🚀 How to Run
+
+### For Development
+```bash
+cd vscode-extension
+pnpm install
+pnpm run compile
+# Press F5 in VS Code to launch Extension Host
+```
+
+### For Users (Future)
+```bash
+# From VS Code Marketplace
+code --install-extension entro314labs.ai-changelog-generator-extension
+```
+
+## 🎯 Current Capabilities
+
+### Commit Assistant (Sidebar)
+- ✅ Lists changed files (staged/unstaged)
+- ✅ Shows file status (M, A, D)
+- ✅ Displays categories and importance
+- ✅ "Generate Commit Message" button
+- ✅ AI suggestions in QuickPick
+- ✅ Populates Git SCM input box
+
+### Release Manager (Sidebar)
+- ✅ Lists recent git tags
+- ✅ "Draft New Release" button
+- ✅ Version input prompt
+- ✅ AI generates changelog
+- ✅ Opens in new editor
+
+### Commands
+- ✅ `AI Changelog: Generate AI Commit`
+- ✅ `AI Changelog: Generate Release`
+- ✅ `AI Changelog: Configure AI Provider`
+
+### Configuration
+- ✅ `aiChangelog.provider` - Select AI provider
+- ✅ `aiChangelog.model` - Override model
+- ✅ `aiChangelog.temperature` - Control creativity
+
+## 🔧 Integration Points
+
+### Core Package Integration
+```typescript
+// Imports from npm package
+import { GitManager } from '@entro314labs/ai-changelog-generator/src/domains/git/git-manager.js'
+import { ApplicationService } from '@entro314labs/ai-changelog-generator/src/application/services/application.service.js'
+```
+
+### VS Code APIs Used
+- `vscode.window.registerWebviewViewProvider` - Sidebar panels
+- `vscode.commands.registerCommand` - Commands
+- `vscode.workspace.getConfiguration` - Settings
+- `vscode.SecretStorage` - API keys
+- `vscode.extensions.getExtension('vscode.git')` - Git integration
+
+## 🐛 Known Limitations
+
+1. **Multi-root workspaces** - Currently assumes single workspace folder
+2. **Large repositories** - No pagination for file lists yet
+3. **Diff preview** - Not implemented in UI (planned)
+4. **Staging/unstaging** - View-only, no file operations yet
+5. **Offline mode** - Requires active AI provider
+
+## 📋 Next Steps (Future Enhancements)
+
+### Phase 1 - Core UX (Priority)
+- [ ] Add diff preview in webview
+- [ ] File tree view (grouped by folder)
+- [ ] Stage/unstage operations from UI
+- [ ] Commit message validation (conventional commits)
+- [ ] Multi-root workspace support
+
+### Phase 2 - Smart Features
+- [ ] AI suggests file groupings
+- [ ] Breaking change detection
+- [ ] Semantic versioning suggestions
+- [ ] Commit templates
+- [ ] Recent commits history
+
+### Phase 3 - Advanced
+- [ ] Stacked changes visualization
+- [ ] PR description generation
+- [ ] Team conventions learning
+- [ ] GitHub/GitLab integration
+- [ ] Telemetry & analytics
+
+### Phase 4 - Polish
+- [ ] Comprehensive testing (unit + E2E)
+- [ ] Performance optimization
+- [ ] Better error recovery
+- [ ] Onboarding tutorial
+- [ ] Keyboard shortcuts
+
+## 🎨 UI Improvements Needed
+
+Current UI is basic HTML. Consider upgrading to:
+- **VS Code Webview UI Toolkit** - Native look and feel
+- **React/Preact** - Component-based UI
+- **File tree component** - Better visualization
+- **Inline diff viewer** - See changes without leaving sidebar
+
+## 📊 Testing Strategy
+
+### Manual Testing
+1. ✅ Build compiles without errors
+2. ✅ Extension activates in host window
+3. ✅ Commands registered and callable
+4. ⏳ Commit generation works (requires API key)
+5. ⏳ Release generation works (requires API key)
+
+### Automated Testing (TODO)
+- [ ] Unit tests for ConfigurationManager
+- [ ] Integration tests for GitService
+- [ ] E2E tests for full workflow
+- [ ] Mock AI responses
+
+## 🚢 Publishing Checklist
+
+Before publishing to marketplace:
+
+- [ ] Test with all supported AI providers
+- [ ] Verify icon/logo (resources/icon.svg)
+- [ ] Update version in package.json
+- [ ] Complete CHANGELOG.md
+- [ ] Add screenshots to README
+- [ ] Create demo GIF
+- [ ] Test on Windows/Linux/Mac
+- [ ] Get publisher account (Azure DevOps)
+- [ ] Package: `vsce package`
+- [ ] Publish: `vsce publish`
+
+## 🔗 Related Repositories
+
+- **Core Package**: https://github.com/entro314-labs/AI-changelog-generator
+- **Extension Repo**: https://github.com/entro314-labs/ai-changelog-generator-vscode (to be created)
+
+## 📝 Migration Notes
+
+When moving to separate repo:
+
+1. Copy entire `vscode-extension/` folder
+2. Initialize git: `git init`
+3. Create GitHub repo
+4. Update package.json URLs to new repo
+5. Publish to marketplace
+6. Update core package README to link to extension
+
+---
+
+**Status**: ✅ **MVP Ready for Testing**
+**Next Action**: Test with real API keys and iterate on UX