Add Cline memory bank

.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.

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.

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.

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.

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.