Skip to content

plugin-development.md

Latest commit

 

History

History
139 lines (112 loc) · 4.84 KB

plugin-development.md

File metadata and controls

139 lines (112 loc) · 4.84 KB
Raw

Developing nbshell plugins

nbshell plugins are QML components loaded into the long-running shell process. They can add a bar widget, a floating panel, an overlay, or a background service without changing nbshell itself.

Creativity is welcome. The compatibility and safety rules below are not optional: plugin code runs unsandboxed with everything the current user can access.

Start from the example

Copy plugins/beispiel into a separate repository and give it a globally unique, namespaced id such as io.github.alice.weather.

Validate the directory before loading it:

nbshell plugin validate /path/to/plugin
nbshell plugin add /path/to/plugin
nbshell plugin enable io.github.alice.weather

Newly cloned third-party plugins remain disabled until the user explicitly enables them.

Manifest v2

manifest.json lives at the repository root:

{
  "schemaVersion": 2,
  "id": "io.github.alice.weather",
  "name": "Weather",
  "version": "1.0.0",
  "author": "Alice",
  "license": "MIT",
  "repository": "https://github.com/alice/nbshell-weather",
  "description": "Weather in the bar and a detailed forecast panel.",
  "kinds": ["bar-widget", "panel"],
  "hosts": ["bar", "panel"],
  "entryPoints": {
    "barWidget": "BarWidget.qml",
    "panel": "Panel.qml"
  },
  "activation": "on-demand",
  "dependencies": {
    "commands": ["curl"],
    "packages": ["curl"]
  },
  "barWidget": {
    "defaultSection": "right",
    "allowMultiple": false
  }
}

Supported kinds are:

Kind Contract
bar-widget A component hosted by the nbshell bar.
panel A floating surface with open(payloadJson) and close().
overlay A full-screen surface with open(payloadJson) and close().
service A headless, long-lived component.

hosts is optional forward-compatible placement metadata. Supported values are bar, panel, overlay, window, and service; unknown values are rejected during validation. A plugin can use it to declare every shell context its design can adapt to without creating separate packages. The host exposes the active value through an optional host property when the component declares one. Entry-point kinds remain the executable contract.

An entry point must stay inside the plugin directory. Symlinks that escape the plugin tree are rejected. activation: "on-demand" is recommended for panels and overlays so closed UI consumes no resources.

The host injects the properties a matching entry point declares: shell, manifest, service, pluginRegistry, and barWidgetRegistry. Do not mark an optional injected property as required.

Required safety rules

  • Never commit credentials, tokens, private prompts, personal paths, or user data.
  • Never install packages, run sudo, modify the boot process, or enable a system service automatically. Declare dependencies and let the user decide.
  • Do not execute an install or removal hook when the repository is cloned.
  • Pass external values as separate process arguments. Do not concatenate them into a shell command.
  • Treat message text, filenames, network responses, and catalog fields as untrusted plain text.
  • Do not fetch remote images or HTML without a visible privacy decision.
  • Store secrets in the desktop Secret Service and normal state below the XDG config, state, or cache directories. Keep secrets out of shell config.
  • A plugin must be safe to disable. Stop timers, sockets, and child processes when they are no longer needed.
  • Do not replace the lock screen, privilege agent, update trust path, or other security boundary from a community plugin.

UI and resource rules

  • Use qs.Common and qs.Widgets components or the public nbshell theme tokens. Do not hard-code a private color palette.
  • Keep visible strings and public documentation in English.
  • Support keyboard focus and Escape in panels and overlays.
  • Avoid continuously repainted Canvas animations and aggressive polling.
  • A bar widget should be quiet while it has nothing useful to report.
  • Do not create a second notification server, tray host, or other exclusive desktop service.

Testing

At minimum:

nbshell plugin validate .
bash -n scripts/*.sh
python -m py_compile scripts/*.py

Keep parsing and decision logic in testable JavaScript or small helper programs. Test malformed input as well as the happy path. A plugin intended for the curated store must also pass tests/plugin-validation.sh in an nbshell checkout.

Publishing

A public plugin repository should contain:

  • manifest.json using schema v2;
  • a README with setup, dependencies, controls, and removal instructions;
  • an OSI-approved license;
  • a preview image when the plugin has a visible UI;
  • no vendored credentials or machine-specific state.

Store inclusion is a compatibility review, not a security guarantee. Plugin authors remain responsible for their code and releases.