sagadeck 1.2.0

package/bin/sagadeck.js

@@ -0,0 +1,511 @@
+#!/usr/bin/env node
+// sagadeck — gerador de apresentações.  Uso: sagadeck <comando> <deck.yaml> [opções]
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import { buildFile, loadSpec, buildHTML } from "../src/build.js";
+import { THEMES } from "../src/themes.js";
+import { listIcons } from "../src/figures/icons.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// templates: ../templates (repositório) ou ./templates (motor empacotado para o pip)
+const TEMPLATES = [path.join(HERE, "..", "templates"), path.join(HERE, "templates")].find((d) => fs.existsSync(d));
+const DOCS = [path.join(HERE, "..", "docs"), path.join(HERE, "docs")].find((d) => fs.existsSync(d));
+const SKILL = [path.join(HERE, "..", "SKILL.md"), path.join(HERE, "docs", "SKILL.md")].find((f) => fs.existsSync(f));
+const VERSION = (() => { for (const f of [path.join(HERE, "..", "package.json"), path.join(HERE, "package.json")]) { try { return JSON.parse(fs.readFileSync(f, "utf8")).version; } catch {} } return "?"; })();
+const [, , cmd, ...rawRest] = process.argv;
+const flags = {};
+const args = [];
+for (let i = 0; i < rawRest.length; i++) {
+  const item = rawRest[i];
+  if (item.startsWith("--")) {
+    const eqIdx = item.indexOf("=");
+    if (eqIdx !== -1) {
+      flags[item.slice(2, eqIdx)] = item.slice(eqIdx + 1);
+    } else {
+      const key = item.slice(2);
+      const next = rawRest[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    }
+  } else {
+    args.push(item);
+  }
+}
+
+const HELP = `sagadeck — YAML -> apresentação (HTML animado + PowerPoint editável + PDF + roteiro)
+
+  sagadeck new <nome> --prompt "briefing" [--slides=10] [--duration=20] [--theme=x]  deck inteiro escrito pelo LLM
+                                   (pesquisa na web quando o pedido precisa de informação recente ou de um artigo; --sem-pesquisa desliga)
+                                   (--duration dispensa --slides: ~1 slide a cada 1,5 min)
+                                   (imagens: peça no briefing; --images = "você decide onde ilustrar", --no-images = nenhuma)
+  sagadeck napkin <texto|arquivo> [-o deck.yaml] [--rules]  texto bruto -> slide visual (LLM se houver; --rules força as regras)
+  sagadeck imagens <deck.yaml>                 gera as imagens pedidas com image_prompt: no YAML (modelo de imagem)
+  sagadeck scaffold <nome> [--theme=prata] [--type=pitch|keynote|palestra]  gera esqueleto narrativo pronto (economiza 80% de tokens)
+  sagadeck new <nome> [--topic=T] [--theme=x]  cria um deck de exemplo NA BIBLIOTECA (<biblioteca>/<tópico>/<nome>/)
+  sagadeck build <deck.yaml>                   gera <deck>.html (abre no navegador; P = modo apresentador)
+  sagadeck check <deck.yaml>                   procura texto estourado, sobreposição, contraste, excesso de texto
+  sagadeck shots <deck.yaml> [--steps] [--only=3,5]  PNG de cada slide + folhas de contato (para revisar)
+  sagadeck pptx <deck.yaml> [--native-charts] [--sem-notas]  gera <deck>.pptx editável (com animações dos cliques e notas; --sem-notas tira as notas, para mandar a alguém)
+  sagadeck pdf <deck.yaml>                     gera <deck>.pdf (um slide por página)
+  sagadeck roteiro <deck.yaml>                 gera <deck> - roteiro.pdf (miniaturas + notas + tempos)
+  sagadeck estudo <deck.yaml> [--html]         gera <deck> - material de estudo.pdf (cada slide + texto de consulta)
+  sagadeck all <deck.yaml>                     build + check + pptx + pdf + roteiro
+  sagadeck studio [deck.yaml|x.sagadeck] [--port=3517] [--library=PASTA]  sem arquivo: abre a biblioteca; já aberto: usa o aberto
+                                   (PASTA padrão: SAGADECK_HOME ou ~/sagadeck); com arquivo: abre o editor dele
+                                   --host=0.0.0.0 abre para a rede (padrão: só esta máquina)
+                                   --multiuser: uma biblioteca por usuário, atrás de um proxy que envia X-Sagadeck-User
+                                   --agentes=naru,ana: no multiusuário, quem pode deixar a IA rodar comandos (padrão: ninguém)
+  sagadeck ensaio-api [--port=3000]            ensaio do slide "api": deck de exemplo contra uma API de mentira (sem VPN)
+                                   o deck fica na biblioteca (Sem tópico/Ensaio APIs de IA ao vivo); se já existir, reabre
+  sagadeck pack <deck.yaml> [saida.sagadeck]   a apresentação inteira num arquivo (YAML + imagens, CSS, widgets)
+  sagadeck unpack <x.sagadeck> [pasta]         extrai um .sagadeck (ou .zip) numa pasta
+  sagadeck importar <arquivo.pptx> [--topico=X] [--titulo=Y] [--sem-fotos]
+                                               traz um PowerPoint para a biblioteca, fiel ao original
+  sagadeck autofix <deck.yaml> [--out=pasta]   auto-corrige sobreposições, margens e excesso de texto no YAML
+  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
+  sagadeck icons [filtro]                      lista ícones disponíveis (2.100+)
+  sagadeck search <termo> [--limit=5]          pesquisa na web via DuckDuckGo (sem bloqueio) para enriquecer dados
+  sagadeck ref                                 imprime a referência completa do YAML (ótimo para dar a um LLM)
+  sagadeck skill                               imprime as instruções para agentes de IA
+  sagadeck --version
+
+Saídas vão para a pasta do YAML (ou --out=pasta).`;
+
+function paths(yamlFile) {
+  if (!yamlFile) { console.error("Informe o arquivo .yaml"); process.exit(1); }
+  const abs = path.resolve(yamlFile);
+  const out = flags.out ? path.resolve(flags.out) : path.dirname(abs);
+  const base = path.basename(abs).replace(/\.(ya?ml)$/i, "");
+  return { abs, out, base, html: path.join(out, `${base}.html`), pptx: path.join(out, `${base}.pptx`), pdf: path.join(out, `${base}.pdf`), roteiro: path.join(out, `${base} - roteiro.pdf`), shots: path.join(out, `${base}-revisao`), tmpShots: path.join(os.tmpdir(), `sagadeck-${base.replace(/[^\w-]+/g, "_")}`) };
+}
+
+function doBuild(p, quiet) {
+  const r = buildFile(p.abs, p.html);
+  if (!quiet) {
+    console.log(`✓ HTML: ${p.html}`);
+    console.log(`  ${r.meta.slides.length} slides · tema ${r.theme.name} · tempo planejado ${r.planned} min${r.spec.duration ? ` de ${r.spec.duration}` : ""}`);
+    if (r.warnings.length) { console.log("⚠ Avisos:"); r.warnings.forEach((w) => console.log("  - " + w)); }
+  }
+  return r;
+}
+
+async function doCheck(p) {
+  const { check } = await import("../src/export/shots.js");
+  const { report, errors } = await check(p.html);
+  if (errors.length) { console.log("✗ Erros de JavaScript:"); errors.forEach((e) => console.log("  - " + e)); }
+  if (!report.length) console.log("✓ check: nenhum problema de layout encontrado");
+  else {
+    console.log(`⚠ check: ${report.length} slide(s) com possíveis problemas`);
+    for (const r of report) for (const i of r.issues) console.log(`  slide ${r.slide}: ${i.kind}${i.px ? ` (${i.px}px)` : ""}${i.ratio ? ` (${i.ratio}:1)` : ""} — "${i.text}"`);
+  }
+  return report;
+}
+
+async function doShots(p, dir = p.shots) {
+  const { shots, contactSheet } = await import("../src/export/shots.js");
+  const only = flags.only ? String(flags.only).split(",").map(Number) : null;
+  const { files, errors } = await shots(p.html, dir, { steps: !!flags.steps, only });
+  const sheets = await contactSheet(files, dir);
+  console.log(`✓ ${files.length} imagens em ${dir}`);
+  sheets.forEach((s) => console.log(`  folha: ${s}`));
+  if (errors.length) errors.forEach((e) => console.log("  ✗ " + e));
+  return files;
+}
+
+async function main() {
+  switch (cmd) {
+    case "napkin":
+    case "visual": {
+      const input = args.join(" ").trim();
+      if (!input) {
+        console.error("Uso: sagadeck napkin <texto bruto ou arquivo.txt> [-o deck.yaml] [--theme=sinal]");
+        process.exit(1);
+      }
+      let content = input;
+      if (fs.existsSync(input)) {
+        content = fs.readFileSync(input, "utf8");
+      }
+      const { textToVisualSlide, napkinToYaml } = await import("../src/diagram/napkin.js");
+      const theme = flags.theme || "sinal";
+      const tone = flags.tone;
+      const title = flags.title;
+
+      // Com um LLM disponível (e sem --rules), o slide é escrito pela IA.
+      const { llmAvailable } = await import("../src/ai/llm.js");
+      if (!flags.rules && await llmAvailable()) {
+        const { textToSlide } = await import("../src/ai/deck-ai.js");
+        const YAML = (await import("yaml")).default;
+        const outPath = flags.o || flags.out;
+        const dir = outPath ? path.dirname(path.resolve(outPath)) : process.cwd();
+        const res = await textToSlide(content, { theme, tone, title, images: !!flags.images, imageOptions: { baseDir: dir } });
+        console.log(`✨ [Napkin · LLM] layout: ${res.detectedType.toUpperCase()}\n💡 ${res.rationale}\n`);
+        if (outPath) {
+          const target = path.resolve(outPath);
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, YAML.stringify({ title: title || "Diagrama", theme, slides: [res.slide] }, { indent: 2 }), "utf8");
+          console.log(`✓ Diagrama visual gerado em: ${target}`);
+        } else {
+          console.log(YAML.stringify(res.slide, { indent: 2 }));
+        }
+        break;
+      }
+
+      const outPath = flags.o || flags.out;
+      if (outPath) {
+        const target = path.resolve(outPath);
+        const yamlStr = napkinToYaml(content, { theme, tone, title });
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, yamlStr, "utf8");
+        console.log(`✓ Diagrama visual gerado com sucesso em: ${target}`);
+      } else {
+        const res = textToVisualSlide(content, { theme, tone, title });
+        console.log(`✨ [Napkin AI] Padrão detectado: ${res.detectedType.toUpperCase()} (confiança: ${Math.round(res.confidence * 100)}%)`);
+        console.log(`💡 Raciocínio: ${res.rationale}\n`);
+        const YAML = (await import("yaml")).default;
+        console.log(YAML.stringify(res.slide, { indent: 2 }));
+      }
+      break;
+    }
+    case "scaffold": {
+      // sempre na biblioteca (ver newDeckPath)
+      const { newDeckPath } = await import("../src/library.js");
+      const target = newDeckPath(args[0], { topic: typeof flags.topic === "string" ? flags.topic : undefined, title: typeof flags.title === "string" ? flags.title : undefined });
+      if (fs.existsSync(target) && !flags.force) {
+        console.error(`Erro: o arquivo ${target} já existe. Use --force para sobrescrever.`);
+        process.exit(1);
+      }
+      const { generateScaffold } = await import("../src/templates/scaffold.js");
+      const YAML = (await import("yaml")).default;
+      const theme = flags.theme || "prata";
+      const type = flags.type || "keynote";
+      const title = flags.title || (args[0] ? path.basename(args[0], path.extname(args[0])) : "Nova Apresentação");
+      const author = flags.author || "Seu Nome";
+      const spec = generateScaffold({ title, theme, type, author });
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, YAML.stringify(spec, { indent: 2 }), "utf8");
+      console.log(`✓ Esqueleto narrativo gerado em: ${target}`);
+      console.log(`  Tipo: ${type} · Tema: ${theme} · Slides: ${spec.slides.length}`);
+      console.log(`  Estrutura ideal (cover -> statement -> stats -> steps -> cards -> end) pronta para preenchimento.`);
+      break;
+    }
+    case "new": {
+      // sempre na biblioteca (ver newDeckPath): "sagadeck new Minha palestra" -> <biblioteca>/Sem tópico/Minha palestra/
+      const { newDeckPath } = await import("../src/library.js");
+      const target = newDeckPath(args[0], { topic: typeof flags.topic === "string" ? flags.topic : undefined, title: typeof flags.title === "string" ? flags.title : undefined });
+      if (fs.existsSync(target)) { console.error(`${target} já existe`); process.exit(1); }
+      if (flags.prompt || flags.briefing) {
+        // Deck inteiro escrito pelo LLM a partir de um briefing
+        let briefing = String(flags.prompt || flags.briefing);
+        if (fs.existsSync(briefing)) briefing = fs.readFileSync(briefing, "utf8");
+        if (flags.images === true) briefing += "\n\nImagens: você decide onde vale ilustrar com imagens geradas (não precisa ser em todos os slides).";
+        if (flags["no-images"]) briefing += "\n\nNão gere imagens.";
+        const { generateDeck, toYaml } = await import("../src/ai/deck-ai.js");
+        const { diagramCheck, closeSnapshots } = await import("../src/studio/snapshot.js");
+        const dir = path.dirname(target);
+        const { spec, images } = await generateDeck(briefing, {
+          drawCheck: diagramCheck, // diagramas: confere desenhando (se houver Chrome/Edge)
+          theme: typeof flags.theme === "string" ? flags.theme : undefined,
+          slides: Number(flags.slides) || undefined,
+          duration: Number(flags.duration) || undefined,
+          images: !flags["no-images"],
+          imageOptions: { baseDir: dir, assetsDir: path.join(dir, "imagens") },
+          research: flags["sem-pesquisa"] ? false : "auto", // a IA decide se pesquisa; as fontes ficam em contexto/pesquisa/
+          researchDir: dir,
+          onProgress: (m) => console.log(`  … ${m}`),
+        }).finally(closeSnapshots);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(target, toYaml(spec));
+        console.log(`✓ criado ${target} com IA: ${spec.slides.length} slides · tema ${spec.theme || "sinal"}`);
+        images.done.forEach((d) => console.log(`  🖼 ${path.relative(process.cwd(), d.file)}`));
+        images.failed.forEach((f) => console.log(`  ✗ imagem não gerada ("${f.prompt.slice(0, 50)}"): ${f.error}`));
+        console.log(`  próximo passo: sagadeck studio "${target}"  ou  sagadeck all "${target}"`);
+        break;
+      }
+      let t = fs.readFileSync(path.join(TEMPLATES, "exemplo.yaml"), "utf8");
+      if (flags.theme) t = t.replace(/^theme: .*/m, `theme: ${flags.theme}`);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, t);
+      console.log(`✓ criado ${target}\n  próximo passo: sagadeck build "${target}"`);
+      break;
+    }
+    case "imagens": case "images": {
+      // Gera as imagens pedidas com `image_prompt:` no YAML e troca por `image: imagens/…`
+      const p = paths(args[0]);
+      const { loadSpec } = await import("../src/build.js");
+      const { materializeImages, countImagePrompts, toYaml } = await import("../src/ai/deck-ai.js");
+      const spec = loadSpec(p.abs);
+      const n = countImagePrompts(spec);
+      if (!n) { console.log("Nenhum `image_prompt:` no deck; nada a gerar."); break; }
+      console.log(`Gerando ${n} imagem(ns)…`);
+      const { done, failed } = await materializeImages(spec, { baseDir: spec._dir, keepFailed: true, onProgress: (m) => console.log(`  … ${m}`) });
+      (await import("../src/deck-file.js")).writeDeckFile(p.abs, spec);
+      done.forEach((d) => console.log(`  🖼 ${path.relative(process.cwd(), d.file)}`));
+      failed.forEach((f) => console.log(`  ✗ "${f.prompt.slice(0, 50)}": ${f.error}`));
+      console.log(`✓ ${done.length} gerada(s), YAML atualizado: ${p.abs}`);
+      if (failed.length) process.exitCode = 1;
+      break;
+    }
+    case "build": doBuild(paths(args[0])); break;
+    case "check": { const p = paths(args[0]); doBuild(p); await doCheck(p); break; }
+    case "shots": { const p = paths(args[0]); doBuild(p, true); await doShots(p); break; }
+    case "pptx": {
+      const p = paths(args[0]); const r = doBuild(p, true);
+      const { exportPptx } = await import("../src/export/pptx.js");
+      console.log("… exportando PowerPoint");
+      const { errors } = await exportPptx(p.html, p.pptx, { theme: r.theme, meta: { ...r.meta, slides: r.slidesMeta }, nativeCharts: !!flags["native-charts"], notes: !flags["sem-notas"], log: flags.verbose ? console.log : () => {} });
+      errors.forEach((e) => console.log("  ✗ " + e));
+      console.log(`✓ PPTX: ${p.pptx}`);
+      break;
+    }
+    case "pdf": {
+      const p = paths(args[0]); doBuild(p, true);
+      const { pdf } = await import("../src/export/shots.js");
+      await pdf(p.html, p.pdf); console.log(`✓ PDF: ${p.pdf}`); break;
+    }
+    case "roteiro": {
+      const p = paths(args[0]); const r = doBuild(p, true);
+      const { shots } = await import("../src/export/shots.js");
+      const { roteiroPDF } = await import("../src/export/roteiro.js");
+      const { files } = await shots(p.html, p.tmpShots + "-mini", { scale: 0.5, jpeg: true });
+      await roteiroPDF({ slidesMeta: r.slidesMeta, shotFiles: files, outFile: p.roteiro, title: r.meta.title, author: r.meta.author, duration: r.spec.duration });
+      console.log(`✓ Roteiro: ${p.roteiro}`); break;
+    }
+    // material de estudo: cada slide inteiro + o texto de consulta (sem as notas); --html para um arquivo HTML só
+    case "estudo": {
+      const p = paths(args[0]); const r = doBuild(p, true);
+      const { shots } = await import("../src/export/shots.js");
+      const { estudoHTML, estudoPDF } = await import("../src/export/estudo.js");
+      const { files } = await shots(p.html, p.tmpShots + "-estudo", { scale: 0.7, jpeg: true });
+      const html = estudoHTML({ title: r.meta.title, author: r.meta.author, date: r.spec.date, slidesMeta: r.slidesMeta, shotFiles: files });
+      const out = p.roteiro.replace(/ - roteiro\.pdf$/, ` - material de estudo.${flags.html ? "html" : "pdf"}`);
+      if (flags.html) fs.writeFileSync(out, html); else await estudoPDF(html, out);
+      console.log(`✓ Material de estudo: ${out}`); break;
+    }
+    case "all": {
+      const p = paths(args[0]); const r = doBuild(p);
+      await doCheck(p);
+      const files = await doShots(p, flags.revisao ? p.shots : p.tmpShots);
+      const { exportPptx } = await import("../src/export/pptx.js");
+      await exportPptx(p.html, p.pptx, { theme: r.theme, meta: { ...r.meta, slides: r.slidesMeta }, nativeCharts: !!flags["native-charts"], notes: !flags["sem-notas"] });
+      console.log(`✓ PPTX: ${p.pptx}`);
+      const { pdf } = await import("../src/export/shots.js");
+      await pdf(p.html, p.pdf); console.log(`✓ PDF: ${p.pdf}`);
+      const { roteiroPDF } = await import("../src/export/roteiro.js");
+      const { shots: mini } = await import("../src/export/shots.js");
+      const small = (await mini(p.html, p.tmpShots + "-mini", { scale: 0.5, jpeg: true })).files;
+      await roteiroPDF({ slidesMeta: r.slidesMeta, shotFiles: small, outFile: p.roteiro, title: r.meta.title, author: r.meta.author, duration: r.spec.duration });
+      console.log(`✓ Roteiro: ${p.roteiro}`);
+      break;
+    }
+    case "watch": {
+      const p = paths(args[0]); doBuild(p);
+      console.log("observando mudanças… (Ctrl+C para sair)");
+      let t; fs.watch(path.dirname(p.abs), () => { clearTimeout(t); t = setTimeout(() => { try { doBuild(p); } catch (e) { console.error("✗ " + e.message); } }, 150); });
+      break;
+    }
+    case "pack": {
+      const p = paths(args[0]);
+      const { packDeck, EXTENSION } = await import("../src/package.js");
+      const name = path.basename(p.abs).replace(/\.ya?ml$/i, "");
+      const out = path.resolve(args[1] || path.join(path.dirname(p.abs), name + EXTENSION));
+      const { zip, files, missing } = await packDeck(loadSpec(p.abs), { baseDir: path.dirname(p.abs), name, generator: "sagadeck cli" });
+      fs.writeFileSync(out, zip);
+      console.log(`✓ ${out} (${(zip.length / 1024).toFixed(0)} KB · ${files.length} arquivo(s) junto)`);
+      missing.forEach((m) => console.log(`  ✗ não encontrado (listado em FALTANDO.txt): ${m}`));
+      break;
+    }
+    case "importar": case "import": {
+      const src = path.resolve(args[0] || "");
+      if (!fs.existsSync(src)) { console.error(`não achei ${src}`); process.exit(1); }
+      const { openLibrary, defaultLibraryRoot } = await import("../src/library.js");
+      const lib = openLibrary(flags.library || defaultLibraryRoot());
+      const r = await lib.importOffice(fs.readFileSync(src), flags.topico || flags.topic, path.basename(src), { title: flags.titulo || flags.title, snapshots: !flags["sem-fotos"], log: (m) => console.log(`  ${m}`) });
+      console.log(`importado: ${r.slides} slides${r.snapshots ? ` · fotos do original pelo ${r.snapBy}` : ""}${r.converted ? ` · ${r.converted} figura(s) WMF/EMF convertidas` : ""}
+  ${r.file}`);
+      break;
+    }
+    case "unpack": {
+      const src = path.resolve(args[0] || "");
+      if (!fs.existsSync(src)) { console.error(`não achei ${src}`); process.exit(1); }
+      const { unpackDeck } = await import("../src/package.js");
+      let dest = path.resolve(args[1] || src.replace(/\.(sagadeck|zip)$/i, ""));
+      for (let n = 2; fs.existsSync(dest) && !args[1]; n++) dest = `${src.replace(/\.(sagadeck|zip)$/i, "")}-${n}`;
+      const { file } = await unpackDeck(fs.readFileSync(src), dest);
+      console.log(`✓ extraído em ${dest}\n  apresentação: ${file}`);
+      break;
+    }
+    case "studio": case "web": {
+      const { createStudioServer } = await import("../src/studio/server.js");
+      let deckFile = args[0] ? path.resolve(args[0]) : null;
+      if (deckFile && /\.(sagadeck|zip)$/i.test(deckFile)) {
+        const { unpackDeck } = await import("../src/package.js");
+        let dest = deckFile.replace(/\.(sagadeck|zip)$/i, "");
+        for (let n = 2; fs.existsSync(dest); n++) dest = `${deckFile.replace(/\.(sagadeck|zip)$/i, "")}-${n}`;
+        deckFile = (await unpackDeck(fs.readFileSync(deckFile), dest)).file;
+        console.log(`  extraído em ${dest}`);
+      }
+      const { DEFAULT_PORT, VERSION, probeInstance, instanceDecision } = await import("../src/studio/instance.js");
+      const port = Number(flags.port || process.env.PORT || DEFAULT_PORT);
+      // só esta máquina por padrão (no banco, 0.0.0.0 abriria a biblioteca para a rede); --host para mudar
+      const host = typeof flags.host === "string" ? flags.host : "127.0.0.1";
+      const multiuser = !!flags.multiuser;
+      if (multiuser && !["127.0.0.1", "localhost", "::1"].includes(host)) {
+        console.error("--multiuser confia no cabeçalho de usuário do proxy (nginx): só funciona escutando em 127.0.0.1.");
+        process.exit(1);
+      }
+      const { defaultLibraryRoot } = await import("../src/library.js");
+      const library = typeof flags.library === "string" ? path.resolve(flags.library) : defaultLibraryRoot();
+      // --agentes=naru,ana: no multiusuário, só esses usuários podem deixar a IA rodar comandos (na máquina do servidor)
+      // já tem um Studio nesta porta? mesma biblioteca e versão: usa o aberto (nada de dois servidores nos mesmos arquivos)
+      const shownHost = host === "0.0.0.0" ? "localhost" : host;
+      const found = await probeInstance(port, host);
+      const decision = instanceDecision(found, { library, version: VERSION });
+      if (decision.action === "reuse") {
+        let url = `http://${shownHost}:${port}/`;
+        if (deckFile) {
+          const rel = path.relative(library, deckFile);
+          if (!rel.startsWith("..") && !path.isAbsolute(rel)) url += `editor?deck=${encodeURIComponent(rel.split(path.sep).join("/"))}`;
+          else { console.error(`O Studio já está aberto em http://${shownHost}:${port} com a biblioteca ${library}, e este deck está fora dela. Use --port=OUTRA para abri-lo à parte.`); process.exit(1); }
+        }
+        console.log(`✓ O SagaDeck Studio ${found.version} já está aberto (processo ${found.pid}): ${url}`);
+        break;
+      }
+      if (decision.action === "conflict") {
+        console.error(`A porta ${port} já tem um SagaDeck Studio aberto com ${decision.why}. Use --port=OUTRA para abrir à parte.`);
+        process.exit(1);
+      }
+      const agentUsers = typeof flags.agentes === "string" ? flags.agentes.split(",").map((x) => x.trim()).filter(Boolean) : undefined;
+      // IA: sobe o `modelrelay serve` junto, se ele estiver instalado e ninguém escutar na porta dele (como o sagadeck do pip)
+      const { startRelay } = await import("../src/ai/relay.js");
+      const relay = multiuser ? null : await startRelay();
+      if (relay) {
+        console.log(`✓ IA: modelrelay em ${relay.url} (configuração: http://127.0.0.1:8765/)`);
+        for (const sig of ["exit", "SIGINT", "SIGTERM"]) process.on(sig, () => { relay.stop(); if (sig !== "exit") process.exit(0); });
+      }
+      const server = createStudioServer(deckFile, { port, host, library, multiuser, userHeader: flags["user-header"], agentUsers });
+      server.on("error", (e) => {
+        if (e.code !== "EADDRINUSE") throw e;
+        console.error(`A porta ${port} está ocupada por outro programa. Use --port=OUTRA.`);
+        process.exit(1);
+      });
+      server.listen(port, host, () => {
+        console.log(`✓ SagaDeck Studio ${VERSION} em http://${shownHost}:${port}${deckFile ? "" : "  (biblioteca)"}  (processo ${process.pid})`);
+        console.log(multiuser ? `  multiusuário: bibliotecas em ${path.join(library, "usuarios")}` : `  biblioteca: ${library}`);
+      });
+      break;
+    }
+    // Ensaio do slide "api": API de mentira + ambientes temporários + o deck de exemplo, no Studio.
+    // Nada disso toca no seu ~/.sagadeck/ambientes.yaml.
+    case "ensaio-api": {
+      const { startMockApi, demoEnvFile, DEMO_FILES } = await import("../src/api-demo.js");
+      const { createStudioServer } = await import("../src/studio/server.js");
+      const { defaultLibraryRoot } = await import("../src/library.js");
+      const { newDeckPath } = await import("../src/library.js");
+      const YAML = (await import("yaml")).default;
+      const mock = await startMockApi({ statuses: ["STARTED", "RUNNING", "RUNNING", "FINISHED"] });
+      // só os ambientes (apontam para a porta desta API de mentira) ficam no temporário; o deck mora na biblioteca
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "sagadeck-ensaio-"));
+      const envFile = path.join(tmp, "ambientes.yaml");
+      fs.writeFileSync(envFile, demoEnvFile(mock));
+      const tpl = path.join(TEMPLATES, "ensaio-api.yaml");
+      const deckFile = newDeckPath(null, { title: YAML.parse(fs.readFileSync(tpl, "utf8")).title });
+      const dir = path.dirname(deckFile);
+      fs.mkdirSync(dir, { recursive: true });
+      // já existe (de outra vez, talvez editado): reabre como está; nada é sobrescrito
+      if (!fs.existsSync(deckFile)) fs.copyFileSync(tpl, deckFile);
+      for (const [name, text] of Object.entries(DEMO_FILES)) if (!fs.existsSync(path.join(dir, name))) fs.writeFileSync(path.join(dir, name), text);
+      const port = Number(flags.port || process.env.PORT || 3000);
+      // ensaio: false — os ambientes do ensaio já estão no arquivo (dev e hom), sem o embutido repetido
+      const server = createStudioServer(deckFile, { port, host: "127.0.0.1", library: defaultLibraryRoot(), apiEnvFile: envFile, ensaio: false });
+      server.listen(port, "127.0.0.1", () => {
+        console.log(`✓ Ensaio no Studio: http://127.0.0.1:${port}/editor`);
+        console.log(`  deck: ${deckFile}`);
+        console.log(`  API de mentira em ${mock.url} · ambientes do ensaio em ${envFile}`);
+        console.log("  Apresente (F5 / Apresentar) e clique em Executar em cada slide. Ctrl+C encerra.");
+      });
+      break;
+    }
+    case "autofix": {
+      const p = paths(args[0]);
+      const { autofixDeck } = await import("../src/fiscal/autofix.js");
+      const YAML = (await import("yaml")).default;
+      const spec = loadSpec(p.abs);
+      console.log(`… analisando e auto-corrigindo ${p.abs}`);
+      const res = autofixDeck(spec);
+      const outYaml = flags.out ? path.resolve(flags.out) : p.abs;
+      (await import("../src/deck-file.js")).writeDeckFile(outYaml, res.spec);
+      console.log(`✓ Auto-correção concluída! Salvo em: ${outYaml}`);
+      if (res.actions.length === 0) {
+        console.log("  Nenhum problema de sobreposição ou margem encontrado.");
+      } else {
+        console.log(`  ${res.modifiedSlidesCount} slide(s) corrigido(s):`);
+        for (const a of res.actions) {
+          console.log(`  • Slide ${a.slide} (${a.layout}):`);
+          for (const item of a.actions) console.log(`    - ${item}`);
+        }
+      }
+      break;
+    }
+    case "mcp": {
+      const { runMCPServer } = await import("../src/mcp/server.js");
+      runMCPServer();
+      break;
+    }
+    case "themes": {
+      const out = path.resolve(flags.out || path.join(process.cwd(), "sagadeck-temas"));
+      fs.mkdirSync(out, { recursive: true });
+      const { shots, contactSheet } = await import("../src/export/shots.js");
+      const src = path.join(TEMPLATES, "exemplo.yaml");
+      for (const name of Object.keys(THEMES)) {
+        const spec = loadSpec(src); spec.theme = name; spec.id = "tema-" + name;
+        const html = path.join(out, `tema-${name}.html`);
+        fs.writeFileSync(html, buildHTML(spec).html);
+        const { files } = await shots(html, path.join(out, `tema-${name}`), {});
+        const sheets = await contactSheet(files, path.join(out, `tema-${name}`), { perSheet: 12 });
+        console.log(`✓ ${name}: ${html}\n  ${sheets[0]}`);
+      }
+      break;
+    }
+    case "icons": { const l = listIcons(args[0]); console.log(l.join("  ")); console.log(`\n${l.length} ícones`); break; }
+    case "search": {
+      const query = args.join(" ");
+      if (!query) {
+        console.error("Uso: sagadeck search <termo de busca>");
+        process.exit(1);
+      }
+      const { searchDuckDuckGo } = await import("../src/research/duckduckgo.js");
+      const limit = Number(flags.limit || 5);
+      console.log(`… pesquisando no DuckDuckGo: "${query}"`);
+      try {
+        const results = await searchDuckDuckGo(query, { limit });
+        if (flags.json) {
+          console.log(JSON.stringify(results, null, 2));
+        } else {
+          console.log(`✓ ${results.length} resultado(s) encontrado(s):\n`);
+          results.forEach((r, i) => {
+            console.log(`${i + 1}. \x1b[1m${r.title}\x1b[0m`);
+            console.log(`   \x1b[36m${r.url}\x1b[0m`);
+            if (r.snippet) console.log(`   ${r.snippet}\n`);
+          });
+        }
+      } catch (err) {
+        console.error(`✗ Erro na pesquisa: ${err.message}`);
+      }
+      break;
+    }
+    case "ref": case "referencia": process.stdout.write(fs.readFileSync(path.join(DOCS, "REFERENCIA.md"), "utf8")); break;
+    case "skill": process.stdout.write(fs.readFileSync(SKILL, "utf8")); break;
+    case "--version": case "-v": case "version": console.log(`sagadeck ${VERSION}`); break;
+    default: console.log(HELP);
+  }
+}
+
+main().catch((e) => { console.error("✗ " + (e.stack || e.message)); process.exit(1); });