openidea/wit/exports.wit

package openidea:plugin@1.8.0;

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

/// Optional pre-launch gate for targets owned by this plugin (API 1.5).
interface run-target-validation {
    enum operation { run, test }
    record launch-info {
        operation: operation,
        /// Bare program name before wrapping; no arguments or environment.
        program: string,
        /// Absolute working directory on the machine hosting the plugin.
        cwd: string,
    }
    /// Called after trust, ownership, process grants and executable pin checks.
    /// An error refuses the launch without changing the selected target. The
    /// host prefixes and bounds the message. Missing exports allow the launch.
    /// Calls wake reclaimed instances, use the host call timeout (5s by default),
    /// and are cancelled with the launch. Traps/timeouts refuse the launch.
    /// For remote projects this runs on the server, where the plugin lives.
    validate: func(project: string, target-id: string, launch: launch-info) -> result<_, string>;
}