Plugins for Ocelot File Manager

A plugin adds commands to the context menus and the Plugins menu, columns to the list view and badges to icons. Its code is never loaded into the app as a library, so a plugin that fails becomes a disabled plugin, not a lost file operation.

There are two kinds:

JavaScript plugins: a main.js run by the app's JavaScript engine inside the app's process, one isolated context per plugin. A script gets only what the app hands it: the paths it was asked about, the tools its manifest names, its own storage. For commands, columns, badges and light integrations.
Process plugins: an executable you build in any language, started by the app in a sandbox and talking JSON-RPC over stdin and stdout. For heavy work: hashing, indexing, tools that already exist.

A process plugin and every tool a script runs work under that sandbox. It keeps them to the plugin's own folders for writing and to the network only with permission, but they can read what the app can, apart from the list in Permissions.

Page	What it covers
Manifest	Every key of `manifest.json`, the limits, what makes a manifest incompatible.
Permissions	What each permission grants, what the consent means, the sandbox every tool and process runs in.
JavaScript plugins	The `ocelot` API: commands, columns, tools, files, links, notifications, logging.
Process plugins	Building, installing, the protocol, the lifecycle.
Columns and badges	Values, types, caching, invalidation, refresh triggers.
Storage	Where a plugin keeps data between runs.
Debugging	Settings ▸ Plugins, the log, strikes and the disabled states, the sandbox self-test.
Publishing	What to ship, versions, licences, naming.

The design behind all this, with the reasons, is in PLUGINS.md. Three working plugins to copy from are in PluginSDK.

Your first plugin in ten minutes

Make a folder for it:

~/Library/Application Support/OcelotFM/Plugins/hello/

Put a manifest.json in it:

{
  "id": "com.example.hello",
  "name": "Hello",
  "version": "1.0.0",
  "runtime": "javascript",
  "hostAPI": { "min": "1.0", "max": "1" },
  "permissions": [],
  "commands": [
    { "id": "hello.say", "title": "Say Hello",
      "placement": "contextMenu",
      "availability": { "minSelection": 0 } }
  ],
  "columns": [],
  "entry": "main.js"
}

minSelection: 0 lets the command appear on the empty area of a folder as well as on a selection.

Put a main.js beside it:

ocelot.onCommand("hello.say", function (ctx) {
  ocelot.notify("Hello", ctx.directoryPath + ": " + ctx.selectionPaths.length + " selected");
});

Open Settings ▸ Plugins, press Reload All and enable "Hello". Enabling a plugin means agreeing to the permissions it lists; this one lists none.
Right-click in any folder: "Say Hello" is under Extensions. The toast shows the folder and how many items were selected.

From here, copy one of the demos: "Open in Terminal" (two commands, one for the tab menu), "Git Status" (a badge column fed by one git status per folder) or "Checksum" (a process plugin in Swift). Each plugin has a log in Settings ▸ Plugins; console.log writes to it.