@fontdata/ai-harness 2.6.0 → 2.7.0

package/dist/banco/drivers/mariadb.js

@@ -0,0 +1,121 @@
+import { agruparChavesEstrangeiras, semPontoEVirgulaFinal, validarLimite, validarTimeout, } from './tipos.js';
+async function criarConexaoMysql2(config) {
+    const { default: mysql } = await import('mysql2');
+    return mysql.createConnection(config);
+}
+function origensDosCampos(campos) {
+    if (!campos.every((c) => typeof c.orgName === 'string'))
+        return undefined;
+    return campos.map((c) => (c.orgTable && c.orgName ? { tabela: c.orgTable, coluna: c.orgName } : null));
+}
+export function paraUriMysql(dsn) {
+    return dsn.replace(/^mariadb:\/\//i, 'mysql://');
+}
+export function criarDriverMariadb(dsn, opcoes = {}) {
+    const criarConexao = opcoes.criarConexao ?? criarConexaoMysql2;
+    let conexao = null;
+    async function obterConexao() {
+        if (!conexao) {
+            const nova = await criarConexao({ uri: paraUriMysql(dsn), multipleStatements: false });
+            nova.on?.('error', () => {
+                if (conexao === nova)
+                    conexao = null;
+            });
+            conexao = nova;
+        }
+        return conexao;
+    }
+    function destruir(alvo) {
+        if (conexao === alvo)
+            conexao = null;
+        alvo.destroy();
+    }
+    async function executar(sql, valores = []) {
+        const atual = await obterConexao();
+        return new Promise((resolve, reject) => {
+            atual.query(sql, valores, (erro, linhas) => {
+                if (!erro)
+                    return resolve(linhas);
+                if (erro.fatal && conexao === atual)
+                    conexao = null;
+                reject(erro);
+            });
+        });
+    }
+    return {
+        async testar() {
+            await executar('SELECT 1');
+        },
+        async listarTabelas() {
+            const linhas = await executar(`SELECT table_name AS nome, table_type AS tipo
+           FROM information_schema.tables
+          WHERE table_schema = DATABASE()
+          ORDER BY table_name`);
+            return linhas.map((t) => ({ nome: t.nome, tipo: /VIEW/i.test(t.tipo) ? 'view' : 'tabela' }));
+        },
+        async descreverTabela(nome) {
+            const colunas = await executar(`SELECT column_name AS nome, column_type AS tipo, is_nullable AS nulo, column_default AS padrao
+           FROM information_schema.columns
+          WHERE table_schema = DATABASE() AND table_name = ?
+          ORDER BY ordinal_position`, [nome]);
+            if (colunas.length === 0)
+                throw new Error(`Tabela ${nome} não encontrada`);
+            const primaria = await executar(`SELECT column_name AS coluna
+           FROM information_schema.key_column_usage
+          WHERE table_schema = DATABASE() AND table_name = ? AND constraint_name = 'PRIMARY'
+          ORDER BY ordinal_position`, [nome]);
+            const estrangeiras = await executar(`SELECT constraint_name AS restricao, column_name AS coluna,
+                referenced_table_name AS tabela_ref, referenced_column_name AS coluna_ref
+           FROM information_schema.key_column_usage
+          WHERE table_schema = DATABASE() AND table_name = ? AND referenced_table_name IS NOT NULL
+          ORDER BY constraint_name, ordinal_position`, [nome]);
+            return {
+                colunas: colunas.map((c) => ({ nome: c.nome, tipo: c.tipo, nulo: c.nulo === 'YES', padrao: c.padrao })),
+                chave_primaria: primaria.map((p) => p.coluna),
+                chaves_estrangeiras: agruparChavesEstrangeiras(estrangeiras),
+            };
+        },
+        async consultar(sql, { limite, timeoutSegundos }) {
+            const timeout = validarTimeout(timeoutSegundos);
+            const maximo = validarLimite(limite);
+            await executar(`SET SESSION max_statement_time = ${timeout}`);
+            await executar('START TRANSACTION READ ONLY');
+            const atual = await obterConexao();
+            const colunas = [];
+            let origens;
+            const linhas = [];
+            let truncado = false;
+            try {
+                const consulta = atual.query({ sql: semPontoEVirgulaFinal(sql), rowsAsArray: true });
+                consulta.on?.('error', () => { });
+                const fluxo = consulta.stream();
+                fluxo.once('fields', (campos) => {
+                    colunas.push(...campos.map((c) => c.name));
+                    origens = origensDosCampos(campos);
+                });
+                for await (const linha of fluxo) {
+                    if (linhas.length === maximo) {
+                        truncado = true;
+                        break;
+                    }
+                    linhas.push(linha);
+                }
+            }
+            finally {
+                if (truncado) {
+                    destruir(atual);
+                }
+                else {
+                    await executar('ROLLBACK').catch(() => destruir(atual));
+                }
+            }
+            return { colunas, linhas, truncado, ...(origens ? { origens } : {}) };
+        },
+        async fechar() {
+            const atual = conexao;
+            conexao = null;
+            if (atual)
+                await new Promise((resolve) => atual.end(() => resolve()));
+        },
+    };
+}

package/dist/banco/drivers/postgres.js

@@ -0,0 +1,157 @@
+import { agruparChavesEstrangeiras, semPontoEVirgulaFinal, validarLimite, validarTimeout, } from './tipos.js';
+const CURSOR = 'ai_harness_cursor';
+async function criarClientePg(dsn) {
+    const { default: pg } = await import('pg');
+    return new pg.Client({ connectionString: dsn });
+}
+function semComentariosIniciais(sql) {
+    let resto = sql;
+    for (;;) {
+        const sem = resto.replace(/^\s*(--[^\n]*(\n|$)|\/\*[\s\S]*?\*\/)/, '');
+        if (sem === resto)
+            return resto.trimStart();
+        resto = sem;
+    }
+}
+function separarNome(nome) {
+    const ponto = nome.indexOf('.');
+    return ponto < 0 ? { schema: null, tabela: nome } : { schema: nome.slice(0, ponto), tabela: nome.slice(ponto + 1) };
+}
+/** Uma consulta ao catálogo cobre todos os pares; falha nela deixa as origens ausentes sem derrubar o resultado. */
+async function resolverOrigens(conexao, campos) {
+    if (!campos.every((c) => typeof c.tableID === 'number' && typeof c.columnID === 'number'))
+        return undefined;
+    const chave = (tabela, coluna) => `${tabela}:${coluna}`;
+    const pares = new Map();
+    for (const c of campos) {
+        if (c.tableID)
+            pares.set(chave(c.tableID, c.columnID), [c.tableID, c.columnID]);
+    }
+    const nomes = new Map();
+    if (pares.size > 0) {
+        try {
+            const { rows } = await conexao.query({
+                text: `SELECT a.attrelid AS tabela_id, a.attnum AS coluna_id, c.relname AS tabela, a.attname AS coluna
+                 FROM pg_attribute a
+                 JOIN pg_class c ON c.oid = a.attrelid
+                WHERE (a.attrelid, a.attnum) IN (SELECT * FROM unnest($1::oid[], $2::int2[]))`,
+                values: [[...pares.values()].map((p) => p[0]), [...pares.values()].map((p) => p[1])],
+            });
+            for (const linha of rows) {
+                nomes.set(chave(Number(linha.tabela_id), Number(linha.coluna_id)), { tabela: linha.tabela, coluna: linha.coluna });
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return campos.map((c) => (c.tableID ? (nomes.get(chave(c.tableID, c.columnID)) ?? null) : null));
+}
+export function criarDriverPostgres(dsn, opcoes = {}) {
+    const criarCliente = opcoes.criarCliente ?? criarClientePg;
+    let cliente = null;
+    async function obterCliente() {
+        if (!cliente) {
+            const novo = await criarCliente(dsn);
+            await novo.connect();
+            cliente = novo;
+        }
+        return cliente;
+    }
+    async function descartarCliente() {
+        const atual = cliente;
+        cliente = null;
+        await atual?.end().catch(() => { });
+    }
+    async function linhas(text, values = []) {
+        const conexao = await obterCliente();
+        return (await conexao.query({ text, values })).rows;
+    }
+    return {
+        async testar() {
+            await linhas('SELECT 1');
+        },
+        async listarTabelas() {
+            const resultado = await linhas(`SELECT table_schema AS schema, table_name AS nome, table_type AS tipo
+           FROM information_schema.tables
+          WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+          ORDER BY table_schema, table_name`);
+            return resultado.map((t) => ({ schema: t.schema, nome: t.nome, tipo: t.tipo === 'VIEW' ? 'view' : 'tabela' }));
+        },
+        async descreverTabela(nome) {
+            const { schema, tabela } = separarNome(nome);
+            const filtro = (alias) => `${alias}table_name = $1 AND ${alias}table_schema = COALESCE($2, current_schema())`;
+            const valores = [tabela, schema];
+            const colunas = await linhas(`SELECT table_schema AS schema, column_name AS nome, data_type AS tipo, is_nullable AS nulo, column_default AS padrao
+           FROM information_schema.columns
+          WHERE ${filtro('')}
+          ORDER BY ordinal_position`, valores);
+            if (colunas.length === 0)
+                throw new Error(`Tabela ${nome} não encontrada`);
+            const primaria = await linhas(`SELECT kcu.column_name AS coluna
+           FROM information_schema.table_constraints tc
+           JOIN information_schema.key_column_usage kcu
+             ON kcu.constraint_schema = tc.constraint_schema AND kcu.constraint_name = tc.constraint_name
+          WHERE tc.constraint_type = 'PRIMARY KEY' AND ${filtro('tc.')}
+          ORDER BY kcu.ordinal_position`, valores);
+            const estrangeiras = await linhas(`SELECT kcu.constraint_name AS restricao, kcu.column_name AS coluna,
+                ref.table_schema AS schema_ref, ref.table_name AS tabela_ref, ref.column_name AS coluna_ref
+           FROM information_schema.key_column_usage kcu
+           JOIN information_schema.referential_constraints rc
+             ON rc.constraint_schema = kcu.constraint_schema AND rc.constraint_name = kcu.constraint_name
+           JOIN information_schema.key_column_usage ref
+             ON ref.constraint_schema = rc.unique_constraint_schema AND ref.constraint_name = rc.unique_constraint_name
+            AND ref.ordinal_position = kcu.position_in_unique_constraint
+          WHERE ${filtro('kcu.')}
+          ORDER BY kcu.constraint_name, kcu.ordinal_position`, valores);
+            const schemaTabela = colunas[0]?.schema;
+            return {
+                colunas: colunas.map((c) => ({ nome: c.nome, tipo: c.tipo, nulo: c.nulo === 'YES', padrao: c.padrao })),
+                chave_primaria: primaria.map((p) => p.coluna),
+                chaves_estrangeiras: agruparChavesEstrangeiras(estrangeiras.map((e) => ({
+                    ...e,
+                    tabela_ref: e.schema_ref === schemaTabela ? e.tabela_ref : `${e.schema_ref}.${e.tabela_ref}`,
+                }))),
+            };
+        },
+        async consultar(sql, { limite, timeoutSegundos }) {
+            const timeout = validarTimeout(timeoutSegundos);
+            const maximo = validarLimite(limite);
+            const texto = semPontoEVirgulaFinal(sql);
+            const direto = /^(explain|show)\b/i.test(semComentariosIniciais(texto));
+            const conexao = await obterCliente();
+            let resultado;
+            let origens;
+            await conexao.query('BEGIN READ ONLY');
+            try {
+                await conexao.query(`SET LOCAL statement_timeout = ${timeout * 1000}`);
+                if (direto) {
+                    resultado = await conexao.query({ text: texto, rowMode: 'array', queryMode: 'extended' });
+                }
+                else {
+                    await conexao.query({ text: `DECLARE ${CURSOR} NO SCROLL CURSOR FOR ${texto}`, queryMode: 'extended' });
+                    resultado = await conexao.query({ text: `FETCH ${maximo + 1} FROM ${CURSOR}`, rowMode: 'array', queryMode: 'extended' });
+                }
+                origens = await resolverOrigens(conexao, resultado.fields ?? []);
+            }
+            finally {
+                try {
+                    await conexao.query('ROLLBACK');
+                }
+                catch {
+                    await descartarCliente();
+                }
+            }
+            const todas = resultado.rows;
+            return {
+                colunas: (resultado.fields ?? []).map((f) => f.name),
+                linhas: todas.slice(0, maximo),
+                truncado: todas.length > maximo,
+                ...(origens ? { origens } : {}),
+            };
+        },
+        async fechar() {
+            await descartarCliente();
+        },
+    };
+}

package/dist/banco/drivers/sqlite.js

@@ -0,0 +1,92 @@
+import { validarLimite, } from './tipos.js';
+async function carregarSqlite() {
+    try {
+        return await import('node:sqlite');
+    }
+    catch {
+        throw new Error('SQLite exige Node 22.13 ou mais recente');
+    }
+}
+function lerLinhas(instrucao, maximo) {
+    const opcional = instrucao;
+    const descritas = typeof opcional.columns === 'function' ? opcional.columns.call(instrucao) : null;
+    const emArrays = descritas !== null && typeof opcional.setReturnArrays === 'function';
+    if (emArrays)
+        opcional.setReturnArrays?.(true);
+    let colunas = descritas?.map((c) => c.name) ?? null;
+    const origens = descritas?.map((c) => (c.table && c.column ? { tabela: c.table, coluna: c.column } : null));
+    const linhas = [];
+    let truncado = false;
+    const fonte = typeof opcional.iterate === 'function' ? opcional.iterate.call(instrucao) : instrucao.all();
+    for (const linha of fonte) {
+        if (linhas.length === maximo) {
+            truncado = true;
+            break;
+        }
+        if (emArrays) {
+            linhas.push(linha);
+        }
+        else {
+            const objeto = linha;
+            colunas ??= Object.keys(objeto);
+            linhas.push(colunas.map((c) => objeto[c]));
+        }
+    }
+    return { colunas: colunas ?? [], linhas, truncado, ...(origens ? { origens } : {}) };
+}
+export async function criarDriverSqlite(caminho) {
+    const { DatabaseSync: Banco } = await carregarSqlite();
+    let banco = null;
+    function abrir() {
+        banco ??= new Banco(caminho, { readOnly: true });
+        return banco;
+    }
+    function todas(sql, ...valores) {
+        return abrir().prepare(sql).all(...valores);
+    }
+    return {
+        async testar() {
+            todas('SELECT count(*) FROM sqlite_master');
+        },
+        async listarTabelas() {
+            const linhas = todas(`SELECT name AS nome, type AS tipo FROM sqlite_master
+          WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'
+          ORDER BY name`);
+            return linhas.map((t) => ({ nome: t.nome, tipo: t.tipo === 'view' ? 'view' : 'tabela' }));
+        },
+        async descreverTabela(nome) {
+            const colunas = todas('SELECT name AS nome, type AS tipo, "notnull" AS nao_nulo, dflt_value AS padrao, pk FROM pragma_table_info(?) ORDER BY cid', nome);
+            if (colunas.length === 0)
+                throw new Error(`Tabela ${nome} não encontrada`);
+            const estrangeiras = todas('SELECT id, "table" AS tabela_ref, "from" AS coluna, "to" AS coluna_ref FROM pragma_foreign_key_list(?) ORDER BY id, seq', nome);
+            const chaves = new Map();
+            for (const fk of estrangeiras) {
+                let chave = chaves.get(fk.id);
+                if (!chave) {
+                    chave = { colunas: [], tabela_ref: fk.tabela_ref, colunas_ref: [] };
+                    chaves.set(fk.id, chave);
+                }
+                chave.colunas.push(fk.coluna);
+                if (fk.coluna_ref !== null)
+                    chave.colunas_ref.push(fk.coluna_ref);
+            }
+            for (const chave of chaves.values()) {
+                if (chave.colunas_ref.length === 0) {
+                    chave.colunas_ref = todas('SELECT name AS nome FROM pragma_table_info(?) WHERE pk > 0 ORDER BY pk', chave.tabela_ref).map((c) => c.nome);
+                }
+            }
+            return {
+                colunas: colunas.map((c) => ({ nome: c.nome, tipo: c.tipo, nulo: c.nao_nulo === 0, padrao: c.padrao })),
+                chave_primaria: colunas.filter((c) => c.pk > 0).sort((a, b) => a.pk - b.pk).map((c) => c.nome),
+                chaves_estrangeiras: [...chaves.values()],
+            };
+        },
+        async consultar(sql, { limite }) {
+            return lerLinhas(abrir().prepare(sql), validarLimite(limite));
+        },
+        async fechar() {
+            banco?.close();
+            banco = null;
+        },
+    };
+}

package/dist/banco/drivers/tipos.js

@@ -0,0 +1,29 @@
+/** Os valores entram no SQL como literais, então só inteiros dentro da faixa passam. */
+export function validarTimeout(timeoutSegundos) {
+    if (typeof timeoutSegundos !== 'number' || !Number.isInteger(timeoutSegundos) || timeoutSegundos < 1 || timeoutSegundos > 600) {
+        throw new Error(`timeoutSegundos deve ser um inteiro de 1 a 600 (recebido: ${String(timeoutSegundos)})`);
+    }
+    return timeoutSegundos;
+}
+export function validarLimite(limite) {
+    if (typeof limite !== 'number' || !Number.isInteger(limite) || limite < 1) {
+        throw new Error(`limite deve ser um inteiro positivo (recebido: ${String(limite)})`);
+    }
+    return limite;
+}
+export function semPontoEVirgulaFinal(sql) {
+    return sql.trim().replace(/;\s*$/, '').trimEnd();
+}
+export function agruparChavesEstrangeiras(linhas) {
+    const grupos = new Map();
+    for (const linha of linhas) {
+        let grupo = grupos.get(linha.restricao);
+        if (!grupo) {
+            grupo = { colunas: [], tabela_ref: linha.tabela_ref, colunas_ref: [] };
+            grupos.set(linha.restricao, grupo);
+        }
+        grupo.colunas.push(linha.coluna);
+        grupo.colunas_ref.push(linha.coluna_ref);
+    }
+    return [...grupos.values()];
+}

package/dist/banco/ferramentas.js

@@ -0,0 +1,241 @@
+import { readConfig } from '../config/config.js';
+import { ocultarSenha } from './cadastro.js';
+import { escolherConexao, resolverConexoes } from './conexao.js';
+import { criarDriver } from './drivers/index.js';
+import { categoriaDaColuna, mascararResultado, mascararTexto } from './lgpd/aplicar.js';
+import { validarLeitura } from './somente-leitura.js';
+const CONEXAO = {
+    type: 'string',
+    description: 'Nome da conexão do projeto; sem ele vale a primeira de banco.conexoes.',
+};
+export const FERRAMENTAS = [
+    {
+        name: 'listar_conexoes',
+        description: 'Lista as conexões de banco do projeto (nome, tipo, se é produção, origem e, nas do projeto, a variável e a fonte), sem credenciais.',
+        inputSchema: { type: 'object', properties: { conexao: CONEXAO }, additionalProperties: false },
+    },
+    {
+        name: 'listar_tabelas',
+        description: 'Lista as tabelas e views do banco, com o schema no Postgres.',
+        inputSchema: { type: 'object', properties: { conexao: CONEXAO }, additionalProperties: false },
+    },
+    {
+        name: 'descrever_tabela',
+        description: 'Descreve uma tabela: colunas (nome, tipo, nulo, padrão), chave primária e chaves estrangeiras.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tabela: { type: 'string', description: 'Nome da tabela, com o schema quando preciso (schema.tabela).' },
+                conexao: CONEXAO,
+            },
+            required: ['tabela'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'consultar',
+        description: 'Executa uma única consulta somente leitura (SELECT, WITH, EXPLAIN, SHOW, DESCRIBE) e devolve colunas, linhas e se o resultado foi truncado.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sql: { type: 'string', description: 'Consulta de leitura; selecione só as colunas necessárias.' },
+                limite: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Máximo de linhas devolvidas; nunca passa de banco.limite_linhas do projeto.',
+                },
+                conexao: CONEXAO,
+            },
+            required: ['sql'],
+            additionalProperties: false,
+        },
+    },
+];
+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.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 adicionar <nome>` e, no projeto, `npx @fontdata/ai-harness banco usar <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 usar <nome> no projeto';
+function orientarAdicionar(nome) {
+    return `Conexão ${nome} não encontrada nesta máquina; rode npx @fontdata/ai-harness banco adicionar ${nome}`;
+}
+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`;
+}
+function paraJson(dados) {
+    return JSON.stringify(dados, function (chave, valor) {
+        const original = this[chave];
+        if (typeof original === 'bigint')
+            return original.toString();
+        if (original instanceof Uint8Array)
+            return Buffer.from(original).toString('hex');
+        if (original instanceof Date)
+            return Number.isNaN(original.getTime()) ? String(original) : original.toISOString();
+        return valor;
+    }, 2);
+}
+function plural(n, singular, plural) {
+    return `${n} ${n === 1 ? singular : plural}`;
+}
+function rodapeLgpd({ colunasMascaradas, valoresEmTexto }) {
+    const partes = [];
+    if (colunasMascaradas.length > 0) {
+        const lista = colunasMascaradas.map((c) => `${c.coluna} → ${c.categoria}`).join(', ');
+        partes.push(`${plural(colunasMascaradas.length, 'coluna', 'colunas')} (${lista})`);
+    }
+    if (valoresEmTexto > 0) {
+        partes.push(plural(valoresEmTexto, 'valor detectado pelo conteúdo', 'valores detectados pelo conteúdo'));
+    }
+    return partes.length === 0 ? '' : `\n\nMascaramento LGPD: ${partes.join(' e ')}.`;
+}
+const TAMANHO_MINIMO_SEGREDO = 8;
+/** Oculta a senha das conexões e dos segredos; o segredo inteiro só a partir de 8 caracteres, para não estragar textos com valores curtos. */
+function limpar(texto, conexoes, segredos = []) {
+    let resultado = [...segredos]
+        .filter((segredo) => segredo.length >= TAMANHO_MINIMO_SEGREDO)
+        .sort((a, b) => b.length - a.length)
+        .reduce((parcial, segredo) => parcial.replaceAll(segredo, '***'), texto);
+    for (const segredo of segredos)
+        resultado = ocultarSenha(resultado, { tipo: 'postgres', dsn: segredo });
+    return conexoes.reduce((parcial, conexao) => ocultarSenha(parcial, conexao), resultado);
+}
+function erro(texto) {
+    return { content: [{ type: 'text', text: texto }], isError: true };
+}
+function argumentoTexto(args, nome, obrigatorio) {
+    const valor = args[nome];
+    if (valor === undefined && !obrigatorio)
+        return undefined;
+    if (typeof valor !== 'string' || !valor.trim())
+        throw new Error(`O argumento ${nome} deve ser um texto não vazio.`);
+    return valor;
+}
+function lerLimite(valor, banco) {
+    if (valor === undefined)
+        return banco.limite_linhas;
+    if (typeof valor !== 'number' || !Number.isInteger(valor) || valor < 1) {
+        throw new Error('O argumento limite deve ser um inteiro positivo.');
+    }
+    return Math.min(valor, banco.limite_linhas);
+}
+/** Sem nome, vale a primeira declarada em banco.conexoes; se ela não estiver disponível, o erro é dela, nunca outra conexão. */
+function escolher(resolvidas, banco, nome) {
+    const alvo = nome ?? banco.conexoes[0];
+    if (alvo !== undefined) {
+        if (resolvidas.faltando.includes(alvo))
+            throw new Error(orientarAdicionar(alvo));
+        const ausente = resolvidas.variaveisAusentes.find((item) => item.nome === alvo);
+        if (ausente)
+            throw new Error(orientarVariavel(ausente.nome, ausente.variavel));
+        const descartada = resolvidas.descartadas.find((item) => item.nome === alvo);
+        if (descartada)
+            throw new Error(`Conexão ${descartada.nome} descartada: ${descartada.motivo}.`);
+    }
+    return escolherConexao(resolvidas.conexoes, alvo);
+}
+function descreverConexao({ nome, tipo, producao, origem, variavel, fonte }) {
+    const dados = { nome, tipo, producao, origem };
+    if (origem === 'projeto')
+        Object.assign(dados, { dsn_env: variavel, fonte });
+    return dados;
+}
+async function comDriver(conexao, contexto, acao) {
+    const fabrica = contexto.criarDriver ?? criarDriver;
+    const driver = await fabrica(conexao.tipo, conexao.dsn ?? conexao.caminho ?? '');
+    try {
+        return await acao(driver);
+    }
+    finally {
+        await driver.fechar().catch(() => { });
+    }
+}
+async function executar(nome, args, contexto, banco, resolvidas) {
+    if (nome === 'listar_conexoes') {
+        const { conexoes, faltando, variaveisAusentes, descartadas } = resolvidas;
+        const dados = { conexoes: conexoes.map(descreverConexao) };
+        if (faltando.length > 0) {
+            dados.faltando = faltando.map((n) => ({ nome: n, orientacao: orientarAdicionar(n) }));
+        }
+        if (variaveisAusentes.length > 0) {
+            dados.variaveisAusentes = variaveisAusentes.map(({ nome: n, variavel }) => ({
+                nome: n,
+                dsn_env: variavel,
+                orientacao: orientarVariavel(n, variavel),
+            }));
+        }
+        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 adicionar <nome> e ${ORIENTACAO_USAR}`;
+        }
+        if (resolvidas.problemas.length > 0)
+            dados.problemas = resolvidas.problemas;
+        return { content: [{ type: 'text', text: paraJson(dados) }] };
+    }
+    if (!['listar_tabelas', 'descrever_tabela', 'consultar'].includes(nome))
+        return erro(`Ferramenta desconhecida: ${nome}`);
+    const conexao = escolher(resolvidas, banco, argumentoTexto(args, 'conexao', false));
+    if (conexao.producao && banco.producao === 'bloqueio') {
+        return erro(`Conexão ${conexao.nome} é de produção e está bloqueada (banco.producao: "bloqueio"). Use uma cópia ou troque banco.producao para "aviso" em .ai-harness/config.json de propósito.`);
+    }
+    let dados;
+    let rodape = '';
+    if (nome === 'listar_tabelas') {
+        dados = { conexao: conexao.nome, tabelas: await comDriver(conexao, contexto, (driver) => driver.listarTabelas()) };
+    }
+    else if (nome === 'descrever_tabela') {
+        const tabela = argumentoTexto(args, 'tabela', true) ?? '';
+        const descricao = await comDriver(conexao, contexto, (driver) => driver.descreverTabela(tabela));
+        const colunas = descricao.colunas.map((coluna) => {
+            const categoria = conexao.mascaramento ? categoriaDaColuna(tabela, coluna.nome, banco.lgpd) : null;
+            return categoria === null ? coluna : { ...coluna, mascarada: categoria };
+        });
+        dados = { conexao: conexao.nome, tabela, ...descricao, colunas };
+    }
+    else {
+        const sql = argumentoTexto(args, 'sql', true) ?? '';
+        const limite = lerLimite(args.limite, banco);
+        const validacao = validarLeitura(sql, conexao.tipo);
+        if (!validacao.ok)
+            return erro(`Consulta recusada: ${validacao.motivo}`);
+        const bruto = await comDriver(conexao, contexto, (driver) => driver.consultar(validacao.sql, { limite, timeoutSegundos: banco.timeout_segundos }));
+        const mascarado = mascararResultado(bruto, {
+            sql: validacao.sql,
+            dialeto: conexao.tipo,
+            regras: banco.lgpd,
+            ativo: conexao.mascaramento,
+        });
+        const { resultado } = mascarado;
+        rodape = rodapeLgpd(mascarado);
+        dados = { conexao: conexao.nome, colunas: resultado.colunas, linhas: resultado.linhas, truncado: resultado.truncado };
+    }
+    const aviso = conexao.producao ? `⚠ PRODUÇÃO — conexão ${conexao.nome} é de produção; confira antes de agir.\n` : '';
+    return { content: [{ type: 'text', text: `${aviso}${paraJson(dados)}${rodape}` }] };
+}
+/** Nunca lança: falhas viram `isError`, e todo texto sai sem a senha dos DSNs e sem os valores lidos de variáveis; erros passam pela detecção LGPD por valor. */
+export async function executarFerramenta(nome, args, contexto) {
+    let conexoes = [];
+    let segredos = [];
+    try {
+        const { config } = readConfig(contexto.raiz);
+        const resolvidas = resolverConexoes(contexto.raiz, contexto.cadastro ? { cadastro: contexto.cadastro } : {});
+        conexoes = resolvidas.conexoes;
+        segredos = resolvidas.segredos;
+        const argumentos = typeof args === 'object' && args !== null && !Array.isArray(args) ? args : {};
+        const resultado = await executar(nome, argumentos, contexto, config.banco, resolvidas);
+        const texto = limpar(resultado.content[0].text, conexoes, segredos);
+        resultado.content[0].text = resultado.isError ? mascararTexto(texto) : texto;
+        return resultado;
+    }
+    catch (falha) {
+        const mensagem = falha instanceof Error ? falha.message : String(falha);
+        return erro(mascararTexto(limpar(mensagem, conexoes, segredos)));
+    }
+}