primocode 8.11.1 → 8.11.2

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

@@ -112,13 +112,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 +287,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 {
@@ -284,13 +307,74 @@ const criar = ({ ferramenta, titulo, doc }) => comStudio(async () => {
     return { ok: true, ...r };
 });
 
+// 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 +422,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.11.2",
   "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"
   },
   "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/server.py

@@ -149,6 +149,106 @@ def gravar(arq):
     return arq
 
 
+# ------------------------------------------------------------------ versões --
+#
+# Um pedido de ajuste apagou o trabalho de um usuário: ele tinha um vídeo de
+# oito cenas, com narração e trilha, pediu "aplique a identidade visual" e o
+# agente mandou um PUT com doc={"tema":"..."}. O handler trocava o documento
+# INTEIRO pelo que chegou — as oito cenas, a narração e a trilha viraram um
+# documento de uma chave só. Não havia como voltar.
+#
+# Daí saíram duas defesas. `mesclar` faz o pedido parcial ser parcial de
+# verdade, que é o conserto. Este histórico é o que sobra quando o conserto
+# não basta: guarda o estado anterior a cada gravação, para que sobrescrever
+# nunca mais seja definitivo. Nada aqui apaga o arquivo vivo; o pior caso é
+# ocupar disco, e vinte versões de um documento de texto não dão um megabyte.
+
+VERSOES = os.path.join(ARQUIVOS, ".versoes")
+MAX_VERSOES = 20
+
+
+_seq_versao = 0
+
+
+def guardar_versao(arq):
+    """Copia o estado atual para .versoes/<id>/<carimbo>.json antes de trocar.
+
+    O carimbo é ordenável como texto, e por isso precisa de milissegundo: o
+    editor do navegador salva a cada 600 ms, e duas versões do mesmo segundo
+    desempatadas por sorteio fariam "desfaz a última mudança" desfazer a
+    penúltima. O contador no fim resolve o empate que sobra."""
+    global _seq_versao
+    try:
+        pasta = os.path.join(VERSOES, arq["id"])
+        os.makedirs(pasta, exist_ok=True)
+        _seq_versao = (_seq_versao + 1) % 10000
+        agora = datetime.now(timezone.utc)
+        carimbo = "%s%03d-%04d" % (agora.strftime("%Y%m%dT%H%M%S"),
+                                   agora.microsecond // 1000, _seq_versao)
+        with open(os.path.join(pasta, carimbo + ".json"), "w", encoding="utf-8") as fh:
+            json.dump(arq, fh, ensure_ascii=False)
+        antigas = sorted(n for n in os.listdir(pasta) if n.endswith(".json"))
+        for velha in antigas[:-MAX_VERSOES]:
+            os.remove(os.path.join(pasta, velha))
+        return carimbo
+    except Exception:
+        # Histórico é rede de proteção, não requisito: se o disco recusar, a
+        # gravação principal segue. Falhar aqui seria trocar perder o passado
+        # por perder o presente.
+        return None
+
+
+def versoes(arq_id):
+    """As versões guardadas, da mais nova para a mais velha."""
+    if not caminho(arq_id):
+        return []
+    pasta = os.path.join(VERSOES, arq_id)
+    if not os.path.isdir(pasta):
+        return []
+    saida = []
+    for nome in sorted(os.listdir(pasta), reverse=True):
+        if not nome.endswith(".json"):
+            continue
+        try:
+            with open(os.path.join(pasta, nome), encoding="utf-8") as fh:
+                a = json.load(fh)
+        except Exception:
+            continue
+        doc = a.get("doc") or {}
+        saida.append({
+            "versao": nome[:-5],
+            "titulo": a.get("titulo", ""),
+            "pecas": len(doc.get("cenas") or doc.get("blocos") or doc.get("abas") or []),
+            "atualizado": a.get("atualizado", ""),
+        })
+    return saida
+
+
+def ler_versao(arq_id, versao):
+    if not caminho(arq_id) or not re.fullmatch(r"[0-9A-Za-z\-]{1,40}", versao or ""):
+        return None
+    c = os.path.join(VERSOES, arq_id, versao + ".json")
+    if not os.path.exists(c):
+        return None
+    with open(c, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def mesclar(antigo, novo):
+    """O documento novo por cima do antigo, chave a chave.
+
+    Quem só quer trocar o tema manda {"tema":"papel"} — e é a coisa natural a
+    mandar, porque o pedido era esse. Trocar o documento inteiro por isso
+    apagava cenas, narração e trilha. Mesclando, o que não foi citado fica
+    onde estava e o que foi citado vale: mandar cenas novas ainda troca as
+    cenas, que é o ajuste de verdade."""
+    if not isinstance(antigo, dict) or not isinstance(novo, dict):
+        return novo
+    saida = dict(antigo)
+    saida.update(novo)
+    return saida
+
+
 def listar():
     saida = []
     for nome in os.listdir(ARQUIVOS):
@@ -311,6 +411,22 @@ def _texto_do_doc(doc):
     return " ".join(pedacos).lower()
 
 
+# Os temas que o render.css de fato define. Fora desta lista não existe cor
+# nenhuma — foi o que aconteceu com "noite", que passou como se fosse tema.
+TEMAS_VALIDOS = {"claro", "meia-noite", "papel", "neon", "brasa", "floresta",
+                 "retro", "oceano", "doce", "mono"}
+
+
+def _tema_invalido(tema, onde=""):
+    if tema is None:
+        return None
+    if isinstance(tema, str) and tema in TEMAS_VALIDOS:
+        return None
+    return ('tema %r%s não existe — a peça sairia sem cor nenhuma. Os temas são: %s. '
+            'Para escuro use "meia-noite".'
+            % (tema, onde, ", ".join(sorted(TEMAS_VALIDOS))))
+
+
 def validar_doc(modelo, doc):
     """None quando o doc serve; senão, a frase que ENSINA o formato certo.
 
@@ -332,6 +448,13 @@ def validar_doc(modelo, doc):
     TIPOS_VALIDOS = {"texto", "lista", "cartoes", "numeros", "tabela", "codigo",
                      "citacao", "forma", "imagem", "icone", "grafico", "no", "conector"}
 
+    # Tema inventado tinha o mesmo destino silencioso do tipo inventado: o CSS
+    # não casa com [data-tema="noite"], nenhuma cor é definida e a peça sai
+    # sem identidade nenhuma. Recusar aqui devolve a lista certa ao agente.
+    problema = _tema_invalido(doc.get("tema"))
+    if problema:
+        return problema
+
     if modelo == "cena":
         cenas = doc.get("cenas")
         if not isinstance(cenas, list) or not cenas:
@@ -345,6 +468,9 @@ def validar_doc(modelo, doc):
             if not isinstance(els, list) or not els:
                 return ('cena %d sem "elementos". Cada cena precisa de elementos:[...] — '
                         'ex.: {"tipo":"texto","texto":"..."}. Leia studio_spec e refaça.' % (i + 1))
+            problema = _tema_invalido(c.get("tema"), " (cena %d)" % (i + 1))
+            if problema:
+                return problema
             dur = c.get("duracao")
             if dur is not None and not isinstance(dur, (int, float)):
                 return ('cena %d com "duracao" que não é número (veio %r). Use número de segundos: '
@@ -600,6 +726,12 @@ class Handler(SimpleHTTPRequestHandler):
             a = ler(m.group(1))
             return self.js(a) if a else self.js({"erro": "não encontrado"}, 404)
 
+        m = re.fullmatch(r"/api/arquivos/([^/]+)/versoes", p)
+        if m:
+            if not ler(m.group(1)):
+                return self.js({"erro": "não encontrado"}, 404)
+            return self.js({"versoes": versoes(m.group(1))})
+
         m = re.fullmatch(r"/api/arquivos/([^/]+)/export", p)
         if m:
             a = ler(m.group(1))
@@ -838,6 +970,32 @@ class Handler(SimpleHTTPRequestHandler):
             threading.Thread(target=lambda: (time.sleep(0.3), os._exit(0)), daemon=True).start()
             return
 
+        m = re.fullmatch(r"/api/arquivos/([^/]+)/restaurar", rota)
+        if m:
+            a = ler(m.group(1))
+            if not a:
+                return self.js({"erro": "não encontrado"}, 404)
+            pedido = self.corpo()
+            disponiveis = versoes(m.group(1))
+            # Sem versão dita, a anterior — que é o que "desfaz" quer dizer
+            # quando alguém acabou de estragar o arquivo.
+            alvo = pedido.get("versao") or (disponiveis[0]["versao"] if disponiveis else None)
+            velha = ler_versao(m.group(1), alvo) if alvo else None
+            if not velha:
+                return self.js({"erro": "versão não encontrada",
+                                "versoes": disponiveis}, 404)
+            # Restaurar também guarda versão: desfazer o desfazer tem de valer.
+            guardar_versao(a)
+            a["titulo"] = velha.get("titulo", a.get("titulo"))
+            a["doc"] = velha.get("doc") or a.get("doc")
+            gravar(a)
+            doc = a.get("doc") or {}
+            return self.js({
+                "ok": True, "id": a["id"], "restaurado": alvo,
+                "titulo": a.get("titulo"),
+                "pecas": len(doc.get("cenas") or doc.get("blocos") or doc.get("abas") or []),
+            })
+
         if rota == "/api/arquivos":
             try:
                 a = criar(self.corpo())
@@ -873,10 +1031,36 @@ class Handler(SimpleHTTPRequestHandler):
             return self.js({"erro": "titulo precisa ser texto"}, 400)
         if "doc" in dados and dados["doc"] is not None and not isinstance(dados["doc"], dict):
             return self.js({"erro": "doc precisa ser um objeto"}, 400)
-        for chave in ("titulo", "doc"):
-            if chave in dados:
-                a[chave] = dados[chave]
-        return self.js(gravar(a))
+
+        antes = a.get("doc") or {}
+        novo = a.get("doc")
+        if "doc" in dados and dados["doc"] is not None:
+            # Mesclar em vez de trocar. Era aqui que o trabalho sumia: um doc
+            # parcial substituía o inteiro. Quem quiser mesmo jogar fora o que
+            # existe manda "substituir": true e assume.
+            novo = dados["doc"] if dados.get("substituir") else mesclar(antes, dados["doc"])
+
+            # O agente precisa da validação: é a única forma de ele saber que
+            # errou o formato. O editor do navegador, não — ali há uma pessoa
+            # digitando, e uma cena momentaneamente vazia no meio da edição não
+            # pode fazer o salvamento falhar calado.
+            if self.headers.get("X-Primo-Agente"):
+                problema = validar_doc(
+                    POR_SLUG.get(a.get("ferramenta"), {}).get("modelo"), novo)
+                if problema:
+                    return self.js({"erro": problema}, 400)
+
+        versao = guardar_versao(a)
+        if "titulo" in dados:
+            a["titulo"] = dados["titulo"]
+        if "doc" in dados:
+            a["doc"] = novo
+        salvo = gravar(a)
+        if versao:
+            # O agente vê isto no resultado da tool: se ele estragou algo, o
+            # caminho de volta está na resposta, não numa doc que ele não leu.
+            salvo = dict(salvo, versao_anterior=versao)
+        return self.js(salvo)
 
     @seguro
     def do_DELETE(self):