citry-lsp 0.1.0__tar.gz

citry_lsp-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Juro Oravec
+
+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.
+

citry_lsp-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: citry-lsp
+Version: 0.1.0
+Summary: Language server for Citry component templates
+Author-email: Juro Oravec <juraj.oravec.josefson@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://citry.dev
+Project-URL: Repository, https://github.com/citry-dev/citry
+Project-URL: Changelog, https://github.com/citry-dev/citry/blob/main/packages/py/citry_lsp/CHANGELOG.md
+Project-URL: Issues, https://github.com/citry-dev/citry/issues
+Keywords: citry,language server,lsp,templates,html
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: citry[analysis-ty]<0.5,>=0.4.0
+Requires-Dist: pygls==2.1.1
+Dynamic: license-file
+
+# Citry language server
+
+`citry-lsp` brings Citry template diagnostics, completion, hover, navigation,
+symbols, references, and formatting to editors that support the Language Server
+Protocol.
+
+It understands templates written inside Python, standalone `citry-html`
+documents, and template files owned by registered components. It can work
+without loading an app, while a project-aware installation also understands
+your registered components and their Python declarations.
+
+## Install in your project
+
+Install the server in the same Python environment as the Citry project:
+
+```console
+python -m pip install citry-lsp
+```
+
+The 0.1.x server supports Citry 0.4.x and Python 3.10 through 3.14. It installs
+the compatible Citry runtime, pygls, and the supported `ty` analyzer
+automatically.
+
+Your editor should launch this command over stdio:
+
+```console
+citry-lsp
+```
+
+For an isolated syntax-only process, use:
+
+```console
+uvx --from citry-lsp citry-lsp
+```
+
+The isolated form cannot import the project app, so it deliberately omits
+registry-backed component knowledge.
+
+## Choose how much project knowledge to load
+
+Without a project target, the server reports `syntax-only` mode. Parser
+diagnostics, Citry structural completion, lexical `c-for` and `c-fill`
+bindings, first-party hover help, and structural formatting remain available.
+The server does not guess which user components exist.
+
+For component-aware features, the editor supplies a `module:attribute` target
+through its `citry.app` setting:
+
+```json
+{
+  "citry.app": "my_project.web:app"
+}
+```
+
+The target may be a configured `Citry` instance or a `ComponentLibrary`:
+
+```json
+{
+  "citry.app": "citry_ui:__citry_library__"
+}
+```
+
+The server imports that target in a bounded worker process. Import errors,
+invalid targets, crashes, and timeouts produce one visible status message and
+fall back to syntax-only behavior without corrupting the editor connection.
+
+Registry mode adds:
+
+- component, input, slot, and typed slot-data completion and hover;
+- navigation to component classes, schema fields, inferred data keys, and
+  template bindings;
+- `TemplateData`, `JsData`, and `CssData` checks across Python, templates,
+  Alpine expressions, JavaScript, and CSS;
+- Events handler and `$c-props` checks;
+- Fluent message, key, argument, formatter, and translation navigation;
+- project lint settings and component-aware diagnostics.
+
+Each workspace folder should run its own server process so it can use that
+folder's Python interpreter and registry target.
+
+## Type-aware template expressions
+
+The server uses the `ty` executable installed in the selected project
+environment. Proven template roots receive Python member and call completion,
+hover, definitions, signature help, narrowing, and source-mapped diagnostics.
+
+If `ty` is missing, has the wrong version, exits, or times out, the server shows
+one degradation notice and keeps parser diagnostics and Citry-owned root
+features active.
+
+## Formatting
+
+Protocol v1 formats `citry-html` documents and parser-proven templates inside
+Python through Citry's shared structural formatter. Registry-proven ordinary
+HTML template files can be formatted through the explicit Citry request without
+registering Citry as the formatter for every HTML document.
+
+Clients may also negotiate `citry/formatComponentAssets` and
+`citry/formatEmbedded` for one atomic template, JavaScript, and CSS formatting
+operation. Stale or malformed client responses produce no edit.
+
+## Compatibility
+
+The server advertises language-server version 0.1.0, Citry 0.4.x, component
+catalog v1, and client protocol v1. It refuses incompatible client protocols or
+Citry series instead of returning results based on a contract it does not
+understand.
+
+The console command accepts pygls development transports:
+
+```console
+citry-lsp --tcp --host 127.0.0.1 --port 2087
+```
+
+Use stdio for normal editor integration.
+
+For editor setup and troubleshooting, see the
+[Citry IDE guide](https://citry.dev/ide/vscode/). Report problems through the
+[Citry issue tracker](https://github.com/citry-dev/citry/issues).

citry_lsp-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Citry language server
+
+`citry-lsp` brings Citry template diagnostics, completion, hover, navigation,
+symbols, references, and formatting to editors that support the Language Server
+Protocol.
+
+It understands templates written inside Python, standalone `citry-html`
+documents, and template files owned by registered components. It can work
+without loading an app, while a project-aware installation also understands
+your registered components and their Python declarations.
+
+## Install in your project
+
+Install the server in the same Python environment as the Citry project:
+
+```console
+python -m pip install citry-lsp
+```
+
+The 0.1.x server supports Citry 0.4.x and Python 3.10 through 3.14. It installs
+the compatible Citry runtime, pygls, and the supported `ty` analyzer
+automatically.
+
+Your editor should launch this command over stdio:
+
+```console
+citry-lsp
+```
+
+For an isolated syntax-only process, use:
+
+```console
+uvx --from citry-lsp citry-lsp
+```
+
+The isolated form cannot import the project app, so it deliberately omits
+registry-backed component knowledge.
+
+## Choose how much project knowledge to load
+
+Without a project target, the server reports `syntax-only` mode. Parser
+diagnostics, Citry structural completion, lexical `c-for` and `c-fill`
+bindings, first-party hover help, and structural formatting remain available.
+The server does not guess which user components exist.
+
+For component-aware features, the editor supplies a `module:attribute` target
+through its `citry.app` setting:
+
+```json
+{
+  "citry.app": "my_project.web:app"
+}
+```
+
+The target may be a configured `Citry` instance or a `ComponentLibrary`:
+
+```json
+{
+  "citry.app": "citry_ui:__citry_library__"
+}
+```
+
+The server imports that target in a bounded worker process. Import errors,
+invalid targets, crashes, and timeouts produce one visible status message and
+fall back to syntax-only behavior without corrupting the editor connection.
+
+Registry mode adds:
+
+- component, input, slot, and typed slot-data completion and hover;
+- navigation to component classes, schema fields, inferred data keys, and
+  template bindings;
+- `TemplateData`, `JsData`, and `CssData` checks across Python, templates,
+  Alpine expressions, JavaScript, and CSS;
+- Events handler and `$c-props` checks;
+- Fluent message, key, argument, formatter, and translation navigation;
+- project lint settings and component-aware diagnostics.
+
+Each workspace folder should run its own server process so it can use that
+folder's Python interpreter and registry target.
+
+## Type-aware template expressions
+
+The server uses the `ty` executable installed in the selected project
+environment. Proven template roots receive Python member and call completion,
+hover, definitions, signature help, narrowing, and source-mapped diagnostics.
+
+If `ty` is missing, has the wrong version, exits, or times out, the server shows
+one degradation notice and keeps parser diagnostics and Citry-owned root
+features active.
+
+## Formatting
+
+Protocol v1 formats `citry-html` documents and parser-proven templates inside
+Python through Citry's shared structural formatter. Registry-proven ordinary
+HTML template files can be formatted through the explicit Citry request without
+registering Citry as the formatter for every HTML document.
+
+Clients may also negotiate `citry/formatComponentAssets` and
+`citry/formatEmbedded` for one atomic template, JavaScript, and CSS formatting
+operation. Stale or malformed client responses produce no edit.
+
+## Compatibility
+
+The server advertises language-server version 0.1.0, Citry 0.4.x, component
+catalog v1, and client protocol v1. It refuses incompatible client protocols or
+Citry series instead of returning results based on a contract it does not
+understand.
+
+The console command accepts pygls development transports:
+
+```console
+citry-lsp --tcp --host 127.0.0.1 --port 2087
+```
+
+Use stdio for normal editor integration.
+
+For editor setup and troubleshooting, see the
+[Citry IDE guide](https://citry.dev/ide/vscode/). Report problems through the
+[Citry issue tracker](https://github.com/citry-dev/citry/issues).

citry_lsp-0.1.0/citry_lsp/__init__.py

@@ -0,0 +1,23 @@
+"""Citry language-server package and protocol declarations."""
+
+from citry_lsp.protocol import (
+    CATALOG_SCHEMA_VERSION,
+    EMBEDDED_FORMATTING_VERSION,
+    FORMAT_COMPONENT_ASSETS_METHOD,
+    FORMAT_EMBEDDED_METHOD,
+    FORMAT_TEMPLATES_METHOD,
+    PROTOCOL_VERSION,
+    SERVER_VERSION,
+    SUPPORTED_CITRY_SERIES,
+)
+
+__all__ = [
+    "CATALOG_SCHEMA_VERSION",
+    "EMBEDDED_FORMATTING_VERSION",
+    "FORMAT_COMPONENT_ASSETS_METHOD",
+    "FORMAT_EMBEDDED_METHOD",
+    "FORMAT_TEMPLATES_METHOD",
+    "PROTOCOL_VERSION",
+    "SERVER_VERSION",
+    "SUPPORTED_CITRY_SERIES",
+]

citry_lsp-0.1.0/citry_lsp/__main__.py

@@ -0,0 +1,26 @@
+"""Console entry point for the Citry language server."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from pygls.cli import start_server
+
+from citry_lsp.server import server
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Start stdio by default, or a pygls development transport."""
+    start_server(server, list(sys.argv[1:] if argv is None else argv))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = ["main"]