docs(lsp): info about LSP runtime providers

[UnschooledGamer]

No description provided.

[greptile-apps]

Greptile Summary

This PR documents the new lsp.registerRuntimeProvider() API, which allows plugins to run language servers outside Acode's built-in Alpine runtime by registering custom runtime providers with lifecycle hooks (canHandle, checkInstallation, install, start).

• Adds the lsp.registerRuntimeProvider() API reference with field descriptions, a collapsible code example, and a runtimes field on server definitions to opt a server into a specific provider.
• Introduces a new "LSP Runtime Provider Plugin API" section with conceptual overview and a "Register a Server For That Runtime" example, plus a Definitions section covering TransportHandle, TransportContext, and LSPRuntimeContext.
• The kind: "transport" return path from start() is documented in the spec but never demonstrated by a code example, and the relationship between the top-level dispose and TransportHandle.dispose is not explained.

Confidence Score: 5/5

Documentation-only change; no runtime code is modified. Safe to merge.

All changes are confined to the documentation file. The new registerRuntimeProvider API reference and supporting sections are coherent and useful. The issues found are minor documentation inconsistencies that do not block understanding the feature.

docs/advanced-apis/lsp.md — the start() return spec and its two examples could be tightened for consistency and completeness.

Important Files Changed

Filename	Overview
docs/advanced-apis/lsp.md	Adds documentation for lsp.registerRuntimeProvider() API with field specs, two code examples, a new LSP Runtime Provider Plugin API section, and a Definitions section. Minor inconsistencies found: the two start() examples disagree on the return description, the kind: "transport" return path has no example, and the top-level dispose vs TransportHandle.dispose responsibilities are left ambiguous.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Plugin
    participant LSP as lsp (Acode)
    participant Provider as RuntimeProvider
    participant Server as LanguageServer

    Plugin->>LSP: "lsp.registerRuntimeProvider({ id, canHandle, checkInstallation, install, start })"
    Plugin->>LSP: "lsp.register({ id, runtimes: [provider-id], ... })"

    Note over LSP: File opened matching server languages

    LSP->>Provider: canHandle(server, context)
    Provider-->>LSP: true

    LSP->>Provider: checkInstallation(server, context)
    Provider-->>LSP: "{ status: present|missing|failed|unknown, ... }"

    alt "status === missing"
        LSP->>Provider: install(server, context, mode)
        Provider-->>LSP: true
    end

    LSP->>Provider: start(server, context)
    alt "kind === websocket"
        Provider-->>LSP: "{ kind: websocket, url: ws://..., dispose }"
    else "kind === transport"
        Provider-->>LSP: "{ kind: transport, transport: TransportHandle, dispose }"
    end

    LSP->>Server: Connect via returned URL or TransportHandle
    Server-->>LSP: LSP messages

    Note over LSP: On teardown
    LSP->>Provider: dispose()

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Plugin
    participant LSP as lsp (Acode)
    participant Provider as RuntimeProvider
    participant Server as LanguageServer

    Plugin->>LSP: "lsp.registerRuntimeProvider({ id, canHandle, checkInstallation, install, start })"
    Plugin->>LSP: "lsp.register({ id, runtimes: [provider-id], ... })"

    Note over LSP: File opened matching server languages

    LSP->>Provider: canHandle(server, context)
    Provider-->>LSP: true

    LSP->>Provider: checkInstallation(server, context)
    Provider-->>LSP: "{ status: present|missing|failed|unknown, ... }"

    alt "status === missing"
        LSP->>Provider: install(server, context, mode)
        Provider-->>LSP: true
    end

    LSP->>Provider: start(server, context)
    alt "kind === websocket"
        Provider-->>LSP: "{ kind: websocket, url: ws://..., dispose }"
    else "kind === transport"
        Provider-->>LSP: "{ kind: transport, transport: TransportHandle, dispose }"
    end

    LSP->>Server: Connect via returned URL or TransportHandle
    Server-->>LSP: LSP messages

    Note over LSP: On teardown
    LSP->>Provider: dispose()

Loading

_{Reviews (2): Last reviewed commit: "fix: grammar & return types. enum fields" | Re-trigger Greptile}

[UnschooledGamer]

@greptile review again