Just for Fun: Building a Gnome Extension with Spec-Driven Development and Kiro

# Design Document

## Overview

Gnome Browser Switcher is a lightweight Gnome Shell extension that provides a quick way to switch the default browser through the system panel. The extension uses standard Gnome Shell APIs for panel integration and GIO/GSettings for managing system browser settings.

**Design Principles:**
- **Simplicity First**: Minimal code, no configuration UI, straightforward functionality
- **Zero External Dependencies**: Uses only APIs included in Gnome Shell
- **Standard Compliance**: Follows XDG Desktop Entry Specification for browser detection

The extension consists of three main components:
- **Indicator** - displays an icon in the system panel
- **Browser Manager** - detects and manages browsers
- **Menu Builder** - creates the popup menu with browsers

## Architecture

```mermaid
graph TD
A[Extension Entry Point] --> B[Browser Manager]
A --> C[Indicator]
C --> D[Menu Builder]
B --> D
B --> E[GSettings/xdg-settings]
D --> F[User Interaction]
F --> B
B --> C
```

### Technology Stack

- **Gnome Shell Extension API** - for panel integration
- **GJS (GNOME JavaScript)** - programming language
- **GIO/GSettings** - for system settings management
- **xdg-settings** - for changing the default browser
- **Desktop Entry Specification** - for detecting installed browsers

## Components and Interfaces

### 1. Extension Entry Point (extension.js)

Main extension file that manages the lifecycle.

**Responsibilities:**
- Initialize extension when Gnome Shell loads
- Create and destroy components
- Handle enable/disable events

**Key Methods:**
```javascript
function init() // Initialize metadata
function enable() // Activate extension
function disable() // Deactivate and cleanup resources
```

### 2. Browser Manager (browserManager.js)

Responsible for browser detection and default browser management.

**Responsibilities:**
- Scan system to detect installed browsers
- Get current default browser
- Change default browser
- Monitor default browser changes

**Key Methods:**
```javascript
getInstalledBrowsers() // Returns array of browser objects
getCurrentDefaultBrowser() // Returns ID of current browser
setDefaultBrowser(browserId) // Sets new default browser
watchDefaultBrowser(callback) // Subscribe to changes
```

**Browser Object Structure:**
```javascript
{
id: 'firefox.desktop',
name: 'Firefox',
icon: 'firefox',
execPath: '/usr/bin/firefox'
}
```

### 3. Indicator (indicator.js)

System tray component that displays the icon and menu.

**Responsibilities:**
- Display current browser icon in the panel
- Update icon when browser changes
- Show popup menu on click
- Position in system tray near clock

**Key Methods:**
```javascript
constructor(browserManager)
updateIcon(browserId) // Updates indicator icon
show() // Shows indicator in panel
hide() // Hides indicator
destroy() // Cleans up resources
```

**Integration:**
- Extends `PanelMenu.Button` from Gnome Shell
- Added to `Main.panel.addToStatusArea()`

### 4. Menu Builder (menuBuilder.js)

Creates and manages the popup menu with browsers.

**Responsibilities:**
- Build menu with browser list
- Display browser icons and names
- Mark current browser
- Handle user browser selection

**Key Methods:**
```javascript
buildMenu(browsers, currentBrowserId) // Creates menu
updateCurrentBrowser(browserId) // Updates marker
onBrowserSelected(callback) // Selection handler
```

**Menu Structure:**
- PopupMenuItem for each browser
- Icon + browser name
- Checkmark for current browser
- Separator between browsers (optional)

## Data Models

### Browser Information

Browsers are represented as objects with the following fields:

```javascript
{
id: String, // Desktop file ID (e.g., 'firefox.desktop')
name: String, // Display name (e.g., 'Mozilla Firefox')
icon: String, // Icon name or path (e.g., 'firefox')
execPath: String, // Path to executable
desktopFile: String // Full path to .desktop file
}
```

### Extension Metadata (metadata.json)

```json
{
"uuid": "browser-switcher@gnome-shell-extensions",
"name": "Browser Switcher",
"description": "Quick default browser switching",
"shell-version": ["45", "46"],
"url": "https://github.com/[username]/gnome-browser-switcher"
}
```

## Implementation Details

### Browser Detection

Browsers are detected by scanning `.desktop` files in standard directories:
- `/usr/share/applications/`
- `/usr/local/share/applications/`
- `~/.local/share/applications/`

Filtered by `WebBrowser` category in desktop entry.

### Default Browser Management

Two approaches are used:

1. **xdg-settings** (primary):
```bash
xdg-settings get default-web-browser # Get current
xdg-settings set default-web-browser firefox.desktop # Set
```

2. **GSettings** (fallback):
```javascript
const settings = new Gio.Settings({
schema_id: 'org.gnome.desktop.default-applications.web'
});
settings.get_string('browser');
settings.set_string('browser', 'firefox.desktop');
```

### Icon Management

Icons are loaded through Gnome Shell Icon Theme:

```javascript
const icon = new St.Icon({
gicon: Gio.icon_new_for_string(browser.icon),
style_class: 'system-status-icon'
});
```

Fallback to generic browser icon if browser icon is not found.

### File Structure

```
gnome-browser-switcher/
├── extension.js # Entry point (~150 lines)
├── metadata.json # Extension metadata
├── browserManager.js # Browser detection and management (~300 lines)
├── indicator.js # System tray indicator (~200 lines)
├── menuBuilder.js # Menu construction (~150 lines)
├── stylesheet.css # Minimal custom styling (optional, ~50 lines)
├── LICENSE # GPL-3.0 license
└── README.md # Installation and usage instructions
```

**Note**: No prefs.js or GSettings schemas - keeping it simple with zero configuration.

## Error Handling

### Browser Detection Failures

- **Scenario**: No browsers found
- **Handling**: Show "No browsers found" message in menu
- **Logging**: Log to journal via `log()`

### Default Browser Change Failures

- **Scenario**: xdg-settings returns error
- **Handling**:
1. Try fallback via GSettings
2. Show notification to user
3. Do not change indicator icon
- **Logging**: Log error details

### Permission Issues

- **Scenario**: Insufficient permissions to change settings
- **Handling**: Show notification with explanation
- **Recovery**: Do not block extension operation

### Icon Loading Failures

- **Scenario**: Browser icon not found
- **Handling**: Use fallback icon 'web-browser'
- **Logging**: Warning to journal

## Testing Strategy

### Manual Testing

1. **Installation Testing**
- Install extension via `gnome-extensions install`
- Verify appearance in extensions list
- Activate via `gnome-extensions enable`

2. **Functional Testing**
- Verify icon display in tray
- Open menu and verify browser list
- Switch browser and verify icon change
- Open link and verify correct browser opens

3. **Edge Cases**
- Test with one browser
- Test with no browsers (remove all)
- Test with custom .desktop files
- Gnome Shell reload (Alt+F2, 'r')

### Integration Testing

- Verify compatibility with different Gnome Shell versions (45, 46)
- Test on different distributions (Ubuntu, Fedora, Arch)
- Check conflicts with other extensions

### Performance Considerations

- Browser scanning performed once at initialization
- Browser list caching
- Minimal memory usage (single indicator)
- Fast icon updates (<1 second)

## Security Considerations

- Use only system APIs
- Validate desktop file paths
- Safe execution of xdg-settings via GLib.spawn_command_line_sync
- Do not execute arbitrary user commands

## Distribution and Publishing

### extensions.gnome.org Requirements

The extension will be published on extensions.gnome.org after local testing. Requirements:

1. **Metadata Completeness**
- Valid UUID format
- Accurate shell-version compatibility
- Clear description and name
- Valid URL to source repository

2. **Code Quality**
- No syntax errors
- Proper resource cleanup
- No memory leaks
- Follows Gnome Shell extension best practices

3. **Packaging**
- ZIP file with all required files
- Proper directory structure
- LICENSE file included
- README with clear instructions

4. **Testing**
- Tested on Gnome Shell 45 and 46
- No conflicts with common extensions
- Proper error handling
- Clean enable/disable cycle

### Publication Process

1. Complete local development and testing
2. Create ZIP package: `gnome-extensions pack`
3. Test installation from ZIP
4. Submit to extensions.gnome.org
5. Respond to review feedback
6. Publish approved extension

## Future Enhancements

**Note**: These are explicitly out of scope for v1.0 to maintain simplicity.

1. **Browser Profiles** - Support switching between profiles of same browser
2. **Keyboard Shortcuts** - Global shortcuts for quick switching
3. **Browser Filtering** - Hide specific browsers from the list
4. **Custom Icons** - User-provided icons for browsers

## Dependencies

### Runtime Dependencies

**Zero External Dependencies** - The extension uses only what's included in Gnome Shell:
- Gnome Shell 45+ (required)
- GJS (included in Gnome Shell)
- GIO/GLib (included in Gnome Shell)
- xdg-utils (typically pre-installed on all Gnome systems)

### Development Dependencies

- gnome-extensions CLI tool (for packaging and testing)
- Text editor (no build system required)

## Deployment

### Installation Methods

1. **Manual Installation**
```bash
mkdir -p ~/.local/share/gnome-shell/extensions/browser-switcher@gnome-shell-extensions
cp -r * ~/.local/share/gnome-shell/extensions/browser-switcher@gnome-shell-extensions/
gnome-extensions enable browser-switcher@gnome-shell-extensions
```

2. **ZIP Package**
```bash
zip -r browser-switcher@gnome-shell-extensions.zip *
gnome-extensions install browser-switcher@gnome-shell-extensions.zip
```

3. **GNOME Extensions Website** (future)
- Publish on extensions.gnome.org
- Automatic updates

### Uninstallation

```bash
gnome-extensions disable browser-switcher@gnome-shell-extensions
gnome-extensions uninstall browser-switcher@gnome-shell-extensions
```

# Implementation Plan

## Overview

This plan breaks down the implementation into discrete, incremental coding tasks. Each task builds on previous ones, ending with full integration. All tasks reference specific requirements from the requirements document.

## Tasks

- [x] 1. Set up project structure and metadata
- Create extension directory structure
- Write metadata.json with UUID, name, description, shell-version, and URL
- Create LICENSE file (GPL-3.0)
- Create basic README.md with installation instructions
- _Requirements: 6.2, 6.4, 6.5_

- [x] 2. Implement browser detection and management (browserManager.js)
- [x] 2.1 Create browser detection functionality
- Write function to scan standard XDG directories for .desktop files
- Parse .desktop files to extract browser information (id, name, icon, exec path)
- Filter applications by WebBrowser category
- Return array of browser objects
- _Requirements: 2.2, 5.2_

- [x] 2.2 Implement default browser getter
- Write function to get current default browser using xdg-settings
- Implement GSettings fallback if xdg-settings fails
- Parse and return browser ID
- _Requirements: 1.2, 4.4_

- [x] 2.3 Implement default browser setter
- Write function to set default browser using xdg-settings
- Implement GSettings fallback mechanism
- Add error handling and logging
- Return success/failure status
- _Requirements: 3.1, 3.4, 4.4, 4.5_

- [x] 2.4 Add browser change monitoring
- Implement file system watch on xdg-settings config
- Create callback mechanism for browser change events
- _Requirements: 1.3, 3.3_

- [x] 3. Create system panel indicator (indicator.js)
- [x] 3.1 Implement basic indicator class
- Extend PanelMenu.Button from Gnome Shell
- Create constructor that accepts browserManager
- Implement show() and hide() methods
- Implement destroy() method with resource cleanup
- _Requirements: 1.1, 4.2_

- [x] 3.2 Add icon display functionality
- Write updateIcon() method to load and display browser icon
- Use St.Icon with Gio.icon_new_for_string
- Apply 'system-status-icon' style class
- Implement fallback to 'web-browser' icon if browser icon not found
- _Requirements: 1.2, 1.4_

- [x] 3.3 Implement icon update on browser change
- Connect to browserManager change events
- Update icon within 1 second of browser change
- _Requirements: 1.3_

- [x] 4. Build popup menu (menuBuilder.js)
- [x] 4.1 Create menu builder class
- Implement buildMenu() method that accepts browsers array and current browser ID
- Create PopupMenuItem for each browser with icon and name
- Add visual indicator (checkmark) for current default browser
- _Requirements: 2.1, 2.3, 2.4_

- [x] 4.2 Implement browser selection handling
- Add click event handlers to menu items
- Call browserManager.setDefaultBrowser() on selection
- Close menu within 500ms after selection
- _Requirements: 3.1, 3.2_

- [x] 4.3 Add error handling for menu
- Display "No browsers found" message if browser list is empty
- Show error notification if browser switch fails
- _Requirements: 2.5, 3.4_

- [x] 4.4 Implement menu update on browser change
- Update checkmark position when default browser changes
- Refresh menu items if needed
- _Requirements: 3.3_

- [x] 5. Create extension entry point (extension.js)
- [x] 5.1 Implement extension lifecycle functions
- Write init() function for metadata initialization
- Write enable() function to create and activate components
- Write disable() function to cleanup and destroy components
- _Requirements: 4.1, 4.2_

- [x] 5.2 Wire components together
- Instantiate browserManager in enable()
- Create indicator with browserManager reference
- Connect indicator to menuBuilder
- Add indicator to Main.panel.addToStatusArea()
- _Requirements: 1.1, 4.1_

- [x] 5.3 Add error handling and logging
- Wrap initialization in try-catch blocks
- Log errors to system journal using log()
- Ensure graceful degradation on errors
- _Requirements: 4.5_

- [x] 6. Add optional styling (stylesheet.css)
- Create minimal CSS for menu styling if needed
- Ensure consistent look with Gnome Shell theme
- Keep file under 50 lines
- _Requirements: 1.4, 5.5_

- [x] 7. Create packaging and distribution files
- [x] 7.1 Test manual installation
- Test copying files to ~/.local/share/gnome-shell/extensions/
- Verify extension appears in gnome-extensions list
- Test enable/disable cycle
- _Requirements: 6.5_

- [x] 7.2 Create ZIP package for extensions.gnome.org
- Use gnome-extensions pack command
- Verify all required files are included
- Test installation from ZIP package
- _Requirements: 6.1, 6.2_

- [x] 7.3 Validate extension for submission
- Verify metadata.json completeness
- Check code for syntax errors
- Test on Gnome Shell 45+
- Verify resource cleanup on disable
- Ensure total codebase is under 1000 lines
- _Requirements: 4.3, 5.4, 5.5, 6.3_

## Notes

- Each task should be completed and tested before moving to the next
- All code should follow Gnome Shell extension best practices
- Keep code simple and readable - avoid over-engineering
- Test frequently with `gnome-extensions enable/disable` and Alt+F2, 'r' to reload
- Use `journalctl -f` to monitor logs during development