mirror of
https://github.com/l0ng-ai/openidea.git
synced 2026-11-08 08:52:12 +00:00
Arnaud Ritti
905a672bad
Closes #1720 Plugins can declare searchable multi-page settings (API 1.3): pages under the plugin in Settings, groups, string lists, editable tables and command buttons, while single-schema plugins keep working. A command button applies pending edits first and runs against the selected Global/Project layer (also remotely); Reset keeps other pages' edits, and invalid table/list edits never replace saved rows. Field and page order come from the schema without changing serde_json's map ordering elsewhere in the app. Co-authored-by: arnaud-ritti <[email protected]>
84 lines
4.9 KiB
Markdown
84 lines
4.9 KiB
Markdown
# Rust plugin SDK
|
|
|
|
The Rust API is documented by `cargo doc`. Web pages shipped alongside a Rust
|
|
component use `window.openidea` rather than Rust imports.
|
|
|
|
API 1.3 adds `Event::FilesChanged(FilesChanged)` for debounced external file
|
|
creation, modification and removal in open projects. Declare
|
|
`engines.openidea = "^1.3"`, the `events` capability and
|
|
`activation = ["on-event:files-changed"]`, then handle the typed event in
|
|
`Plugin::handle_events`. Use `host::subscribe_paths("files-changed", &["config/**"])`
|
|
to receive only matching project-relative paths in each category. An empty
|
|
filter pauses delivery. Paths are absolute, like `Event::FileSaved`; pending
|
|
batches are discarded when their project closes. The released WIT variant
|
|
is unchanged: the SDK decodes `event::other` with kind `files-changed`.
|
|
|
|
See [the event contract](../../../plugins/README.md#events)
|
|
and the [real Wasm fixture](../../../crates/ide-plugin/tests/fixtures/files-events).
|
|
|
|
API 1.3 adds capability-gated interactive PTYs to that web bridge. Declare
|
|
`engines.openidea = "^1.3"` and `process:<program>` in `plugin.toml`, then send
|
|
`pty-spawn`, `pty-input`, `pty-resize` and `pty-kill` JSON strings using
|
|
`openidea.postMessage`. Consume `pty-data` and acknowledge its `sequence` using
|
|
`pty-ack`; handle `pty-exit` and `pty-error` through `openidea.onMessage`.
|
|
|
|
See [the protocol, permission and resource limits](../../../plugins/README.md#web-frame-ptys-api-13)
|
|
and the [minimal fixture](../../../crates/ide-plugin/tests/fixtures/web-pty).
|
|
The frame cannot access IPC directly. Its sessions belong to that frame and
|
|
end with its view or plugin. There is no new WIT import for this API.
|
|
|
|
API 1.3 also answers Find Usages and Rename from `DocumentIndexer` definitions
|
|
and references. Existing indexers work without another export; declare
|
|
`engines.openidea = "^1.3"` when requiring these host features. Each anchor must
|
|
cover exactly the name, using UTF-16 columns. The host merges native results,
|
|
previews indexed renames and applies them as one undoable workspace edit.
|
|
The existing `project.read` capability and trusted-project boundary apply.
|
|
See [the indexing contract](../../../docs/plugins/indexing.md#find-usages-and-rename-api-13)
|
|
and [the minimal fixture](../../../crates/ide-plugin/tests/fixtures/indexer).
|
|
|
|
API 1.3 also adds diagnostics for unsaved documents. Declare
|
|
`kinds = ["diagnostics"]` and the supported `languages` under
|
|
`[[contributes.providers]]`, implement
|
|
`openidea_plugin::diagnostics::DiagnosticsProvider`, and export it with
|
|
`register_plugin!(MyPlugin, diagnostics)`. The host supplies versioned text
|
|
after a 300 ms debounce, cancels superseded calls, and drops stale answers
|
|
under the editor-provider budget. Ranges use 0-based UTF-16 positions.
|
|
|
|
The provider declaration supplies the document; host imports retain their
|
|
usual capability checks. Provider results coexist with manually published
|
|
diagnostics and are cleared with the document, project or plugin. Native
|
|
tests can call `MockHost::refresh_diagnostics` and inspect
|
|
`MockHost::provider_diagnostics`.
|
|
|
|
See [the diagnostics contract and limits](../../../plugins/README.md#diagnostics-while-typing)
|
|
and the [real Wasm fixture](../../../crates/ide-plugin/tests/fixtures/diagnostics).
|
|
|
|
API 1.3 also adds `open-log-tab` to the web bridge: a generic read-only editor
|
|
tab streams output from a granted process, with plugin-defined argument toggles.
|
|
It uses the same backend authorization and bounded PTY transport. See the
|
|
[protocol and lifecycle](../../../plugins/README.md#streaming-log-editor-tabs-api-13)
|
|
and the [built fixture](../../../crates/ide-plugin/tests/fixtures/web-log).
|
|
|
|
API 1.3 also adds `open-content-tab` to the web bridge: a plugin-backed editor
|
|
tab with custom toolbar actions (`content-tab-action` / `content-tab-reply`),
|
|
native diff viewer integration, and full `EditorDocumentLifecycle` support. See
|
|
the [protocol and lifecycle](../../../plugins/README.md#plugin-backed-content-editor-tabs-api-13)
|
|
and the [built fixture](../../../crates/ide-plugin/tests/fixtures/web-content).
|
|
|
|
## Multi-page settings (API 1.3)
|
|
|
|
Declare `[[contributes.settings.pages]]` with `id`, `title`, and `schema` and
|
|
require `engines.openidea = "^1.3"`. The IDE supplies searchable pages, grouped
|
|
fields, string lists and object tables. Values stay plugin-wide; read a table
|
|
with `host::setting("profiles")` and deserialize its JSON array.
|
|
|
|
A page action declares `title` and `command`. Pending settings are applied
|
|
before the command runs; return `Error::Invalid` / `Error::Failed` for an inline
|
|
failure and call `host::notify` on success. Keep API keys in declared secrets.
|
|
|
|
The [complete example](../../../crates/ide-plugin/tests/fixtures/settings-pages)
|
|
contains two pages, a model-profile table and a Test button, including the
|
|
manifest, schemas and Rust command implementation. See the
|
|
[settings contract](../../../plugins/README.md#multiple-pages-groups-lists-and-tables-api-13)
|
|
for supported field types, limits and Apply/Cancel behavior.
|