primocode 8.11.1 → 8.12.0

package/lib/catalogo.js

@@ -83,7 +83,9 @@ const GRUPOS = [
               args: 'ferramenta: prisma | tela | prosa | grade | corte | traco. titulo. doc: objeto no formato que studio_spec daquela ferramenta descreve.' },
             { tool: 'studio_ler',       escreve: false, faz: 'lê algo que já foi criado', args: 'id.' },
             { tool: 'studio_atualizar', escreve: false, faz: 'ajusta o que já existe, sem refazer do zero',
-              args: 'id. titulo (opcional). doc (opcional).' },
+              args: 'id. titulo (opcional). doc (opcional): só as chaves que MUDAM — o resto do documento fica intacto.' },
+            { tool: 'studio_versoes',   escreve: false, faz: 'histórico de um arquivo, e volta a uma versão anterior',
+              args: 'id. restaurar (opcional): "anterior" desfaz a última mudança, ou o nome de uma versão da lista.' },
             { tool: 'studio_listar',    escreve: false, faz: 'lista o que já existe no estúdio', args: null },
             { tool: 'studio_midia',     escreve: false, faz: 'manda imagem, música ou vídeo seu para usar nas peças',
               args: 'arquivo (opcional): caminho no projeto — sem ele, lista a galeria. nome (opcional).' },

package/lib/studio.js

@@ -39,7 +39,10 @@ const BASE = `http://127.0.0.1:${PORTA}`;
 
 // Só o código do Studio é atualizado; `arquivos/` e `midia/` (o que o usuário
 // criou) nunca são tocados.
-const COPIAVEIS = new Set(['server.py', 'web', 'ferramentas', 'README.md', 'PRIMOCODE.md']);
+// voz.py é módulo do servidor, não enfeite: sem ele o server.py não importa
+// e o Studio inteiro deixa de subir. Todo arquivo .py do Studio precisa
+// entrar aqui.
+const COPIAVEIS = new Set(['server.py', 'voz.py', 'web', 'ferramentas', 'README.md', 'PRIMOCODE.md']);
 
 /**
  * Onde está o Python 3 desta máquina.
@@ -112,13 +115,36 @@ function pedir(metodo, rota, corpo, timeout = 30000) {
             path: rota,
             method: metodo,
             timeout,
-            headers: dados ? { 'Content-Type': 'application/json', 'Content-Length': dados.length } : {},
+            // Este cabeçalho diz ao Studio que quem fala é a IA, não o editor
+            // do navegador. O servidor valida o documento com rigor só neste
+            // caso: erro de formato tem de voltar para o agente como lição, e
+            // não pode fazer o salvamento de uma pessoa que está digitando
+            // falhar no meio da edição.
+            headers: Object.assign({ 'X-Primo-Agente': '1' },
+                dados ? { 'Content-Type': 'application/json', 'Content-Length': dados.length } : {}),
         }, (res) => {
             let texto = '';
             res.setEncoding('utf8');
             res.on('data', (c) => { texto += c; });
             res.on('end', () => {
-                if (res.statusCode >= 400) return reject(new Error(`HTTP ${res.statusCode}: ${texto.slice(0, 200)}`));
+                if (res.statusCode >= 400) {
+                    // A mensagem do servidor é escrita PARA o agente ("tema X
+                    // não existe, os temas são..."). Envolver em "HTTP 400:
+                    // {json}" só afasta a lição do olho dele.
+                    let motivo = texto.slice(0, 400);
+                    let corpoErro = null;
+                    try {
+                        corpoErro = JSON.parse(texto);
+                        motivo = corpoErro.erro || motivo;
+                    } catch { /* texto cru serve */ }
+                    const erro = new Error(motivo);
+                    erro.corpo = corpoErro;
+                    // O código vem no objeto, e não mais embutido no texto:
+                    // quem trata 404 (comIdReal) precisa saber que é 404 sem
+                    // depender de a mensagem começar com "HTTP 404".
+                    erro.status = res.statusCode;
+                    return reject(erro);
+                }
                 try { resolve(JSON.parse(texto)); }
                 catch { resolve({ texto }); }
             });
@@ -264,7 +290,7 @@ async function comIdReal(id, fn) {
     try {
         return await fn();
     } catch (e) {
-        if (!/HTTP 404/.test(String(e && e.message))) throw e;
+        if (!(e && e.status === 404)) throw e;
         let existem = [];
         try { existem = (await pedir('GET', '/api/arquivos')).map((a) => a.id).slice(0, 8); } catch {}
         return {
@@ -277,20 +303,102 @@ async function comIdReal(id, fn) {
 
 const ler = (id) => comStudio(() => comIdReal(id, async () => ({ ok: true, arquivo: await pedir('GET', `/api/arquivos/${encodeURIComponent(id)}`) })));
 
+// Quando o documento tem narração, o servidor começa a baixar a voz neural
+// sozinho. São ~90 MB, e o usuário merece saber por que o primeiro vídeo sai
+// com uma voz e o próximo com outra — melhor ele ouvir isso do agente do que
+// achar que o programa está inconstante.
+async function avisoDaVoz(doc) {
+    const temNarracao = !!(doc && (doc.narracao
+        || (doc.cenas || []).some((c) => c && typeof c.narracao === 'string' && c.narracao.trim())));
+    if (!temNarracao) return null;
+    try {
+        const s = await pedir('GET', '/api/voz/status', null, 3000);
+        if (s && s.piper && !s.piper.pronta && s.piper.suportado) {
+            return 'A voz neural (offline, ilimitada) está sendo baixada agora — ~90 MB, uma vez só. '
+                + 'Até terminar a narração sai por uma voz de reserva, mais simples. Diga isso ao usuário.';
+        }
+    } catch { /* status é enfeite; não pode atrapalhar a criação */ }
+    return null;
+}
+
 const criar = ({ ferramenta, titulo, doc }) => comStudio(async () => {
     if (!ferramenta) return { ok: false, error: 'Diga a ferramenta: prisma, tela, prosa, grade, corte ou traco.' };
     if (!doc) return { ok: false, error: 'Falta o doc. Leia a spec com studio_spec antes de criar.' };
     const r = await pedir('POST', '/api/arquivos', { ferramenta, titulo: titulo || 'Sem título', doc });
-    return { ok: true, ...r };
+    const saida = { ok: true, ...r };
+    const voz = await avisoDaVoz(doc);
+    if (voz) saida.voz = voz;
+    return saida;
 });
 
+// O que o agente recebe de volta depois de mexer num arquivo. Devolver o
+// documento inteiro era caro e inútil: um vídeo de oito cenas volta como
+// milhares de tokens que ele acabou de escrever. O que ele precisa saber é
+// que gravou, quantas peças ficaram e como voltar atrás.
+const resumoDoArquivo = (r) => {
+    const doc = r.doc || {};
+    const pecas = (doc.cenas || doc.blocos || doc.abas || []).length;
+    return {
+        id: r.id, titulo: r.titulo, ferramenta: r.ferramenta,
+        pecas, tema: doc.tema,
+        temNarracao: !!(doc.narracao || (doc.cenas || []).some((c) => c && c.narracao)),
+        temTrilha: !!doc.trilha,
+        // O mesmo link de sempre: ajustar não cria peça nova, e é isso que o
+        // agente precisa dizer ao usuário no finish.
+        // localhost, e não 127.0.0.1, para bater com o link que studio_criar
+        // já deu ao usuário — dois endereços para a mesma peça confundem.
+        ver: `http://localhost:${PORTA}/v/${r.id}`,
+    };
+};
+
 const atualizar = ({ id, titulo, doc }) => comStudio(() => comIdReal(id, async () => {
     if (!id) return { ok: false, error: 'Falta o id do arquivo.' };
     const corpo = {};
     if (titulo != null) corpo.titulo = titulo;
     if (doc != null) corpo.doc = doc;
     const r = await pedir('PUT', `/api/arquivos/${encodeURIComponent(id)}`, corpo);
-    return { ok: true, ...r };
+    const saida = { ok: true, ...resumoDoArquivo(r) };
+    // A mescla é a razão de isto não ter destruído nada: as chaves que você
+    // não mandou continuam lá. Dizer isso evita a rodada seguinte em que o
+    // agente "reconstrói" o que nunca se perdeu.
+    saida.nota = 'Só as chaves que você mandou mudaram; o resto do documento continua como estava.';
+    if (r.versao_anterior) saida.desfazer = `studio_versoes com id "${r.id}" e restaurar "${r.versao_anterior}" volta ao estado anterior.`;
+    return saida;
+}));
+
+// ── Histórico ────────────────────────────────────────────────────────────
+// Existe porque uma vez não existiu: um ajuste apagou oito cenas de trabalho
+// e não havia de onde tirar de volta.
+const versoesDe = ({ id, restaurar }) => comStudio(() => comIdReal(id, async () => {
+    if (!id) return { ok: false, error: 'Falta o id do arquivo.' };
+    if (restaurar) {
+        const alvo = restaurar === true || restaurar === 'anterior' ? null : String(restaurar);
+        try {
+            const r = await pedir('POST', `/api/arquivos/${encodeURIComponent(id)}/restaurar`,
+                alvo ? { versao: alvo } : {});
+            return { ok: true, ...r };
+        } catch (e) {
+            // 404 aqui pode ser o arquivo OU a versão. Quando o servidor manda
+            // a lista junto, o arquivo existe e quem não existe é a versão —
+            // deixar comIdReal dizer "o id não existe" mandaria o agente
+            // caçar um problema que não é o dele.
+            if (e && e.status === 404 && e.corpo && Array.isArray(e.corpo.versoes)) {
+                return {
+                    ok: false,
+                    error: `A versão "${alvo}" não existe.`,
+                    versoes: e.corpo.versoes,
+                    comoCorrigir: 'Use um "versao" desta lista, copiado LITERALMENTE, ou "anterior" para desfazer a última mudança.',
+                };
+            }
+            throw e;
+        }
+    }
+    const r = await pedir('GET', `/api/arquivos/${encodeURIComponent(id)}/versoes`);
+    return {
+        ok: true,
+        versoes: r.versoes || [],
+        comoVoltar: 'Para voltar, chame de novo com restaurar: "<versao>" — ou restaurar: "anterior" para desfazer a última mudança.',
+    };
 }));
 
 // ── Mídia: a imagem de fundo e a música do usuário ───────────────────────
@@ -338,6 +446,6 @@ const midiaEnviar = ({ arquivo, nome }) => comStudio(async () => {
 module.exports = {
     BASE, PORTA, CASA,
     garantirNoAr, estaNoAr, prepararCasa, pythonCmd,
-    manual, ferramentas, spec, listar, ler, criar, atualizar,
+    manual, ferramentas, spec, listar, ler, criar, atualizar, versoesDe,
     midiaListar, midiaEnviar,
 };

package/lib/tools.js

@@ -535,6 +535,8 @@ async function despachar(name, args, ctx) {
                 return studio.ler(args.id);
             case 'studio_atualizar':
                 return studio.atualizar({ id: args.id, titulo: args.titulo, doc: args.doc });
+            case 'studio_versoes':
+                return studio.versoesDe({ id: args.id, restaurar: args.restaurar });
             case 'studio_listar':
                 return studio.listar();
             case 'studio_midia':

package/lib/ui.js

@@ -278,6 +278,7 @@ function actionHeader(name, args) {
         desktop_double_click:'Desktop·2click', desktop_open_app:'Desktop·app',
         studio_manual:'Estúdio·manual', studio_spec:'Estúdio·spec', studio_criar:'Estúdio·criar',
         studio_ler:'Estúdio·ler', studio_atualizar:'Estúdio·ajustar', studio_listar:'Estúdio·lista',
+        studio_versoes:'Estúdio·histórico',
         desktop_windows:'Desktop·janelas', desktop_focus:'Desktop·foco',
         desktop_elements:'Desktop·elementos', desktop_click_element:'Desktop·click',
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "8.11.1",
+  "version": "8.12.0",
   "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modelos grátis. Cria arquivos, roda comandos, controla navegador e desktop: abre apps, clica em botões e ícones pelo nome, digita e usa atalhos.",
   "main": "bin/primocode.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/primocode.js",
-    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/studio-spec.test.js"
+    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/studio-spec.test.js && node test/studio-versoes.test.js && node test/voz.test.js"
   },
   "engines": {
     "node": ">=18.17.0"

package/studio/ferramentas/00-protocolo.md

@@ -106,6 +106,19 @@ A resposta do POST traz:
 
 ## Iterar
 
-Para ajustar algo que o usuário pediu depois, faça `GET` do arquivo, altere só o que
-mudou e `PUT` de volta. Não recrie do zero — o link já está com o usuário e deve
+Para ajustar algo que o usuário pediu depois, mande no `PUT` **só as chaves que
+mudam**. Elas entram por cima do documento; o que você não citou fica como estava.
+Trocar o tema de um vídeo pronto é `{"doc":{"tema":"papel"}}` — as cenas, a narração
+e a trilha continuam lá. Não recrie do zero: o link já está com o usuário e deve
 continuar valendo.
+
+Se quiser mesmo jogar fora o documento inteiro e pôr outro no lugar, mande
+`{"doc": {...}, "substituir": true}`. Sem essa chave, nada é apagado.
+
+| Método | Rota | O que faz |
+|---|---|---|
+| `GET` | `/api/arquivos/<id>/versoes` | as últimas 20 versões, a mais nova primeiro |
+| `POST` | `/api/arquivos/<id>/restaurar` | `{versao?}` — sem `versao`, desfaz a última mudança |
+
+Toda gravação guarda a versão anterior antes de trocar. Estragou um arquivo pronto?
+`POST /api/arquivos/<id>/restaurar` traz de volta.

package/studio/ferramentas/01-modelos.md

@@ -136,6 +136,8 @@ Sem declarar nada, os elementos já entram em cascata na ordem em que aparecem.
 
 `meia-noite` `claro` `papel` `neon` `brasa` `floresta` `retro` `oceano` `doce` `mono`
 
+São esses dez, e só. Nome fora da lista é recusado: escuro é `meia-noite`, não
+`noite`. Cor de marca não vira tema — ela entra em `cor` nos elementos.
 Vale no documento ou por cena. Uma cena com tema diferente no meio cria respiro —
 use uma vez, não cinco.
 

package/studio/ferramentas/corte.md

@@ -138,12 +138,28 @@ na hora de tocar — sem gravar nada, sem arquivo:
   "elementos": [ ... ] }
 ```
 
-Ajuste da voz no **documento** (opcional):
+Escolha da voz no **documento** (opcional):
 
 ```json
-"voz": { "velocidade": 1, "tom": 1, "volume": 1, "lang": "pt-BR" }
+"voz": { "voz": "jeff", "grave": true, "velocidade": 1 }
 ```
 
+A síntese é neural e roda na máquina do usuário — offline, sem limite. As
+vozes pt-BR, com a frequência de cada uma medida (menor = mais grave):
+
+| id | timbre | Hz |
+|---|---|---|
+| `jeff` | grave, de locução — **é a padrão** | 139 |
+| `cadu` | grave, mais solta | 140 |
+| `edresson` | média, mais leve de baixar | 151 |
+| `faber` | clara, de leitura | 167 |
+| `tugao` | português de Portugal | — |
+
+`"grave": true` abaixa mais uns 10% — é o registro de abertura de vídeo. Não
+há voz feminina em pt-BR neste motor; se pedirem uma, diga isso em vez de
+prometer. Na primeira vez o motor é baixado sozinho (~90 MB); enquanto isso
+a narração sai por uma voz de reserva, e o vídeo nunca fica mudo.
+
 Regras que fazem diferença:
 
 - **Escreva para o ouvido, não para o olho.** A narração NÃO repete o texto da