Debugging

Settings ▸ Plugins

The pane lists every plugin found in ~/Library/Application Support/OcelotFM/Plugins with its state, its permissions (an explanation appears on hover; tools that run any program are marked) and a tail of its log. "Reveal Folder" opens the Plugins folder; "Reload All" rescans it, restarts every plugin and clears the unresponsive state.

States you will meet:

Incompatible: the manifest was refused. The log says which key, or that the hostAPI range does not include the app's version.
Disabled after errors: three strikes. A strike is a timeout, an exception thrown out of a handler, a denied API call, a malformed reply, or a process plugin's crash or failed handshake. The plugin stays disabled across Reload All and relaunch until the user enables it again; the log has the three reasons.
Unresponsive: a JavaScript call ran out of time. The app cannot stop a running script, so the plugin gets no more calls until Reload All.

The log

ocelot.log, console.log and a process plugin's stderr all land in the plugin's log. Lines are cut at 4 096 characters and capped at 100 a second; when lines are dropped, the next one says how many. The log also records every refused call with the permission it lacked, every value a column returned with the wrong type, and every manifest problem.

Builds made from source

A build made with make run watches the Plugins folder and reloads a plugin whose files changed, so editing main.js and saving is enough. Such builds also have Settings ▸ Plugins ▸ "Sandbox Self-Test…", which runs every rule of the plugin sandbox on this Mac and reports what held, and accept the launch flag -OcelotSandboxSelfTest /path/to/report.txt for the same from a terminal.

Common problems

Symptom	Cause
A command is missing from the menu	Its `availability` is not met: `minSelection` defaults to 1, so a command for the empty area needs 0; inside an archive, commands need `"schemes": ["archive"]`.
The command is there but greyed out	The same rules; `requiresWritableDirectory` in a read-only folder.
`spawn` says the tool was not found	Tools come from `/usr/bin`, `/bin`, `/usr/sbin`, `/sbin`, `/usr/local/bin` and `/opt/homebrew/bin`, never from `PATH`; the name must match the permission exactly.
The tool fails to write a file	Only `$OCELOT_PLUGIN_DATA` and `$TMPDIR` are writable; `/tmp` and the plugin's own folder are not.
The tool cannot reach the network	`network.client` is missing from the manifest.
`perl` does not start; `sips` cannot save	Known limits of the sandbox; use `python3` or a shell, and convert images in a process plugin.
A column stays empty	The provider returned values for other paths than asked, a value of the wrong type for the declared `type`, or ran out of its 2 seconds. Check the log.
A column is never asked	It is hidden (`defaultVisible: false` and not turned on by the user), or the folder is inside an archive.
The badge does not change after `git add`	The cache key is the file's path and date; name the index in `refreshWhenChanged` or call `invalidateColumn`.
`notify` does nothing	It was called from a column provider or at the top level, or the plugin passed 10 toasts in a minute.