@semacode/cli 1.5.7 → 1.5.9

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
@@ -17,6 +17,7 @@ import { gerarCss } from "@sema/gerador-css";
 import { carregarConfiguracaoProjeto, carregarProjeto, resolverAlvoPadrao, resolverAlvosVerificacao, resolverEstruturaSaidaPadrao, resolverFrameworkPadrao, resolverSaidaPadrao, } from "./projeto.js";
 import { importarProjetoLegado, resumoImportacao } from "./importador.js";
 import { analisarDriftLegado, assistirRenomeacaoSemantica, gerarMapaImpactoSemantico, } from "./drift.js";
+import { resolverDocumentacaoObrigatoria, verificarDocumentacaoMudanca, } from "./docs.js";
 const STARTER_IA = `Voce esta trabalhando com Sema, um Protocolo de Governanca de Intencao para IA sobre software vivo em backend e front consumer.
 
 Importante:
@@ -63,8 +64,9 @@ Comandos essenciais:
 - validacao: \`sema validar <arquivo.sema> --json\`
 - diagnosticos: \`sema diagnosticos <arquivo.sema> --json\`
 - formatacao: \`sema formatar <arquivo.sema>\`
-- importacao assistida de legado: \`sema importar <nestjs|fastapi|flask|nextjs|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|firebase|dotnet|java|go|rust|cpp|typescript|python|dart> <diretorio> --saida <diretorio>\`
-- geracao de codigo: \`sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua> --saida <diretorio>\`
+- importacao assistida de legado: \`sema importar <nestjs|fastapi|flask|nextjs|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|firebase|dotnet|java|go|rust|cpp|typescript|python|dart> <diretorio> --saida <diretorio>\`
+- exemplos oficiais no projeto: \`sema instalar-exemplos\`
+- geracao de codigo: \`sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua> --saida <diretorio>\`
 - verificacao final: \`sema verificar <arquivo-ou-pasta> [--json]\`
 
 Antes de editar:
@@ -339,6 +341,12 @@ const DOCUMENTOS_SUPORTE_IA = [
     "docs/persistencia-vendor-first.md",
     "docs/sintaxe.md",
     "docs/cli.md",
+    "docs/mcp.md",
+    "docs/documentacao.md",
+    "docs/deploy.md",
+    "docs/env.md",
+    "docs/rollback.md",
+    "docs/extensao-vscode.md",
 ];
 function resolverImportadorNodeOpcional(especificador) {
     try {
@@ -350,6 +358,65 @@ function resolverImportadorNodeOpcional(especificador) {
 }
 const TSX_IMPORTADOR_CLI = resolverImportadorNodeOpcional("tsx");
 const TSX_EXECUTOR_CLI = resolverImportadorNodeOpcional("tsx/cli");
+async function caminhoEhDiretorio(caminhoAlvo) {
+    try {
+        return (await stat(caminhoAlvo)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function localizarDiretorioExemplosOficiais() {
+    const candidatos = [
+        path.resolve(DIRETORIO_CLI_ATUAL, "..", "exemplos"),
+        path.resolve(DIRETORIO_CLI_ATUAL, "..", "..", "..", "exemplos"),
+    ];
+    for (const candidato of candidatos) {
+        if (await caminhoEhDiretorio(candidato)) {
+            return candidato;
+        }
+    }
+    return undefined;
+}
+async function materializarExemplosOficiais(baseProjeto = process.cwd(), preservarExistentes = true) {
+    const origem = await localizarDiretorioExemplosOficiais();
+    const destino = path.resolve(baseProjeto, "exemplos");
+    if (!origem) {
+        return {
+            sucesso: false,
+            origem: null,
+            destino,
+            criados: [],
+            preservados: [],
+            erro: "Diretorio de exemplos oficiais nao foi encontrado no pacote da CLI.",
+        };
+    }
+    await mkdir(destino, { recursive: true });
+    const criados = [];
+    const preservados = [];
+    const entradas = await readdir(origem, { withFileTypes: true });
+    for (const entrada of entradas.sort((a, b) => a.name.localeCompare(b.name, "pt-BR"))) {
+        if (!entrada.isFile() || !entrada.name.endsWith(".sema")) {
+            continue;
+        }
+        const origemArquivo = path.join(origem, entrada.name);
+        const destinoArquivo = path.join(destino, entrada.name);
+        const jaExiste = await caminhoExiste(destinoArquivo);
+        if (jaExiste && preservarExistentes) {
+            preservados.push(entrada.name);
+            continue;
+        }
+        await writeFile(destinoArquivo, await readFile(origemArquivo, "utf8"), "utf8");
+        criados.push(entrada.name);
+    }
+    return {
+        sucesso: true,
+        origem,
+        destino,
+        criados,
+        preservados,
+    };
+}
 function obterArgumentos() {
     const [, , comando, ...resto] = process.argv;
     return { comando: comando, resto };
@@ -389,6 +456,7 @@ function ajuda() {
             "sema resumo <arquivo-ou-pasta> --micro --para mudanca",
             "sema drift <arquivo-ou-pasta> --escopo modulo --json",
             "sema impacto <arquivo-ou-pasta> --alvo <token> --mudanca <descricao> --json",
+            "sema docs-impacto --intencao \"fazer deploy\" --criar-ausentes --json",
             "sema contexto-ia <arquivo.sema> --saida ./.tmp/contexto --json",
             "",
             "[3] Adotar Sema em projeto que ainda nao usa",
@@ -430,6 +498,9 @@ function ajuda() {
             "sema exemplos-prompt-ia",
             "sema contexto-ia <arquivo.sema> [--saida <diretorio>] [--json]",
             "sema sync-ai-entrypoints [--json]",
+            "sema instalar-exemplos [--json]",
+            "sema docs-impacto --intencao <acao> [--arquivo <caminho>] [--criar-ausentes] [--json]",
+            "sema finalizar-mudanca --intencao <acao> [--arquivo <caminho>] [--doc-lida <caminho>] [--json]",
         ]),
         "",
         renderizarSecaoAscii("Operacional", [
@@ -461,6 +532,16 @@ function obterOpcao(args, nome, padrao) {
 function possuiFlag(args, nome) {
     return args.includes(nome);
 }
+function obterOpcoesRepetidas(args, nome) {
+    const valores = [];
+    for (let indice = 0; indice < args.length; indice += 1) {
+        if (args[indice] === nome && args[indice + 1]) {
+            valores.push(args[indice + 1]);
+            indice += 1;
+        }
+    }
+    return valores;
+}
 const OPCOES_COM_VALOR = new Set([
     "--template",
     "--alvo", "-a",
@@ -472,6 +553,9 @@ const OPCOES_COM_VALOR = new Set([
     "--mudanca",
     "--de",
     "--para",
+    "--intencao",
+    "--arquivo",
+    "--doc-lida",
 ]);
 const ALIAS_OPCOES = {
     "-a": "--alvo",
@@ -3177,9 +3261,113 @@ public:
         ];
     }
     await escreverArquivos(cwd, arquivos);
+    const exemplos = await materializarExemplosOficiais(cwd, true);
+    if (!exemplos.sucesso) {
+        console.error(exemplos.erro);
+        return 1;
+    }
     console.log(`Projeto Sema inicializado com template ${template}.`);
+    console.log(`Exemplos oficiais sincronizados em ${exemplos.destino} (${exemplos.criados.length} criados, ${exemplos.preservados.length} preservados).`);
+    return 0;
+}
+async function comandoInstalarExemplos(emJson) {
+    const resultado = await materializarExemplosOficiais(process.cwd(), true);
+    const payload = {
+        comando: "instalar-exemplos",
+        ...resultado,
+    };
+    if (emJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return resultado.sucesso ? 0 : 1;
+    }
+    if (!resultado.sucesso) {
+        console.error(resultado.erro ?? "Falha ao instalar exemplos oficiais.");
+        return 1;
+    }
+    console.log("Exemplos oficiais sincronizados");
+    console.log(`- Origem: ${resultado.origem}`);
+    console.log(`- Destino: ${resultado.destino}`);
+    console.log(`- Criados: ${resultado.criados.length}`);
+    console.log(`- Preservados: ${resultado.preservados.length}`);
     return 0;
 }
+function resolverEntradaDocs(posicionais, args) {
+    const intencao = obterOpcao(args, "--intencao") ?? posicionais[0] ?? "";
+    const arquivosPorFlag = obterOpcoesRepetidas(args, "--arquivo");
+    const arquivosPosicionais = obterOpcao(args, "--intencao") ? posicionais : posicionais.slice(1);
+    return {
+        intencao,
+        arquivosAlvo: [...new Set([...arquivosPorFlag, ...arquivosPosicionais])],
+    };
+}
+async function comandoDocsImpacto(posicionais, args, emJson) {
+    const { intencao, arquivosAlvo } = resolverEntradaDocs(posicionais, args);
+    if (!intencao.trim()) {
+        console.error("Uso: sema docs-impacto --intencao <acao> [--arquivo <caminho>] [--criar-ausentes] [--json]");
+        return 1;
+    }
+    const resultado = await resolverDocumentacaoObrigatoria({
+        baseProjeto: process.cwd(),
+        intencao,
+        arquivosAlvo,
+        criarAusentes: possuiFlag(args, "--criar-ausentes"),
+    });
+    const payload = {
+        comando: "docs-impacto",
+        ...resultado,
+    };
+    if (emJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return resultado.sucesso ? 0 : 1;
+    }
+    console.log("Documentacao obrigatoria da mudanca");
+    console.log(`- Intencao: ${resultado.intencao}`);
+    console.log(`- Categorias: ${resumirListaTexto(resultado.categorias, 8)}`);
+    console.log(`- Leitura obrigatoria: ${resultado.leituraObrigatoria.length}`);
+    for (const doc of resultado.leituraObrigatoria) {
+        console.log(`  - ${doc.relativo} (${doc.existe ? "ok" : "ausente"}) - ${doc.motivo}`);
+    }
+    if (resultado.docsCriadas.length > 0) {
+        console.log(`- Docs criadas: ${resultado.docsCriadas.map((doc) => doc.relativo).join(", ")}`);
+    }
+    if (resultado.bloqueios.length > 0) {
+        console.error("Bloqueios:");
+        for (const bloqueio of resultado.bloqueios) {
+            console.error(`- [SEM DOC ${bloqueio.severidade}] ${bloqueio.mensagem}`);
+        }
+    }
+    return resultado.sucesso ? 0 : 1;
+}
+async function comandoFinalizarMudanca(posicionais, args, emJson) {
+    const { intencao, arquivosAlvo } = resolverEntradaDocs(posicionais, args);
+    if (!intencao.trim()) {
+        console.error("Uso: sema finalizar-mudanca --intencao <acao> [--arquivo <caminho>] [--doc-lida <caminho>] [--json]");
+        return 1;
+    }
+    const resultado = await verificarDocumentacaoMudanca({
+        baseProjeto: process.cwd(),
+        intencao,
+        arquivosAlvo,
+        docsLidas: obterOpcoesRepetidas(args, "--doc-lida"),
+    });
+    const payload = {
+        comando: "finalizar-mudanca",
+        ...resultado,
+    };
+    if (emJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return resultado.sucesso ? 0 : 1;
+    }
+    if (resultado.sucesso) {
+        console.log("Leitura documental comprovada para a mudanca.");
+        return 0;
+    }
+    console.error("Mudanca bloqueada por documentacao obrigatoria:");
+    for (const diagnostico of resultado.diagnosticos) {
+        console.error(`- [severidade ${diagnostico.severidade}] ${diagnostico.mensagem}`);
+    }
+    return 1;
+}
 async function comandoValidar(entrada) {
     const modulos = await carregarModulos(entrada);
     const diagnosticos = modulos.flatMap((item) => item.resultado.diagnosticos);
@@ -3639,10 +3827,26 @@ async function comandoStarterIa() {
 }
 async function comandoSyncAiEntrypoints(emJson) {
     const resumoProjeto = await gerarResumoProjetoIa(process.cwd(), undefined, true);
+    const exemplos = await materializarExemplosOficiais(resumoProjeto.baseProjeto, true);
+    if (!exemplos.sucesso) {
+        if (emJson) {
+            console.log(JSON.stringify({
+                comando: "sync-ai-entrypoints",
+                sucesso: false,
+                baseProjeto: resumoProjeto.baseProjeto,
+                erro: exemplos.erro,
+                exemplos,
+            }, null, 2));
+            return 1;
+        }
+        console.error(exemplos.erro);
+        return 1;
+    }
     const indexJson = JSON.parse(await readFile(path.join(resumoProjeto.pastaSaida, "SEMA_INDEX.json"), "utf8"));
     const artefatos = [...new Set([
             ...ARQUIVOS_CANONICOS_IA_RAIZ,
             ...resumoProjeto.artefatos,
+            "exemplos",
         ])];
     if (emJson) {
         console.log(JSON.stringify({
@@ -3652,6 +3856,7 @@ async function comandoSyncAiEntrypoints(emJson) {
             pastaSaida: resumoProjeto.pastaSaida,
             artefatos,
             entradaCanonica: indexJson.entradaCanonica,
+            exemplos,
         }, null, 2));
         return 0;
     }
@@ -3662,6 +3867,7 @@ async function comandoSyncAiEntrypoints(emJson) {
     console.log(`IA pequena: ${indexJson.entradaCanonica.porCapacidade.pequena.join(" -> ")}`);
     console.log(`IA media: ${indexJson.entradaCanonica.porCapacidade.media.join(" -> ")}`);
     console.log(`IA grande: ${indexJson.entradaCanonica.porCapacidade.grande.join(" -> ")}`);
+    console.log(`Exemplos oficiais: ${exemplos.criados.length} criados, ${exemplos.preservados.length} preservados em ${exemplos.destino}`);
     return 0;
 }
 async function comandoAjudaIa() {
@@ -3690,12 +3896,15 @@ async function comandoAjudaIa() {
     console.log(renderizarSecaoAscii("Fluxo recomendado", [
         "Use `sema starter-ia` para um texto curto de onboarding.",
         "Use `sema sync-ai-entrypoints` para regenerar `SEMA_BRIEF.*` e `SEMA_INDEX.json` na raiz.",
+        "Use `sema instalar-exemplos` para materializar `exemplos/` oficiais sem sobrescrever arquivos locais.",
         "Use `sema resumo <arquivo> --micro --para onboarding` para IA pequena.",
         "Use `sema prompt-curto <arquivo> --curto --para mudanca` para colar contexto em modelo gratuito.",
         "Use `sema prompt-ia`, `sema prompt-ia-ui`, `sema prompt-ia-react` e `sema prompt-ia-sema-primeiro` conforme a tarefa.",
         "Use `sema exemplos-prompt-ia` para pegar modelos prontos de prompt.",
         "Use `sema inspecionar` para descobrir base, codigo vivo e fontes legado.",
         "Use `sema drift` para medir impls, vinculos, rotas, score e lacunas.",
+        "Use `sema docs-impacto --intencao <acao>` para ler ou criar docs obrigatorias antes de agir.",
+        "Use `sema finalizar-mudanca --intencao <acao>` para bloquear conclusao sem leitura documental comprovada.",
         "Use `sema contexto-ia <arquivo.sema>` para gerar AST, IR, drift, `briefing.json` e `briefing.min.json`.",
         "Use `sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua> --saida <diretorio>` quando a tarefa pedir codigo derivado.",
     ]));
@@ -4201,6 +4410,15 @@ async function principal() {
         case "sync-ai-entrypoints":
             codigoSaida = await comandoSyncAiEntrypoints(possuiFlag(resto, "--json"));
             break;
+        case "instalar-exemplos":
+            codigoSaida = await comandoInstalarExemplos(possuiFlag(resto, "--json"));
+            break;
+        case "docs-impacto":
+            codigoSaida = await comandoDocsImpacto(posicionais, resto, possuiFlag(resto, "--json"));
+            break;
+        case "finalizar-mudanca":
+            codigoSaida = await comandoFinalizarMudanca(posicionais, resto, possuiFlag(resto, "--json"));
+            break;
         case "resumo":
             codigoSaida = await comandoResumo(posicionais[0], resto, possuiFlag(resto, "--json"));
             break;