feat(extension): add VS Code extension with kanban board interface
- Complete VS Code extension with React-based kanban board UI - MCP integration for real-time Task Master synchronization - Professional CI/CD workflows for marketplace publishing - Comprehensive configuration system with user preferences - ShadCN UI components with VS Code theme integration - Drag-and-drop task management with status transitions - AI-powered task features via MCP protocol - Robust error handling and connection management - Multi-registry publishing (VS Code Marketplace + Open VSX) - Security audit completed with hardcoded paths removed BREAKING CHANGE: Extension requires publisher setup and marketplace keys Publisher and extension naming decisions required: - Update publisher field from placeholder 'DavidMaliglowka' - Choose unique extension name (currently 'taskr-kanban') - Select appropriate extension icon - Configure CI secrets (VSCE_PAT, OVSX_PAT) for publishing See apps/extension/docs/ for detailed setup instructions
This commit is contained in:
DavidMaliglowka
159
apps/extension/docs/extension-CI-setup.md
Normal file
159
apps/extension/docs/extension-CI-setup.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# VS Code Extension CI/CD Setup
|
||||
|
||||
This document explains the CI/CD setup for the Task Master VS Code extension.
|
||||
|
||||
## 🔄 Workflows Overview
|
||||
|
||||
### 1. Extension CI (`extension-ci.yml`)
|
||||
**Triggers:**
|
||||
- Push to `main` or `next` branches (only when extension files change)
|
||||
- Pull requests to `main` or `next` (only when extension files change)
|
||||
|
||||
**What it does:**
|
||||
- ✅ Lints and type-checks the extension code
|
||||
- 🔨 Builds the extension (`pnpm run build`)
|
||||
- 📦 Creates a clean package (`pnpm run package`)
|
||||
- 🧪 Runs tests with VS Code test framework
|
||||
- 📋 Creates a test VSIX package to verify packaging works
|
||||
- 💾 Uploads build artifacts for inspection
|
||||
|
||||
### 2. Extension Release (`extension-release.yml`)
|
||||
**Triggers:**
|
||||
- Push to `main` branch (only when extension files change AND version changes)
|
||||
- Manual trigger with `workflow_dispatch` (with optional force publish)
|
||||
|
||||
**What it does:**
|
||||
- 🔍 Checks if the extension version changed
|
||||
- 🧪 Runs full test suite (lint, typecheck, tests)
|
||||
- 🔨 Builds and packages the extension
|
||||
- 📤 Publishes to VS Code Marketplace
|
||||
- 🌍 Publishes to Open VSX Registry (for VSCodium, Gitpod, etc.)
|
||||
- 🏷️ Creates a GitHub release with the VSIX file
|
||||
- 📊 Uploads release artifacts
|
||||
|
||||
## 🔑 Required Secrets
|
||||
|
||||
To use the release workflow, you need to set up these GitHub repository secrets:
|
||||
|
||||
### `VSCE_PAT` (VS Code Marketplace Personal Access Token)
|
||||
1. Go to [Azure DevOps](https://dev.azure.com/)
|
||||
2. Sign in with your Microsoft account
|
||||
3. Create a Personal Access Token:
|
||||
- **Name**: VS Code Extension Publishing
|
||||
- **Organization**: All accessible organizations
|
||||
- **Expiration**: Custom (recommend 1 year)
|
||||
- **Scopes**: Custom defined → **Marketplace** → **Manage**
|
||||
4. Copy the token and add it to GitHub Secrets as `VSCE_PAT`
|
||||
|
||||
### `OVSX_PAT` (Open VSX Registry Personal Access Token)
|
||||
1. Go to [Open VSX Registry](https://open-vsx.org/)
|
||||
2. Sign in with your GitHub account
|
||||
3. Go to your [User Settings](https://open-vsx.org/user-settings/tokens)
|
||||
4. Create a new Access Token:
|
||||
- **Description**: VS Code Extension Publishing
|
||||
- **Scopes**: Leave default (full access)
|
||||
5. Copy the token and add it to GitHub Secrets as `OVSX_PAT`
|
||||
|
||||
### `GITHUB_TOKEN` (automatically provided)
|
||||
This is automatically available in GitHub Actions - no setup required.
|
||||
|
||||
## 🚀 Publishing Process
|
||||
|
||||
### Automatic Publishing (Recommended)
|
||||
1. **Make changes** to the extension code
|
||||
2. **Update version** in both:
|
||||
- `apps/extension/package.json`
|
||||
- `apps/extension/package.publish.json`
|
||||
3. **Commit and push** to `main` branch
|
||||
4. **CI automatically triggers** and publishes if version changed
|
||||
|
||||
### Manual Publishing
|
||||
1. Go to **Actions** tab in GitHub
|
||||
2. Select **Extension Release** workflow
|
||||
3. Click **Run workflow**
|
||||
4. Check **"Force publish even without version changes"** if needed
|
||||
5. Click **Run workflow**
|
||||
|
||||
## 📋 Version Management
|
||||
|
||||
### Version Sync Checklist
|
||||
When updating the extension version, ensure these fields match in both files:
|
||||
|
||||
**`package.json` and `package.publish.json`:**
|
||||
```json
|
||||
{
|
||||
"version": "1.0.2", // ⚠️ MUST MATCH
|
||||
"publisher": "DavidMaliglowka", // ⚠️ MUST MATCH
|
||||
"displayName": "Task Master Kanban", // ⚠️ MUST MATCH
|
||||
"description": "...", // ⚠️ MUST MATCH
|
||||
"engines": { "vscode": "^1.93.0" }, // ⚠️ MUST MATCH
|
||||
"categories": [...], // ⚠️ MUST MATCH
|
||||
"contributes": { ... } // ⚠️ MUST MATCH
|
||||
}
|
||||
```
|
||||
|
||||
### Version Detection Logic
|
||||
The release workflow only publishes when:
|
||||
- Extension files changed in the push, AND
|
||||
- Version field changed in `package.json` or `package.publish.json`
|
||||
|
||||
## 🔍 Monitoring Builds
|
||||
|
||||
### CI Status
|
||||
- **Green ✅**: Extension builds and tests successfully
|
||||
- **Red ❌**: Build/test failures - check logs for details
|
||||
- **Yellow 🟡**: Partial success - some jobs may have warnings
|
||||
|
||||
### Release Status
|
||||
- **Published 🎉**: Extension live on VS Code Marketplace
|
||||
- **Skipped ℹ️**: No version changes detected
|
||||
- **Failed ❌**: Check logs - often missing secrets or build issues
|
||||
|
||||
### Artifacts
|
||||
Both workflows upload artifacts that you can download:
|
||||
- **CI**: Test results, built files, and VSIX package
|
||||
- **Release**: Final VSIX package and build artifacts (90-day retention)
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"VSCE_PAT is not set" Error**
|
||||
- Ensure `VSCE_PAT` secret is added to repository
|
||||
- Check token hasn't expired
|
||||
- Verify token has Marketplace > Manage permissions
|
||||
|
||||
**"OVSX_PAT is not set" Error**
|
||||
- Ensure `OVSX_PAT` secret is added to repository
|
||||
- Check token hasn't expired
|
||||
- Verify you're signed in to Open VSX Registry with GitHub
|
||||
|
||||
**"Version not changed" Skipped Release**
|
||||
- Update version in both `package.json` AND `package.publish.json`
|
||||
- Ensure files are committed and pushed
|
||||
- Use manual trigger with force publish if needed
|
||||
|
||||
**Build Failures**
|
||||
- Check extension code compiles locally: `cd apps/extension && pnpm run build`
|
||||
- Verify tests pass locally: `pnpm run test`
|
||||
- Check for TypeScript errors: `pnpm run check-types`
|
||||
|
||||
**Packaging Failures**
|
||||
- Ensure clean package builds: `pnpm run package`
|
||||
- Check vsix-build structure is correct
|
||||
- Verify package.publish.json has correct fields
|
||||
|
||||
## 📁 File Structure Impact
|
||||
|
||||
The CI workflows respect the 3-file packaging system:
|
||||
- **Development**: Uses `package.json` for dependencies and scripts
|
||||
- **Release**: Uses `package.publish.json` for clean marketplace package
|
||||
- **Build**: Uses `package.mjs` to create `vsix-build/` for final packaging
|
||||
|
||||
This ensures clean, conflict-free publishing to both VS Code Marketplace and Open VSX Registry! 🚀
|
||||
|
||||
## 🌍 **Dual Registry Publishing**
|
||||
|
||||
Your extension will be automatically published to both:
|
||||
- **VS Code Marketplace** - For official VS Code users
|
||||
- **Open VSX Registry** - For Cursor, Windsurf, VSCodium, Gitpod, Eclipse Theia, and other compatible editors
|
||||
177
apps/extension/docs/extension-development-guide.md
Normal file
177
apps/extension/docs/extension-development-guide.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# VS Code Extension Development Guide
|
||||
|
||||
## 📁 File Structure Overview
|
||||
|
||||
This VS Code extension uses a **3-file packaging system** to avoid dependency conflicts during publishing:
|
||||
|
||||
```
|
||||
apps/extension/
|
||||
├── package.json # Development configuration
|
||||
├── package.publish.json # Clean publishing configuration
|
||||
├── package.mjs # Build script for packaging
|
||||
├── .vscodeignore # Files to exclude from extension package
|
||||
└── vsix-build/ # Generated clean package directory
|
||||
```
|
||||
|
||||
## 📋 File Purposes
|
||||
|
||||
### `package.json` (Development)
|
||||
- **Purpose**: Development environment with all build tools
|
||||
- **Contains**:
|
||||
- All `devDependencies` needed for building
|
||||
- Development scripts (`build`, `watch`, `lint`, etc.)
|
||||
- Development package name: `"taskr"`
|
||||
- **Used for**: Local development, building, testing
|
||||
|
||||
### `package.publish.json` (Publishing)
|
||||
- **Purpose**: Clean distribution version for VS Code Marketplace
|
||||
- **Contains**:
|
||||
- **No devDependencies** (avoids dependency conflicts)
|
||||
- Publishing metadata (`keywords`, `repository`, `categories`)
|
||||
- Marketplace package name: `"taskr-kanban"`
|
||||
- VS Code extension configuration
|
||||
- **Used for**: Final extension packaging
|
||||
|
||||
### `package.mjs` (Build Script)
|
||||
- **Purpose**: Creates clean package for distribution
|
||||
- **Process**:
|
||||
1. Builds the extension (`build:js` + `build:css`)
|
||||
2. Creates clean `vsix-build/` directory
|
||||
3. Copies only essential files (no source code)
|
||||
4. Renames `package.publish.json` → `package.json`
|
||||
5. Ready for `vsce package`
|
||||
|
||||
## 🚀 Development Workflow
|
||||
|
||||
### Local Development
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development with hot reload
|
||||
pnpm run watch
|
||||
|
||||
# Run just JavaScript build
|
||||
pnpm run build:js
|
||||
|
||||
# Run just CSS build
|
||||
pnpm run build:css
|
||||
|
||||
# Full production build
|
||||
pnpm run build
|
||||
|
||||
# Type checking
|
||||
pnpm run check-types
|
||||
|
||||
# Linting
|
||||
pnpm run lint
|
||||
```
|
||||
|
||||
### Testing in VS Code
|
||||
1. Press `F5` in VS Code to launch Extension Development Host
|
||||
2. Test your extension functionality in the new window
|
||||
3. Use `Developer: Reload Window` to reload after changes
|
||||
|
||||
## 📦 Production Packaging
|
||||
|
||||
### Step 1: Build Clean Package
|
||||
```bash
|
||||
pnpm run package
|
||||
```
|
||||
This creates `vsix-build/` with clean distribution files.
|
||||
|
||||
### Step 2: Create VSIX
|
||||
```bash
|
||||
cd vsix-build
|
||||
pnpm exec vsce package --no-dependencies
|
||||
```
|
||||
Creates: `taskr-kanban-1.0.1.vsix`
|
||||
|
||||
### Alternative: One Command
|
||||
```bash
|
||||
pnpm run package && cd vsix-build && pnpm exec vsce package --no-dependencies
|
||||
```
|
||||
|
||||
## 🔄 Keeping Files in Sync
|
||||
|
||||
### Critical Fields to Sync Between Files
|
||||
|
||||
When updating extension metadata, ensure these fields match between `package.json` and `package.publish.json`:
|
||||
|
||||
#### Version & Identity
|
||||
```json
|
||||
{
|
||||
"version": "1.0.1", // ⚠️ MUST MATCH
|
||||
"publisher": "DavidMaliglowka", // ⚠️ MUST MATCH
|
||||
"displayName": "taskr: Task Master Kanban", // ⚠️ MUST MATCH
|
||||
"description": "A visual Kanban board...", // ⚠️ MUST MATCH
|
||||
}
|
||||
```
|
||||
|
||||
#### VS Code Configuration
|
||||
```json
|
||||
{
|
||||
"engines": { "vscode": "^1.101.0" }, // ⚠️ MUST MATCH
|
||||
"categories": [...], // ⚠️ MUST MATCH
|
||||
"activationEvents": [...], // ⚠️ MUST MATCH
|
||||
"main": "./dist/extension.js", // ⚠️ MUST MATCH
|
||||
"contributes": { ... } // ⚠️ MUST MATCH EXACTLY
|
||||
}
|
||||
```
|
||||
|
||||
### Key Differences (Should NOT Match)
|
||||
```json
|
||||
// package.json (dev)
|
||||
{
|
||||
"name": "taskr", // ✅ Short dev name
|
||||
"devDependencies": { ... }, // ✅ Only in dev file
|
||||
"scripts": { ... } // ✅ Build scripts
|
||||
}
|
||||
|
||||
// package.publish.json (publishing)
|
||||
{
|
||||
"name": "taskr-kanban", // ✅ Marketplace name
|
||||
"keywords": [...], // ✅ Only in publish file
|
||||
"repository": "https://github.com/...", // ✅ Only in publish file
|
||||
// NO devDependencies // ✅ Clean for publishing
|
||||
// NO build scripts // ✅ Not needed in package
|
||||
}
|
||||
```
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Dependency Conflicts
|
||||
**Problem**: `vsce package` fails with missing dependencies
|
||||
**Solution**: Use the 3-file system - never run `vsce package` from root
|
||||
|
||||
### Build Failures
|
||||
**Problem**: Extension not working after build
|
||||
**Check**:
|
||||
1. All files copied to `vsix-build/dist/`
|
||||
2. `package.publish.json` has correct `main` field
|
||||
3. VS Code engine version compatibility
|
||||
|
||||
### Sync Issues
|
||||
**Problem**: Extension works locally but fails when packaged
|
||||
**Check**: Ensure critical fields are synced between package files
|
||||
|
||||
## 📝 Version Release Checklist
|
||||
|
||||
1. **Update version** in both `package.json` and `package.publish.json`
|
||||
2. **Update CHANGELOG.md** with new features/fixes
|
||||
3. **Test locally** with `F5` in VS Code
|
||||
4. **Build clean package**: `pnpm run package`
|
||||
5. **Test packaged extension**: Install `.vsix` file
|
||||
6. **Publish**: Upload to marketplace or distribute `.vsix`
|
||||
|
||||
## 🎯 Why This System?
|
||||
|
||||
- **Avoids dependency conflicts**: VS Code doesn't see dev dependencies
|
||||
- **Clean distribution**: Only essential files in final package
|
||||
- **Faster packaging**: No dependency resolution during `vsce package`
|
||||
- **Maintainable**: Clear separation of dev vs. production configs
|
||||
- **Reliable**: Consistent, conflict-free packaging process
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Always use `pnpm run package` → `cd vsix-build` → `vsce package --no-dependencies` for production builds! 🚀
|
||||
Reference in New Issue
Block a user