Файли
openidea/wit/host.wit
T
l0ng-ai 966963c8b6 feat(plugins): menus on plugin status bar items (API 1.14) (#4561)
A plugin status bar item could only run one command on click, so quick actions needed a centered pick dialog. Plugin API 1.14 adds ui.set-status-item-menu / set-window-status-item-menu: the item with a menu of actions (label, optional description, declared command and argument), separators and headers, at most 64; a click opens it anchored to the item with the shared Menu. Undeclared commands fail the call. SDK wrappers, mock, docs, rebuilt components. Also makes the SDK's wit_coverage export check ignore whitespace (rustfmt split the hover_actions impl, failing it since #4544).
2026-11-19 23:22:59 +08:00

246 рядки
13 KiB
Plaintext

package openidea:[email protected];
/// Writes to the IDE log, tagged with the plugin id.
interface log {
use types.{log-level};
log: func(level: log-level, message: string);
}
interface ui {
use types.{error, notification-level};
use workspace.{project};
record status-item {
text: string,
tooltip: option<string>,
/// One of the plugin's commands, run when the item is clicked.
command: option<string>,
}
/// An action in a status bar item's menu (API 1.14).
record status-menu-action {
/// Up to 256 bytes, one line.
label: string,
/// Secondary text shown after the label, such as a URL (up to 256 bytes).
description: option<string>,
/// The id of a command the plugin declares, run when the entry is chosen.
command: string,
/// Passed to the command as its argument (up to 64 KiB).
argument: option<string>,
}
/// An entry of a status bar item's menu (API 1.14).
variant status-menu-entry {
action(status-menu-action),
/// A line between groups of actions.
separator,
/// A caption above a group (up to 256 bytes, one line).
header(string),
}
record pick-item {
/// Returned when the item is chosen.
key: string,
label: string,
description: option<string>,
}
/// A context key's value, as `when` clauses compare it.
variant context-value {
flag(bool),
/// A finite number.
number(f64),
/// At most 1024 bytes.
text(string),
}
/// A highlight rule for Run and Debug console output (API 1.12).
record console-rule {
/// A regular expression (at most 512 bytes) in the syntax shared by
/// Rust's `regex` and JavaScript: no inline flags, named groups,
/// lookaround, backreferences, `\A`, `\z`, `\p`, POSIX classes or
/// repeated groups such as `(…)+`. A pattern that could take too long
/// on a long line is `invalid`. It sees the first 2000 characters of a line.
pattern: string,
ignore-case: bool,
/// A console palette colour: `black`, `red`, `green`, `yellow`,
/// `blue`, `magenta`, `cyan`, `white`, or one of them with `bright-`
/// (`bright-red`). The colour scheme's Console Colors decide how they
/// look. Unknown names are ignored.
foreground: option<string>,
/// A palette colour behind the text, as `foreground`.
background: option<string>,
/// Any of `bold`, `italic`, `underline`, `strikethrough`, `dim`.
/// Unknown names are ignored.
styles: list<string>,
/// Style the whole line instead of only the matched text.
whole-line: bool,
/// A disabled rule keeps its place in the list but never matches.
enabled: bool,
}
/// A notification button that runs one of the plugin's commands.
record notification-action {
/// Up to 256 bytes, one line.
label: string,
/// The id of a command the plugin declares.
command: string,
/// Passed to the command as its argument (up to 64 KiB).
argument: option<string>,
}
/// Shows a notification balloon in the window the current command or
/// event came from (every window when there is none).
show-notification: func(level: notification-level, title: string, body: string);
/// `show-notification` with up to three action buttons. Choosing one
/// dismisses the balloon and runs the command in its window. An invalid
/// action or an undeclared command fails the call and shows nothing.
notify: func(level: notification-level, title: string, body: string, actions: list<notification-action>) -> result<_, error>;
/// `notify` in a window of `target` only (API 1.5), with or without an
/// invoking window: the most recently focused one when the project is open
/// in several. Actions run in that window. A project closed by the time of
/// the call fails it with `not-found` and shows nothing; there is no
/// fallback to another window. A shown balloon goes away with its window.
notify-project: func(target: borrow<project>, level: notification-level, title: string, body: string, actions: list<notification-action>) -> result<_, error>;
/// Shows or updates the plugin's status bar item `id` in every window.
set-status-item: func(id: string, item: status-item);
remove-status-item: func(id: string);
/// Overrides the global item in the invoking window only (API 1.4).
/// Invalid outside a command or event of a window; removed on window close or plugin stop.
set-window-status-item: func(id: string, item: status-item) -> result<_, error>;
/// Removes this window's override, falling back to the global item.
remove-window-status-item: func(id: string) -> result<_, error>;
/// `set-status-item` with a menu (API 1.14): clicking the item opens the
/// menu anchored to it instead of running the item's command, and choosing
/// an action runs its command in that window. At most 64 entries. An empty
/// menu is the same as `set-status-item`. An action naming a command the
/// plugin does not declare fails the call and changes nothing.
set-status-item-menu: func(id: string, item: status-item, menu: list<status-menu-entry>) -> result<_, error>;
/// `set-window-status-item` with a menu, as `set-status-item-menu` (API 1.14).
set-window-status-item-menu: func(id: string, item: status-item, menu: list<status-menu-entry>) -> result<_, error>;
/// Replaces the plugin's console highlight rules (API 1.12); an empty
/// list removes them. Every window applies them to the stdout and stderr
/// lines of its Run and Debug consoles; the plugin never sees the output.
/// The first enabled whole-line rule that matches a line styles it,
/// instead of the colour of its log level; each enabled match-only rule
/// styles its matches on top, an earlier rule winning where matches
/// overlap. A rule's colours and styles replace the program's own. Rules
/// of several plugins apply in plugin id order. At most 100 rules; an
/// invalid one fails the call and keeps the previous rules. They go
/// away when the plugin stops. Needs no capability.
set-console-rules: func(rules: list<console-rule>) -> result<_, error>;
/// Sets the plugin's context key `key`, which `when` clauses test as
/// `plugin.<id>.<key>`, in the window the current command or event came
/// from (every window when there is none). A window's value takes
/// precedence over the global one. `key` is 1-64 of `A-Za-z0-9_-`; at most
/// 100 keys; they go away when the plugin stops.
set-context: func(key: string, value: context-value) -> result<_, error>;
/// Removes the key `set-context` set in the same scope.
remove-context: func(key: string);
/// Copies `text` to the system clipboard. Requires `clipboard`.
copy-to-clipboard: func(text: string) -> result<_, error>;
/// What `read-clipboard` found (API 1.11). Both `none`: the clipboard holds
/// neither text nor an image.
record clipboard-content {
text: option<string>,
/// An image (a screenshot), always as PNG bytes.
image: option<list<u8>>,
}
/// Reads the system clipboard of the user's machine (API 1.11). Requires
/// `clipboard.read`. Only in a command the user ran or a view action from
/// a window; anywhere else (event handlers, background and scheduled
/// work, web view messages, a command run through `command-runner`) it is
/// `denied`, so nothing reads the clipboard behind the user's back. Text
/// or an image over 16 MiB fails the call. In a remote project the user
/// confirms first; refusing is `denied`.
read-clipboard: func() -> result<clipboard-content, error>;
/// Opens an `http://` or `https://` URL in the user's default browser.
open-url: func(url: string) -> result<_, error>;
/// Shows a list and waits for the chosen key, or `none` when dismissed.
/// Works in a command/event of a window, or while resolving a selected code
/// or file action in its editor's window; `invalid` otherwise.
/// Needs no capability. Waiting doesn't count against the call's budget.
pick: func(title: string, items: list<pick-item>) -> result<option<string>, error>;
/// Native folder chooser; an absolute path, or `none` when dismissed.
/// Only from a command or event of a window; waiting is excluded from the budget.
pick-directory: func(title: string, initial: option<string>) -> result<option<string>, error>;
/// Like `pick`, with any number of items chosen.
pick-many: func(title: string, items: list<pick-item>) -> result<option<list<string>>, error>;
/// Asks for a line of text, pre-filled with `value`; `none` when dismissed.
/// Same rules as `pick`.
input: func(prompt: string, value: option<string>) -> result<option<string>, error>;
/// Asks for text over several lines, pre-filled with `value`; `none` when
/// dismissed. Only from a command or event of a window; the dialog confirms
/// on Cmd/Ctrl+Enter.
input-multiline: func(prompt: string, value: option<string>) -> result<option<string>, error>;
/// Asks for confirmation with OK and Cancel: `true` on OK, `false` on
/// Cancel or Escape. Same rules as `pick`.
confirm: func(title: string, body: string) -> result<bool, error>;
/// The IDE's UI language as a BCP 47 tag (`en`, `fr`, `zh-CN`, …); it
/// follows a change of language. For the text the plugin builds itself:
/// the strings of its manifest and views are translated from
/// `locales/<tag>.json`.
locale: func() -> string;
}
/// Persistent key-value storage of the plugin (survives restarts and idle
/// reclaim; instance memory does not). Requires `storage`. At most 64 MiB,
/// counting UTF-8 bytes of keys and values; rejected writes preserve the data.
interface storage {
use types.{error};
get: func(key: string) -> result<option<string>, error>;
set: func(key: string, value: string) -> result<_, error>;
delete: func(key: string) -> result<_, error>;
/// Keys starting with `prefix`, sorted.
keys: func(prefix: string) -> result<list<string>, error>;
}
/// Executes stable IDE action ids or `plugin.<plugin-id>.<command-id>` (API 1.4).
interface command-runner {
use types.{error};
/// Only in commands/events of a window. Returns a plugin command's value,
/// or none for IDE actions; unknown ids are not-found. Nested calls are bounded.
/// Requires high-risk `ide.commands`, except for this plugin's own commands.
execute: func(id: string, arg: option<string>) -> result<option<string>, error>;
}
/// Requests to the language servers the IDE runs (API 1.9).
interface language-servers {
use types.{error};
use workspace.{project};
/// Sends `method` to the server named `server` (the `name` of its
/// `[[language-servers]]` entry in the language definition, e.g. `phoxite`)
/// running for `project`, and returns the result as JSON. `params` is JSON,
/// or none for no params. Requires `lsp:<server>` and a trusted project.
///
/// Only the server's own methods pass (`phoxite/laravel/routes`): `initialize`,
/// `initialized`, `shutdown`, `exit`, anything starting with `$/` and any
/// method whose first segment is an LSP namespace (`textDocument`, `workspace`,
/// `window`, `notebookDocument`, `callHierarchy`, `typeHierarchy`,
/// `completionItem`, `codeAction`, `codeLens`, `documentLink`, `inlayHint`,
/// `workspaceSymbol`, `client`, `telemetry`) are `invalid`.
///
/// `not-found` when no such server is running for the project: the call never
/// starts one. The server's own error is `failed` with its message. The call
/// ends with the invocation's cancellation and time budget. At most 256 bytes
/// of method and 1 MiB of params.
request: func(project: borrow<project>, server: string, method: string, params: option<string>) -> result<string, error>;
/// The same for a notification: no answer is awaited.
notify: func(project: borrow<project>, server: string, method: string, params: option<string>) -> result<_, error>;
}
/// Per-plugin named, read-only Output tabs (API 1.4), with a 1 MiB UTF-8 ring buffer.
interface output {
use types.{error};
/// Appends text to a channel (at most 32 channels, names 1-128 bytes).
append: func(channel: string, text: string) -> result<_, error>;
/// Clears a channel's buffer.
clear: func(channel: string) -> result<_, error>;
/// Reveals the channel in the invoking window; only commands/events of a window.
reveal: func(channel: string) -> result<_, error>;
}