Módulo 3.8 - Produção: Deploy, CI/CD & Observabilidade

📦 Publishing rules V3 (CRÍTICO)

A regra mais importante do release process: Ruflo publica TRÊS pacotes juntos. @claude-flow/cli (binário core), claude-flow (umbrella) e ruflo (alias amigável). Esquecer um deles quebra usuários que rodam npx ruflo@alpha.

🚨ALERTA CRÍTICO — NÃO ESQUECER do package ruflo!

É EXTREMAMENTE comum esquecer de publicar o pacote ruflo. Isso quebra todos os usuários que rodam npx ruflo@alpha ou npx ruflo@latest. Sempre publique os 3 pacotes juntos e atualize todos os dist-tags antes de avisar o usuário que terminou.

Esquecer também o tag alpha da umbrella claude-flow é o segundo erro mais frequente. Verifique sempre.

📋Sequência completa de publicação

1. Publicar @claude-flow/cli:

cd v3/@claude-flow/cli
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm run build
npm publish --tag alpha
npm dist-tag add @claude-flow/cli@3.0.0-alpha.XXX latest

2. Publicar claude-flow (umbrella):

cd /workspaces/claude-flow
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm publish --tag v3alpha
npm dist-tag add claude-flow@3.0.0-alpha.XXX latest
npm dist-tag add claude-flow@3.0.0-alpha.XXX alpha

3. Publicar ruflo (NÃO ESQUECER):

cd /workspaces/claude-flow/ruflo
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm publish --tag alpha
npm dist-tag add ruflo@3.0.0-alpha.XXX latest

4. Verificação obrigatória:

npm view @claude-flow/cli dist-tags --json
npm view claude-flow dist-tags --json
npm view ruflo dist-tags --json

📊Todos os dist-tags por pacote

Para cada pacote, atualize TODOS os tags relevantes: @claude-flow/cli precisa de alpha + latest + v3alpha; claude-flow precisa de alpha + latest + v3alpha; ruflo precisa de alpha + latest. Nada disso é opcional.

🌐 Plugin registry IPFS

O registry de plugins vive no IPFS via Pinata. Quando você adiciona um plugin novo, atualiza o JSON, faz upload, recebe um CID novo, e troca o LIVE_REGISTRY_CID em discovery.ts. Imutável e descentralizado.

🔗Fluxo de atualização

1. Buscar registry atual:

curl -s "https://gateway.pinata.cloud/ipfs/$CID" \
  > /tmp/registry.json

2. Editar registry.json (adicionar plugin, incrementar contadores)

3. Upload para Pinata:

PINATA_JWT=$(grep "^PINATA_API_JWT=" .env | cut -d'=' -f2-)
curl -X POST "https://api.pinata.cloud/pinning/pinJSONToIPFS" \
  -H "Authorization: Bearer $PINATA_JWT" \
  -H "Content-Type: application/json" \
  -d @/tmp/registry.json

4. Atualizar LIVE_REGISTRY_CID em discovery.ts

5. Verificar acessibilidade:

curl -s "https://gateway.pinata.cloud/ipfs/$NEW_CID" | jq '.totalPlugins'

⚠️Segurança

NUNCA hardcode PINATA_API_JWT em scripts. Sempre via env var carregada de .env (que está no .gitignore). Apague scripts temporários após upload one-time.

🐳 Docker setup

Para produção, Ruflo roda em containers Docker. Um docker-compose.yml sobe daemon, MCP server e Postgres em rede isolada. Variáveis de ambiente entram via .env file (mais seguro que CLI args).

📦docker-compose.yml exemplo

version: '3.9'
services:
  ruflo-daemon:
    image: ruflo/daemon:3.6.10
    env_file: .env
    volumes:
      - ./data:/app/data
    networks: [internal]

  ruflo-mcp:
    image: ruflo/mcp:3.6.10
    env_file: .env
    ports: ["3000:3000"]
    depends_on: [ruflo-daemon]
    networks: [internal]

  postgres:
    image: postgres:16-alpine
    env_file: .env
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks: [internal]

volumes:
  pgdata:
networks:
  internal:

💡Subir tudo

docker compose up -d
docker compose logs -f ruflo-daemon

👁️ Observability plugin

Em produção você precisa enxergar o que cada agente está fazendo. O observability plugin exporta logs estruturados, traces OpenTelemetry e métricas Prometheus. Plug em Grafana, Datadog, New Relic — sai dashboard pronto.

✓ O que você captura

✓Logs estruturados JSON
✓Traces distribuídos por agente
✓Métricas Prometheus
✓Health checks customizados
✓Latency p50/p95/p99 por hook
✓Memory usage por agente

✓ Para onde exporta

✓Grafana (via Prometheus)
✓Datadog (OTLP nativo)
✓New Relic (OTLP)
✓Jaeger / Tempo (traces)
✓Loki / ELK (logs)
✓Custom webhook receivers

💸 Cost tracking

Sem tracking, gasto LLM cresce silenciosamente. Cost tracking registra tokens por agente, calcula custo em USD por requisição, alerta quando passa thresholds e bloqueia agente que estoura budget.

💰Configurar budgets

# Budget global por dia
npx claude-flow@v3alpha config set budget.daily 50.00

# Budget por agente
npx claude-flow@v3alpha config set budget.per-agent.coder 10.00
npx claude-flow@v3alpha config set budget.per-agent.researcher 5.00

# Alerta a 80% do budget
npx claude-flow@v3alpha config set budget.alert-threshold 0.80

# Bloquear agente em 100%
npx claude-flow@v3alpha config set budget.hard-stop true

📊Dashboard de custo

Cost tracker exporta breakdown completo: gasto por dia, por agente, por provider, por feature. Você descobre que "o agent reviewer está consumindo 60% do budget" antes do mês fechar — e ajusta routing para Tier inferior.

🚀 CI/CD pipeline complete

Pipeline ideal de release Ruflo via GitHub Actions: doctor → scan → benchmark → publish → tag update. Cada step bloqueia o próximo se falhar. Produção só recebe versão que passou em tudo.

⚙️.github/workflows/release.yml

name: Release Ruflo
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - name: Install
        run: npm ci

      - name: Doctor (health check)
        run: npx claude-flow@v3alpha doctor

      - name: Security scan
        run: npx claude-flow@v3alpha security scan --depth full

      - name: Performance benchmark
        run: npx claude-flow@v3alpha performance benchmark --suite all

      - name: Build all packages
        run: npm run build:all

      - name: Publish @claude-flow/cli
        working-directory: v3/@claude-flow/cli
        run: npm publish --tag alpha
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Publish claude-flow
        run: npm publish --tag v3alpha
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Publish ruflo
        working-directory: ruflo
        run: npm publish --tag alpha
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Update dist-tags
        run: |
          npm dist-tag add @claude-flow/cli@$VERSION latest
          npm dist-tag add claude-flow@$VERSION latest
          npm dist-tag add claude-flow@$VERSION alpha
          npm dist-tag add ruflo@$VERSION latest
        env:
          VERSION: ${{ github.ref_name }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Verify
        run: |
          npm view @claude-flow/cli dist-tags --json
          npm view claude-flow dist-tags --json
          npm view ruflo dist-tags --json

⚠️Atenção final

Mesmo com pipeline automatizado, o step de verificação no final não é opcional. Sempre rode npm view para os 3 pacotes antes de anunciar release. CI pode falhar silenciosamente em algum tag — verificação manual fecha o ciclo.

💡Você terminou o curso!

Parabéns. Você cobriu fundamentos, uso prático e tópicos avançados de Ruflo. Agora vá construir — escolha um projeto real, aplique os patterns aprendidos, e contribua de volta com a comunidade INEMA.CLUB.

📋Resumo do Módulo

✓

Publishing V3 — 3 pacotes (cli + claude-flow + ruflo) + TODOS os dist-tags

✓

Plugin registry IPFS — Atualizar CID + Pinata flow + verificação

✓

Docker — daemon + MCP + postgres com env vars seguros

✓

Observability — Logs, traces OTel, métricas Prometheus

✓

Cost tracking — Budgets configuráveis + alerts + hard stop

✓

CI/CD pipeline — doctor → scan → benchmark → publish → verify

Curso completo:

Você concluiu todas as 3 trilhas. Parabéns — agora é botar em prática.

← Voltar para Trilha ← Voltar ao Início