Plugins

What it's for

A plugin adds commands to PrumoGrid without changing the app. It comes as a .prumoplugin file, a package with a manifest and JavaScript code that runs on the Node that ships with PrumoGrid. Once installed and enabled, each command becomes a button on the extension's card, with the title the developer chose. API 1 lets a plugin list the registered projects, open a PowerShell in a project, show a message and store its own data. A team can, for example, distribute a plugin that opens a diagnostics terminal in each project with the commands everyone uses.

When to use it and when not to

Use a plugin when an action repeats and fits in a button: opening a terminal with a ready-made command, checking a project's environment, gathering information from the registered projects.

Don't install plugins from people you don't know. A plugin's code runs with your account's rights: it can read files, access the network and run programs. To guide agents, use Rules and Roles; for sequences of stages, Routines. Plugins don't create stages and don't talk to agents.

Step by step

Install and enable

1. Open Tools → Extensions…. The Extensions section of the Advanced options says that you install a .prumoplugin package from the developer and that updates require enabling it again.
2. Click Install package… and choose the file. Check the name in the confirmation and install.
3. The extension's card appears as Disabled. Installing does not run anything.
4. Click Enable. The question asks you to trust the author and shows the package's Declared capabilities. Read them and confirm only if you trust it.
5. The card switches to Enabled and shows one button for each command. There is no generic "Run" button.

Use a command

1. Click the command's button on the extension's card.
2. The first time, PrumoGrid starts the plugin's process and calls its code.
3. Check what the command produced: a message with the extension's name or a new terminal.
4. Command completed. confirms that the plugin responded. If it opened a terminal, look at the output in that terminal to know whether the program ran successfully.

Update, disable and remove

Disabling or removing does not end the terminals the plugin opened; they are yours. A package with a different ID becomes a different extension, with separate data. You don't need to restart PrumoGrid to install, enable or update.

What you see on screen

Enlarge screenshot ↗

Trust and security

Before enabling, take the trust question seriously:

• The code runs with your account's rights. The manifest's permissions control what the plugin can ask PrumoGrid for, such as listing projects or opening terminals. They don't limit what Node can do on its own.
• Each plugin runs in a separate process. That isolates failures: a plugin that hangs does not bring down the window. It is not a security sandbox.
• The name and author are declared by the package itself, with no certification. Prefer plugins whose code is published for review.
• Changing the installed file from outside invalidates the enablement. Reinstall from a known source and enable it again.
• Plugins don't receive the identity variables of the agents running in the terminals.

Profile and data

The installation, the enablement and each plugin's data live in the current profile, usually in %APPDATA%\TerminalGrid\extensions. A plugin installed in one profile does not show up in another. If you use separate profiles with the TG_PROFILE variable, install the plugin in each profile that needs it. When you reopen PrumoGrid in the same profile, the commands are still available; the plugin's process only starts when you click the first command.

Build your own plugin

The plugin lives in a folder or repository of your own. It does not need PrumoGrid's source code, a pull request or approval. There are three files:

• extension.json, the manifest: ID in the autor.nome format, version, apiVersion: 1, permissions and the list of commands with each button's title.
• index.cjs, which exports activate(api) and registers a function for each declared command.
• empacotar.mjs, the guide's standalone packager, which bundles the two into a .prumoplugin. It needs Node.js 22 or later and does not use npm install.

The complete tutorial, with the code of the Diagnóstico do projeto example, the packager and the ready-to-download package, is in the plugin guide. To change a plugin, keep the same ID, bump the version, build the package and install it again; editing index.cjs does not change the installed copy.

Tips

• Read the Declared capabilities before enabling. A plugin that only shows a message should not ask to open terminals.
• If a command takes a while, move the heavy work into the terminal the plugin opens. The command has a short deadline to respond.
• To check the result of a command that opens a terminal, read the terminal's output. Command completed. only says the plugin responded.

Known limitations

• API 1: up to 30 commands per extension and packages of up to 2 MiB.
• Activation and each command have up to 15 seconds to respond.
• The plugin opens only PowerShell, in an existing project, and does not read the output or the conversations of the terminals.
• There is no remote catalog, automatic update, signature verification or HTML panels. VSIX packages and the VS Code API are not accepted.
• The installer does not run npm install: dependencies must be bundled into index.cjs.