MangoStudio

CI Release

Estúdio de geração de imagens e chat alimentado por IA com suporte a modelos Gemini, compatíveis com OpenAI, Anthropic, DeepSeek e ChatGPT.

🇺🇸 Read in English

Instalar

Execute o MangoStudio sem clonar o repositório. Cada canal distribui o mesmo binário pré-compilado e verifica downloads contra SHA256SUMS quando aplicável.

O app pré-compilado não precisa de um compilador Rust local. cargo install mangostudio compila o launcher e exige Rust 1.99.0 ou mais recente. cargo binstall usa um arquivo pré-compilado quando disponível; a compilação de fallback exige a mesma versão do Rust. Veja a política de suporte e releases Rust ao migrar do Rust 1.96 ou 1.97.

Início rápido com o instalador shell:

curl -fsSL https://mangostudio.dev/install.sh | bash
mangostudio setup           # segredo, serviço, início e abre o navegador

Em um Alpine (musl) puro, rode apk add bash curl libstdc++ antes: o instalador é um script bash, e o hub linka libstdc++ dinamicamente. Sem ele a verificação de versão do instalador falha com a mensagem do loader e esta mesma dica.

setup é o único comando de que uma instalação nova precisa: gera um segredo de autenticação se não houver, pergunta se o hub deve continuar rodando depois do logout, inicia (ou reaproveita um já em execução) e abre. Por SSH ele imprime o endereço e uma linha de encaminhamento de porta em vez de fingir que abriu uma janela. mangostudio serve e mangostudio service install continuam sendo os equivalentes diretos.

Na primeira vez que você entra, o navegador abre um fluxo curto de configuração — pasta, toolchain, quem responde, e uma pergunta de verdade no seu próprio projeto. Todo passo é pulável e refazível em Configurações → Geral. Veja docs/pt-br/guides/first-run.md.

No Windows, execute o instalador PowerShell:

irm https://mangostudio.dev/install.ps1 | iex

ou use Scoop (veja a tabela acima). O canal Cargo instala um launcher pequeno que baixa o mesmo arquivo verificado por checksum na primeira execução.

Os dois scripts de instalação vivem neste repositório (scripts/install/), são publicados como assets de release ao lado dos arquivos que instalam e constam em SHA256SUMS; as cópias em https://mangostudio.dev/install.sh e install.ps1 são espelhos. Use --canary (-Canary) para o pre-release canary mais recente ou --version x.y.z (-Version) para fixar uma versão.

Atualizar

mangostudio upgrade (alias update) descobre como o binário foi instalado e atualiza no lugar ou entrega a tarefa à ferramenta que é dona dele:

O hub verifica uma vez por dia se há release mais nova; mangostudio status, mangostudio doctor e a página “Esta máquina” avisam quando existe uma, e a página consegue aplicá-la na própria máquina do hub. [updates] check = false no config.toml, MANGO_UPDATES_CHECK=false, NO_UPDATE_NOTIFIER, DO_NOT_TRACK ou CI desligam a verificação.

mangostudio é um CLI de binário único que gerencia um servidor local:

mangostudio serve [host|port|host:port] # foreground (padrão localhost:3001)
mangostudio serve lan:3001 -d           # background (logs em ~/.mango/logs/)
mangostudio service install # mantém rodando após logout e reboot
mangostudio status         # mostra a instância em execução
mangostudio restart        # reinicia do jeito que foi iniciado
mangostudio logs -f        # acompanha o log do servidor
mangostudio stop           # encerramento gracioso
mangostudio doctor         # diagnóstico de ambiente

Execute mangostudio sem argumentos para a lista completa de comandos. Veja docs/reference/cli.md para detalhes.

Na primeira execução, mangostudio serve pode gerar um BETTER_AUTH_SECRET forte e armazená-lo em ~/.mango/.env ou ~/.mango/config.toml. Configure chaves de provedor como GEMINI_API_KEY quando estiver pronto para usar modelos hospedados. Configurações opcionais de runtime incluem API_HOST, API_PORT e DATABASE_PATH. Veja mangostudio para o ambiente completo. Para deploy em container, veja docs/operations/deployment.md.

Pré-requisitos (desenvolvimento)

• Bun 1.4.3 ou mais recente (bun upgrade ou curl -fsSL https://bun.sh/install | bash na primeira instalação)
• Rust 1.99.0 ou mais recente via rustup (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh). O hub inicia o Local como o mangostudio-runtime construído com cargo, e o rust-toolchain.toml fixa a versão que o rustup instala no primeiro build.
• Uma ou mais chaves de API ou contas com login para provedores suportados (Gemini, compatíveis com OpenAI, Anthropic, DeepSeek, ChatGPT)

Desenvolver a partir do código-fonte

1. Clone o repositório:

   git clone <repo-url>
   cd mangostudio

2. Instale as dependências:

   bun install

3. Inicie os servidores de desenvolvimento:

   bun run dev

   Primeiro ele executa cargo build -p mangostudio-runtime --locked — o runtime Local que o hub inicia —; sem cargo ele para e mostra o comando do rustup, e MANGOSTUDIO_RUNTIME_BINARY aponta para um binário já construído. Depois inicia:

   • API em http://localhost:3001 (Elysia + Kysely/SQLite)
   • Frontend servido pela mesma API em http://localhost:3001 (React, empacotado com Bun)

Configuração de Conectores (Secrets)

O MangoStudio possui um sistema flexível de múltiplos conectores que permite gerenciar várias chaves de API com diferentes níveis de persistência.

Métodos de Persistência Suportados

1. OS Secret Store — Armazenamento nativo seguro do sistema operacional (via Bun.secrets). Recomendado para maior segurança.
2. config.toml — Armazena chaves em ~/.mango/config.toml. Ideal para compartilhar chaves entre instâncias ou ferramentas CLI.
3. Arquivo .env — Adiciona variáveis ao arquivo ~/.mango/.env.

Como Configurar

Acesse a página Configurações na interface do MangoStudio para adicionar e gerenciar conectores.

Para cada conector, é possível habilitar ou desabilitar modelos específicos (ex: Gemini 2.5 Flash, Gemini 2.0 Flash Image). O MangoStudio seleciona automaticamente o conector correto com base no modelo ativo no chat.

Provedores Suportados

Sincronização via Terminal

Você pode adicionar chaves manualmente em ~/.mango/config.toml:

[gemini_api_keys]
pessoal = "sua-chave-aqui"
trabalho = "outra-chave-aqui"

O MangoStudio sincroniza essas chaves automaticamente ao carregar a página de Configurações ou ao iniciar uma geração.

Cursor

O Cursor não é um conector. Ele roda como agente externo — escolha-o no seletor de runner do compositor e ele usa o seu próprio login, regras e configuração MCP do Cursor CLI. O provider Cursor mantido pelo MangoStudio foi descontinuado: conectores existentes continuam editáveis, mas não executam mais turnos. Veja docs/providers/cursor.md.

Conector De Assinatura ChatGPT

O provedor ChatGPT usa login pelo navegador em vez de chave de API. Ele inicia um servidor temporário de callback na porta 1455, armazena tokens OAuth rotativos no OS secret store e usa os modelos disponíveis no plano ChatGPT conectado. Veja docs/providers/chatgpt.md para detalhes e notas de port-forwarding em hosts remotos.

Estrutura do Projeto

mangostudio/
├── .mango/            # Templates de configuração de exemplo
│   └── config.toml.example
├── apps/
│   ├── api/
│   │   └── src/
│   │       ├── lib/                # Config, runtime paths, SPA guard
│   │       ├── modules/            # Módulos de domínio (inspirados em DDD)
│   │       │   ├── chats/          # application/ domain/ http/ infrastructure/
│   │       │   ├── messages/       # application/ domain/ http/ infrastructure/
│   │       │   ├── generation/     # application/ domain/ http/ infrastructure/
│   │       │   ├── connectors/     # application/ domain/ http/ infrastructure/
│   │       │   ├── app-settings/   # application/ http/ infrastructure/
│   │       │   ├── provider-settings/  # application/ http/ infrastructure/
│   │       │   ├── tool-settings/  # application/ http/ infrastructure/
│   │       │   ├── prompt-rules/   # application/ http/
│   │       │   └── attachments/    # application/ infrastructure/
│   │       ├── plugins/            # Auth guard, rate limiting, error handler
│   │       ├── services/           # Provedores de IA, tools, secrets, imagens geradas
│   │       │   ├── providers/      # Implementações multi-provedor + infra core
│   │       │   ├── tools/          # Registro de ferramentas + ferramentas built-in
│   │       │   └── generated-images/  # Armazenamento de imagens geradas
│   │       └── db/                 # Kysely + SQLite + migrações
│   ├── frontend/
│   │   └── src/
│   │       ├── components/
│   │       │   └── ui/             # Design system (Button, Input, Card, Spinner, Toast, Toggle)
│   │       ├── features/           # Módulos de feature (chat, gallery, generation, settings, sidebar)
│   │       ├── hooks/              # React hooks (use-i18n, use-app-state, use-model-catalog…)
│   │       └── routes/             # Páginas TanStack Router
│   └── shared/
│       └── src/
│           ├── contracts/          # Barrel de contratos
│           ├── <module>/           # Contratos + schemas por módulo (auth, chat, connectors…)
│           ├── streaming/          # Tipos e schemas de eventos SSE
│           ├── types/              # Tipos de domínio (provider, agent-events, gallery)
│           ├── i18n/               # Dicionários pt-BR / en + tipos
│           └── test-utils/         # Mock factories compartilhadas
├── docs/
│   ├── README.md                   # Hub da documentação
│   ├── architecture/              # Arquitetura e fluxos transversais
│   ├── features/                  # Documentação por área do produto
│   ├── providers/                 # Guias e notas por provedor
│   ├── reference/                 # API, testes e mapas de arquivos
│   ├── guides/                    # Guias práticos para contribuição
│   ├── operations/                # Deploy e segurança
│   └── pt-br/                     # Traduções curadas em Português
├── package.json                    # Raiz do Bun workspace
└── tsconfig.json                   # Configuração base de TypeScript

Scripts Principais

Ferramentas de Desenvolvimento

Estes binários são instalados como devDependencies e invocados através dos scripts bun run. Nenhuma instalação global é necessária.

Validação Local

Git Hooks

Um hook lefthook de pre-commit é instalado automaticamente via bun install (através do script prepare). Ele executa as seguintes verificações em paralelo a cada git commit:

Arquivos formatados são re-adicionados ao stage automaticamente. Todos os hooks devem ser bem-sucedidos para o commit prosseguir.

Verificações Manuais

• bun run check — verificação completa (Biome, dprint, typecheck, dependências circulares).
• bun run check --staged — apenas os workspaces afetados pelos arquivos staged (usado pelo hook pre-commit).
• bun run check --changed — apenas os workspaces modificados em relação a origin/main.
• bun run fix --staged — correção automática apenas nos workspaces afetados.

Arquitetura

Configuração do Editor

Os hooks do Claude Code prependem node_modules/.bin ao PATH automaticamente ao iniciar sessão e ao mudar de diretório (SessionStart / CwdChanged). Após cada escrita ou edição, um hook PostToolUse executa auto-fix.mjs para formatar o arquivo modificado.

OpenCode

A configuração de instruções e formatadores do OpenCode está em opencode.json.

Prettier está desativado. As instruções do OpenCode são carregadas de .agents/opencode/rules/*.md.

Qualidade de Código

Biome (Lint)

Configurado em biome.json com as regras recommended ativadas e sobrescritas específicas por workspace.

Regras globais (todos os arquivos):

Sobrescritas TypeScript/TSX (**/*.{ts,tsx}):

Sobrescritas específicas do frontend (apps/frontend/**/*.{ts,tsx}):

Atenuações por workspace:

Configurações adicionais de formatação:

• Largura de linha: 100, indentação: 2 espaços, aspas simples, ponto e vírgula, vírgulas finais (es5)
• Parser CSS ativa diretivas Tailwind
• Formatador HTML auto-fecha elementos void
• assist.actions.source.organizeImports ativado

dprint (Formatação)

Configurado em dprint.json com o seguinte escopo e configurações:

Dependências Circulares

O Biome verifica os ciclos de importação como parte do bun run check, incluindo imports de valores, de tipos e do próprio módulo. Cada workspace verifica arquivos TS, TSX, MTS, CTS, JS, JSX, MJS e CJS, incluindo arquivos na raiz, arquivos gerados e saídas de build ignoradas pelo Git, com o biome.cycles.json. Arquivos JavaScript são verificados como dependências de arquivos TypeScript e como raízes independentes. Somente node_modules e .git são excluídos da verificação de ciclos. A formatação e os demais checks de lint continuam seguindo o biome.json.

Detecção de Código Duplicado

Verificada via jscpd durante CI (qa-gate). A configuração é definida diretamente em scripts/qa-gate/collect.ts.

Design System

O frontend usa um design system próprio em apps/frontend/src/components/ui/:

• Button — variantes primary, secondary, ghost; prop loading
• Input — label, mensagem de erro, spread de InputHTMLAttributes
• Card — variantes glass (glassmorphism) e solid
• Spinner — indicador de carregamento com tamanhos sm, md, lg
• Toast — notificações não-bloqueantes via hook useToast()
• Toggle — interruptor com foco em acessibilidade

Internacionalização (i18n)

Strings de UI centralizadas em @mangostudio/shared/i18n. Suporte a pt-BR (padrão) e en, com detecção automática via navigator.language.

import { useI18n } from '@/hooks/use-i18n';

function MyComponent() {
  const { t } = useI18n();
  return <h1>{t.auth.loginTitle}</h1>;
}

O tipo Messages é inferido diretamente do dicionário pt-BR.ts (as const). Adicionar uma chave sem traduzir em en.ts gera erro de compilação imediatamente.

Documentação

• ./README.md — hub da documentação em Português
• ./guides/contributor-quickstart.md — onboarding rápido para contribuidores
• ./architecture/continuation.md — arquitetura de continuação
• ./providers/development.md — guia de integração de provedores
• ./reference/cli.md — referência da CLI e canais de instalação
• ./reference/ci.md — gates agregados e checks obrigatórios
• ./reference/releasing.md — runbook de release e canais de distribuição
• ./reference/runtime-metrics.md — tamanho, perfil de build e volume de código do runtime Rust
• ./reference/testing.md — estratégia e guia de testes
• ./reference/agent-playbooks.md — mapas de arquivos por feature
• ./reference/labels.md — taxonomia de labels de classificação
• ./operations/deployment.md — deploy e builds standalone
• ./operations/security.md — política e modelo de segurança
• ./CONTRIBUTING.md — diretrizes de contribuição em Português

Estrutura Espelhada

docs/pt-br/ agora espelha a mesma organização de docs/ com subpastas por responsabilidade:

• architecture/
• features/
• providers/
• reference/
• guides/
• operations/

Quando uma alteração relevante for feita em docs/, a versão correspondente em docs/pt-br/ deve ser atualizada na mesma tarefa para manter o espelho consistente.

Notas de Build Standalone

O comando bun run build --binary compila a API em binários específicos por plataforma em .mango/out/<platform>/, ao lado do mangostudio-runtime construído com cargo. Localmente ele constrói a plataforma do próprio host (--platform <host>); outras plataformas precisam de runtimes pré-construídos via --runtime-dir <dir> (veja releasing).

• O banco de dados é persistido em ~/.mango/database.sqlite por padrão.
• Os assets do frontend são embarcados no executável em tempo de compilação.

Licença

Este projeto está licenciado sob a Licença MIT.