@semacode/cli 4.1.2 → 4.1.3

package/dist/cliGrammar.js

@@ -461,7 +461,7 @@ function validarComandoBasico(comando, args) {
             const estrutura = valorOpcao(parsed, "--estrutura"), framework = valorOpcao(parsed, "--framework");
             return Boolean(alvo && ALVOS_GERACAO.has(alvo)) && (!estrutura || ESTRUTURAS.has(estrutura)) && (!framework || FRAMEWORKS.has(framework));
         }
-        case "verificar": return parsearArgumentos(args, { opcoes: ["--saida", "--alvo"], flags: ["--sem-cache"], maxPosicionais: 1 }) !== null;
+        case "verificar": return parsearArgumentos(args, { opcoes: ["--saida", "--alvo"], flags: ["--sem-cache", "--preservar-implementacao"], maxPosicionais: 1 }) !== null;
         case "sessao": return parsearArgumentos(args, { flags: ["--json"], maxPosicionais: 2 }) !== null;
         case "formatar": return parsearArgumentos(args, { flags: ["--check"], maxPosicionais: 1 }) !== null;
         case "inspecionar": {

package/dist/cliHelpTexto.js

@@ -29,7 +29,8 @@ export function criarAjudaRaiz(versao) {
             "Arquivos existentes são preservados; use --force somente para sobrescrita explícita. O starter de exemplos vem por padrão; --com-exemplos instala o pacote completo. Em subpasta de workspace já governado, a subpasta é registrada nos diretoriosCodigo do sema.config.json ancestral em vez de criar config local.",
             "sema validar contratos/<modulo>.sema --json",
             "sema compilar <arquivo-ou-pasta> --alvo <typescript|python|php|dart|lua|javascript|html|css|dotnet|cpp> --saida <diretorio>",
-            "sema verificar <arquivo-ou-pasta> [--saida <dir>] [--alvo <alvo>] [--sem-cache] --json",
+            "sema verificar <arquivo-ou-pasta> [--saida <dir>] [--alvo <alvo>] [--sem-cache] [--preservar-implementacao] --json",
+            "  --preservar-implementacao: somente Python base; preserva implementação local, regenera testes e ignora cache. Não comprova produção.",
             "",
             "[2] Editar projeto que já usa Sema",
             "sema inspecionar . [--drift <none|cache|fresh>] --json",
@@ -121,7 +122,7 @@ export function criarAjudaRaiz(versao) {
             "geração: sema compilar <arquivo-ou-pasta> --alvo <typescript|python|php|dart|lua|javascript|html|css|dotnet|cpp> --saida <diretorio> [--estrutura <flat|modulos|backend>] [--framework <base|nestjs|fastapi>]",
             "teste local: sema testar <arquivo.sema> --alvo <typescript|python|php|dart|lua|javascript|html|css|dotnet|cpp> --saida <diretorio-temporario> [--estrutura <flat|modulos|backend>] [--framework <base|nestjs|fastapi>]",
             "aliases nativos: cs|csharp -> dotnet; c++|cxx|cc -> cpp (CLI e sema.config.json)",
-            "verificação final: sema verificar <arquivo-ou-pasta> [--saida <diretorio-base>] [--alvo <alvo>] [--sem-cache] [--json]",
+            "verificação final: sema verificar <arquivo-ou-pasta> [--saida <diretorio-base>] [--alvo <alvo>] [--sem-cache] [--preservar-implementacao] [--json]",
             "formatação: sema formatar <arquivo-ou-pasta> [--check] [--json]",
             "author: sema author <iniciar|validar|briefing|revisar-cliches|validar-narrativa|validar-proibicoes> [arquivo] [--tema-sensivel] [--preset conto|romance|roteiro|lore|campanha] [--saida <arquivo>] [--texto <texto>] [--json]",
             "profile: sema profile validar <software|workflow|ops|game|simulation|legal|research|redacao|propostas|conversas> <arquivo-ou-pasta> [--maturidade draft|prototype|production|critical] [--preset <preset>] [--artefato <texto>|--artefato-arquivo <arquivo>] [--json]",

package/dist/geracaoCore.d.ts

@@ -18,7 +18,7 @@ export interface ResumoAlvoVerificacao {
     estrutura: EstruturaSaida;
     testesExecutados: boolean;
     origem?: "executado" | "cache";
-    tipoEvidencia?: "andaime_demonstrativo";
+    tipoEvidencia?: "andaime_demonstrativo" | "implementacao_local_preservada";
     implementacaoExternaExecutada?: boolean;
 }
 export interface ResumoModuloVerificacao {

package/dist/index.part07.d.ts

@@ -3,6 +3,7 @@ import type { EstruturaSaida } from "./tipos.js";
 export interface OpcoesVerificar {
     alvo?: string;
     semCache?: boolean;
+    preservarImplementacao?: boolean;
 }
 export declare function alvosSuportadosPelaStack(fontesLegado: string[] | undefined): AlvoGeracao[] | undefined;
 export declare function avisoEscopoStackVerificacao(fontesLegado: string[] | undefined, alvosEfetivos: AlvoGeracao[]): string | undefined;

package/dist/index.part07.js

@@ -6,6 +6,7 @@ import pacoteCli from "../package.json" with { type: "json" };
 import { compilarCodigo, formatarDiagnosticos, lerArquivoTexto, temErros, } from "@sema/nucleo";
 import { carregarProjeto, resolverAlvosVerificacao, } from "./projeto.js";
 import { SCHEMA_CACHE_VERIFICACAO, calcularChaveVerificacao, carregarCacheVerificacao, gravarCacheVerificacao, } from "./verificacaoCache.js";
+import { erroModoPreservacao, prepararImplementacaoPythonLocal, evidenciaPython } from "./verificacaoPythonLocal.js";
 const FONTES_POR_ALVO_SUPORTADO = {
     typescript: ["typescript", "javascript"],
     javascript: ["typescript", "javascript"],
@@ -210,7 +211,7 @@ export function imprimirResumoVerificacao(resumos) {
             totalArquivos += alvo.arquivosGerados;
             totalTestes += alvo.quantidadeTestes;
             totalAlvos += 1;
-            console.log(`  alvo=${alvo.alvo} framework=${alvo.framework} estrutura=${alvo.estrutura} status=${alvo.sucesso ? "ok" : "falhou"} arquivos=${alvo.arquivosGerados} testes=${alvo.quantidadeTestes}${alvo.testesExecutados ? "" : " (skip)"} saida=${alvo.pastaSaida}`);
+            console.log(`  alvo=${alvo.alvo} framework=${alvo.framework} estrutura=${alvo.estrutura} status=${alvo.sucesso ? "ok" : "falhou"} arquivos=${alvo.arquivosGerados} testes=${alvo.quantidadeTestes}${alvo.testesExecutados ? "" : " (skip)"}${alvo.tipoEvidencia ? ` evidencia=${alvo.tipoEvidencia} (não comprova produção)` : ""} saida=${alvo.pastaSaida}`);
         }
     }
     console.log(`Totais: modulos=${resumos.length} alvos=${totalAlvos} arquivos=${totalArquivos} testes=${totalTestes}`);
@@ -240,6 +241,11 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
         ...resolverConfiguracaoVerificacaoPorAlvo(alvo, contextoProjeto.configCarregada),
     }));
     const incompatibilidade = configuracoesAlvo.find((item) => item.incompatibilidade);
+    const erroPreservacao = erroModoPreservacao(opcoes.preservarImplementacao, configuracoesAlvo);
+    if (erroPreservacao) {
+        console.error(erroPreservacao);
+        return 1;
+    }
     if (incompatibilidade?.incompatibilidade) {
         console.error(incompatibilidade.incompatibilidade);
         return 1;
@@ -272,7 +278,7 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
                 estrutura,
                 conteudoContrato,
             });
-            const emCache = opcoes.semCache ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
+            const emCache = opcoes.semCache || opcoes.preservarImplementacao ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
             if (emCache) {
                 resumoModulo.alvos.push({
                     alvo,
@@ -294,21 +300,27 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
                 continue;
             }
             const arquivos = aplicarEstruturaSaida(gerarArquivosPorAlvo(ir, alvo, framework), ir, estrutura);
-            const escrita = await escreverArquivos(pastaAlvo, arquivos, { artefatoGerado: true });
+            const preparacao = opcoes.preservarImplementacao ? await prepararImplementacaoPythonLocal(pastaAlvo, arquivos) : { arquivosParaEscrita: arquivos };
+            if (preparacao.erro) {
+                console.error(preparacao.erro);
+                return 1;
+            }
+            const escrita = await escreverArquivos(pastaAlvo, preparacao.arquivosParaEscrita, { artefatoGerado: true });
             artefatosGeradosAcimaDoLimite.push(...escrita.artefatosGeradosAcimaDoLimite);
             const { execucao, testesExecutados } = executarTestesParaVerificacao(alvo, pastaAlvo, arquivos, framework);
-            await gravarCacheVerificacao({
-                schemaVersion: SCHEMA_CACHE_VERIFICACAO,
-                chave,
-                versaoCli: pacoteCli.version,
-                alvo,
-                modulo: ir.nome,
-                sucesso: execucao.codigoSaida === 0,
-                quantidadeTestes: execucao.quantidadeTestes,
-                testesExecutados,
-                arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
-                geradoEm: new Date().toISOString(),
-            });
+            if (!opcoes.preservarImplementacao)
+                await gravarCacheVerificacao({
+                    schemaVersion: SCHEMA_CACHE_VERIFICACAO,
+                    chave,
+                    versaoCli: pacoteCli.version,
+                    alvo,
+                    modulo: ir.nome,
+                    sucesso: execucao.codigoSaida === 0,
+                    quantidadeTestes: execucao.quantidadeTestes,
+                    testesExecutados,
+                    arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
+                    geradoEm: new Date().toISOString(),
+                });
             resumoModulo.alvos.push({
                 alvo,
                 arquivosGerados: arquivos.length,
@@ -319,7 +331,7 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
                 estrutura,
                 testesExecutados,
                 origem: "executado",
-                ...(alvo === "python" ? { tipoEvidencia: "andaime_demonstrativo", implementacaoExternaExecutada: false } : {}),
+                ...(alvo === "python" ? evidenciaPython(opcoes.preservarImplementacao) : {}),
             });
             if (execucao.codigoSaida !== 0) {
                 imprimirResumoVerificacao([...resumos, resumoModulo]);
@@ -372,6 +384,11 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
         ...resolverConfiguracaoVerificacaoPorAlvo(alvo, contextoProjeto.configCarregada),
     }));
     const incompatibilidade = configuracoesAlvo.find((item) => item.incompatibilidade);
+    const erroPreservacao = erroModoPreservacao(opcoes.preservarImplementacao, configuracoesAlvo);
+    if (erroPreservacao) {
+        console.log(JSON.stringify({ comando: "verificar", sucesso: false, erro: erroPreservacao, modulos: [], totais: { modulos: 0, alvos: 0, arquivos: 0, testes: 0 } }));
+        return 1;
+    }
     if (incompatibilidade?.incompatibilidade) {
         console.log(JSON.stringify({
             comando: "verificar",
@@ -418,7 +435,7 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
                 estrutura,
                 conteudoContrato,
             });
-            const emCache = opcoes.semCache ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
+            const emCache = opcoes.semCache || opcoes.preservarImplementacao ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
             if (emCache) {
                 resumoModulo.alvos.push({
                     alvo,
@@ -439,21 +456,27 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
                 continue;
             }
             const arquivos = aplicarEstruturaSaida(gerarArquivosPorAlvo(ir, alvo, framework), ir, estrutura);
-            const escrita = await escreverArquivos(pastaAlvo, arquivos, { artefatoGerado: true });
+            const preparacao = opcoes.preservarImplementacao ? await prepararImplementacaoPythonLocal(pastaAlvo, arquivos) : { arquivosParaEscrita: arquivos };
+            if (preparacao.erro) {
+                console.log(JSON.stringify({ comando: "verificar", sucesso: false, erro: preparacao.erro, modulos: resumos, totais: { modulos: resumos.length, alvos: 0, arquivos: 0, testes: 0 } }));
+                return 1;
+            }
+            const escrita = await escreverArquivos(pastaAlvo, preparacao.arquivosParaEscrita, { artefatoGerado: true });
             artefatosGeradosAcimaDoLimite.push(...escrita.artefatosGeradosAcimaDoLimite);
             const { execucao, testesExecutados } = executarTestesParaVerificacao(alvo, pastaAlvo, arquivos, framework, true);
-            await gravarCacheVerificacao({
-                schemaVersion: SCHEMA_CACHE_VERIFICACAO,
-                chave,
-                versaoCli: pacoteCli.version,
-                alvo,
-                modulo: ir.nome,
-                sucesso: execucao.codigoSaida === 0,
-                quantidadeTestes: execucao.quantidadeTestes,
-                testesExecutados,
-                arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
-                geradoEm: new Date().toISOString(),
-            });
+            if (!opcoes.preservarImplementacao)
+                await gravarCacheVerificacao({
+                    schemaVersion: SCHEMA_CACHE_VERIFICACAO,
+                    chave,
+                    versaoCli: pacoteCli.version,
+                    alvo,
+                    modulo: ir.nome,
+                    sucesso: execucao.codigoSaida === 0,
+                    quantidadeTestes: execucao.quantidadeTestes,
+                    testesExecutados,
+                    arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
+                    geradoEm: new Date().toISOString(),
+                });
             resumoModulo.alvos.push({
                 alvo,
                 arquivosGerados: arquivos.length,
@@ -464,7 +487,7 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
                 estrutura,
                 testesExecutados,
                 origem: "executado",
-                ...(alvo === "python" ? { tipoEvidencia: "andaime_demonstrativo", implementacaoExternaExecutada: false } : {}),
+                ...(alvo === "python" ? evidenciaPython(opcoes.preservarImplementacao) : {}),
             });
             resumoModulo.saidaTestes.push({ alvo, stdout: execucao.saidaPadrao, stderr: execucao.saidaErro });
             if (execucao.codigoSaida !== 0) {

package/dist/index.part08.js

@@ -105,8 +105,8 @@ export async function principal() {
             break;
         case "verificar":
             codigoSaida = possuiFlag(resto, "--json")
-                ? await comandoVerificarJson(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache") })
-                : await comandoVerificar(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache") });
+                ? await comandoVerificarJson(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache"), preservarImplementacao: possuiFlag(resto, "--preservar-implementacao") })
+                : await comandoVerificar(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache"), preservarImplementacao: possuiFlag(resto, "--preservar-implementacao") });
             break;
         case "inspecionar":
             codigoSaida = await comandoInspecionar(posicionais[0], possuiFlag(resto, "--json"), cwd, resto);

package/dist/verificacaoPythonLocal.d.ts

@@ -0,0 +1,17 @@
+type Arquivo = {
+    caminhoRelativo: string;
+    conteudo: string;
+};
+export declare function erroModoPreservacao(preservar: boolean | undefined, configuracoes: Array<{
+    alvo: string;
+    framework: string;
+}>): string | undefined;
+export declare function prepararImplementacaoPythonLocal(base: string, arquivos: Arquivo[]): Promise<{
+    arquivosParaEscrita: Arquivo[];
+    erro?: string;
+}>;
+export declare function evidenciaPython(preservar: boolean | undefined): {
+    tipoEvidencia: "andaime_demonstrativo" | "implementacao_local_preservada";
+    implementacaoExternaExecutada: boolean;
+};
+export {};

package/dist/verificacaoPythonLocal.js

@@ -0,0 +1,46 @@
+// SEMA-GOVERNED: sema.produto.cli_verificacao
+// Contrato: contratos/sema/cli_verificacao.sema
+// Descrição: preserva Python local explicitamente; testes continuam derivados do contrato, sem cache.
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+export function erroModoPreservacao(preservar, configuracoes) {
+    if (preservar && (configuracoes.length !== 1 || configuracoes[0].alvo !== "python" || configuracoes[0].framework !== "base")) {
+        return "--preservar-implementacao exige --alvo python e framework base.";
+    }
+    return undefined;
+}
+export async function prepararImplementacaoPythonLocal(base, arquivos) {
+    const implementacoes = arquivos.filter(arquivo => arquivo.caminhoRelativo.endsWith(".py") && !path.basename(arquivo.caminhoRelativo).startsWith("test_"));
+    if (implementacoes.length === 0)
+        return { arquivosParaEscrita: [], erro: "Nenhuma implementação Python local prevista pelo contrato." };
+    try {
+        for (const arquivo of implementacoes) {
+            const destino = path.resolve(base, arquivo.caminhoRelativo);
+            const relativo = path.relative(path.resolve(base), destino);
+            if (path.isAbsolute(relativo) || relativo.split(path.sep).includes(".."))
+                throw new Error("escape");
+            let atual = destino;
+            while (true) {
+                const info = await lstat(atual);
+                if (info.isSymbolicLink() || (atual === destino ? !info.isFile() || info.nlink > 1 : !info.isDirectory()))
+                    throw new Error("link ou tipo inválido");
+                const pai = path.dirname(atual);
+                if (pai === atual)
+                    break;
+                atual = pai;
+            }
+        }
+        const preservados = new Set(implementacoes.map(arquivo => arquivo.caminhoRelativo));
+        return { arquivosParaEscrita: arquivos.filter(arquivo => !preservados.has(arquivo.caminhoRelativo)) };
+    }
+    catch {
+        return { arquivosParaEscrita: [], erro: "Implementação Python local ausente ou caminho não seguro. Gere e preencha a implementação antes de usar --preservar-implementacao." };
+    }
+}
+export function evidenciaPython(preservar) {
+    return {
+        tipoEvidencia: preservar ? "implementacao_local_preservada" : "andaime_demonstrativo",
+        implementacaoExternaExecutada: false,
+    };
+}
+//# sourceMappingURL=verificacaoPythonLocal.js.map

package/docs/testing.md

@@ -169,3 +169,21 @@ this scaffold: its tests and guarantees cannot establish production behavior.
 Use the application's real tests and drift evidence for that claim. Generated
 failure cases currently retain the explicit synthetic error context and are
 not evidence that the real implementation produces those errors.
+
+To execute an explicitly filled local Python implementation without overwriting
+it, use the same verification output base that contains the generated module:
+
+```bash
+sema verificar contratos/app.sema --alvo python --saida .tmp/check --preservar-implementacao --json
+```
+
+This opt-in mode supports only Python with the base framework. All expected
+implementation files must already exist as regular files, without symlinks,
+junctions or hardlinks. It preserves those files byte for byte, regenerates the
+contract tests and support artifacts, and always runs the tests without reading
+or writing the verification cache. Missing implementations fail before writes;
+new expectations and incorrect implementation results still fail. The output
+reports `tipoEvidencia: implementacao_local_preservada` and
+`implementacaoExternaExecutada: false`: it proves execution of those local files,
+not automatic execution of a linked `impl`, a remote deployment or production.
+Normal verification retains the demonstration scaffold behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semacode/cli",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "description": "Local-first semantic governance CLI for AI agents, proven with Claude, Codex, zCode (GLM) and Kimi: contracts, drift, impact, docs gates, and code generation.",
   "type": "module",
   "icon": "logo.png",