primocode 8.42.2 → 9.1.0

package/lib/skills.js

@@ -0,0 +1,329 @@
+/**
+ * skills.js — o que o PrimoCode sabe fazer bem, escrito em texto.
+ *
+ *   "O Primo Code já vem com várias skills instaladas por padrão. Comandos:
+ *    /skills, /install-skill e /marketplace."
+ *
+ * ── O QUE É UMA SKILL, E O QUE ELA NÃO É ─────────────────────────────────
+ * Uma skill é uma pasta com um `SKILL.md` dentro: um cabeçalho que diz quem
+ * ela é e quando serve, e um corpo que é o prompt dela. Nada de código, nada
+ * de instalar dependência, nada que rode. É conhecimento, não programa.
+ *
+ * Isso é decisão, não limitação. Uma skill que executa código é uma porta
+ * para qualquer pessoa mandar um arquivo e rodar o que quiser na máquina de
+ * quem instalou — e um marketplace de programas executáveis exige assinatura,
+ * revisão e sandbox, que é outro produto. Skill é texto: o pior que um texto
+ * mal-intencionado faz é dar um conselho ruim ao modelo, e o usuário vê o
+ * agente agindo, passo a passo, na tela.
+ *
+ * ── POR QUE NÃO É A MESMA COISA QUE OS ESPECIALISTAS ─────────────────────
+ * `especialistas.js` são sete briefings FIXOS, escolhidos pelo modelo quando
+ * ele delega uma tarefa a um subagente. Eles são do produto: ninguém instala,
+ * ninguém desliga, e a lista não cresce.
+ *
+ * Skill é do USUÁRIO. Ele instala, desliga, escreve a dele. É a resposta para
+ * "o Primo sempre esquece de rodar o lint antes de terminar" — que não se
+ * resolve pedindo de novo a cada conversa, e sim escrevendo uma vez.
+ *
+ * ── COMO ELA CHEGA AO MODELO ─────────────────────────────────────────────
+ * O corpo NÃO vai em todo pedido. São oito skills; mandar todas custaria
+ * milhares de tokens por mensagem num plano limitado por token, para que
+ * sete delas não tenham nada a ver com o pedido.
+ *
+ * O que decide é o `quando:` do cabeçalho — as palavras que fazem aquela
+ * skill valer a pena. Bateu, o corpo dela entra na frente da tarefa; não
+ * bateu, ela não custa nada. É o mesmo desenho dos especialistas, e pelo
+ * mesmo motivo: o teto de tokens é o recurso escasso deste produto.
+ *
+ * ── ONDE ELAS MORAM ──────────────────────────────────────────────────────
+ * Em `~/.primocode/skills/`, fora do pacote — pelo mesmo motivo do Studio:
+ * instalado global, a pasta do pacote costuma ser de sistema, e um `npm
+ * update` apagaria o que o usuário escreveu. As que vêm com o produto são
+ * copiadas na primeira vez; as dele ficam lá, a salvo de atualização.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ORIGEM = path.join(__dirname, '..', 'skills');
+const CASA = path.join(os.homedir(), '.primocode', 'skills');
+const ESTADO = path.join(CASA, 'estado.json');
+
+/* Teto do que entra num pedido. Duas skills longas já são mais texto que a
+   maioria das tarefas — e cada caractere aqui é um caractere a menos de
+   arquivo lido. Estourou, entram as que couberam, das que casaram melhor. */
+const MAX_CARACTERES = 6000;
+
+// ── leitura ──────────────────────────────────────────────────────────────
+
+/**
+ * O cabeçalho e o corpo de um SKILL.md.
+ *
+ * O cabeçalho fica entre duas linhas de `---`, uma chave por linha. Formato
+ * escolhido por ser o que qualquer pessoa já viu, e por caber num parser de
+ * dez linhas — YAML de verdade seria uma dependência para ler quatro campos.
+ */
+function separar(texto) {
+    const bruto = String(texto || '');
+    const m = bruto.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!m) return { cabecalho: {}, corpo: bruto.trim() };
+    const cabecalho = {};
+    for (const linha of m[1].split(/\r?\n/)) {
+        const par = linha.match(/^\s*([a-zA-Z_][\w-]*)\s*:\s*(.*)$/);
+        if (par) cabecalho[par[1].toLowerCase()] = par[2].trim().replace(/^["']|["']$/g, '');
+    }
+    return { cabecalho, corpo: m[2].trim() };
+}
+
+function lerEstado() {
+    try { return JSON.parse(fs.readFileSync(ESTADO, 'utf8')); } catch { return { desligadas: [] }; }
+}
+
+function salvarEstado(estado) {
+    try {
+        fs.mkdirSync(CASA, { recursive: true });
+        fs.writeFileSync(ESTADO, JSON.stringify(estado, null, 2), 'utf8');
+        return true;
+    } catch { return false; }
+}
+
+/* As que vêm com o produto são copiadas na primeira vez. Copiar SEMPRE por
+   cima seria desfazer a edição de quem melhorou uma delas; copiar só o que
+   falta deixa o usuário dono do que ele mexeu. */
+function prepararCasa() {
+    fs.mkdirSync(CASA, { recursive: true });
+    let nascidas = 0;
+    let origens = [];
+    try { origens = fs.readdirSync(ORIGEM, { withFileTypes: true }); } catch { return 0; }
+    for (const item of origens) {
+        if (!item.isDirectory()) continue;
+        const destino = path.join(CASA, item.name);
+        if (fs.existsSync(destino)) continue;
+        try {
+            fs.mkdirSync(destino, { recursive: true });
+            fs.copyFileSync(path.join(ORIGEM, item.name, 'SKILL.md'), path.join(destino, 'SKILL.md'));
+            nascidas++;
+        } catch { /* uma que falha não impede as outras */ }
+    }
+    return nascidas;
+}
+
+/** Uma skill pelo nome da pasta, ou null. */
+function ler(nome) {
+    const arquivo = path.join(CASA, nome, 'SKILL.md');
+    let texto;
+    try { texto = fs.readFileSync(arquivo, 'utf8'); } catch { return null; }
+    const { cabecalho, corpo } = separar(texto);
+    const estado = lerEstado();
+    return {
+        nome,
+        titulo: cabecalho.nome || cabecalho.titulo || nome,
+        descricao: cabecalho.descricao || '',
+        quando: String(cabecalho.quando || '').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean),
+        autor: cabecalho.autor || '',
+        corpo,
+        ligada: !estado.desligadas.includes(nome),
+        doProduto: fs.existsSync(path.join(ORIGEM, nome, 'SKILL.md')),
+        caminho: arquivo,
+    };
+}
+
+/** Todas as instaladas, em ordem alfabética. */
+function listar() {
+    prepararCasa();
+    let nomes = [];
+    try {
+        nomes = fs.readdirSync(CASA, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .sort();
+    } catch { return []; }
+    return nomes.map(ler).filter(Boolean);
+}
+
+// ── escrita ──────────────────────────────────────────────────────────────
+
+/* O nome vira pasta, então precisa ser um nome de pasta: sem barra, sem
+   `..`, sem acento. Um nome com `../` escreveria fora de ~/.primocode. */
+function apelidar(bruto) {
+    return String(bruto || '')
+        .normalize('NFD').replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+}
+
+/**
+ * Cria (ou reescreve) uma skill.
+ *
+ * @param {string} nome      como a pessoa a chamou
+ * @param {string} corpo     o prompt inteiro
+ * @param {object} extra     { descricao, quando, autor }
+ */
+function criar(nome, corpo, extra = {}) {
+    const apelido = apelidar(nome);
+    if (!apelido) return { ok: false, error: 'Dê um nome à skill.' };
+    if (!String(corpo || '').trim()) return { ok: false, error: 'A skill precisa de um conteúdo — é ele que vai para o modelo.' };
+
+    const cabecalho = [
+        '---',
+        `nome: ${String(nome).trim()}`,
+        `descricao: ${String(extra.descricao || '').replace(/\n/g, ' ').trim()}`,
+        `quando: ${String(extra.quando || '').replace(/\n/g, ' ').trim()}`,
+        `autor: ${String(extra.autor || 'você').trim()}`,
+        '---',
+        '',
+    ].join('\n');
+
+    try {
+        const pasta = path.join(CASA, apelido);
+        fs.mkdirSync(pasta, { recursive: true });
+        fs.writeFileSync(path.join(pasta, 'SKILL.md'), cabecalho + String(corpo).trim() + '\n', 'utf8');
+        // Skill recém-criada nasce LIGADA, mesmo que uma de mesmo nome tenha
+        // sido desligada antes: quem acabou de escrevê-la quer usá-la.
+        const estado = lerEstado();
+        estado.desligadas = estado.desligadas.filter((x) => x !== apelido);
+        salvarEstado(estado);
+        return { ok: true, nome: apelido, caminho: path.join(pasta, 'SKILL.md') };
+    } catch (e) {
+        return { ok: false, error: `Não deu para gravar: ${e.message}` };
+    }
+}
+
+function ligar(nome, ligada) {
+    const estado = lerEstado();
+    estado.desligadas = estado.desligadas.filter((x) => x !== nome);
+    if (!ligada) estado.desligadas.push(nome);
+    salvarEstado(estado);
+    return { ok: true, nome, ligada: !!ligada };
+}
+
+/**
+ * Apaga uma skill.
+ *
+ * As do produto voltam no próximo `listar()` — a cópia nasce de novo a partir
+ * do pacote. Por isso apagar uma delas não é apagar, é DESLIGAR: prometer
+ * remoção e ver a skill reaparecer amanhã é pior que dizer a verdade agora.
+ */
+function apagar(nome) {
+    const s = ler(nome);
+    if (!s) return { ok: false, error: `Não achei a skill "${nome}".` };
+    if (s.doProduto) {
+        ligar(nome, false);
+        return { ok: true, desligada: true,
+            aviso: 'Esta skill vem com o PrimoCode, então ela foi DESLIGADA em vez de apagada — '
+                + 'apagada, ela voltaria na próxima atualização.' };
+    }
+    try {
+        fs.rmSync(path.join(CASA, nome), { recursive: true, force: true });
+        return { ok: true, apagada: true };
+    } catch (e) { return { ok: false, error: e.message }; }
+}
+
+/**
+ * Instala de um arquivo ou de uma pasta que já está no disco.
+ *
+ * Não busca na rede de propósito: baixar e executar texto que virou prompt do
+ * agente é uma decisão que merece o caminho explícito de quem salvou o
+ * arquivo antes. O `/marketplace` traz as do catálogo; `/install-skill
+ * <caminho>` traz as que a pessoa escreveu ou recebeu.
+ */
+function instalarDe(caminho) {
+    const alvo = String(caminho || '').replace(/^~(?=$|[/\\])/, os.homedir());
+    let arquivo = alvo;
+    try {
+        if (fs.statSync(alvo).isDirectory()) arquivo = path.join(alvo, 'SKILL.md');
+    } catch { return { ok: false, error: `Não achei ${caminho}.` }; }
+
+    let texto;
+    try { texto = fs.readFileSync(arquivo, 'utf8'); }
+    catch { return { ok: false, error: `Não consegui ler ${arquivo}. Uma skill é um arquivo SKILL.md.` }; }
+
+    const { cabecalho, corpo } = separar(texto);
+    const nome = cabecalho.nome || path.basename(path.dirname(arquivo));
+    if (!corpo.trim()) return { ok: false, error: 'O arquivo não tem conteúdo depois do cabeçalho.' };
+    return criar(nome, corpo, cabecalho);
+}
+
+// ── o que entra no pedido ────────────────────────────────────────────────
+
+const semAcento = (v) => String(v || '').toLowerCase()
+    .normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+/**
+ * Quantas palavras do `quando:` aparecem no texto do pedido.
+ *
+ * ── PALAVRA INTEIRA, NUNCA PEDACO ────────────────────────────────────────
+ * O primeiro jeito era `texto.includes(palavra)`, e estava errado de um jeito
+ * que so apareceu no ensaio: "faz uma landing page PRO meu curso" puxou a
+ * skill de Git, porque o gatilho `pr` mora dentro de "pro". Gatilhos curtos
+ * — pr, api, seo, css — casam com metade da lingua portuguesa se a borda nao
+ * for exigida.
+ *
+ * Uma skill errada nao e ruido inofensivo: ela ocupa o teto de tokens do
+ * pedido e da ao modelo instrucoes sobre um assunto que ninguem pediu.
+ */
+function pontuar(skill, texto) {
+    const t = semAcento(texto);
+    let pontos = 0;
+    for (const palavra of skill.quando) {
+        const p = semAcento(palavra).trim();
+        if (!p) continue;
+        const escapado = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // A borda e escrita a mao em vez de `\b`: o gatilho pode comecar ou
+        // terminar em simbolo ("e-mail"), e ali o `\b` nao vale.
+        const re = new RegExp('(^|[^a-z0-9])' + escapado + '($|[^a-z0-9])');
+        if (re.test(t)) pontos++;
+    }
+    return pontos;
+}
+
+/**
+ * As skills que valem a pena para ESTE pedido, das mais ao menos relevantes.
+ *
+ * Só as ligadas, só as que casaram com alguma palavra, e só até o teto de
+ * caracteres. Skill que não casou não entra: mandar as oito em todo pedido
+ * custaria milhares de tokens para sete delas não terem nada a ver com o que
+ * foi pedido.
+ */
+function paraOPedido(texto, { teto = MAX_CARACTERES, todas = null } = {}) {
+    const lista = (todas || listar()).filter((s) => s.ligada && s.corpo);
+    const casadas = lista
+        .map((s) => ({ skill: s, pontos: pontuar(s, texto) }))
+        .filter((x) => x.pontos > 0)
+        .sort((a, b) => b.pontos - a.pontos);
+
+    const escolhidas = [];
+    let tamanho = 0;
+    for (const { skill } of casadas) {
+        if (tamanho + skill.corpo.length > teto) continue;
+        escolhidas.push(skill);
+        tamanho += skill.corpo.length;
+    }
+    return escolhidas;
+}
+
+/**
+ * O texto que vai na frente da tarefa.
+ *
+ * Vem antes do pedido, e não depois, pelo mesmo motivo do briefing dos
+ * especialistas: é contexto para ler o pedido, não um adendo a ele.
+ */
+function montar(texto, op = {}) {
+    const escolhidas = paraOPedido(texto, op);
+    if (!escolhidas.length) return { texto, skills: [] };
+    const blocos = escolhidas.map((s) => `### ${s.titulo}\n${s.corpo}`);
+    const cabeca = 'O QUE VOCÊ SABE SOBRE ESTE TIPO DE TAREFA (siga ao trabalhar):\n\n'
+        + blocos.join('\n\n') + '\n\n---\n\nPEDIDO:\n';
+    return { texto: cabeca + texto, skills: escolhidas };
+}
+
+module.exports = {
+    CASA, ORIGEM, MAX_CARACTERES,
+    separar, listar, ler, criar, ligar, apagar, instalarDe, apelidar,
+    paraOPedido, montar, pontuar, prepararCasa,
+};