exbyte-depot-viewer-perforce/PLUGINS.md

Exbyte Depot — Plugins

Plugins add features on top of the core app so the base stays lean and specialised work ships (and updates) independently.

What language?

JavaScript / TypeScript. A plugin is a plain ES module that exports activate(host). Author in TypeScript if you like, then compile to a single JS file (esbuild index.ts --bundle --format=esm --outfile=index.js). No build step is required for plain JS.

Why JS and not native? The app's Rust backend is compiled and sealed; the extensible surface is the webview. Plugins run in the app's webview and reach the app only through the host object — never invoke directly.

How plugins are loaded

The app reads the plugin's entry source from disk (Rust) and imports it as an ES module from a blob: URL — no eval, and it stays inside the CSP (script-src 'self' blob:). Disabled plugins are never imported.

Anatomy

my-plugin/
  plugin.json     # manifest
  index.js        # ES module exporting activate(host)

plugin.json

{
  "id": "my-plugin",                // unique; [A-Za-z0-9-_.]
  "name": "My Plugin",
  "version": "1.0.0",
  "author": "You",
  "description": "What it does.",
  "entry": "index.js",              // must stay inside the plugin folder
  "minAppVersion": "0.3.5",
  "permissions": ["p4:read", "notify"],
  "contributes": { "menu": true, "views": ["notes"], "fileContext": true, "submitHooks": true }
}

Permissions (declared, shown to the user)

permission	grants
p4:read	read-only p4: opened, dirs, describe, changeSizes, clientSpec on host.p4
p4:write	mutating p4: add, edit, del, sync, reconcile on host.p4
notify	native notifications via host.notify

Without a permission, the matching APIs are simply absent (or no-ops). host.storage, host.clipboard, host.flash, host.info, host.t, host.theme are always available.

The host SDK

host.version                       // Host SDK version, e.g. "1.0"
host.plugin                        // { id, name, dir }
host.has(perm)                     // boolean

host.p4.<method>(...)              // Promise — only the whitelisted set your perms allow
host.info()                        // { userName, clientName, clientRoot } | null
host.selectedFile()                // { depotFile } | null
host.refresh()                     // re-read the Changes view
host.theme()                       // current theme's CSS-var overrides

host.ui.addMenuItem(label, run)                 // Actions-menu action
host.ui.addFileContextItem(label, run(file))    // right-click a file
host.ui.addView({ id, title, render(el, host) })// a panel; render into a DOM element (return an optional cleanup fn)
host.ui.addSubmitHook(run(files) => {ok, message})  // block/allow a commit

host.flash(text, isError?)         // toast
host.notify(title, body)           // native notification (needs "notify")
host.clipboard.write(text)         // Promise
host.storage.get/set/remove(key)   // per-plugin localStorage namespace
host.t(key, params?)               // app i18n
host.log(...args)                  // console, tagged with the plugin id

Theme tokens

A plugin's DOM inherits the app's CSS variables — use them so the panel follows the active theme. The exact names (a wrong name silently falls back to your hardcoded default, which then breaks on the opposite theme):

--accent --accent-2 --accent-deep · --bg --panel --panel-2 --panel-3 --elevated --border · --txt --muted --faint · --add (success) --edit (warning) --del (danger) · --mono (font)

There is no --text, --ok, --err, or --sans.

Contribution points

• Menu items and views appear in the Actions menu.
• File context items appear when you right-click a file in Changes.
• Submit hooks run before a commit is finalised; returning { ok:false, message } prompts the user to confirm or cancel. (This is exactly where a reference-integrity guard, size check, or lint would live.)

Import methods

1. Install from folder — Actions → Plugins… → Install from folder… → pick a folder that contains plugin.json. It's copied into the app's plugins folder.
2. Drop-in — Actions → Plugins… → Open plugins folder, drop my-plugin/ in there, then Reload.
3. (Planned) Registry — a signed registry (exbyte-depot-plugins repo, minisign-signed bundles) for one-click install/updates, reusing the app's updater signing infra.

Try the example

plugins-examples/hello-exbyte/ demonstrates all four contribution points plus storage, clipboard, info and notifications. Install it from folder, then:

• Actions → Say hello 👋 and Actions → Workspace Notes
• right-click a file → Copy depot path (plugin)
• try to commit a file named wip* → the submit guard warns.

Safety

Plugins run in-app on the main thread — install only ones you trust. The id is path-validated, the entry cannot escape the plugin folder, and each plugin's storage is namespaced. A plugin that throws is isolated and does not crash the app.