@fontdata/ai-harness 2.6.0 → 3.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,9 @@
 {
   "name": "fontdata",
-  "version": "2.6.0",
+  "version": "3.0.0",
+  "mcpServers": {
+    "banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@3.0.0", "banco-dados-mcp"] }
+  },
   "description": "Harness de engenharia com IA da Fontdata para Claude Code",
   "author": { "name": "Fontdata" },
   "commands": ["./templates/commands"],

package/README.md

@@ -96,6 +96,7 @@ npx @fontdata/ai-harness init --comandos resolver-bug,nova-tarefa --sem-harness
 | `--sem-harness` | Não inclui o comando-mestre `/harness` |
 | `--sem-hooks` / `--sem-agents` | Não instala hooks / agents |
 | `--sem-comentarios` | Não instala a rule de comentários, o hook e a catraca do legado |
+| `--sem-banco-dados` | Não registra o servidor MCP de banco no `.mcp.json` e lembra a recusa no config |
 | `--claude-md criar\|manter\|backup\|sobrescrever` | O que fazer com o `CLAUDE.md` (padrão: `criar`) |
 | `--conflito sobrescrever\|pular` | Arquivos que já existem (padrão: `pular`) |
 | `--yes` | Aplica; sem ele, só simula |
@@ -110,7 +111,8 @@ aprovação, inclusive no modo auto do Claude Code:
 
 - `permissions.allow`: o rastro, a checagem de conflitos, o `doctor` e a `memoria` do harness; `git add`,
   `git commit` e `git push` (o `/git-commit-push`); a abertura de sub-agents (`Agent`); as ferramentas `Read`,
-  `Grep`, `Glob` e `Skill`; e consultas só de leitura
+  `Grep`, `Glob` e `Skill`; as quatro ferramentas do servidor MCP de banco, inclusive a `consultar`, que
+  devolve os dados pessoais mascarados; e consultas só de leitura
   (`git status`, `diff`, `log`, `show`, `blame`, `gh pr view`, `gh pr diff`, `npm outdated`...);
 - `permissions.deny`: o push forçado (`--force`, `-f`, `--force-with-lease` e refspec com `+`), que vence o `allow`.
 
@@ -119,6 +121,35 @@ Ficam de fora os comandos de teste e build, que variam por projeto, e os que reg
 Nos modos 1 e 2 nada é gravado no projeto: rode `npx @fontdata/ai-harness update --yes` num projeto já instalado,
 ou `init`, para receber as regras.
 
+## Conexões de banco de dados
+
+O Claude pode ler o banco do projeto (PostgreSQL, MariaDB ou SQLite) sem que ninguém cole credencial no chat. O
+jeito recomendado para a equipe é a **conexão do projeto**: o `.ai-harness/config.json` (versionado) declara o nome
+da conexão e o nome da variável de ambiente (`dsn_env`), e cada dev guarda o DSN nessa variável, no `env` do
+`.claude/settings.local.json` (fora do git), no `.env` ou no ambiente:
+
+```bash
+npx @fontdata/ai-harness banco-dados adicionar erp --projeto   # pergunta os dados, testa e grava ERP_DATABASE_URL
+npx @fontdata/ai-harness banco-dados testar
+```
+
+O `adicionar --projeto` grava `{ "nome": "erp", "dsn_env": "ERP_DATABASE_URL" }` em `banco_dados.conexoes` e a variável
+no `.claude/settings.local.json`. Faça commit do `config.json`; cada colega roda o mesmo comando, que grava só a
+variável. `"producao": true` na entrada vale para a equipe toda. Quem prefere um cadastro por máquina
+(`~/.config/ai-harness/conexoes.json`) usa `banco-dados adicionar erp-dev` sem `--projeto` e `banco-dados usar erp-dev` no
+projeto.
+
+O servidor MCP `banco_dados` entrega ao Claude `listar_conexoes`, `listar_tabelas`, `descrever_tabela` e
+`consultar`, tudo somente leitura. Ele vem no plugin; sem plugin, o `init` e o `update` o registram no `.mcp.json`
+(`--sem-banco-dados` pula). Conexão de produção nasce bloqueada. Use um usuário de banco só com leitura.
+
+Os dados pessoais (CPF, CNPJ, e-mail, telefone, nome, endereço e afins) saem com **mascaramento LGPD**, feito no
+servidor antes de a resposta chegar ao Claude; os filtros rodam sobre o dado real. Por isso a `consultar` fica
+liberada nas permissões, sem pedir aprovação. Falsos positivos e colunas extras se ajustam em
+`banco_dados.lgpd.liberar_colunas` e `banco_dados.lgpd.mascarar_colunas`; desligar, só no cadastro da máquina. Conexões do
+projeto, cadastro, limites do filtro, produção, mascaramento e dúvidas frequentes estão no
+[guia de banco de dados](docs/guias/banco-dados.md).
+
 ## Subcomandos do CLI
 
 | Subcomando | O que faz |
@@ -130,6 +161,8 @@ ou `init`, para receber as regras.
 | `memoria [caminho]` | Índice de quem mexeu em cada arquivo (`--arquivo <caminho>`, `--regressao <id>`) |
 | `evento <evento>` | Grava no rastro do trabalho (usado por fluxos e agents) |
 | `conflitos <id>` | Aponta trabalhos em execução que mexem nos mesmos arquivos; `--aguardar` espera liberar (usado pelo `/executar-plan`) |
+| `banco-dados <subcomando>` | Conexões de banco somente leitura: `adicionar`, `listar`, `testar`, `usar`, `remover` |
+| `banco-dados-mcp` | Servidor MCP de leitura do banco, iniciado pelo Claude Code |
 | `comentarios [caminho]` | Instala o hook do padrão de comentários com a catraca do legado (`--yes`) |
 | `list` | Lista o catálogo |
 

package/dist/banco-dados/ambiente.js

@@ -0,0 +1,98 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const SETTINGS_LOCAL_PATH = '.claude/settings.local.json';
+function ehObjeto(valor) {
+    return typeof valor === 'object' && valor !== null && !Array.isArray(valor);
+}
+function lerSettings(caminho) {
+    if (!existsSync(caminho))
+        return { existe: false };
+    let dados;
+    try {
+        dados = JSON.parse(readFileSync(caminho, 'utf8'));
+    }
+    catch {
+        return { existe: true, erro: `${caminho} não é um JSON válido` };
+    }
+    if (!ehObjeto(dados))
+        return { existe: true, erro: `${caminho} precisa ter um objeto JSON na raiz` };
+    if (dados.env !== undefined && !ehObjeto(dados.env)) {
+        return { existe: true, erro: `${caminho}: a chave env precisa ser um objeto` };
+    }
+    return { existe: true, dados };
+}
+export function lerEnvSettingsLocal(raiz) {
+    const leitura = lerSettings(join(raiz, SETTINGS_LOCAL_PATH));
+    if (!('dados' in leitura) || !ehObjeto(leitura.dados.env))
+        return {};
+    const env = {};
+    for (const [chave, valor] of Object.entries(leitura.dados.env)) {
+        if (typeof valor === 'string')
+            env[chave] = valor;
+    }
+    return env;
+}
+function semAspas(valor) {
+    const aspas = /^(["'])(.*)\1$/.exec(valor);
+    if (aspas)
+        return aspas[2] ?? '';
+    return valor.replace(/\s+#.*$/, '');
+}
+/** Lê a variável do .env da raiz; vale a última ocorrência e valor vazio conta como ausente. */
+export function lerVariavelDotEnv(raiz, nome) {
+    const arquivo = join(raiz, '.env');
+    if (!existsSync(arquivo))
+        return null;
+    const nomeEscapado = nome.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const padrao = new RegExp(`^\\s*(?:export\\s+)?${nomeEscapado}\\s*=\\s*(.*?)\\s*$`);
+    let valor = null;
+    for (const linha of readFileSync(arquivo, 'utf8').split(/\r?\n/)) {
+        const encontrado = padrao.exec(linha);
+        if (encontrado)
+            valor = semAspas(encontrado[1] ?? '');
+    }
+    return valor || null;
+}
+/** Procura a variável no processo, no env do settings.local.json e no .env, nessa ordem. */
+export function lerVariavel(nome, raiz, env = process.env) {
+    const doProcesso = env[nome];
+    if (doProcesso)
+        return { valor: doProcesso, fonte: 'processo' };
+    const doSettings = lerEnvSettingsLocal(raiz)[nome];
+    if (doSettings)
+        return { valor: doSettings, fonte: 'settings.local.json' };
+    const doDotEnv = lerVariavelDotEnv(raiz, nome);
+    if (doDotEnv)
+        return { valor: doDotEnv, fonte: '.env' };
+    return null;
+}
+export function validarSettingsLocal(raiz) {
+    const leitura = lerSettings(join(raiz, SETTINGS_LOCAL_PATH));
+    if ('erro' in leitura)
+        throw new Error(leitura.erro);
+}
+/** Grava a variável no env do settings.local.json de forma atômica, preservando as outras chaves e o modo do arquivo. */
+export function gravarVariavelSettingsLocal(raiz, nome, valor) {
+    const caminho = join(raiz, SETTINGS_LOCAL_PATH);
+    const leitura = lerSettings(caminho);
+    if ('erro' in leitura)
+        throw new Error(leitura.erro);
+    const dados = leitura.existe ? leitura.dados : {};
+    const envAtual = ehObjeto(dados.env) ? dados.env : {};
+    if (envAtual[nome] === valor)
+        return { changed: false };
+    const novo = { ...dados, env: { ...envAtual, [nome]: valor } };
+    const modo = leitura.existe ? statSync(caminho).mode & 0o777 : 0o600;
+    mkdirSync(dirname(caminho), { recursive: true });
+    const temporario = `${caminho}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(temporario, `${JSON.stringify(novo, null, 2)}\n`, { mode: modo });
+        chmodSync(temporario, modo);
+        renameSync(temporario, caminho);
+    }
+    catch (erro) {
+        rmSync(temporario, { force: true });
+        throw erro;
+    }
+    return { changed: true };
+}

package/dist/banco-dados/cadastro.js

@@ -0,0 +1,179 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const TIPOS_BANCO = ['postgres', 'mariadb', 'sqlite'];
+export const VERSAO_CADASTRO = 1;
+const NOME_VALIDO = /^[a-z0-9][a-z0-9_-]*$/;
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function caminhoCadastro(env = process.env, home = homedir()) {
+    if (env.AI_HARNESS_CONEXOES)
+        return env.AI_HARNESS_CONEXOES;
+    const base = env.XDG_CONFIG_HOME || join(home, '.config');
+    return join(base, 'ai-harness', 'conexoes.json');
+}
+/** Devolve a conexão normalizada, com o que foi descartado dela, ou o motivo de ser inválida. */
+function validarConexao(valor) {
+    if (!isObject(valor))
+        return 'não é um objeto';
+    const tipo = valor.tipo;
+    if (typeof tipo !== 'string' || !TIPOS_BANCO.includes(tipo)) {
+        return `tipo deve ser ${TIPOS_BANCO.join(', ')}`;
+    }
+    if (valor.producao !== undefined && typeof valor.producao !== 'boolean')
+        return 'producao deve ser true ou false';
+    const conexao = { tipo: tipo };
+    if (tipo === 'sqlite') {
+        if (typeof valor.caminho !== 'string' || !valor.caminho)
+            return 'sqlite exige caminho';
+        conexao.caminho = valor.caminho;
+    }
+    else {
+        if (typeof valor.dsn !== 'string' || !valor.dsn)
+            return `${tipo} exige dsn`;
+        conexao.dsn = valor.dsn;
+    }
+    if (valor.producao !== undefined)
+        conexao.producao = valor.producao;
+    const descartes = [];
+    if (typeof valor.mascaramento === 'boolean')
+        conexao.mascaramento = valor.mascaramento;
+    else if (valor.mascaramento !== undefined)
+        descartes.push('mascaramento deve ser true ou false; vale true');
+    return { conexao, descartes };
+}
+/** Lê o arquivo bruto; lança se o JSON ou o formato estiverem quebrados. */
+function lerBruto(caminho) {
+    if (!existsSync(caminho))
+        return {};
+    let dados;
+    try {
+        dados = JSON.parse(readFileSync(caminho, 'utf8'));
+    }
+    catch (erro) {
+        throw new Error(`${caminho}: JSON inválido (${erro.message})`);
+    }
+    if (!isObject(dados) || (dados.conexoes !== undefined && !isObject(dados.conexoes))) {
+        throw new Error(`${caminho}: formato inválido, esperado {"versao": 1, "conexoes": {...}}`);
+    }
+    return dados.conexoes ?? {};
+}
+/** Lê o cadastro sem lançar; conexões inválidas são descartadas e viram problema. */
+export function lerCadastro(caminho = caminhoCadastro()) {
+    let brutas;
+    try {
+        brutas = lerBruto(caminho);
+    }
+    catch (erro) {
+        return { conexoes: {}, problemas: [erro.message] };
+    }
+    const conexoes = {};
+    const problemas = [];
+    for (const [nome, valor] of Object.entries(brutas)) {
+        const resultado = validarConexao(valor);
+        if (typeof resultado === 'string') {
+            problemas.push(`${caminho}: conexão ${nome} ignorada, ${resultado}`);
+            continue;
+        }
+        for (const descarte of resultado.descartes)
+            problemas.push(`${caminho}: conexão ${nome}, ${descarte}`);
+        conexoes[nome] = { ...resultado.conexao, mascaramento: resultado.conexao.mascaramento ?? true };
+    }
+    return { conexoes, problemas };
+}
+function gravarAtomico(caminho, conexoes) {
+    const pasta = dirname(caminho);
+    if (!existsSync(pasta)) {
+        mkdirSync(pasta, { recursive: true, mode: 0o700 });
+        chmodSync(pasta, 0o700);
+    }
+    const temporario = `${caminho}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(temporario, `${JSON.stringify({ versao: VERSAO_CADASTRO, conexoes }, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(temporario, 0o600);
+        renameSync(temporario, caminho);
+    }
+    catch (erro) {
+        rmSync(temporario, { force: true });
+        throw erro;
+    }
+}
+export function salvarConexao(nome, conexao, opcoes = {}) {
+    if (!NOME_VALIDO.test(nome)) {
+        throw new Error(`Nome de conexão inválido: "${nome}". Use letras minúsculas, números, _ e -, começando por letra ou número.`);
+    }
+    const validada = validarConexao(conexao);
+    const motivo = typeof validada === 'string' ? validada : validada.descartes[0];
+    if (typeof validada === 'string' || motivo !== undefined)
+        throw new Error(`Conexão ${nome} inválida: ${motivo}.`);
+    const caminho = opcoes.caminho ?? caminhoCadastro();
+    const brutas = lerBruto(caminho);
+    if (nome in brutas && !opcoes.substituir) {
+        throw new Error(`A conexão ${nome} já existe em ${caminho}. Use a opção de substituir para trocá-la.`);
+    }
+    gravarAtomico(caminho, { ...brutas, [nome]: validada.conexao });
+}
+/** Devolve true quando a conexão existia e foi removida. */
+export function removerConexao(nome, caminho = caminhoCadastro()) {
+    const brutas = lerBruto(caminho);
+    if (!(nome in brutas))
+        return false;
+    const { [nome]: _removida, ...restantes } = brutas;
+    gravarAtomico(caminho, restantes);
+    return true;
+}
+function lerUrl(dsn) {
+    try {
+        return new URL(dsn);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resumirConexao(conexao) {
+    if (conexao.tipo === 'sqlite')
+        return `sqlite ${conexao.caminho ?? ''}`.trimEnd();
+    const url = lerUrl(conexao.dsn ?? '');
+    if (!url || !url.hostname)
+        return `${conexao.tipo} (dsn não reconhecido)`;
+    const porta = url.port ? `:${url.port}` : '';
+    return `${conexao.tipo} ${url.hostname}${porta}${url.pathname === '/' ? '' : url.pathname}`;
+}
+function decodificar(texto) {
+    try {
+        return decodeURIComponent(texto);
+    }
+    catch {
+        return texto;
+    }
+}
+/** Troca `usuario:senha` e a senha do DSN por *** em qualquer texto, nas formas codificada e decodificada. */
+export function ocultarSenha(texto, conexao) {
+    if (!conexao.dsn)
+        return texto;
+    const url = lerUrl(conexao.dsn);
+    const credencial = url
+        ? { usuario: url.username, senha: url.password }
+        : /^[a-z][a-z0-9+.-]*:\/\/(?<usuario>[^:@/]*):(?<senha>[^@]*)@/i.exec(conexao.dsn)?.groups;
+    if (!credencial?.senha)
+        return texto;
+    const usuario = credencial.usuario ?? '';
+    const senha = credencial.senha;
+    const trechos = new Set();
+    const pares = [
+        [usuario, senha],
+        [decodificar(usuario), decodificar(senha)],
+    ];
+    for (const [u, s] of pares) {
+        if (u)
+            trechos.add(`${u}:${s}`);
+        trechos.add(s);
+    }
+    let resultado = texto;
+    for (const trecho of [...trechos].sort((a, b) => b.length - a.length)) {
+        if (trecho)
+            resultado = resultado.replaceAll(trecho, '***');
+    }
+    return resultado;
+}