Metadata-Version: 2.4
Name: citry-lsp
Version: 0.1.7
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>=0.5.1
Requires-Dist: packaging>=25.0
Requires-Dist: pygls==2.1.1
Requires-Dist: python-dotenv<2,>=1.2.3
Requires-Dist: ty==0.0.78
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 server requires Citry 0.5.1 or newer and Python 3.10 through 3.14. It checks
catalog and protocol schemas for compatibility. 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, Citry event/State binding keys and modifiers, Alpine directive
completion and hover, 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.

Clients may also provide an optional `envFile` initialization option. Relative
paths resolve from the workspace:

```json
{
  "protocolVersion": 1,
  "app": "my_project.web:app",
  "envFile": ".env"
}
```

File values override the environment inherited by the server and apply only
to the isolated app-discovery worker. The stdio server and its type analyzer
remain unchanged. Each registry reload rereads the file; missing or malformed
configured files produce a syntax-only status instead of importing the app
with an unintended environment. Citry's environment adapter reports the
selected path but never serializes or logs its parsed values.

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;
- public State-field completion in `:c-*` binding names, with errors on unknown fields;
- callback-parameter navigation and errors on unknown `data` members when
  `JsData` or a complete `js_data()` return analysis determines the fields;
- 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.

Unknown-field checks wait until the component and its schema are known.
Dynamic JavaScript keys and open data schemas remain unchecked. Ordinary
JavaScript member completion in VS Code uses its installed JavaScript provider.

## 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.7, component catalog v1, and
client protocol v1. It accepts Citry 0.5.1 and newer without a version upper
bound, and checks the catalog and client protocol contracts before returning
registry-backed results.

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