Seu primeiro plugin.
Do arquivo ao botão.

01 / PREPARE A PASTA

Três arquivos. Nenhum checkout do aplicativo.

Crie uma pasta chamada meu-plugin. Salve os arquivos abaixo nela, com os nomes exatos e em UTF-8. Node.js 22 ou superior é necessário para executar este empacotador; para instalar o pacote pronto, o PrumoGrid já inclui o ambiente de execução.

meu-plugin/
├── extension.json
├── index.cjs
└── empacotar.mjs

02 / DECLARE O PLUGIN

O manifesto descreve o que aparece no PrumoGrid.

{
  "id": "exemplo.diagnostico",
  "name": "Diagnóstico do projeto",
  "publisher": "Exemplo PrumoGrid",
  "version": "1.0.0",
  "apiVersion": 1,
  "description": "Lista projetos e abre um PowerShell de diagnóstico no Projeto-demo.",
  "permissions": ["code.execute", "projects.read", "terminal.create"],
  "commands": [
    { "id": "listar-projetos", "title": "1. Mostrar projetos" },
    { "id": "abrir-diagnostico", "title": "2. Abrir diagnóstico" }
  ]
}

03 / REGISTRE O COMPORTAMENTO

Cada ID declarado ganha uma função.

O PrumoGrid fornece api e chama activate quando você executa o primeiro comando. Dentro dela, commands.register liga cada ID ao seu callback. Registre os dois comandos do manifesto. Não acrescente o ID do plugin ao nome do comando.

'use strict';
// SPDX-License-Identifier: Apache-2.0
// Troque pelo nome EXATO do projeto cadastrado no PrumoGrid.
const PROJECT_NAME = 'Projeto-demo';

exports.activate = (api) => {
  // Mesmo ID declarado em extension.json → commands[].id.
  api.commands.register('listar-projetos', async () => {
    const projects = await api.projects.list();
    const names = projects.map(project => project.name).join(', ');
    await api.window.showMessage(
      `Projetos: ${names || 'nenhum cadastrado'}`.slice(0, 900)
    );
  });

  api.commands.register('abrir-diagnostico', async () => {
    const projects = await api.projects.list();
    const matches = projects.filter(project => project.name === PROJECT_NAME);

    // Não escolhe outro projeto silenciosamente.
    if (matches.length !== 1) {
      await api.window.showMessage(
        `Cadastre exatamente um projeto chamado ${PROJECT_NAME}. ` +
        'Use Mostrar projetos para conferir os nomes.'
      );
      return;
    }

    // Abre um NOVO terminal, sem escrever nos que já estão em uso.
    await api.terminal.create({
      projectId: matches[0].id,
      title: 'Diagnóstico por plugin',
      command: "Write-Output 'PrumoGrid plugin OK'; Get-Location; $PSVersionTable.PSVersion"
    });
  });
};

Este exemplo procura exatamente Projeto-demo; não usa automaticamente o projeto selecionado na tela. Se faltar esse nome ou houver duplicatas, ele avisa. Para usar outro projeto, altere PROJECT_NAME, gere um novo pacote e instale-o.

04 / GERE O PACOTE

Junte manifesto e código em um .prumoplugin.

Salve também o empacotador abaixo. Ele usa apenas módulos que vêm com o Node, confere campos básicos, sintaxe e tamanho, e gera um arquivo novo. A validação do pacote pelo PrumoGrid acontece na instalação.

// SPDX-License-Identifier: Apache-2.0
// Node.js 22+. Sem dependências e sem acesso aos fontes do PrumoGrid.
import { readFileSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { Script } from 'node:vm';

export function createPackage(directory = import.meta.dirname) {
  const manifest = JSON.parse(readFileSync(join(directory, 'extension.json'), 'utf8'));
  const source = readFileSync(join(directory, 'index.cjs'), 'utf8');
  if (manifest.apiVersion !== 1 || !/^[a-z][a-z0-9-]{0,39}\.[a-z][a-z0-9-]{0,39}$/.test(manifest.id || '')
    || !/^\d+\.\d+\.\d+$/.test(manifest.version || '')) {
    throw new Error('Confira id, version e apiVersion no extension.json.');
  }
  // Apenas verifica sintaxe. Não executa nem atesta a segurança do plugin.
  new Script(source, { filename: 'index.cjs' });
  const json = JSON.stringify({ manifest, source }, null, 2) + '\n';
  if (Buffer.byteLength(json, 'utf8') > 2 * 1024 * 1024) {
    throw new Error('O pacote excede o limite de 2 MiB.');
  }
  return { manifest, json };
}

if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
  const { manifest, json } = createPackage();
  const filename = `${manifest.id.split('.')[1]}-${manifest.version}.prumoplugin`;
  const output = join(import.meta.dirname, filename);
  writeFileSync(output, json, { flag: 'wx' });
  console.log(`Pacote criado: ${output}`);
}

No PowerShell, entre na pasta meu-plugin e execute:

node .empacotar.mjs

Resultado: diagnostico-1.0.0.prumoplugin, na mesma pasta. Não precisa de npm install, token ou chave de API. O pacote é JSON com manifest e source, até 2 MiB; renomear um ZIP não funciona.

05 / INSTALE E TESTE

Agora o aplicativo reconhece seu plugin.

1. Crie uma pasta Projeto-demo e adicione-a ao PrumoGrid em + adicionar projetos…; confira o nome no painel de projetos.
2. Abra Ferramentas → Extensões → Instalar pacote… e selecione diagnostico-1.0.0.prumoplugin.
3. O cartão Diagnóstico do projeto começa desabilitado. Clique em Habilitar, confira os recursos solicitados e confirme se confia no código.
4. Clique em 1. Mostrar projetos. A mensagem deve incluir Projeto-demo.
5. Clique em 2. Abrir diagnóstico. Feche Extensões, selecione Projeto-demo e confira o novo terminal Diagnóstico por plugin.

Ampliar captura ↗

Ampliar captura ↗

06 / ALTERE E DISTRIBUA

Mesmo ID. Nova versão. Nova instalação.

Edite os arquivos, mantenha exemplo.diagnostico e aumente version para 1.0.1. Execute o empacotador, instale diagnostico-1.0.1.prumoplugin e habilite novamente. Editar index.cjs não altera a cópia instalada. Atualizar lista apenas relê os pacotes instalados; não recompila seu plugin.

A instalação fica no perfil atual. Você não precisa copiar arquivos para a pasta do aplicativo nem editar o armazenamento interno. Para distribuir seu próprio plugin, escolha um ID próprio e envie o .prumoplugin com instruções, licença e código para revisão. A API 1 não oferece marketplace ou atualização automática.

Se não aparecer ou não executar

• Não há Extensões: confira se a janela está usando PrumoGrid 0.5.4 ou posterior.
• Botões desativados: habilite o pacote, inclusive depois de atualizar.
• Comando não registrado: compare commands[].id com commands.register, letra por letra, e confira exports.activate.
• Permissão negada: declare a permissão da API utilizada em permissions e instale o novo pacote.
• EEXIST ao empacotar: a saída já existe. Aumente a versão para gerar outro arquivo.

Plugins executam código Node com os direitos da sua conta. As permissões do manifesto controlam as APIs do PrumoGrid, não as capacidades nativas do Node. Instale somente código em que confia. Não coloque credenciais no pacote.