@fontdata/ai-harness 3.0.0 → 3.1.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -129,15 +129,16 @@ da conexão e o nome da variável de ambiente (`dsn_env`), e cada dev guarda o D
 `.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 adicionar erp   # na raiz do 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 `adicionar` grava `{ "nome": "erp", "dsn_env": "ERP_DATABASE_URL" }` em `banco_dados.conexoes` e a variável no
+`.claude/settings.local.json`; fora da raiz de um projeto (sem `.git` nem `.ai-harness/config.json`), ele recusa sem
+gravar nada. 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, e `banco-dados remover erp` tira a conexão do projeto. Quem
+prefere um cadastro por máquina (`~/.config/ai-harness/conexoes.json`) usa `banco-dados adicionar erp-dev --global` 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`

package/dist/banco-dados/ambiente.js

@@ -81,12 +81,27 @@ export function gravarVariavelSettingsLocal(raiz, nome, valor) {
     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 });
+    gravarAtomico(caminho, { ...dados, env: { ...envAtual, [nome]: valor } }, modo);
+    return { changed: true };
+}
+/** Tira a variável do env do settings.local.json com a mesma gravação atômica; arquivo ou chave ausente não escreve. */
+export function removerVariavelSettingsLocal(raiz, nome) {
+    const caminho = join(raiz, SETTINGS_LOCAL_PATH);
+    const leitura = lerSettings(caminho);
+    if ('erro' in leitura)
+        throw new Error(leitura.erro);
+    if (!leitura.existe || !ehObjeto(leitura.dados.env) || !Object.hasOwn(leitura.dados.env, nome))
+        return { changed: false };
+    const { [nome]: _removida, ...envRestante } = leitura.dados.env;
+    gravarAtomico(caminho, { ...leitura.dados, env: envRestante }, statSync(caminho).mode & 0o777);
+    return { changed: true };
+}
+function gravarAtomico(caminho, dados, modo) {
     const temporario = `${caminho}.${process.pid}.${Date.now()}.tmp`;
     try {
-        writeFileSync(temporario, `${JSON.stringify(novo, null, 2)}\n`, { mode: modo });
+        writeFileSync(temporario, `${JSON.stringify(dados, null, 2)}\n`, { mode: modo });
         chmodSync(temporario, modo);
         renameSync(temporario, caminho);
     }
@@ -94,5 +109,4 @@ export function gravarVariavelSettingsLocal(raiz, nome, valor) {
         rmSync(temporario, { force: true });
         throw erro;
     }
-    return { changed: true };
 }

package/dist/banco-dados/command.js

@@ -2,24 +2,28 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { EOL } from 'node:os';
 import { join, resolve } from 'node:path';
 import * as p from '@clack/prompts';
-import { comSecaoBanco, CONFIG_PATH, gravarConexaoProjeto, readConfig, REGRA_DSN_ENV, REGRA_NOME_CONEXAO, secaoBanco, validarConfigParaEscrita, writeDefaultConfig, } from '../config/config.js';
+import { comSecaoBanco, CONFIG_PATH, gravarConexaoProjeto, readConfig, removerConexaoProjeto, REGRA_DSN_ENV, REGRA_NOME_CONEXAO, secaoBanco, validarConfigParaEscrita, writeDefaultConfig, } from '../config/config.js';
 import { suggestFlag } from '../install/flags.js';
 import { caminhoCadastro, lerCadastro, ocultarSenha, removerConexao, resumirConexao, salvarConexao, TIPOS_BANCO, } from './cadastro.js';
-import { gravarVariavelSettingsLocal, lerEnvSettingsLocal, lerVariavel, SETTINGS_LOCAL_PATH, validarSettingsLocal } from './ambiente.js';
+import { gravarVariavelSettingsLocal, lerEnvSettingsLocal, lerVariavel, removerVariavelSettingsLocal, SETTINGS_LOCAL_PATH, validarSettingsLocal, } from './ambiente.js';
 import { interpretarDsn, resolverConexoes } from './conexao.js';
 import { criarDriver as criarDriverPadrao } from './drivers/index.js';
 const AJUDA = [
     'Uso: ai-harness banco-dados <subcomando>',
     '',
-    '  adicionar <nome> [--dsn <dsn>] [--producao] [--sem-testar] [--substituir]',
-    '                     cadastra a conexão nesta máquina (sem --dsn, pergunta os dados)',
-    '  adicionar <nome> --projeto [--env <VAR>] [--dsn <dsn>] [--producao] [--sem-testar] [--substituir]',
-    '                     grava o DSN na variável <NOME>_DATABASE_URL (ou --env) do .claude/settings.local.json',
+    '  adicionar <nome> [--env <VAR>] [--dsn <dsn>] [--producao] [--sem-testar] [--substituir]',
+    '                     grava no projeto: o DSN na variável <NOME>_DATABASE_URL (ou --env) do .claude/settings.local.json',
     '                     e a conexão { nome, dsn_env } em banco_dados.conexoes do .ai-harness/config.json',
+    '                     (sem --dsn, pergunta os dados)',
+    '  adicionar <nome> --global [--dsn <dsn>] [--producao] [--sem-testar] [--substituir]',
+    '                     cadastra a conexão nesta máquina',
     '  listar             mostra as conexões cadastradas e as do projeto, sem a senha',
     '  testar [nome]      testa a conexão pedida ou todas as do projeto',
-    '  usar <nome...>     grava banco_dados.conexoes no .ai-harness/config.json (mantém as entradas { nome, dsn_env })',
-    '  remover <nome>     apaga a conexão do cadastro',
+    '  usar <nome...>     grava banco_dados.conexoes no .ai-harness/config.json, para conexões do cadastro global',
+    '                     (mantém as entradas { nome, dsn_env })',
+    '  remover <nome> [--global]',
+    '                     tira a conexão do projeto e a variável dela do .claude/settings.local.json;',
+    '                     com --global, apaga a conexão do cadastro desta máquina',
 ].join(EOL);
 const PORTA_PADRAO = { postgres: '5432', mariadb: '3306' };
 const ESQUEMA = { postgres: 'postgres', mariadb: 'mysql' };
@@ -118,14 +122,15 @@ function conexaoDoDsn(dsn, cwd, producao) {
     return conexao;
 }
 async function adicionar(ctx, argv) {
-    const { posicionais, marcadas, valores } = lerArgumentos(argv, ['--producao', '--sem-testar', '--substituir', '--projeto'], ['--dsn', '--env']);
+    const { posicionais, marcadas, valores } = lerArgumentos(argv, ['--producao', '--sem-testar', '--substituir', '--global'], ['--dsn', '--env']);
     const [nome, ...sobra] = posicionais;
-    if (!nome || sobra.length > 0)
-        throw new Error('Uso: ai-harness banco-dados adicionar <nome> [--projeto [--env <VAR>]] [--dsn <dsn>] [--producao] [--sem-testar] [--substituir]');
-    if (marcadas.has('--projeto'))
+    if (!nome || sobra.length > 0) {
+        throw new Error('Uso: ai-harness banco-dados adicionar <nome> [--global | --env <VAR>] [--dsn <dsn>] [--producao] [--sem-testar] [--substituir]');
+    }
+    if (!marcadas.has('--global'))
         return adicionarNoProjeto(ctx, nome, marcadas, valores);
     if (valores['--env'] !== undefined)
-        throw new Error('--env só vale com --projeto.');
+        throw new Error('--env não vale com --global.');
     const substituir = marcadas.has('--substituir');
     if (!substituir && nome in lerCadastro(ctx.cadastro).conexoes) {
         ctx.erro(`A conexão ${nome} já existe em ${ctx.cadastro}. Use --substituir para trocá-la.`);
@@ -169,6 +174,10 @@ function variavelPadrao(nome) {
     return `${nome.toUpperCase().replace(/-/g, '_')}_DATABASE_URL`;
 }
 async function adicionarNoProjeto(ctx, nome, marcadas, valores) {
+    if (!existsSync(join(ctx.cwd, '.git')) && !existsSync(join(ctx.cwd, CONFIG_PATH))) {
+        ctx.erro(`Nenhum projeto em ${ctx.cwd} (sem .git nem ${CONFIG_PATH}). Rode na raiz do projeto ou use --global para cadastrar nesta máquina.`);
+        return 1;
+    }
     const substituir = marcadas.has('--substituir');
     if (!REGRA_NOME_CONEXAO.test(nome)) {
         ctx.erro(`Nome de conexão inválido: ${JSON.stringify(nome)}; use só minúsculas, dígitos, - e _, começando por minúscula ou dígito.`);
@@ -260,7 +269,7 @@ function listar(ctx, argv) {
     const doProjeto = config.banco_dados.conexoes.flatMap((nome) => config.banco_dados.projeto[nome] ?? []);
     const nomes = Object.keys(conexoes).sort();
     if (nomes.length === 0 && doProjeto.length === 0) {
-        ctx.log(`Nenhuma conexão cadastrada em ${ctx.cadastro}. Cadastre com: npx @fontdata/ai-harness banco-dados adicionar <nome>`);
+        ctx.log('Nenhuma conexão. Na raiz do projeto, rode: npx @fontdata/ai-harness banco-dados adicionar <nome>');
         return 0;
     }
     for (const nome of nomes) {
@@ -313,7 +322,7 @@ async function testar(ctx, argv) {
             for (const problema of resolvidas.problemas)
                 ctx.erro(problema);
         for (const faltando of resolvidas.faltando.filter((item) => nome === undefined || item === nome)) {
-            ctx.erro(`Conexão ${faltando} não encontrada nesta máquina; rode banco-dados adicionar ${faltando}.`);
+            ctx.erro(`Conexão ${faltando} não encontrada nesta máquina; rode banco-dados adicionar ${faltando} --global.`);
             ok = false;
         }
         for (const ausente of resolvidas.variaveisAusentes.filter(pedida)) {
@@ -327,7 +336,7 @@ async function testar(ctx, argv) {
         }
         alvos = resolvidas.conexoes.filter(pedida);
         if (alvos.length === 0 && ok) {
-            ctx.erro('Nenhuma conexão de banco configurada neste projeto; rode npx @fontdata/ai-harness banco-dados usar <nome>.');
+            ctx.erro('Nenhuma conexão de banco configurada neste projeto; rode npx @fontdata/ai-harness banco-dados adicionar <nome>.');
             return 1;
         }
     }
@@ -371,15 +380,17 @@ function usar(ctx, argv) {
     const { conexoes } = lerCadastro(ctx.cadastro);
     const ausentes = unicos.filter((nome) => !(nome in conexoes) && !objetos.has(nome));
     if (ausentes.length > 0) {
-        ctx.erro(`Aviso: sem cadastro nesta máquina para ${ausentes.join(', ')}; rode banco-dados adicionar <nome> para cada uma.`);
+        ctx.erro(`Aviso: sem cadastro nesta máquina para ${ausentes.join(', ')}; rode banco-dados adicionar <nome> --global para cada uma.`);
     }
     return 0;
 }
 function remover(ctx, argv) {
-    const { posicionais } = lerArgumentos(argv, []);
+    const { posicionais, marcadas } = lerArgumentos(argv, ['--global']);
     const [nome, ...sobra] = posicionais;
     if (!nome || sobra.length > 0)
-        throw new Error('Uso: ai-harness banco-dados remover <nome>');
+        throw new Error('Uso: ai-harness banco-dados remover <nome> [--global]');
+    if (!marcadas.has('--global'))
+        return removerDoProjeto(ctx, nome);
     if (!removerConexao(nome, ctx.cadastro)) {
         ctx.erro(`Conexão ${nome} não existe em ${ctx.cadastro}.`);
         return 1;
@@ -387,7 +398,34 @@ function remover(ctx, argv) {
     ctx.log(`Conexão ${nome} removida de ${ctx.cadastro}.`);
     return 0;
 }
-/** `ai-harness banco-dados <subcomando>`: cadastro de conexões da máquina e escolha das conexões do projeto. */
+function removerDoProjeto(ctx, nome) {
+    validarSettingsLocal(ctx.cwd);
+    validarConfigParaEscrita(ctx.cwd);
+    const removida = removerConexaoProjeto(ctx.cwd, nome);
+    if (removida === null) {
+        const noCadastro = nome in lerCadastro(ctx.cadastro).conexoes;
+        ctx.erro(`Conexão ${nome} não está em banco_dados.conexoes de ${CONFIG_PATH}.${noCadastro ? ` Para o cadastro desta máquina, use remover ${nome} --global.` : ''}`);
+        return 1;
+    }
+    ctx.log(`Conexão ${nome} removida de banco_dados.conexoes de ${CONFIG_PATH}.`);
+    const variavel = typeof removida === 'string' ? undefined : removida.dsn_env;
+    if (variavel === undefined)
+        return 0;
+    const atual = lerEnvSettingsLocal(ctx.cwd)[variavel];
+    if (atual !== undefined)
+        ctx.sensiveis.push(sensivel(atual));
+    const outra = Object.values(readConfig(ctx.cwd).config.banco_dados.projeto).find((conexao) => conexao.dsn_env === variavel);
+    if (outra)
+        ctx.log(`Variável ${variavel} mantida em ${SETTINGS_LOCAL_PATH}: a conexão ${outra.nome} também a usa.`);
+    else if (removerVariavelSettingsLocal(ctx.cwd, variavel).changed)
+        ctx.log(`Variável ${variavel} removida de ${SETTINGS_LOCAL_PATH}.`);
+    ctx.log(`Se ${variavel} estiver definida no .env ou no ambiente, ela não foi tocada.`);
+    return 0;
+}
+/**
+ * `ai-harness banco-dados <subcomando>`: conexões do projeto (padrão), cadastro global de conexões da máquina
+ * (`--global`) e escolha das conexões do cadastro que o projeto usa.
+ */
 export async function runBancoCommand(argv, opcoes = {}) {
     const saida = opcoes.saida ?? { log: (texto) => console.log(texto), erro: (texto) => console.error(texto) };
     const cadastro = opcoes.caminhoCadastro ?? caminhoCadastro();

package/dist/banco-dados/conexao.js

@@ -118,7 +118,7 @@ export function resolverConexoes(raiz, opcoes = {}) {
 }
 export function escolherConexao(resolvidas, nome) {
     if (resolvidas.length === 0) {
-        throw new Error('Nenhuma conexão de banco configurada neste projeto; rode npx @fontdata/ai-harness banco-dados usar <nome>');
+        throw new Error('Nenhuma conexão de banco configurada neste projeto; rode npx @fontdata/ai-harness banco-dados adicionar <nome> na raiz do projeto');
     }
     const escolhida = nome === undefined ? resolvidas[0] : resolvidas.find((conexao) => conexao.nome === nome);
     if (!escolhida)

package/dist/banco-dados/ferramentas.js

@@ -55,16 +55,15 @@ export const INSTRUCOES = [
     'Use estas ferramentas para ler o banco de dados do projeto; o acesso é somente leitura.',
     'Nunca peça nem repita credenciais, senhas ou DSNs no chat.',
     'As conexões vêm do cadastro da máquina ou do projeto: uma conexão do projeto é declarada em banco_dados.conexoes do .ai-harness/config.json com dsn_env (o nome da variável), e o valor da variável fica no .claude/settings.local.json, no .env ou no ambiente.',
-    'Sem conexão configurada, oriente o usuário a rodar no terminal `npx @fontdata/ai-harness banco-dados adicionar <nome>` e, no projeto, `npx @fontdata/ai-harness banco-dados usar <nome>`.',
+    'Sem conexão configurada, oriente o usuário a rodar na raiz do projeto `npx @fontdata/ai-harness banco-dados adicionar <nome>`.',
     'Se a variável de uma conexão do projeto não estiver definida, oriente a defini-la no .claude/settings.local.json, no .env ou no ambiente.',
     'Antes de consultar, rode listar_tabelas e descrever_tabela para conhecer o esquema.',
     'Em consultar, selecione só as colunas necessárias e filtre as linhas; evite SELECT *.',
     'Somente leitura: comandos que alteram dados ou esquema são recusados.',
     'Os dados pessoais (CPF, e-mail, telefone, nome e afins) vêm mascarados, e o rodapé de consultar diz o que foi mascarado. Não tente contornar o mascaramento: não concatene, fatie, converta nem compare valores para reconstruir o original. Peça só as colunas necessárias.',
 ].join('\n');
-const ORIENTACAO_USAR = 'rode npx @fontdata/ai-harness banco-dados usar <nome> no projeto';
 function orientarAdicionar(nome) {
-    return `Conexão ${nome} não encontrada nesta máquina; rode npx @fontdata/ai-harness banco-dados adicionar ${nome}`;
+    return `Conexão ${nome} não encontrada nesta máquina; rode npx @fontdata/ai-harness banco-dados adicionar ${nome} --global`;
 }
 function orientarVariavel(nome, variavel) {
     return `A variável ${variavel} da conexão ${nome} não está definida; defina-a no .claude/settings.local.json, no .env ou no ambiente`;
@@ -173,7 +172,7 @@ async function executar(nome, args, contexto, banco, resolvidas) {
         if (descartadas.length > 0)
             dados.descartadas = descartadas;
         if (conexoes.length + faltando.length + variaveisAusentes.length + descartadas.length === 0) {
-            dados.orientacao = `Nenhuma conexão configurada; rode npx @fontdata/ai-harness banco-dados adicionar <nome> e ${ORIENTACAO_USAR}`;
+            dados.orientacao = 'Nenhuma conexão configurada; rode npx @fontdata/ai-harness banco-dados adicionar <nome> na raiz do projeto';
         }
         if (resolvidas.problemas.length > 0)
             dados.problemas = resolvidas.problemas;

package/dist/config/config.js

@@ -301,6 +301,30 @@ export function gravarConexaoProjeto(root, conexao, { substituir = false } = {})
     const base = raw ?? lerJsonParaEscrita(file, 'banco_dados.conexoes');
     writeFileSync(file, `${JSON.stringify(comSecaoBanco(base, { ...banco, conexoes: proximas }), null, 2)}\n`);
 }
+/**
+ * Tira de `banco_dados.conexoes` a primeira entrada com o nome (objeto, mesmo inválido, ou texto), preservando
+ * o resto do JSON, e devolve o que leu. Sem config ou sem o nome, devolve null e não escreve.
+ * JSON inválido ou `conexoes` que não é lista lança sem tocar no arquivo.
+ */
+export function removerConexaoProjeto(root, nome) {
+    const file = join(root, CONFIG_PATH);
+    if (!existsSync(file))
+        return null;
+    const raw = lerJsonParaEscrita(file, 'banco_dados.conexoes');
+    const banco = secaoBanco(raw);
+    const conexoes = banco.conexoes === undefined ? [] : banco.conexoes;
+    if (!Array.isArray(conexoes))
+        throw new Error(`banco_dados.conexoes em ${CONFIG_PATH} não é uma lista; corrija-o antes de remover a conexão ${nome}.`);
+    const posicao = conexoes.findIndex((entrada) => (isObject(entrada) ? entrada.nome : entrada) === nome);
+    if (posicao === -1)
+        return null;
+    const entrada = conexoes[posicao];
+    const proximas = conexoes.filter((_atual, i) => i !== posicao);
+    writeFileSync(file, `${JSON.stringify(comSecaoBanco(raw, { ...banco, conexoes: proximas }), null, 2)}\n`);
+    if (!isObject(entrada))
+        return nome;
+    return typeof entrada.dsn_env === 'string' ? { nome, dsn_env: entrada.dsn_env } : { nome };
+}
 /**
  * Grava só `banco_dados.registrar_mcp`, preservando o resto do JSON; sem config, cria uma com os padrões
  * e essa chave. JSON inválido é recusado sem tocar no arquivo.

package/dist/doctor/checks.js

@@ -425,7 +425,7 @@ function checkBancoProjeto(root, config, env) {
             id: 'banco-variavel-ausente',
             severidade: 'aviso',
             mensagem: `A conexão ${nome}, declarada em banco_dados.conexoes de ${join(root, CONFIG_PATH)}, lê o DSN da variável ${dsn_env}, que não está definida no ambiente, em ${SETTINGS_LOCAL_PATH} nem no .env.`,
-            correcao: `Defina ${dsn_env} com \`npx @fontdata/ai-harness banco-dados adicionar ${nome} --projeto\` ou no ambiente do terminal.`,
+            correcao: `Defina ${dsn_env} com \`npx @fontdata/ai-harness banco-dados adicionar ${nome}\` ou no ambiente do terminal.`,
         });
     }
     const envLocal = lerEnvSettingsLocal(root);
@@ -487,7 +487,7 @@ export function checkBanco(root, config, env = process.env) {
             id: 'banco-conexao-ausente',
             severidade: 'aviso',
             mensagem: `A conexão ${nome}, citada em banco_dados.conexoes de ${join(root, CONFIG_PATH)}, não está no cadastro desta máquina (${caminho}).`,
-            correcao: `Cadastre-a com \`npx @fontdata/ai-harness banco-dados adicionar ${nome}\`.`,
+            correcao: `Cadastre-a com \`npx @fontdata/ai-harness banco-dados adicionar ${nome} --global\`.`,
         });
     }
     for (const nome of doCadastro.filter((nome) => conexoes[nome]?.mascaramento === false)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fontdata/ai-harness",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Harness de engenharia com IA da Fontdata para Claude Code: roda os slash commands direto na pasta do projeto via npx, sem instalar nada — ou instala-os em .claude/commands.",
   "type": "module",
   "bin": {