118 lines
6.2 KiB
Markdown
118 lines
6.2 KiB
Markdown
# Extensions (IDE Plugins) Architecture
|
|
|
|
> Technical architecture for VS Code and JetBrains IDE plugins providing Stella Ops integration.
|
|
|
|
## Overview
|
|
|
|
The Extensions module consists of two independent IDE plugins that provide developer-facing integration with the Stella Ops platform. Both plugins are pure HTTP clients that consume the Orchestrator and Router APIs; they do not host any services, expose endpoints, or maintain local databases. Authentication is handled through OAuth tokens obtained from the Authority service.
|
|
|
|
## Design Principles
|
|
|
|
1. **Thin client** - Extensions contain no business logic; all state and decisions live in backend services
|
|
2. **Consistent experience** - Both plugins expose equivalent functionality despite different technology stacks
|
|
3. **Non-blocking** - All API calls are asynchronous; the IDE remains responsive during network operations
|
|
4. **Offline-tolerant** - Graceful degradation when the Stella Ops backend is unreachable
|
|
|
|
## Components
|
|
|
|
```
|
|
Extensions/
|
|
├── vscode-stella-ops/ # VS Code extension (TypeScript)
|
|
│ ├── src/
|
|
│ │ ├── extension.ts # Entry point and activation
|
|
│ │ ├── providers/
|
|
│ │ │ ├── ReleaseTreeProvider.ts # TreeView: releases
|
|
│ │ │ ├── EnvironmentTreeProvider.ts# TreeView: environments
|
|
│ │ │ └── CodeLensProvider.ts # CodeLens for stella.yaml
|
|
│ │ ├── commands/ # Command palette handlers
|
|
│ │ ├── views/
|
|
│ │ │ └── webview/ # Webview panels (detail views)
|
|
│ │ ├── statusbar/
|
|
│ │ │ └── StatusBarManager.ts # Status bar integration
|
|
│ │ └── api/
|
|
│ │ └── OrchestratorClient.ts # HTTP client for Orchestrator API
|
|
│ ├── package.json # Extension manifest
|
|
│ └── tsconfig.json
|
|
│
|
|
└── jetbrains-stella-ops/ # JetBrains plugin (Kotlin)
|
|
├── src/main/kotlin/
|
|
│ ├── toolwindow/
|
|
│ │ ├── ReleasesToolWindow.kt # Tool window: Releases tab
|
|
│ │ ├── EnvironmentsToolWindow.kt # Tool window: Environments tab
|
|
│ │ └── DeploymentsToolWindow.kt # Tool window: Deployments tab
|
|
│ ├── annotator/
|
|
│ │ └── StellaYamlAnnotator.kt # YAML file annotator
|
|
│ ├── actions/ # Action menu handlers
|
|
│ ├── statusbar/
|
|
│ │ └── StellaStatusBarWidget.kt # Status bar widget
|
|
│ └── api/
|
|
│ └── OrchestratorClient.kt # HTTP client for Orchestrator API
|
|
├── src/main/resources/
|
|
│ └── META-INF/plugin.xml # Plugin descriptor
|
|
└── build.gradle.kts
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
```
|
|
[Developer IDE] --> [Extension/Plugin]
|
|
│
|
|
├── GET /api/v1/releases/* ──────> [Orchestrator API]
|
|
├── GET /api/v1/environments/* ──> [Orchestrator API]
|
|
├── POST /api/v1/promotions/* ──-> [Orchestrator API]
|
|
└── POST /oauth/token ──────────-> [Authority]
|
|
```
|
|
|
|
1. **Authentication:** On activation, the extension initiates an OAuth device-code or browser-redirect flow against Authority. The obtained access token is stored in the IDE's secure credential store (VS Code `SecretStorage`, JetBrains `PasswordSafe`).
|
|
2. **Data retrieval:** Tree views and tool windows issue HTTP GET requests to the Orchestrator API on initial load and on manual/timed refresh.
|
|
3. **Actions:** Approve/reject/promote commands issue HTTP POST requests to the Orchestrator release control endpoints.
|
|
4. **Configuration validation:** The CodeLens provider (VS Code) and YAML annotator (JetBrains) parse `stella.yaml` files locally and highlight configuration issues inline.
|
|
|
|
## VS Code Extension Details
|
|
|
|
### Tree Views
|
|
- **Releases:** Hierarchical view of releases grouped by environment, showing status, version, and promotion eligibility
|
|
- **Environments:** Flat list of configured environments with health indicators
|
|
|
|
### CodeLens
|
|
- Inline annotations above `stella.yaml` entries showing the current deployment status of the referenced release
|
|
- Click-to-promote actions directly from the YAML file
|
|
|
|
### Status Bar
|
|
- Compact widget showing the number of pending promotions and overall platform health
|
|
|
|
### Webview Panels
|
|
- Detail panels for release timelines, evidence summaries, and deployment logs
|
|
|
|
## JetBrains Plugin Details
|
|
|
|
### Tool Windows
|
|
- **Releases tab:** Table view of all releases with sortable columns (version, environment, status, timestamp)
|
|
- **Environments tab:** Environment cards with health status and current deployments
|
|
- **Deployments tab:** Active and recent deployment history with log links
|
|
|
|
### YAML Annotator
|
|
- Real-time validation of `stella.yaml` files with gutter icons and tooltip messages for configuration issues
|
|
|
|
### Action Menus
|
|
- Context-sensitive actions (promote, approve, reject) available from tool window rows and editor context menus
|
|
|
|
## Security Considerations
|
|
|
|
- **Token storage:** OAuth tokens are stored exclusively in the IDE's built-in secure credential store; never persisted to disk in plaintext
|
|
- **Scope enforcement:** Extensions request only the scopes necessary for read operations and promotions (`release:read`, `release:promote`, `env:read`)
|
|
- **TLS enforcement:** All HTTP communication uses HTTPS; certificate validation is not bypassed
|
|
- **No secrets in configuration:** The `stella.yaml` file contains no credentials; integration secrets are managed by the Authority and Integrations modules
|
|
|
|
## Performance Characteristics
|
|
|
|
- Tree view refresh is debounced to avoid excessive API calls (default: 30-second minimum interval)
|
|
- API responses are cached locally with short TTL (60 seconds) to reduce latency on repeated navigation
|
|
- Webview panels and tool windows load data lazily on first open
|
|
|
|
## References
|
|
|
|
- [Module README](./README.md)
|
|
- [Orchestrator Architecture](../orchestrator/architecture.md)
|
|
- [Authority Architecture](../authority/architecture.md)
|