diff --git a/.clinerules/memory-bank.md b/.clinerules/memory-bank.md new file mode 100644 index 0000000..dd7e2f1 --- /dev/null +++ b/.clinerules/memory-bank.md @@ -0,0 +1,115 @@ +# Cline's Memory Bank + +I am Cline, an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional. + +## Memory Bank Structure + +The Memory Bank consists of core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy: + +flowchart TD + PB[projectbrief.md] --> PC[productContext.md] + PB --> SP[systemPatterns.md] + PB --> TC[techContext.md] + + PC --> AC[activeContext.md] + SP --> AC + TC --> AC + + AC --> P[progress.md] + +### Core Files (Required) +1. `projectbrief.md` + - Foundation document that shapes all other files + - Created at project start if it doesn't exist + - Defines core requirements and goals + - Source of truth for project scope + +2. `productContext.md` + - Why this project exists + - Problems it solves + - How it should work + - User experience goals + +3. `activeContext.md` + - Current work focus + - Recent changes + - Next steps + - Active decisions and considerations + - Important patterns and preferences + - Learnings and project insights + +4. `systemPatterns.md` + - System architecture + - Key technical decisions + - Design patterns in use + - Component relationships + - Critical implementation paths + +5. `techContext.md` + - Technologies used + - Development setup + - Technical constraints + - Dependencies + - Tool usage patterns + +6. `progress.md` + - What works + - What's left to build + - Current status + - Known issues + - Evolution of project decisions + +### Additional Context +Create additional files/folders within memory-bank/ when they help organize: +- Complex feature documentation +- Integration specifications +- API documentation +- Testing strategies +- Deployment procedures + +## Core Workflows + +### Plan Mode +flowchart TD + Start[Start] --> ReadFiles[Read Memory Bank] + ReadFiles --> CheckFiles{Files Complete?} + + CheckFiles -->|No| Plan[Create Plan] + Plan --> Document[Document in Chat] + + CheckFiles -->|Yes| Verify[Verify Context] + Verify --> Strategy[Develop Strategy] + Strategy --> Present[Present Approach] + +### Act Mode +flowchart TD + Start[Start] --> Context[Check Memory Bank] + Context --> Update[Update Documentation] + Update --> Execute[Execute Task] + Execute --> Document[Document Changes] + +## Documentation Updates + +Memory Bank updates occur when: +1. Discovering new project patterns +2. After implementing significant changes +3. When user requests with **update memory bank** (MUST review ALL files) +4. When context needs clarification + +flowchart TD + Start[Update Process] + + subgraph Process + P1[Review ALL Files] + P2[Document Current State] + P3[Clarify Next Steps] + P4[Document Insights & Patterns] + + P1 --> P2 --> P3 --> P4 + end + + Start --> Process + +Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md and progress.md as they track current state. + +REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy. \ No newline at end of file diff --git a/memory-bank/activeContext.md b/memory-bank/activeContext.md new file mode 100644 index 0000000..96508a7 --- /dev/null +++ b/memory-bank/activeContext.md @@ -0,0 +1,42 @@ +# Active Context + +*This file tracks the current work focus, recent changes, next steps, active decisions, important patterns, and project insights.* + +## Current Focus + +- **Initial Repository Analysis:** Analyzing the existing codebase (`gitpod-vscode-desktop`) to understand its structure, functionality, and integration points. +- **Memory Bank Population:** Updating the Cline Memory Bank files (`projectbrief.md`, `productContext.md`, `systemPatterns.md`, `techContext.md`, `activeContext.md`, `progress.md`) with the findings from the analysis. + +## Recent Changes + +- **Memory Bank Updates (In Progress):** + - Updated `projectbrief.md` with core requirements, goals, and scope based on code analysis. + - Updated `productContext.md` with problem statement, target audience, high-level workflow, and UX goals. + - Updated `systemPatterns.md` with architecture overview, key decisions, design patterns, component relationships, and critical paths. + - Updated `techContext.md` with technologies, setup, constraints, dependencies, and tool usage. + +## Next Steps + +- Update `progress.md` to reflect the current state of the project based on the analysis. +- Complete the initial Memory Bank population task. +- Await further instructions or tasks from the user. + +## Active Decisions & Considerations + +- **Connection Methods:** The extension supports two distinct SSH connection methods (Local Proxy via IPC/Supervisor API keys, and SSH Gateway via user keys/owner token). Understanding the trade-offs and configuration for each is important. +- **External Dependencies:** The reliance on `ms-vscode-remote.remote-ssh` for the final connection step and the requirement for the companion `gitpod.gitpod-remote-ssh` extension remotely are key architectural points. +- **SSH Configuration:** The local proxy method actively modifies the user's SSH configuration, which is a significant side effect. + +## Important Patterns & Preferences + +- **Service-Oriented Architecture:** Code is organized into distinct services for different concerns (Session, Host, Remote, Telemetry, etc.). +- **Dual Connection Strategy:** Explicit implementation of two connection paths (Local Proxy, Gateway). +- **IPC for Secure Data Transfer:** Using gRPC/ConnectRPC for IPC between the extension and the proxy script to handle sensitive data like temporary SSH keys. +- **Leveraging VS Code APIs:** Strong preference for using built-in VS Code APIs (Authentication, Remote Development, UI) where possible. + +## Learnings & Insights + +- The extension acts primarily as a sophisticated orchestrator and configuration manager, setting up the parameters and environment for the `ms-vscode-remote.remote-ssh` extension to perform the actual connection. +- The Local SSH Proxy method is complex, involving SSH config modification, helper scripts, IPC, and interaction with the Gitpod Supervisor API for temporary keys. +- The extension does *not* manage the VS Code Server binary on the remote host. +- Authentication relies on VS Code's built-in provider and Gitpod's Public/Supervisor APIs. diff --git a/memory-bank/productContext.md b/memory-bank/productContext.md new file mode 100644 index 0000000..61b0465 --- /dev/null +++ b/memory-bank/productContext.md @@ -0,0 +1,35 @@ +# Product Context + +*This file describes why this project exists, the problems it solves, how it should work, and the user experience goals.* + +## Problem Statement + +- Gitpod Classic users need a way to connect their local VS Code Desktop application to their remote Gitpod workspaces. +- Standard SSH connections might be blocked by firewalls or require complex setup (key management, host configuration). +- Users need a streamlined way to authenticate with Gitpod and manage their workspace connections directly within VS Code. + +## Target Audience + +- Developers using Gitpod Classic who prefer using their local VS Code Desktop installation over the web-based IDE (Gitpod Theia or VS Code in Browser). +- Users in environments where direct SSH access (port 22) might be restricted. + +## How it Works + +1. **Authentication:** The extension integrates with VS Code's Authentication API, allowing users to sign into their Gitpod account. +2. **Workspace Discovery:** It uses the Gitpod Public API to fetch a list of the user's workspaces. +3. **UI Integration:** Presents workspaces in a dedicated Activity Bar view and provides commands for actions like connecting, stopping, and deleting. +4. **Connection Initiation:** When a user chooses to connect: + * The extension determines the connection method (Local SSH Proxy or SSH Gateway). + * **Local Proxy:** It ensures the local SSH client is configured with a `ProxyCommand` pointing to a helper script (`proxy.js`). This script communicates via IPC with the extension to get authentication details (including a temporary SSH key from the Supervisor API) and likely establishes a WebSocket tunnel. + * **SSH Gateway:** It fetches necessary details (host keys, owner token) and checks for user-provided SSH keys registered with Gitpod. If no key exists, it prompts the user with the temporary owner token to use as a password. + * It verifies host keys and adds them to `known_hosts`. +5. **Hand-off to Remote-SSH:** The extension constructs a `vscode-remote://ssh-remote+...` URI and uses the `vscode.openFolder` command to delegate the actual SSH connection and remote session management to the built-in `ms-vscode-remote.remote-ssh` extension. +6. **Remote Setup:** Ensures a companion extension (`gitpod.gitpod-remote-ssh`) is installed in the remote environment. + +## User Experience Goals + +- **Seamless Integration:** Feel like a natural part of VS Code's remote development workflow. +- **Simplified Connection:** Abstract away the complexities of SSH configuration and authentication where possible. +- **Reliability:** Provide robust connection methods that work in various network environments. +- **Clear Feedback:** Inform the user about connection status, errors, and necessary actions (e.g., installing Remote-SSH, handling passwords). +- **Convenient Management:** Allow users to manage their workspaces (view status, connect, stop) without leaving VS Code. diff --git a/memory-bank/progress.md b/memory-bank/progress.md new file mode 100644 index 0000000..135b215 --- /dev/null +++ b/memory-bank/progress.md @@ -0,0 +1,47 @@ +# Progress + +*This file tracks what works, what's left to build, the current status, known issues, and the evolution of project decisions.* + +## What Works + +Based on the code structure and implementation details observed: + +- **Authentication:** Integration with VS Code's Authentication API for Gitpod login appears functional. +- **Workspace Listing & Management:** Commands and UI elements for listing, refreshing, stopping, and deleting workspaces via the Gitpod Public API seem implemented. +- **SSH Gateway Connection:** The logic for connecting via the SSH gateway (fetching host keys, checking user keys, falling back to owner token password) is present and appears to be the primary, stable connection method. +- **Local SSH Proxy Connection (Experimental):** The infrastructure for the local proxy method (SSH config modification, helper scripts, IPC server, Supervisor API interaction for temp keys) is implemented, but likely marked as experimental or behind a feature flag. +- **Integration with Remote-SSH:** Hand-off to `ms-vscode-remote.remote-ssh` via `vscode.openFolder` is implemented. +- **UI:** Activity Bar view, commands, and status bar elements are defined in `package.json` and likely functional. +- **Basic Configuration:** Handling of `gitpod.host` and other extension settings is implemented. +- **Telemetry & Logging:** Basic infrastructure for telemetry (`@segment/analytics-node`) and logging (`vscode.LogOutputChannel`) is in place. +- **Companion Extension Setup:** Logic exists to ensure `gitpod.gitpod-remote-ssh` is added to default remote extensions. + +## What's Left to Build + +- Based on this initial analysis, the core features seem implemented. Further work might involve: + - Bug fixes and stability improvements. + - Enhancements to existing features (e.g., more detailed workspace information, improved error handling). + - Maturing the Local SSH Proxy connection method if it's still experimental. + - Addressing any TODOs or planned features not evident from this high-level review. + - Keeping dependencies (APIs, libraries, VS Code version) up-to-date. + +## Current Status + +- **Initial Analysis Complete:** The codebase has been analyzed at a high level to understand its structure and core functionality. +- **Memory Bank Populated:** The core Memory Bank files have been updated with the findings of this analysis. +- **Functionality:** The extension appears to be functional for its primary purpose: connecting VS Code Desktop to Gitpod Classic workspaces, primarily via the SSH Gateway method, with an experimental Local Proxy option. + +## Known Issues + +- No specific bugs were identified during this high-level analysis. Potential areas for issues could include: + - Edge cases in SSH configuration parsing or modification (Local Proxy). + - Network reliability issues affecting API calls or connections. + - Compatibility problems with specific SSH client versions or configurations. + - Errors during the IPC communication for the Local Proxy. + - Issues related to the companion extension (`gitpod.gitpod-remote-ssh`). + +## Evolution of Decisions + +- **Introduction of Local SSH Proxy:** The addition of the complex Local SSH Proxy method alongside the more straightforward SSH Gateway method represents a significant evolution, likely aimed at improving connection reliability in restricted network environments and potentially enhancing security by using temporary, session-specific SSH keys obtained from the Supervisor API instead of relying solely on long-lived user keys or tokens passed as passwords. +- **Dependency on `ms-vscode-remote.remote-ssh`:** The decision to leverage the existing Remote-SSH extension instead of building a custom remote file system and terminal backend was likely an early, foundational decision to reduce complexity and benefit from VS Code's mature remote infrastructure. +- **Companion Remote Extension:** The requirement for `gitpod.gitpod-remote-ssh` suggests a shift towards handling some logic within the remote environment itself after the connection is established. diff --git a/memory-bank/projectbrief.md b/memory-bank/projectbrief.md new file mode 100644 index 0000000..4ecbae5 --- /dev/null +++ b/memory-bank/projectbrief.md @@ -0,0 +1,46 @@ +# Project Brief + +*This file is the foundation document that shapes all other Memory Bank files. It defines the core requirements and goals of the project and serves as the source of truth for the project scope.* + +## Core Requirements + +- Provide VS Code integration for connecting to Gitpod Classic workspaces. +- Manage authentication with the Gitpod service using VS Code's Authentication API. +- Facilitate SSH connections to workspaces using either a local proxy mechanism or a direct SSH gateway. +- Integrate seamlessly with VS Code's Remote Development features, specifically Remote - SSH (`ms-vscode-remote.remote-ssh`). +- Provide UI elements (Activity Bar view, commands, status bar indicators) for managing Gitpod workspaces (listing, connecting, stopping, etc.). +- Handle URI schemes for initiating connections. +- Configure local SSH settings (`~/.ssh/config`) to support the local proxy connection method. +- Ensure a companion extension (`gitpod.gitpod-remote-ssh`) is installed in the remote workspace. + +## Project Goals + +- **Primary Goal:** Enable VS Code Desktop users to connect to and work within Gitpod Classic workspaces reliably and efficiently. +- **Connection Strategy:** Implement two primary SSH connection methods: + 1. **Local SSH Proxy (Preferred/Experimental):** Configure the local SSH client (`~/.ssh/config`) to use a proxy script (`proxy.js` via `proxylauncher.sh/bat`). This script communicates via IPC with the main extension (`ExtensionServiceServer`) to obtain authentication details (including a temporary SSH key generated via the Supervisor API) and likely establishes a WebSocket tunnel for the SSH connection. + 2. **SSH Gateway (Fallback):** Connect directly to Gitpod's SSH gateway using standard SSH keys registered in the user's Gitpod account (verified via API) or a temporary `ownerToken` obtained via API as a password if no suitable key is found. +- **Integration:** Leverage VS Code's native Remote - SSH extension (`ms-vscode-remote.remote-ssh`) for the final connection step, providing it with the necessary configuration (SSH destination, host platform settings). +- **Authentication:** Use VS Code's built-in Authentication API to manage Gitpod credentials securely. +- **User Experience:** Provide clear feedback during connection attempts, handle errors gracefully, and offer relevant commands and views for workspace management. + +## Scope + +### In Scope + +- Authentication with Gitpod (via VS Code Auth Provider). +- Listing, starting, stopping, and deleting Gitpod Classic workspaces via API calls. +- Implementing both Local SSH Proxy and SSH Gateway connection methods. +- Configuring the user's local SSH client settings (`~/.ssh/config`) for the Local Proxy method. +- Integrating with `ms-vscode-remote.remote-ssh` to initiate connections. +- Providing UI elements (Activity Bar, Commands, Status Bar). +- Handling `vscode://gitpod.gitpod-desktop/...` URIs. +- Basic telemetry and logging. +- Ensuring the `gitpod.gitpod-remote-ssh` companion extension is installed remotely. +- Managing SSH host keys in `known_hosts`. + +### Out of Scope + +- Managing the VS Code Server binary installation/update within the Gitpod workspace (assumed handled by Gitpod infrastructure). +- Direct integration with Gitpod Flex (extension detects and disables itself in Flex environments). +- Features beyond connecting to and managing Classic workspaces (e.g., creating new workspaces from VS Code). +- Deep file synchronization or complex remote environment management beyond SSH connection. diff --git a/memory-bank/systemPatterns.md b/memory-bank/systemPatterns.md new file mode 100644 index 0000000..93c3fb2 --- /dev/null +++ b/memory-bank/systemPatterns.md @@ -0,0 +1,145 @@ +# System Patterns + +*This file documents the system architecture, key technical decisions, design patterns in use, component relationships, and critical implementation paths.* + +## System Architecture + +This is a VS Code Extension (`extensionKind: ["ui"]`) designed to bridge VS Code Desktop with Gitpod Classic workspaces. Its architecture revolves around: + +1. **VS Code API Integration:** Heavily utilizes core VS Code APIs for UI (Activity Bar, Views, Commands, Status Bar, Notifications), Authentication, Configuration, File System access, Logging, and Remote Development hooks (`onResolveRemoteAuthority`, `vscode.openFolder`). +2. **Service Layer:** A set of services (`*Service.ts`) encapsulate distinct functionalities like session management, host configuration, remote connection logic, telemetry, notifications, and logging. +3. **Dual Connection Strategy:** Implements two methods for establishing SSH connections: + * **Local SSH Proxy:** Modifies the user's SSH configuration (`~/.ssh/config`) to use a `ProxyCommand`. This command executes a helper Node.js script (`proxy.js`) which communicates back to the main extension via an IPC channel (`ExtensionServiceServer`) to retrieve authentication details (including temporary SSH keys fetched from the Gitpod Supervisor API) before establishing the connection (likely over a WebSocket). + * **SSH Gateway:** Connects directly to Gitpod's SSH endpoint, authenticating using user-provided SSH keys (verified via Gitpod API) or a temporary `ownerToken` (obtained via Gitpod API) used as a password. +4. **External Dependencies:** + * **Gitpod APIs:** Interacts with the Gitpod Public API (for workspace management, user keys) and the Gitpod Supervisor API (within the workspace, via the local proxy, to generate temporary SSH keys). + * **`ms-vscode-remote.remote-ssh`:** Relies entirely on this built-in VS Code extension to handle the final SSH connection establishment and remote session management once the connection parameters are determined. + * **`gitpod.gitpod-remote-ssh`:** A companion extension that this extension ensures is installed *within* the remote Gitpod workspace, likely for post-connection setup or features. + * **Local SSH Client:** Leverages the user's installed SSH client via configuration modifications for the Local Proxy method. +5. **IPC:** Uses a gRPC/ConnectRPC-based IPC mechanism (`ExtensionServiceServer`) for communication between the main extension process and the `proxy.js` script executed by the SSH client. + +```mermaid +graph LR + %% Node Definitions + %% VSCode UI Extension + nodeExtMain["extension.ts"] + nodeExtServices["Services"] + nodeExtAuth["Authentication"] + nodeExtWsInfo["Workspace Info"] + nodeExtConnLogic["Connection Logic"] + nodeExtUi["UI Components"] + nodeIpcServer["IPC Server - ExtensionServiceServer"] + nodeSshConfig["User SSH Config"] + nodeRemoteSshExt["ms-vscode-remote.remote-ssh"] + + %% Local SSH Client + nodeSshCmd["ssh command"] + nodeProxyLauncher["proxylauncher.sh/bat"] + nodeProxyJs["proxy.js"] + + %% Gitpod Backend + nodePublicApi["Public API"] + nodeSupervisorApi["Supervisor API"] + nodeSshGateway["SSH Gateway"] + nodeWsContainer["Workspace Container"] + + %% Remote VSCode Environment + nodeCompanionExt["gitpod.gitpod-remote-ssh"] + nodeVscodeServer["VS Code Server"] + + %% Link Definitions + %% VSCode UI Extension Internal Links + nodeExtMain --> nodeExtServices + nodeExtServices -- Manages --> nodeExtAuth + nodeExtServices -- Manages --> nodeExtWsInfo + nodeExtServices -- Manages --> nodeExtConnLogic + nodeExtMain --> nodeExtUi + nodeExtConnLogic --> nodeIpcServer + nodeExtConnLogic -- Modifies --> nodeSshConfig + nodeExtConnLogic -- Triggers --> nodeRemoteSshExt + + %% Local SSH Client Internal Links & Interaction + nodeSshCmd -- Reads --> nodeSshConfig + nodeSshCmd -- Executes ProxyCommand --> nodeProxyLauncher + nodeProxyLauncher -- Runs --> nodeProxyJs + nodeProxyJs -- Connects --> nodeIpcServer + + %% Remote VSCode Environment Internal Links & Interaction + nodeRemoteSshExt -- Connects --> nodeWsContainer + nodeRemoteSshExt -- Installs/Uses --> nodeCompanionExt + nodeRemoteSshExt -- Manages --> nodeVscodeServer + + %% Interactions between Groups + nodeExtAuth --> nodePublicApi + nodeExtWsInfo --> nodePublicApi + nodeExtConnLogic -- Uses --> nodePublicApi + nodeExtConnLogic -- Uses --> nodeSshGateway + nodeIpcServer -- Uses --> nodeSupervisorApi + nodeProxyJs -- Proxies connection to --> nodeWsContainer + nodeRemoteSshExt -- SSH Connection via --> nodeSshGateway + nodeRemoteSshExt -- SSH Connection via --> nodeProxyJs +``` + +## Key Technical Decisions + +- **Leverage Native Remote-SSH:** Instead of implementing a full SSH client and remote file system provider, delegate the core remote connection handling to the mature `ms-vscode-remote.remote-ssh` extension. This significantly reduces complexity. +- **Dual Connection Methods:** Provide both a direct SSH gateway method (more standard but potentially blocked) and a local proxy method (more complex setup but potentially bypasses firewall issues and uses temporary keys). +- **IPC for Proxy Authentication:** Use an IPC server within the extension to securely pass sensitive information (like API tokens or temporary SSH keys) to the `proxy.js` script, avoiding the need to store them insecurely or pass them via command-line arguments. +- **Modify Global SSH Config:** Directly modify the user's `~/.ssh/config` (via an included file) to integrate the `ProxyCommand` needed for the local proxy method. This requires careful handling but enables seamless integration with the native SSH client. +- **Use Supervisor API for Temporary Keys:** For the local proxy method, interact with the Supervisor API within the target workspace (via the owner token initially) to generate a temporary SSH key pair (`createSSHKeyPair`). This avoids relying solely on user-managed keys for this path. +- **Feature Flag for Local Proxy:** Introduce the local proxy mechanism behind an experimental flag (`ExperimentalSettings`), allowing for gradual rollout and testing. +- **Companion Remote Extension:** Require `gitpod.gitpod-remote-ssh` on the remote side, suggesting some functionality is better handled within the remote context after connection. + +## Design Patterns + +- **Service Locator / Dependency Injection:** Services are instantiated in `extension.ts` and passed down to components that need them (e.g., `RemoteConnector` receives `SessionService`, `HostService`, etc.). +- **Disposable Pattern:** Classes extend `Disposable` and register resources (event listeners, servers, etc.) using `_register` for cleanup in the `dispose` method. +- **Command Pattern:** Commands are encapsulated in classes (e.g., `SignInCommand`) registered with a `CommandManager`. +- **Asynchronous Programming:** Extensive use of `async`/`await` and `Promise`s for handling I/O operations (API calls, file system access, IPC). +- **Observer Pattern:** Use of `vscode.EventEmitter` and `onDidChange*` events (e.g., `hostService.onDidChangeHost`). +- **gRPC/ConnectRPC:** Used for defining and implementing the IPC service (`ExtensionServiceDefinition`). + +## Component Relationships + +- **`extension.ts`:** Orchestrates activation, initializes all core services, registers the authentication provider, commands, views, and URI handlers. +- **Services (`*Service.ts`):** + - `SessionService`: Manages authentication state, tokens, and API client instances. + - `HostService`: Manages the target Gitpod host URL. + - `RemoteService`: Implements the core logic for setting up SSH configuration (local proxy), copying scripts, starting the IPC server, and handling the gateway connection details. + - `NotificationService`, `TelemetryService`, `LogService`: Provide cross-cutting concerns. +- **`RemoteConnector.ts`:** Handles the high-level connection flow triggered by URIs or commands. It checks prerequisites (Remote-SSH extension), determines connection type (local proxy vs. gateway), fetches SSH destination details (using `RemoteService` or its own logic for gateway), updates global state, and finally triggers `vscode.openFolder` to hand off to `ms-vscode-remote.remote-ssh`. +- **`GitpodAuthenticationProvider.ts`:** Implements the `vscode.AuthenticationProvider` interface for Gitpod login. +- **`ExtensionServiceServer.ts`:** Implements the server-side logic for the IPC channel used by the `proxy.js` script. It handles requests like `getWorkspaceAuthInfo`, which involves calling Gitpod APIs (Public and Supervisor) to retrieve necessary tokens and temporary SSH keys. +- **`proxy.js` (Helper Script):** Executed by the SSH client's `ProxyCommand`. Connects to the `ExtensionServiceServer` via IPC, requests auth info, and then likely establishes the actual proxied SSH connection (e.g., via WebSocket). +- **SSH Helpers (`src/ssh/`):** Utilities for parsing SSH config, managing `known_hosts`, testing connections, and gathering identity files. + +## Critical Implementation Paths + +1. **Authentication:** `SignInCommand` -> `SessionService.signIn` -> `GitpodAuthenticationProvider.requestSession` -> OAuth Flow -> Token stored in `SessionService`. +2. **Connection via URI (`vscode://gitpod.gitpod-desktop/...`):** + * `extension.ts` registers `vscode.window.registerUriHandler`. + * Handler calls `RemoteConnector.handleUri`. + * `handleUri` checks prerequisites (`ensureRemoteSSHExtInstalled`), ensures sign-in (`sessionService.signIn`). + * Determines connection type (local proxy experiment check). + * **If Local Proxy:** + * `RemoteService.setupSSHProxy` (copies scripts, updates SSH config). + * `RemoteService.startLocalSSHServiceServer`. + * `RemoteConnector.getLocalSSHWorkspaceSSHDestination`. + * `testLocalSSHConnection`. + * **If Gateway (or Local Proxy fails):** + * `RemoteConnector.getWorkspaceSSHDestination` (fetches host keys, owner token, checks user keys via API). + * `testSSHGatewayConnection`. + * `showSSHPasswordModal` if no user key found. + * `RemoteService.updateRemoteConfig` (ensures companion ext). + * Stores connection info in global state (`context.globalState.update`). + * Calls `vscode.commands.executeCommand('vscode.openFolder', vscode.Uri.parse('vscode-remote://ssh-remote+...'))`. +3. **Local Proxy SSH Handshake:** + * User/VS Code initiates SSH connection (e.g., `ssh workspace-id.gitpod.local`). + * SSH client reads `~/.ssh/config`, finds matching `Host` entry. + * Executes `ProxyCommand`: `proxylauncher.sh/bat` -> `node proxy.js ...`. + * `proxy.js` connects to `ExtensionServiceServer` on the specified IPC port. + * `proxy.js` sends `getWorkspaceAuthInfo` request. + * `ExtensionServiceServer` receives request, calls Gitpod Public API (get workspace details) and Supervisor API (`createSSHKeyPair` using owner token). + * `ExtensionServiceServer` returns auth info (host, user, temporary private key) to `proxy.js`. + * `proxy.js` uses this information to establish the final connection tunnel (likely WebSocket) to the workspace. + * SSH traffic flows through the tunnel established by `proxy.js`. diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md new file mode 100644 index 0000000..4e695f9 --- /dev/null +++ b/memory-bank/techContext.md @@ -0,0 +1,65 @@ +# Tech Context + +*This file details the technologies used, development setup, technical constraints, dependencies, and tool usage patterns.* + +## Technologies Used + +- **Language:** TypeScript +- **Runtime:** Node.js (for the extension host process and helper scripts like `proxy.js`) +- **Frameworks/Libraries:** + - VS Code API (`vscode`) + - `ssh2`, `ssh-config`, `@microsoft/dev-tunnels-ssh*`: For SSH connection handling, configuration parsing, and potentially tunneling. + - `nice-grpc`, `@connectrpc/connect`, `@connectrpc/connect-node`: For gRPC/ConnectRPC based IPC communication between the extension and the `proxy.js` script. + - `@gitpod/public-api`, `@gitpod/supervisor-api-grpcweb`: Gitpod API clients. + - `node-fetch-commonjs`: Polyfill for `fetch` API used by gRPC-web clients in Node.js. + - `ws`: WebSocket client, likely used for the proxied connection tunnel. + - `@vscode/proxy-agent`: For handling network proxies. + - `configcat-node`: For feature flagging. + - `@segment/analytics-node`: For telemetry. + - `protobufjs`, `ts-proto`, `@bufbuild/buf`: For Protocol Buffer definition and code generation (used for IPC). +- **Build Tools:** + - `webpack`: For bundling the extension and proxy script. + - `tsc`: TypeScript compiler. + - `eslint`: Linter. + - `mocha`: Testing framework. + - `@vscode/vsce`: VS Code Extension packager. + +## Development Setup + +1. **Prerequisites:** Node.js, Yarn (implied by `yarn.lock`). +2. **Install Dependencies:** Run `yarn install`. +3. **Compile:** + * Extension: `yarn compile-ext` (or `yarn watch-ext` for continuous compilation). + * Proxy Script: `yarn compile-proxy` (or `yarn watch-proxy`). +4. **Run/Debug:** Use VS Code's built-in "Run and Debug" panel (likely configured in `.vscode/launch.json`, although this file wasn't listed). +5. **Lint:** `yarn lint`. +6. **Test:** `yarn test`. +7. **Protocol Buffers:** If modifying `.proto` files, run `yarn proto-gen` (requires `buf` CLI). +8. **Packaging:** `yarn package`. + +## Technical Constraints + +- **VS Code Version:** Requires VS Code `^1.82.0` or higher (`engines.vscode` in `package.json`). +- **Platform:** Primarily targets desktop environments (Windows, macOS, Linux) where VS Code Desktop runs. Includes platform-specific launcher scripts (`proxylauncher.bat`, `proxylauncher.sh`). +- **SSH Client:** The Local SSH Proxy method relies on the user having a functional native SSH client installed and configured (`~/.ssh/config`). +- **Network:** Connection success depends on network accessibility to Gitpod APIs, the SSH Gateway, or WebSocket endpoints. The local proxy method aims to mitigate direct SSH port blocking. +- **Companion Extension:** Requires `gitpod.gitpod-remote-ssh` to be installable in the remote environment. + +## Dependencies + +- **VS Code APIs:** Core dependency for all UI, authentication, configuration, and remote development integration. +- **Gitpod Public API:** Used for fetching workspace lists, workspace status, user SSH keys, and owner tokens. Accessed via generated gRPC clients. +- **Gitpod Supervisor API:** Used via the local proxy's IPC call (`ExtensionServiceServer`) to generate temporary SSH key pairs within the workspace (`createSSHKeyPair`). Accessed via generated gRPC-web clients. +- **`ms-vscode-remote.remote-ssh` Extension:** Essential dependency for handling the final SSH connection and remote session. The extension prepares the parameters and hands off the connection URI to it. +- **`gitpod.gitpod-remote-ssh` Extension:** Companion extension required on the remote side. Functionality unknown from this codebase alone, but likely handles post-connection setup or remote-specific features. +- **Local SSH Client & Configuration:** External dependency for the Local SSH Proxy method. + +## Tool Usage Patterns + +- **Build:** `webpack` bundles the main extension (`out/extension.js`) and the proxy script (`out/local-ssh/proxy.js`). +- **Compilation:** `tsc` compiles TypeScript source files. +- **Linting:** `eslint` enforces code style. +- **Testing:** `mocha` runs unit/integration tests. +- **Packaging:** `vsce package` creates the `.vsix` file for distribution. +- **Protocol Buffers:** `buf lint` and `buf generate` are used to manage and generate code from `.proto` definitions for the IPC layer. +- **Scripts:** Node.js scripts in `scripts/` handle release preparation (`prepare-release-build.js`, `prepare-nightly-build.js`).