sagadeck 1.7.1 → 1.9.0

package/README.md

@@ -16,7 +16,7 @@ Ele vem com 11 temas (incluindo prata limpo e respirável, artesanal desenhado
 ```bash
 npm install -g sagadeck
 ```
-Requer **Node.js 18+** e **Chrome ou Edge** instalados (o PDF, o PNG e as conferências visuais usam o navegador).
+Requer **Node.js 22.13+** e **Chrome ou Edge** instalados (o PDF, o PNG e as conferências visuais usam o navegador).
 É tudo Node: não precisa de Python. (O pacote do PyPI parou na 1.5.0.)
 
 ## Comece aqui
@@ -150,6 +150,48 @@ ilustrar" e `--no-images` proíbe. Imagens só são geradas para os slides que a
 
 Todo YAML vindo do LLM é validado (renderiza cada slide); se falhar, o erro volta para o LLM corrigir (até 3 tentativas). Decks gerados passam por uma rodada de enxugamento quando o fiscal anti-sono reclamaria.
 
+## Mapa (opcional)
+
+O slide de mapa (`layout: map`) mostra pontos, linhas e áreas sobre um mapa ao vivo: sensores, medidores, unidades de
+atendimento, cinemas, trajetos, bairros, o que for. Os dados vêm de uma planilha do projeto (CSV com latitude e
+longitude, ou só com o endereço) ou de arquivos GeoJSON, GPX e KML. **Nada aqui é obrigatório**: quem não usa mapa
+não precisa configurar coisa nenhuma, e o sagadeck não pede nada à internet por causa dele.
+
+**Sem chave nenhuma, já funciona** com os serviços públicos gratuitos do OpenStreetMap:
+
+| serviço | para quê | padrão (sem configurar) |
+|---|---|---|
+| mapa de fundo | as ruas por baixo das camadas | OpenStreetMap |
+| fundos claro e escuro | dados sobre terra e mar, sem a linha de fronteira no mar | OpenFreeMap (vetorial) |
+| endereço e coordenada | **Achar coordenadas** de uma planilha só com endereço | Nominatim (1 endereço por segundo) |
+| busca de lugares | achar cinemas, escolas, unidades de saúde… pelo nome do tipo | Overpass |
+| rotas | "seguir as ruas" ao desenhar, distância e tempo | OSRM (servidor de demonstração) |
+
+**Chave opcional: OpenRouteService**, para rotas a pé, de carro e de bicicleta e para a **área alcançável em X
+minutos**. É gratuita:
+1. Crie a conta em [openrouteservice.org](https://openrouteservice.org) e confirme o e-mail.
+2. No painel, gere um token do plano gratuito (Standard).
+3. No Studio, **Configurar mapa** (no alto da biblioteca, ou no formulário do slide de mapa) › Rotas › **Usar o
+   OpenRouteService**, cole a chave e clique em **Testar**.
+
+A configuração fica só nesta máquina, em `~/.sagadeck/mapa.json` (como a da IA); a chave nunca volta inteira para a
+página e nunca vai para dentro da apresentação. Também vale pôr a chave numa variável de ambiente e indicar o nome dela
+em `keyEnv` (no servidor, por exemplo):
+
+```json
+{ "rotas": { "provedor": "openrouteservice", "url": "https://api.openrouteservice.org", "keyEnv": "OPENROUTESERVICE_API_KEY" } }
+```
+
+Os serviços públicos têm regras de uso que o sagadeck respeita sozinho: identifica os pedidos de dados, mostra as
+atribuições do mapa, busca um endereço por segundo, guarda o que já achou e nunca baixa mapa fora da tela. O
+[OpenFreeMap](https://openfreemap.org/) permite uso comercial e não exige cadastro ou chave. Os demais serviços
+de demonstração servem para uso leve; para uma demanda maior, configure um provedor apropriado em **Configurar mapa**.
+Os fundos claro e escuro também aceitam um estilo vetorial (JSON) ou tiles de um servidor próprio. Antes de mandar os endereços de uma planilha sua para um
+serviço de fora, o sagadeck pergunta.
+
+Se a rede barrar um serviço (autorização negada, proxy, bloqueio), o sagadeck faz **uma tentativa e para**: avisa
+na tela, as camadas continuam desenhadas e nada é tentado de novo até você clicar em **Tentar de novo**.
+
 ## Desenvolvimento
 
 ```bash
@@ -192,6 +234,13 @@ formato avisa para atualizar o sagadeck. Se um filtro de e-mail barrar a extens
 `sagadeck studio` sem arquivo abre a biblioteca: suas apresentações organizadas em tópicos, com capa, busca,
 lixeira (30 dias; o prazo se muda em Preferências) e o menu **⋯** de cada cartão (apresentar, renomear, duplicar, mover, baixar tudo/.sagadeck/PPTX/PDF).
 
+Na lateral, **Demos oficiais** (com cadeado) guarda as apresentações do próprio SagaDeck, só leitura. Primeiro, as
+demos de um assunto só, curtas: **Mapas** (mostrar, calcular e editar), **Programação** (código destacado e guiado,
+código que a plateia roda, algoritmo animado, Git a dois, diagramas) e **APIs com curl** (a anatomia de um curl e
+chamadas ao vivo com o curl para copiar, rodando na API de mentira do Studio). Depois, o **Conheça o SagaDeck** (um
+slide por recurso, cada um com a frase para pedir à IA) e as outras demos de recursos. Elas abrem em prévia, sem criar arquivo; editar cria uma cópia sua em Modelos. O Conheça o SagaDeck
+aparece também como o primeiro cartão de Recentes e Todas.
+
 **Nova apresentação** tem três caminhos: *Descrever com IA* (o assunto, quanto tempo você tem, que vira o número de
 slides, o estilo e, se quiser, material de apoio: PDF, Word, PowerPoint, Excel ou um link), *A partir de um arquivo
 ou link* (o mesmo, começando pelo anexo) e *Modelo pronto* (coleções, estilos, demonstrações e exemplos, com filtro).
@@ -244,9 +293,11 @@ token nunca vai para a página.
 
 Para ver funcionando sem configurar nada:
 
-- **Biblioteca → Nova → Exemplo: aula de APIs ao vivo.** Cria um deck com um slide de cada tipo, que roda no
-  ambiente **ENSAIO**: uma API de mentira que o Studio sobe sozinho (sem VPN, sem chave). Apresente e clique
-  em **Executar**. (`sagadeck ensaio-api` faz o mesmo pela linha de comando.) O deck também traz um slide
+- **Demos oficiais → APIs com curl.** As chamadas mais comuns (corpo, consulta na URL, token, polling, streaming),
+  cada uma com o curl, rodando no ambiente **ENSAIO**: uma API de mentira que o Studio sobe sozinho (sem VPN, sem
+  chave). Apresente e clique em **Executar**.
+- **`sagadeck ensaio-api`.** O ensaio completo, com um slide de cada tipo (upload, OCR, embeddings, voz, tempo
+  real), no mesmo ambiente ENSAIO. O deck também traz um slide
   **OpenRouter (real)** com `nvidia/nemotron-3-super-120b-a12b:free`. Para usá-lo, defina `OPENROUTER_API_KEY` no
   processo que inicia o Studio e escolha o ambiente **OPENROUTER** no selo do slide. A chave fica fora do
   deck; no PowerShell, por exemplo, defina `$env:OPENROUTER_API_KEY = "sua-chave"` antes de iniciar o

package/SKILL.md

@@ -11,7 +11,7 @@ O sagadeck gera apresentações profissionais a partir de um arquivo YAML, ofere
 
 Quando a pessoa pede para instalar o sagadeck e deixar pronto:
 
-1. `npm install -g sagadeck` (Node 18+; não precisa de Python).
+1. `npm install -g sagadeck` (Node 22.13+; não precisa de Python).
 2. `sagadeck studio`: o navegador abre sozinho em **http://127.0.0.1:3517** (é também a primeira linha que o
    comando escreve; `--sem-navegador` não abre). **O Studio é a interface do sagadeck**: biblioteca, editor e chat com
    IA. O terminal fica aberto enquanto ela usa.
@@ -20,7 +20,12 @@ Quando a pessoa pede para instalar o sagadeck e deixar pronto:
 4. Para a IA, mostre onde configurar: **Configurar IA** no alto da biblioteca (ou **IA desligada** no editor):
    **Usar a recomendação** (OpenRouter com modelos que funcionam), a chave, Testar e Salvar. A configuração fica em `~/.sagadeck/ia.json`; nunca grave a chave no código nem
    na pasta das apresentações.
-5. As apresentações moram na biblioteca (`SAGADECK_HOME`, senão Documentos\sagadeck no Windows e `~/sagadeck` fora
+5. **Para saber o que de IA funciona**, rode `sagadeck ia-check` (ou a ferramenta `sagadeck_ia_check` do MCP) antes de
+   prometer qualquer recurso de IA: testa texto, visão, geração de imagem, pesquisa e vídeo com chamadas de verdade, em
+   paralelo, em segundos. Cada recurso sai `OK`, `FALHOU` (com o motivo), `SEM CONFIG` ou, no vídeo, `SEM PROVA`: por
+   padrão o vídeo não é gerado (é cobrado); só `--video-real` prova que funciona, e só rode quando a pessoa pedir.
+   `--json` para ler a saída; o comando sai com código 1 se algo falhou.
+6. As apresentações moram na biblioteca (`SAGADECK_HOME`, senão Documentos\sagadeck no Windows e `~/sagadeck` fora
    dele). Não crie decks em outra pasta.
 
 ## Comandos Disponíveis
@@ -30,6 +35,7 @@ Quando a pessoa pede para instalar o sagadeck e deixar pronto:
 | `sagadeck studio [deck.yaml] [--port=3517]` | **Abre o estúdio web estilo PowerPoint** com canvas visual 16:9, edição WYSIWYG direta, detector de sobreposição em tempo real e **chat lateral com IA**. |
 | `sagadeck autofix <deck.yaml>` | **Auto-cura do layout**: detecta e repara automaticamente sobreposição entre elementos, elementos fora das margens seguras (120px) e excesso de texto. |
 | `sagadeck search "<termo>"` | **Pesquisa web sem bloqueio (DuckDuckGo)**: busca dados reais, números e referências confiáveis para enriquecer os slides. |
+| `sagadeck ia-check [--rapido] [--so=texto,visao,imagem,pesquisa,video] [--video-real] [--json]` | **Testa a IA configurada sem tela**: cada recurso com uma chamada de verdade, todos ao mesmo tempo; `--rapido` pula imagem e vídeo; `--video-real` gera um clipe curto (cobrado). Código de saída 1 se algo falhou |
 | `sagadeck mcp` | **Servidor MCP**: expõe ferramentas padronizadas (JSON-RPC) para IDEs agênticos criarem, lerem, pesquisarem, fiscalizarem e editarem decks. |
 | `sagadeck new "<nome>" [--topic=T] [--theme=prata]` | cria um deck de exemplo na biblioteca |
 | `sagadeck build deck.yaml` | compila `deck.html` standalone (abre no navegador; tecla P = modo apresentador) |
@@ -107,6 +113,7 @@ Ferramentas disponíveis no MCP:
 - `sagadeck_autofix_deck`: executa a auto-cura geométrica no arquivo YAML.
 - `sagadeck_build_html`: compila o arquivo `.html` interativo.
 - `sagadeck_launch_studio`: abre o SagaDeck Studio na web.
+- `sagadeck_ia_check`: testa a IA configurada (texto, visão, imagem, pesquisa, vídeo), em paralelo, e diz o que funciona.
 
 ### 2. Via Linha de Comando (CLI)
 O agente no terminal deve seguir o fluxo:
@@ -151,6 +158,6 @@ Para apresentações de alto impacto sem "muralhas de texto":
 
 ## Recursos recentes para autoria por IA
 
-Consulte `docs/REFERENCIA.md` para os contratos atuais de `science` (KaTeX, até cinco equações, Plotly 2D/3D), `scenography` (texto integrado ao cenário, estático), `spotlight`, `codewalk` e `api`. Para criar apresentações autonomamente, a IA precisa desta referência, do briefing, do material autorizado e das imagens; acesso ao banco por si só não transmite o formato do SagaDeck. Use apenas endpoints/status reais fornecidos pela documentação interna, sem inventar detalhes. Configure credenciais no ambiente local; nunca dentro dos slides.
+Consulte `docs/REFERENCIA.md` para os contratos atuais de `science` (KaTeX, até cinco equações, Plotly 2D/3D), `spotlight`, `codewalk` e `api`. Para criar apresentações autonomamente, a IA precisa desta referência, do briefing, do material autorizado e das imagens; acesso ao banco por si só não transmite o formato do SagaDeck. Use apenas endpoints/status reais fornecidos pela documentação interna, sem inventar detalhes. Configure credenciais no ambiente local; nunca dentro dos slides.
 
 O Studio permite inserir e arrastar elementos e revisar uma imagem do slide com IA. Ajustes manuais `visualEdits` são específicos da estrutura renderizada: remova-os ao reconstruir um slide. Sempre confira o resultado renderizado; regras geométricas não garantem qualidade visual.

package/bin/sagadeck.js

@@ -76,6 +76,11 @@ const HELP = `sagadeck — YAML -> apresentação (HTML animado + PowerPoint edi
   sagadeck autofix <deck.yaml> [--out=pasta]   auto-corrige sobreposições, margens e excesso de texto no YAML
   sagadeck diff <a.yaml> <b.yaml> [--json]      o que entrou, saiu, mudou e andou entre dois decks (por uid)
   sagadeck enxugar <deck.yaml> [--fix]          palavras por slide contra o limite do material (--fix: excedente para as notas)
+  sagadeck ia-check [--rapido] [--so=texto,visao,imagem,pesquisa,video] [--video-real] [--json]
+                                   testa a IA configurada, sem tela: cada recurso com uma chamada de verdade, todos ao
+                                   mesmo tempo, cada resultado assim que chega. --rapido pula imagem e vídeo; vídeo, por
+                                   padrão, só confere chave e catálogo; --video-real gera um clipe curto (é cobrado).
+                                   Sai com erro se algo falhou (bom para agentes e CI); --json para máquina
   sagadeck mcp                                 inicia o servidor MCP para IDEs agênticos (Cursor, Claude Code, Cline)
   sagadeck watch <deck.yaml>                   recompila o HTML sempre que o YAML mudar
   sagadeck themes [--out=pasta]                gera uma vitrine com todos os temas
@@ -490,6 +495,24 @@ async function main() {
       }
       break;
     }
+    case "ia-check": case "testar-ia": {
+      const { iaCheck, CHECKS } = await import("../src/ai/ia-check.js");
+      const only = flags.so ? String(flags.so).split(",").map((x) => x.trim().normalize("NFD").replace(/[̀-ͯ]/g, "")).filter(Boolean) : null;
+      const bad = (only || []).filter((x) => !CHECKS[x]);
+      if (bad.length) { console.error(`Recurso desconhecido: ${bad.join(", ")}. Vale: ${Object.keys(CHECKS).join(", ")}`); process.exit(2); }
+      const json = !!flags.json, log = json ? (...a) => console.error(...a) : (...a) => console.log(...a);
+      const SELO = { ok: "OK        ", falhou: "FALHOU    ", nao_configurado: "SEM CONFIG", sem_prova: "SEM PROVA " };
+      const seg = (ms) => `${(ms / 1000).toFixed(1).replace(".", ",")} s`;
+      log(`Testando a IA em paralelo${flags["video-real"] ? " (vídeo: gera um clipe de verdade, é cobrado)" : ""}…`);
+      const rep = await iaCheck({ only, rapido: !!flags.rapido, videoReal: !!flags["video-real"], videoTimeoutS: Number(flags["video-prazo"] || 600),
+        onResult: (r) => log(`  ${SELO[r.status] || r.status}  ${r.nome.padEnd(18)} ${seg(r.ms).padStart(7)}  ${r.modelo ? r.modelo + " · " : ""}${r.detalhe || ""}${r.arquivo ? ` · ${r.arquivo}` : ""}`) });
+      const n = (st) => rep.resultados.filter((r) => r.status === st).length;
+      log(`${n("ok")} de ${rep.resultados.length} funcionando${n("falhou") ? `, ${n("falhou")} com falha` : ""}${n("nao_configurado") ? `, ${n("nao_configurado")} sem configuração` : ""}${n("sem_prova") ? `, ${n("sem_prova")} sem prova (use --video-real)` : ""} · ${seg(rep.ms)}`);
+      if (json) console.log(JSON.stringify(rep, null, 2));
+      // sai na hora: conexões que o provedor deixa abertas seguravam o processo por dezenas de segundos
+      process.stdout.write("", () => process.exit(rep.ok ? 0 : 1));
+      break;
+    }
     case "mcp": {
       const { runMCPServer } = await import("../src/mcp/server.js");
       runMCPServer();