lint md file

Author: jankuca

INTEGRATIONS_CREDENTIALS.md

@@ -19,17 +19,20 @@ The integrations system enables Deepnote notebooks to connect to external data s
 Manages persistent storage of integration configurations using VSCode's encrypted SecretStorage API.
 
 **Key Features:**
+
 - Uses VSCode's `SecretStorage` API for secure credential storage
 - Storage is scoped to the user's machine (shared across all Deepnote projects)
 - In-memory caching for performance
 - Event-driven updates via `onDidChangeIntegrations` event
 - Index-based storage for efficient retrieval
 
 **Storage Format:**
+
 - Each integration config is stored as JSON under key: `deepnote-integrations.{integrationId}`
 - An index is maintained at key: `deepnote-integrations.index` containing all integration IDs
 
 **Key Methods:**
+
 - `getAll()`: Retrieve all stored integration configurations
 - `get(integrationId)`: Get a specific integration by ID
 - `save(config)`: Save or update an integration configuration
@@ -67,18 +70,21 @@ Manages persistent storage of integration configurations using VSCode's encrypte
 Scans Deepnote projects to discover which integrations are used in SQL blocks.
 
 **Detection Process:**
+
 1. Retrieves the Deepnote project from `IDeepnoteNotebookManager`
 2. Scans all notebooks in the project
 3. Examines each code block for `metadata.sql_integration_id`
 4. Checks if each integration is configured (has credentials)
 5. Returns a map of integration IDs to their status
 
 **Integration Status:**
+
 - `Connected`: Integration has valid credentials stored
 - `Disconnected`: Integration is used but not configured
 - `Error`: Integration configuration is invalid
 
 **Special Cases:**
+
 - Excludes `deepnote-dataframe-sql` (internal DuckDB integration)
 - Only processes code blocks with SQL integration metadata
 
@@ -87,6 +93,7 @@ Scans Deepnote projects to discover which integrations are used in SQL blocks.
 Orchestrates the integration management UI and commands.
 
 **Responsibilities:**
+
 - Registers the `deepnote.manageIntegrations` command
 - Updates VSCode context keys for UI visibility:
   - `deepnote.hasIntegrations`: True if any integrations are detected
@@ -95,6 +102,7 @@ Orchestrates the integration management UI and commands.
 - Opens the integration webview with detected integrations
 
 **Command Flow:**
+
 1. User triggers command (from command palette or SQL cell status bar)
 2. Manager detects integrations in the active notebook
 3. Manager opens webview with integration list
@@ -105,6 +113,7 @@ Orchestrates the integration management UI and commands.
 Provides the webview-based UI for managing integration credentials.
 
 **Features:**
+
 - Persistent webview panel (survives defocus)
 - Real-time integration status updates
 - Configuration forms for each integration type
@@ -113,6 +122,7 @@ Provides the webview-based UI for managing integration credentials.
 **Message Protocol:**
 
 Extension → Webview:
+
 ```typescript
 // Update integration list
 { type: 'update', integrations: IntegrationWithStatus[] }
@@ -125,6 +135,7 @@ Extension → Webview:
 ```
 
 Webview → Extension:
+
 ```typescript
 // Save configuration
 { type: 'save', integrationId: string, config: IntegrationConfig }
@@ -143,6 +154,7 @@ Webview → Extension:
 Main React component that manages the webview UI state.
 
 **State Management:**
+
 - `integrations`: List of detected integrations with status
 - `selectedIntegrationId`: Currently selected integration for configuration
 - `selectedConfig`: Existing configuration being edited
@@ -152,6 +164,7 @@ Main React component that manages the webview UI state.
 **User Flows:**
 
 **Configure Integration:**
+
 1. User clicks "Configure" button
 2. Panel shows configuration form overlay
 3. User enters credentials
@@ -160,6 +173,7 @@ Main React component that manages the webview UI state.
 6. Panel shows success message and refreshes list
 
 **Delete Integration:**
+
 1. User clicks "Reset" button
 2. Panel shows confirmation prompt (5 seconds)
 3. User clicks again to confirm
@@ -172,6 +186,7 @@ Main React component that manages the webview UI state.
 Type-specific forms for entering integration credentials.
 
 **PostgreSQL Form Fields:**
+
 - Name (display name)
 - Host
 - Port (default: 5432)
@@ -181,11 +196,13 @@ Type-specific forms for entering integration credentials.
 - SSL (checkbox)
 
 **BigQuery Form Fields:**
+
 - Name (display name)
 - Project ID
 - Service Account Credentials (JSON textarea)
 
 **Validation:**
+
 - All fields are required
 - BigQuery credentials must be valid JSON
 - Port must be a valid number
@@ -197,6 +214,7 @@ Type-specific forms for entering integration credentials.
 Provides environment variables containing integration credentials for the Jupyter kernel.
 
 **Process:**
+
 1. Scans the notebook for SQL cells with `sql_integration_id` metadata
 2. Retrieves credentials for each detected integration
 3. Converts credentials to the format expected by `deepnote-toolkit`
@@ -211,6 +229,7 @@ Example: Integration ID `my-postgres-db` → Environment variable `SQL_MY_POSTGR
 **Credential JSON Format:**
 
 PostgreSQL:
+
 ```json
 {
   "url": "postgresql://username:password@host:port/database",
@@ -220,18 +239,22 @@ PostgreSQL:
 ```
 
 BigQuery:
+
 ```json
 {
   "url": "bigquery://?user_supplied_client=true",
   "params": {
     "project_id": "my-project",
-    "credentials": { /* service account JSON */ }
+    "credentials": {
+      /* service account JSON */
+    }
   },
   "param_style": "format"
 }
 ```
 
 **Integration Points:**
+
 - Registered as an environment variable provider in the kernel environment service
 - Called when starting a Jupyter kernel for a Deepnote notebook
 - Environment variables are passed to the kernel process at startup
@@ -244,6 +267,7 @@ Injects Python code into the kernel at startup to set environment variables.
 Jupyter doesn't automatically pass all environment variables from the server process to the kernel process. This provider ensures credentials are available in the kernel's `os.environ`.
 
 **Generated Code:**
+
 ```python
 try:
     import os
@@ -258,6 +282,7 @@ except Exception as e:
 ```
 
 **Execution:**
+
 - Registered with `IStartupCodeProviders` for `JupyterNotebookView`
 - Runs automatically when a Python kernel starts for a Deepnote notebook
 - Priority: `StartupCodePriority.Base` (runs early)
@@ -270,6 +295,7 @@ except Exception as e:
 The `deepnote-toolkit` Python package reads credentials from environment variables to execute SQL blocks.
 
 **Flow:**
+
 1. Extension detects SQL blocks in notebook
 2. Extension retrieves credentials from secure storage
 3. Extension converts credentials to JSON format
@@ -282,6 +308,7 @@ The `deepnote-toolkit` Python package reads credentials from environment variabl
 
 **Environment Variable Lookup:**
 When a SQL block with `sql_integration_id: "my-postgres-db"` is executed:
+
 1. Toolkit looks for environment variable `SQL_MY_POSTGRES_DB`
 2. Toolkit parses the JSON value
 3. Toolkit creates a SQLAlchemy connection using the `url` and `params`
@@ -291,6 +318,7 @@ When a SQL block with `sql_integration_id: "my-postgres-db"` is executed:
 ## Data Flow
 
 ### Configuration Flow
+
 ```
 User → IntegrationPanel (UI)
   → vscodeApi.postMessage({ type: 'save', config })
@@ -302,6 +330,7 @@ User → IntegrationPanel (UI)
 ```
 
 ### Execution Flow
+
 ```
 User executes SQL cell
   → Kernel startup triggered
@@ -332,13 +361,14 @@ User executes SQL cell
 To add a new integration type (e.g., MySQL, Snowflake):
 
 1. **Add type to `integrationTypes.ts`**:
+
    ```typescript
    export enum IntegrationType {
      Postgres = 'postgres',
      BigQuery = 'bigquery',
      MySQL = 'mysql' // New type
    }
-   
+
    export interface MySQLIntegrationConfig extends BaseIntegrationConfig {
      type: IntegrationType.MySQL;
      host: string;
@@ -347,11 +377,12 @@ To add a new integration type (e.g., MySQL, Snowflake):
      username: string;
      password: string;
    }
-   
+
    export type IntegrationConfig = PostgresIntegrationConfig | BigQueryIntegrationConfig | MySQLIntegrationConfig;
    ```
 
 2. **Add conversion logic in `sqlIntegrationEnvironmentVariablesProvider.ts`**:
+
    ```typescript
    case IntegrationType.MySQL: {
      const url = `mysql://${config.username}:${config.password}@${config.host}:${config.port}/${config.database}`;
@@ -370,12 +401,13 @@ To add a new integration type (e.g., MySQL, Snowflake):
 ## Testing
 
 Unit tests are located in:
+
 - `sqlIntegrationEnvironmentVariablesProvider.unit.test.ts`
 
 Tests cover:
+
 - Environment variable generation for each integration type
 - Multiple integrations in a single notebook
 - Missing credentials handling
 - Integration ID to environment variable name conversion
 - JSON format validation
-