terminal-smart-cli 0.94.2 → 0.97.1

package/lib/keyring.js

@@ -0,0 +1,235 @@
+// lib/keyring.js — de ONDE vem a credencial de IA de cada run.
+//
+// Antes: todo caminho do CLI chamava `/api/ai/key` direto (9 pontos). Agora todos passam
+// por `resolve()`, que decide entre a chave PRÓPRIA do usuário (BYOK) e o gateway do TS.
+// O formato de retorno é o MESMO da rota ({key, baseUrl}) — por isso o encaixe é transparente
+// e, SEM provedor configurado, o caminho é idêntico ao anterior (garantido por teste).
+//
+// SEGREDO: as chaves vivem em ~/.ts/providers.json com chmod 600, NUNCA em config.json —
+// aquele é lido e regravado por merge em quase todo comando, e acabaria em log/backup.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const providers = require('./providers');
+
+const DIR = path.join(os.homedir(), '.ts');
+const FILE = path.join(DIR, 'providers.json');
+
+function _load() {
+  try { const j = JSON.parse(fs.readFileSync(FILE, 'utf8')); return (j && typeof j === 'object') ? j : {}; }
+  catch (_) { return {}; }
+}
+function _save(obj) {
+  fs.mkdirSync(DIR, { recursive: true });
+  fs.writeFileSync(FILE, JSON.stringify(obj, null, 2));
+  try { fs.chmodSync(FILE, 0o600); } catch (_) { /* Windows: sem chmod */ }
+  return obj;
+}
+
+// ── estado ──────────────────────────────────────────────────────────────────
+function listar() {
+  const st = _load();
+  const provs = st.provedores || {};
+  return Object.keys(provs).map(id => ({
+    id,
+    ativo: st.ativo === id,
+    modelo: provs[id].modelo || '',
+    baseUrl: provs[id].baseUrl || '',
+    toolsOk: provs[id].toolsOk === true,
+    testadoEm: provs[id].testadoEm || '',
+    chaveMascarada: mascarar(provs[id].key || ''),
+  }));
+}
+
+function ativo() {
+  const st = _load();
+  if (!st.ativo) return null;
+  const p = (st.provedores || {})[st.ativo];
+  if (!p) return null;
+  return Object.assign({ id: st.ativo }, p);
+}
+
+function salvar(id, { key = '', baseUrl = '', modelo = '', toolsOk = null, testadoEm = '' } = {}) {
+  const st = _load();
+  st.provedores = st.provedores || {};
+  const anterior = st.provedores[id] || {};
+  st.provedores[id] = {
+    key: key || anterior.key || '',
+    baseUrl: providers.baseUrlDe(id, baseUrl || anterior.baseUrl),
+    modelo: modelo || anterior.modelo || (providers.info(id) || {}).modeloPadrao || '',
+    toolsOk: toolsOk === null ? (anterior.toolsOk === true) : !!toolsOk,
+    testadoEm: testadoEm || anterior.testadoEm || '',
+  };
+  _save(st);
+  return st.provedores[id];
+}
+
+function usar(id) {
+  const st = _load();
+  if (id && !((st.provedores || {})[id])) throw new Error('provedor não configurado: ' + id);
+  if (id) st.ativo = id; else delete st.ativo;   // sem id = volta pro TS Cloud
+  _save(st);
+  return id || null;
+}
+
+function remover(id) {
+  const st = _load();
+  if (!st.provedores || !st.provedores[id]) return false;
+  delete st.provedores[id];
+  if (st.ativo === id) delete st.ativo;
+  _save(st);
+  return true;
+}
+
+// Mostra só o suficiente pra o usuário reconhecer a chave, nunca a chave.
+function mascarar(k) {
+  const s = String(k || '');
+  if (!s) return '(sem chave)';
+  if (s.length <= 10) return s.slice(0, 2) + '…';
+  return s.slice(0, 6) + '…' + s.slice(-4);
+}
+
+// ── resolução (o ponto que o resto do CLI usa) ──────────────────────────────
+// Mesma forma de retorno da rota /api/ai/key + campos extras que só o BYOK usa.
+// `api` é INJETADO pra manter este módulo testável sem rede.
+async function resolve(token, opts = {}) {
+  const { feature = 'cli_agent', api = null, timeoutMs = 20000 } = opts;
+  const a = ativo();
+  if (a && (a.key || (providers.info(a.id) || {}).semChave)) {
+    return {
+      key: a.key || 'ollama',           // servidor local ignora o header, mas o fetch exige algo
+      baseUrl: a.baseUrl,
+      modelo: a.modelo || null,
+      source: 'byok',
+      provedor: a.id,
+      toolsOk: a.toolsOk === true,
+    };
+  }
+  const _api = api || require('./api').api;
+  const k = await _api('/api/ai/key?feature=' + encodeURIComponent(feature), { token, timeoutMs });
+  return Object.assign({}, k, { source: 'cloud', provedor: 'ts-cloud' });
+}
+
+// Qual modelo mandar para ESTA credencial.
+// Vários pontos do CLI pedem um modelo específico do GATEWAY (ex: 'gemini-2.5-flash-lite'
+// pro classificador barato). Esse id não existe no provedor do usuário e volta 404 — foi
+// exatamente o que quebrou o primeiro teste real com a NVIDIA. Com BYOK, o modelo é o do
+// provedor; sem BYOK, respeita o que o chamador pediu.
+function modeloPara(k, preferidoDoGateway) {
+  if (k && k.source === 'byok') return k.modelo || null;
+  return preferidoDoGateway || null;
+}
+
+// ── teste REAL da credencial ────────────────────────────────────────────────
+// Duas perguntas, nesta ordem, porque falham por motivos diferentes:
+//   1) a chave responde?          → erro de auth/rede/modelo inexistente
+//   2) o modelo CHAMA FERRAMENTA? → é o que decide se serve pro agente
+// Modelo grátis que não faz tool-call vira um chat que NARRA sucesso sem executar nada —
+// exatamente o `false_done` que o model_router já monitora. Melhor descobrir no cadastro.
+const TOOL_TESTE = {
+  type: 'function',
+  function: {
+    name: 'somar',
+    description: 'Soma dois números inteiros e devolve o resultado.',
+    parameters: {
+      type: 'object',
+      properties: { a: { type: 'number' }, b: { type: 'number' } },
+      required: ['a', 'b'],
+    },
+  },
+};
+
+// timeout generoso de propósito: provedores serverless (NVIDIA NIM à frente) sobem o
+// modelo sob demanda, e um modelo grande FRIO passa de 2 min na primeira chamada.
+// Medido: llama-3.3-70b > 120s frio; llama-3.1-8b 1s quente. Cortar cedo aqui faria o
+// cadastro reprovar chave BOA — o erro mais caro que este comando pode cometer.
+async function testar(id, { key = '', baseUrl = '', modelo = '', timeoutMs = 150000, fetchImpl = null } = {}) {
+  const p = providers.info(id);
+  if (!p) return { ok: false, erro: 'provedor desconhecido: ' + id };
+  const url = providers.baseUrlDe(id, baseUrl);
+  if (!url) return { ok: false, erro: 'baseUrl não definida' };
+  const mdl = modelo || p.modeloPadrao;
+  if (!mdl) return { ok: false, erro: 'modelo não definido' };
+  const _fetch = fetchImpl || fetch;
+
+  const chamar = async (body) => {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await _fetch(url.replace(/\/+$/, '') + '/chat/completions', {
+        method: 'POST',
+        signal: ctrl.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': 'Bearer ' + (key || 'local'),
+          'User-Agent': 'terminal-smart-cli',
+        },
+        body: JSON.stringify(body),
+      });
+      let j = null;
+      try { j = await res.json(); } catch (_) {}
+      return { status: res.status, json: j };
+    } finally { clearTimeout(t); }
+  };
+
+  // 1) a chave responde?
+  let r1;
+  try {
+    r1 = await chamar({ model: mdl, max_tokens: 16, messages: [{ role: 'user', content: 'Responda apenas: ok' }] });
+  } catch (e) {
+    // Timeout aqui quase nunca é chave ruim: é modelo grande subindo do zero. Dizer
+    // "não conectou" mandaria o usuário caçar firewall em vez de trocar de modelo.
+    const msg = (e && e.message) ? e.message : String(e);
+    if (/abort/i.test(msg)) {
+      const alt = (p.sugestoes || []).filter(s => s[0] !== mdl).slice(0, 2).map(s => s[0]).join(' · ');
+      return { ok: false, timeout: true, erro: 'o modelo "' + mdl + '" não respondeu em ' + Math.round(timeoutMs / 1000) + 's. ' +
+        'Modelo grande costuma ter "cold start" (sobe sob demanda) — tente de novo, ou escolha um menor' +
+        (alt ? ': ' + alt : '') + '.' };
+    }
+    return { ok: false, erro: 'não conectou: ' + msg };
+  }
+  if (r1.status === 401 || r1.status === 403) return { ok: false, erro: 'chave recusada pelo provedor (HTTP ' + r1.status + ')' };
+  if (r1.status === 404) return { ok: false, erro: 'modelo "' + mdl + '" não existe nesse provedor (HTTP 404)' };
+  if (r1.status >= 400) {
+    const msg = (r1.json && (r1.json.error?.message || r1.json.message)) || ('HTTP ' + r1.status);
+    return { ok: false, erro: String(msg).slice(0, 200) };
+  }
+
+  // 2) o modelo chama ferramenta?
+  let toolsOk = false, obsTools = '';
+  try {
+    const r2 = await chamar({
+      model: mdl,
+      max_tokens: 128,
+      tools: [TOOL_TESTE],
+      messages: [{ role: 'user', content: 'Quanto é 2 + 3? Use a ferramenta somar para calcular.' }],
+    });
+    if (r2.status >= 400) {
+      obsTools = 'o provedor recusou a requisição com ferramentas (HTTP ' + r2.status + ')';
+    } else {
+      const m = r2.json && r2.json.choices && r2.json.choices[0] && r2.json.choices[0].message;
+      const tc = m && (m.tool_calls || (m.function_call ? [m.function_call] : null));
+      toolsOk = Array.isArray(tc) && tc.length > 0;
+      if (!toolsOk) obsTools = 'respondeu em TEXTO em vez de chamar a ferramenta';
+    }
+  } catch (e) {
+    obsTools = 'falhou ao testar ferramentas: ' + (e && e.message ? e.message : String(e));
+  }
+
+  return { ok: true, modelo: mdl, baseUrl: url, toolsOk, obsTools };
+}
+
+// Recursos que EXIGEM o gateway do TS e por isso não funcionam com chave própria.
+// Mostrado no `ts conectar` — degradação anunciada, nunca silenciosa.
+const SO_NA_NUVEM = [
+  ['visão / gate visual', 'o olho que aprova tela de jogo usa modelo de visão do gateway'],
+  ['RAG e embeddings', 'a base recuperável indexa pelo gateway'],
+  ['aprovação remota', 'o pedido de OK no Telegram passa pelo backend do TS'],
+  ['ts run (nuvem)', 'orquestração remota roda no servidor, não na sua máquina'],
+];
+
+module.exports = {
+  FILE, listar, ativo, salvar, usar, remover, mascarar,
+  resolve, testar, modeloPara, SO_NA_NUVEM, _load, _save,
+};

package/lib/meta.js

@@ -11,6 +11,7 @@ const path = require('path');
 const cp = require('child_process');
 const compactor = require('./compactor');
 const { api, ApiError } = require('./api');
+const keyring = require('./keyring');
 // Teto de IA estourado (free/plano) no gateway → 402 (ou 429 com type cost_cap). Os helpers de
 // IA da missão DEVEM lançar (não retornar vazio em silêncio), senão a missão desperdiça rodadas
 // fingindo trabalhar. O run() pausa (estado salvo = resumível) e mostra CTA de upgrade.
@@ -589,7 +590,11 @@ function runApp(b, projRoot, onAlert) {
 // default grok-4.5) critica o layout (nav torta, gráfico cortado, sobreposição).
 // A crítica volta pro executor melhorar o visual. É o gate de APARÊNCIA.
 async function _llmVision({ token, model, text, imageB64, images, maxTokens = 700 }) {
-  if (!_key) _key = await api('/api/ai/key?feature=cli_agent', { token, timeoutMs: 20000 });
+  // VISÃO fica SEMPRE no gateway do TS, mesmo com BYOK: os provedores gratuitos ou não
+  // têm modelo de visão, ou usam outro formato de imagem. Cache PRÓPRIO (_keyNuvem) —
+  // compartilhar `_key` com as chamadas de texto misturaria as duas credenciais.
+  if (!_keyNuvem) _keyNuvem = await api('/api/ai/key?feature=cli_agent', { token, timeoutMs: 20000 });
+  const _key = _keyNuvem;
   // aceita 1 imagem (imageB64) ou VÁRIAS (images[]) na MESMA chamada de visão — 1 crítica cobre N telas
   const imgs = (images && images.length ? images : [imageB64]).filter(Boolean);
   const content = [{ type: 'text', text }].concat(imgs.map(b64 => ({ type: 'image_url', image_url: { url: 'data:image/png;base64,' + b64 } })));
@@ -789,8 +794,9 @@ function save(st, dir) {
 
 // Chamada JSON barata (flash-lite via CDC, chave sk-hub do usuário) + cobrança
 let _key = null;
+let _keyNuvem = null;   // credencial do GATEWAY (visão) — separada da BYOK
 async function _llmJson({ token, system, user, maxTokens = 900 }) {
-  if (!_key) _key = await api('/api/ai/key?feature=cli_agent', { token, timeoutMs: 20000 });
+  if (!_key) _key = await keyring.resolve(token, { feature: 'cli_agent' });
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), 60000);
   let res;
@@ -798,7 +804,7 @@ async function _llmJson({ token, system, user, maxTokens = 900 }) {
     res = await fetch(String(_key.baseUrl).replace(/\/+$/, '') + '/chat/completions', {
       method: 'POST', signal: ctrl.signal,
       headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + _key.key },
-      body: JSON.stringify({ model: 'gemini-2.5-flash-lite', stream: false, max_completion_tokens: maxTokens,
+      body: JSON.stringify({ model: keyring.modeloPara(_key, 'gemini-2.5-flash-lite'), stream: false, max_completion_tokens: maxTokens,
         messages: [{ role: 'system', content: system }, { role: 'user', content: user }] }),
     });
   } finally { clearTimeout(timer); }
@@ -814,7 +820,7 @@ async function _llmJson({ token, system, user, maxTokens = 900 }) {
 
 // Chamada de TEXTO com modelo arbitrário — usada pelo PENSADOR (escalonamento).
 async function _llmText({ token, model, system, user, maxTokens = 1200 }) {
-  if (!_key) _key = await api('/api/ai/key?feature=cli_agent', { token, timeoutMs: 20000 });
+  if (!_key) _key = await keyring.resolve(token, { feature: 'cli_agent' });
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), 120000);
   let res;
@@ -822,7 +828,7 @@ async function _llmText({ token, model, system, user, maxTokens = 1200 }) {
     res = await fetch(String(_key.baseUrl).replace(/\/+$/, '') + '/chat/completions', {
       method: 'POST', signal: ctrl.signal,
       headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + _key.key },
-      body: JSON.stringify({ model, stream: false, max_completion_tokens: maxTokens, messages: [{ role: 'system', content: system }, { role: 'user', content: user }] }),
+      body: JSON.stringify({ model: keyring.modeloPara(_key, model), stream: false, max_completion_tokens: maxTokens, messages: [{ role: 'system', content: system }, { role: 'user', content: user }] }),
     });
   } finally { clearTimeout(timer); }
   const j = await res.json().catch(() => null);

package/lib/office-readers.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const JSZip = require('jszip');
+
+function _entities(text) {
+  return String(text || '')
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"').replace(/&apos;/g, "'");
+}
+
+function _xmlText(xml, tag) {
+  const re = new RegExp(`<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)<\\/${tag}>`, 'g');
+  const parts = [];
+  let match;
+  while ((match = re.exec(String(xml || '')))) parts.push(_entities(match[1]).replace(/<[^>]+>/g, ''));
+  return parts.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+async function _load(file, extension, maxMb = 80) {
+  const p = path.resolve(String(file || ''));
+  if (!p.toLowerCase().endsWith(extension)) throw new Error(`O arquivo precisa terminar em ${extension}.`);
+  if (!fs.existsSync(p) || !fs.statSync(p).isFile()) throw new Error('Arquivo não encontrado: ' + p);
+  const size = fs.statSync(p).size;
+  if (size > maxMb * 1048576) throw new Error(`Arquivo muito grande (${Math.round(size / 1048576)} MB, máximo ${maxMb} MB).`);
+  return { p, size, zip: await JSZip.loadAsync(fs.readFileSync(p)) };
+}
+
+function _window(text, input) {
+  const total = text.length;
+  if (input.buscar) {
+    const q = String(input.buscar).trim().toLocaleLowerCase();
+    const lower = text.toLocaleLowerCase();
+    const hits = [];
+    let at = 0;
+    while (q && hits.length < 20 && (at = lower.indexOf(q, at)) >= 0) {
+      hits.push({
+        posicao_char: at,
+        trecho: text.slice(Math.max(0, at - 180), Math.min(total, at + q.length + 420)).trim(),
+      });
+      at += Math.max(1, q.length);
+    }
+    return { busca: input.buscar, encontrados: hits.length, trechos: hits };
+  }
+  const start = Math.max(0, Number(input.inicio_char) || 0);
+  const length = Math.min(30000, Math.max(500, Number(input.tamanho) || 12000));
+  return {
+    janela: `${start}–${Math.min(total, start + length)}`,
+    texto: text.slice(start, start + length),
+    proximo_inicio: start + length < total ? start + length : null,
+  };
+}
+
+async function lerDocumento(input = {}) {
+  try {
+    const { p, size, zip } = await _load(input.caminho, '.docx');
+    const doc = zip.file('word/document.xml');
+    if (!doc) return { ok: false, erro: 'DOCX inválido: word/document.xml ausente.' };
+    const xml = await doc.async('string');
+    const paragraphs = (xml.match(/<w:p(?:\s|>)/g) || []).length;
+    const tables = (xml.match(/<w:tbl(?:\s|>)/g) || []).length;
+    const text = _xmlText(xml, 'w:t');
+    return {
+      ok: true,
+      arquivo: p,
+      tamanho_bytes: size,
+      paragrafos: paragraphs,
+      tabelas: tables,
+      imagens: Object.keys(zip.files).filter(f => /^word\/media\//.test(f)).length,
+      total_chars: text.length,
+      ..._window(text, input),
+    };
+  } catch (error) {
+    return { ok: false, erro: 'Falha ao ler DOCX: ' + error.message };
+  }
+}
+
+async function lerApresentacao(input = {}) {
+  try {
+    const { p, size, zip } = await _load(input.caminho, '.pptx');
+    const names = Object.keys(zip.files)
+      .filter(f => /^ppt\/slides\/slide\d+\.xml$/.test(f))
+      .sort((a, b) => Number(a.match(/\d+/)?.[0]) - Number(b.match(/\d+/)?.[0]));
+    const start = Math.max(1, Number(input.inicio_slide) || 1);
+    const limit = Math.min(50, Math.max(1, Number(input.slides) || 20));
+    const slides = [];
+    for (let i = start - 1; i < Math.min(names.length, start - 1 + limit); i++) {
+      const xml = await zip.file(names[i]).async('string');
+      slides.push({ numero: i + 1, texto: _xmlText(xml, 'a:t').slice(0, 12000) });
+    }
+    return {
+      ok: true,
+      arquivo: p,
+      tamanho_bytes: size,
+      total_slides: names.length,
+      imagens: Object.keys(zip.files).filter(f => /^ppt\/media\//.test(f)).length,
+      slides,
+      proximo_slide: start - 1 + limit < names.length ? start + limit : null,
+    };
+  } catch (error) {
+    return { ok: false, erro: 'Falha ao ler PPTX: ' + error.message };
+  }
+}
+
+module.exports = { lerDocumento, lerApresentacao };

package/lib/policy.js

@@ -0,0 +1,162 @@
+// lib/policy.js — POLÍTICA DECLARATIVA de permissões do agente.
+//
+// Os gates do TS são fortes, mas fixos: `isDestructive` decide igual em todo projeto. Isso
+// não cobre "neste repo `git push` pergunta; em staging pode; em produção nunca" — e o
+// `--yolo` é tudo-ou-nada. A política resolve isso em arquivo, versionável junto do projeto.
+//
+// ⚠️ A REGRA DE SEGURANÇA CENTRAL DESTE MÓDULO:
+// a política do PROJETO só pode RESTRINGIR, nunca AMPLIAR. O conteúdo do repositório é
+// dado NÃO-CONFIÁVEL — é o mesmo motivo pelo qual AGENTS.md é lido como "dado, não comando".
+// Se um `.ts-politica.json` pudesse liberar, um repo hostil escreveria `shell: allow` e
+// desarmaria o produto inteiro só por ter sido clonado. Por isso `combinar()` sempre fica
+// com o veredito MAIS restritivo entre global e projeto.
+//
+// E o que a política NUNCA alcança (garantido no agent.js, não aqui): a recusa instantânea
+// de auto-destrutivos (`selfDestructiveReason`) e a proteção de `~/.ts` (`touchesTsConfig`).
+// Um `allow` não ressuscita nenhum dos dois.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ARQ_PROJETO = '.ts-politica.json';
+const ARQ_GLOBAL = path.join(os.homedir(), '.ts', 'policy.json');
+
+const VEREDITOS = ['allow', 'ask', 'deny'];
+const NIVEL = { allow: 0, ask: 1, deny: 2 };
+
+// Cada ferramenta do agente cai numa categoria. O que não está mapeado é tratado como
+// 'outro' — e 'outro' sem regra explícita NÃO é decidido pela política (cai no gate normal).
+const CATEGORIA = {
+  ler_arquivo: 'ler', listar_diretorio: 'ler', buscar_arquivos: 'ler', buscar_codigo: 'ler',
+  mapa_projeto: 'ler', info_sistema: 'ler', explorar: 'ler', ler_documento: 'ler', ler_apresentacao: 'ler',
+  escrever_arquivo: 'editar', editar_arquivo: 'editar', restaurar_arquivo: 'editar',
+  executar_comando: 'shell',
+  executar_remoto: 'ssh', conectar_vps: 'ssh',
+  buscar_web: 'rede', navegador: 'rede',
+  android_dispositivos: 'dispositivo', android_parear: 'dispositivo', android_conectar: 'dispositivo',
+  android_instalar: 'dispositivo', android_iniciar: 'dispositivo', android_logs: 'dispositivo',
+  android_capturar_tela: 'dispositivo',
+  lembrar: 'memoria', skill_gerenciar: 'memoria',
+};
+
+function categoriaDe(tool) {
+  const t = String(tool || '');
+  if (CATEGORIA[t]) return CATEGORIA[t];
+  if (t.startsWith('mcp_')) return 'mcp';
+  return 'outro';
+}
+
+// O "valor" que a regra casa: o comando no shell/ssh, o caminho no editar, a URL na rede.
+function valorDe(tool, input) {
+  const i = input || {};
+  const cat = categoriaDe(tool);
+  if (cat === 'shell' || cat === 'ssh') return String(i.comando || i.host || '');
+  if (cat === 'editar' || cat === 'ler') return String(i.caminho || i.arquivo || i.padrao || '');
+  if (cat === 'rede') return String(i.url || i.consulta || i.query || '');
+  if (cat === 'dispositivo') return String(i.pacote || i.serial || i.host || '');
+  return String(i.comando || i.caminho || '');
+}
+
+// ── glob simples (sem dependência) ───────────────────────────────────────────
+// `git push*` casa "git push origin main". `*producao*` casa no meio. Ancorado por padrão,
+// que é o comportamento intuitivo pra comando ("rm *" não deve casar "npm run rm-cache").
+function casaGlob(padrao, valor) {
+  const p = String(padrao || '');
+  if (p === '*') return true;
+  const re = new RegExp('^' + p.split('*').map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$', 'i');
+  return re.test(String(valor || '').trim());
+}
+
+// ── leitura ──────────────────────────────────────────────────────────────────
+function _lerJson(caminho, { ler = null } = {}) {
+  try {
+    const txt = (ler || ((p) => fs.readFileSync(p, 'utf8')))(caminho);
+    const j = JSON.parse(txt);
+    return (j && typeof j === 'object' && !Array.isArray(j)) ? j : null;
+  } catch (_) { return null; }
+}
+
+function carregar({ dir = process.cwd(), lerGlobal = null, lerProjeto = null } = {}) {
+  const global = _lerJson(ARQ_GLOBAL, { ler: lerGlobal });
+  const projeto = _lerJson(path.join(dir, ARQ_PROJETO), { ler: lerProjeto });
+  return { global, projeto, temPolitica: !!(global || projeto) };
+}
+
+// ── decisão ──────────────────────────────────────────────────────────────────
+// Uma categoria pode ser string ('ask') ou objeto de globs ({'git push*':'ask','*':'allow'}).
+// Devolve {veredito, regra} — `regra` serve pro `ts politica testar` explicar de ONDE veio.
+function _decidirEm(politica, categoria, valor) {
+  if (!politica) return null;
+  const bruto = politica[categoria];
+  if (bruto === undefined || bruto === null) return null;
+  if (typeof bruto === 'string') {
+    return VEREDITOS.includes(bruto) ? { veredito: bruto, regra: categoria } : null;
+  }
+  if (typeof bruto !== 'object') return null;
+  // Regra mais ESPECÍFICA primeiro: '*' é sempre o último recurso; entre os demais,
+  // o padrão mais longo vence (mais específico).
+  const chaves = Object.keys(bruto).filter(k => VEREDITOS.includes(bruto[k]));
+  const especificas = chaves.filter(k => k !== '*').sort((a, b) => b.length - a.length);
+  for (const k of especificas) {
+    if (casaGlob(k, valor)) return { veredito: bruto[k], regra: categoria + ' → "' + k + '"' };
+  }
+  // o curinga também passa pela validação: um typo ('liberado') não pode virar decisão
+  if (VEREDITOS.includes(bruto['*'])) return { veredito: bruto['*'], regra: categoria + ' → "*"' };
+  return null;
+}
+
+function maisRestritivo(a, b) {
+  if (!a) return b; if (!b) return a;
+  return NIVEL[a.veredito] >= NIVEL[b.veredito] ? a : b;
+}
+
+// A decisão final. `null` = a política não opina (o fluxo normal do agente decide).
+function decidir({ global, projeto }, tool, input, { valor = null } = {}) {
+  const cat = categoriaDe(tool);
+  const val = valor !== null ? valor : valorDe(tool, input);
+  const g = _decidirEm(global, cat, val);
+  const p = _decidirEm(projeto, cat, val);
+  if (!g && !p) return null;
+  // Projeto SÓ RESTRINGE: se ele tenta afrouxar o global, o global prevalece — e dizemos
+  // isso na explicação, senão o usuário acha que a regra dele foi ignorada por bug.
+  if (g && p && NIVEL[p.veredito] < NIVEL[g.veredito]) {
+    return { veredito: g.veredito, regra: g.regra, origem: 'global',
+      nota: 'a política do projeto pediu "' + p.veredito + '" mas só pode RESTRINGIR — o global "' + g.veredito + '" prevalece' };
+  }
+  const venc = maisRestritivo(g, p);
+  return { veredito: venc.veredito, regra: venc.regra, origem: (venc === p ? 'projeto' : 'global') };
+}
+
+// Valida um arquivo de política e devolve os problemas em linguagem humana (pro `ts politica`).
+function validar(politica) {
+  const erros = [];
+  if (!politica || typeof politica !== 'object') return ['não é um objeto JSON'];
+  for (const [cat, val] of Object.entries(politica)) {
+    if (typeof val === 'string') {
+      if (!VEREDITOS.includes(val)) erros.push('"' + cat + '": "' + val + '" não é ' + VEREDITOS.join('/'));
+    } else if (val && typeof val === 'object' && !Array.isArray(val)) {
+      for (const [glob, v] of Object.entries(val)) {
+        if (!VEREDITOS.includes(v)) erros.push('"' + cat + '" → "' + glob + '": "' + v + '" não é ' + VEREDITOS.join('/'));
+      }
+    } else {
+      erros.push('"' + cat + '" precisa ser texto ou objeto de regras');
+    }
+  }
+  return erros;
+}
+
+const EXEMPLO = {
+  ler: 'allow',
+  editar: 'ask',
+  shell: { 'git status*': 'allow', 'git push*': 'ask', 'rm *': 'deny', '*': 'ask' },
+  ssh: { '*producao*': 'deny', '*': 'ask' },
+  rede: 'allow',
+  mcp: 'ask',
+};
+
+module.exports = {
+  ARQ_PROJETO, ARQ_GLOBAL, VEREDITOS, NIVEL, CATEGORIA, EXEMPLO,
+  categoriaDe, valorDe, casaGlob, carregar, decidir, validar, maisRestritivo,
+  _decidirEm,
+};