Alterpspective ShareDo VS Code Extension
🚀 Current Project Status
This extension is being transformed into the official Alterpspective ShareDo release!
Implementation Plan
A comprehensive 5-week implementation plan is now active. See:
Timeline to v1.0.0 Launch
Week 1-2: Foundation & Core Fixes (Testing, DOCX validation, legacy cleanup)
Week 3: Extension Rebranding (Alterpspective identity)
Week 4: Quality Assurance (200+ tests, 80% coverage)
Week 5: Marketplace Publishing (Live on VS Code Marketplace)
Key Improvements
- ✅ DOCX Fix Complete - Files now open correctly in Word, LibreOffice, Google Docs
- ✅ Clean Architecture - No backward compatibility constraints
- 🚧 Fresh Marketplace Release - New publisher, new extension ID
- 🚧 Production-Ready Quality - 80% test coverage, CI/CD pipeline
- 🚧 Professional Documentation - Complete user guides and API docs
⚠️ Important Disclaimer
This is a community-developed extension for ShareDo, soon to be officially released as Alterpspective ShareDo.
CURRENT STATUS: PRE-RELEASE DEVELOPMENT
- Extension is under active development for v1.0.0 release
- Not yet published to VS Code Marketplace
- Use at your own risk during development phase
- Production release expected Week 5 (see timeline above)
For production environments, please wait for the official v1.0.0 marketplace release.
Features
Current Version (v0.12.2):
🚀 Unified HLD System (NEW!)
- MAJOR UPGRADE! Command consolidation: 16 commands reduced to 3 unified commands
- NEW!
Generate HLD Document - Universal generator with format/stakeholder selection
- NEW!
Preview HLD Document - Enhanced preview with live updates
- NEW!
Configure HLD Settings - Unified configuration management
- IMPROVED! 80% reduction in code duplication with enhanced performance
- MAINTAINED! Full backward compatibility with legacy commands
📋 HLD Generation Features
- Multiple Formats: Markdown, HTML, and DOCX output
- Stakeholder Views: Business Analyst, System Admin, Support, Trainer, and Full documentation
- Batch Processing: Generate HLD for multiple work types simultaneously
- Template System: Role-based filtering and custom templates
- Smart Configuration: Intelligent dependency analysis and cross-references
🎨 Enhanced User Experience
- NEW! Visual format selection with icons and descriptions
- NEW! Progress tracking for complex operations
- NEW! Contextual error messages with suggested solutions
- NEW! Status bar integration with real-time feedback
- IMPROVED! Setup wizard for first-time users
📁 File Management
- Upload and download IDE files (Cross-platform Windows/Mac/Linux support)
- Batch file operations with progress tracking
- File conflict resolution and validation
- Enhanced error handling with context-aware messages
🔐 Work-Type Permission Management
- Delete permissions
- Apply to ALL derived types
- Bulk permission operations
🎯 Work-Type Role Permissions
- Delete role permissions
- Apply to all derived types
- Copy permissions between work types
🔧 Developer Experience
- NEW! Production-grade structured logging for AI-assisted debugging
- Correlation IDs for end-to-end operation tracing
- Persistent JSONL logs (survives VS Code restarts)
- Export logs for AI analysis with configurable time ranges
- Windows-specific debugging context (paths, environment, file system)
- Four new commands: Export, Show, Statistics, Open Directory
- See LOGGING-QUICKSTART.md for details
- Enhanced error handling with context-aware messages
- Cross-platform path handling utilities
- Better debugging information with caller context
HLD Command Migration Guide
The extension now features a simplified, unified command structure! All legacy HLD commands continue to work but are now marked as "(Legacy)" for easy identification.
New Unified Commands:
🚀 Generate HLD Document (sharedo.hld.generate)
- Replaces 10+ individual generation commands
- Interactive format selection (Markdown, HTML, DOCX)
- Stakeholder role filtering (Business Analyst, System Admin, etc.)
- Batch processing support
🔍 Preview HLD Document (sharedo.hld.preview)
- Replaces preview and Playwright preview commands
- Live preview with format switching
- Auto-refresh capabilities
⚙️ Configure HLD Settings (sharedo.hld.configure)
- Replaces configuration, cache, and performance commands
- Unified settings management
- Performance monitoring dashboard
Legacy Command Compatibility:
All existing commands continue to work and are automatically routed to the new unified system:
Generate Business Analyst HLD (Legacy) → Routes to unified generator with BA presetGenerate System Admin HLD (Legacy) → Routes to unified generator with SysAdmin presetClear HLD Cache (Legacy) → Routes to unified configuration cache management- And all other legacy commands maintain full functionality
Recommendation: Start using the new unified commands for the best experience, while legacy commands remain available for backward compatibility.
Requirements
- VS Code: Version 1.76.0 or higher
- ShareDo Server: Access to a ShareDo platform server
- Node.js: v18.x or higher (for development)
- npm: v8.x or higher (for development)
Windows Development Setup
Building native modules (like canvas) on Windows requires additional tools. Follow these steps:
Prerequisites
Install Visual Studio Build Tools (one of these options):
Install Python 3.x (if not already installed):
- Download from python.org
- Ensure "Add Python to PATH" is checked during installation
Configure npm to use the correct Visual Studio version (if needed):
npm config set msvs_version 2022
Run npm install:
npm install
Note: If you encounter build errors with the canvas package, see the node-canvas Windows installation guide.
Windows Developer Scripts
PowerShell equivalents of the bash development scripts are provided:
| Bash Script (Mac/Linux) |
PowerShell Script (Windows) |
Description |
./run-debug.sh |
.\run-debug.ps1 |
Launch extension in debug mode |
./debug-extension.sh |
.\debug-extension.ps1 |
Debug with log capture |
./test-extension.sh |
.\test-extension.ps1 |
Compile and test extension |
Usage:
# Run from project root
.\run-debug.ps1
# Or with execution policy bypass (if needed)
powershell -ExecutionPolicy Bypass -File .\run-debug.ps1
The extension uses cross-platform path utilities (src/Utilities/platformPaths.ts) to ensure consistent behavior across Windows, macOS, and Linux. When developing:
- Always use
path.join() instead of string concatenation for paths
- Use
os.tmpdir() instead of hardcoded /tmp
- Use forward slashes in glob patterns (VS Code expects this even on Windows)
Known Issues
Fixed in v0.8.0:
- ✅ Windows path handling issues when publishing files to ShareDo
- ✅ Cross-platform compatibility improvements
- ✅ Enhanced error logging with caller information
Current Issues:
- Some UI elements may not scale properly on high-DPI displays
- Large file uploads may timeout on slower connections
Pre-Release, please raise issue here:
https://github.com/Alter-Igor/sharedo-vscode-extension/issues
Compatibility
- VS Code: 1.76.0 or higher
- Operating Systems: Windows, macOS, Linux
- ShareDo: Compatible with ShareDo platform servers
Installation
From VS Code Marketplace
- Open VS Code
- Go to Extensions (
Ctrl+Shift+X / Cmd+Shift+X)
- Search for "ShareDo VSCode Extension"
- Click Install
- New! Run the Setup Wizard: Open Command Palette (
Ctrl+Shift+P / Cmd+Shift+P) and search for "ShareDo: Setup Wizard"
From VSIX File (Manual Installation)
- Download the
.vsix file from GitHub Releases
- Open VS Code
- Go to Extensions (
Ctrl+Shift+X / Cmd+Shift+X)
- Click the
... menu at the top of the Extensions panel
- Select "Install from VSIX..."
- Browse to the downloaded
.vsix file and select it
Quick Start
- Use the Setup Wizard (
Ctrl+Shift+P → "ShareDo: Setup Wizard") for guided configuration
- Or manually connect using "ShareDo: Connect to ShareDo Server"
- Your ShareDo resources will appear in the Explorer panel under "ShareDo Servers"
User Experience Improvements
v0.8.1+ Enhancements:
- 🧙♂️ Setup Wizard: Guided first-time setup with validation and testing
- 📊 Progress Indicators: Visual feedback for file uploads, downloads, and API operations
- 💬 Smart Notifications: Context-aware messages with suggested actions
- 🔗 Connection Status: Real-time connection status in the status bar
- 📈 Operation Results: Detailed success/failure reporting for batch operations
- 🛠️ Better Error Messages: User-friendly errors with troubleshooting suggestions
- ✅ Bug Fixes: Resolved extension activation issues and command conflicts
Release Notes
[0.8.0] - 2025-07-25
Added
- Enhanced error handling and logging throughout codebase
- Cross-platform path handling for Windows/Mac/Linux compatibility
- Better debugging information with caller context
Fixed
- Windows file path issues when publishing to ShareDo servers
- Malformed URLs due to backslash/forward slash path differences
- URL encoding for special characters in file paths
Changed
- Improved logging format for better traceability
- Standardized path handling across all file operations
Enjoy!
