Plugins

Para que serve

Um plugin acrescenta comandos ao PrumoGrid sem mudar o aplicativo. Ele chega como um arquivo .prumoplugin, um pacote com um manifesto e código JavaScript que roda no Node que já vem com o PrumoGrid. Depois de instalado e habilitado, cada comando vira um botão no cartão da extensão, com o título que o desenvolvedor escolheu. A API 1 permite listar os projetos cadastrados, abrir um PowerShell num projeto, mostrar uma mensagem e guardar dados próprios do plugin. Um time pode, por exemplo, distribuir um plugin que abre um terminal de diagnóstico em cada projeto com os comandos que todo mundo usa.

Quando usar e quando não usar

Use um plugin quando uma ação se repete e cabe num botão: abrir um terminal com um comando pronto, conferir o ambiente de um projeto, juntar informação dos projetos cadastrados.

Não instale plugins de quem você não conhece. O código de um plugin roda com os direitos da sua conta: pode ler arquivos, acessar a rede e executar programas. Para orientar agentes, use Regras e Papéis; para sequências de etapas, Rotinas. Plugins não criam etapas nem falam com os agentes.

Passo a passo

Instalar e habilitar

1. Abra Ferramentas → Extensões…. A seção Extensões das Opções avançadas diz que você instala um pacote .prumoplugin do desenvolvedor e que atualizações exigem nova habilitação.
2. Clique em Instalar pacote… e escolha o arquivo. Confira o nome na confirmação e instale.
3. O cartão da extensão aparece como Desabilitada. Instalar não executa nada.
4. Clique em Habilitar. A pergunta pede que você confie no autor e mostra os Recursos declarados pelo pacote. Leia e confirme só se confia.
5. O cartão passa a Habilitada e mostra um botão para cada comando. Não há um botão genérico "Executar".

Usar um comando

1. Clique no botão do comando no cartão da extensão.
2. Na primeira vez, o PrumoGrid inicia o processo do plugin e chama o código dele.
3. Confira o que o comando produziu: uma mensagem com o nome da extensão ou um terminal novo.
4. Comando concluído. confirma que o plugin respondeu. Se ele abriu um terminal, olhe a saída nesse terminal para saber se o programa rodou com sucesso.

Atualizar, desabilitar e remover

Desabilitar ou remover não encerra os terminais que o plugin abriu; eles são seus. Um pacote com outro ID vira outra extensão, com dados separados. Não é preciso reiniciar o PrumoGrid para instalar, habilitar ou atualizar.

O que aparece na tela

Ampliar captura ↗

Confiança e segurança

Antes de habilitar, leve a sério a pergunta de confiança:

• O código roda com os direitos da sua conta. As permissões do manifesto controlam o que o plugin pode pedir ao PrumoGrid, como listar projetos ou abrir terminais. Elas não limitam o que o Node pode fazer por conta própria.
• Cada plugin roda num processo separado. Isso isola falhas: um plugin que trava não derruba a janela. Não é uma sandbox de segurança.
• O nome e o autor são declarados pelo próprio pacote, sem certificação. Prefira plugins com código publicado para revisão.
• Alterar o arquivo instalado por fora invalida a habilitação. Reinstale de uma origem conhecida e habilite de novo.
• Os plugins não recebem as variáveis de identidade dos agentes que rodam nos terminais.

Perfil e dados

A instalação, a habilitação e os dados de cada plugin ficam no perfil atual, normalmente em %APPDATA%\TerminalGrid\extensions. Um plugin instalado num perfil não aparece em outro. Se você usa perfis separados com a variável TG_PROFILE, instale o plugin em cada perfil que precisar dele. Ao reabrir o PrumoGrid no mesmo perfil, os comandos continuam disponíveis; o processo do plugin só inicia quando você clica no primeiro comando.

Criar o seu plugin

O plugin vive numa pasta ou repositório seu. Não precisa dos fontes do PrumoGrid, de pull request nem de aprovação. São três arquivos:

• extension.json, o manifesto: ID no formato autor.nome, versão, apiVersion: 1, permissões e a lista de comandos com o título de cada botão.
• index.cjs, que exporta activate(api) e registra uma função para cada comando declarado.
• empacotar.mjs, o empacotador independente do guia, que junta os dois num .prumoplugin. Ele precisa do Node.js 22 ou superior e não usa npm install.

O tutorial completo, com o código do exemplo Diagnóstico do projeto, o empacotador e o pacote pronto para baixar, está no guia de plugins. Para mudar um plugin, mantenha o mesmo ID, aumente a versão, gere o pacote e instale de novo; editar o index.cjs não muda a cópia instalada.

Dicas

• Leia os Recursos declarados antes de habilitar. Um plugin que só mostra uma mensagem não deveria pedir para abrir terminais.
• Se um comando demora, mova o trabalho pesado para o terminal que o plugin abre. O comando tem prazo curto para responder.
• Para conferir o resultado de um comando que abre terminal, leia a saída do terminal. Comando concluído. só diz que o plugin respondeu.

Limites conhecidos

• API 1: até 30 comandos por extensão e pacote de até 2 MiB.
• A ativação e cada comando têm até 15 segundos para responder.
• O plugin abre só PowerShell, num projeto existente, e não lê a saída nem as conversas dos terminais.
• Não há catálogo remoto, atualização automática, verificação de assinatura nem painéis HTML. Pacotes VSIX e a API do VS Code não são aceitos.
• O instalador não roda npm install: dependências precisam estar embutidas no index.cjs.