# CatSuite Studio para VS Code

> CatSuite Studio para VS Code: como instalar e usar a extensão para criar, validar, testar e assinar plugins .catplug com sugestões do SDK do CatSuite.

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

O **CatSuite Studio** é a extensão oficial do CatSuite para o **Visual Studio Code**. Com ela você escreve plugins JavaScript, comandos e fluxos para o aplicativo CatSuite sem sair do editor: sugestões do **SDK** ao digitar `cat.`, modelos prontos, **validação** do projeto, **prévia local** com fixtures e geração de pacotes **`.catplug` assinados**. Esta página explica como instalar, configurar e usar cada recurso da extensão.

| Recurso | Endereço |
|---|---|
| Instalar a extensão | [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=NetCatTest.catsuite-studio) |
| Código-fonte | [Pasta catsuite-vscode no GitHub](https://github.com/netcattest/catsuite/tree/main/catsuite-vscode) |
| Licença | MIT |
| Requisito | Visual Studio Code 1.100.0 ou superior |

## O que é o CatSuite Studio e para que serve

O CatSuite Studio é uma bancada de desenvolvimento para as [extensões do CatSuite](https://netcattest.com/catsuite/docs/extensoes). Ele reúne, no VS Code, o ciclo completo de um plugin: escrever o código com ajuda do SDK, conferir manifesto e permissões, observar o comportamento em uma prévia isolada e gerar o pacote assinado que você importa no aplicativo.

É a alternativa instalável à [IDE web de extensões](https://netcattest.com/catsuite/docs/extensoes/ide). As duas falam o mesmo contrato da API v1 e produzem pacotes `.catplug`; a escolha depende de onde você prefere trabalhar.

> [!NOTA]
> O CatSuite Studio acompanha o SDK de extensões: o arquivo de tipos `catsuite.d.ts` vem dentro da extensão e alimenta as sugestões do editor. Não é preciso baixar o SDK separadamente.

## Instalação

### Pelo Marketplace

1. Abra a página do [CatSuite Studio no Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=NetCatTest.catsuite-studio).
2. Clique em **Install** e permita que o navegador abra o VS Code.
3. Confirme a instalação no editor.

### Pela visão Extensões do VS Code

1. Abra a visão **Extensões** na barra lateral do VS Code.
2. Busque por **CatSuite Studio**.
3. Confira se o publicador é a **NetCatTest** e clique em **Instalar**.

### Pela linha de comando

```bash
code --install-extension NetCatTest.catsuite-studio
```

### Requisitos

- **Visual Studio Code 1.100.0 ou superior**.
- Um **workspace confiável**: criar projetos, executar a prévia, assinar e exportar exigem que a pasta aberta esteja marcada como confiável no VS Code.
- Um aplicativo CatSuite compatível com extensões para instalar e executar os pacotes exportados.

> [!AVISO]
> Instale o CatSuite Studio apenas pelo Marketplace oficial ou a partir do [código no GitHub](https://github.com/netcattest/catsuite/tree/main/catsuite-vscode). Desconfie de arquivos `.vsix` distribuídos em outros sites.

## Primeiros passos

1. Abra uma pasta no Visual Studio Code.
2. Abra a paleta de comandos e execute **CatSuite: Criar extensão**.
3. Escolha um modelo e abra o script JavaScript de entrada.
4. Digite `cat.` para explorar o SDK e depois execute **CatSuite: Validar projeto**.
5. Execute **CatSuite: Testar com fixture local** para conferir a prévia.
6. Com o projeto pronto, execute **CatSuite: Gerar .catplug assinado** e importe o pacote em uma versão do CatSuite que suporte extensões.

Para um script rápido, sem projeto, execute **CatSuite: Novo script CatPlug**, ou crie um arquivo `.catjs` ou um `.catplug` textual vazio e digite `catplug`.

## A interface do CatSuite Studio

Depois da instalação, um ícone do **CatSuite** aparece na barra de atividades do VS Code. Ele abre duas visões:

- **Projetos** — os projetos CatSuite do workspace aberto.
- **Recursos do SDK** — os recursos do SDK disponíveis para inserir no código.

O comando **CatSuite: Ateliê CatSuite** abre o painel principal da extensão, o ponto de partida para criar, validar, testar e empacotar.

## Escrever com o SDK

- **Sugestões ao digitar `cat.`.** O editor lista as APIs do SDK com ajuda contextual, a partir dos tipos `catsuite.d.ts`. Por padrão as sugestões aparecem em qualquer linguagem; você pode limitá-las a projetos CatSuite nas configurações.
- **Modelo `catplug`.** Digite `catplug` para inserir um modelo de script pronto.
- **Inserir recurso do SDK.** O comando **CatSuite: Inserir recurso do SDK** adiciona trechos dos recursos do SDK no ponto do cursor.
- **Arquivos textuais.** Os arquivos `.catplug` e `.catjs` textuais têm edição JavaScript, realce de sintaxe, trechos e diagnósticos. Pacotes compilados abrem em um inspetor separado.

Consulte o contrato completo na [Referência da API JavaScript](https://netcattest.com/catsuite/docs/extensoes/api).

## Criar projetos e fluxos

O comando **CatSuite: Criar extensão** abre um assistente com modelos para:

- painéis e comandos;
- análise de tráfego;
- alteração de headers;
- etapas de fluxo;
- parsers.

O comando **CatSuite: Criar fluxo de exemplo** gera um arquivo `.catflow` de exemplo para os [fluxos visuais](https://netcattest.com/catsuite/docs/fluxos).

## Validar o projeto

O CatSuite Studio confere o projeto enquanto você trabalha:

- **manifesto** — identidade, script de entrada, permissões, destinos e hashes (veja [Manifesto do pacote .catplug](https://netcattest.com/catsuite/docs/extensoes/manifesto));
- **permissões e uso do SDK** — se o código usa capacidades que o manifesto declara;
- **hashes dos arquivos** — se os hashes do manifesto batem com os arquivos;
- **conexões do fluxo** — se as etapas de um `.catflow` estão ligadas corretamente.

Com a opção **validação contínua** ligada (padrão), os problemas aparecem no editor enquanto você digita. Para rodar a verificação completa, use **CatSuite: Validar projeto**. Depois de alterar arquivos, **CatSuite: Atualizar hashes do manifesto** recalcula os hashes.

Os arquivos `manifest.json`, `catsuite.projeto.json`, `.catflow` e `.catdata` também recebem validação por esquema JSON, com sugestões de campos.

## Prévia local com fixtures

O comando **CatSuite: Testar com fixture local** executa o script em uma prévia **QuickJS isolada**, com fixtures locais e APIs do host simuladas. Na prévia você inspeciona:

- as abas registradas;
- os achados gerados;
- as alterações em requests;
- os artefatos emitidos.

> [!IMPORTANTE]
> A prévia não envia requisições HTTP reais e não executa ferramentas externas. Valide o comportamento real separadamente, no seu ambiente CatSuite autorizado.

## Empacotar e assinar

O comando **CatSuite: Gerar .catplug assinado** cria o pacote final do plugin com a sua **identidade de assinatura**. O script de origem passa pelo empacotamento do projeto antes de ir para o aplicativo, e o CatSuite instalado precisa suportar o formato do pacote e a versão do SDK pedida pelo plugin.

A identidade de assinatura é gerenciada por três comandos:

| Comando | O que faz |
|---|---|
| **CatSuite: Ver identidade de assinatura** | Mostra a identidade usada para assinar os seus pacotes. |
| **CatSuite: Exportar backup protegido da identidade** | Gera um backup criptografado da identidade, para guardar ou levar a outra máquina. |
| **CatSuite: Restaurar identidade de backup** | Restaura a identidade a partir de um backup protegido. |

> [!DICA]
> Guarde o backup da identidade em local seguro. Ele permite continuar assinando pacotes com o mesmo autor depois de trocar de computador.

## Inspecionar pacotes e reconhecer autores

O comando **CatSuite: Inspecionar arquivo CatSuite** abre pacotes compilados e mostra a integridade do pacote e a impressão digital do autor. A inspeção distingue duas coisas:

- **assinatura válida** — o pacote não foi alterado depois de assinado;
- **autor reconhecido** — você já confirmou que aquela impressão digital pertence a um autor confiável.

Use **CatSuite: Reconhecer autor deste pacote** depois de conferir a impressão digital com o autor por um canal confiável, e **CatSuite: Remover autor reconhecido** para desfazer. O inspetor também abre pacotes protegidos por senha.

Para editar um plugin existente sem mexer no original, use **CatSuite: Criar cópia editável do pacote**: a extensão transforma o pacote em uma cópia de projeto e preserva o pacote original e as informações de origem.

> [!AVISO]
> Uma assinatura válida não significa que o autor é confiável. Confira a impressão digital antes de reconhecer um autor desconhecido.

## Arquivos que o CatSuite Studio entende

| Arquivo | Para que serve |
|---|---|
| `.catjs` ou `.catplug` textual | Código JavaScript para desenvolvimento |
| `manifest.json` | Identidade do plugin, script de entrada, permissões, destinos e hashes |
| `catsuite.projeto.json` | Configuração do projeto no CatSuite Studio |
| `.catplug` compilado | Pacote do plugin para inspeção e importação no aplicativo |
| `.catflow` | Definição de fluxo, com validação e inspeção |
| `.catdata` | Dados exportados do CatSuite, para inspeção |

## Todos os comandos

Abra a paleta de comandos (`Ctrl+Shift+P` no Windows e no Linux, `Cmd+Shift+P` no macOS) e digite **CatSuite** para ver a lista.

| Comando | O que faz |
|---|---|
| **Ateliê CatSuite** | Abre o painel principal da extensão. |
| **Criar extensão** | Assistente de novo projeto a partir de um modelo. |
| **Novo script CatPlug** | Cria um script avulso, sem projeto. |
| **Abrir script no editor** | Abre o script de entrada do projeto. |
| **Validar projeto** | Confere manifesto, permissões, uso do SDK, hashes e fluxos. |
| **Atualizar hashes do manifesto** | Recalcula os hashes dos arquivos no manifesto. |
| **Inserir recurso do SDK** | Insere um trecho de recurso do SDK no cursor. |
| **Criar fluxo de exemplo** | Gera um `.catflow` de exemplo. |
| **Testar com fixture local** | Executa a prévia isolada com fixtures. |
| **Gerar .catplug assinado** | Empacota e assina o plugin. |
| **Inspecionar arquivo CatSuite** | Abre um pacote ou arquivo CatSuite no inspetor. |
| **Criar cópia editável do pacote** | Converte um pacote em projeto editável, preservando o original. |
| **Ver identidade de assinatura** | Mostra a identidade de assinatura. |
| **Exportar backup protegido da identidade** | Exporta a identidade criptografada. |
| **Restaurar identidade de backup** | Restaura a identidade de um backup. |
| **Reconhecer autor deste pacote** | Marca a impressão digital do autor como reconhecida. |
| **Remover autor reconhecido** | Remove um autor da lista de reconhecidos. |
| **Aplicar estilo CatSuite** | Aplica o visual CatSuite ao editor. |
| **Restaurar estilo anterior** | Volta ao tema que você usava antes. |
| **Aplicar ícones CatSuite** | Ativa os ícones de arquivo do CatSuite. |
| **Escolher idioma** | Troca o idioma dos painéis da extensão. |
| **Abrir opções do CatSuite Studio** | Abre as configurações da extensão. |
| **Atualizar** | Recarrega as visões da extensão. |

## Configurações

Abra **CatSuite: Abrir opções do CatSuite Studio** ou procure por `catsuite` nas configurações do VS Code.

| Opção | Valores | Padrão | O que faz |
|---|---|---|---|
| `catsuite.idioma` | `sistema`, `pt-BR`, `en` | `sistema` | Idioma dos painéis, prompts e ajuda. Os comandos do VS Code seguem o idioma do editor. |
| `catsuite.validacaoContinua` | `true`, `false` | `true` | Valida manifesto, JavaScript e fluxo enquanto você edita. |
| `catsuite.estiloPainel` | `catsuite`, `editor` | `catsuite` | Estilo dos painéis do CatSuite Studio. Não muda o tema global. |
| `catsuite.autor` | texto | vazio | Autor sugerido para novos plugins. |
| `catsuite.sugestoesGlobais` | `true`, `false` | `true` | Mostra as sugestões de `cat.` e os modelos `catplug` em qualquer arquivo, inclusive fora de projetos. |

```json
{
  "catsuite.idioma": "pt-BR",
  "catsuite.validacaoContinua": true,
  "catsuite.estiloPainel": "catsuite",
  "catsuite.autor": "Equipe do Laboratório",
  "catsuite.sugestoesGlobais": false
}
```

## Temas, ícones e idioma

O CatSuite Studio traz dois temas de cores e um tema de ícones:

- **CatSuite Cyber** — o visual preto e amarelo do aplicativo;
- **CatSuite Conforto** — uma alternativa de cores para quem prefere menos contraste;
- **ícones CatSuite** — ícones dedicados para os arquivos do ecossistema.

Use **CatSuite: Aplicar estilo CatSuite** e **CatSuite: Aplicar ícones CatSuite** para ativá-los, e **CatSuite: Restaurar estilo anterior** para voltar ao seu tema. Os painéis funcionam em **português do Brasil** e **inglês**: escolha em **CatSuite: Escolher idioma** ou deixe seguir o idioma do editor.

## CatSuite Studio ou IDE web?

| Situação | Melhor opção |
|---|---|
| Testar uma ideia rápida, sem instalar nada | [IDE web](https://netcattest.com/catsuite/docs/extensoes/ide) |
| Trabalhar em um computador sem permissão para instalar extensões | [IDE web](https://netcattest.com/catsuite/docs/extensoes/ide) |
| Projetos maiores, versionados com Git | CatSuite Studio |
| Gerar pacotes assinados com a sua identidade de autor | CatSuite Studio |
| Inspecionar pacotes recebidos e reconhecer autores | CatSuite Studio |

## Problemas comuns

**As sugestões de `cat.` não aparecem.** Confira se a opção `catsuite.sugestoesGlobais` está ligada ou se o arquivo está dentro de um projeto CatSuite.

**Não consigo criar o projeto, testar ou assinar.** Essas ações exigem um workspace confiável. Marque a pasta como confiável no VS Code e tente de novo.

**O aplicativo recusou o pacote.** Verifique se a sua versão do CatSuite suporta extensões e a versão do SDK pedida pelo plugin, rode **CatSuite: Validar projeto** e gere o pacote de novo.

**A validação acusa hashes diferentes.** Execute **CatSuite: Atualizar hashes do manifesto** depois de alterar os arquivos do projeto.

**Troquei de computador e perdi a identidade.** Restaure com **CatSuite: Restaurar identidade de backup**, usando o backup protegido exportado antes.

## Continue

- [IDE web de extensões](https://netcattest.com/catsuite/docs/extensoes/ide)
- [Referência da API JavaScript](https://netcattest.com/catsuite/docs/extensoes/api)
- [Manifesto do pacote .catplug](https://netcattest.com/catsuite/docs/extensoes/manifesto)
- [Downloads e SDK](https://netcattest.com/catsuite/docs/downloads)