# IDE web de extensões

> Como usar a IDE do CatSuite no navegador para criar extensões do zero ou a partir de exemplos, validar, simular, inspecionar e exportar pacotes .catplug.

- Idioma: pt-BR
- URL canônica: https://netcattest.com/catsuite/docs/extensoes/ide
- Seção: Extensões
- Atualizado: 2026-10-06
- Outro idioma (en): https://netcattest.com/catsuite/en/docs/extensions/ide

A [IDE de extensões](https://netcattest.com/catsuite/ide) é 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:

| Opção | O que acontece |
|---|---|
| **Continuar de onde parei** | Reabre o projeto salvo neste navegador, com nome, ID, versão, quantidade de arquivos e horário do último salvamento. Só aparece quando existe um projeto salvo. |
| **Criar do zero** | Gera um projeto em branco com `manifest.json` e um `main.js` vazio. Você informa o nome, o nome no outro idioma, o ID e o autor. |
| **Começar de um exemplo** | Abre um dos modelos prontos, todos testados no simulador com dados fictícios. |
| **Importar .catplug** | Abre um pacote exportado pelo aplicativo ou pela própria IDE. |

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

> [!AVISO]
> A IDE guarda um projeto por navegador. Criar, abrir um exemplo ou importar substitui o projeto salvo, e por isso a IDE sempre pede confirmação antes. Exporte o `.catplug` para manter uma cópia.

### 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:

```json
{
  "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

| Exemplo | Demonstra | Permissões |
|---|---|---|
| Modelo básico | comando, aba nativa, campo e armazenamento | `commands`, `ui.tab`, `storage` |
| Marcador de requests | hooks `onRequest` e `onResponse` no laboratório | `traffic.read`, `traffic.modify`, `ui.tab`, `storage`, `commands` |
| Auditor de cache | envios, API externa simulada, menu e achado com evidência | `traffic.read`, `http.send`, `external.call`, `findings`, `storage`, `ui.menu`, `ui.tab`, `commands` |
| Etapa de fluxo | etapa com checkpoint e parser JSON | `pipeline.step`, `parsers`, `traffic.read` |
| Painel de componentes | todos os componentes nativos de interface | `ui.tab`, `commands`, `storage` |

## Áreas da IDE

| Área | Função |
|---|---|
| Arquivos | lista do pacote, criação, renomeação e exclusão de arquivos |
| Permissões | caixas de seleção que atualizam `permissions` no `manifest.json` |
| Referência do SDK | APIs do `cat` com filtro e trechos prontos para inserir no código |
| Modelos | troca o projeto atual por um exemplo |
| Editor | realce de sintaxe, números de linha e marcação de problemas |
| Problemas | erros, avisos e dicas da validação, com atalho para a linha |
| Console | registros de `cat.log`, envios simulados e falhas de execução |
| Laboratório | captura de requests fictícias para testar hooks de proxy |
| Prévia | abas registradas pela extensão, renderizadas como no aplicativo |
| Inspetor | hooks, comandos, menus, etapas, parsers e dados salvos |
| Achados | achados registrados, com severidade, confiança, estado e evidência |

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

## Editor e atalhos

| Atalho | Ação |
|---|---|
| `Tab` e `Shift` + `Tab` | indentar e remover indentação |
| `Enter` | nova linha mantendo a indentação |
| `Ctrl` + `S` | salvar no navegador |
| `Ctrl` + `Enter` | validar e executar no simulador |
| `Esc` e depois `Tab` | sair do editor pelo teclado |

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](https://netcattest.com/catsuite/docs/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.

```json
{
  "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](https://netcattest.com/catsuite/docs/extensoes/vscode).

> [!DICA]
> Comece pelo modelo básico, rode no simulador e só então adicione permissões. A validação aponta cada permissão declarada que o código não usa.

## 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](https://marketplace.visualstudio.com/items?itemName=NetCatTest.catsuite-studio)
- [Código-fonte na pasta catsuite-vscode do GitHub](https://github.com/netcattest/catsuite/tree/main/catsuite-vscode)
- [Guia completo do CatSuite Studio](https://netcattest.com/catsuite/docs/extensoes/vscode)

## Próximos passos

- [CatSuite Studio para VS Code](https://netcattest.com/catsuite/docs/extensoes/vscode)
- [Manifesto e pacote .catplug](https://netcattest.com/catsuite/docs/extensoes/manifesto)
- [Referência da API JavaScript](https://netcattest.com/catsuite/docs/extensoes/api)
- [Interface, dados e achados](https://netcattest.com/catsuite/docs/extensoes/interface-e-dados)