@fontdata/ai-harness 2.6.0 → 3.0.0

package/dist/banco-dados/somente-leitura.js

@@ -0,0 +1,221 @@
+const COMANDOS_INICIAIS = new Set(['select', 'with', 'explain', 'show', 'describe', 'desc']);
+const PALAVRAS_PROIBIDAS = new Set([
+    'insert', 'update', 'delete', 'merge', 'drop', 'alter', 'create', 'truncate', 'grant', 'revoke',
+    'copy', 'call', 'lock', 'vacuum', 'attach', 'detach', 'into', 'outfile',
+]);
+const FUNCOES_PROIBIDAS = [
+    'pg_terminate_backend', 'pg_cancel_backend', 'pg_reload_conf', 'pg_rotate_logfile', 'set_config',
+    'pg_read_file', 'pg_read_binary_file', 'pg_ls_dir', 'pg_ls_logdir', 'pg_ls_waldir', 'pg_stat_file',
+    'pg_switch_wal', 'pg_promote', 'pg_notify', 'lo_import', 'lo_export', 'dblink', 'dblink_exec',
+    'load_file', 'sys_exec', 'sys_eval', 'query_to_xml', 'query_to_xmlschema', 'query_to_xml_and_xmlschema',
+    'cursor_to_xml', 'cursor_to_xmlschema', 'ts_stat', 'crosstab', 'crosstab2', 'crosstab3', 'crosstab4',
+    'connectby',
+];
+const INICIO_PALAVRA = /[\p{L}_]/u;
+const CONTINUA_PALAVRA = /[\p{L}\p{N}_$]/u;
+const DIGITO = /[0-9]/;
+const ESPACO = /\s/;
+const TAG_DOLAR = /^\$([\p{L}_][\p{L}\p{N}_]*)?\$/u;
+export function tokenizar(sql, dialeto) {
+    return tokenizarCom(sql, dialeto, { barraInvertida: dialeto === 'mariadb' });
+}
+function tokenizarCom(sql, dialeto, regras) {
+    const tokens = [];
+    let i = 0;
+    const n = sql.length;
+    const push = (tipo, fim, valor) => {
+        tokens.push({ tipo, valor: valor ?? sql.slice(i, fim), inicio: i });
+        i = fim;
+    };
+    const fecharCitado = (aspa, escapa) => {
+        let j = i + 1;
+        while (j < n) {
+            const c = sql[j];
+            if (escapa && c === '\\') {
+                j += 2;
+                continue;
+            }
+            if (c === aspa) {
+                if (sql[j + 1] === aspa) {
+                    j += 2;
+                    continue;
+                }
+                return j + 1;
+            }
+            j++;
+        }
+        throw new Error(aspa === "'" || (dialeto === 'mariadb' && aspa === '"') ? 'string sem fechamento' : 'identificador sem fechamento');
+    };
+    const citado = (aspa) => {
+        const fim = fecharCitado(aspa, false);
+        push('identificador-citado', fim, sql.slice(i + 1, fim - 1).split(aspa + aspa).join(aspa).toLowerCase());
+    };
+    while (i < n) {
+        const c = sql[i];
+        const prox = sql[i + 1];
+        if (ESPACO.test(c)) {
+            i++;
+            continue;
+        }
+        if (c === '/' && prox === '*') {
+            const resto = sql.slice(i + 2, i + 4);
+            if (resto.startsWith('!') || /^m!/i.test(resto)) {
+                throw new Error('comentário executável /*! ou /*M! não permitido');
+            }
+            push('comentario', fecharComentarioBloco(sql, i, dialeto === 'postgres'));
+            continue;
+        }
+        const comentarioLinha = (c === '-' && prox === '-' && (dialeto !== 'mariadb' || espacoOuFim(sql, i + 2))) ||
+            (c === '#' && dialeto === 'mariadb');
+        if (comentarioLinha) {
+            const quebra = sql.indexOf('\n', i);
+            push('comentario', quebra === -1 ? n : quebra);
+            continue;
+        }
+        if (dialeto === 'postgres') {
+            if ((c === 'e' || c === 'E') && prox === "'") {
+                throw new Error("prefixo E' não permitido");
+            }
+            if ((c === 'u' || c === 'U') && prox === '&' && (sql[i + 2] === "'" || sql[i + 2] === '"')) {
+                throw new Error('prefixo U& não permitido');
+            }
+            if (c === '$') {
+                if (prox !== undefined && DIGITO.test(prox)) {
+                    let j = i + 1;
+                    while (j < n && DIGITO.test(sql[j]))
+                        j++;
+                    push('simbolo', j);
+                    continue;
+                }
+                const tag = TAG_DOLAR.exec(sql.slice(i));
+                if (tag) {
+                    const fim = sql.indexOf(tag[0], i + tag[0].length);
+                    if (fim === -1)
+                        throw new Error('string sem fechamento');
+                    push('string', fim + tag[0].length);
+                    continue;
+                }
+            }
+        }
+        if (c === "'") {
+            push('string', fecharCitado("'", regras.barraInvertida));
+            continue;
+        }
+        if (c === '"') {
+            if (dialeto === 'mariadb')
+                push('string', fecharCitado('"', regras.barraInvertida));
+            else
+                citado('"');
+            continue;
+        }
+        if (c === '`' && dialeto !== 'postgres') {
+            citado('`');
+            continue;
+        }
+        if (c === '[' && dialeto === 'sqlite') {
+            const fim = sql.indexOf(']', i + 1);
+            if (fim === -1)
+                throw new Error('identificador sem fechamento');
+            push('identificador-citado', fim + 1, sql.slice(i + 1, fim).toLowerCase());
+            continue;
+        }
+        if (INICIO_PALAVRA.test(c) || (c === '$' && dialeto === 'mariadb')) {
+            let j = i + 1;
+            while (j < n && CONTINUA_PALAVRA.test(sql[j]))
+                j++;
+            push('palavra', j, sql.slice(i, j).toLowerCase());
+            continue;
+        }
+        if (DIGITO.test(c)) {
+            let j = i + 1;
+            while (j < n && /[0-9.]/.test(sql[j]))
+                j++;
+            push('simbolo', j);
+            continue;
+        }
+        push('simbolo', i + 1);
+    }
+    return tokens;
+}
+function espacoOuFim(sql, j) {
+    const c = sql[j];
+    return c === undefined || ESPACO.test(c);
+}
+function fecharComentarioBloco(sql, inicio, aninhado) {
+    let profundidade = 1;
+    let j = inicio + 2;
+    while (j < sql.length) {
+        if (aninhado && sql[j] === '/' && sql[j + 1] === '*') {
+            profundidade++;
+            j += 2;
+            continue;
+        }
+        if (sql[j] === '*' && sql[j + 1] === '/') {
+            profundidade--;
+            j += 2;
+            if (profundidade === 0)
+                return j;
+            continue;
+        }
+        j++;
+    }
+    throw new Error('comentário sem fechamento');
+}
+function funcaoProibida(sql) {
+    const minusculo = sql.toLowerCase();
+    return FUNCOES_PROIBIDAS.find((nome) => new RegExp(`(?<![a-z0-9_])${nome}(?![a-z0-9_])`).test(minusculo));
+}
+function validarTokens(sql, tokens) {
+    const uteis = tokens.filter((t) => t.tipo !== 'comentario');
+    const primeiro = uteis[0];
+    if (!primeiro)
+        return { ok: false, motivo: 'consulta vazia' };
+    const pontos = uteis.filter((t) => t.tipo === 'simbolo' && t.valor === ';');
+    const ultimo = uteis[uteis.length - 1];
+    if (pontos.length > 1 || (pontos.length === 1 && pontos[0] !== ultimo)) {
+        return { ok: false, motivo: 'mais de um comando: ";" só é aceito no fim' };
+    }
+    if (primeiro.tipo !== 'palavra' || !COMANDOS_INICIAIS.has(primeiro.valor)) {
+        const texto = primeiro.tipo === 'palavra' ? primeiro.valor.toUpperCase() : sql.slice(primeiro.inicio).split(/\s/)[0];
+        return {
+            ok: false,
+            motivo: `comando ${texto} não permitido: só SELECT, WITH, EXPLAIN, SHOW, DESCRIBE ou DESC`,
+        };
+    }
+    const proibida = uteis.find((t) => t.tipo === 'palavra' && PALAVRAS_PROIBIDAS.has(t.valor));
+    if (proibida) {
+        return { ok: false, motivo: `palavra ${proibida.valor.toUpperCase()} não permitida em consulta de leitura` };
+    }
+    const ponto = pontos[0];
+    const final = ponto ? sql.slice(0, ponto.inicio) + sql.slice(ponto.inicio + 1) : sql;
+    return { ok: true, sql: final };
+}
+/**
+ * Filtro léxico de somente leitura. Falha fechado: qualquer dúvida do tokenizador vira recusa.
+ * No MariaDB a consulta precisa passar com e sem escape por `\`, cobrindo `NO_BACKSLASH_ESCAPES`.
+ */
+export function validarLeitura(sql, dialeto) {
+    const funcao = funcaoProibida(sql);
+    if (funcao)
+        return { ok: false, motivo: `função ${funcao} não permitida` };
+    const modos = dialeto === 'mariadb' ? [{ barraInvertida: true }, { barraInvertida: false }] : [{ barraInvertida: false }];
+    let resultado = { ok: false, motivo: 'consulta vazia' };
+    for (const regras of modos) {
+        let tokens;
+        try {
+            tokens = tokenizarCom(sql, dialeto, regras);
+        }
+        catch (erro) {
+            return { ok: false, motivo: erro.message };
+        }
+        resultado = validarTokens(sql, tokens);
+        if (!resultado.ok)
+            return resultado;
+    }
+    return resultado;
+}
+export function identificadoresDoSql(sql, dialeto) {
+    return tokenizar(sql, dialeto)
+        .filter((t) => t.tipo === 'palavra' || t.tipo === 'identificador-citado')
+        .map((t) => t.valor);
+}

package/dist/cli.js

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { allCommands, loadCatalog } from './catalog.js';
 import { runCommand, runnableIds, suggestIds } from './run.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Comandos renomeados depois da 2.7.0: o nome antigo aponta o novo em vez de cair em "Comando desconhecido". */
+const RENAMED_COMMANDS = { banco: 'banco-dados', 'banco-mcp': 'banco-dados-mcp' };
 const RESERVED = new Set([
     'init',
     'doctor',
@@ -14,6 +16,8 @@ const RESERVED = new Set([
     'conflitos',
     'comentarios',
     'memoria',
+    'banco-dados',
+    'banco-dados-mcp',
     'list',
     'run',
     'help',
@@ -47,12 +51,15 @@ Gerenciar:
   init [caminho]  Instala os slash commands em .claude/commands do projeto (interativo)
   doctor [caminho]  Diagnostica a instalação (arquivos, lock, skills, agents, hooks, Node)
   update [caminho]  Atualiza o que foi instalado: --check só lista, --yes aplica, --forcar sobrescreve conflitos
+                    --sem-banco-dados: não registra o MCP de banco no .mcp.json e lembra a recusa no config
   migrar [caminho]  Move docs/specs, plans, bugs e investigacoes para docs/trabalhos/<id>/ (--yes aplica)
                     --reclassificar: planos já migrados em em-execucao viram concluido ou legado
   comentarios [caminho]  Instala o hook de comentários e a catraca do legado (--yes aplica)
   memoria [caminho]  Índice de quem mexeu em cada arquivo (--arquivo <caminho>, --regressao <id do bug>)
   evento <evento>   Grava no rastro do trabalho (--trabalho, --task, --nome, --resultado, --dados '{json}')
   conflitos <id>    Aponta trabalhos em execução que mexem nos mesmos arquivos (--aguardar espera liberar)
+  banco-dados <subcomando>  Conexões de banco somente leitura: adicionar, listar, testar, usar, remover
+  banco-dados-mcp   Servidor MCP de leitura do banco, usado pelo Claude Code (stdio)
   list            Lista todos os comandos disponíveis no catálogo
 
 Init sem perguntas (CI):
@@ -61,6 +68,7 @@ Init sem perguntas (CI):
   --sem-hooks                          não instala os hooks do harness
   --sem-agents                         não instala os agents somente leitura
   --sem-comentarios                    não instala a rule, o hook e a catraca de comentários
+  --sem-banco-dados                    não registra o servidor MCP de banco no .mcp.json
   --claude-md criar|manter|backup|sobrescrever   (padrão: criar)
   --conflito sobrescrever|pular        (padrão: pular)
   --yes                                aplica; sem ele o init só simula
@@ -146,6 +154,15 @@ async function main() {
         const { runConflictsCommand } = await import('./trabalhos/conflitos.js');
         process.exit(await runConflictsCommand(argv.slice(1)));
     }
+    if (cmd === 'banco-dados') {
+        const { runBancoCommand } = await import('./banco-dados/command.js');
+        process.exit(await runBancoCommand(argv.slice(1)));
+    }
+    if (cmd === 'banco-dados-mcp') {
+        const { iniciarServidorMcp } = await import('./banco-dados/mcp.js');
+        await iniciarServidorMcp({ entrada: process.stdin, saida: process.stdout });
+        return;
+    }
     if (cmd === 'update') {
         const { runUpdateCommand } = await import('./update/update.js');
         process.exit(runUpdateCommand(argv.slice(1)));
@@ -165,6 +182,11 @@ async function main() {
         const { args, claudeFlags } = splitArgs(argv.slice(1));
         process.exit(runCommand(cmd, args, claudeFlags));
     }
+    const renamed = RENAMED_COMMANDS[cmd];
+    if (renamed) {
+        console.error(`O comando ${cmd} mudou de nome: use ${renamed}.`);
+        process.exit(1);
+    }
     if (!RESERVED.has(cmd)) {
         const near = suggestIds(cmd.replace(/^\//, ''), ids);
         console.error(`Comando desconhecido: ${cmd}`);

package/dist/config/config.js

@@ -11,17 +11,190 @@ export const DEFAULT_HOOK_MODES = {
     'proteger-contratos': 'aviso',
     'sem-jargao': 'aviso',
 };
+export const MODOS_PRODUCAO = ['aviso', 'bloqueio'];
+export const TIPOS_CONEXAO_PROJETO = ['postgres', 'mariadb', 'sqlite'];
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/** Seção do banco no config; até a 2.7.0 ela se chamava `banco`. */
+export const BANCO_CHAVE = 'banco_dados';
+export const BANCO_CHAVE_LEGADA = 'banco';
+/** Só a seção com o nome antigo existe: ela vale e o update a renomeia. */
+function soSecaoLegada(raw) {
+    return !(BANCO_CHAVE in raw) && BANCO_CHAVE_LEGADA in raw;
+}
+/** A seção do banco no JSON bruto: `banco_dados`, ou a `banco` antiga quando só ela existe. */
+export function secaoBanco(raw) {
+    const secao = soSecaoLegada(raw) ? raw[BANCO_CHAVE_LEGADA] : raw[BANCO_CHAVE];
+    return isObject(secao) ? secao : {};
+}
+/** O JSON com a seção do banco gravada como `banco_dados`; a `banco` antiga é trocada na mesma posição. */
+export function comSecaoBanco(raw, secao) {
+    if (!soSecaoLegada(raw))
+        return { ...raw, [BANCO_CHAVE]: secao };
+    return Object.fromEntries(Object.entries(raw).map(([chave, valor]) => (chave === BANCO_CHAVE_LEGADA ? [BANCO_CHAVE, secao] : [chave, valor])));
+}
+function lerJsonBruto(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(root, CONFIG_PATH), 'utf8'));
+        return isObject(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** O config ainda tem a seção do banco com o nome antigo (`banco`), que o update renomeia. */
+export function temSecaoBancoLegada(root) {
+    const raw = lerJsonBruto(root);
+    return raw !== undefined && soSecaoLegada(raw);
+}
+/** Renomeia a seção `banco` para `banco_dados`, preservando o resto do JSON; devolve se mudou. */
+export function migrarSecaoBanco(root) {
+    const raw = lerJsonBruto(root);
+    if (!raw || !soSecaoLegada(raw))
+        return false;
+    writeFileSync(join(root, CONFIG_PATH), `${JSON.stringify(comSecaoBanco(raw, secaoBanco(raw)), null, 2)}\n`);
+    return true;
+}
 export function defaultConfig() {
     return {
         config_versao: CONFIG_VERSION,
         hooks: { ...DEFAULT_HOOK_MODES },
         rastro: { versionar: false },
         bloqueios: { dias_para_aviso: 7 },
+        banco_dados: {
+            conexoes: [],
+            producao: 'bloqueio',
+            limite_linhas: 200,
+            timeout_segundos: 30,
+            registrar_mcp: true,
+            lgpd: { mascarar_colunas: [], liberar_colunas: [] },
+            projeto: {},
+            declarado: false,
+        },
     };
 }
+function inteiroEntre(value, min, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max;
+}
+const SO_NO_CADASTRO = 'O mascaramento LGPD só pode ser desligado no cadastro da máquina (mascaramento: false na conexão)';
+const REGRA_DE_COLUNA = /^[^.\s]+(\.[^.\s]+){0,2}$/;
+function lerLgpd(raw, lgpd, problems) {
+    if (!isObject(raw)) {
+        problems.push(`banco_dados.lgpd deve ser um objeto com mascarar_colunas e liberar_colunas em ${CONFIG_PATH}.`);
+        return;
+    }
+    if ('desligar' in raw)
+        problems.push(`${SO_NO_CADASTRO}; banco_dados.lgpd.desligar em ${CONFIG_PATH} foi ignorado.`);
+    for (const chave of ['mascarar_colunas', 'liberar_colunas']) {
+        if (!(chave in raw))
+            continue;
+        const lista = raw[chave];
+        if (!Array.isArray(lista)) {
+            problems.push(`banco_dados.lgpd.${chave} deve ser uma lista de colunas em ${CONFIG_PATH}.`);
+            continue;
+        }
+        lgpd[chave] = lista.filter((regra) => {
+            if (typeof regra === 'string' && REGRA_DE_COLUNA.test(regra))
+                return true;
+            problems.push(`Entrada ${JSON.stringify(regra)} ignorada em banco_dados.lgpd.${chave} de ${CONFIG_PATH}; use coluna, tabela.coluna ou schema.tabela.coluna.`);
+            return false;
+        });
+    }
+}
+export const REGRA_NOME_CONEXAO = /^[a-z0-9][a-z0-9_-]*$/;
+export const REGRA_DSN_ENV = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const CHAVES_CONEXAO_PROJETO = ['nome', 'dsn_env', 'tipo', 'producao'];
+/** Devolve o motivo de a conexão ser inválida, ou null se ela puder ser usada. */
+function motivoConexaoInvalida(entrada) {
+    if (typeof entrada.nome !== 'string' || !REGRA_NOME_CONEXAO.test(entrada.nome)) {
+        return 'nome deve usar só minúsculas, dígitos, - e _, começando por minúscula ou dígito';
+    }
+    if (typeof entrada.dsn_env !== 'string' || !REGRA_DSN_ENV.test(entrada.dsn_env)) {
+        return 'dsn_env deve ser um nome de variável de ambiente (letras, dígitos e _, sem começar por dígito)';
+    }
+    if ('tipo' in entrada && !TIPOS_CONEXAO_PROJETO.includes(entrada.tipo)) {
+        return 'tipo deve ser postgres, mariadb ou sqlite';
+    }
+    if ('producao' in entrada && typeof entrada.producao !== 'boolean')
+        return 'producao deve ser true ou false';
+    return null;
+}
+function lerConexoes(conexoes, banco, problems) {
+    banco.declarado = !(Array.isArray(conexoes) && conexoes.length === 0);
+    if (!Array.isArray(conexoes)) {
+        problems.push(`banco_dados.conexoes deve ser uma lista de nomes ou de objetos { nome, dsn_env } em ${CONFIG_PATH}.`);
+        return;
+    }
+    for (const entrada of conexoes) {
+        const citada = JSON.stringify(entrada);
+        let nome;
+        if (typeof entrada === 'string' && entrada.trim() !== '')
+            nome = entrada;
+        else if (isObject(entrada)) {
+            const motivo = motivoConexaoInvalida(entrada);
+            if (motivo) {
+                problems.push(`Entrada ${citada} descartada em banco_dados.conexoes de ${CONFIG_PATH}: ${motivo}.`);
+                continue;
+            }
+            nome = entrada.nome;
+        }
+        else {
+            problems.push(`Entrada ${citada} descartada em banco_dados.conexoes de ${CONFIG_PATH}; use um nome (texto não vazio) ou um objeto { nome, dsn_env }.`);
+            continue;
+        }
+        if (banco.conexoes.includes(nome)) {
+            problems.push(`Entrada ${citada} descartada em banco_dados.conexoes de ${CONFIG_PATH}: o nome "${nome}" já foi declarado antes.`);
+            continue;
+        }
+        banco.conexoes.push(nome);
+        if (typeof entrada === 'string' || !isObject(entrada))
+            continue;
+        for (const chave of Object.keys(entrada).filter((chave) => !CHAVES_CONEXAO_PROJETO.includes(chave))) {
+            problems.push(chave === 'mascaramento'
+                ? `${SO_NO_CADASTRO}; mascaramento da entrada ${citada} em banco_dados.conexoes de ${CONFIG_PATH} foi ignorado.`
+                : `Chave desconhecida ${chave} ignorada na entrada ${citada} de banco_dados.conexoes em ${CONFIG_PATH}.`);
+        }
+        banco.projeto[nome] = {
+            nome,
+            dsn_env: entrada.dsn_env,
+            ...(entrada.tipo === undefined ? {} : { tipo: entrada.tipo }),
+            producao: entrada.producao === true,
+        };
+    }
+}
+function lerBanco(raw, banco, problems) {
+    if ('conexoes' in raw)
+        lerConexoes(raw.conexoes, banco, problems);
+    if ('producao' in raw) {
+        if (MODOS_PRODUCAO.includes(raw.producao))
+            banco.producao = raw.producao;
+        else
+            problems.push(`Modo "${String(raw.producao)}" inválido para banco_dados.producao em ${CONFIG_PATH}; use aviso ou bloqueio.`);
+    }
+    if ('limite_linhas' in raw) {
+        if (inteiroEntre(raw.limite_linhas, 1, 5000))
+            banco.limite_linhas = raw.limite_linhas;
+        else
+            problems.push(`banco_dados.limite_linhas deve ser um inteiro de 1 a 5000 em ${CONFIG_PATH}.`);
+    }
+    if ('timeout_segundos' in raw) {
+        if (inteiroEntre(raw.timeout_segundos, 1, 600))
+            banco.timeout_segundos = raw.timeout_segundos;
+        else
+            problems.push(`banco_dados.timeout_segundos deve ser um inteiro de 1 a 600 em ${CONFIG_PATH}.`);
+    }
+    if ('registrar_mcp' in raw) {
+        if (typeof raw.registrar_mcp === 'boolean')
+            banco.registrar_mcp = raw.registrar_mcp;
+        else
+            problems.push(`banco_dados.registrar_mcp deve ser true ou false em ${CONFIG_PATH}.`);
+    }
+    if ('mascaramento' in raw)
+        problems.push(`${SO_NO_CADASTRO}; banco_dados.mascaramento em ${CONFIG_PATH} foi ignorado.`);
+    if ('lgpd' in raw)
+        lerLgpd(raw.lgpd, banco.lgpd, problems);
+}
 /** Lê a config sobre os padrões; valores inválidos são ignorados e viram problema, nunca erro. */
 export function readConfig(root) {
     const config = defaultConfig();
@@ -59,17 +232,95 @@ export function readConfig(root) {
         else
             problems.push(`bloqueios.dias_para_aviso deve ser um inteiro positivo em ${CONFIG_PATH}.`);
     }
+    const secao = soSecaoLegada(raw) ? raw[BANCO_CHAVE_LEGADA] : raw[BANCO_CHAVE];
+    if (isObject(secao))
+        lerBanco(secao, config.banco_dados, problems);
+    if (soSecaoLegada(raw)) {
+        problems.push(`A seção banco de ${CONFIG_PATH} agora se chama banco_dados; rode npx @fontdata/ai-harness update --yes para renomeá-la.`);
+    }
+    else if (BANCO_CHAVE_LEGADA in raw) {
+        problems.push(`A seção banco de ${CONFIG_PATH} foi ignorada: vale a banco_dados. Apague a banco.`);
+    }
     return { config, problems };
 }
-/** Cria a config com os padrões; retorna false se já existia (nunca sobrescreve). */
+/** Cria a config com os padrões, sem a seção banco_dados; retorna false se já existia (nunca sobrescreve). */
 export function writeDefaultConfig(root) {
     const file = join(root, CONFIG_PATH);
     if (existsSync(file))
         return false;
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, `${JSON.stringify(defaultConfig(), null, 2)}\n`);
+    const { banco_dados: _banco, ...gravada } = defaultConfig();
+    writeFileSync(file, `${JSON.stringify(gravada, null, 2)}\n`);
     return true;
 }
+function lerJsonParaEscrita(file, chave) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (!isObject(parsed))
+        throw new Error(`O ${CONFIG_PATH} está com JSON inválido; corrija-o antes de gravar ${chave}.`);
+    return parsed;
+}
+/** Lança o mesmo erro de `gravarConexaoProjeto` se a config existir com JSON inválido; nunca escreve. */
+export function validarConfigParaEscrita(root) {
+    const file = join(root, CONFIG_PATH);
+    if (existsSync(file))
+        lerJsonParaEscrita(file, 'banco_dados.conexoes');
+}
+/**
+ * Grava a conexão em `banco_dados.conexoes`, preservando o resto do JSON; sem config, cria uma com os padrões.
+ * Se o nome já existir (objeto ou string), lança, ou troca a entrada na mesma posição com `substituir`.
+ * JSON inválido é recusado sem tocar no arquivo.
+ */
+export function gravarConexaoProjeto(root, conexao, { substituir = false } = {}) {
+    const motivo = motivoConexaoInvalida({ ...conexao });
+    if (motivo)
+        throw new Error(`Conexão ${JSON.stringify(conexao.nome)} inválida: ${motivo}.`);
+    const file = join(root, CONFIG_PATH);
+    const raw = existsSync(file) ? lerJsonParaEscrita(file, 'banco_dados.conexoes') : undefined;
+    const banco = raw ? 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 gravar a conexão ${conexao.nome}.`);
+    const posicao = conexoes.findIndex((entrada) => (isObject(entrada) ? entrada.nome : entrada) === conexao.nome);
+    if (posicao !== -1 && !substituir)
+        throw new Error(`A conexão ${conexao.nome} já está em banco_dados.conexoes de ${CONFIG_PATH}.`);
+    const entrada = {
+        nome: conexao.nome,
+        dsn_env: conexao.dsn_env,
+        ...(conexao.tipo === undefined ? {} : { tipo: conexao.tipo }),
+        ...(conexao.producao === true ? { producao: true } : {}),
+    };
+    const proximas = posicao === -1 ? [...conexoes, entrada] : conexoes.map((atual, i) => (i === posicao ? entrada : atual));
+    if (!raw)
+        writeDefaultConfig(root);
+    const base = raw ?? lerJsonParaEscrita(file, 'banco_dados.conexoes');
+    writeFileSync(file, `${JSON.stringify(comSecaoBanco(base, { ...banco, conexoes: proximas }), null, 2)}\n`);
+}
+/**
+ * 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.
+ */
+export function gravarRegistrarMcp(root, valor) {
+    const file = join(root, CONFIG_PATH);
+    let raw;
+    if (existsSync(file)) {
+        raw = lerJsonParaEscrita(file, 'banco_dados.registrar_mcp');
+    }
+    else {
+        const { banco_dados: _banco, ...padrao } = defaultConfig();
+        raw = padrao;
+    }
+    const banco = secaoBanco(raw);
+    if (banco.registrar_mcp === valor)
+        return;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(comSecaoBanco(raw, { ...banco, registrar_mcp: valor }), null, 2)}\n`);
+}
 const BLOCK_START = '# ai-harness (gerenciado pelo harness; não edite entre estas linhas)';
 const BLOCK_END = '# /ai-harness';
 /**