@bricks2k/governance

Sistema de governança para projetos React com gestão de débitos técnicos, backlog e logs de desenvolvimento.

📋 Funcionalidades

• ✅ Dashboard de Governança - Visão unificada do projeto
• 📊 Tech Debt Management - Rastreamento de débitos técnicos
• 📦 Backlog Management - Gestão de features e melhorias
• 📝 Logs System - Histórico de arquitetura e decisões
• 🏗️ Architecture View - Visualização da arquitetura
• 🔧 Supabase Integration - Status e configuração do Supabase
• 🤖 AI Assistant - Assistente de desenvolvimento

🚀 Instalação

npm install @bricks2k/governance

Peer Dependencies

npm install react react-dom

📦 Uso Básico

Sem Provider (Standalone)

import { GovernanceDashboard } from '@bricks2k/governance';

function App() {
  return (
    <GovernanceDashboard />
  );
}

Com Provider (Recomendado)

O GovernanceProvider permite injetar dependências e configurações customizadas:

import { GovernanceProvider, GovernanceDashboard } from '@bricks2k/governance';
import { copyToClipboard, maskCredential } from './lib/credentialUtils';
import { supabase } from './lib/supabase';
import { SUPABASE_CONFIG } from './lib/constants/supabaseConfig';
import { supabaseHealthCheck } from './lib/supabaseHealthCheck';

function App() {
  return (
    <GovernanceProvider
      utils={{ copyToClipboard, maskCredential }}
      client={supabase}
      config={{ supabase: SUPABASE_CONFIG }}
      healthCheck={supabaseHealthCheck}
    >
      <GovernanceDashboard />
    </GovernanceProvider>
  );
}

Uso Avançado com Chat AI

import { GovernanceProvider } from '@bricks2k/governance';
import { DevAssistantTab } from '@bricks2k/governance';
import ChatInterface from './components/ai/ChatInterface';

function App() {
  return (
    <GovernanceProvider
      utils={{ copyToClipboard, maskCredential }}
      ChatInterface={ChatInterface}
      chatConfig={{
        endpoint: '/api/openrouter-ai-service',
        context: 'development',
        systemContext: 'React development project'
      }}
    >
      <DevAssistantTab />
    </GovernanceProvider>
  );
}

🎨 Estilização

O pacote requer Tailwind CSS configurado no projeto host.

Tailwind Config

Adicione o caminho do pacote no tailwind.config.js:

module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@bricks2k/governance/dist/**/*.{js,jsx}' // ← Adicionar
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

📄 Estrutura de Dados

Tech Debt Registry

Esperado em: public/docs/TECHNICAL_DEBT_REGISTRY.md

| TD-001 | Descrição | 🔴 Crítico | Trigger | Location | Owner | ⏳ Pendente | 2026-01-01 |

Backlog Registry

Esperado em: public/docs/BACKLOG_REGISTRY.md

| BL-001 | Título | ✨ Feature | 📋 Backlog | Owner | M | 2026-01-01 |

Logs

Esperados em: public/.logs/

• architecture.log.md
• decisions.log.md

🔧 API Completa

GovernanceProvider

Provider para injeção de dependências e configuração.

Props:

Prop	Tipo	Required	Descrição
children	ReactNode	✅	Componentes filhos
utils	Object	❌	Utilitários customizados
utils.copyToClipboard	Function	❌	Função para copiar texto
utils.maskCredential	Function	❌	Função para mascarar credenciais
client	Object	❌	Cliente de banco (ex: Supabase)
config	Object	❌	Configurações gerais
config.supabase	Object	❌	Configuração Supabase
healthCheck	Function	❌	Função de health check
ChatInterface	Component	❌	Componente de chat AI
chatConfig	Object	❌	Configuração do chat

Exemplo Completo:

import { GovernanceProvider } from '@bricks2k/governance';

<GovernanceProvider
  // Utilitários customizados
  utils={{
    copyToClipboard: async (text) => {
      await navigator.clipboard.writeText(text);
      toast.success('Copiado!');
    },
    maskCredential: (value) => '•'.repeat(value.length)
  }}
  
  // Cliente de banco de dados
  client={supabase}
  
  // Configurações
  config={{
    supabase: {
      url: process.env.VITE_SUPABASE_URL,
      anonKey: process.env.VITE_SUPABASE_ANON_KEY
    }
  }}
  
  // Health check customizado
  healthCheck={async () => {
    const { data, error } = await supabase.from('_health').select('*');
    return { healthy: !error, services: [...] };
  }}
  
  // Chat AI (opcional)
  ChatInterface={ChatInterface}
  chatConfig={{
    endpoint: '/api/chat',
    context: 'development'
  }}
>
  <YourApp />
</GovernanceProvider>

useGovernance Hook

Hook para acessar o contexto do Provider.

import { useGovernance } from '@bricks2k/governance';

function MyComponent({ onCopy }) {
  const context = useGovernance();
  
  // Prioridade: props > context > default
  const copyFn = onCopy || context?.utils?.copyToClipboard || defaultCopy;
  
  return <button onClick={() => copyFn('text')}>Copy</button>;
}

Componentes Principais

<GovernanceDashboard />

Dashboard completo com todas as abas.

import { GovernanceDashboard } from '@bricks2k/governance';

<GovernanceDashboard />

<TechDebtTab />

Aba de débitos técnicos standalone.

import { TechDebtTab } from '@bricks2k/governance';

<TechDebtTab />

<BacklogTab />

Aba de backlog standalone.

import { BacklogTab } from '@bricks2k/governance';

<BacklogTab />

<SupabaseTab />

Aba de integração Supabase (requer Provider com client e config).

import { GovernanceProvider, SupabaseTab } from '@bricks2k/governance';

<GovernanceProvider client={supabase} config={{ supabase: {...} }}>
  <SupabaseTab />
</GovernanceProvider>

<DevAssistantTab />

Assistente de desenvolvimento com AI (requer Provider com ChatInterface).

import { GovernanceProvider, DevAssistantTab } from '@bricks2k/governance';
import ChatInterface from './components/ai/ChatInterface';

<GovernanceProvider
  ChatInterface={ChatInterface}
  chatConfig={{ endpoint: '/api/chat' }}
>
  <DevAssistantTab />
</GovernanceProvider>

Utilitários

import {
  parseTechDebtRegistry,
  parseBacklogRegistry,
  calculateHealthScore
} from '@bricks2k/governance';

// Parse de arquivos Markdown
const { debts, stats } = parseTechDebtRegistry(markdownContent);

// Cálculo de health score do projeto
const score = calculateHealthScore(techDebtStats, backlogStats);

🧪 Desenvolvimento

# Instalar dependências
npm install

# Desenvolvimento
npm run dev

# Build
npm run build

# Testes
npm test

# Lint
npm run lint

📁 Estrutura do Projeto

governance/
├── src/
│   ├── components/       # Componentes React
│   │   ├── dashboard/    # Componentes de dashboard
│   │   ├── backlog/      # Módulo de backlog
│   │   ├── logs/         # Módulo de logs
│   │   ├── supabase/     # Módulo Supabase
│   │   ├── techdebt/     # Módulo tech debt
│   │   └── widgets/      # Widgets reutilizáveis
│   ├── utils/            # Utilitários (parsers, helpers)
│   └── index.js          # Entry point
├── tests/                # Testes
├── docs/                 # Documentação
└── package.json

🤝 Contribuindo

Este é um repositório privado mantido por @bricks2k.

Workflow

1. Criar branch para mudanças
2. Testar localmente
3. Criar PR
4. Review e testes
5. Merge para main

📝 Changelog

v1.0.0 (2026-01-17)

• ✨ Versão inicial com sistema completo
• 📦 35 componentes React organizados
• 🎯 GovernanceProvider para injeção de dependências
• 🛠️ 3 utilitários principais (parsers e health check)
• 📚 Documentação completa com exemplos
• ✅ Testes unitários com Vitest
• 🔧 ESLint configurado para qualidade de código
• 📋 Suporte a 7 abas: Overview, Tech Debt, Backlog, Logs, Architecture, Supabase, AI Assistant

📄 Licença

MIT © bricks2k

---

Última Atualização: 2026-01-17
Autor: Nexus Team
Status: Em Desenvolvimento