Skip to main content

Module plugin

Module plugin 

Source
Expand description

Alfred-style plugin host.

pop-launcher already has a plugin system, and it keeps working — anything installed under /usr/lib/pop-launcher/plugins shows up for free through the service. But writing one means implementing the full stateful IPC protocol (indices, activation, context menus, cancellation), which is far more than a shell script should have to do.

This host covers the other end of that range: a manifest plus an executable that receives the query on argv and prints JSON. It is deliberately a subset of Alfred’s Script Filter format so existing workflow scripts mostly port by changing the manifest.

§Layout

~/.local/share/jump/plugins/github/
  manifest.toml
  search.sh
name = "GitHub"
description = "Search your repositories"
keyword = "gh"          # optional; omit to run on every query
query = "./search.sh"   # invoked as: query <text>
activate = "./open.sh"  # invoked as: activate <arg>
icon = "github"         # optional icon-theme name or path
timeout_ms = 1000       # optional; up to 3000 for slow keyworded plugins

Items may carry Alfred’s uid (a stable identity, which is what feeds the launcher’s frecency ranking) and autocomplete (text that replaces the query on Tab).

§Isolation

A plugin is an arbitrary program on the interactive path, so it is held to a hard deadline. Exceeding it (180 ms by default, raised for a keyworded plugin with timeout_ms) kills the process and drops its results rather than delaying the frame — a broken plugin degrades its own results and nothing else.

Structs§

LintReport
What lint found. Errors stop the plugin working; warnings do not.
Manifest
Parsed manifest.toml.
Plugin
A discovered plugin: its manifest plus the directory it lives in.
PluginHost
All discovered plugins.
QueryResults
A completed plugin query: the items, plus how long until the plugins that asked to be re-run should see the same query again.

Functions§

is_keyword
Whether text can be a plugin keyword: one non-empty word. A keyword is matched up to the first space of the query, so one containing whitespace could never match. The manifest, the Settings override and the Alfred importer all hold keywords to this.
lint
Check a plugin directory: the manifest, the commands it names, and the output of one sample query against the item schema.
scaffold
Write a runnable plugin skeleton for name into a new directory under root, named by scaffold_keyword. Returns the directory and the keyword.
scaffold_keyword
The keyword, and plugin directory name, jump plugin new <name> derives from name: lowercased, with runs of whitespace joined by dashes.