feat(plugins): plugin system with extension points, consent, Wasm runtime and plugin API 1.0 (#971)

A plugin system built on WebAssembly components (wasmtime, WASI p2), with a
typed WIT API (`openidea:[email protected]`) and a Rust SDK, shipped as a preview.

- Extension points declared in `plugin.toml` (commands, languages, themes,
  icon themes, menus, key bindings, status items, settings, views, custom
  editors, file icons and templates, run detectors, editor providers),
  validated before anything takes effect and projected onto the workbench's
  own registries: plugin themes and file icon themes are chosen in
  Settings › Appearance and Quick Switch, plugin shortcuts are edited in
  Settings › Keymap, plugin problems are grouped in Settings › Inspections.
- Capabilities with risk levels and consent at install, pinned `process:`
  programs, secrets in the OS keychain.
- Runtime: one thread per active plugin, fuel/time/memory budgets, soft and
  hard deadlines on the editing path, cancellation, crash backoff, idle
  reclaim, a precompiled-component cache; remote projects run code plugins on
  `openidea-server`.
- Web views and custom editors with a sandboxed page, a document bridge
  joined to the text editor's undo history, and split or preview layouts.
- Distribution: signed `.oiplugin` packages, a static marketplace index with
  revocation, versioned installs with rollback, install from a `.zip` or a
  folder. The release workflow signs and publishes the official plugins and
  their index, which released builds use as the default marketplace.
- Official plugins: String Tools, Key Promoter, Git Toolbox, AI Completion,
  Checkstyle, MyBatis Navigator, CSV Editor, Solidity, Material Icons, Harbor
  Night, Excalidraw, Graphviz, Regex Tester, License Header.

Closes #732

Co-authored-by: Deng Liu <[email protected]>
Co-authored-by: florentvdry <[email protected]>

wit/events.wit

@@ -0,0 +1,68 @@
+package openidea:[email protected];
+
+/// Workbench events, delivered in batches to `event-handler.handle`.
+interface events {
+    use types.{error};
+
+    enum event-kind {
+        file-opened,
+        file-saved,
+        /// The focused editor changed.
+        editor-focused,
+        /// An IDE action ran. Requires `events.input`.
+        action-performed,
+        /// A repository's state changed (commit, checkout, fetch, …).
+        vcs-changed,
+        /// The plugin's `on-schedule` period elapsed.
+        scheduled,
+    }
+
+    /// How the user started an action.
+    enum action-source {
+        keyboard,
+        menu,
+        toolbar,
+        context-menu,
+        search,
+        other,
+    }
+
+    record action-performed {
+        /// Action id (`editor.duplicate-line`).
+        action: string,
+        title: string,
+        source: action-source,
+        /// Its keyboard shortcut, when it has one (`Ctrl+D`).
+        shortcut: option<string>,
+    }
+
+    variant event {
+        file-opened(string),
+        file-saved(string),
+        editor-focused(option<string>),
+        action-performed(action-performed),
+        vcs-changed(string),
+        scheduled,
+    }
+
+    /// Delivers `kind` events from now on, for the rest of the session (also
+    /// across idle reclaim: an event activates the plugin again). Declare
+    /// `activation = ["on-event:<kind>"]` to get them before first use.
+    /// Requires `events` (`events.input` for `action-performed`).
+    subscribe: func(kind: event-kind) -> result<_, error>;
+    unsubscribe: func(kind: event-kind);
+}
+
+/// Long-running work with a progress indicator. While a task is open, the
+/// call that began it may run for the background budget (60 s) instead of 5 s.
+interface tasks {
+    resource task {
+        /// `done` of `total` units (`none`: indeterminate), with a short status.
+        report: func(done: u32, total: option<u32>, message: option<string>);
+        /// The user cancelled it: stop soon and return.
+        is-cancelled: func() -> bool;
+    }
+
+    /// Starts a task shown in the status bar; dropping it ends it.
+    begin: func(title: string, cancellable: bool) -> task;
+}

wit/exports.wit

@@ -0,0 +1,75 @@
+package openidea:[email protected];
+
+interface lifecycle {
+    use types.{context, error};
+
+    /// Called once after the instance is created: subscribe to events and
+    /// restore state from `storage`. Contributions (commands, languages,
+    /// themes, …) are declared in plugin.toml, not registered here.
+    /// An error fails the activation (shown on the plugin's page).
+    activate: func(ctx: context) -> result<_, error>;
+    /// Called before the instance is dropped (disable, uninstall, idle reclaim).
+    deactivate: func();
+}
+
+interface commands {
+    use types.{error};
+    use invocation.{invocation};
+
+    /// Runs one of the plugin's commands. Returns an optional message.
+    /// `cancelled` (the user gave up) and `denied` (a capability is missing)
+    /// are not counted as the plugin failing.
+    run: func(id: string, ctx: borrow<invocation>, arg: option<string>) -> result<option<string>, error>;
+}
+
+interface event-handler {
+    use events.{event};
+    use invocation.{invocation};
+
+    /// A batch of subscribed events, oldest first, from one window (`ctx`).
+    handle: func(events: list<event>, ctx: borrow<invocation>);
+}
+
+/// Optional export (world `plugin-syntax`): syntax of the plugin's own
+/// languages, for languages the IDE has no grammar for. The IDE calls it
+/// with the whole document; results are flat. Offsets are UTF-8 byte offsets
+/// into `text` (the IDE converts them); lines are 0-based.
+interface syntax-provider {
+    /// One highlighted range. `kind` is a highlight category: keyword, string,
+    /// string-special, escape, regexp, atom, number, constant, comment,
+    /// doc-comment, function, function-call, builtin, type, namespace,
+    /// variable, self-variable, property, attribute, macro, label, tag,
+    /// operator, punctuation. Unknown kinds are ignored; ranges must be
+    /// sorted and not overlap.
+    record token {
+        start: u32,
+        end: u32,
+        kind: string,
+    }
+
+    /// A symbol of the structure view. `parent` is the index of the enclosing
+    /// symbol in the same list (which must come first).
+    record symbol {
+        name: string,
+        detail: option<string>,
+        /// class, interface, struct, enum, function, method, constructor,
+        /// field, property, variable, constant, module, namespace, event, …
+        kind: string,
+        start: u32,
+        end: u32,
+        name-start: u32,
+        name-end: u32,
+        parent: option<u32>,
+    }
+
+    /// A foldable line range. `kind`: region, comment or imports.
+    record fold {
+        start-line: u32,
+        end-line: u32,
+        kind: string,
+    }
+
+    highlights: func(language: string, text: string) -> list<token>;
+    outline: func(language: string, text: string) -> list<symbol>;
+    folding: func(language: string, text: string) -> list<fold>;
+}

wit/host.wit

@@ -0,0 +1,38 @@
+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.{notification-level};
+
+    record status-item {
+        text: string,
+        tooltip: option<string>,
+        /// One of the plugin's commands, run when the item is clicked.
+        command: 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);
+    /// 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);
+}
+
+/// Persistent key-value storage of the plugin (survives restarts and idle
+/// reclaim; instance memory does not). Requires `storage`. At most 1 MiB.
+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>;
+}

wit/io.wit

@@ -0,0 +1,85 @@
+package openidea:[email protected];
+
+/// Problems in files, shown in the editor and the Problems view.
+interface diagnostics {
+    use types.{error, range};
+
+    enum severity {
+        error,
+        warning,
+        info,
+        hint,
+    }
+
+    record diagnostic {
+        range: range,
+        severity: severity,
+        message: string,
+        /// Rule or check id (`LineLength`).
+        code: option<string>,
+    }
+
+    /// Replaces the plugin's diagnostics for the file at `path` (absolute, in
+    /// an open project); an empty list clears them. Requires `project.read`.
+    publish: func(path: string, diagnostics: list<diagnostic>) -> result<_, error>;
+}
+
+/// HTTP(S) to the hosts granted with `net:<host>`.
+interface net {
+    use types.{error};
+
+    record header {
+        name: string,
+        value: string,
+    }
+
+    record request {
+        method: string,
+        /// `https://…`; plain `http://` only to `localhost` / `127.0.0.1`.
+        url: string,
+        /// `{{secret:<name>}}` in a value is replaced by the plugin's secret
+        /// `name` on the way out (requires `secrets`); the plugin never sees it.
+        headers: list<header>,
+        body: option<list<u8>>,
+        /// Default 30 s; the call's own budget applies too.
+        timeout-ms: option<u32>,
+    }
+
+    record response {
+        status: u16,
+        headers: list<header>,
+        /// At most 8 MiB.
+        body: list<u8>,
+    }
+
+    /// Fails with `denied` for a host the plugin may not reach, `cancelled`
+    /// when a newer request replaced the call or the user cancelled.
+    fetch: func(req: request) -> result<response, error>;
+}
+
+/// Secrets the user stored for the plugin (Settings › Plugins, kept in the
+/// OS keychain). Plugins only use them through `{{secret:<name>}}` in
+/// `net` requests. Requires `secrets`.
+interface secrets {
+    is-set: func(name: string) -> bool;
+}
+
+/// One-off runs of programs granted with `process:<program>` (the file the
+/// user approved, checked before every run).
+interface process {
+    use types.{error};
+    use workspace.{project};
+
+    record output {
+        /// `none` when killed by a signal.
+        status: option<s32>,
+        /// At most 4 MiB each (the rest is dropped).
+        stdout: string,
+        stderr: string,
+    }
+
+    /// Runs `program` with `args` in `cwd`'s root (else the plugin's data
+    /// directory) and waits; cancelled with the task or call. Call it inside
+    /// a task for anything slow.
+    run: func(program: string, args: list<string>, cwd: option<borrow<project>>, stdin: option<string>) -> result<output, error>;
+}

wit/plugin.wit

@@ -1,84 +1,67 @@
-/// OpenIDEA plugin API, version 0.1.
+/// OpenIDEA plugin API, version 1.0. Once released, 1.x only adds (new
+/// interfaces, new optional exports; plugins/README.md, "Evolving the plugin
+/// API"); a 2.0 keeps 1.0 running through an adapter in the host.
 ///
-/// A plugin is a WebAssembly component targeting the `plugin` world. It runs
-/// sandboxed: no filesystem, network, environment or clock access beyond what
-/// WASI preview 2 grants by default (wall/monotonic clocks and random only).
-/// Everything else goes through the `host` interface and is gated by the
-/// permissions declared in `plugin.toml`.
-package openidea:plugin@0.1.0;
-
-interface types {
-    enum log-level {
-        trace,
-        debug,
-        info,
-        warn,
-        error,
-    }
-
-    enum notification-level {
-        info,
-        warning,
-        error,
-    }
-
-    /// Passed to `activate`.
-    record context {
-        plugin-id: string,
-        plugin-version: string,
-        /// Version of this API the host implements, e.g. "0.1".
-        api-version: string,
-        /// Permissions granted from the manifest, e.g. ["project-read"].
-        permissions: list<string>,
-    }
-}
-
-interface host {
-    use types.{log-level, notification-level};
-
-    /// Writes to the IDE log (tagged with the plugin id).
-    log: func(level: log-level, message: string);
-
-    /// Registers (or updates) a command. It appears as action
-    /// `plugin.<plugin-id>.<id>` in Search Everywhere and the keymap editor.
-    /// `id` must match `[a-z0-9][a-z0-9._-]*`.
-    register-command: func(id: string, title: string, category: option<string>);
-
-    /// Shows a notification balloon.
-    show-notification: func(level: notification-level, title: string, body: string);
-
-    /// Root of the project the current command was invoked from.
-    /// Requires `project-read`.
-    workspace-root: func() -> option<string>;
-
-    /// Path of the focused editor's file. Requires `editor-read`.
-    active-file: func() -> option<string>;
-
-    /// Reads a UTF-8 text file inside the project root (absolute, or relative
-    /// to the root). Paths escaping the root are rejected. Requires `project-read`.
-    read-file: func(path: string) -> result<string, string>;
-
-    /// Inserts text at the cursor of the active editor. Requires `editor-write`.
-    insert-text: func(text: string);
-
-    /// Replaces the active editor's selection(s). Requires `editor-write`.
-    replace-selection: func(text: string);
-
-    /// Registers a language from a `languages/<id>.toml`-style definition.
-    register-language: func(definition: string) -> result<_, string>;
-
-    /// Registers a theme from JSON: {"id","name","kind":"dark"|"light","tokens":{"--var":"value"}}.
-    register-theme: func(definition: string) -> result<_, string>;
-}
+/// A plugin is a WebAssembly component targeting the `plugin` world (or
+/// `plugin-syntax`). It runs sandboxed: no filesystem, network, environment
+/// or processes beyond WASI's clocks and randomness; everything else goes
+/// through the imports below, gated by the capabilities granted in
+/// `plugin.toml` (a missing one returns `error::denied`).
+package openidea:plugin@1.0.0;
 
 world plugin {
-    use types.{context};
-    import host;
+    import log;
+    import ui;
+    import storage;
+    import workspace;
+    import editor;
+    import invocation;
+    import vcs;
+    import events;
+    import tasks;
+    import diagnostics;
+    import net;
+    import secrets;
+    import process;
+    import views;
+    import settings;
 
-    /// Called once after loading. Register commands here.
-    export activate: func(ctx: context) -> result<_, string>;
-    /// Called before unloading / disabling.
-    export deactivate: func();
-    /// Runs one of the plugin's commands. Returns an optional message.
-    export run-command: func(id: string, arg: option<string>) -> result<option<string>, string>;
+    export lifecycle;
+    export commands;
+    export event-handler;
+}
+
+/// A plugin that also provides syntax for its languages.
+world plugin-syntax {
+    include plugin;
+    export syntax-provider;
+}
+
+/// A plugin with editor providers (`[[contributes.providers]]`).
+world plugin-providers {
+    include plugin;
+    export providers;
+}
+
+/// A plugin with views or custom editors (`[[contributes.views]]`,
+/// `[[contributes.custom-editors]]`).
+world plugin-views {
+    include plugin;
+    export view-provider;
+}
+
+/// Only the `syntax-provider` export: guests generate it next to `plugin`
+/// (the component tools merge both into one component).
+world syntax {
+    export syntax-provider;
+}
+
+/// Only the `providers` export, generated next to `plugin` like `syntax`.
+world editor-providers {
+    export providers;
+}
+
+/// Only the `view-provider` export, generated next to `plugin` like `syntax`.
+world views-provider {
+    export view-provider;
 }

wit/providers.wit

@@ -0,0 +1,69 @@
+package openidea:[email protected];
+
+/// Editor features a plugin provides for the languages it declares under
+/// `[[contributes.providers]]` (the host calls only declared kinds). They run
+/// on the editing path: a result later than ~50 ms is dropped, a call still
+/// running at 500 ms is interrupted.
+interface providers {
+    use types.{position, range, text-edit, location};
+
+    /// The document a request is about.
+    record document {
+        path: string,
+        language: string,
+        version: u64,
+        text: string,
+    }
+
+    record completion-item {
+        label: string,
+        detail: option<string>,
+        /// Icon and sort group: text, method, function, constructor, field,
+        /// variable, class, interface, module, property, unit, value, enum,
+        /// keyword, snippet, color, file, reference, folder, enum-member,
+        /// constant, struct, event, operator or type-parameter. Unknown kinds
+        /// show no icon.
+        kind: option<string>,
+        insert-text: string,
+        /// Replaced on accept; `none`: the word at the caret.
+        replace: option<range>,
+        sort-text: option<string>,
+        documentation: option<string>,
+    }
+
+    record inline-suggestion {
+        insert-text: string,
+        /// Replaced range; `none` inserts at the caret.
+        replace: option<range>,
+    }
+
+    record file-edit {
+        path: string,
+        edits: list<text-edit>,
+    }
+
+    record code-action {
+        title: string,
+        /// `quickfix`, `refactor`, …
+        kind: option<string>,
+        preferred: bool,
+        edits: list<file-edit>,
+    }
+
+    record line-marker {
+        line: u32,
+        /// Gutter icon: `navigate` (default), `implemented`, `implementing`, `run`.
+        icon: option<string>,
+        tooltip: string,
+        /// Opened on click.
+        target: option<location>,
+    }
+
+    completion: func(doc: document, at: position, trigger: option<string>) -> list<completion-item>;
+    /// Ghost text at the caret (typing replaces an older request: it is cancelled).
+    inline-completion: func(doc: document, at: position) -> option<inline-suggestion>;
+    /// Actions for `selection` (quick fixes for the plugin's own diagnostics).
+    code-actions: func(doc: document, selection: range) -> list<code-action>;
+    definition: func(doc: document, at: position) -> list<location>;
+    line-markers: func(doc: document) -> list<line-marker>;
+}

wit/types.wit

@@ -0,0 +1,64 @@
+package openidea:[email protected];
+
+/// Shared types. Positions are 0-based lines and UTF-16 code unit columns,
+/// as in the editor and LSP.
+interface types {
+    /// Why a host call failed. A capability that is not granted is reported
+    /// as `denied`, so the plugin can degrade (0.1 trapped instead).
+    variant error {
+        /// Not granted; the payload names the capability (`editor.write`).
+        denied(string),
+        /// The document changed since the version the edit was made for.
+        stale,
+        not-found(string),
+        invalid(string),
+        /// Cancelled by the user, or the plugin is being stopped.
+        cancelled,
+        failed(string),
+    }
+
+    enum log-level {
+        trace,
+        debug,
+        info,
+        warn,
+        error,
+    }
+
+    enum notification-level {
+        info,
+        warning,
+        error,
+    }
+
+    record position {
+        line: u32,
+        character: u32,
+    }
+
+    record range {
+        start: position,
+        end: position,
+    }
+
+    record text-edit {
+        range: range,
+        text: string,
+    }
+
+    /// A range in a file (absolute path).
+    record location {
+        path: string,
+        range: range,
+    }
+
+    /// Passed to `lifecycle.activate`.
+    record context {
+        plugin-id: string,
+        plugin-version: string,
+        /// Version of this API the host implements, e.g. "1.0".
+        api-version: string,
+        /// Capabilities granted to the plugin (`editor.write`, `process:git`, …).
+        capabilities: list<string>,
+    }
+}

wit/views.wit

@@ -0,0 +1,146 @@
+package openidea:[email protected];
+
+/// Declarative views: tool windows declared
+/// under `[[contributes.views]]` and custom editors under
+/// `[[contributes.customEditors]]`. The plugin describes what to show; the
+/// IDE renders it with its own components (theme, keyboard, accessibility)
+/// and sends the user's actions back as `view-event`s. Nothing of the plugin
+/// runs in the WebView, except a `html` body, which is shown in a sandboxed
+/// frame that can only exchange messages with the plugin.
+interface view-types {
+    record button {
+        id: string,
+        label: string,
+        /// An IDE icon name (`refresh`, `add`, `remove`, `run`, …).
+        icon: option<string>,
+        enabled: bool,
+    }
+
+    /// A tree node; `parent` is the key of an earlier item (none: a root).
+    record tree-item {
+        key: string,
+        parent: option<string>,
+        label: string,
+        icon: option<string>,
+        /// Grey text after the label.
+        detail: option<string>,
+        /// Shows an expander even before its children are known
+        /// (`expand` asks for them).
+        expandable: bool,
+        expanded: bool,
+    }
+
+    record list-item {
+        key: string,
+        label: string,
+        icon: option<string>,
+        detail: option<string>,
+    }
+
+    variant field-value {
+        text(string),
+        multiline(string),
+        checkbox(bool),
+        /// The options and the chosen one.
+        choice(tuple<list<string>, string>),
+    }
+
+    record field {
+        key: string,
+        label: string,
+        value: field-value,
+    }
+
+    /// Rows `first-row`..`first-row + len(rows)` of `total-rows`: the IDE
+    /// asks for the rows it shows (`viewport`), so large tables stay cheap.
+    record table {
+        columns: list<string>,
+        total-rows: u32,
+        first-row: u32,
+        rows: list<list<string>>,
+        editable: bool,
+    }
+
+    variant body {
+        /// A centred message (empty state, errors).
+        message(string),
+        tree(list<tree-item>),
+        %list(list<list-item>),
+        form(list<field>),
+        table(table),
+        /// HTML shown in a sandboxed frame: no scripts from elsewhere, no
+        /// network, no IDE API. Its script talks to the plugin with
+        /// `openidea.postMessage(text)` / `openidea.onMessage(fn)`.
+        html(string),
+    }
+
+    record view {
+        toolbar: list<button>,
+        body: body,
+        /// A line below the body (counts, last refresh…).
+        status: option<string>,
+    }
+
+    /// The table rows the IDE shows.
+    record viewport {
+        first-row: u32,
+        rows: u32,
+    }
+
+    record cell-edit {
+        row: u32,
+        column: u32,
+        value: string,
+    }
+
+    variant view-event {
+        /// A toolbar button.
+        button(string),
+        /// Double click / Enter on a tree or list item.
+        activate(string),
+        select(string),
+        expand(string),
+        collapse(string),
+        /// A form field changed: key and new value (`true`/`false` for checkboxes).
+        field(tuple<string, string>),
+        cell(cell-edit),
+        /// Insert an empty row before this one (the row count: append).
+        insert-row(u32),
+        delete-rows(list<u32>),
+        /// From the `html` body's script.
+        message(string),
+    }
+}
+
+/// What a plugin's code can ask of its views.
+interface views {
+    use types.{error};
+
+    /// The view (or every custom editor of that id) shows outdated content:
+    /// the IDE renders it again.
+    refresh: func(view: string);
+    /// Sends a message to the script of a view's `html` body.
+    post-message: func(view: string, message: string) -> result<_, error>;
+    /// Opens a terminal tab in the window the call came from, running
+    /// `program` (pinned by a `process:<program>` grant) with `args` in the
+    /// project root: long-running output (logs) and interactive sessions.
+    open-terminal: func(title: string, program: string, args: list<string>) -> result<_, error>;
+}
+
+/// The plugin's own settings (`[contributes.settings]`), as the user set them
+/// (project over global) or the schema's default.
+interface settings {
+    /// The value of `key` as JSON (`true`, `3`, `"text"`), none if unknown.
+    get: func(key: string) -> option<string>;
+}
+
+/// Optional export (world `plugin-views`): content of declared views and
+/// custom editors. For a custom editor, `ctx.editor()` is its document.
+interface view-provider {
+    use view-types.{view, viewport, view-event};
+    use invocation.{invocation};
+    use types.{error};
+
+    render: func(view: string, viewport: option<viewport>, ctx: borrow<invocation>) -> result<view, error>;
+    handle: func(view: string, event: view-event, ctx: borrow<invocation>) -> result<_, error>;
+}

wit/workspace.wit

@@ -0,0 +1,90 @@
+package openidea:[email protected];
+
+interface workspace {
+    use types.{error};
+
+    /// A project open in the IDE.
+    resource project {
+        /// Absolute path of the project root. Requires `project.read`.
+        root: func() -> result<string, error>;
+        /// Reads a UTF-8 text file inside the project (absolute, or relative
+        /// to the root); paths leaving the root are refused. Unsaved editor
+        /// contents win over the disk. Requires `project.read`.
+        read-file: func(path: string) -> result<string, error>;
+        /// Project files whose root-relative path matches `glob` (`**/*Mapper.xml`),
+        /// at most `limit`, as absolute paths. Ignored and excluded files are
+        /// skipped. Requires `project.read`.
+        find-files: func(glob: string, limit: u32) -> result<list<string>, error>;
+    }
+
+    /// Projects open in any window. Requires `project.read`.
+    projects: func() -> result<list<project>, error>;
+}
+
+interface editor {
+    use types.{error, range, text-edit};
+
+    record document {
+        /// Grows with every change; edits name the version they were made for.
+        version: u64,
+        text: string,
+    }
+
+    /// A file open in an editor.
+    resource text-editor {
+        /// Absolute path of the file.
+        path: func() -> string;
+        /// Language id (`rust`, `solidity`, …).
+        language: func() -> string;
+        /// Current version and text. Requires `editor.read`.
+        document: func() -> result<document, error>;
+        /// Selections when the command was invoked (a cursor is an empty
+        /// range). Requires `editor.read`.
+        selections: func() -> result<list<range>, error>;
+        /// Applies `edits` as one undoable change, only if the document is
+        /// still at `version` (else `stale`, and nothing changes). Ranges are
+        /// in that version and must not overlap. Returns the new version.
+        /// Requires `editor.write`.
+        apply-edits: func(version: u64, edits: list<text-edit>) -> result<u64, error>;
+    }
+}
+
+/// Where a command or event comes from.
+interface invocation {
+    use workspace.{project};
+    use editor.{text-editor};
+
+    resource invocation {
+        /// The window's project.
+        project: func() -> option<project>;
+        /// The window's focused editor.
+        editor: func() -> option<text-editor>;
+    }
+}
+
+/// Git, for the repository containing a project.
+interface vcs {
+    use types.{error};
+    use workspace.{project};
+
+    record repository-status {
+        /// Absolute path of the working tree root.
+        root: string,
+        /// `none` when HEAD is detached.
+        branch: option<string>,
+        commit: option<string>,
+        upstream: option<string>,
+        ahead: u32,
+        behind: u32,
+        /// Merge / rebase / cherry-pick in progress.
+        operation: option<string>,
+        /// Files with staged or unstaged changes.
+        changed-files: u32,
+    }
+
+    /// `none` when the project is not in a repository. Requires `vcs.read`.
+    status: func(project: borrow<project>) -> result<option<repository-status>, error>;
+    /// Fetches all remotes (pruning deleted branches). Requires `vcs.write`.
+    /// Long-running: call it inside a task.
+    fetch: func(project: borrow<project>) -> result<_, error>;
+}