openidea/wit/host.wit

package openidea:plugin@1.6.0;

/// 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>,
    }

    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 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>;
    /// 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>;
    /// 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>;
}

/// 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>;
}