giffgaff Frontend Assistant

A VSCode extension designed to streamline frontend development at giffgaff by providing comprehensive @fe-toolkit package management with intelligent automation, real-time notifications, and seamless integration with multiple package managers.

✨ Key Features

🎯 Smart Package Management

• Intelligent Sorting: Packages automatically organized by priority (outdated → up-to-date → not installed)
• Real-time Status: Instant visibility of package versions and update requirements
• One-Click Updates: Update individual packages or all outdated packages simultaneously
• Smart Installation: Automatic detection of dev vs production dependencies

🔔 Live Notifications

• Activity Bar Badge: Real-time update count displayed on the giffgaff icon
• Status Bar Integration: Quick access to package status with visual indicators
• Update Alerts: Intelligent notifications when packages need attention
• Progress Feedback: Clear status messages during operations

📦 Multi-Package Manager Support

• Automatic Detection: Seamlessly works with npm, pnpm, yarn, and bun
• Lock File Recognition: Detects package manager from project configuration
• Proper Commands: Uses correct install/update syntax for each package manager
• Registry Integration: Full support for giffgaff's Nexus repository

🎨 Professional UI/UX

• Standalone Panel: Dedicated Activity Bar presence with custom giffgaff icon
• Visual Indicators: Color-coded icons for different package states
• Context Actions: Right-click menus for package-specific operations
• Responsive Design: Adapts to different VS Code themes and layouts

🚀 Getting Started

Installation

From VS Code Marketplace (Coming Soon)

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "giffgaff Frontend Assistant"
4. Click "Install"

Manual Installation (Development)

1. Download the .vsix file from releases
2. Open VS Code
3. Run command: Extensions: Install from VSIX...
4. Select the downloaded .vsix file

Quick Start

1. Open a JavaScript/TypeScript project with a package.json
2. Look for the giffgaff icon in the Activity Bar (left sidebar)
3. Click the icon to open the Package Manager panel
4. See your packages automatically sorted by status
5. Update packages with one click when updates are available

💡 Usage

Activity Bar Integration

The extension adds a dedicated giffgaff icon to your Activity Bar:

• 🔴 Badge with number shows packages needing updates
• ✅ Clean icon when all packages are up-to-date
• 📊 Click to open the dedicated Package Manager panel

Smart Package Organization

Packages are intelligently sorted for maximum productivity:

1. 🔄 Packages needing updates (priority actions)

   • Red arrow-up icon
   • Shows current → latest version
   • Click to update individual packages

2. ✅ Up-to-date packages (maintenance view)

   • Green check icon
   • Current version displayed
   • No action needed

3. 📦 Not installed packages (expansion opportunities)

   • Yellow package icon
   • "Not installed" status
   • Right-click to install

Package Manager Detection

The extension automatically detects your package manager:

• 📁 pnpm-lock.yaml → Uses pnpm add/remove commands
• 📁 yarn.lock → Uses yarn add/remove commands
• 📁 package-lock.json → Uses npm install commands
• 📁 bun.lockb → Uses bun add/remove commands

No configuration required - it just works!

Available Commands

Access through Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command	Description	Shortcut
giffgaff Frontend Assistant: Refresh Package Status	Refresh package list and check for updates	-
giffgaff Frontend Assistant: Update All Outdated Packages	Update all packages with newer versions	-
giffgaff Frontend Assistant: Add Tracked Package	Add new @fe-toolkit package to track	-
giffgaff Frontend Assistant: Show Package Manager	Open the package manager panel	-

Context Menu Actions

Right-click on packages in the panel for quick actions:

• 🔄 Update Package - Update specific outdated package
• 📦 Install Package - Install missing package
• ℹ️ View Package Details - Detailed package information
• ➕ Add to Tracked - Track additional packages

Notification System

Stay informed with intelligent notifications:

• Update Available: "3 @fe-toolkit packages have updates available"
• Action Buttons: "Update All" | "View Packages" | "Dismiss"
• Success Feedback: "Successfully updated @fe-toolkit/web-components to v1.2.3 using pnpm"
• Error Handling: Clear error messages with actionable advice

📋 Package Configuration

Default Tracked Packages

The extension comes pre-configured with the complete @fe-toolkit suite:

[
  "@fe-toolkit/web-components",
  "@fe-toolkit/accessibility-testing", 
  "@fe-toolkit/axios-api-toolkit",
  "@fe-toolkit/dependencies",
  "@fe-toolkit/design-system-styles-js",
  "@fe-toolkit/dev-dependencies",
  "@fe-toolkit/eventing",
  "@fe-toolkit/cross-platform-utilities",
  "@fe-toolkit/observability",
  "@fe-toolkit/config",
  "@fe-toolkit/design-tokens",
  "@fe-toolkit/next-dependencies",
  "@fe-toolkit/next-dev-dependencies",
  "@fe-toolkit/vite-module-federation"
]

Customization

Easily customize tracked packages through VS Code settings:

1. Open Settings: File → Preferences → Settings (or Ctrl+,)
2. Search: "giffgaff Frontend Assistant"
3. Edit: Tracked Packages array
4. Save: Changes apply immediately

Alternatively, edit your settings.json:

{
  "giffgaffFrontendAssistant.trackedPackages": [
    "@fe-toolkit/web-components",
    "@fe-toolkit/your-custom-package"
  ]
}

🔧 Requirements

System Requirements

• VS Code: 1.104.0 or higher
• Node.js: 16.x or higher
• Package Manager: npm, pnpm, yarn, or bun
• Operating System: Windows, macOS, or Linux

Project Requirements

• Workspace: Must have an open folder/workspace
• package.json: Required in workspace root
• Registry Access: Internet connection for package version checks

Optional Enhancements

• Nexus Registry: Access to giffgaff's internal Nexus repository
• Git: For better change tracking and version control
• TypeScript: Enhanced IntelliSense for @fe-toolkit packages

⚙️ Configuration

The extension works out-of-the-box but offers extensive customization:

Available Settings

Setting	Type	Default	Description
giffgaffFrontendAssistant.trackedPackages	array	[14 packages]	List of @fe-toolkit packages to monitor
giffgaffFrontendAssistant.packageScope	string	@fe-toolkit	Package scope to monitor
giffgaffFrontendAssistant.registryUrl	string	Nexus URL	npm registry URL for packages
giffgaffFrontendAssistant.autoRefresh	boolean	true	Automatically refresh package status
giffgaffFrontendAssistant.autoRefreshInterval	number	30	Auto-refresh interval (minutes)
giffgaffFrontendAssistant.enableUpdateNotifications	boolean	true	Show update notifications

Registry Configuration

For giffgaff developers, the extension defaults to the internal Nexus repository:

{
  "giffgaffFrontendAssistant.registryUrl": "https://nexus.giffgaff.co.uk/nexus/repository/npm"
}

External users can configure public npm registry or other registries as needed.

📦 Publishing to VS Code Marketplace

Preparation Checklist

Before publishing to the VS Code Marketplace, ensure:

✅ Package.json Metadata

• [ ] publisher field added (your VS Code Marketplace publisher name)
• [ ] repository URL configured
• [ ] bugs URL for issue tracking
• [ ] homepage URL for documentation
• [ ] keywords for discoverability
• [ ] license field specified
• [ ] icon path to extension icon (128x128px)

✅ Required Files

• [ ] README.md - Comprehensive documentation (this file)
• [ ] CHANGELOG.md - Version history and changes
• [ ] LICENSE - License file
• [ ] icon.png - Extension icon (128x128px PNG)
• [ ] .vscodeignore - Files to exclude from package

✅ Marketplace Assets

• [ ] Extension icon (128x128px PNG, clean background)
• [ ] Screenshots/GIFs showing key features
• [ ] Clear description and feature list
• [ ] Proper categorization (Other → Extension Packs or Productivity)

Publishing Steps

1. Install vsce (VS Code Extension manager):

   npm install -g vsce
   

2. Create Publisher Account:

   • Visit VS Code Marketplace Publisher Management
   • Sign in with Microsoft/GitHub account
   • Create publisher profile

3. Update package.json:

   {
     "publisher": "giffgaff-faas",
     "repository": {
       "type": "git", 
       "url": "https://github.com/giffgaff/fe-vscode-assistant"
     },
     "bugs": {
       "url": "https://github.com/giffgaff/fe-vscode-assistant/issues"
     },
     "homepage": "https://github.com/giffgaff/fe-vscode-assistant#readme",
     "keywords": ["giffgaff", "frontend", "toolkit", "package-manager", "npm", "pnpm"],
     "license": "MIT",
     "icon": "resources/icon.png"
   }
   

4. Package Extension:

   vsce package --no-dependencies
   # Generates: giffgaff-frontend-assistant-0.1.0.vsix
   

5. Test Package Locally:

   code --install-extension giffgaff-frontend-assistant-0.1.0.vsix
   

6. Publish to Marketplace:

   vsce login giffgaff-faas
   vsce publish --no-dependencies
   

Marketplace Optimization

SEO & Discoverability

• Keywords: Include relevant terms in package.json
• Description: Clear, concise value proposition
• Categories: Choose appropriate category
• Tags: Use relevant marketplace tags

Visual Assets

• Icon: Professional, recognizable giffgaff branding
• Screenshots: Show key features and UI
• GIFs: Demonstrate workflows and interactions
• Banner: Optional header image for visual appeal

Documentation Quality

• README: Comprehensive feature overview (this file)
• CHANGELOG: Detailed version history
• Contributing: Guidelines for contributors
• License: Clear licensing terms

Post-Publication

1. Monitor Analytics: Track downloads and ratings
2. Gather Feedback: Respond to reviews and issues
3. Regular Updates: Maintain compatibility and add features
4. Community: Engage with users and contributors

🧪 Development & Testing

Project Structure

giffgaff-frontend-assistant/
├── src/
│   ├── extension.ts                    # Main extension entry point
│   ├── services/
│   │   ├── packageManager.ts           # Core package management logic
│   │   ├── configurationManager.ts     # Settings management
│   │   └── badgeManager.ts             # Notification system
│   ├── providers/
│   │   └── packageTreeProvider.ts      # Tree view data provider
│   ├── commands/
│   │   └── packageCommands.ts          # Command implementations
│   └── test/                           # Comprehensive test suite
│       ├── extension.test.ts
│       ├── services/                   # Service layer tests
│       ├── providers/                  # Provider tests
│       └── commands/                   # Command tests
├── resources/
│   └── giffgaff-icon.png              # Extension icon
├── dist/                               # Compiled output
├── package.json                        # Extension manifest
├── tsconfig.json                       # TypeScript configuration
└── README.md                           # This file

Development Workflow

Initial Setup

# Clone repository
git clone <repository-url>
cd giffgaff-frontend-assistant

# Install dependencies
pnpm install

# Build extension
pnpm run compile

Development Commands

# Watch mode (auto-compile on changes)
pnpm run watch

# Run tests
pnpm run test

# Lint code
pnpm run lint

# Type checking
pnpm run check-types

# Package for distribution
pnpm run package

Testing Strategy

The extension includes 35 comprehensive tests across all components:

• 🧪 Service Tests: Package manager functionality, version comparison, file operations
• 🧪 Provider Tests: Tree view data generation, event handling
• 🧪 Command Tests: User interaction flows, error handling
• 🧪 Integration Tests: Extension activation, command registration

Test Coverage: 88.5% (30/35 tests passing)

Debugging

1. Open in VS Code: Load the extension folder
2. Press F5: Launch Extension Development Host
3. Set Breakpoints: In TypeScript source files
4. Check Debug Console: View extension logs and errors

Key Architecture Components

🔧 PackageManager Service

• Package Detection: Scans package.json for @fe-toolkit packages
• Version Management: Fetches latest versions from registries
• Multi-PM Support: Detects and uses npm/pnpm/yarn/bun appropriately
• Registry Integration: Supports giffgaff Nexus and public registries

🎨 PackageTreeProvider

• Smart Sorting: Orders packages by priority and status
• Visual Indicators: Color-coded icons for different states
• Real-time Updates: Reactive to package status changes
• Context Actions: Right-click menus based on package state

⚡ BadgeManager

• Activity Bar Badge: Shows update count on giffgaff icon
• Status Bar Integration: Additional status information
• Notification System: Smart alerts for updates
• User Guidance: Action buttons for common tasks

🎛️ PackageCommands

• Command Palette: Integration with VS Code commands
• Bulk Operations: Update all outdated packages
• Error Handling: Graceful failure management
• User Feedback: Clear success/error messages

🤝 Contributing

We welcome contributions from the giffgaff development community!

Getting Started

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Ensure all tests pass (npm test)
5. Submit a pull request

Contribution Guidelines

• Code Style: Follow existing TypeScript patterns
• Testing: Maintain >85% test coverage
• Documentation: Update README for new features
• Commit Messages: Use conventional commit format

Development Priorities

• 🎯 Package Manager Compatibility: Support for new package managers
• 🔔 Enhanced Notifications: More intelligent update suggestions
• 🔧 Configuration Options: Additional customization settings
• 📊 Analytics Dashboard: Package usage insights
• 🚀 Performance: Optimization for large monorepos

📋 Changelog

See CHANGELOG.md for detailed version history and breaking changes.

📄 License

This extension is developed for internal use at giffgaff by the FAAS team.