Writing extensions

ecliptic's extensions work the way VS Code's do: a folder with a package.json that says what the extension contributes (colour themes, settings, commands, menu entries, keybindings, views), and, if it needs to do something, a process of its own that the app talks to. An extension can reach every part of the app: the theme, the Settings editor, the title bar's and the columns' menus, the keyboard, the Activity Bar and the side bar, the status bar, the Changes rows, the diff drawer, the notice bar, the clipboard and the columns themselves.

The app ships three extensions, built in (crates/ecliptic/extensions/): VS Code Themes (ecliptic.vscode), which contributes Dark Modern and Light Modern (the defaults), Dark+ and Light+; Atlas Themes (ecliptic.atlas-themes), the Atlas-branded themes, with Atlas Ember; and Tokyo Night (ecliptic.tokyo-night), with Tokyo Midnight. The app itself knows only the two defaults: every other theme is an extension, and the picker lists the defaults first and the rest by name. There is a complete example in examples/extensions/change-stats: a status bar total, two views, decorations, commands, a menu entry, a keybinding and two settings, in 200 lines of Python.

Installing

An extension is a folder in ~/.local/share/ecliptic/extensions/ ($XDG_DATA_HOME/ecliptic/extensions/; on macOS ~/Library/Application Support/ecliptic/extensions/, on Windows %APPDATA%\ecliptic\extensions\). The Extensions view (the Ctrl+Shift+X icon in the Activity Bar) lists every extension, built in or installed, and turns each on or off, at once: what it contributes comes and goes, and its process starts or stops. Its folder icon opens the extensions folder. Click an extension for its page, as in VS Code: the header (name, publisher, version, Enable or Disable, the folder it is in and any manifest problems), Details (its README.md), Features (what the manifest contributes: colour themes, commands with their keybindings, settings with their defaults, keybindings, menus, view containers, views and its process) and Changelog (its CHANGELOG.md). The README and changelog are read as a small Markdown subset: headings, paragraphs, lists, fenced code, rules and quotes; links and images show their text, and HTML is dropped.

cp -r examples/extensions/change-stats ~/.local/share/ecliptic/extensions/

A folder that is not an extension (no package.json, or one that is not JSON) is listed under Could not load with the reason; the others load. An installed extension with a built-in's id replaces the built-in.

A VS Code colour-theme extension works as it is: unpack its .vsix (it is a zip; the extension is in its extension/ folder) into the extensions folder.

The manifest

{
    "name": "change-stats",                 // with publisher, the id: ecliptic-examples.change-stats
    "publisher": "ecliptic-examples",
    "version": "1.0.0",
    "displayName": "Change Stats",
    "description": "Lines added and removed across every column.",
    "main": "./extension.py",               // optional: its process
    "activationEvents": ["onStartupFinished"],
    "contributes": { … }
}

Comments and trailing commas are allowed. Fields the app does not use (engines, repository, icon, …) are read past. A contribution the app cannot use is reported (in the log and the Extensions view) and the rest of the manifest still loads.

Contribution points

themes

"themes": [
    { "label": "Night", "uiTheme": "vs-dark", "path": "./themes/night.json" }
]

uiTheme is vs (light), vs-dark, hc-black or hc-light. The file is a VS Code colour theme:

{
    "name": "Night",
    "include": "./night-base.json",      // merged under this file's colours
    "colors": {
        "sideBar.background": "#14161B",
        "statusBar.background": "#0E639C",
        "gitDecoration.modifiedResourceForeground": "#E5C07B"
    }
}

Colours are #RGB, #RGBA, #RRGGBB or #RRGGBBAA; null unsets one. tokenColors and semanticTokenColors (syntax colours) are read past. Every colour a theme does not set takes Dark Modern's (for a dark theme) or Light Modern's (for a light one), so a theme can set as few colours as it likes. The ids are VS Code's where VS Code has the colour, ecliptic.* otherwise; they are all at the end.

Themes are chosen with Preferences: Color Theme (Ctrl+K Ctrl+T), which previews each as the selection moves, or in settings: workbench.colorTheme, and workbench.preferredDarkColorTheme and workbench.preferredLightColorTheme while window.autoDetectColorScheme follows the desktop. workbench.colorCustomizations overrides colours on top of any theme, or one theme's: { "[Night]": { "focusBorder": "#FF0" } }.

configuration

"configuration": {
    "title": "Change Stats",
    "properties": {
        "changeStats.largeChange": { "type": "integer", "default": 200, "minimum": 1,
                                     "description": "Lines from which a file is marked." },
        "changeStats.mode": { "type": "string", "enum": ["lines", "files"], "default": "lines" }
    }
}

Types: boolean, integer and number (with minimum, maximum), string, string with enum, and array of strings. The settings appear in the Settings editor under the title, are stored in settings.json, and are checked as the built-in ones are: a value of the wrong type takes the default and the problem is shown. Its process gets its settings in initialize and again in configuration/changed.

commands

"commands": [
    { "command": "changeStats.showSummary", "title": "Show Summary",
      "category": "Change Stats", "icon": "$(graph)" },
    { "command": "changeStats.gitk", "title": "Open in gitk",
      "exec": ["gitk", "--all"] }
]

A command shows in the Command Palette (Ctrl+Shift+P or F1) as Category: Title. Running it starts the extension's process if it is not running, and sends it command/execute.

exec is ecliptic's own: the command runs that program instead, in the repository it was run on, with ${repository}, ${path} (relative), ${file} (absolute) and ${hash} replaced. It needs no process.

Icons are codicons by name: $(graph), $(beaker), $(git-commit). Every codicon is there.

menus

"menus": {
    "scm/resourceState/context": [{ "command": "changeStats.fileStats", "when": "scmResourceState != D" }],
    "scm/historyItem/context":   [{ "command": "changeStats.blame" }],
    "scm/title":                 [{ "command": "changeStats.showSummary" }],
    "commandPalette":            [{ "command": "changeStats.fileStats", "when": "false" }]
}

The entries follow the built-in ones, which the settings ecliptic.menu.file, ecliptic.menu.commit and ecliptic.menu.column list by command id; a user can drop or reorder those, not an extension's.

when clauses take context keys, ==, != (values bare or quoted), !, &&, || and parentheses. Keys: scmResourceState (the status letter: M, A, D, R, C, T, U, !), scmResourceGroup (index, workingTree), scmHistoryItem, sideBarVisible, activeViewlet, settingsEditorOpen, drawerOpen. A clause that cannot be read is false.

keybindings

"keybindings": [{ "command": "changeStats.showSummary", "key": "ctrl+alt+s", "when": "!settingsEditorOpen" }]

VS Code's spelling, chords included (ctrl+k ctrl+s); linux wins over key. An extension's keybinding wins over a built-in one with the same keys, and the user's keybindings.json wins over both (it can also remove an extension's binding, with "command": "-id"). args are passed to the command. File → Keyboard Shortcuts lists them all with their source.

viewsContainers, views, viewsWelcome

"viewsContainers": { "activitybar": [{ "id": "changeStats", "title": "Change Stats", "icon": "$(graph)" }] },
"views": { "changeStats": [{ "id": "changeStats.biggest", "name": "Biggest Changes" }] },
"viewsWelcome": [{ "view": "changeStats.biggest", "contents": "No changed files in any column." }]

A container is an icon in the Activity Bar that opens the side bar on its views, one section each. The views' items come from the extension's process (view/setItems); until it sends some, a view shows its welcome text. Showing a container starts its extension.

The extension's process

main names an executable inside the extension's folder, started in that folder. One that is not executable runs through the interpreter its file extension names: .py python3, .js node, .sh sh, .rb ruby, .pl perl, .lua lua. It starts on its activation event (* or onStartupFinished: when the app starts; onCommand:<id>, onView:<id>), when one of its commands runs, or when its container shows.

The app and the process exchange JSON-RPC 2.0 messages, one JSON object per line, over the process's stdin and stdout. What it writes to stderr goes to the app's log (RUST_LOG=info). A request has an id and is answered by a response with the same id; a notification has none.

The process runs as the user, like VS Code's extensions: install only extensions you trust. It never slows the app down: messages to it queue in a thread of their own (and are dropped, with a warning, if it stops reading), and its messages are read on another. If it exits, it is marked Crashed in the Extensions view, its status bar items, views and decorations go, and the notice bar says so; turning the extension off and on again starts it again. Everything it sends is checked: a message that is not one is logged, a method the app does not know is answered with an error.

From the app

initialize (request), first:

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{
  "extensionId":"ecliptic-examples.change-stats",
  "extensionPath":"/home/me/.local/share/ecliptic/extensions/change-stats",
  "appVersion":"0.1.0",
  "settings":{"changeStats.largeChange":200,"changeStats.statusBar":true}}}

Answer it to start receiving anything else; the answer may subscribe to events at once:

{"jsonrpc":"2.0","id":0,"result":{"subscriptions":["repositories","selection"]}}

repositories/changed (after subscribing to repositories): every column's repository and changed files, at once and then at most every quarter second while they change.

{"jsonrpc":"2.0","method":"repositories/changed","params":{"active":0,"columns":[
  {"column":0,"repository":"/home/me/src/app","name":"app","branch":"main","ahead":0,"behind":2,"unseen":3,
   "files":[{"path":"src/main.rs","origPath":null,"staged":null,"unstaged":"M","added":12,"removed":3,"binary":false}]}]}}

selection/changed (after subscribing to selection): the active column and what is selected in it.

{"jsonrpc":"2.0","method":"selection/changed","params":{"column":0,"repository":"/home/me/src/app",
  "file":{"path":"src/main.rs","staged":false},"commit":null}}

configuration/changed: its settings, when one of them changed.

command/execute (request): one of its commands was run, with its arguments (a file's or a commit's from a menu, the active column's repository otherwise, a keybinding's args, a view item's arguments). Answer with a result, or with an error, which the notice bar shows.

{"jsonrpc":"2.0","id":3,"method":"command/execute","params":{"command":"changeStats.fileStats",
  "arguments":{"repository":"/home/me/src/app","path":"src/main.rs","status":"M","staged":false}}}

shutdown: before the app quits or turns the extension off; then its stdin closes. It should exit.

From the extension

Each of these may be sent as a notification, or as a request to hear whether it worked.

A view Item is { "id"?, "label", "description"?, "tooltip"?, "icon"?: "$(name)", "command"?: "<id>" | { "command", "arguments" }, "collapsibleState"?: "expanded" | "collapsed", "children"?: [Item] }. A click on an item with children folds it open or shut; on one without, runs its command.

A minimal extension

#!/usr/bin/env python3
import json, sys

def send(m):
    m["jsonrpc"] = "2.0"
    print(json.dumps(m), flush=True)

for line in sys.stdin:
    m = json.loads(line)
    if m.get("method") == "initialize":
        send({"id": m["id"], "result": {"subscriptions": ["repositories"]}})
    elif m.get("method") == "repositories/changed":
        n = sum(len(c["files"]) for c in m["params"]["columns"])
        send({"method": "statusBar/set", "params": {"id": "n", "text": f"$(files) {n}"}})
    elif m.get("method") == "shutdown":
        break

Built-in commands

Any extension may run these with commands/execute, bind keys to them, or put them in menus.

Colour ids

What a theme can set, and the defaults (a dark theme's missing colours are Dark Modern's, a light theme's Light Modern's).