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

Thin client - Extensions contain no business logic; all state and decisions live in backend services
Consistent experience - Both plugins expose equivalent functionality despite different technology stacks
Non-blocking - All API calls are asynchronous; the IDE remains responsive during network operations
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]

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).
Data retrieval: Tree views and tool windows issue HTTP GET requests to the Orchestrator API on initial load and on manual/timed refresh.
Actions: Approve/reject/promote commands issue HTTP POST requests to the Orchestrator release control endpoints.
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

6.2 KiB Raw Blame History