Atlassian Forge Developer - Plugin IDE Inteligente
Um plugin WebStorm/JetBrains oferecendo autocompletion inteligente, validacao em tempo real e documentacao integrada para desenvolvimento Atlassian Forge - 83 escopos OAuth, 71 tipos de eventos, 155+ templates de projetos, totalmente modelados em Kotlin.
Linhas Kotlin
9,120
main + testes compilados
Arquivos Totais
112
112 arquivos em todas as categorias
Escopos OAuth
83
Totalmente modelados com descricoes
Templates Forge
155+
Catalogados por produto & tipo de UI
Apresentacao
Visao geral e contexto do projeto
Atlassian Forge Developer e um plugin para WebStorm (e IDEs JetBrains compativeis) que fornece suporte inteligente para desenvolvimento de aplicacoes Atlassian Forge. Oferece autocompletion contextual, realce de sintaxe avancado, validacao em tempo real e correcoes automaticas para arquivos `manifest.yml` - o arquivo de configuracao central de toda aplicacao Forge.
O plugin e destinado a desenvolvedores que constroem aplicacoes cloud para o ecossistema Atlassian (Jira, Confluence, Bitbucket, Compass, Jira Service Management) via plataforma Forge. Antes deste plugin, desenvolvedores editavam seus arquivos manifest.yml sem nenhuma assistencia do IDE: sem sugestoes, sem validacao, sem documentacao contextual. Cada erro neste arquivo so era revelado no momento do deploy, causando ciclos de debug custosos.
O plugin e exclusivamente projetado para aplicacoes Forge e nao suporta aplicacoes Atlassian Connect (que usam `atlassian-connect.json`).
O plugin so ativa suas funcionalidades quando detecta um projeto Forge genuino via criterio duplo: o `manifest.yml` contem um `app.id` comecando com `ari:cloud:ecosystem::` E um `package.json` no mesmo diretorio contem pelo menos uma dependencia `@forge/`. Isso garante que o plugin nunca interfira com outros arquivos YAML.
Objetivos, Contexto, Desafios & Riscos
Contexto estrategico e desafios identificados
O plugin Atlassian Forge Developer foi criado para preencher uma lacuna critica: a ausencia total de ferramentas IDE para o formato proprietario manifest.yml usado pelo Atlassian Forge.
Experiencia do Desenvolvedor
Primeira classe
Suporte nativo do IDE para desenvolvimento Forge no WebStorm
Reducao de Erros
Pre-deploy
Validacao em tempo real detecta erros antes do deploy
Cobertura de Produtos
5 produtos
Jira, Confluence, Bitbucket, Compass, JSM + Rovo
Documentacao
Integrada
Documentacao Atlassian pesquisavel diretamente do IDE
Templates
155+
Templates oficiais Forge acessiveis via assistente de projeto
Contexto
O projeto se baseia no template oficial da JetBrains para desenvolvimento de plugins IntelliJ Platform. O schema do manifest Forge e complexo e proprietario: cobre centenas de propriedades distribuidas entre modulos de 5 produtos Atlassian, 83 escopos OAuth 2.0, 71 tipos de eventos e 155+ templates de projetos. Todo este schema teve que ser modelado em Kotlin para alimentar o autocompletion e a validacao.
Desafios
Produtividade do desenvolvedor: cada minuto economizado na configuracao Forge impacta milhares de desenvolvedores no ecossistema Atlassian. Qualidade do codigo: deteccao de erros pre-deploy evita ciclos de debug custosos na plataforma cloud. Posicionamento estrategico: ser o primeiro plugin IDE dedicado ao Forge proporciona vantagem competitiva significativa no JetBrains Marketplace.
Dependencia do schema Atlassian
O schema Forge evolui regularmente; o plugin deve acompanhar atualizacoes ou arrisca ficar obsoleto
Compatibilidade IDE
Suportar versoes 2024.2 a 2025.2 do WebStorm (builds 242-252) requer testes de compatibilidade rigorosos
Complexidade do PSI
Manipular a arvore sintatica (PSI) da IntelliJ Platform e tecnicamente exigente e propenso a regressoes sutis
Adocao do mercado
Versao pre-release (0.1.0) pode limitar a adocao inicial no Marketplace
As Etapas - O que Eu Fiz
Jornada de implementacao da inicializacao a estabilizacao
- Fork do template oficial JetBrains intellij-platform-plugin-template
- Configuracao do projeto para WebStorm (platformType = WS)
- Estruturacao do pacote app.addly.atlassian
- Configuracao de dependencias: plugin YAML, kotlinx-serialization, SnakeYAML, Gson, Coroutines
- Configuracao de 5 workflows CI/CD GitHub Actions
- Modelagem completa do schema Forge em ManifestSchema.kt (669 linhas)
- Catalogo de 83 escopos OAuth 2.0 cobrindo todos os produtos Atlassian
- Catalogo de 71 tipos de eventos para triggers Forge
- Autocompletion contextual (ManifestCompletionContributor, 370 linhas)
- Validacao em tempo real (ManifestValidator, 620 linhas)
- Inspecoes IDE com correcoes automaticas (ManifestInspection, 341 linhas)
- Realce de sintaxe avancado (ManifestSyntaxHighlighter, 250 linhas)
- Deteccao inteligente de projetos Forge (criterio duplo ARI + @forge/)
- Painel de busca de documentacao Atlassian integrado via API Algolia
- Documentacao contextual ao passar o mouse (tooltips nas propriedades do manifest)
- Gerenciador visual de variaveis de ambiente (multi-env, criptografia, sincronizacao)
- Integracao da execucao do Forge CLI (deploy, tunnel, install, lint)
- Assistente de criacao de projetos Forge cobrindo 155+ templates oficiais
- Scripts de desenvolvimento: hot-reload, monitoramento de logs, analise de erros
- 10 arquivos de teste: completion, validacao (5 arquivos), highlighting, deteccao, setup, geracao
- Dados de teste: manifests validos e com erros, package.json, arquivos XML
- Configuracoes IDE: Run Plugin, Run Tests, Run Verifications
- Analise estatica Qodana com JDK 21
- Relatorios de cobertura de codigo Kover
Os Atores - As Interacoes
Modelo de colaboracao e ecossistema de partes interessadas
Este plugin foi desenvolvido como projeto solo sob a marca Addly (https://addly.app), uma empresa dedicada a criacao de ferramentas de produtividade para desenvolvedores. Como unico desenvolvedor, gerenciei todo o ciclo de vida do produto: arquitetura, implementacao, testes, CI/CD, documentacao e preparacao para o Marketplace.
O desenvolvimento foi assistido pelo Claude Code para geracao de codigo e sessoes de pair-programming. O workflow combinava minha expertise profunda no dominio Atlassian Forge com implementacao acelerada por IA - um modelo onde o humano fornece visao, arquitetura e conhecimento de dominio enquanto a IA assiste na execucao do codigo.
| Fonte | Linhas | % do Total | Arquivos |
|---|---|---|---|
| JetBrains Template (unchanged) | 1,636 | 10.8% | 20 |
| Adapted from template | 652 | 4.3% | 6 |
| Original (Dev + Claude Code) | 12,921 | 84.9% | 86 |
| TOTAL | 15,209 | 100% | 112 |
Dependencias Externas
Atlassian forneceu a plataforma Forge, documentacao e API de busca Algolia. JetBrains forneceu o IntelliJ Platform SDK, template de plugin e infraestrutura de distribuicao do Marketplace. A comunidade de desenvolvedores Forge representa a base de usuarios alvo.
Os Resultados
Entregas, metricas e crescimento pessoal
Para o Produto
Extensoes do Plugin
12
Completion, annotator, inspection, highlighter, tool windows, etc.
Workflows CI/CD
5
Build, release, UI tests, template cleanup, template verify
Icones & Visuais
19
7 icones SVG + 10 PNG readme + 2 SVG readme
Scripts Utilitarios
5
1 bash + 3 JS + 1 configuracao JSON
Para a Empresa (Addly)
O plugin e um produto publicavel no JetBrains Marketplace com pipeline de publicacao totalmente automatizado (assinatura + deploy). Fornece cobertura completa do schema Forge para os 5 produtos Atlassian Cloud. Ate o momento, nenhum concorrente direto existe no Marketplace JetBrains para suporte especifico ao Atlassian Forge.
Para Mim - O que Aprendi
Este projeto aprofundou minha expertise em diversas areas tecnicas e estrategicas:
- Padroes avancados Kotlin - coroutines, serializacao, DSL, convencoes IntelliJ Platform
- Dominio do IntelliJ Platform SDK - manipulacao PSI, extension points, inspecoes, quick fixes, tool windows, completion contributors, syntax highlighters
- Arquitetura de plugins IDE - gestao de ciclo de vida, extension points, acoes, listeners, gestao de tipos de arquivo
- Developer Experience (DevEx) como disciplina - entender que uma ferramenta IDE economizando 5 minutos por dia por desenvolvedor se justifica rapidamente em escala
- Workflows de desenvolvimento assistido por IA - uso de Claude Code com especificacoes detalhadas (CLAUDE.md) para implementacao acelerada mantendo o controle arquitetural
- Precisao na modelagem de dominio - os arquivos de schema (ManifestSchema, Scopes, EventTypes) representam o valor fundamental; quanto mais preciso o modelo, mais util o plugin
O Dia Seguinte do Projeto
Estado pos-desenvolvimento e trajetoria futura
Estado Imediato
O plugin atingiu a versao 0.1.0 com todas as funcionalidades principais implementadas. O pipeline de publicacao no JetBrains Marketplace e totalmente automatizado via GitHub Actions: uma GitHub Release aciona assinatura, empacotamento e deploy. O CI/CD inclui 5 workflows cobrindo build, testes, analise estatica (Qodana), verificacao de compatibilidade e release automatizado.
Evolucao Planejada
O roadmap imediato inclui: commitar o codigo fonte inicial no git (atualmente nao versionado), melhorar a cobertura de testes alem do ratio atual de ~14.5%, internacionalizar todas as mensagens de UI (atualmente 8 propriedades i18n) e criar scripts de atualizacao automatica do schema para acompanhar mudancas do Atlassian Forge programaticamente.
Estado Atual & Contexto da Serie
O plugin esta em desenvolvimento ativo como parte de uma serie mais ampla de plugins IDE JetBrains construidos sob a marca Addly. Este plugin particular foi escolhido para esta apresentacao porque melhor demonstra a profundidade tecnica e completude de produto alcancaveis com o IntelliJ Platform SDK. Outros plugins da serie seguem padroes similares de modelagem de dominio profunda combinada com integracao IDE completa.
Minha Visao Critica
Retrospectiva honesta sobre sucessos e areas de melhoria
- Cobertura funcional exaustiva: autocompletion, validacao, highlighting, quick fixes, documentacao integrada, gestao de variaveis, criacao de projetos
- Arquitetura limpa e modular organizada por funcionalidade (completion, validacao, highlighting, search, forge), cada modulo com responsabilidade clara
- Modelagem rigorosa do schema: 83 escopos, 71 eventos, 155+ templates catalogados com descricoes
- Deteccao inteligente de projeto por criterio duplo evitando falsos positivos
- CI/CD maduro: 5 workflows GitHub Actions cobrindo build, testes, analise Qodana, verificacao de compatibilidade e publicacao assinada
- Ferramental de desenvolvimento: dev-webstorm.sh com watch, monitoramento, debug + analisador de logs
- Sem commits git: o repositorio esta inicializado mas nenhum commit foi feito - sem historico, sem rollback, sem rastreabilidade
- Versao pre-release (0.1.0): pode limitar adocao inicial no Marketplace
- Cobertura de testes limitada: ratio ~14.5% testes/codigo (1.157 linhas testes / 7.963 linhas main)
- i18n minimalista: apenas 8 propriedades de mensagens - muitos textos provavelmente hardcoded no codigo Kotlin
- Documentacao dos scripts em frances: pode limitar contribuicoes internacionais em caso de open source
Licoes Duradouras
- Developer Experience (DevEx) e um dominio de alto impacto - uma ferramenta que economiza 5 minutos por dia por desenvolvedor se justifica rapidamente em escala no ecossistema Atlassian
- A IntelliJ Platform e poderosa mas exigente - manipulacao do PSI, extension points e convencoes da API requerem investimento significativo de aprendizado mas permitem construir ferramentas profundamente integradas
- A modelagem de dominio e o valor fundamental - os arquivos de schema (ManifestSchema, Scopes, EventTypes) representam o valor do plugin; quanto mais preciso e completo o modelo, mais util o plugin se torna
- IA como acelerador de desenvolvimento - as especificacoes CLAUDE.md + workflow Claude Code demonstram como IA pode assistir o desenvolvimento de projetos complexos, da implementacao ao debugging, enquanto o humano mantem a visao e controle arquitetural
Arquitetura & Diagramas Tecnicos
Trajetoria relacionada
Experiencia profissional ligada a esta realizacao
Competencias aplicadas
Competencias tecnicas e humanas aplicadas
Galeria de imagens
Capturas e visuais do projeto
