Plugins

A command that does more than edit is a :run command, (fn [ctx] ...), and the plugin lists what it reaches in :effects:

(ns jonquil.plugins.shout
  (:require [clojure.string :as str]
            [jonquil.plugin :as p]))

(p/defplugin
  {:id      :shout
   :doc     "Upper-case the whole buffer."
   :effects #{:buffer :console}
   :commands
   [{:id :shout/go :doc "Upper-case the whole buffer." :scope :window
     :run (fn [ctx]
            (p/replace-text! ctx (str/upper-case (p/buffer-text ctx)))
            (p/status! ctx "Shouted."))}]
   :bindings
   [{:key "u" :mods #{:cmd :alt} :command :shout/go}]})

A :run command runs in the background on the tab that was active when it started, and its key always counts as used. One run goes at a time, and nothing stops one that never finishes short of quitting. A throw shows on the status bar and console with the plugin's id.

Calling a function whose effect wasn't declared throws "this plugin didn't declare :buffer"; a closed tab throws "that tab was closed".

Both eval functions run in the tab's namespace, wait 10 seconds by default ("the eval took longer than 10000 ms and was stopped"), and throw "the REPL is busy" if something else is running.

• p/eval! leaves the console, history and *1/*2/*3/*e alone. A throw comes back as :error. Jolt dialect only; other dialects get told to use p/repl!.
• p/repl! works like Run Selection: echoed, shown, added to history. It works everywhere.

Stopping an eval equals pressing Stop. For Jolt as a child (a project with a deps.edn), code still running a second after the interrupt makes Jonquil restart the child, and its definitions are lost.

:hooks maps a hook point to (fn [ctx event] ...). The ctx reaches only the plugin's declared effects.

A Run is Run, Run Selection or Run Form, from a key, menu, palette or an agent's jonquil_run/jonquil_run_selection. A Run that never started (REPL busy, other project's tab, unclosed bracket) fires nothing. :on-error also hears console errors, but never those from a plugin's own p/eval!/p/repl!.

Hooks other than :before-run run in the background after the fact and can't change the save or Run. At one point they run in plugin-id order, each getting the previous one's returned event (non-maps are ignored). A throw shows with the plugin's id and the next hook still runs. Up to 16 events queue while a point is busy; further ones are skipped with a console line.

:before-run is synchronous, because the Run waits for it:

(ns jonquil.plugins.no-todo
  (:require [jonquil.plugin :as p]))

(p/defplugin
  {:id      :no-todo
   :doc     "Refuse to Run code that still says TODO."
   :effects #{}
   :hooks   {:before-run (fn [_ e]
                           (if (.contains ^String (:text e) "TODO")
                             {:abort "the code still has a TODO"}
                             e))}})

A stopped Run shows ; plugin no-todo stopped this Run: the code still has a TODO on the console and status bar, sends nothing, and gives an agent's jonquil_run the same line as its error. The first abort wins. Editing :text changes nothing, and a non-sentence :abort is reported and ignored.

• All :before-run hooks together get 100 ms. If they time out or throw, the Run goes ahead with a line saying so. While a hook from an earlier Run hasn't returned, every later Run skips all :before-run hooks, with a line saying so.
• :before-run hooks can't use effects, even declared ones (p/print! etc. throw and the Run goes ahead).
• Inspect Form, the console and jonquil_eval don't ask these hooks.

Plugins load at startup, one file at a time. A broken file is skipped and the console names the problem (with a line when known). A file gets 10 seconds to load. Each :edit command is tried on sample buffers (2 seconds each) before going live, and its answer is checked on your real buffer every time it runs, so a wrong answer is refused instead of editing the wrong text.

Bindings must hold Cmd/Ctrl. Chords the window takes first are refused (Cmd+Alt+W is the window's Cmd+W). A binding that loses only some chords loads with a warning (:mods #{:cmd} on P also matches Cmd+Shift+P, the palette's), and so does a chord a built-in already uses. Plugins take keys in id order, so on a shared chord the earlier id wins and the later one gets a warning. Plugin bindings come ahead of built-in ones; their commands appear in the palette with the plugin's id.

Reload. Saving a plugin file in a tab reloads it. Reload Plugins in the palette reloads every file that changed, appeared or went away (needed for edits made elsewhere). A failed reload keeps the previous version running and your file untouched. Later plugins are rechecked, and one that now fails is removed and named until fixed.

No plugins. --no-plugins (or JONQUIL_NO_PLUGINS=1 for a Dock or Finder launch) starts with none. Reload, Enable, Disable, Revert and Accept refuse with a line saying plugins are off, and an agent can't propose one. The list, History and review still open. To keep one off persistently, add its id to settings.edn's :plugins :disabled and start normally.

The palette's Show the plugins entry lists every plugin in the right-hand panel: id, live version, loaded/disabled/not loaded, effects, pending proposal and doc (the same as jonquil_plugins_list). A plugin that fails its checks shows as not loaded, and one whose file was deleted keeps its row ("file deleted"). Select a row, then:

• Disable: writes the id into settings.edn and reloads; commands and keys go at once. The file stays.
• Enable: removes its id from :disabled and reloads through the usual checks.
• Open: the file in a tab.
• History: its versions.
• Review Proposals: pending agent proposals.

Disable writes this and keeps your other settings (you can also write it by hand, then Reload Plugins). If :plugins holds something Jonquil can't use, Enable and Disable refuse rather than overwrite it:

{:plugins {:disabled #{:wrap-when}}}

Every version that goes live is kept in plugins/.history/<id>/ (1.clj, 2.clj, ... plus history.edn with when, where from and why). Entries are never changed or removed. A new version is added when a plugin loads with text different from its latest, with the reason "edited by hand"; an edit that fails its checks isn't one. An unreadable history.edn is left alone and the plugin still loads.

History lists versions newest first (status, source: you, an agent or a revert, when, why). Select an older one, add an optional reason, press Revert. It runs the reload checks, writes the file, and records a new version ("revert to v2"), so nothing is erased. Back returns to the list.

Revert refuses, saying why in the footer, if the version was never live (proposals go through Accept), the plugin is disabled, the text is already live, or the file differs from the live version (an unreloaded or failing edit a write would lose). A tab open on the file follows a Revert or Accept: it reloads if clean, and otherwise keeps your unsaved edits with a one-time console warning that saving overwrites the version on disk. The reload is one undo step, as for any file changed on disk.

An agent proposes a change with jonquil_plugin_propose (see Driving Jonquil from an agent (MCP)). It becomes a pending version and the status bar counts the waiting ones. Review Plugin Proposals in the palette shows, in the right-hand panel: the agent's reason, whether it builds on the live version or an older one, a diff, the declared effects (new ones marked), and the checks' warnings and timings. Next steps through several.

Accept reruns the checks in Jonquil, then writes the file and makes it live. If they fail, it stays pending and the footer says why. Reject takes an optional note. The agent can read the outcome but can never Accept.

The isolated check. Before review, the proposal is checked in a separate Jolt, in a fresh temporary folder only you can open, with credential-looking environment variables removed. This is isolation from the running Jonquil, not a sandbox. The child runs as you, with your files and network, so top-level code that deletes a file deletes it during the check (no more reach than an agent has via jonquil_eval), and the scrub catches only obvious names. It could even rewrite a file Jonquil reads later, such as another plugin or settings.edn. What it can't touch before Accept is the running Jonquil: your tabs, REPL, loaded plugins and already-read settings, and it can't crash or hang the window.

• A check over 30 seconds is stopped and the agent gets that reason.
• After a timeout, no result or an error exit, the check's folder is kept for a day; the agent's answer and the History line give the path of check.log.
• With no jolt available, the proposal waits unchecked (the review says so) and its checks run on Accept.