terminal-smart-cli 0.94.2 → 0.97.0

package/lib/providers.js

@@ -0,0 +1,118 @@
+// lib/providers.js — CATÁLOGO de provedores de IA compatíveis com a API OpenAI.
+// Base do BYOK ("traga sua própria chave"): o CLI já fala `POST {baseUrl}/chat/completions`
+// (agent.llm), então qualquer provedor OpenAI-compat entra sem tocar no loop do agente.
+//
+// PORQUÊ: no plano Free todo token passa pelo gateway do TS e consome crédito — o usuário
+// conhece só uma amostra do produto. Com chave própria ele usa o TS INTEIRO de graça
+// (agente, missão, diagnóstico) e migra pro TS Cloud pela conveniência, não pelo teto.
+//
+// Por que tier gratuito FUNCIONA aqui: uma requisição de agente dura 2-3 minutos, então
+// 40 req/min é inatingível na prática. Um chatbot web estouraria; um agente de terminal não.
+'use strict';
+
+// `prefixo` valida a chave ANTES de gastar uma chamada (erro de copiar/colar é o mais comum).
+// `gratuito` só descreve o tier de entrada — não é promessa, provedor muda política.
+const PROVEDORES = {
+  nvidia: {
+    nome: 'NVIDIA NIM',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    // MEDIDO na API real (28/07/2026): o 70b estourou 120s de COLD START e o
+    // nemotron-70b é listado em /v1/models mas devolve 404 no /chat/completions.
+    // O v4-flash respondeu em 16s E chamou ferramenta — é o mesmo executor que o
+    // resto do TS já usa, então é o padrão sensato aqui.
+    modeloPadrao: 'deepseek-ai/deepseek-v4-flash',
+    sugestoes: [
+      ['deepseek-ai/deepseek-v4-flash', 'equilíbrio — chama ferramenta, ~16s'],
+      ['meta/llama-3.1-8b-instruct', 'o mais rápido — ~1s, bom pra chat/roteamento'],
+      ['mistralai/mistral-medium-3.5-128b', 'mais capaz — ~43s'],
+    ],
+    prefixo: /^nvapi-/,
+    gratuito: true,
+    limite: '40 req/min',
+    cadastro: 'https://build.nvidia.com — cadastro por telefone, sem cartão',
+  },
+  google: {
+    nome: 'Google AI Studio',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    modeloPadrao: 'gemini-2.5-flash',
+    prefixo: /^AIza/,
+    gratuito: true,
+    limite: 'cota diária generosa',
+    cadastro: 'https://aistudio.google.com/apikey — sem cartão',
+  },
+  cerebras: {
+    nome: 'Cerebras',
+    baseUrl: 'https://api.cerebras.ai/v1',
+    modeloPadrao: 'llama-3.3-70b',
+    prefixo: /^csk-/,
+    gratuito: true,
+    limite: 'todos os modelos no tier free',
+    cadastro: 'https://cloud.cerebras.ai — sem cartão',
+  },
+  groq: {
+    nome: 'Groq',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    modeloPadrao: 'llama-3.3-70b-versatile',
+    prefixo: /^gsk_/,
+    gratuito: true,
+    limite: 'cota diária',
+    cadastro: 'https://console.groq.com/keys — sem cartão',
+  },
+  openrouter: {
+    nome: 'OpenRouter',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    modeloPadrao: 'deepseek/deepseek-chat',
+    prefixo: /^sk-or-/,
+    gratuito: false,
+    limite: 'free tier com rate limit frequente',
+    cadastro: 'https://openrouter.ai/keys',
+  },
+  ollama: {
+    nome: 'Ollama (local)',
+    baseUrl: 'http://localhost:11434/v1',
+    modeloPadrao: 'qwen2.5-coder:7b',
+    prefixo: null,       // servidor local não exige chave
+    semChave: true,
+    gratuito: true,
+    limite: 'limitado pela sua máquina',
+    cadastro: 'https://ollama.com — roda offline',
+  },
+  custom: {
+    nome: 'Outro (OpenAI-compat)',
+    baseUrl: '',          // o usuário informa
+    modeloPadrao: '',
+    prefixo: null,
+    gratuito: false,
+    limite: 'depende do provedor',
+    cadastro: 'informe a baseUrl que termina em /v1',
+  },
+};
+
+function info(id) { return PROVEDORES[String(id || '').toLowerCase()] || null; }
+function ids() { return Object.keys(PROVEDORES); }
+
+// Valida o formato da chave contra o prefixo conhecido. Retorna '' se OK, senão o motivo.
+// NÃO prova que a chave funciona (isso é o keyring.testar, que faz chamada real) — só
+// mata o erro bobo de colar a chave do provedor errado.
+function validarChave(id, chave) {
+  const p = info(id);
+  if (!p) return 'provedor desconhecido: ' + id;
+  if (p.semChave) return '';
+  const k = String(chave || '').trim();
+  if (!k) return 'chave vazia';
+  if (p.prefixo && !p.prefixo.test(k)) {
+    return 'essa chave não parece ser do ' + p.nome + ' (esperado começar com "' +
+      String(p.prefixo).replace(/[/^]/g, '') + '")';
+  }
+  return '';
+}
+
+// baseUrl efetiva: o provedor custom (e o ollama, se a porta mudar) traz a sua.
+function baseUrlDe(id, override) {
+  const o = String(override || '').trim().replace(/\/+$/, '');
+  if (o) return o;
+  const p = info(id);
+  return p ? p.baseUrl : '';
+}
+
+module.exports = { PROVEDORES, info, ids, validarChave, baseUrlDe };

package/lib/router.js

@@ -5,6 +5,7 @@
 // Errar é barato de propósito: agente tem gate de destrutivo, orquestração tem
 // aprovação de plano com custo — o roteador nunca dispara gasto grande sozinho.
 const { api } = require('./api');
+const keyring = require('./keyring');
 
 // Pergunta/conversa: forma interrogativa ou pedido de explicação
 const Q_RE = /^(como|por ?qu[eê]|o ?que|qual|quais|quando|onde|quem|ser[aá] que|devo|posso|vale a pena|existe|tem como|é melhor|what|how|why|which|when|where|explique|me explica|explica|o que significa|diferen[çc]a entre)\b|\?\s*$/i;
@@ -52,7 +53,7 @@ function scope(msg) {
 let _keyCache = null;
 async function _aiKey(token) {
   if (_keyCache) return _keyCache;
-  _keyCache = await api('/api/ai/key', { token, timeoutMs: 15000 });
+  _keyCache = await keyring.resolve(token, { feature: 'cli_router', timeoutMs: 15000 });
   return _keyCache;
 }
 
@@ -66,7 +67,7 @@ async function classify(msg, token) {
       method: 'POST', signal: ctrl.signal,
       headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + k.key },
       body: JSON.stringify({
-        model: 'gemini-2.5-flash-lite', stream: false, max_completion_tokens: 5,
+        model: keyring.modeloPara(k, 'gemini-2.5-flash-lite'), stream: false, max_completion_tokens: 5,
         messages: [
           { role: 'system', content: 'Classifique a intenção da mensagem de um usuário de um CLI DevOps. Responda APENAS uma palavra: "chat" (pergunta, conversa, pedido de explicação), "agente" (quer que algo seja FEITO nesta máquina: comandos, arquivos, diagnóstico, instalação) ou "orquestrar" (objetivo GRANDE com vários entregáveis para uma equipe de agentes).' },
           { role: 'user', content: String(msg).slice(0, 500) },

package/lib/skill-index.js

@@ -0,0 +1,398 @@
+// lib/skill-index.js — o agente SABE que existe skill pra isso.
+//
+// Antes: o prompt listava só as skills INSTALADAS (~/.ts/skills). O agente era cego para
+// o que existe na galeria e não foi instalado, e para o que outros agentes instalaram na
+// mesma máquina. Resultado: refazia do zero um procedimento que já estava escrito.
+//
+// Listar tudo não resolve — 323 skills de um catálogo dariam ~48k chars em TODA conversa.
+// A saída é BUSCA por relevância, e o gatilho é DETERMINÍSTICO: o harness consulta o índice
+// com a tarefa antes da primeira iteração e injeta no máximo 3 candidatas acima de um
+// limiar. Sem match, o bloco não existe e o custo é zero.
+//
+// Por que não deixar o modelo decidir chamar uma tool de busca: regra sozinha não segura
+// comportamento (o filtro de segredos precisou virar código porque o agente ignorou a
+// regra 3x). A tool `buscar_skill` existe, mas como complemento pro pedido explícito.
+//
+// A busca REUSA o BM25 de indice.js: `search(dir, query, k, idxIn)` aceita um índice já
+// montado, então basta montar os chunks no formato dele — zero matemática duplicada.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const indice = require('./indice');
+
+const CACHE_DIR = path.join(os.homedir(), '.ts', 'cache');
+const CACHE = path.join(CACHE_DIR, 'skills-index.json');
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+// Onde OUTROS agentes instalam skills. O formato é o mesmo (<slug>/SKILL.md com
+// frontmatter name/description) — confirmado contra o catálogo público da NVIDIA. Ler
+// daqui é o mesmo princípio de já ler AGENTS.md/CLAUDE.md: aproveitar o que o ecossistema
+// instalou, sem pedir configuração nenhuma ao usuário.
+const DIRS_AGENTES = [
+  ['ts', path.join(os.homedir(), '.ts', 'skills')],
+  ['claude-code', path.join(os.homedir(), '.claude', 'skills')],
+  ['codex', path.join(os.homedir(), '.codex', 'skills')],
+  ['cursor', path.join(os.homedir(), '.cursor', 'skills')],
+  ['agents', path.join(os.homedir(), '.agents', 'skills')],
+];
+
+// ── leitura local ────────────────────────────────────────────────────────────
+// A DESCRIÇÃO é o que alimenta a busca: skill com descrição vazia fica invisível. Por isso
+// aqui trata também o bloco literal YAML (`description: |` com linhas indentadas embaixo),
+// que catálogos reais usam — sem isso, `aiq-deploy` e `aiq-research` da NVIDIA entravam com
+// descrição "|" e nunca seriam encontradas.
+function _valorYaml(raw, campo) {
+  const re = new RegExp('^' + campo + '\\s*:\\s*(.*)$', 'mi');
+  const m = raw.match(re);
+  if (!m) return '';
+  const primeira = m[1].trim();
+  if (!/^[|>]-?\+?$/.test(primeira)) return primeira.replace(/^["']|["']$/g, '');
+  // bloco literal: junta as linhas indentadas que vêm logo depois
+  const resto = raw.slice(m.index + m[0].length).split(/\r?\n/);
+  const linhas = [];
+  for (const l of resto) {
+    if (!l.trim()) { if (linhas.length) break; continue; }
+    if (!/^\s+/.test(l)) break;                    // acabou a indentação = acabou o bloco
+    linhas.push(l.trim());
+    if (linhas.join(' ').length > 400) break;
+  }
+  return linhas.join(' ');
+}
+
+function _frontmatter(md) {
+  const raw = String(md || '').slice(0, 4000);
+  const tags = (raw.match(/^\s*tags\s*:\s*\[?([^\]\n]+)\]?/mi) || [])[1];
+  return {
+    nome: _valorYaml(raw, 'name'),
+    descricao: _valorYaml(raw, 'description'),
+    tags: (tags || '').split(/[,\s]+/).map(s => s.trim().replace(/^["'-]+|["']+$/g, '')).filter(Boolean).slice(0, 8),
+  };
+}
+
+// Varre os diretórios de skills de TODOS os agentes conhecidos.
+function locais({ dirs = DIRS_AGENTES, lerDir = null, lerArq = null } = {}) {
+  const _ls = lerDir || ((d) => fs.readdirSync(d));
+  const _read = lerArq || ((p) => fs.readFileSync(p, 'utf8'));
+  const out = [];
+  const vistos = new Set();
+  for (const [agente, dir] of dirs) {
+    let slugs = [];
+    try { slugs = _ls(dir); } catch (_) { continue; }
+    for (const slug of slugs) {
+      if (vistos.has(slug)) continue;           // a do TS ganha (é a 1ª da lista)
+      const md = path.join(dir, slug, 'SKILL.md');
+      let raw; try { raw = _read(md); } catch (_) { continue; }
+      const fm = _frontmatter(raw);
+      vistos.add(slug);
+      // `corpo` (só das INSTALADAS) entra no índice de busca para dar recall: a descrição
+      // sozinha é curta e perde sinônimo ("redesenhar a interface" × "redesign de UI").
+      // Só das instaladas porque é conteúdo já aprovado pelo usuário — o corpo de skill de
+      // terceiro não entra nem no índice nem no prompt.
+      const corpo = String(raw).replace(/^---[\s\S]*?---/, '').replace(/\s+/g, ' ').trim().slice(0, 800);
+      out.push({
+        slug, nome: fm.nome || slug, descricao: fm.descricao, tags: fm.tags, corpo,
+        origem: agente, caminho: md, instalada: true,
+      });
+    }
+  }
+  return out;
+}
+
+// ── normalização de português ────────────────────────────────────────────────
+// O tokenize do indice.js foi feito pra CÓDIGO (identificadores ASCII): ele parte em
+// acento ("fórmulas" vira "rmulas") e não trata plural. Descrição de skill é prosa em
+// português, então aqui a busca precisa de mais: "planilha" tem que achar "planilhas".
+// Normalizo NESTA camada em vez de mexer no indice.js — alterar o tokenize mudaria o
+// ranking da busca de código, que é outra feature e já está calibrada.
+// STOPWORDS: sem isso, "abrir a porta NO firewall" casava `commit-semantico` — porque
+// "no" aparece nas duas frases e o BM25 conta como termo. Palavra vazia casa com tudo e
+// produz exatamente o falso-positivo que mais atrapalha aqui. O tokenize do indice.js não
+// filtra (foi feito pra código, onde não existe artigo).
+const STOPWORDS = new Set([
+  'a', 'o', 'as', 'os', 'um', 'uma', 'uns', 'umas', 'de', 'do', 'da', 'dos', 'das', 'em',
+  'no', 'na', 'nos', 'nas', 'por', 'para', 'pra', 'pro', 'com', 'sem', 'ao', 'aos', 'e',
+  'ou', 'que', 'se', 'ja', 'meu', 'minha', 'seu', 'sua', 'este', 'esta', 'isso', 'esse',
+  'essa', 'aqui', 'ali', 'quero', 'preciso', 'fazer', 'faz', 'ter', 'tem', 'the', 'of',
+  'to', 'in', 'on', 'for', 'and', 'or', 'with', 'my', 'this', 'that', 'is', 'are', 'it',
+]);
+
+const ACENTOS = new RegExp('[\\u0300-\\u036f]', 'g');
+function _semStopwords(texto) {
+  return String(texto || '').split(/\s+/).filter(w => w && !STOPWORDS.has(w)).join(' ');
+}
+function _normalizar(texto) {
+  return _semStopwords(String(texto || '')
+    .normalize('NFD').replace(ACENTOS, '')      // fórmulas → formulas
+    .toLowerCase()
+    // plural simples do português: -oes/-aes/-ais/-eis → -ao/-al/-el, e -s final.
+    // Aplicado dos DOIS lados (índice e query), então basta ser consistente, não perfeito.
+    .replace(/\b(\w{3,}?)(?:oes|aes)\b/g, '$1ao')
+    .replace(/\b(\w{3,}?)(?:ais)\b/g, '$1al')
+    .replace(/\b(\w{4,})s\b/g, '$1')
+    // RADICAL de 6: BM25 é casamento exato de token, então "revisar" (query) nunca acharia
+    // "revisa" (descrição) — flexão verbal mata o recall em prosa portuguesa. Truncar dos
+    // DOIS lados resolve sem stemmer de verdade. 6 e não 4/5 de propósito: é o menor corte
+    // que resolveu os casos reais sem colar palavras não relacionadas.
+    .replace(/\b(\w{7,})\b/g, (m) => m.slice(0, 6)));
+}
+
+// NEGAÇÃO vira falso-positivo em busca lexical. Caso real: a skill `public-relations`
+// descreve "...media strategy (NOT pull requests)" — o autor escreveu a negação justamente
+// pra evitar confusão, e o BM25, que não entende "not", passou a casá-la com "revisar um
+// pull request" acima de qualquer skill de code review. Tirar o trecho negado antes de
+// indexar resolve na origem.
+const NEGACOES = [
+  /\((?:not|não|nao)\s[^)]{0,80}\)/gi,        // "(not pull requests)"
+  /\bnot\s+for\s+[^.;]{0,80}/gi,               // "Not for prod monitoring"
+  /\bdo\s+not\s+use\s+(?:for|to|when)\s+[^.;]{0,80}/gi,
+  /\b(?:não|nao)\s+use\s+(?:para|quando)\s+[^.;]{0,80}/gi,
+];
+function _semNegacao(texto) {
+  let s = String(texto || '');
+  for (const re of NEGACOES) s = s.replace(re, ' ');
+  return s;
+}
+
+// ── índice pesquisável (formato de indice.js) ────────────────────────────────
+// Cada skill vira um "chunk". O campo `file` é o slug — o dedup por arquivo do search()
+// então garante uma linha por skill, que é justamente o que se quer aqui.
+function montarIndice(skills) {
+  const df = Object.create(null);
+  const chunks = [];
+  for (const s of skills || []) {
+    const texto = _normalizar(_semNegacao([s.slug, s.nome, s.descricao, (s.tags || []).join(' '), s.corpo || ''].filter(Boolean).join(' ')));
+    const toks = indice.tokenize(texto);
+    if (!toks.length) continue;
+    const tf = Object.create(null);
+    for (const t of toks) tf[t] = (tf[t] || 0) + 1;
+    for (const t in tf) df[t] = (df[t] || 0) + 1;
+    chunks.push({ file: s.slug, l0: 1, l1: 1, tf, len: toks.length, snippet: s.descricao || s.nome, sig: [], _skill: s });
+  }
+  const totalLen = chunks.reduce((a, c) => a + c.len, 0);
+  return { v: 1, root: '', built: null, N: chunks.length, avgdl: chunks.length ? totalLen / chunks.length : 0, df, chunks, files: chunks.length };
+}
+
+// LIMIAR: BM25 não é normalizado — o score depende do corpus (medido no catálogo real:
+// 16.8 pra "mensagem de commit", 5.5 pra "revisar pull request"). Por isso são DOIS
+// limiares, e não um:
+//
+//   LIMIAR (1.0) — busca EXPLÍCITA (`ts skills buscar`). O usuário está lendo a lista e
+//   julga sozinho; recall vale mais que precisão.
+//
+//   LIMIAR_PROMPT (3.5) — injeção AUTOMÁTICA no prompt. Aqui um falso-positivo empurra o
+//   agente pro caminho errado sem ninguém revisar. Medido: "fazer deploy do container
+//   docker" casa `doca-container-deployment` (que é DPU BlueField, não Docker) com 6.6 —
+//   ou seja, nem 3.5 elimina todo falso-positivo em catálogo de domínio alheio. Daí o
+//   texto do bloco dizer "se servir CLARAMENTE" e nunca autorizar instalação sozinho.
+const LIMIAR = 1.0;
+const LIMIAR_PROMPT = 3.5;
+// destaque mínimo do 1º sobre o 2º pra sugerir no prompt (empate técnico = ruído).
+// Medido em corpus de 486 skills: 1.15 mantém os bons matches e corta 5 dos 6 falsos.
+const DESTAQUE_PROMPT = 1.15;
+
+// `destaque` = quanto o 1º precisa superar o 2º pra a sugestão valer. Limiar absoluto
+// sozinho não escala: com 486 skills os scores dobraram e QUASE TODA tarefa passava a
+// receber duas sugestões, a maioria irrelevante ("criar um dockerfile" casava
+// `tao-run-on-local-docker` com 7.56 × 7.52 do segundo — empate técnico = ruído).
+// Quando vários resultados empatam, é sinal de que a query casou por palavra genérica;
+// quando um se destaca de verdade, aí sim há skill pra aquilo.
+function buscar(skills, consulta, { k = 3, limiar = LIMIAR, destaque = 0, idx = null } = {}) {
+  const texto = String(consulta || '').trim();
+  if (!texto) return [];
+  const _idx = idx || montarIndice(skills);
+  if (!_idx.N) return [];
+  const brutos = indice.search('', _normalizar(texto), Math.max(k * 3, 9), _idx) || [];
+  const acima = brutos.filter(r => r.score >= limiar);
+  if (!acima.length) return [];
+  if (destaque > 1 && acima.length > 1 && acima[0].score < acima[1].score * destaque) return [];
+  const porSlug = new Map(_idx.chunks.map(c => [c.file, c._skill]));
+  return acima
+    .slice(0, k)
+    .map(r => Object.assign({ score: Math.round(r.score * 100) / 100 }, porSlug.get(r.file) || { slug: r.file }));
+}
+
+// ── cache do catálogo remoto ─────────────────────────────────────────────────
+function lerCache({ agora = Date.now() } = {}) {
+  try {
+    const j = JSON.parse(fs.readFileSync(CACHE, 'utf8'));
+    if (!j || !Array.isArray(j.skills)) return null;
+    if (agora - (j.em || 0) > TTL_MS) return { ...j, vencido: true };
+    return j;
+  } catch (_) { return null; }
+}
+
+function gravarCache(skills, { agora = Date.now() } = {}) {
+  try {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(CACHE, JSON.stringify({ v: 1, em: agora, skills }));
+    return true;
+  } catch (_) { return false; }
+}
+
+// Catálogo remoto = galeria do TS + fontes externas. `fetchGaleria` e `fetchExternas` são
+// INJETADOS pra este módulo continuar testável sem rede.
+async function atualizar({ fetchGaleria = null, fetchExternas = null, agora = Date.now() } = {}) {
+  const out = [];
+  if (fetchGaleria) {
+    try {
+      for (const s of (await fetchGaleria()) || []) {
+        out.push({ slug: s.slug, nome: s.name || s.nome || s.slug, descricao: s.description || s.descricao || '',
+          tags: s.tags || [], origem: 'galeria', instalada: false });
+      }
+    } catch (_) { /* galeria fora do ar não pode derrubar a busca local */ }
+  }
+  if (fetchExternas) {
+    try {
+      for (const s of (await fetchExternas()) || []) {
+        // `caminhoRepo` PRECISA sobreviver ao cache: é por ele que `ts skills add` baixa o
+        // SKILL.md depois. Sem esse campo, a instalação caía na galeria e dava 404 — ou
+        // seja, o comando que o próprio agente sugere não funcionaria.
+        out.push({ slug: s.slug, nome: s.nome || s.slug, descricao: s.descricao || '', tags: s.tags || [],
+          origem: s.origem || 'externa', url: s.url || '', caminhoRepo: s.caminhoRepo || '', instalada: false });
+      }
+    } catch (_) {}
+  }
+  if (out.length) gravarCache(out, { agora });
+  return out;
+}
+
+// A visão completa: instaladas (de qualquer agente) + catálogo em cache, sem duplicar.
+function todas({ locaisIn = null, cache = null } = {}) {
+  const inst = locaisIn || locais();
+  const slugs = new Set(inst.map(s => s.slug));
+  const c = cache !== null ? cache : (lerCache() || { skills: [] });
+  const remotas = (c.skills || []).filter(s => !slugs.has(s.slug));
+  return inst.concat(remotas);
+}
+
+// ── bloco do prompt ──────────────────────────────────────────────────────────
+// Só entra o que passou no limiar. Skill NÃO instalada aparece apenas com nome, descrição
+// e origem — o CORPO dela nunca entra sem instalação aprovada, porque skill de terceiro é
+// conteúdo não-confiável (mesma razão de AGENTS.md ser lido como dado, não como ordem).
+function blocoSugestao(candidatas, lang = 'pt') {
+  const naoInstaladas = (candidatas || []).filter(s => !s.instalada);
+  if (!naoInstaladas.length) return '';
+  const linhas = naoInstaladas.map(s =>
+    `- ${s.slug}${s.nome && s.nome !== s.slug ? ' (' + s.nome + ')' : ''}: ${String(s.descricao || '').slice(0, 160)}` +
+    (s.origem ? ` [${s.origem}]` : ''));
+  return lang === 'en'
+    ? '\n\nSKILLS AVAILABLE BUT NOT INSTALLED (they match this task):\n' + linhas.join('\n') +
+      '\nThese are NOT loaded. If one clearly fits, TELL the user it exists and that `ts skills add <slug>` installs it — never install on your own.'
+    : '\n\nSKILLS QUE EXISTEM MAS NÃO ESTÃO INSTALADAS (casaram com esta tarefa):\n' + linhas.join('\n') +
+      '\nElas NÃO estão carregadas. Se uma servir claramente, AVISE o usuário que ela existe e que `ts skills add <slug>` instala — nunca instale por conta própria.';
+}
+
+// ── fontes externas (repos no formato Agent Skills) ──────────────────────────
+// Registro em ARQUIVO (~/.ts/skill-sources.json) pra somar catálogo sem release novo.
+// O default vem vazio de propósito: nada de terceiro entra no índice sem o usuário pedir.
+const FONTES = path.join(os.homedir(), '.ts', 'skill-sources.json');
+
+function fontes({ ler = null } = {}) {
+  try {
+    const j = JSON.parse((ler || ((p) => fs.readFileSync(p, 'utf8')))(FONTES));
+    return Array.isArray(j) ? j : (j && Array.isArray(j.fontes) ? j.fontes : []);
+  } catch (_) { return []; }
+}
+
+function addFonte(repo, { pasta = 'skills' } = {}) {
+  const r = String(repo || '').trim().replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '').replace(/\/+$/, '');
+  if (!/^[\w.-]+\/[\w.-]+$/.test(r)) throw new Error('formato esperado: <org>/<repo> (ex: NVIDIA/skills)');
+  const atuais = fontes();
+  if (atuais.some(f => f.repo === r)) return atuais;
+  atuais.push({ repo: r, pasta });
+  fs.mkdirSync(path.dirname(FONTES), { recursive: true });
+  fs.writeFileSync(FONTES, JSON.stringify({ fontes: atuais }, null, 2));
+  return atuais;
+}
+
+function rmFonte(repo) {
+  const restantes = fontes().filter(f => f.repo !== repo);
+  fs.writeFileSync(FONTES, JSON.stringify({ fontes: restantes }, null, 2));
+  return restantes;
+}
+
+// Repos costumam DUPLICAR as mesmas skills por agente (`.gemini/`, `.claude/`, `.cursor/`).
+// Indexar tudo encheria o catálogo com o mesmo conteúdo 3x — puro ruído na busca.
+const PASTAS_DUPLICATA = /^\.(gemini|claude|cursor|codex|agents|kiro)/i;
+
+// Descobre em que pasta o repo guarda as skills (nem todo mundo usa `skills/`) escolhendo
+// a de maior contagem, ignorando as pastas de duplicata por agente.
+function _pastaPrincipal(caminhos) {
+  const cont = {};
+  for (const p of caminhos) {
+    const raiz = p.split('/')[0];
+    if (PASTAS_DUPLICATA.test(raiz)) continue;
+    cont[raiz] = (cont[raiz] || 0) + 1;
+  }
+  const top = Object.entries(cont).sort((a, b) => b[1] - a[1])[0];
+  return top ? top[0] : null;
+}
+
+// Baixa o índice de UM repositório no formato Agent Skills.
+// UMA chamada à Git Trees API traz a árvore inteira; os SKILL.md vêm do raw.githubusercontent,
+// que é CDN e NÃO consome o rate limit da API (60/h anônimo) — é isso que permite catálogo
+// grande. O que limita é o tempo, então os downloads vão em paralelo com concorrência fixa.
+async function indexarRepo(repo, { pasta = null, teto = 500, concorrencia = 8, fetchImpl = null, onProgresso = null } = {}) {
+  const _fetch = fetchImpl || fetch;
+  const arvore = await _fetch('https://api.github.com/repos/' + repo + '/git/trees/HEAD?recursive=1',
+    { headers: { 'User-Agent': 'terminal-smart-cli', 'Accept': 'application/vnd.github+json' } });
+  if (!arvore || !arvore.ok) {
+    const st = (arvore && arvore.status) || '?';
+    throw new Error(st === 403
+      ? 'GitHub recusou (HTTP 403) — provável rate limit da API; tente de novo em alguns minutos'
+      : 'não consegui ler o repositório ' + repo + ' (HTTP ' + st + ')');
+  }
+  const j = await arvore.json();
+  const todosMd = (j.tree || []).filter(n => n.type === 'blob' && /(^|\/)SKILL\.md$/i.test(n.path)).map(n => n.path);
+  const _pasta = pasta || _pastaPrincipal(todosMd);
+  if (!_pasta) return { skills: [], total: todosMd.length, lidas: 0, pasta: null };
+
+  const alvos = todosMd.filter(p => p.startsWith(_pasta + '/')).slice(0, teto);
+  const out = [];
+  let feitos = 0;
+
+  // fila com N workers: 500 downloads sequenciais levariam minutos
+  const fila = alvos.slice();
+  const worker = async () => {
+    for (;;) {
+      const p = fila.shift();
+      if (!p) return;
+      const slug = p.slice(_pasta.length + 1, -('/SKILL.md'.length)).replace(/\//g, '-');
+      try {
+        const r = await _fetch('https://raw.githubusercontent.com/' + repo + '/HEAD/' + p, { headers: { 'User-Agent': 'terminal-smart-cli' } });
+        if (r && r.ok) {
+          const fm = _frontmatter(await r.text());
+          // sem descrição a skill é invisível na busca — não vale ocupar espaço no índice
+          if (fm.descricao || fm.nome) {
+            out.push({ slug, nome: fm.nome || slug, descricao: fm.descricao, tags: fm.tags,
+              origem: repo, caminhoRepo: p, url: 'https://github.com/' + repo + '/blob/HEAD/' + p, instalada: false });
+          }
+        }
+      } catch (_) { /* uma skill ilegível não invalida o catálogo inteiro */ }
+      feitos++;
+      if (onProgresso) { try { onProgresso(feitos, alvos.length); } catch (_) {} }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(concorrencia, 16)) }, worker));
+  return { skills: out, total: todosMd.length, lidas: out.length, pasta: _pasta, truncado: todosMd.filter(p => p.startsWith(_pasta + '/')).length > teto };
+}
+
+// Baixa o SKILL.md de uma skill EXTERNA já indexada (pra `ts skills add` funcionar com
+// catálogo, não só com a galeria — sem isto, a sugestão que o agente dá não funciona).
+async function baixarSkill(skill, { fetchImpl = null } = {}) {
+  const _fetch = fetchImpl || fetch;
+  if (!skill || !skill.origem || !skill.caminhoRepo) throw new Error('skill sem origem rastreável');
+  const url = 'https://raw.githubusercontent.com/' + skill.origem + '/HEAD/' + skill.caminhoRepo;
+  const r = await _fetch(url, { headers: { 'User-Agent': 'terminal-smart-cli' } });
+  if (!r || !r.ok) throw new Error('não consegui baixar (HTTP ' + ((r && r.status) || '?') + ')');
+  return await r.text();
+}
+
+module.exports = {
+  CACHE, TTL_MS, DIRS_AGENTES, LIMIAR, LIMIAR_PROMPT, DESTAQUE_PROMPT, FONTES,
+  locais, montarIndice, buscar, todas, _normalizar,
+  lerCache, gravarCache, atualizar, blocoSugestao,
+  fontes, addFonte, rmFonte, indexarRepo, baixarSkill, _pastaPrincipal, _semNegacao,
+  _frontmatter,
+};

package/lib/temas.js

@@ -0,0 +1,101 @@
+// lib/temas.js — paletas do CLI.
+//
+// Trocar tema é irracional e é exatamente por isso que engaja: dev gosta de escolher tema.
+// Custa pouco e é a primeira coisa que se compara entre CLIs.
+//
+// A regra que separa isto de enfeite: as cores são SEMÂNTICAS, não decorativas.
+//   ok    = comprovado / passou no gate      (o TS prova entrega — esta cor significa prova)
+//   warn  = precisa da sua aprovação
+//   err   = bloqueado / falhou
+//   dim   = leitura, contexto, coisa inativa
+// Um tema pode mudar o TOM de cada uma; nenhum pode trocar o significado. Por isso a
+// paleta define os quatro papéis, e não "uma cor pra cada coisa que aparecer".
+//
+// `terminal` é o tema que NÃO usa RGB: emite os códigos ANSI básicos (30-37), que o
+// emulador pinta com o esquema do próprio usuário. É o "herda do terminal".
+'use strict';
+
+const TEMAS = {
+  padrao: {
+    nome: 'Padrão — cyan → indigo',
+    primaria: [34, 211, 238], secundaria: [129, 140, 248],
+    ok: [52, 211, 153], warn: [251, 191, 36], err: [248, 113, 113],
+  },
+  oceano: {
+    nome: 'Oceano — azul profundo',
+    primaria: [56, 189, 248], secundaria: [59, 130, 246],
+    ok: [45, 212, 191], warn: [250, 204, 21], err: [244, 114, 182],
+  },
+  ambar: {
+    nome: 'Âmbar — quente, alto contraste',
+    primaria: [251, 191, 36], secundaria: [249, 115, 22],
+    ok: [163, 230, 53], warn: [253, 224, 71], err: [239, 68, 68],
+  },
+  matrix: {
+    nome: 'Matrix — verde fósforo',
+    primaria: [74, 222, 128], secundaria: [34, 197, 94],
+    ok: [134, 239, 172], warn: [250, 204, 21], err: [248, 113, 113],
+  },
+  violeta: {
+    nome: 'Violeta — roxo/rosa',
+    primaria: [167, 139, 250], secundaria: [236, 72, 153],
+    ok: [110, 231, 183], warn: [252, 211, 77], err: [251, 113, 133],
+  },
+  mono: {
+    nome: 'Mono — sem cor decorativa, só os estados',
+    primaria: [156, 163, 175], secundaria: [107, 114, 128],
+    ok: [156, 163, 175], warn: [209, 213, 219], err: [248, 113, 113],
+  },
+  terminal: {
+    nome: 'Terminal — herda o esquema do seu emulador',
+    ansi: { primaria: 36, secundaria: 34, ok: 32, warn: 33, err: 31 },
+  },
+};
+
+const PADRAO = 'padrao';
+function nomes() { return Object.keys(TEMAS); }
+function info(id) { return TEMAS[String(id || '').toLowerCase()] || null; }
+function existe(id) { return !!info(id); }
+
+// Constrói as funções de cor do tema. `tty=false` (pipe/NO_COLOR) devolve texto puro —
+// a saída do CLI continua parseável por script, que é o comportamento de sempre.
+function montar(id, tty) {
+  const t = info(id) || TEMAS[PADRAO];
+  const puro = (s) => String(s);
+  if (!tty) {
+    return { cyan: puro, indigo: puro, ok: puro, warn: puro, err: puro, bold: puro, dim: puro, _tema: id || PADRAO };
+  }
+  const rgb = (c) => (s) => `\x1b[38;2;${c[0]};${c[1]};${c[2]}m${s}\x1b[39m`;
+  const ansi = (n) => (s) => `\x1b[${n}m${s}\x1b[39m`;
+  const cor = t.ansi
+    ? { primaria: ansi(t.ansi.primaria), secundaria: ansi(t.ansi.secundaria), ok: ansi(t.ansi.ok), warn: ansi(t.ansi.warn), err: ansi(t.ansi.err) }
+    : { primaria: rgb(t.primaria), secundaria: rgb(t.secundaria), ok: rgb(t.ok), warn: rgb(t.warn), err: rgb(t.err) };
+  return {
+    // `cyan`/`indigo` mantêm o NOME antigo de propósito: são usados em centenas de pontos
+    // do CLI. O que muda é o valor — renomear tudo seria um diff enorme sem ganho.
+    cyan: cor.primaria,
+    indigo: cor.secundaria,
+    ok: cor.ok, warn: cor.warn, err: cor.err,
+    bold: (s) => `\x1b[1m${s}\x1b[22m`,
+    dim: (s) => `\x1b[2m${s}\x1b[22m`,
+    _tema: id || PADRAO,
+  };
+}
+
+// Gradiente primária→secundária, caractere a caractere (a assinatura visual do ts).
+// Tema ANSI não interpola (só tem 16 cores): devolve tudo na primária.
+function gradienteDe(id, texto, tty) {
+  const t = info(id) || TEMAS[PADRAO];
+  if (!tty) return String(texto);
+  if (t.ansi) return `\x1b[${t.ansi.primaria}m${texto}\x1b[39m`;
+  const a = t.primaria, b = t.secundaria;
+  const chars = [...String(texto)];
+  const n = Math.max(1, chars.length - 1);
+  return chars.map((ch, i) => {
+    const k = i / n;
+    const [r, g, bl] = a.map((v, j) => Math.round(v + (b[j] - v) * k));
+    return `\x1b[38;2;${r};${g};${bl}m${ch}`;
+  }).join('') + '\x1b[39m';
+}
+
+module.exports = { TEMAS, PADRAO, nomes, info, existe, montar, gradienteDe };