Skip to content
in studydocs
↑ ↓ navigateEnter openon-site search, no external service

0006 · Execução local-first e divisão da stack

  • Status: Aceito (revisão obrigatória ao fim do C2)
  • Data: 2026-11-14

Contexto

Seção intitulada “Contexto”

O Prumo executa agentes de IA, roda comandos, sobe ambientes e mexe em arquivos de um projeto. Isso exige uma máquina. Hoje essa máquina é o computador de quem usa; no futuro pode ser uma VPS ou runners sob demanda. Também queremos uma versão web e, quem sabe, mobile.

Ao mesmo tempo, quem for contribuir precisa conseguir rodar o Prumo na própria máquina com pouco esforço e sem pagar nada (ADR-0005).

O mantenedor domina Java/Spring e React/TypeScript. O projeto vai ter partes com necessidades diferentes, então pode ter mais de uma linguagem.

Decisão (proposta)

Seção intitulada “Decisão (proposta)”
  1. Local-first. O núcleo do Prumo (o motor que lê o pipeline.yml, executa as etapas e grava em tasks/<id>/) roda na máquina de quem usa, como um processo local com uma CLI.
  2. Interface web servida localmente. A tela é uma aplicação web que o próprio núcleo serve em localhost e abre no navegador. Não nasce como app desktop nativo.
  3. Uma base, três formas. A mesma combinação núcleo + interface web serve pra:
    • rodar no computador da pessoa (agora);
    • virar app desktop depois, embrulhando a interface com uma casca leve (ex.: Tauri), se houver motivo;
    • rodar numa VPS, com o mesmo núcleo atrás de login, quando chegar a hora (fase 1 da infraestrutura).
  4. Poliglota por fronteira, não por gosto.
    • Núcleo: Go (ver “Linguagem do núcleo”).
    • Interface: TypeScript + React, seguindo o design system.
    • Adapters (integrações, executores): qualquer linguagem, desde que falem com o núcleo por processo/CLI ou por MCP. Assim alguém pode contribuir com um adapter em Python mesmo que o núcleo seja em outra linguagem.
  5. Rodar pra contribuir em um comando. O repositório oferece um caminho único de execução local (um binário ou compose up) e um modo dublê, em que os executores devolvem respostas gravadas, pra testar tudo sem IA paga.

Linguagem do núcleo: Go

Seção intitulada “Linguagem do núcleo: Go”
Opção A favor Contra
Java / Spring O mantenedor domina; ecossistema maduro Pesado pra uma CLI; distribuição exige JVM ou compilação nativa
Go Binário único, fácil de distribuir; bom com processos e concorrência Linguagem nova pro mantenedor
Python Mais fácil pra estudante contribuir; maior ecossistema de IA Distribuição e empacotamento mais trabalhosos; tipagem opcional
TypeScript / Node Mesma linguagem da interface; vários agentes livres são em TS Runtime separado; dois mundos (servidor e tela) na mesma linguagem podem misturar responsabilidades

Critérios usados: facilidade de distribuir pra quem usa, facilidade de quem chega pra contribuir, adequação ao problema (orquestrar processos externos, ler e gravar arquivos, rodar etapas em paralelo) e licença livre de tudo que entrar.

Escolha: Go, por ser a opção mais orientada ao problema:

  • O núcleo é, no fundo, um orquestrador de processos (agentes de IA, testes, comandos de ambiente). A biblioteca padrão do Go cobre isso (os/exec, context, goroutines) sem dependência extra.
  • Gera um binário só por sistema operacional, com compilação cruzada nativa. Quem usa baixa e roda; quem contribui não precisa instalar runtime.
  • É a linguagem de várias ferramentas de linha de comando que o público do Prumo já usa, o que facilita achar exemplo e contribuidor.
  • A linguagem é pequena e tem formatação e testes padronizados (gofmt, go test), o que ajuda estudante a entrar.
  • Licença BSD-3-Clause, compatível com a AGPL-3.0.

Custo aceito: Go é novo pro mantenedor. Isso aumenta o risco do C1; se o prazo apertar, corta-se escopo do C1, não a data. Outras partes podem ter versões em outras linguagens no futuro, via a fronteira de processo/MCP, sem mexer no núcleo.

Consequências

Seção intitulada “Consequências”
  • O C1 não precisa de servidor, banco nem login: só a CLI na máquina local.
  • A versão web/VPS não exige reescrever o núcleo, só autenticação e isolamento (que viram ADRs próprios).
  • Adapters em linguagens diferentes obrigam a manter contratos claros (formato de entrada e saída) e testes de contrato.
  • “Desktop” deixa de ser uma decisão agora e vira uma casca opcional depois.

Fontes

Seção intitulada “Fontes”

Dependências do núcleo (checagem de licença, ADR-0005)

Seção intitulada “Dependências do núcleo (checagem de licença, ADR-0005)”
Dependência Uso Licença
github.com/goccy/go-yaml Ler o pipeline.yml com erros apontando linha e campo MIT