Plugins and bundles

DataMind Oda is built from plugins, and a bundle groups plugins together. The Plugins page shows what this installation runs: the plugins and feature bundles Oda ships with, and the bundles you have installed. Here you switch them on or off, look inside a bundle, and open the settings a plugin brings. This page also covers what happens underneath when Oda installs, switches or removes a bundle: what each switch records, what an install checks and reports, and where its errors and logs live.

What the Plugins page shows

Open Plugins in the sidebar. In the web app it sits under Global panels. The page is part of Oda's developer surface: it appears once the Plugins page feature is on in Settings > Developer > Advanced features; Advanced features covers that switch.

• The Official group lists the feature bundles and built-in plugins Oda ships with; the Installed group lists the bundles added on this computer.
• Each row shows the name, description and icon its package declares, read before the plugin runs.
• The switch on a row records your saved choice. It is not a report that the plugin loaded: a bundle that failed to load keeps its row, with its error, and cannot be switched back on until it is repaired.
• A few rows manage Oda itself and stay read-only, even if their own files become unreadable, so the parts of Oda that manage plugins stay visible. Oda refuses to switch them off or uninstall them: Plugin management needs it; it cannot be switched off or uninstalled.
• For what is loaded right now, open Settings > Built-in plugins, a read-only list; Built-in plugins covers it.

Switch a plugin or a bundle on or off

1. Open Plugins in the sidebar.
2. Find the row of the plugin or the bundle.
3. Flip its switch.

• A plugin switch edits one entry. It updates the last entry for that plugin in the settings file this computer keeps (The Oda settings file); comments and expressions already in the file stay as they are, and switching twice ends where you started. When the file's entry for the plugin is not clear, Oda adds a clear one instead of guessing.
• A bundle switch changes the ordered bundle list. Switching a bundle on adds it at the end, and that order can change which setting wins, so one bundle can change how another setting resolves. Switching it off keeps the package installed.
• The change reaches every chat in this installation, including chats already open. Where live apply is on, it takes effect while Oda runs; otherwise the row reports The change takes effect at the next start. Hot reload covers which case you are in.
• If a switch fails, the row reports it: Could not enable: {reason} or Could not disable: {reason}.

Look inside a bundle

Open the bundle: select View on its row and its page lists its Components.

• The summary counts them: {count} total, {count} running, {count} off, {count} failed.
• Each part shows its own state and its own switch, Enable component; switching a part changes only that part.
• Filter components narrows the list, and with nothing matching it reads No component matches.
• A package that brings no parts reads This plugin pack contains no components.

Change a plugin's settings

Some plugins and bundles bring settings you edit from their page.

1. Open the plugin or bundle and open its settings.
2. Edit the fields you need.
3. Choose Save.

• An edit stages in the page until you save; leaving the page drops what you have not saved.
• A value you override carries an Overridden badge, and Reset to default puts the base value back.
• An invalid value shows the reason and blocks saving until you correct it.
• When Oda runs with live apply, a saved change takes effect while Oda runs. Live plugin settings covers the forms; Hot reload covers the timing.

Add a plugin

1. On the Plugins page, choose Add plugin.
2. In Package name or address, enter the plugin's package name, a GitHub repository address, or the path to a local folder on this computer.
3. Choose Install. Oda checks the address first, with Checking…, then downloads and installs the package.
4. When the run finishes, choose Enable now to switch the new plugin on, or Done to leave it installed and off.

• Registry beside the field names where the package is fetched from, and your last choice starts the next dialog.
• If a dependency wants to run install scripts, Oda lists them and waits; Allow these scripts and retry allows the scripts still waiting. They then run with your permissions, so allow only what you trust.
• A failed or cancelled install puts the package records back. Install a plugin follows the whole dialog step by step.

When Oda changes plugins for you

You can ask Oda in a chat to install, switch or remove a plugin. Every one of these actions needs Full access or your approval for that single call, and a lower access mode asks first; approving does not change the chat's access mode, and a declined, cancelled or unavailable approval changes nothing. Installing runs plugin code with your permissions, so approve only what you trust. When Oda needs more access covers approvals.

Ask Oda to install the package you name: Oda performs the install itself, reading and checking the package, adding it, and switching the new bundle on. Do not install the package with package-manager commands.

• Refused before anything runs. Oda refuses a package it cannot accept and names the reason: an empty name; a local path that is not absolute; a web address that is not a git repository or a tarball; a name the package source would not accept; or a version left empty after @. A refusal installs nothing.
• The stages of an install. While it runs, the install reports its stage: installing while the package is fetched and installed, cancelling while a cancellation is settled, and applying once it has passed the point where it can still be cancelled.
• Already present. If the package is already on this computer as a dependency, the install answers restart-required: the change is saved and takes effect after a restart.
• Not a bundle. A package that declares no plugins for Oda is not added as a bundle: Oda reports it and puts the package records back.

Where Oda gets a package

• Your source first. Oda tries the source you named first when it is one of the sources this installation allows.
• A private source is asked alone. Oda never falls through from a private source to a public one, so a package that lives only in a private source is never fetched from a public one.
• Only some failures move on. A network failure, a timeout, or the package or version not being found can change with another source, so Oda tries the next one; any other failure stops the attempt.
• Every attempt is reported. The result names each source Oda asked, so you can see where it stopped.

When a package wants to run build scripts

Some packages run their own build steps during an install. Oda does not run them on its own: it lists them and waits, and they run only after you approve them. Approve only scripts you have seen.

Oda approves the exact scripts still listed as waiting. Approving a script that is no longer waiting refuses the whole approval and writes nothing, so approve from the list as it stands.

Cancel an install

While an install runs, you can ask to stop it. The answer tells you where it stopped:

• cancelled: it stopped in time, and the package manifest and lockfile were put back as they were.
• too-late: it had already passed the point of cancellation, so it finishes applying.
• not-running: there was nothing left to cancel.

When an install fails

• The records are put back. Oda returns the package manifest and lockfile to what they were, so a failed install leaves the app as it was. Files already downloaded can stay.
• What went wrong is named. Oda reports one of these kinds: the package manager was not found; the wait timed out; the package was not found; no version matched; the network failed; the disk is full; a permission was refused; the package's build scripts were blocked; a package failed its integrity check; or something else.
• The log is kept. Oda keeps the full log of each operation on this computer, while the report in the app is shorter. When you ask for help, keep the report.

Remove a bundle

1. Open the bundle and choose Uninstall.
2. Confirm in the dialog, which asks Uninstall "{name}"? and explains What it provides goes away once it is uninstalled.

Oda unloads the bundle's parts before it removes the package.

• Oda refuses to remove a bundle it manages itself, a bundle Oda needs at start-up, a bundle whose parts are still active and cannot be unloaded, or one a higher-priority setting keeps active: Other configuration still uses this bundle's components; switch them off first.
• A refused removal changes nothing. A removal that fails partway can keep the changes that landed; Oda reports what is left.

When a plugin is broken

A bundle that fails to load stays where it is: its row reads Problem with a Reason, and its switch keeps your saved choice. You can switch it off, and switching it back on is refused until it is repaired. Do not install a second copy to fix it: repair or remove the same bundle.

A part inside a bundle can fail on its own, and it reads Problem in the parts list too.

Questions, answered

What is a bundle, and how is it different from a plugin?

A plugin is one of the parts Oda is built from, and a bundle groups plugins together into one package with one switch. On the Plugins page you meet them side by side: Oda's own under Official, the bundles added on this computer under Installed. Switching a bundle moves its parts together; switching a single plugin changes only that one.

Why can I not find the Plugins page?

The page is part of Oda's developer surface, so it stays hidden until the Plugins page feature is on in Settings > Developer > Advanced features. Advanced features covers the switch and its risks.

What do the states beside a plugin mean?

A row or a part can read Running (loaded and working), Loading, Waiting for dependencies (something it needs has not started yet), Unloading, or Problem (it failed). A Problem row names its reason, and switching it back on is refused until it is repaired.

What does the switch next to a plugin record?

Your saved choice, not whether the plugin loaded. That is why a broken bundle keeps a switch that still shows what you chose; the error shows on the row itself. The choice belongs to this installation, so it stays across restarts and applies to every chat.

How do I see what is inside a bundle?

Open the bundle and read its Components: a summary count, each part's state, and each part's own switch. Filter components narrows the list; a package that brings no parts reads This plugin pack contains no components.

Can I change a plugin's settings from the Plugins page?

Yes, for plugins that bring settings. Open the plugin or bundle and open its settings: edits stage until you choose Save, an overridden value carries an Overridden badge with Reset to default, and leaving the page drops unsaved edits. Live plugin settings covers the values you change while Oda runs.

Why was my package refused before anything was installed?

Oda reads the package you named before anything is downloaded, and refuses one it cannot accept: an empty name, a local path that is not absolute, a web address that is not a git repository or a tarball, a name the package source would not accept, or a version left empty after @. A refusal installs nothing.

Where does Oda look for the package, and in what order?

The source you named first, when it is one of the sources this installation allows. From a private source Oda never falls through to a public one. A network failure, a timeout, or the package or version not being found moves the attempt to the next source; any other failure stops it, and the result names every source Oda asked.

Why was my build-script approval refused?

Oda approves only the scripts still listed as waiting. A script that is no longer waiting refuses the whole approval and writes nothing, so read the list as it stands and approve only what is on it.

How do I remove a bundle?

Open the bundle and choose Uninstall, then confirm. Oda unloads the bundle's parts before the package is removed. Oda refuses a bundle it manages itself, one it needs at start-up, one whose parts are still active, or one a higher-priority setting keeps active.

Why does the page say it could not read all plugins?

Oda could not read every plugin's details, usually because of a network problem. Choose Retry to read them again.

Do my installed plugins survive an update?

Yes. Installed packages and their saved state are kept across restarts and app updates, so your bundles stay where they were. Oda also keeps the full log of each install on this computer, to check later when you ask for help.