pyxle-langkit 0.2.0__tar.gz

pyxle_langkit-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[codz]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Node
+node_modules/
+package-lock.json
+
+# VS Code extension build
+editors/vscode/out/
+editors/vscode/node_modules/
+editors/vscode/*.vsix
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

pyxle_langkit-0.2.0/CLAUDE.md

@@ -0,0 +1,163 @@
+# CLAUDE.md — Pyxle Langkit v2
+
+Language tooling suite for Pyxle — powers IDE support for `.pyx` files.
+
+---
+
+## Project Overview
+
+Pyxle Langkit provides IDE support for `.pyx` files — the hybrid Python/JSX format
+used by the Pyxle framework. The architecture is **server-driven**: all intelligence
+lives in the Python LSP server, and the VS Code extension is a thin LSP client.
+
+**Key architecture decisions:**
+- **jedi** for Python completions, definitions, hover, references
+- **pyflakes** for Python static analysis
+- **Babel** (Node.js subprocess) for JSX validation
+- **pygls** for the LSP server framework
+- **TypeScript** for the VS Code extension
+- **No virtual files on disk** — jedi analyzes in-memory, no SegmentManager
+
+---
+
+## Module Map
+
+```
+pyxle_langkit/
+|-- __init__.py           # Public API exports
+|-- server.py             # PyxleLanguageServer (pygls) — main LSP orchestrator
+|-- parser_adapter.py     # Tolerant parser wrapper (never raises)
+|-- document.py           # PyxDocument — parsed .pyx with line mapping
+|-- workspace.py          # WorkspaceIndex — tracks all .pyx files
+|-- linter.py             # Static analysis: pyflakes, Pyxle rules, React rules
+|-- react_checker.py      # Babel-based JSX validation via Node.js
+|-- completions.py        # jedi + Pyxle-specific completions
+|-- hover.py              # jedi + Pyxle-specific hover docs
+|-- definitions.py        # jedi + cross-section go-to-definition
+|-- diagnostics.py        # Diagnostic aggregation + position mapping
+|-- symbols.py            # Document + workspace symbols
+|-- formatting.py         # ruff (Python) + prettier (JSX) coordinator
+|-- semantic_tokens.py    # AST-based semantic tokens
+|-- cli.py                # CLI: parse, lint, outline, format
++-- js/                   # Node.js helpers
+    |-- react_parser_runner.mjs
+    +-- jsx_component_extractor.mjs
+
+editors/vscode/           # VS Code extension (TypeScript, thin client)
+|-- src/
+|   |-- extension.ts      # Activation + LSP client lifecycle
+|   +-- status.ts         # Status bar management
+|-- syntaxes/
+|   +-- pyx.tmLanguage.json
+|-- test/
+|   |-- suite/
+|   |   +-- extension.test.ts
+|   +-- runTest.ts
+|-- package.json
+|-- tsconfig.json
++-- language-configuration.json
+```
+
+---
+
+## Setup
+
+```bash
+# Install core framework (editable)
+pip install -e /path/to/pyxle[dev]
+
+# Install langkit
+pip install -e .[dev]
+
+# Install Babel helpers
+npm install
+
+# Build VS Code extension
+cd editors/vscode && npm install && npm run compile
+```
+
+---
+
+## Mandatory Rules
+
+### 1. Run Tests After Every Change
+
+```bash
+pytest                    # Full suite with coverage
+pytest tests/ -x          # Stop on first failure
+pytest --no-cov           # Skip coverage for faster iteration
+```
+
+All tests must pass. Coverage threshold is 95%.
+
+### 2. Test File Convention
+
+```
+pyxle_langkit/parser_adapter.py   -> tests/test_parser_adapter.py
+pyxle_langkit/document.py         -> tests/test_document.py
+pyxle_langkit/linter.py           -> tests/test_linter.py
+pyxle_langkit/completions.py      -> tests/test_completions.py
+pyxle_langkit/hover.py            -> tests/test_hover.py
+pyxle_langkit/definitions.py      -> tests/test_definitions.py
+pyxle_langkit/server.py           -> tests/test_server.py
+pyxle_langkit/workspace.py        -> tests/test_workspace.py
+pyxle_langkit/diagnostics.py      -> tests/test_diagnostics.py
+pyxle_langkit/symbols.py          -> tests/test_symbols.py
+pyxle_langkit/formatting.py       -> tests/test_formatting.py
+pyxle_langkit/semantic_tokens.py  -> tests/test_semantic_tokens.py
+pyxle_langkit/cli.py              -> tests/test_cli.py
+editors/vscode/                   -> editors/vscode/test/
+```
+
+### 3. Lint Before Committing
+
+```bash
+ruff check pyxle_langkit/ tests/
+```
+
+### 4. Commit Scope Convention
+
+Scope examples: `linter`, `server`, `completions`, `hover`, `definitions`,
+`formatting`, `vscode`, `parser`, `cli`, `workspace`.
+
+---
+
+## Module Rules
+
+### Parser Adapter
+- Must tolerate incomplete/malformed code — IDE users type incomplete code constantly
+- Never raise exceptions for parse failures — return PyxDocument with diagnostics
+
+### Linter
+- Python issues use pyflakes — don't reinvent its checks
+- `server` and `action` are whitelisted as globals (injected by Pyxle runtime)
+- JSX issues delegate to Node.js/Babel
+- All issues must have accurate line/column mapped to the original `.pyx` file
+
+### Completions / Hover / Definitions
+- Use jedi for Python intelligence — import safely with try/except
+- If jedi is not available, return Pyxle-specific results only (never crash)
+- Map all positions: .pyx → virtual Python → jedi → virtual Python → .pyx
+
+### LSP Server
+- Never block the event loop with synchronous I/O
+- Use asyncio.to_thread() for jedi calls (jedi is synchronous)
+- Diagnostics published on didOpen, didChange, didSave
+
+### VS Code Extension
+- TypeScript — compiled to out/ directory
+- Thin LSP client only — no SegmentManager, no virtual files
+- All intelligence comes from the LSP server
+
+---
+
+## DO NOT List
+
+- **DO NOT** import anything from `pyxle` other than `pyxle.compiler`
+- **DO NOT** add `print()` — use `logging`
+- **DO NOT** write virtual files to disk for language analysis
+- **DO NOT** use mutable dataclasses for data-carrying types
+- **DO NOT** block the async event loop with synchronous I/O
+- **DO NOT** grow caches without eviction policies
+- **DO NOT** hardcode file paths or OS-specific assumptions
+- **DO NOT** commit `.vsix` build artifacts or `node_modules/`

pyxle_langkit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shivam Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyxle_langkit-0.2.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: pyxle-langkit
+Version: 0.2.0
+Summary: Language tools for Pyxle: LSP server, linter, and editor integrations.
+Project-URL: Homepage, https://pyxle.dev
+Project-URL: Repository, https://github.com/pyxle-framework/pyxle-langkit
+Author-email: Shivam Saini <dev@pyxle.dev>
+License: MIT
+License-File: LICENSE
+Keywords: language-server,linter,lsp,pyxle,vscode
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Editors :: Integrated Development Environments (IDE)
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jedi<0.20,>=0.19
+Requires-Dist: lsprotocol>=2023.0.0
+Requires-Dist: pyflakes<3.3,>=3.2
+Requires-Dist: pygls<2.0,>=1.3
+Requires-Dist: pyxle-framework>=0.1.0
+Provides-Extra: dev
+Requires-Dist: coverage<8.0,>=7.4; extra == 'dev'
+Requires-Dist: pytest-cov<5.0,>=4.1; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.7,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Pyxle Language Toolkit
+
+Language tools for [Pyxle](https://pyxle.dev) `.pyx` files — LSP server, linter, and VS Code extension.
+
+## Features
+
+- **Syntax highlighting** via TextMate grammar (Python + JSX sections)
+- **Diagnostics** from pyflakes, Babel, and Pyxle-specific rules
+- **Completions** via Jedi (Python) + Pyxle component completions (JSX)
+- **Hover documentation** for Python symbols and Pyxle decorators/components
+- **Go-to-definition** via Jedi with cross-section navigation
+- **Document symbols** and **workspace symbols**
+- **Formatting** with ruff (Python) and prettier (JSX)
+- **Semantic tokens** via AST analysis
+
+## Installation
+
+```bash
+pip install pyxle-langkit
+```
+
+The VS Code extension is available on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools).
+
+## Architecture
+
+All intelligence lives in the Python LSP server. The VS Code extension is a thin LSP client (~100 LOC).
+
+- **Python analysis**: [Jedi](https://jedi.readthedocs.io/) for completions, definitions, hover
+- **JSX analysis**: Pyxle-specific completions + [Babel](https://babeljs.io/) for validation
+- **Static analysis**: [pyflakes](https://pypi.org/project/pyflakes/) + Pyxle rules
+- **LSP framework**: [pygls](https://pygls.readthedocs.io/)
+
+## License
+
+MIT

pyxle_langkit-0.2.0/README.md

@@ -0,0 +1,35 @@
+# Pyxle Language Toolkit
+
+Language tools for [Pyxle](https://pyxle.dev) `.pyx` files — LSP server, linter, and VS Code extension.
+
+## Features
+
+- **Syntax highlighting** via TextMate grammar (Python + JSX sections)
+- **Diagnostics** from pyflakes, Babel, and Pyxle-specific rules
+- **Completions** via Jedi (Python) + Pyxle component completions (JSX)
+- **Hover documentation** for Python symbols and Pyxle decorators/components
+- **Go-to-definition** via Jedi with cross-section navigation
+- **Document symbols** and **workspace symbols**
+- **Formatting** with ruff (Python) and prettier (JSX)
+- **Semantic tokens** via AST analysis
+
+## Installation
+
+```bash
+pip install pyxle-langkit
+```
+
+The VS Code extension is available on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pyxle.pyxle-language-tools).
+
+## Architecture
+
+All intelligence lives in the Python LSP server. The VS Code extension is a thin LSP client (~100 LOC).
+
+- **Python analysis**: [Jedi](https://jedi.readthedocs.io/) for completions, definitions, hover
+- **JSX analysis**: Pyxle-specific completions + [Babel](https://babeljs.io/) for validation
+- **Static analysis**: [pyflakes](https://pypi.org/project/pyflakes/) + Pyxle rules
+- **LSP framework**: [pygls](https://pygls.readthedocs.io/)
+
+## License
+
+MIT

pyxle_langkit-0.2.0/editors/vscode/.vscodeignore

@@ -0,0 +1,10 @@
+**/*.ts
+!out/**/*.js
+src/**
+test/**
+node_modules/**
+.vscode/**
+.ruff_cache/**
+tsconfig.json
+**/*.map
+**/*.vsix

pyxle_langkit-0.2.0/editors/vscode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shivam Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyxle_langkit-0.2.0/editors/vscode/icons/pyx.svg

@@ -0,0 +1,11 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="g" x1="2" y1="1" x2="14" y2="15" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#6ee7b7" />
+      <stop offset="0.5" stop-color="#34d399" />
+      <stop offset="1" stop-color="#059669" />
+    </linearGradient>
+  </defs>
+  <path d="M4.5 13 V3 H9 Q12.5 3 12.5 6.5 Q12.5 10 9 10 H4.5" stroke="url(#g)" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" fill="none" />
+  <circle cx="9" cy="6.5" r="1.2" fill="#6ee7b7" />
+</svg>

pyxle_langkit-0.2.0/editors/vscode/language-configuration.json

@@ -0,0 +1,51 @@
+{
+  "comments": {
+    "lineComment": "//",
+    "blockComment": ["/*", "*/"]
+  },
+  "brackets": [
+    ["{", "}"],
+    ["[", "]"],
+    ["(", ")"],
+    ["<", ">"]
+  ],
+  "autoClosingPairs": [
+    { "open": "{", "close": "}" },
+    { "open": "[", "close": "]" },
+    { "open": "(", "close": ")" },
+    { "open": "'", "close": "'", "notIn": ["string", "comment"] },
+    { "open": "\"", "close": "\"", "notIn": ["string", "comment"] },
+    { "open": "`", "close": "`", "notIn": ["string", "comment"] },
+    { "open": "<", "close": ">", "notIn": ["string", "comment"] }
+  ],
+  "surroundingPairs": [
+    ["{", "}"],
+    ["[", "]"],
+    ["(", ")"],
+    ["'", "'"],
+    ["\"", "\""],
+    ["`", "`"],
+    ["<", ">"]
+  ],
+  "folding": {
+    "markers": {
+      "start": "^\\s*(?:#\\s*---\\s*(?:python|server|javascript|client)|(?:def|class|async\\s+def|if|for|while|with|try|export\\s+default\\s+function|function|const)\\b)",
+      "end": "^\\s*$"
+    }
+  },
+  "indentationRules": {
+    "increaseIndentPattern": "^\\s*(?:def\\b|class\\b|if\\b|elif\\b|else:|for\\b|while\\b|with\\b|try:|except\\b|finally:|async\\s+def\\b|function\\b|=>\\s*\\{|\\{).*$",
+    "decreaseIndentPattern": "^\\s*(?:elif\\b|else:|except\\b|finally:|\\}|\\)|\\])"
+  },
+  "onEnterRules": [
+    {
+      "beforeText": ":\\s*$",
+      "action": { "indent": "indent" }
+    },
+    {
+      "beforeText": "\\{\\s*$",
+      "afterText": "^\\s*\\}",
+      "action": { "indent": "indent" }
+    }
+  ]
+}

pyxle_langkit-0.2.0/editors/vscode/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "pyxle-language-tools",
+  "displayName": "Pyxle Language Tools",
+  "publisher": "pyxle",
+  "version": "0.1.0-beta",
+  "description": "Language support for Pyxle .pyx files — syntax highlighting, diagnostics, completions, hover, go-to-definition, and formatting.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyxle-framework/pyxle-langkit"
+  },
+  "bugs": {
+    "url": "https://github.com/pyxle-framework/pyxle-langkit/issues"
+  },
+  "homepage": "https://pyxle.dev",
+  "keywords": ["pyxle", "pyx", "python", "react", "jsx", "lsp"],
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": ["Programming Languages"],
+  "activationEvents": ["onLanguage:pyxle"],
+  "main": "./out/extension.js",
+  "scripts": {
+    "compile": "tsc -p ./",
+    "watch": "tsc -watch -p ./",
+    "lint": "tsc --noEmit",
+    "pretest": "npm run compile",
+    "test": "node ./out/test/runTest.js",
+    "package": "npx @vscode/vsce package --no-dependencies"
+  },
+  "contributes": {
+    "languages": [
+      {
+        "id": "pyxle",
+        "aliases": ["Pyxle", "pyxle"],
+        "extensions": [".pyx"],
+        "configuration": "./language-configuration.json",
+        "icon": {
+          "light": "./icons/pyx.svg",
+          "dark": "./icons/pyx.svg"
+        }
+      }
+    ],
+    "grammars": [
+      {
+        "language": "pyxle",
+        "scopeName": "source.pyxle",
+        "path": "./syntaxes/pyx.tmLanguage.json",
+        "embeddedLanguages": {
+          "source.python": "python",
+          "source.js.jsx": "javascriptreact"
+        }
+      }
+    ],
+    "configuration": [
+      {
+        "title": "Pyxle",
+        "properties": {
+          "pyxle.langserver.command": {
+            "type": "string",
+            "default": "pyxle-langserver",
+            "description": "Command to launch the Pyxle language server. Install via: pip install pyxle-langkit"
+          },
+          "pyxle.langserver.args": {
+            "type": "array",
+            "items": { "type": "string" },
+            "default": ["--stdio"],
+            "description": "Arguments forwarded to the language server command."
+          },
+          "pyxle.formatting.python": {
+            "type": "string",
+            "default": "ruff",
+            "enum": ["ruff", "black", "none"],
+            "description": "Python formatter for .pyx files."
+          },
+          "pyxle.formatting.jsx": {
+            "type": "string",
+            "default": "prettier",
+            "enum": ["prettier", "none"],
+            "description": "JSX formatter for .pyx files."
+          },
+          "pyxle.diagnostics.pyflakes": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable pyflakes diagnostics for Python sections."
+          },
+          "pyxle.diagnostics.react": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable React/JSX analysis via Babel."
+          }
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "vscode-languageclient": "^9.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/vscode": "^1.85.0",
+    "@types/node": "^20.0.0",
+    "@vscode/test-electron": "^2.3.0",
+    "@vscode/vsce": "^2.22.0"
+  }
+}

pyxle_langkit-0.2.0/editors/vscode/src/extension.ts

@@ -0,0 +1,135 @@
+/**
+ * Pyxle Language Tools — VS Code extension.
+ *
+ * This is a thin LSP client.  All language intelligence (completions, hover,
+ * diagnostics, formatting, semantic tokens, go-to-definition) is provided by
+ * the ``pyxle-langserver`` Python process.  The extension's only job is to
+ * launch that process, wire up the Language Client, and manage the status bar.
+ *
+ * JSX intelligence comes from two sources:
+ * 1. The LSP server provides Pyxle-specific completions (components, props)
+ * 2. The ``embeddedLanguages`` mapping in the grammar contribution tells
+ *    VS Code that ``source.js.jsx`` regions are ``javascriptreact``, which
+ *    enables basic word-based completions and bracket matching from VS Code's
+ *    built-in TypeScript/JavaScript extension.
+ *
+ * Full semantic JSX intelligence (type-aware completions, go-to-definition
+ * into React types) requires embedding TypeScript's language service in the
+ * LSP server — planned for a future release.
+ */
+
+import * as vscode from "vscode";
+import {
+    LanguageClient,
+    LanguageClientOptions,
+    ServerOptions,
+} from "vscode-languageclient/node";
+import { createStatusBar, updateStatus, StatusState } from "./status";
+
+const LANGUAGE_ID = "pyxle";
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 2_000;
+
+let client: LanguageClient | undefined;
+let outputChannel: vscode.OutputChannel;
+let statusBar: vscode.StatusBarItem;
+
+/* ------------------------------------------------------------------ */
+/*  Activation                                                        */
+/* ------------------------------------------------------------------ */
+
+export function activate(context: vscode.ExtensionContext): void {
+    outputChannel = vscode.window.createOutputChannel("Pyxle Language Server");
+    context.subscriptions.push(outputChannel);
+
+    statusBar = createStatusBar(context);
+    updateStatus(statusBar, StatusState.Starting);
+
+    startClient(context, 0);
+}
+
+/* ------------------------------------------------------------------ */
+/*  Deactivation                                                      */
+/* ------------------------------------------------------------------ */
+
+export function deactivate(): Thenable<void> | undefined {
+    return client?.stop();
+}
+
+/* ------------------------------------------------------------------ */
+/*  Client lifecycle                                                  */
+/* ------------------------------------------------------------------ */
+
+function startClient(
+    context: vscode.ExtensionContext,
+    attempt: number,
+): void {
+    const config = vscode.workspace.getConfiguration("pyxle.langserver");
+    const command = config.get<string>("command", "pyxle-langserver");
+    const args = config.get<string[]>("args", ["--stdio"]);
+
+    const serverOptions: ServerOptions = {
+        run: { command, args },
+        debug: { command, args },
+    };
+
+    const clientOptions: LanguageClientOptions = {
+        documentSelector: [{ scheme: "file", language: LANGUAGE_ID }],
+        synchronize: {
+            fileEvents: vscode.workspace.createFileSystemWatcher("**/*.pyx"),
+        },
+        outputChannel,
+    };
+
+    client = new LanguageClient(
+        "pyxle",
+        "Pyxle Language Server",
+        serverOptions,
+        clientOptions,
+    );
+
+    const startPromise = client.start();
+
+    client.onDidChangeState((event) => {
+        if (event.newState === 2 /* Running */) {
+            updateStatus(statusBar, StatusState.Running);
+        }
+    });
+
+    const onReady = (): void => {
+        updateStatus(statusBar, StatusState.Running);
+    };
+
+    const onError = (error: unknown): void => {
+        const message =
+            error instanceof Error ? error.message : String(error);
+        outputChannel.appendLine(
+            `Language server failed to start: ${message}`,
+        );
+
+        if (attempt < MAX_RETRIES) {
+            const next = attempt + 1;
+            updateStatus(statusBar, StatusState.Retrying, next, MAX_RETRIES);
+            outputChannel.appendLine(
+                `Retrying in ${RETRY_DELAY_MS}ms (attempt ${next}/${MAX_RETRIES})...`,
+            );
+            setTimeout(() => startClient(context, next), RETRY_DELAY_MS);
+        } else {
+            updateStatus(statusBar, StatusState.Failed);
+            vscode.window
+                .showErrorMessage(
+                    `Pyxle Language Server failed after ${MAX_RETRIES} attempts. Is pyxle-langserver installed?`,
+                    "Show Output",
+                )
+                .then((choice) => {
+                    if (choice === "Show Output") {
+                        outputChannel.show();
+                    }
+                });
+        }
+    };
+
+    startPromise.then(onReady, onError);
+
+    context.subscriptions.push({ dispose: () => { client?.stop(); } });
+}