feat(plugins): notifications targeted at one project (API 1.5) (#2375)

- Add ui.notify-project: it shows only in that project's window (the most recently focused one if there are several) and works without a calling window - Button commands run in the window showing the notification; a closed project returns not-found, with nothing shown and no fallback to another window - Bump the plugin API to 1.5.0 (wit/, SDK copy, ENGINE_VERSION, API_VERSION) and rebuild all components - Add Project::notify and its mock to the SDK; update plugins/README.md Co-authored-by: LU XIANGRUI <[email protected]>
2026-11-09 19:25:54 +02:00 · 2026-11-09 23:20:38 +08:00
@@ -37,7 +37,7 @@ sdk/rust/openidea-plugin/     # the Rust SDK (host API, Plugin trait, mock host)
 crates/ide-plugin/tests/fixtures/  # test plugins: hello, jobs, language-toy, misbehave, semantic-tokens, hover, commit, inlay-hints
 ```

-The plugin API is defined in [`wit/`](../wit/) (`openidea:plugin@1.4.0`, world
+The plugin API is defined in [`wit/`](../wit/) (`openidea:plugin@1.5.0`, world
 `plugin`).

 ## 1. Quick start
@@ -365,9 +365,19 @@ are always available. Calling a gated function without its capability returns

 ## 3. Writing code (Rust SDK)

+### API 1.5
+
+API 1.5.0 is planned for the next OpenIDEA release. Use
+`engines.openidea = "^1.5"` and the matching SDK. Released 1.4 plugins keep
+working. New in 1.5:
+
+- [Notifications for a project](#notifications-with-commands):
+  `Project::notify` shows a notification in a window of that project only,
+  also from scheduled or background work.
+
 ### API 1.4

-API 1.4.0 is planned for the next OpenIDEA release. Use
+API 1.4.0 shipped with OpenIDEA 0.1.40. Use
 `engines.openidea = "^1.4"` and the matching SDK. Released 1.3 plugins keep
 working. New in 1.4:

@@ -525,6 +535,7 @@ then run `openidea-plugin check`.
 | `host::output_append(channel, text)`, `output_clear`, `output_reveal`                                          | `output.{append,clear,reveal}`             | API 1.4: read-only Output tabs; 32 named channels per plugin, each a 1 MiB UTF-8 ring buffer. Reveal requires the invoking window.                                                                                                                                                                                                                        |
 | `host::set_context(key, value)`, `remove_context`                                                              | `ui.{set,remove}-context`                  | Sets `plugin.<id>.<key>` for `when` clauses in the window the call came from (`true`, `3.5`, `"text"`; `ContextValue`). Key 1–64 of `A-Za-z0-9_-`, 100 per plugin; gone when the plugin stops.                                                                                                                                                            |
 | `host::notify(level, title, body)`                                                                             | `ui.show-notification`                     | Balloon in the window the command or events came from (every window otherwise).                                                                                                                                                                                                                                                                           |
+| `Project::notify(level, title, body, actions)`                                                                 | `ui.notify-project`                        | API 1.5: balloon only in a window of that project (the most recently focused one), with or without an invoking window; see _Notifications with commands_.                                                                                                                                                                                                 |
 | `host::copy_to_clipboard(text)`                                                                                | `ui.copy-to-clipboard`                     | Copies `text` to the system clipboard. Needs `clipboard`.                                                                                                                                                                                                                                                                                                 |
 | `host::open_url(url)`                                                                                          | `ui.open-url`                              | Opens an `http://` or `https://` URL in the user's default browser.                                                                                                                                                                                                                                                                                       |
 | `host::pick(title, items)`, `pick_many`                                                                        | `ui.pick`, `ui.pick-many`                  | Picks key(s) from `PickItem`s, or `None` when dismissed. From a command/event or code-action resolution in its editor window (else `invalid`); waiting is excluded from the budget.                                                                                                                                                                       |
@@ -2254,8 +2265,8 @@ the API itself follows _Evolving the plugin API_ below.
 ## 10. Evolving the plugin API

 Released versions are frozen: 1.0.0 shipped with OpenIDEA 0.1.36, 1.1.0
-with 0.1.37, 1.2.0 with 0.1.38 and 1.3.0 with 0.1.39. API 1.4.0 is planned
-with the next release. wasmtime decides what stays compatible: it resolves interface names
+with 0.1.37, 1.2.0 with 0.1.38, 1.3.0 with 0.1.39 and 1.4.0 with 0.1.40.
+API 1.5.0 is planned with the next release. wasmtime decides what stays compatible: it resolves interface names
 by semver (a component importing `openidea:plugin/[email protected]` links against a
 host defining `@1.1.0`, and the host finds its exports the same way), but
 function types must match exactly — a record with another field count, or a
@@ -2382,6 +2393,29 @@ its normal editor and project context. No capability is needed. Invalid or
 undeclared actions reject the whole notification. Labels are limited to 256
 bytes and arguments to 64 KiB. Plain `host::notify` behaves as before.

+Both go to the window the command or event came from, or to every window when
+there is none (a scheduled call, for instance). To reach one project from such
+work, call `notify` on that [`Project`](#the-api) (API 1.5, `ui.notify-project`),
+with the same actions and limits:
+
+```rust
+for project in host::projects()? {
+    if let Some(update) = check_for_update(&project)? {
+        let disable = NotificationAction::new("Disable automatic checks", "disable-checks")
+            .argument(project.root()?);
+        project.notify(NotificationLevel::Info, "Update available", &update, &[disable])?;
+    }
+}
+```
+
+- It shows only in a window of that project: the most recently focused one
+  when the project is open in several.
+- A button runs its command with an invocation from that window, so
+  `ctx.project()` is the notification's project.
+- If the project has closed by the time of the call, the call fails with
+  `Error::NotFound` and shows nothing; it never falls back to another window.
+  A balloon already shown goes away with its window.
+
 ### Selecting plugin tests (API 1.4, unreleased)

 A plugin using `framework = "plugin"` can implement `TestResults::select_tests`
@@ -1 +1 @@
-e3c11d8969a1b8b52e7e745b558d12f804ebf533e7f0f3fe614ffe6f7b9c9468
+bb67a1b003840ecc2d0c056a0b0af3474b08ac095239c1f4d02b7a7aab5b526c
@@ -1 +1 @@
-b28ccfd442c6348e0826680ec97391cbe4ec6a93a27ff02e40f47341e21586b4
+a6289739f5b644ea559ba18298741205ea0bedce7bd1dd2b367309101e8ffb1e
@@ -1 +1 @@
-d669a2600b0c59e91ac8a9b875a24bddf0eeddd404ce7b67da31733861a846b8
+767ff8329456fe3a1f324f571b22124707244a61ff5b6ea2c7ed88f909d202e8
@@ -1 +1 @@
-a5f0ebce6d30e0dc03769ebe5cb82d3704c5ccc32207aa2b3f5500de7b1a9152
+edb2a28419861c6f2d7cd5c300fa9f3120df5c17fb94596814635a9d97bf56d7
@@ -1 +1 @@
-ee3ccb648ca4b98a0359521c4cd895b5e7336fd65101563f2ca82b8cbaeedc3d
+debc0eccd6eb6a93bafecb0d6eca8feb26a3436d9154a278b877eaee567dce80
@@ -1 +1 @@
-51f7167dd5ed21ed37e227bd3b100a5be5a57e7890a494c942fdd036b1307993
+6e7cea8633d117d65b293c35bf332d8f4474ab1fdea88aedb37aa189e130857d
@@ -1 +1 @@
-cd860e7a652951aaa42029da23fdeee7a3c09ab1bfcbfb0d1bb6c89036fc8817
+e3a0ef77e0c7b54307751d24cc899a0cf782149ebf98833fc1d7b990b369cced
@@ -1 +1 @@
-db3ee94b5cf4234cee7d61e08a9f8629d7e7f6adbf11208b54cd4ea44cf1fc13
+39e75e8fc6d9227dce2efc7e29ffc03d4b1a2364e4710d74a4b255850bef1928
@@ -1 +1 @@
-76d13e772046b192485ea59c7720177b563986e0167475c449a9a5c7430ef908
+bd06b9b59b6515a1fd8a71271a4d8bb5280b685f400e141eba7365e7daabc7ea
@@ -1 +1 @@
-a22c9e7ebf79b2d5926424a028edc09aef40293db9ebc959d9ececa1f0ebe4ca
+3e04301385edee3c3693a89860e49b9d933ee3ad22046cd9cda320c10e64cec4
@@ -1 +1 @@
-fcc3d666fd1e89363fa8668dd10f89efc49f2376766282b734de4b719fdc9aff
+e60ead150d753c9824eeed0279ebe0a14f7ad226a2b90977ebeba646397b407b
@@ -1 +1 @@
-2eb742315f877e3251f992884160ed4d9a2940ee12a7d4d7a52669238d495930
+b8d20ee5966943cd298ab16a61b1552ddc523b2669ec2d11ad97bb1a86045ce6
@@ -1 +1 @@
-c2feb6a4cd0e9908f078a3d0074732cfce653cc57cce9d1907838598515048ee
+65fa71854546a7b19f7afe86642bc1e2c4eee9a7a08a71f87d307c68c95410d0
@@ -1 +1 @@
-590b46034f6c39592a27cabd5b0b76809e7f7133d258f322604614ecb3479317
+ce6fdce3010c8d836b452ebac7d0c7e42bf507b35f814ff448696a0541788d4a
@@ -1 +1 @@
-0d068ea0f0851e6e3166af0a91f290da8dc3f4a852b86050e7f7ced214a39124
+1d3689b3b18946e41753390f5e37cd6870374884831c5c5e0fd66606a1bfb659