Protocolo do sidecar

Visão geral

Um sidecar é um processo filho que o Jarvis ADE inicia com o comando do manifesto, com a pasta instalada do plugin como cwd. A conversa é em JSON lines: um objeto JSON por linha, sem quebras de linha dentro dele.

• stdin (app → sidecar): hello, eventos de missão e do quadro, e shutdown.
• stdout (sidecar → app): ready, log, card.note, card.link, resync, error.
• stderr: cada linha vira um log de nível warn.

O sidecar só é iniciado quando o plugin está ativado e todas as configurações com required: true têm valor. Uma falha do sidecar (linha ilegível, crash, timeout) é registrada no log da integração e nunca derruba o app.

Variáveis de ambiente

O processo herda o process.env do app, mais o env declarado na integração, mais as variáveis abaixo (as ADE_* vencem em caso de conflito):

Mensagens do app para o sidecar (stdin)

Toda linha tem o envelope { v: 1, id, at, type, ...payload }: v é a versão do protocolo, id um UUID por mensagem e at o Date.now() da emissão.

{"v":1,"id":"6f1c…","at":1789744976234,"type":"hello","adeVersion":"0.1.0","pluginId":"hello-ade","integrationId":"echo","settings":{"greeting":"hello"}}

{
  "v": 1,
  "id": "0b8d…",
  "at": 1789745131936,
  "type": "board.card_moved",
  "mission": { "id": "…", "name": "…", "workspaceId": "…", "workspaceName": "…", "status": "running", "createdAt": 1789744899624 },
  "columns": [{ "id": "…", "title": "Backlog", "order": 0, "role": "backlog" }],
  "card": { "id": "…", "title": "…", "columnId": "…", "assignee": null, "columnTitle": "Em desenvolvimento", "columnRole": "dev" },
  "from": { "id": "…", "title": "Backlog", "order": 0, "role": "backlog" },
  "to": { "id": "…", "title": "Em desenvolvimento", "order": 1, "role": "dev" }
}

Formas que se repetem

• mission: id, name, workspaceId, workspaceName, status (draft | planning | running | paused | merging | done | aborted | failed), createdAt (ms).
• coluna: id, title, order, role (backlog | dev | qa_wait | qa_test | bug | done ou null).
• card: o card completo (id, missionId, columnId, parentId, type story | task | subtask, title, description, docs, activity, attachments, questions, order, createdAt, updatedAt…) mais assignee ({ paneId, label, agentId } ou null), columnTitle e columnRole.

Mensagens do sidecar para o app (stdout)

{"type":"ready","name":"meu-plugin"}
{"type":"log","level":"info","message":"sincronizado"}
{"type":"card.note","cardId":"<id do card>","message":"✅ espelhado no serviço"}
{"type":"card.link","cardId":"<id do card>","url":"https://exemplo.com/t/123","label":"Tarefa #123"}
{"type":"resync"}
{"type":"error","message":"falha ao autenticar"}

• Uma linha do stdout que não é JSON (ou é JSON sem type textual, ou com um type desconhecido) vira um log info com o texto da linha — útil para depurar, mas prefira mensagens log explícitas.
• Cada mensagem de log é cortada em 500 caracteres; o painel guarda as últimas 50 entradas.
• Um card.note para um card que não existe mais gera um aviso no log — não derruba nada.

Ciclo de vida, restart e backoff

O que dispara um restart gracioso

• Salvar as configurações do plugin.
• Ativar o plugin, ou reimportá-lo.
• O botão Reiniciar na tela do plugin.

Em todo início do processo — restart gracioso, reinício depois de um crash com backoff, abertura do app — o sidecar recebe de novo o hello (com as configurações atuais) e os board.snapshot. Trate o hello como “começando do zero”, nunca como “o usuário acabou de fazer algo”. É exatamente por isso que ações disparadas por configuração precisam de uma trava anti-repetição.

Filtro de eventos

Com events no manifesto, só chegam os eventos de board.*/mission.* que combinam com um nome exato ou um prefixo algo.*. O filtro também vale para o board.snapshot. Sem filtro, ou com [], chega tudo.

Checklist de um sidecar correto

• Ler o stdin linha a linha (node:readline) e fazer JSON.parse dentro de um try/catch.
• Enviar { type: 'ready' } logo que estiver pronto.
• Ao receber shutdown (ou quando o stdin fechar), limpar e sair com process.exit(0) em menos de 5 s.
• Só mensagens do protocolo no stdout — uma por linha. Tudo que for diagnóstico solto vai para o stderr ou para uma mensagem log.
• Nunca deixar uma exceção sem tratamento nem bloquear esperando I/O sem timeout.