IDE web de extensões

A IDE de extensões é um ambiente completo para escrever, testar e empacotar extensões .catplug direto no navegador. Tudo acontece no seu dispositivo: o código não é enviado para servidores, o simulador não faz conexões de rede e o projeto fica salvo apenas neste navegador.

Começar um projeto #

Ao abrir a IDE, nada é carregado automaticamente. A tela inicial pergunta como você quer começar:

O botão Novo da barra da IDE volta para essa tela a qualquer momento, com a opção de retornar ao projeto aberto.

Criar do zero #

O ID é gerado a partir do nome: acentos são removidos, espaços viram hífens e o prefixo lab. é adicionado. Você pode editar o ID livremente, desde que siga o padrão do manifesto: de 3 a 64 caracteres, começando por letra, usando apenas minúsculas, números, ponto e hífen.

O manifesto inicial já passa na validação:

{
  "formatVersion": 1,
  "apiVersion": 1,
  "id": "lab.minha-extensao",
  "version": "1.0.0",
  "author": "Equipe de QA",
  "entry": "main.js",
  "name": {
    "pt-BR": "Minha extensão",
    "en": "My extension"
  },
  "description": {
    "pt-BR": "Descreva aqui o que a extensão faz.",
    "en": "Describe what the extension does."
  },
  "permissions": [],
  "targets": [],
  "externalHosts": [],
  "settings": {},
  "hashes": {}
}

Exemplos disponíveis #

Áreas da IDE #

Em telas pequenas, as áreas ficam organizadas em quatro guias: Arquivos, Código, Prévia e Console.

Editor e atalhos #

No macOS, use Cmd no lugar de Ctrl. O projeto também é salvo automaticamente alguns instantes depois de cada alteração.

Validação #

A validação roda a cada alteração e usa as mesmas regras de importação do aplicativo:

• campos obrigatórios do manifesto, textos em pt-BR e en, versão e ID;
• destinos de targets e externalHosts, incluindo curingas, portas e endereços privados;
• permissões declaradas comparadas com as APIs usadas no código;
• etapas e parsers com entradas http exigem traffic.read;
• APIs que não existem no QuickJS, como fetch, require e document;
• import e export, que não são suportados porque o código roda como script;
• erros de sintaxe do arquivo de entrada, verificados sem executar o código.

Erros bloqueiam a execução e a exportação. Avisos e dicas não bloqueiam.

Simulador #

Executar carrega o arquivo de entrada em um Web Worker isolado que reproduz a API v1 do SDK. O simulador usa o idioma escolhido no seletor de idioma do site: em português, cat.i18n.text e os textos bilíngues aparecem em pt-BR; em inglês, em en.

O simulador aplica as mesmas regras do aplicativo:

• cada API exige a permissão correspondente e responde E_PERMISSION quando ela falta;
• envios e APIs externas respeitam targets e externalHosts;
• hooks de alteração precisam ser síncronos e são encerrados se travarem;
• armazenamento limitado a 128 KiB por valor e 10 MiB por extensão;
• achados são consolidados pelo fingerprint.

Conectores do CatBridge não estão disponíveis no navegador e respondem E_CONNECTOR.

Dados fictícios com fixtures.json #

Envios, APIs externas e o laboratório usam as rotas do arquivo fixtures.json. Rotas que não existem respondem com um 404 simulado.

{
  "scenario": "fictional",
  "routes": [
    {
      "url": "https://api.aurora.test/api/perfil",
      "status": 200,
      "cacheControl": "public, max-age=600",
      "body": { "id": "cliente-ficticio-001", "scenario": "fictional" }
    },
    {
      "url": "https://api.aurora.test/timeout",
      "error": "E_TIMEOUT"
    }
  ]
}

Para usar cat.laboratory.capture, ative settings.laboratory no manifesto.

Exportar o pacote #

Exportar .catplug valida o projeto e gera o pacote:

1. remove a assinatura anterior, porque o conteúdo foi editado;
2. recalcula o SHA-256 de cada arquivo em hashes;
3. no formato 2, cria um novo revisionId e registra parentHash quando o projeto veio de uma importação;
4. compacta tudo em um arquivo id-versão.catplug.

Depois, importe o arquivo no aplicativo em Configurações → Extensões. O aplicativo assina o pacote novamente e mostra as permissões antes de ativar a extensão.

Segurança da IDE #

• A página bloqueia qualquer conexão de rede pela política de segurança de conteúdo.
• O código da extensão roda isolado, sem acesso à página, aos cookies ou ao armazenamento do navegador.
• fetch, XMLHttpRequest, WebSocket, importScripts, WebAssembly e o canal de mensagens do worker ficam bloqueados para o código da extensão.
• Pacotes importados passam pelos limites do formato: até 10 MiB compactados, 40 MiB expandidos, 4 MiB por arquivo e 500 arquivos, sem caminhos absolutos, .., links simbólicos ou entradas criptografadas.
• Hashes divergentes geram aviso no console e são recalculados na exportação.
• Pacotes protegidos por senha (CATSEAL2) não abrem na IDE web: abra-os no aplicativo ou inspecione-os no CatSuite Studio.

Prefere o VS Code? #

A mesma experiência existe como extensão instalável: o CatSuite Studio traz sugestões do SDK, validação, prévia local com fixtures e geração de pacotes .catplug assinados dentro do Visual Studio Code. Projetos criados na IDE web podem continuar no editor.

• Instalar o CatSuite Studio pelo Visual Studio Marketplace
• Código-fonte na pasta catsuite-vscode do GitHub
• Guia completo do CatSuite Studio

Próximos passos #

• CatSuite Studio para VS Code
• Manifesto e pacote .catplug
• Referência da API JavaScript
• Interface, dados e achados